https://wiki.archlinux.org/api.php?action=feedcontributions&user=B6hgas5&feedformat=atomArchWiki - User contributions [en]2024-03-29T07:40:27ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Solid_state_drive/NVMe&diff=792685Solid state drive/NVMe2023-11-17T16:18:46Z<p>B6hgas5: /* Discards */ delete poor advice about discard. it's unclear that the cited author is any sort of authority, and their cited source is a low-quality howtogeek.com article from 2013</p>
<hr />
<div>[[Category:Storage]]<br />
[[ja:ソリッドステートドライブ/NVMe]]<br />
{{Related articles start}}<br />
{{Related|Solid State Drive}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:NVM Express|NVM Express]] (NVMe) is a specification for accessing [[SSD]]s attached through the PCI Express bus. As a logical device interface, NVM Express has been designed from the ground up, capitalizing on the low latency and parallelism of PCI Express SSDs, and mirroring the parallelism of contemporary CPUs, platforms and applications.<br />
<br />
== Installation ==<br />
<br />
NVMe devices should show up as {{ic|/dev/nvme*}}. See [[Device file#NVMe]] for an explanation on their naming.<br />
<br />
Extra userspace NVMe tools can be found in {{Pkg|nvme-cli}} or {{aur|nvme-cli-git}}.<br />
<br />
See [[Solid State Drives]] for supported filesystems, maximizing performance, minimizing disk reads/writes, etc.<br />
<br />
== Management ==<br />
<br />
{{Note|This section was adapted from [https://nvmexpress.org/open-source-nvme-management-utility-nvme-command-line-interface-nvme-cli/].}}<br />
<br />
List all the NVMe SSDs attached with name, serial number, size, LBA format and serial:<br />
<br />
# nvme list<br />
<br />
List information about a drive and features it supports in a human-friendly way:<br />
<br />
# nvme id-ctrl -H /dev/nvme0<br />
<br />
{{Tip|In order to make sense of the abbreviations used, see reference section "Identify Controller data structure" in the relevant [https://nvmexpress.org/developers/nvme-specification/ NVMe specification], (e.g. bottom of page 172 for the 1.4a specification).}}<br />
<br />
List information about a namespace and features it supports:<br />
<br />
{{Note|Namespaces are the construct in NVMe technology that hold user data. An NVMe controller can have multiple namespaces attached to it. Most NVMe SSDs today just use a single namespace, but multi-tenant applications, virtualization and security have use cases for multiple namespaces.}}<br />
<br />
# nvme id-ns /dev/nvme0n1<br />
<br />
{{Tip|In order to make sense of the abbreviations used, see reference section "Identify Namespace data structure" in the relevant [https://nvmexpress.org/developers/nvme-specification/ NVMe specification] (e.g. page 163 for the 1.4a specification).}}<br />
<br />
Output the NVMe error log page:<br />
<br />
# nvme error-log /dev/nvme0<br />
<br />
{{Tip|Look for output where error count does not equal 0 to find out if there are any errors in the error log.}}<br />
<br />
Delete a namespace:<br />
<br />
{{Warning|This command will delete all data on the specified namespace. Use with caution!}}<br />
<br />
# nvme delete-ns /dev/nvme0n1<br />
<br />
Create a new namespace, e.g creating a smaller size namespace to overprovision an SSD for improved endurance, performance, and latency:<br />
<br />
# nvme create-ns /dev/nvme0<br />
<br />
See {{ic|nvme help}} and {{man|1|nvme}} for a list of all commands along with a terse description.<br />
<br />
=== SMART ===<br />
<br />
Output the NVMe SMART log page for health status, temp, endurance, and more:<br />
<br />
# nvme smart-log /dev/nvme0<br />
<br />
{{Tip|Use the {{ic|-H}} option to output even more information, e.g. {{ic|nvme smart-log -H /dev/nvme0}}.}}<br />
<br />
NVMe support was added to {{Pkg|smartmontools}} [https://www.smartmontools.org/wiki/NVMe_Support#SmartmontoolsNVMesupport1 in version 6.5].<br />
<br />
{{Note|[https://www.smartmontools.org/wiki/NVMe_Support#SmartmontoolsNVMesupport1 smartmontools official wiki] reports this support as experimental.}}<br />
<br />
Currently implemented features (as taken from the wiki):<br />
<br />
* Basic information about controller name, firmware, capacity ({{ic|smartctl -i}})<br />
* Controller and namespace capabilities ({{ic|smartctl -c}})<br />
* SMART overall-health self-assessment test result and warnings ({{ic|smartctl -H}})<br />
* NVMe SMART attributes ({{ic|smartctl -A}})<br />
* NVMe error log ({{ic|smartctl -l error[,NUM]}})<br />
* Ability to fetch any nvme log ({{ic|smartctl -l nvmelog,N,SIZE}})<br />
* The smartd daemon tracks health ({{ic|-H}}), error count ({{ic|-l error}}) and temperature ({{ic|-W DIFF,INFO,CRIT}}) <br />
<br />
See [[S.M.A.R.T.]] and the [https://www.smartmontools.org/wiki/NVMe_Support official wiki entry] for more information, and see [https://www.percona.com/blog/2017/02/09/using-nvme-command-line-tools-to-check-nvme-flash-health/ this article] for contextual information about the output.<br />
<br />
=== Secure erase ===<br />
<br />
See [[Solid state drive/Memory cell clearing#NVMe drive]].<br />
<br />
=== Firmware update ===<br />
<br />
==== Generic ====<br />
<br />
Firmware can be managed using {{Pkg|nvme-cli}}. To display available slots and check whether Slot 1 is read only: <br />
<br />
{{hc|# nvme fw-log /dev/nvme0|<br />
Firmware Log for device:nvme0<br />
afi : 0x11<br />
frs1 : 0x32303132345a3553 (S5Z42102)<br />
frs2 : 0x32303132345a3553 (S5Z42102)<br />
}}<br />
<br />
{{hc|# nvme id-ctrl /dev/nvme0 -H {{!}} grep Firmware|<br />
[9:9] : 0x1 Firmware Activation Notices Supported<br />
[4:4] : 0x1 Firmware Activate Without Reset Supported<br />
[3:1] : 0x2 Number of Firmware Slots<br />
[0:0] : 0 Firmware Slot 1 Read/Write<br />
}}<br />
<br />
Download and commit firmware to specified slot. In the example below, firmware is first committed without activation ({{ic|-a 0}}). Next, an existing image is activated ({{ic|-a 2}}). Refer to the [https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4b-2020.09.21-Ratified.pdf NVMe specification] for details on firmware commit ''action'' values.<br />
<br />
{{hc|# nvme fw-download -f S5Z42_fw_S5Z42105.bin /dev/nvme0|<br />
Firmware download success<br />
}}<br />
<br />
{{hc|# nvme fw-commit -s 2 -a 0 /dev/nvme0|<br />
Success committing firmware action:0 slot:2<br />
}}<br />
<br />
{{hc|# nvme fw-log /dev/nvme0|<br />
Firmware Log for device:nvme0<br />
afi : 0x21<br />
frs1 : 0x32303132345a3553 (S5Z42102)<br />
frs2 : 0x35303132345a3553 (S5Z42105)<br />
}}<br />
<br />
{{hc|# nvme fw-commit -s 2 -a 2 /dev/nvme0|<br />
Success committing firmware action:2 slot:2<br />
}}<br />
<br />
Finally reset the controller to load the new firmware:<br />
<br />
{{Note|If {{ic|Firmware Activate Without Reset}} is marked as supported as in the example above, this step may not be necessary.}}<br />
<br />
# nvme reset /dev/nvme0<br />
<br />
This can also be done manually if needed:<br />
<br />
# echo 1 > /sys/class/nvme/nvme0/reset_controller<br />
<br />
==== Intel/Solidigm ====<br />
<br />
After Intel SSD business was acquired by SK Hynix[https://news.solidigm.com/en-WW/212943-sk-hynix-completes-the-first-phase-of-intel-nand-and-ssd-business-acquisition][https://www.anandtech.com/show/17134/intel-sells-ssd-business-to-sk-hynix-as-new-subsidiary-solidigm], its "Memory and Storage Tool" (Intel MAS) lost support for SSDs and can now only be used to manage Optane devices.[https://www.intel.com/content/www/us/en/download/19520/intel-memory-and-storage-tool-cli-command-line-interface.html]<br />
<br />
Solidigm, the US subsidiary formed from Intel's SSD business acquisition, provides a new utility to manage former Intel SSDs: ''"The Solidigm Storage Tool, also called SST, assists with managing Solidigm SSDs. It provides access to drive information and health, SMART Attributes, Firmware Updates, diagnostic scans, and secure erase."''[https://www.solidigm.com/content/solidigm/us/en/support-page/drivers-downloads/ka-00085.html]<br />
<br />
Install {{AUR|solidigm-sst-storage-tool-cli}}, then check whether your drive has an update available:<br />
<br />
{{hc|# sst show -ssd|<br />
- ABCD012345NS512A -<br />
<br />
Capacity : 512.11 GB (512,110,190,592 bytes)<br />
DevicePath : /dev/nvme0n1<br />
DeviceStatus : Healthy<br />
Firmware : 004C<br />
FirmwareUpdateAvailable : 005C<br />
Index : 0<br />
MaximumLBA : 1000215215<br />
ModelNumber : INTEL SSDPEKNW512G8<br />
ProductFamily : Intel SSD 660p Series<br />
SMARTEnabled : True<br />
SectorDataSize : 512<br />
SerialNumber : ABCD012345NS512A}}<br />
<br />
If so execute the {{ic|load}} command as follows, using the index value given in the previous command:<br />
<br />
{{hc|# sst load -ssd ''index''|<br />
WARNING! You have selected to update the drives firmware! <br />
Proceed with the update? (Y{{!}}N): Y<br />
Updating firmware...<br />
Firmware update successful<br />
}}<br />
<br />
For more information, refer to the user guide provided on the tool's aforementioned official page.<br />
<br />
==== Kingston ====<br />
<br />
Kingston does not provide separate firmware downloads on their website, instead referring users to a Windows only utility. Firmware files appear to use a predictable naming scheme based on the firmware revision:<br />
<br />
<nowiki>https://media.kingston.com/support/downloads/</nowiki>'''S5Z42105.zip'''<br />
<br />
Then proceed with the [[#Generic|generic flashing instructions]].<br />
<br />
==== Samsung ====<br />
Next to "Samsung Magician Software" for Windows users Samsung also provides SSD firmware as bootable ISO images:<br />
<br />
https://semiconductor.samsung.com/consumer-storage/support/tools/<br />
<br />
They can be written onto a bootable CD or USB drive, or you can unpack the image and do everything live:<br />
<br />
$ curl -OL <nowiki>https://samsung.com</nowiki>/.../'''xxx'''.iso<br />
$ bsdtar -xf '''xxx'''.iso initrd<br />
$ bsdtar -xf initrd root<br />
# ./root/fumagician/fumagician<br />
<br />
Instead of using the manufacturer's program you might prefer to use {{Pkg|nvme-cli}} and upload the firmware manually as explained in the [[#Generic|previous section]]:<br />
<br />
{{hc|$ ls -1 root/fumagician/*.enc|<br />
root/fumagician/1B2QJXD7.enc<br />
root/fumagician/DSRD.enc<br />
}}<br />
<br />
The first file is the firmware.<br />
<br />
==== Western Digital ====<br />
<br />
Western Digital only supports updating via their Windows based Dashboard software. However, the firmware can be downloaded directly if you know where to look.[https://community.frame.work/t/western-digital-drive-update-guide-without-windows-wd-dashboard/20616]<br />
<br />
First, navigate to the [https://wddashboarddownloads.wdc.com/wdDashboard/config/devices/lista_devices.xml list of all drives] and find your drive ({{ic|model{{=}}''model_number''}}).<br />
<br />
Under your particular drive model there will be one or more {{ic|<url>}} entries. If there are multiple URLs then you may need to try each one using the directions below and check the {{ic|<dependency>}} tag for your current firmware version.<br />
<br />
Now, download the drive-specific XML file:<br />
<br />
$ curl <nowiki>https://wddashboarddownloads.wdc.com/</nowiki>''url_entry''<br />
<br />
Inside this drive-specific XML file should be a {{ic|<fwfile>}} tag with a {{ic|''xxxx''.fluf}} filename. This is the name of the file you want; you can download it by replacing {{ic|device_properties.xml}} from the previous URL with this filename.<br />
<br />
A full URL example for a SN820X drive:<br />
<br />
$ curl --remote-name <nowiki>https://wddashboarddownloads.wdc.com/</nowiki>wdDashboard/firmware/WD_BLACK_SN850X_2000GB/620331WD/620331WD.fluf<br />
<br />
Once you have the ''.fluf'' file, updating can be performed using the [[#Generic|generic flashing instructions]]. Be aware that this is not officially supported by Western Digital, may not work correctly, and could possibly damage your device. Be extra careful that you are updating with the correct drive and version of firmware.<br />
<br />
== Performance ==<br />
<br />
=== Sector size ===<br />
<br />
See [[Advanced Format#NVMe solid state drives]].<br />
<br />
=== Discards ===<br />
<br />
Discards are disabled by default on typical setups that use [[ext4]] and [[LVM]], but other [[file systems]] might need discards to be disabled explicitly.<br />
<br />
=== Airflow ===<br />
<br />
NVMe SSDs are known to be affected by high operating temperatures and will throttle performance over certain thresholds.[https://www.legitreviews.com/samsung-ssd-950-pro-512gb-nvme-pcie-ssd-review_174096/3]<br />
<br />
=== Testing ===<br />
<br />
Raw device performance tests can be run with {{pkg|hdparm}}:<br />
<br />
# hdparm -Tt --direct /dev/nvme0n1<br />
<br />
== Power Saving (APST) ==<br />
<br />
To check NVMe power states, install {{Pkg|nvme-cli}} or {{AUR|nvme-cli-git}}, and run {{ic|nvme get-feature /dev/nvme[0-9] -f 0x0c -H}}:<br />
<br />
{{hc|# nvme get-feature /dev/nvme0 -f 0x0c -H|<br />
get-feature:0xc (Autonomous Power State Transition), Current value:0x000001<br />
Autonomous Power State Transition Enable (APSTE): Enabled<br />
Auto PST Entries .................<br />
<br />
...<br />
}}<br />
<br />
When APST is enabled the output should contain "Autonomous Power State Transition Enable (APSTE): Enabled" and there should be non-zero entries in the table below indicating the idle time before transitioning into each of the available states.<br />
<br />
If APST is enabled but no non-zero states appear in the table, the latencies might be too high for any states to be enabled by default. The output of {{ic|nvme id-ctrl /dev/nvme[0-9]}} (as the root user) should show the available non-operational power states of the NVME controller. If the total latency of any state (enlat + xlat) is greater than 25000 (25ms) you must pass a value at least that high as parameter {{ic|default_ps_max_latency_us}} for the {{ic|nvme_core}} [[kernel module]]. This should enable APST and make the table in {{ic|nvme get-feature}} (as the root user) show the entries.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Controller failure due to broken APST support ===<br />
<br />
Some NVMe devices may exhibit issues related to power saving (APST). This is a known issue for Kingston A2000 [https://bbs.archlinux.org/viewtopic.php?pid=1926994#p1926994] as of firmware ''S5Z42105'' and has previously been reported on Samsung NVMe drives (Linux v4.10) [https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1678184][https://askubuntu.com/questions/905710/ext4-fs-error-after-ubuntu-17-04-upgrade/906105#906105]<br />
<br />
A failure renders the device unusable until system reset, with kernel logs similar to:<br />
<br />
nvme nvme0: I/O 566 QID 7 timeout, aborting<br />
nvme nvme0: I/O 989 QID 1 timeout, aborting<br />
nvme nvme0: I/O 990 QID 1 timeout, aborting<br />
nvme nvme0: I/O 840 QID 6 timeout, reset controller<br />
nvme nvme0: I/O 24 QID 0 timeout, reset controller<br />
nvme nvme0: Device not ready; aborting reset, CSTS=0x1<br />
...<br />
nvme nvme0: Device not ready; aborting reset, CSTS=0x1<br />
nvme nvme0: Device not ready; aborting reset, CSTS=0x1<br />
nvme nvme0: failed to set APST feature (-19)<br />
<br />
As a workaround, add the [[kernel parameter]] {{ic|1=nvme_core.default_ps_max_latency_us=0}} to completely disable APST, or set a custom threshold to disable specific states.<br />
<br />
{{Out of date|1=This kernel parameter may no longer be necessary with recent versions of Linux Kernel. (e.g., v4.14.221, v4.19.175, v5.4.97, v5.10.15, v5.11-rc7, and later). [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=538e4a8c571efdf131834431e0c14808bcfb1004] }}<br />
<br />
Since March 2021 a firmware update [https://www.kingston.com/unitedkingdom/en/support/technical/ksm-firmware-update 9] from Kingston is available. As Kingston only supports Windows, downloads for Linux can be found via [https://www.heise.de/downloads/18/3/0/9/6/7/4/4/A2000_-_S5Z42109.zip heise.de] or [https://github.com/vulgo/kingston-a2000-firmware-bin-linux github]. It is expected that, as long as the kernel workaround is in place, the firmware update will not do much as the deepest powersaving states are not reached anyway.<br />
<br />
{{hc|# smartctl -c /dev/nvme0|<br />
Supported Power States<br />
St Op Max Active Idle RL RT WL WT Ent_Lat Ex_Lat<br />
0 + 9.00W - - 0 0 0 0 0 0<br />
1 + 4.60W - - 1 1 1 1 0 0<br />
2 + 3.80W - - 2 2 2 2 0 0<br />
3 - 0.0450W - - 3 3 3 3 2000 2000<br />
4 - 0.0040W - - 4 4 4 4 15000 15000<br />
}}<br />
<br />
The value passed is the maximum exit latency (''Ex_Lat''). For example, to disable PS4 set {{ic|1=nvme_core.default_ps_max_latency_us=2000}}.<br />
<br />
=== Controller failure due to broken suspend support ===<br />
<br />
Some users (for example, see [[Laptop/HP]]) have reported suspend failures with certain NVMe drives. As above, the failure renders the device inoperable until system reset, with kernel messages<br />
<br />
nvme nvme0: Device not ready; aborting reset, CSTS=0x3<br />
nvme nvme0: Removing after probe failure status: -19<br />
<br />
As a workaround, add the [[kernel parameter]] {{ic|1=iommu=soft}} to use a software replacement for the hardware IOMMU. (For further details, see [https://docs.kernel.org/arch/x86/x86_64/boot-options.html this documentation].) This has the potential to cause some slight processing overhead.<br />
<br />
{{Accuracy|The following solution does not explain why it works, nor provide sources.}}<br />
<br />
Also you can try kernel parameter {{ic|1=amd_iommu=off}} or better {{ic|1=amd_iommu=fullflush}} on HP laptops with AMD CPU and KIOXIA KBG40ZN* nvme's, after you get I/O error with messages like this:<br />
Failed to rotate /var/log/journal/*/system.journal: Read-only file system<br />
nvme nvme0: Device not ready; aborting reset, CSTS=0x3<br />
BTRFS error (device nvme0n1): bdev /dev/nvme0n1p* errs: wr 2, rd 0, flush 0, corrupt 0, gen 0<br />
<br />
== See also ==<br />
<br />
* [https://nvmexpress.org/open-source-nvme-ssd-management-utility-nvme-command-line-interface-nvme-cli/ Open Source NVMe™ Management Utility – NVMe Command Line Interface (NVMe-CLI)]<br />
* [https://metebalci.com/blog/a-quick-tour-of-nvm-express-nvme/ A Quick Tour of NVM Express (NVMe)]<br />
* [https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4b-2020.09.21-Ratified.pdf NVM Express Base Specification, Revision 1.4b]</div>B6hgas5https://wiki.archlinux.org/index.php?title=Systemd-resolved&diff=758163Systemd-resolved2022-11-27T18:29:14Z<p>B6hgas5: /* DNS */ add example nsswitch excerpt from man page</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Domain Name System]]<br />
[[de:Systemd/systemd-resolved]]<br />
[[es:Systemd-resolved]]<br />
[[ja:Systemd-resolved]]<br />
[[ru:Systemd-resolved]]<br />
{{Related articles start}}<br />
{{Related|systemd-networkd}}<br />
{{Related|Domain name resolution}}<br />
{{Related|Avahi}}<br />
{{Related articles end}}<br />
''systemd-resolved'' is a [[systemd]] service that provides network name resolution to local applications via a [[D-Bus]] interface, the {{ic|resolve}} [[Name Service Switch|NSS]] service ({{man|8|nss-resolve}}), and a local DNS stub listener on {{ic|127.0.0.53}}. See {{man|8|systemd-resolved}} for the usage.<br />
<br />
== Installation ==<br />
<br />
''systemd-resolved'' is a part of the {{Pkg|systemd}} package that is installed by default.<br />
<br />
== Configuration ==<br />
<br />
''systemd-resolved'' provides resolver services for [[Wikipedia:Domain Name System|Domain Name System (DNS)]] (including [[Wikipedia:Domain Name System Security Extensions|DNSSEC]] and [[Wikipedia:DNS over TLS|DNS over TLS]]), [[Wikipedia:Multicast DNS|Multicast DNS (mDNS)]] and [[Wikipedia:Link-Local Multicast Name Resolution|Link-Local Multicast Name Resolution (LLMNR)]].<br />
<br />
The resolver can be configured by editing {{ic|/etc/systemd/resolved.conf}} and/or drop-in ''.conf'' files in {{ic|/etc/systemd/resolved.conf.d/}}. See {{man|5|resolved.conf}}.<br />
<br />
To use ''systemd-resolved'' [[start]] and [[enable]] {{ic|systemd-resolved.service}}.<br />
<br />
{{Tip|To understand the context around the choices and switches, one can turn on detailed debug information for ''systemd-resolved'' as described in [[systemd#Diagnosing a service]].}}<br />
<br />
=== DNS ===<br />
<br />
Software that relies on glibc's {{man|3|getaddrinfo}} (or similar) will work out of the box, since, by default, {{ic|/etc/nsswitch.conf}} is configured to use {{man|8|nss-resolve}} if it is available:<br />
<br />
{{hc|/etc/nsswitch.conf|2=<br />
…<br />
hosts: mymachines '''resolve [!UNAVAIL=return]''' files myhostname dns<br />
…<br />
}}<br />
<br />
To provide [[domain name resolution]] for software that reads {{ic|/etc/resolv.conf}} directly, such as [[web browsers]] and [[GnuPG]], ''systemd-resolved'' has four different modes for handling the file—stub, static, uplink and foreign. They are described in {{man|8|systemd-resolved|/ETC/RESOLV.CONF}}. We will focus here only on the recommended mode, i.e. the stub mode which uses {{ic|/run/systemd/resolve/stub-resolv.conf}}.<br />
<br />
{{ic|/run/systemd/resolve/stub-resolv.conf}} contains the local stub {{ic|127.0.0.53}} as the only DNS server and a list of search domains. This is the recommended mode of operation that propagates the ''systemd-resolved'' managed configuration to all clients. To use it, replace {{ic|/etc/resolv.conf}} with a symbolic link to it:<br />
<br />
# ln -rsf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf<br />
<br />
{{Note|<br />
* Failure to properly configure {{ic|/etc/resolv.conf}} will result in broken DNS resolution.<br />
* Creating the {{ic|/etc/resolv.conf}} symlink will not be possible while inside ''arch-chroot'', since the file is bind-mounted from the outside system. Instead, create the symlink from outside the chroot. E.g. {{bc|# ln -sf /run/systemd/resolve/stub-resolv.conf ''/mnt''/etc/resolv.conf}}<br />
}}<br />
<br />
==== Setting DNS servers ====<br />
<br />
{{Tip|To check the DNS currently in use by ''systemd-resolved'', run {{ic|resolvectl status}}.}}<br />
<br />
===== Automatically =====<br />
<br />
''systemd-resolved'' will work out of the box with a [[network manager]] using {{ic|/etc/resolv.conf}}. No particular configuration is required since ''systemd-resolved'' will be detected by following the {{ic|/etc/resolv.conf}} symlink. This is going to be the case with [[systemd-networkd]], [[NetworkManager]], and [[iwd]].<br />
<br />
However, if the [[DHCP]] and [[VPN]] clients use the [[Wikipedia:resolvconf|resolvconf]] program to set name servers and search domains (see [[openresolv#Users]] for a list of software that use ''resolvconf''), the additional package {{Pkg|systemd-resolvconf}} is needed to provide the {{ic|/usr/bin/resolvconf}} symlink.<br />
<br />
{{Note|<br />
* ''systemd-resolved'' has a limited ''resolvconf'' interface and may not work with all the clients, see {{man|1|resolvectl|COMPATIBILITY WITH RESOLVCONF(8)}} for more information.<br />
* {{Pkg|systemd-resolvconf}} only works when {{ic|systemd-resolved.service}} is running. If you are not using ''systemd-resolved'', make sure the {{Pkg|systemd-resolvconf}} package is [[uninstall]]ed, otherwise it will cause issues with networking software that expect a working {{ic|/usr/bin/resolvconf}} binary.<br />
}}<br />
<br />
===== Manually =====<br />
<br />
In stub and static modes, custom DNS server(s) can be set in the {{man|5|resolved.conf}} file:<br />
<br />
{{hc|/etc/systemd/resolved.conf.d/dns_servers.conf|2=<br />
[Resolve]<br />
DNS=192.168.35.1 fd7b:d0bd:7a6e::1<br />
Domains=~.<br />
}}<br />
<br />
{{Note|<br />
* Without the {{ic|1=Domains=~.}} option in {{man|5|resolved.conf}}, ''systemd-resolved'' might use the per-link DNS servers, if any of them set {{ic|1=Domains=~.}} in the per-link configuration.<br />
* This option will not affect queries of domain names that match the more specific search domains specified in per-link configuration, they will still be resolved using their respective per-link DNS servers.<br />
For more information on per-link configuration see [[systemd-networkd#network files]].<br />
}}<br />
<br />
===== Fallback =====<br />
<br />
If ''systemd-resolved'' does not receive DNS server addresses from the [[network manager]] and no DNS servers are configured [[#Manually|manually]] then ''systemd-resolved'' falls back to the fallback DNS addresses to ensure that DNS resolution always works.<br />
<br />
{{Note|1=The fallback DNS are in this order: [[Alternative DNS services#Cloudflare|Cloudflare]], [[Alternative DNS services#Quad9|Quad9]] and [[Alternative DNS services#Google|Google]]; see the [https://github.com/archlinux/svntogit-packages/blob/packages/systemd/trunk/PKGBUILD#L100-L111 systemd PKGBUILD] where the servers are defined.}}<br />
<br />
The addresses can be changed by setting {{ic|FallbackDNS}} in {{man|5|resolved.conf}}. E.g.:<br />
<br />
{{hc|/etc/systemd/resolved.conf.d/fallback_dns.conf|2=<br />
[Resolve]<br />
FallbackDNS=127.0.0.1 ::1<br />
}}<br />
<br />
To disable the fallback DNS functionality set the {{ic|FallbackDNS}} option without specifying any addresses:<br />
<br />
{{hc|/etc/systemd/resolved.conf.d/fallback_dns.conf|2=<br />
[Resolve]<br />
FallbackDNS=<br />
}}<br />
<br />
==== DNSSEC ====<br />
<br />
[[DNSSEC]] validation can be enabled by changing {{ic|DNSSEC}} setting in {{man|5|resolved.conf}}.<br />
<br />
* Set {{ic|1=DNSSEC=allow-downgrade}} to validate DNSSEC only if the upstream DNS server supports it.<br />
* Set {{ic|1=DNSSEC=true}} to always validate DNSSEC, thus breaking DNS resolution with name servers that do not support it. For example:<br />
<br />
{{hc|/etc/systemd/resolved.conf.d/dnssec.conf|2=<br />
[Resolve]<br />
DNSSEC=true<br />
}}<br />
<br />
{{Note|<br />
* If your DNS server does not support DNSSEC and you experience problems with the default allow-downgrade mode (e.g. [https://github.com/systemd/systemd/issues/10579 systemd issue 10579]), you can explicitly disable systemd-resolved's DNSSEC support by setting {{ic|1=DNSSEC=false}}.<br />
* systemd-resolved may disable DNSSEC after a few unsuccessful validations. If the {{ic|DNSSEC}} option is set to {{ic|true}}, then DNS resolution will stop working entirely. See [https://github.com/systemd/systemd/issues/9867 systemd issue 9867].<br />
}}<br />
<br />
Test DNSSEC validation by querying a domain with a invalid signature:<br />
<br />
{{hc|$ resolvectl query sigfail.verteiltesysteme.net|<br />
sigfail.verteiltesysteme.net: resolve call failed: DNSSEC validation failed: invalid<br />
}}<br />
<br />
Now test a domain with valid signature:<br />
<br />
{{hc|$ resolvectl query sigok.verteiltesysteme.net|<br />
sigok.verteiltesysteme.net: 134.91.78.139<br />
<br />
-- Information acquired via protocol DNS in 266.3ms.<br />
-- Data is authenticated: yes<br />
}}<br />
<br />
==== DNS over TLS ====<br />
<br />
DNS over TLS is disabled by default. To enable it change the {{ic|DNSOverTLS}} setting in the {{ic|[Resolve]}} section in {{man|5|resolved.conf}}. To enable validation of your DNS provider's server certificate, include their hostname in the {{ic|DNS}} setting in the format {{ic|''ip_address''#''hostname''}}. For example:<br />
<br />
{{hc|/etc/systemd/resolved.conf.d/dns_over_tls.conf|2=<br />
[Resolve]<br />
DNS=9.9.9.9#dns.quad9.net<br />
DNSOverTLS=yes<br />
}}<br />
<br />
{{Note|The DNS server used must support DNS over TLS. Otherwise all DNS requests will fail.}}<br />
<br />
{{pkg|ngrep}} can be used to test if DNS over TLS is working since DNS over TLS always uses port 853 and never port 53. The command {{ic|ngrep port 53}} should produce no output when a hostname is resolved with DNS over TLS and {{ic|ngrep port 853}} should produce encrypted output.<br />
<br />
[[Wireshark]] can be used for more detailed packet inspection of DNS over TLS queries.<br />
<br />
=== mDNS ===<br />
<br />
''systemd-resolved'' is capable of working as a [[Wikipedia:Multicast DNS|multicast DNS]] resolver and responder.<br />
<br />
The resolver provides [[hostname]] resolution using a "''hostname''.local" naming scheme.<br />
<br />
mDNS will only be activated for a connection if both systemd-resolved's mDNS support has been enabled, and if the configuration for the currently active [[network manager]] enables mDNS for the connection.<br />
<br />
''systemd-resolved'''s mDNS support can be enabled by its {{ic|MulticastDNS}} setting (see {{man|5|resolved.conf|OPTIONS}}).<br />
<br />
Enabling per-connection mDNS support depends on the [[network manager]]:<br />
<br />
* For [[systemd-networkd]], set the {{ic|MulticastDNS}} setting in the {{ic|[Network]}} section of a per-connection settings file. You may also have to set {{ic|1=Multicast=yes}} in the {{ic|[Link]}} section. See {{man|5|systemd.network}}.<br />
* Otherwise, for [[NetworkManager]], set {{ic|mdns}} in the {{ic|[connection]}} section of the connection's settings file. Running {{ic|nmcli connection modify ''interface_name'' connection.mdns ''{yes{{!}}no{{!}}resolve}''}} will do that for you. See {{man|5|nm-settings}}.<br />
<br />
{{Note|<br />
* If [[Avahi]] has been installed, consider [[disabling]] or [[mask]]ing {{ic|avahi-daemon.service}} and {{ic|avahi-daemon.socket}} to prevent conflicts with ''systemd-resolved''.<br />
* If you plan to use mDNS and a [[firewall]], make sure to open UDP port {{ic|5353}}.<br />
}}<br />
<br />
{{Tip|1=The default for all [[NetworkManager]] connections can be set by creating a configuration file in {{ic|/etc/NetworkManager/conf.d/}} and setting {{ic|1=connection.mdns=2}} in the {{ic|[connection]}} section. See {{man|5|NetworkManager.conf|CONNECTION SECTION}} and [https://bbs.archlinux.org/viewtopic.php?pid=1965078#p1965078].}}<br />
<br />
=== LLMNR ===<br />
<br />
[[Wikipedia:Link-Local Multicast Name Resolution|Link-Local Multicast Name Resolution]] is a [[hostname]] resolution protocol created by Microsoft.<br />
<br />
LLMNR will only be activated for the connection if both the systemd-resolved's global setting ({{ic|LLMNR}} in {{man|5|resolved.conf|OPTIONS}}) and the [[Network manager|network manager's]] per-connection setting is enabled. By default ''systemd-resolved'' enables LLMNR responder; [[systemd-networkd]] and [[NetworkManager]][https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/301] enable it for connections.<br />
<br />
* For [[systemd-networkd]] the setting is {{ic|LLMNR}} in the {{ic|[Network]}} section. See {{man|5|systemd.network|[NETWORK] SECTION OPTIONS}}.<br />
* For [[NetworkManager]] the setting is {{ic|llmnr}} in the {{ic|[connection]}} section. See {{man|5|nm-settings|connection setting}}.<br />
<br />
{{Tip|The default for all [[NetworkManager]] connections can be set by creating a configuration file in {{ic|/etc/NetworkManager/conf.d/}} and setting {{ic|connection.llmnr}} in the {{ic|[connection]}} section. See {{man|5|NetworkManager.conf|CONNECTION SECTION}}.}}<br />
<br />
If you plan to use LLMNR and use a [[firewall]], make sure to open UDP and TCP ports {{ic|5355}}.<br />
<br />
== Lookup ==<br />
<br />
To query DNS records, mDNS or LLMNR hosts you can use the ''resolvectl'' utility.<br />
<br />
For example, to query a DNS record:<br />
<br />
{{hc|$ resolvectl query archlinux.org|<br />
archlinux.org: 2a01:4f8:172:1d86::1<br />
138.201.81.199<br />
<br />
-- Information acquired via protocol DNS in 48.4ms.<br />
-- Data is authenticated: no<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== systemd-resolved not searching the local domain ===<br />
<br />
''systemd-resolved'' may not search the local domain when given just the hostname, even when {{ic|1=UseDomains=yes}} or {{ic|1=Domains=[domain-list]}} is present in the appropriate [[systemd-networkd]]'s ''.network'' file, and that file produces the expected {{ic|search [domain-list]}} in {{ic|resolv.conf}}. You can run {{ic|networkctl status}} or {{ic|resolvectl status}} to check if the search domains are actually being picked up.<br />
<br />
Possible workarounds:<br />
<br />
* Disable [[#LLMNR|LLMNR]] to let ''systemd-resolved'' immediately continue with appending the DNS suffixes<br />
* Trim {{ic|/etc/nsswitch.conf}}'s {{ic|hosts}} database (e.g., by removing {{ic|1=[!UNAVAIL=return]}} option after {{ic|resolve}} service)<br />
* Switch to using fully-qualified domain names<br />
* Use {{ic|/etc/hosts}} to resolve hostnames<br />
* Fall back to using glibc's {{ic|dns}} instead of using systemd's {{ic|resolve}}<br />
<br />
=== systemd-resolved does not resolve hostnames without suffix ===<br />
<br />
To make systemd-resolved resolve hostnames that are not fully qualified domain names, add {{ic|1=ResolveUnicastSingleLabel=yes}} to {{ic|/etc/systemd/resolved.conf}}.<br />
<br />
{{Warning|This will forward single-label names to global DNS servers which may not be under your control. This behaviour is not standard-conformant and may create a privacy and security risk. See {{man|5|resolved.conf}} for details.}}<br />
<br />
This only seems to work with LLMNR disabled ({{ic|1=LLMNR=no}}).<br />
<br />
If you are using [[systemd-networkd]], you might want the domain supplied by the DHCP server or IPv6 Router Advertisement to be used as a search domain. This is disabled by default, to enable it add to the interface's ''.network'' file:<br />
<br />
{{bc|1=<br />
[DHCPv4]<br />
UseDomains=true<br />
<br />
[IPv6AcceptRA]<br />
UseDomains=yes<br />
}}<br />
<br />
You can check what systemd-resolved has for each interface with:<br />
<br />
$ resolvectl domain<br />
<br />
== See also ==<br />
<br />
* [https://moss.sh/name-resolution-issue-systemd-resolved A name resolution issue with systemd-resolved we found in the wild By Francisco Ros]<br />
* See {{man|1|resolvectl|EXAMPLES}} for more examples.</div>B6hgas5https://wiki.archlinux.org/index.php?title=Steam/Game-specific_troubleshooting&diff=701193Steam/Game-specific troubleshooting2021-11-07T13:41:45Z<p>B6hgas5: /* Don't Starve Together */ explain crash on startup</p>
<hr />
<div>[[Category:Gaming]]<br />
[[ja:Steam/ゲーム別のトラブルシューティング]]<br />
== Introduction ==<br />
<br />
See [[Steam/Troubleshooting]] first.<br />
<br />
This page assumes familiarity with the [[Steam#Directory structure]], [[Steam#Launch options]], [[environment variables]], the [[Steam runtime]] and [[Steam/Troubleshooting#Debugging shared libraries|shared libraries]]. The {{ic|''GAME''}} pseudo-variable is used to refer to a game's directory. When the text reads "''run the game with {{ic|1=FOO=bar}}''" it is implied that you either update your launch options or run the game from the command-line with the environment variable.<br />
<br />
== Contributing ==<br />
<br />
* Use "game directory" or the {{ic|''GAME''}} pseudo-variable to refer to a game's directory.<br />
* Link bug reports and sources of workarounds.<br />
<br />
== Other sources ==<br />
<br />
The following links offer even more fixes and tweaks for various games which would otherwise exceed this article's purpose:<br />
<br />
* [https://pcgamingwiki.com/wiki/Home PC Gaming Wiki]<br />
<br />
For games running with Proton, you can check the ProtonDB which lists a lot of useful user reports for specific games. You can filter searched reports by Linux distribution and by hardware. Users also describe if they had to apply tweaks.<br />
<br />
* [https://www.protondb.com/ ProtonDB]<br />
<br />
== Common steps ==<br />
<br />
=== OpenSSL 1.0 setup ===<br />
<br />
Some Steam games are built against OpenSSL 1.0. ({{bug|53618}})<br />
<br />
Install {{Pkg|lib32-openssl-1.0}} and run the game with {{ic|1=LD_LIBRARY_PATH=/usr/lib/openssl-1.0}}.<br />
<br />
=== Adobe Air setup ===<br />
<br />
The package {{AUR|adobe-air-sdk}}{{Broken package link|package not found}} installs Adobe Air not in the place where the game expects it to be, fix this by creating the following symlink:<br />
<br />
# ln -s "/opt/adobe-air-sdk/runtimes/air/linux/Adobe AIR" "/opt/Adobe AIR"<br />
<br />
Adobe AIR requires you to accept its EULA by creating the file {{ic|~/.appdata/Adobe/AIR/eulaAccepted}} containing {{ic|2}}.<br />
<br />
=== Steam Link ===<br />
<br />
Currently Steam Link does not work with Wayland. You will only see a blank screen or even flickering when connecting to a Steam host running on Wayland. So you have to disable Wayland in /etc/gdm/custom.conf:<br />
<br />
WaylandEnable=false<br />
<br />
And reboot before trying again.<br />
<br />
=== Squares or invisible symbols, special characters and cyrillic letters in Source-based games ===<br />
<br />
Any special character may produce a square or an empty space mark in the game, main menu and game console. In practice, any characters other than latin ones are not working. The problem is that {{ic|Bitstream Vera Sans}} is configured as the system primary default font for latin sans-serif fonts.<br />
<br />
First, make sure that per-user font customization files are enabled, i.e. the following file exist:<br />
<br />
/etc/fonts/conf.d/50-user.conf<br />
<br />
Next, create {{ic|fonts.conf}} file in your fontconfig directory with the following content or if the file already exist, append only the alias section to the file:<br />
<br />
{{hc|~/.config/fontconfig/fonts.conf|2=<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>sans-serif</family><br />
<prefer><br />
<family>DejaVu Sans</family><br />
<family>Verdana</family><br />
<family>Arial</family><br />
<family>Albany AMT</family><br />
<family>Luxi Sans</family><br />
<family>Nimbus Sans L</family><br />
<family>Nimbus Sans</family><br />
<family>Helvetica</family><br />
<family>Lucida Sans Unicode</family><br />
<family>BPG Glaho International</family> <!-- lat,cyr,arab,geor --><br />
<family>Tahoma</family> <!-- lat,cyr,greek,heb,arab,thai --><br />
</prefer><br />
</alias><br />
</fontconfig><br />
}}<br />
<br />
== Games ==<br />
<br />
=== 7 Days To Die ===<br />
<br />
If the game crashes on start, add the following to Steam launch options:<br />
<br />
LD_PRELOAD="libpthread.so.0 libGL.so.1" __GL_THREADED_OPTIMIZATIONS=1 %command% -force-glcore<br />
<br />
If the game does not recognize your screen's resolution, launch the game with '''Game Launcher''' and check the '''Unity screen selector''' option to correct the resolution. This will give you a GUI in which you can select the correct screen when the game is started.<br />
<br />
{{Note|The game tends to crash or disfunction in windowed mode. It may be advisable to run it in full screen mode.}}<br />
<br />
If that does not help try running the game in '''32-bit''' mode by checking the respective option in the Game-engine in the launcher options.<br />
<br />
It will help the game performance if the '''GLCore''' option is checked in launcher options.<br />
<br />
{{Note|The game does not accept {{ic|.dll}} mods if installing mods. Always check if the mod is of {{ic|.dll}} type}}<br />
<br />
=== Alien Isolation ===<br />
<br />
==== Missing libpcre.so.3 and libidn.so.11 ====<br />
<br />
$ ln -s /usr/lib/libpcre.so '''GAME''/lib/x86_64/libpcre.so.3'<br />
$ ln -s /usr/lib/libidn.so '''GAME''/lib/x86_64/libidn.so.11'<br />
<br />
Append {{ic|./lib/x86_64}} to your {{ic|LD_LIBRARY_PATH}}.[https://steamcommunity.com/app/214490/discussions/0/154644705028020291/]<br />
<br />
=== Amnesia: The Dark Descent ===<br />
<br />
Dependencies:<br />
[https://steamcommunity.com/app/221410/discussions/0/864957183198111387/]<br />
<br />
* {{AUR|lib32-freealut}}<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libxmu}}<br />
* {{pkg|lib32-sdl_ttf}}<br />
<br />
==== Gamepad not working ====<br />
<br />
The version of libSDL2 shipped with the game seems to be out-of-date and may not support your gamepad yet. Simply remove or rename {{ic|<install_dir>/game/lib64/libSDL2-2.0.so.0}}, the linker will fall back to using the up-to-date version from /usr/lib.<br />
<br />
=== And Yet It Moves ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|lib32-libjpeg6-turbo}}<br />
* {{Pkg|lib32-libpng12}}<br />
* {{Pkg|lib32-libtheora}}<br />
* {{Pkg|lib32-libtiff4}}<br />
<br />
==== Game does not start ====<br />
<br />
When the game refuses to launch and prints one of the following error messages:<br />
<br />
readlink: extra operand ‘Yet’<br>Try 'readlink --help' for more information.<br />
<br />
This script must be run as a user with write priviledges to game directory<br />
<br />
Open {{ic|''GAME''/AndYetItMovesSteam.sh}} and surround {{ic|${BASH_SOURCE[0]} }} in the following line with double quotes.<br />
<br />
ayim_dir="$(dirname "$(readlink -f ${BASH_SOURCE[0]})")"<br />
<br />
=== Anodyne ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|adobe-air-sdk}}{{Broken package link|package not found}}, follow [[#Adobe Air setup]]<br />
* {{pkg|xterm}} (probably not required)<br />
<br />
==== Play with a controller: joy2key configuration ====<br />
<br />
Configuration example to play Anodyne with an XBox 360 Wireless Controller<br />
<br />
COMMON<br />
-dev /dev/input/js0<br />
-X<br />
-thresh -18000 18000 -18000 18000 -18000 18000 -18000 18000 -18000 18000 -18000 18000 -18000 18000 -18000 18000<br />
-axis Left Right Up Down blank blank blank blank blank blank blank blank Left Right Up Down<br />
-buttons c x Return<br />
<br />
Save this to {{ic|~/.joy2keyrc}} and start joy2key after you start Anodyne<br />
<br />
joy2key -rcfile ~/.joy2keyrc<br />
<br />
=== Anomaly Warzone Earth ===<br />
<br />
==== Leave fullsrceen ====<br />
<br />
There are no ingame settings for this, but fullscreen can be toggled with Alt-Enter<br />
<br />
==== Infinite loading ====<br />
<br />
Create file {{ic|loadfix.c}} next to the game executable: [https://steamcommunity.com/app/282070/discussions/0/610573751159186268/?ctp=4#c530647080133257413 src]<br />
<br />
#define _GNU_SOURCE <br />
#include <dlfcn.h> <br />
#include <semaphore.h> <br />
#include <stdio.h> <br />
#include <time.h> <br />
#include <unistd.h> <br />
static int (*_realSemTimedWait)(sem_t *, const struct timespec *) = NULL; <br />
<br />
int sem_timedwait(sem_t *sem, const struct timespec *abs_timeout)<br />
{ <br />
if (abs_timeout->tv_nsec >= 1000000000)<br />
{ <br />
//fprintf(stderr, "to: %lu:%lu\n", abs_timeout->tv_sec, abs_timeout->tv_nsec); <br />
((struct timespec *)abs_timeout)->tv_nsec -= 1000000000; <br />
((struct timespec *)abs_timeout)->tv_sec++; <br />
} <br />
return _realSemTimedWait(sem, abs_timeout); <br />
} <br />
<br />
__attribute__((constructor)) void init(void) <br />
{<br />
_realSemTimedWait = dlsym(RTLD_NEXT, "sem_timedwait");<br />
}<br />
<br />
Compile with {{ic|gcc -m32 -o loadfix.so loadfix.c -ldl -shared -fPIC -Wall -Wextra}}<br />
<br />
Launch with {{ic|1=LD_PRELOAD=$LD_PRELOAD:./loadfix.so %command%}}<br />
<br />
==== Gamepad not working ====<br />
<br />
You have to enable keyboard control and map gamepad to keys.<br />
<br />
Config for Steam: {{ic|steam://controllerconfig/91200/1498735506}}<br />
<br />
=== Aquaria ===<br />
<br />
==== Mouse pointer gets stuck in one direction ====<br />
<br />
If the mouse pointer gets stuck in one direction, make sure {{ic|''GAME''/usersettings.xml}} contains {{ic|1=<JoystickEnabled on="0" />}}.<br />
<br />
If that does not fix the issue, try unplugging any joysticks or joystick adapter devices you have plugged in.<br />
<br />
=== ARK: Survival Evolved ===<br />
<br />
==== Game does not start, displays text window with unreadable text ====<br />
<br />
Run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=4.0 MESA_GLSL_VERSION_OVERRIDE=400}}.<br />
<br />
==== Gray water ====<br />
<br />
Download the TheCenter map and copy {{ic|Water_DepthBlur_MIC.uasset}} from that map into TheIsland as described [https://www.gamingonlinux.com/articles/heres-a-way-to-fix-the-broken-water-in-ark-survival-evolved-on-linux.10530 here].<br />
<br />
Ragnarok uses TheIsland's texture, so the same procedure fixes the issue on Ragnarok as well.<br />
<br />
==== Segmentation fault on startup ====<br />
<br />
Caused by the games packaged libopenal. Use system libopenal to solve the segfault by running the game with with {{ic|1=LD_PRELOAD=/usr/lib/libopenal.so.1}}<br />
<br />
==== Crash on joining a game ====<br />
<br />
Set steam to 'offline mode' and try again<br />
<br />
=== Audiosurf 2 ===<br />
<br />
==== error. unable to load song <filename> ,came back with zero duration ====<br />
<br />
If you get this in your log, install {{pkg|pulseaudio-alsa}}.<br />
<br />
=== BADLAND: Game of the Year Edition ===<br />
<br />
Refer to [[#Missing libcurl.so.4 or version CURL_OPENSSL_3 not found]].<br />
<br />
=== BATTLETECH ===<br />
<br />
==== Game does not start ====<br />
<br />
Try deleting {{ic|''BATTLETECH''/BattleTech_Data/plugins/x86_64/libc.so.6}}, this should make the game run again.<br />
<br />
=== Beat Cop ===<br />
<br />
==== "BeatCop.x86_64" is not responding ====<br />
<br />
Run {{ic|BeatCop.x86}} instead of {{ic|BeatCop.x86_64}}.<br />
<br />
=== Binding of Isaac: Rebirth ===<br />
<br />
==== No sound ====<br />
<br />
{{Note|This also helps with Never Alone (Kisima Ingitchuna) and No Time to Explain.}}<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
Adjust the audio levels in the game options.<br />
<br />
=== BioShock Infinite ===<br />
<br />
==== Game launching on wrong monitor in fullscreen mode ====<br />
<br />
Add the following launch option:<br />
--eon_force_display=1<br />
<br />
Various more fixes and tweaks can be found [https://pcgamingwiki.com/wiki/BioShock_Infinite here]<br />
<br />
=== BLACKHOLE ===<br />
<br />
Refer to [[#Missing libcurl.so.4 or version CURL_OPENSSL_3 not found]].<br />
<br />
=== Black Mesa ===<br />
<br />
Install {{AUR|lib32-gperftools}} for 32bit version of libtcmalloc_minimal.so.4 which is needed [https://steamcommunity.com/app/362890/discussions/1/340412628175324858/?ctp=7 Source].<br />
<br />
=== Block'hood ===<br />
<br />
==== White screen on startup ====<br />
<br />
When launched the game may only display a white screen with no interface and no way to play the game. Add "-screen-fullscreen 0" to launch options.<br />
<br />
=== The Book of Unwritten Tales ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|lib32-jasper}}<br />
* {{AUR|lib32-libxaw}}<br />
<br />
If the game does not start, uncheck: ''Properties > Enable Steam Community In-Game''.<br />
<br />
The game is known to segfault when opening the settings and possibly during or before playing. A workaround from the [https://steamcommunity.com/app/221410/discussions/3/846939071081758230/#p2 Steam discussions] is to replace the game's {{ic|RenderSystem_GL.so}} with one from Debian's repositories. To do that download [https://launchpad.net/ubuntu/+archive/primary/+files/libogre-1.7.4_1.7.4-3_i386.deb this deb file], and extract it with {{Pkg|dpkg}}:<br />
<br />
$ dpkg -x libogre-*.deb outdir<br />
<br />
Now replace {{ic|''GAME''/lib/32/RenderSystem_GL.so}} with the one extracted from the {{ic|.deb}} package.<br />
<br />
=== BRAIN/OUT ===<br />
<br />
If the game does not start with error message saying "invalid app configuration".<br />
Change directory to game folder:<br />
<br />
$ cd ~/.steam/steam/steamapps/common/BrainOut/<br />
<br />
Run game directly:<br />
<br />
$ java -jar brainout-steam.jar<br />
<br />
You need to have steam running in the background.<br />
<br />
=== The Book of Unwritten Tales: The Critter Chronicles ===<br />
<br />
See [[#The Book of Unwritten Tales]].<br />
<br />
To prevent the game from crashing at the end credits, change the size of the credits image as described [https://steamcommunity.com/app/221830/discussions/0/828925849276110960/#c810921273836530791 here].<br />
<br />
=== Borderlands 2 ===<br />
<br />
==== Migrating saves from other platforms ====<br />
<br />
Borderlands 2 does not support cross-platform Steam Cloud syncing,<br />
you have to manually copy the files between platforms.<br />
Save locations can be found [https://pcgamingwiki.com/wiki/Borderlands_2#Game_data here].<br />
Make sure your user can access the files.<br />
<br />
==== Using Ctrl Key ====<br />
<br />
Borderlands 2 does not allow the {{ic|Ctrl}} key to be used by default. The game seems to be accessing keycodes and not keysyms, therefore xmodmap has no affect. A workaround is using ''setkeycodes'' to map the Ctrl-scancode to some other key, as described in [[Map scancodes to keycodes#Using setkeycodes]]. I use {{ic|setkeycodes 0x1d 56}} (as root) to map Ctrl to Alt before starting the game and {{ic|setkeycodes 0x1d 29}} to restore the default.<br />
<br />
==== Logging into SHiFT ====<br />
<br />
Out of the box you will not be able to log into SHiFT since the game expects certificates to be in {{ic|/usr/lib/ssl}}, which is where Ubuntu stores them. Arch however uses {{ic|/etc/ssl}}.<br />
To resolve the problem, run the game with {{ic|1=SSL_CERT_DIR=/etc/ssl/certs}}.<br />
<br />
==== Game crashes nearly instantly ====<br />
<br />
The game crashes in libopenal directly after launch.<br />
<br />
Possible solution 0: Run the game with the {{ic|-nostartupmovies}} flag. It no longer crashes in libopenal with a general protection error.<br />
<br />
Possible solution 1: As of lib32-openal version 1.18.0-1, the game crashes instantly. The possible solutions are to downgrade lib32-openal to 1.17.2-1, or to start the game with {{ic|LD_PRELOAD<nowiki>=</nowiki>'$HOME/.steam/root/ubuntu12_32/steam-runtime/i386/usr/lib/i386-linux-gnu/libopenal.so.1'}}.<br />
<br />
In case there are messages like this in the terminal:<br />
<br />
[ 671.617205] Borderlands2[2772]: segfault at 0 ip (null) sp 00000000ff9a462c error 14 in Borderlands2[8048000+235a000]<br />
<br />
The following change may help ([https://steamcommunity.com/app/49520/discussions/0/348292787746982160/ source]):<br />
LD_PRELOAD='./libcxxrt.so:/usr/$LIB/libstdc++.so.6' %command%<br />
<br />
Possible solution 2: Launch steam as {{ic|steam-native}} as described in [[Steam/Troubleshooting #Steam native runtime|#Steam native runtime]]. If the game still fails to launch even after installing the {{Pkg|steam-native-runtime}} meta package, then you might be missing some libraries. You can find those missing libraries as described in [[Steam/Troubleshooting #Debugging shared libraries|#Debugging shared libraries]].<br />
<br />
=== Borderlands: The Pre-Sequel ===<br />
<br />
See [[#Borderlands 2]].<br />
<br />
==== Keyboard not working ====<br />
<br />
This can occur with certain window managers e.g. [[dwm]]. Try a different [[window manager]], or install {{pkg|wmname}} and run:<br />
$ wmname LG3D<br />
<br />
see [[Java#Impersonate another window manager]] for more information.<br />
<br />
==== Not starting via Steam ====<br />
<br />
If the game appears as ''Running'', then syncs and closes when you launch it from Steam, try creating a {{ic|steam_appid.txt}} in the game directory<br />
containing {{ic|261640}}. This should resolve the issue and let you start the game directly from the game directory. If that does not work, try using the {{Pkg|steam-native-runtime}}.<br />
<br />
=== Chaos Engine ===<br />
<br />
Set your [[launch option]]s to:<br />
<br />
LD_PRELOAD="/usr/lib32/libpng16.so.16" %command%<br />
<br />
If such error is seen in terminal output of steam-native:<br />
/home/$USER/.local/share/Steam/steamapps/common/Chaos engine/TheChaosEngineSteam: /home/$USER/.local/share/Steam/steamapps/common/Chaos engine/lib/libz.so.1: version `ZLIB_1.2.9' not found (required by /usr/lib32/libpng16.so.16)<br />
/home/$USER/.local/share/Steam/steamapps/common/Chaos engine/TheChaosEngineSteam: /home/$USER/.local/share/Steam/steamapps/common/Chaos engine/lib/libz.so.1: version `ZLIB_1.2.3.4' not found (required by /usr/lib32/libpng16.so.16)<br />
<br />
Then link the system libz.so:<br />
cd ~/.local/share/Steam/steamapps/common/Chaos\ engine/lib<br />
mv libz.so.1 libz.so.1.old<br />
ln -s /lib/libz.so.1<br />
<br />
=== Cities in Motion 2 ===<br />
<br />
==== Dialog boxes fail to display properly ====<br />
<br />
You will not be able to read or see anything, and you will have this in your logs:<br />
Fontconfig error: "/etc/fonts/conf.d/10-scale-bitmap-fonts.conf", line 69: non-double matrix element<br />
Fontconfig error: "/etc/fonts/conf.d/10-scale-bitmap-fonts.conf", line 69: wrong number of matrix elements<br />
<br />
Workaround for the bug {{Bug|35039}} is available [https://archive.is/L9AoT here] (replace {{ic|/etc/fonts/conf.d/10-scale-bitmap-fonts.conf}}).<br />
<br />
=== Cities Skylines ===<br />
<br />
==== Game not starting ====<br />
<br />
If you set {{ic|$XDG_DATA_HOME}} to something other than {{ic|$HOME/.local/share}}, Cities Skylines will put some files in {{ic|$XDG_DATA_HOME/Paradox Interactive}} and some hard-coded in {{ic|~/.local/share/Paradox Interactive}}.<br />
Unset the Variable to fix this issue.<br />
<br />
==== Textures not rendering properly ====<br />
<br />
Run the game with {{ic|1=UNITY_DISABLE_GRAPHICS_DRIVER_WORKAROUNDS=yes}}.<br />
<br />
==== Game crashes in loading screen when Node Controller or Intersection Marking tool are enabled in Content Manager ====<br />
<br />
If the game crashes with one or both of the above mods enabled when loading a save or starting a new game but works fine with both mods disabled, install {{Pkg|mono}}.<br />
<br />
=== Civilization V ===<br />
<br />
Run the game with {{ic|1=LD_PRELOAD=/usr/lib32/libopenal.so.1 %command% }}.[https://steamcommunity.com/app/8930/discussions/0/1621726179576099775/] For old versions of PulseAudio (<12.0), use {{ic|1=LD_PRELOAD='./libcxxrt.so:/usr/$LIB/libstdc++.so.6:/usr/lib32/libopenal.so.1' %command% }}.[https://github.com/ValveSoftware/steam-for-linux/issues/4379] If libopenal.so.1 is not in /usr/lib32, you may need to install {{Pkg|lib32-openal}} after making sure multilib is enabled.[[Official repositories#multilib]]<br />
<br />
If you are experiencing heavy lag (less than 1fps) or the game crashes on startup, try adding the following paths to LD_PRELOAD: {{ic|1='/usr/$LIB/libgcc_s.so.1 /usr/$LIB/libxcb.so.1 /usr/$LIB/libgpg-error.so ./libcxxrt.so /usr/lib32/libstdc++.so.6 /usr/lib32/libopenal.so.1'}}.[https://forum.manjaro.org/t/civ-v-wont-launch-after-update/10825/6]{{Dead link|2021|05|17|status=404}}<br />
<br />
==== Stuttering sound with PulseAudio ====<br />
<br />
See [[PulseAudio/Troubleshooting#Laggy sound]].<br />
<br />
==== Game crashes seconds after loading a map ====<br />
<br />
If you have a CPU with more than 8 threads (such as AMD Ryzen), set {{ic|MaxSimultaneousThreads}} to {{ic|16}} in {{ic|config.ini}} in game directory.[https://www.reddit.com/r/civ5/comments/5z77jr/game_crashes_randomly_on_linux_amd_ryzen/]<br />
<br />
Alternatively, you can limit the number of threads the game uses by adding {{ic|taskset -c 0-7 %command%}} to the launch options: [https://steamcommunity.com/app/8930/discussions/0/1693788384127278334/]<br />
<br />
==== Game crashes after intro video with "Unable to load texture (LoadingBaseGame.dds)" / configuration reset at startup ====<br />
<br />
The issue is a result of the game calling some file in a case-insensitive manner.<br />
<br />
The solution is either to install the game on a case-insensitive file system like VFAT, or on a mount point for {{AUR|ciopfs}}.<br />
<br />
It is not enough the game is in a case-insensitive filesystem, but also the configuration/data directory at "~/.local/share/Aspyr/Sid Meier's Civilization 5" needs to be in a case-insensitive filesystem or mount point. If the data directory is in a case-sensitive filesystem, the game will not work correctly and symptoms such as configuration getting constantly reset can be observed.<br />
<br />
==== Game crashes on startup with an error in libpulsecommon-12.0.so" ====<br />
<br />
Run the game with {{ic|1=LD_PRELOAD=/usr/lib32/libopenal.so.1 %command%}}<br />
<br />
==== Steam Overlay not working ====<br />
<br />
If the Steam Overlay does not show up simply add<br />
LD_PRELOAD='/home/USERNAME/.local/share/Steam/ubuntu12_32/gameoverlayrenderer.so' %command%<br />
<br />
to the launch options in the properties of the game in Steam.<br />
<br />
==== Crashes during __memcpy_ssse3 ====<br />
<br />
This appears to be a memory alignment bug that can be corrected by compiling the libraries with -mstackrealign. GDB can also be used to run it as-is with the following launch options:<br />
LD_PRELOAD=/usr/lib/libcurl.so.4 /bin/gdb -windows -batch -return-child-result -nx -eval-command="run" -exec=%command%<br />
<br />
=== Civilization: Beyond earth ===<br />
<br />
If you are getting an instant crash/close upon launch, make sure you have the following packages installed:<br />
<br />
* {{aur|lib32-tbb}}<br />
* {{pkg|lib32-libcurl-compat}}<br />
* {{pkg|lib32-libcurl-gnutls}}<br />
* {{pkg|lib32-openal}}<br />
<br />
==== Segfault after a few minutes ====<br />
<br />
Backtrace:<br />
#0 0x08b71d06 in FireGrafix::DynamicsLock<Graphics::BuildingSkinnedDataDynamicConsts>::DynamicsLock(Graphics::SurfaceSet**, FireGrafix::SurfaceSetPoolAllocator*, unsigned short) ()<br />
#1 0x08c25ffc in cvLandmarkVisSystem::cvLandmarkVisDynamicConstantUpdaterSS::HandleBuildingShaderSkinned(Graphics::FGXShaderPackageInstanceView*, FireGrafix::FGXModelNode*, FGXVector4*) ()<br />
#2 0x08c25f34 in cvLandmarkVisSystem::cvLandmarkVisDynamicConstantUpdaterSS::UpdateNode(Graphics::FGXShaderPackageInstanceView*, FireGrafix::FGXModelNode*, FGXVector4*) ()<br />
#3 0x08c25e2c in FireGrafix::FGXModelRenderByNodeSSExample_Shadow<cvLandmarkVisSystem::cvLandmarkVisDynamicConstantUpdaterSS, 2, FireGrafix::FGXModelRenderEndSuperclass>::RenderNode(unsigned int*, FireGrafix::FGX_SPIV_GENERIC*, FireGrafix::FGXModelNode*, FGXVector4*) ()<br />
#4 0x08c24ff5 in cvLandmarkVisSystem::LandmarkRenderJob::Execute(unsigned int) ()<br />
#5 0x093d26d9 in Platform::JobTask::execute() ()<br />
#6 0xf749f3c0 in ?? () from /usr/lib32/libtbb.so.2<br />
#7 0xf7497551 in ?? () from /usr/lib32/libtbb.so.2<br />
#8 0xf7495fc3 in ?? () from /usr/lib32/libtbb.so.2<br />
#9 0xf7491b7e in ?? () from /usr/lib32/libtbb.so.2<br />
#10 0xf7491db7 in ?? () from /usr/lib32/libtbb.so.2<br />
#11 0xf78f4346 in start_thread () from /usr/lib32/libpthread.so.0<br />
#12 0xf7716026 in clone () from /usr/lib32/libc.so.6<br />
<br />
Segfault is caused by {{aur|lib32-tbb}}. To fix the issue:<br />
# Download the [http://archive.ubuntu.com/ubuntu/pool/universe/t/tbb/libtbb2_4.2~20130725-1.1ubuntu1_i386.deb libtbb2 deb-package] from the Ubuntu archive.<br />
# Unpack {{ic|libtbb.so.2}} from {{ic|libtbb2_4.2_20130725-1.1ubuntu1_i386.deb/data.tar.xz/usr/lib}} into the game directory.<br />
# Run the game with {{ic|1=LD_PRELOAD='./libtbb.so.2'}}.<br />
<br />
=== Civilization VI ===<br />
<br />
Either run with steam-native, launch option {{ic|1=LD_PRELOAD=/usr/lib/libfreetype.so.6 %command%}}, {{ic|1=env LD_PRELOAD='./libcxxrt.so:/usr/$LIB/libstdc++.so.6'}} or go to ''Properties > Compatibility'', check "Force the use of a specific Stam Play compatiblity tool" and select "Steam Linux runtime".<br />
<br />
If you are using [[Wayland]], you might need to also set {{ic|1=QT_QPA_PLATFORM=xcb}}, as the game's launcher uses a version of Qt which only supports Xorg (see [[Wayland#Qt]]). Some versions of the game also seem to require adding {{ic|1=SDL_VIDEODRIVER=x11}} and will otherwise refuse to start with an error message that reads "An unrecoverable error has occurred, and Civilization VI cannot continue."<br />
<br />
Follow [[#OpenSSL 1.0 setup]]. <br />
<br />
Ensure that Steam Workshop mods are disabled as certain ones may cause issues following loading.<br />
<br />
==== Steam Overlay not working ====<br />
<br />
Since the introduction of the new launcher, the steam overlay does not work in this game. To get it working again, simlpy skip the launcher as described in [[#Launcher unable to load page]].<br />
<br />
==== If Segfault Immediately on Start ====<br />
<br />
This is a strange corner case which happens infrequently at best (and the prerequisites for reproducing it are unknown), but the crash would look like this:<br />
<br />
# Immediate segfault on start, before any windows get created<br />
# The game creates {{ic|~/.local/share/aspyr-media/Sid Meier's Civilization VI/AppOptions.txt}}<br />
# The string {{ic|AppHost::BugSubmissionPackager::BugSubmissionPackager}} appears in the backtrace output when running the game under {{pkg|gdb}}<br />
## To run under {{pkg|gdb}}, first launch a shell and change into the game directory.<br />
## Then {{ic|echo 289070 > steam_appid.txt}} ''(otherwise the game will not launch outside of Steam itself)''<br />
## Then run something like {{ic|gdb -ex run -ex bt -ex quit --args ./Civ6 ./Civ6}}<br />
## The relevant info towards the end of the output should look like this:<br />
Thread 3 "Civ6" received signal SIGSEGV, Segmentation fault.<br />
[Switching to Thread 0x7fffe5d06700 (LWP 12315)]<br />
0x000000000201121e in AppHost::BugSubmissionPackager::BugSubmissionPackager(unsigned long, String::BasicT<Platform::StaticHeapAllocator<5, 0>, (String::Encoding)4> const&, String::BasicT<Platform::StaticHeapAllocator<5, 0>, (String::Encoding)0> const&, AppHost::ModuleVersionInfo const&) ()<br />
#0 0x000000000201121e in AppHost::BugSubmissionPackager::BugSubmissionPackager(unsigned long, String::BasicT<Platform::StaticHeapAllocator<5, 0>, (String::Encoding)4> const&, String::BasicT<Platform::StaticHeapAllocator<5, 0>, (String::Encoding)0> const&, AppHost::ModuleVersionInfo const&) ()<br />
#1 0x000000000200c796 in AppHost::_INTERNAL::SetupFXSPlatform(AppHost::AppEnvironment const*, AppHost::AppOptions*)<br />
()<br />
#2 0x000000000200fea0 in AppHost::RunApp(int, char**, AppHost::Application*) ()<br />
#3 0x000000000200f9bc in AppHost::RunApp(char*, AppHost::Application*) ()<br />
#4 0x0000000001112d98 in WinMain ()<br />
#5 0x00000000010bdab0 in ?? ()<br />
#6 0x00000000010bfb31 in ThreadHANDLE::ThreadProc(void*) ()<br />
#7 0x00007ffff473e08a in start_thread () from /usr/lib/libpthread.so.0<br />
#8 0x00007ffff38f747f in clone () from /usr/lib/libc.so.6<br />
<br />
If all of that is the case for you, the fix is pretty simple. Edit {{ic|~/.local/share/aspyr-media/Sid Meier's Civilization VI/AppOptions.txt}} and change the line reading {{ic|EnableBugCollection 1}} to {{ic|EnableBugCollection 0}}.<br />
<br />
Presumably this fix will prevent any automated bug reports from reaching Aspyr, should you encounter crashes/bugs in the future, but it will at least let the game launch properly.<br />
<br />
==== If Crash with Error "undefined symbol FT_Done_MM_Var" ====<br />
<br />
If the game crashed with error<br />
./GameGuide/Civ6: symbol lookup error: /usr/lib/libfontconfig.so.1: undefined symbol: FT_Done_MM_Var<br />
<br />
The solution is to set launch option to be <br />
<br />
LD_PRELOAD=/usr/lib/libfreetype.so.6 %command%<br />
<br />
==== If the game ends up being a grey-color blank screen ====<br />
<br />
The solution is to disable mods.<br />
<br />
==== If the computer becomes irresponsive after "Loading" screen ====<br />
<br />
This may be caused by amdgpu driver crash due to insuffcient video memory. If running an integrated graphics (eg. AMD Renoir), try allocating more memory in your BIOS.<br />
<br />
==== Multi-monitor and wayland: mismatched resolution ====<br />
<br />
Wayland does not define a primary monitor, so the game will show the available resolutions of an arbitrary monitor; it may not have the same size and the mouse may be off. A solution is to set an XWayland monitor as primary.<br />
<br />
To find the list of XWayland monitors: {{ic|xrandr --listmonitors}}<br />
<br />
To set (eg) the XWAYLAND4 monitor as the primary: {{ic|xrandr --output XWAYLAND4 --primary}}<br />
<br />
==== Launcher window is huge (wrong scaling) ====<br />
<br />
If the launcher window is huge (sometimes bigger than the screen), then the scaling is wrong. Add {{ic|1=QT_AUTO_SCREEN_SCALE_FACTOR=0}} to the launch options and on next start the launcher should be usable.<br />
<br />
==== Launcher unable to load page ====<br />
<br />
The launcher often shows errors like {{ic|1=Error loading page}}. It is possible to bypass the launcher by editing the games startup configuration {{ic|~/.local/share/Steam/steamapps/common/Sid Meier's Civilization VI/Civ6}} and changing the line {{ic|1=./GameGuide/Civ6}} to {{ic|1=./Civ6Sub}}.<br />
<br />
=== CrossCode ===<br />
<br />
==== If FontConfig Errors on Start ====<br />
<br />
{{bc|<br />
...<br />
Fontconfig error: "/etc/fonts/fonts.conf", line 6: invalid attribute 'translate'<br />
Fontconfig error: "/etc/fonts/fonts.conf", line 6: invalid attribute 'selector'<br />
Fontconfig error: "/etc/fonts/fonts.conf", line 7: invalid attribute 'xmlns:its'<br />
Fontconfig error: "/etc/fonts/fonts.conf", line 7: invalid attribute 'version'<br />
Fontconfig warning: "/etc/fonts/fonts.conf", line 9: unknown element "description"<br />
Fontconfig warning: "/etc/fonts/conf.d/10-hinting-slight.conf", line 4: unknown element "its:rules"<br />
Fontconfig warning: "/etc/fonts/conf.d/10-hinting-slight.conf", line 5: unknown element "its:translateRule"<br />
Fontconfig error: "/etc/fonts/conf.d/10-hinting-slight.conf", line 5: invalid attribute 'translate'<br />
Fontconfig error: "/etc/fonts/conf.d/10-hinting-slight.conf", line 5: invalid attribute 'selector'<br />
Fontconfig error: "/etc/fonts/conf.d/10-hinting-slight.conf", line 6: invalid attribute 'xmlns:its'<br />
Fontconfig error: "/etc/fonts/conf.d/10-hinting-slight.conf", line 6: invalid attribute 'version'<br />
Fontconfig warning: "/etc/fonts/conf.d/10-hinting-slight.conf", line 8: unknown element "description"<br />
Fontconfig warning: "/etc/fonts/conf.d/10-scale-bitmap-fonts.conf", line 4: unknown element "its:rules"<br />
Fontconfig warning: "/etc/fonts/conf.d/10-scale-bitmap-fonts.conf", line 5: unknown element "its:translateRule"<br />
...<br />
}}<br />
Download the latest version of nwjs from [https://nwjs.io/ here] and extract its contents into your CrossCode directory, overwriting the files.<br />
<br />
Be sure to rename {{ic|nw}} to {{ic|CrossCode}} after.<br />
<br />
This solution was documented to work with CrossCode 1.2 and nwjs 0.41.2 and is based on [https://steamcommunity.com/app/368340/discussions/1/1727575977598417554/ this steam post]<br />
<br />
=== Deus Ex: Mankind Divided ===<br />
<br />
Follow [[#OpenSSL 1.0 setup]].<br />
<br />
Requires {{Pkg|libidn11}} & {{Pkg|librtmp0}}.<br />
<br />
Also if you use Bumblebee set your [[launch option]]s to:<br />
<br />
LD_PRELOAD="$LD_PRELOAD:libpthread.so.0:libGL.so.1" __GL_THREADED_OPTIMIZATIONS=1 optirun %command%<br />
<br />
=== The Clockwork Man ===<br />
<br />
Requires {{pkg|lib32-libidn}} (pulled in by {{pkg|steam-native-runtime}}).<br />
<br />
=== Company of Heroes 2 ===<br />
<br />
Make sure you have {{AUR|lib32-gconf}} installed.<br />
<br />
==== Missing libpcre.so.3 and libidn.so.11 ====<br />
<br />
Like with [[#Alien Isolation]] you need to symlink {{ic|/usr/lib/libpcre.so}} to {{ic|''GAME''/lib/''arch''/libpcre.so.3}}, as well as {{ic|/usr/lib/libidn.so}} to {{ic|''GAME''/lib/''arch''/libidn.so.11}}, otherwise the game will fail to start.<br />
<br />
=== Cossacks 3 ===<br />
<br />
==== No sound ====<br />
<br />
Use the steam-runtime, e.g. set the [https://support.steampowered.com/kb_article.php?ref=1040-JWMT-2947 launch options] to:<br />
<br />
~/.steam/root/ubuntu12_32/steam-runtime/run.sh %command%<br />
<br />
==== Flashing screen with primus ====<br />
<br />
Set {{ic|1=PRIMUS_SYNC=2}}in the launch options.<br />
<br />
=== Counter-Strike: Source (CS:S) ===<br />
<br />
==== Invisible symbols, special characters and cyrillic letters ====<br />
<br />
Check [[#Squares or invisible symbols, special characters and cyrillic letters in Source-based games]]<br />
<br />
=== Counter-Strike: Global Offensive (CS:GO) ===<br />
<br />
==== Game starts on the wrong screen ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/60 csgo-osx-linux issue #60]<br />
<br />
If it happens, go into fullscreen windowed or windowed mode and drag the window to the correct monitor. Then go back into fullscreen, the game should now be on the correct monitor.<br />
<br />
==== Cannot reach bottom of the screen on menus ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/594 csgo-osx-linux issue #594]<br />
<br />
If you have a secondary monitor you might have a part of your lower screen you cannot reach in menus.<br />
If on Gnome you can try to open the overview (Super key) and drag the game to the other monitor and back.<br />
<br />
If you are not on Gnome or dragging the window back and forth did not work you can try to [[install]] {{pkg|wmctrl}} and run this command, where X and Y is the offset of the window and H and W is the size.<br />
wmctrl -r "Counter-Strike: Global Offensive - OpenGL" -e 0,X,Y,H,W<br />
<br />
'''Example''': SecondaryMonitor: on the left 2560x1600, GamingMonitor: on the right 2560x1440).<br />
wmctrl -r "Counter-Strike: Global Offensive - OpenGL" -e 0,2560,0,1600,1200<br />
Here X and Y is 0,2560 to move the window to the monitor on the right and H and W 1600,1200 is set to match the in-game resolution.<br />
<br />
==== Sound is played slightly delayed ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/45 csgo-osx-linux issue #45]<br />
<br />
See [[PulseAudio/Troubleshooting#Laggy sound]] for a possible solution.<br />
<br />
==== Mouse not working in-game ====<br />
<br />
If your mouse works in the main menu but not in-game, run the game with {{ic|1=SDL_VIDEO_X11_DGAMOUSE=0}}.<br />
[https://bbs.archlinux.org/viewtopic.php?id=184905]<br />
<br />
==== Brightness slider not working ====<br />
<br />
[[Install]] {{pkg|xorg-xrandr}} and run {{ic|xrandr}} to find out the name of your connected display output.<br />
<br />
Edit {{ic|''GAME''/csgo.sh}} and add the following lines (adapt ''output_name''):<br />
<br />
'''# gamma correction'''<br />
'''xrandr --output ''output_name'' --gamma 1.6:1.6:1.6 # play with values if required'''<br />
STATUS=42<br />
while [$STATUS -eq 42]; do<br />
...<br />
done<br />
'''# restore gamma'''<br />
'''xrandr --output ''output_name'' --gamma 1:1:1'''<br />
exit $STATUS<br />
<br />
==== Microphone not working ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/573#issuecomment-174016722 csgo-osx-linux issue #573]<br />
<br />
CS:GO uses the default PulseAudio sound device ignoring what is configured in Steam settings.<br />
<br />
First find out the source name of your microphone (it should start with {{ic|alsa_input.}}):<br />
$ pacmd list-sources<br />
<br />
Then set the default device (change the name accordingly):<br />
$ pacmd set-default-source ''device_name''<br />
<br />
Also lower the microphone level to 60% otherwise you will get some nasty background noise and you will be difficult to understand (change the name accordingly):<br />
$ pacmd set-source-volume ''device_name'' 0x6000<br />
<br />
==== Mouse is unrensponsive or moves slowly ====<br />
<br />
Set launch options to:<br />
vblank_mode=0 %command%<br />
<br />
Works with almost any other game.<br />
<br />
==== Game crashes on startup with game controller plugged in ====<br />
<br />
[https://github.com/ValveSoftware/csgo-osx-linux/issues/1757 csgo-osx-linux issue #1757]<br />
<br />
The solution is to add {{ic|-nojoy}} to the launch options.<br />
<br />
==== Some texts are missing or mis-positioned ====<br />
<br />
[[Locale#Generating_locales|Generate]] the {{ic|en_US.UTF-8}} locale will solve the problem.<br />
<br />
=== Creeper World 3: Arc Eternal ===<br />
<br />
==== Game does not start ====<br />
<br />
Search for Player.log<br />
(might be in ~/.config/unity3d/Knuckle Cracker LLC/Creeper World 3/ )<br />
<br />
If it says somewhere in Player.log<br />
"FMOD failed to get number of drivers ... An error occured that was not supposed to. Contact support."<br />
Unity is probably having problem with some pulse audio libraries. <br />
<br />
Fix that worked for me:<br />
Remove or rename all instances of libpulse-simple* files.<br />
<br />
Places to look for them:<br />
/usr/lib<br />
/usr/lib32<br />
~/.steam/steam/ubuntu12_32/steam-runtime/i386/usr/lib/i386-linux-gnu/<br />
~/.steam/steam/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/<br />
<br />
=== Crusader Kings II ===<br />
<br />
==== No audio ====<br />
<br />
SDL uses [[PulseAudio]] by default, so to use it with [[ALSA]] you need to set:<br />
<br />
{{hc|~/.pam_environment|2=SDL_AUDIODRIVER=alsa}}<br />
<br />
==== Oddly sized starting window ====<br />
<br />
You can make full screen mode the default by setting {{ic|1=fullscreen=yes}} in {{ic|~/.paradoxinteractive/Crusader Kings II/settings.txt}}.<br />
<br />
==== DLCs not detected ====<br />
<br />
If the DLC tab in the launcher is not selectable, rename the {{ic|DLC}} directory in the game directory to {{ic|dlc}}.<br />
<br />
==== Game takes ages to start ====<br />
<br />
If you are using a nvidia graphics card, make sure you have enabled the [[NVIDIA#DRM kernel mode setting|DRM kernel mode setting]].<br />
<br />
==== Game does not start at all ====<br />
<br />
If the game stopped launching after Patch 3.3 (when the game became 64-bit only), install {{Pkg|tbb}}.<br />
<br />
=== Crypt of the NecroDancer ===<br />
<br />
==== Crashes after splash screen ====<br />
<br />
The following error occurs if launching Steam from the terminal.<br />
<br />
FMOD ERROR: UpdateFMOD SystemUpdate: This command failed because System::init or System::setDriver was not called.<br />
<br />
This error is solved by installing {{pkg|pulseaudio-alsa}}.<br />
<br />
=== The Curious Expedition ===<br />
<br />
==== Game stuck on loading screen ====<br />
<br />
The Electron shipped with this game is too old for Arch Linux.<br />
<br />
Install {{pkg|electron}} and run the game with {{ic|electron resources/app.asar}}.<br />
<br />
=== Death Road To Canada ===<br />
<br />
==== No music ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
=== Dirt ===<br />
<br />
Follow [[#OpenSSL 1.0 setup]].<br />
<br />
=== Dirt Rally ===<br />
<br />
Prepend {{ic|lib/x86_64}} to your {{ic|LD_LIBRARY_PATH}}, otherwise the game will fail to start.<br />
<br />
{{Note|The order of the paths is important. {{ic|$LD_LIBRARY_PATH}} must be the last entry or it will not work.}}<br />
<br />
=== Divinity: Original Sin - Enhanced Edition ===<br />
<br />
==== Game does not start when using Bumblebee optirun or primusrun ====<br />
<br />
Edit {{ic|''GAME''/runner.sh}} to use primusrun:<br />
LD_LIBRARY_PATH="." primusrun ./EoCApp<br />
<br />
==== Game does not work with mesa ====<br />
<br />
It is a known bug and they have no intention of fixing it, see [https://bugs.freedesktop.org/show_bug.cgi?id=93551 the bug].<br />
<br />
Workaround[https://www.gamingonlinux.com/articles/divinity-original-sin-may-soon-work-with-mesa-drivers.8867/comment_id=81524] (see [https://bugs.freedesktop.org/show_bug.cgi?id=93551#c46 step by step guide])<br />
<br />
Get the following file:<br />
https://bugs.freedesktop.org/attachment.cgi?id=125302<br />
and rename it to {{ic|divos-hack.c}}<br />
<br />
Then execute <br />
$ gcc -s -O2 -shared -fPIC -o divos-hack.{so,c} -ldl<br />
<br />
Copy the {{ic|divos-hack.so}} to the ''game'' folder.<br />
<br />
For GOG version, go to the said game folder and run Divinity with the following command<br />
$ allow_glsl_extension_directive_midshader=true LD_PRELOAD="divos-hack.so" ./runner.sh<br />
<br />
For ''steam'', open a console, change to the divinity directory with <br />
$ cd ~/.steam/steam/steamapps/common/Divinity Original Sin Enhanced Edition<br />
<br />
Launch steam and got o the preferences of the game, and open the "Set Launch Options" dialogue. There, put the following<br />
allow_glsl_extension_directive_midshader=true LD_PRELOAD="divos-hack.so:$LD_PRELOAD" %command%<br />
<br />
Then just start the game.<br />
<br />
=== Doki Doki Literature Club ===<br />
<br />
Linux version is shipped with the Windows version, but can only be installed with Steam Play.<br />
<br />
Native version can be started with this launch option: {{ic|./DDLC.sh # %command%}}<br />
<br />
=== Don't Starve Together ===<br />
<br />
If you get a crash on start in {{ic|libX11.so.6.4.0}}, the problem is likely a bug in SDL1.3. Unfortunately, DST is statically linked and we can't use {{ic|LD_PRELOAD}} to replace libSDL with something newer. The bug has been reported to the developer, but a possible workaround is [https://forums.kleientertainment.com/klei-bug-tracker/dont-starve-together/crash-on-startup-r32786/?do=findComment&comment=49731 to patch {{ic|XGetICValues()}} to not crash when it is incorrectly given a null parameter.]<br />
<br />
=== Dota 2 ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|libudev0}}<br />
* {{pkg|libpng12}}<br />
<br />
==== Install/Set RADV as default Vulkan application ====<br />
<br />
Valve recommend RADV (Mesa) is used instead of AMDVLK (AMD) see here to install and set default:<br />
<br />
<br />
[[Vulkan]]<br />
<br />
==== Switch between OpenGL and Vulkan (recommended) ====<br />
<br />
Under the game launch options add this flag<br />
<br />
OpenGL: -gl<br />
<br />
<br />
Vulkan -vulkan<br />
<br />
<br />
==== In-game font is unreadable ====<br />
<br />
Run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=2.1}}.<br />
<br />
==== Error with libpangoft2 ====<br />
<br />
# [[Install]] the {{pkg|pango}} package.<br />
# Remove {{ic|libpango-1.0.so}} and {{ic|libpangoft2-1.0.so}} in {{ic|''GAME''/game/bin/linuxsteamrt64}}.<br />
# If you are using Bumblebee add {{ic|1=LD_PRELOAD="libpthread.so.0 libGL.so.1" __GL_THREADED_OPTIMIZATIONS=1 optiru}} to your [[launch option]]s.<br />
<br />
==== The game does not start ====<br />
<br />
If you run the game from the terminal and, although no error is shown, try disabling: ''Steam > Settings > In-Game > Enable Steam Community In-Game''.<br />
<br />
Apparently the game [[#The Book of Unwritten Tales]] has the same problem. It also describes a workaround that is untested in Dota 2.<br />
<br />
==== Game runs on the wrong screen ====<br />
<br />
: [https://github.com/ValveSoftware/Dota-2/issues/11 GitHub Dota 2 issue #11]<br />
<br />
==== Game does not start with libxcb-dri3 error message ====<br />
<br />
After a recent Mesa update, Dota 2 stopped working. The error message is:<br />
<br />
SDL_GL_LoadLibrary(NULL) failed: Failed loading libGL.so.1: /usr/lib32/libxcb-dri3.so.0: undefined symbol: xcb_send_fd<br />
<br />
==== Game has no audio ====<br />
<br />
This might happen because Dota 2 is trying to output through ALSA, which has already been taken over by PulseAudio. Try installing {{pkg|pulseaudio-alsa}} and setting in-game audio output to 'Default'.<br />
<br />
==== Steam overlay ====<br />
<br />
Steam distributes a copy of libxcb which is incompatible with the latest xorg libxcb. See [https://github.com/ValveSoftware/steam-for-linux/issues/3199], [https://github.com/ValveSoftware/steam-for-linux/issues/3093].<br />
<br />
==== Clear or disable shader cache for troubleshooting purposes ====<br />
<br />
To clear shader cache delete delete the 570 (Dota's app ID) folder under the steam shadercache directory e.g.<br />
<br />
/home/gaben/steam/steamapps/shadercache/<br />
<br />
To disable shader cache add the following to dota's launch options:<br />
<br />
-vulkan_disable_steam_shader_cache<br />
<br />
<br />
==== Chinese tips and player names not shown ====<br />
<br />
The Chinese characters in tips and player names are displayed as block characters.<br />
<br />
The problem is caused by the font packages: {{pkg|ttf-dejavu}}, {{pkg|ttf-liberation}} and {{aur|ttf-ms-fonts}}.<br />
<br />
: [https://github.com/ValveSoftware/Dota-2/issues/1688 GitHub Steam issue #1688]<br />
<br />
==== Chinese input method problem ====<br />
<br />
Dota2 is compatible with [[IBus]] .<br />
<br />
=== Devil Daggers ===<br />
<br />
Refer to [[#Missing libcurl.so.4 or version CURL_OPENSSL_3 not found]].<br />
<br />
=== Drox Operative ===<br />
<br />
If the game fails to start with "Couldn't find Database/database.dbl!", manually extract the assets. assets003.zip will overwrite some files from the previous files.<br />
<br />
$ cd "~/.steam/root/steamapps/common/Drox Operative/Assets"<br />
$ unzip assets00[123].zip<br />
<br />
=== Dungeon Souls ===<br />
<br />
For AMD cards this game crashes on launch, unless you start it like this:<br />
<br />
R600_DEBUG=mono %command%<br />
<br />
=== Dying Light ===<br />
<br />
==== Game crashes on startup ====<br />
<br />
The game runs with the Steam setting "Force the use of a specific Steam Play compatibility tool" > "Steam Linux Runtime"<br />
<br />
=== Dynamite Jack ===<br />
<br />
Requires {{Pkg|lib32-sdl}}.<br />
<br />
==== Sound Issues ====<br />
<br />
When running on 64-bit Arch Linux, there may be "pops and hisses" when running Dynamite Jack. This could be caused by not having {{ic|1=STEAM_RUNTIME=0}} set. (However, even with {{ic|1=STEAM_RUNTIME=0}} set, the game may still sometimes start with this issue. Exiting and restarting the game seems to make the problem go away.)<br />
<br />
==== Game does not start ====<br />
<br />
If running steam with the {{ic|1=STEAM_RUNTIME=0}}, Dynamite Jack may have a problem starting. Check the steam error messages for this message:<br />
<br />
/home/$USER/.steam/root/steamapps/common/Dynamite Jack/bin/main: error while loading shared libraries: libSDL-1.2.so.0: cannot open shared object file: No such file or directory<br />
<br />
Install {{pkg|lib32-sdl}} from [[multilib]] and Dynamite Jack should start up.<br />
<br />
=== Empire Total War ===<br />
<br />
==== Weird unreadable fonts ====<br />
<br />
Open {{ic|~/.local/share/feral-interactive/Empire/preferences}}, then find {{ic|UsePBOSurfaces}} and change it from 1 to 0.<br />
<br />
=== Euro Truck Simulator 2 ===<br />
<br />
==== Shows only a black screen ====<br />
<br />
Select safe mode when the game starts up.<br />
<br />
=== Firewatch ===<br />
<br />
If Firewatch starts but does not show anything try running Steam with<br />
<br />
`STEAM_RUNTIME_PREFER_HOST_LIBRARIES=0 steam`<br />
<br />
=== Football Manager 2014 ===<br />
<br />
This game will not run when installed on an [[XFS]] or reiserfs filesystem. Workaround is to install on an ext4 filesystem.<br />
<br />
=== FORCED ===<br />
<br />
Requires {{pkg|lib32-glu}}.<br />
<br />
This game has 32-bit and 64-bit binaries. For some reason, Steam will launch the 32-bit binary even on 64-bit Arch Linux.<br />
When manually launching the 64-bit binary, the game starts, but cannot connect to Steam account, so you cannot play.<br />
So install 32-bits dependencies, and launch the game from Steam.<br />
<br />
=== For the King ===<br />
<br />
For steam-native --<br />
<br />
Starts with black page. Requires to be told to use the libSDL2 shipping with Steam<br />
<br />
Add to Steam launch options for game. <br />
<br />
LD_PRELOAD=~/.local/share/Steam/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0 %command%<br />
<br />
Note however, that this disables the Steam overlay as a side effect.<br />
<br />
For steam-runtime --<br />
<br />
It works out of the box.<br />
<br />
For the full experience, run FTK via steam-runtime instead of steam-native.<br />
<br />
=== FTL: Faster than Light ===<br />
<br />
==== Compatibility ====<br />
<br />
After installation, FTL may fail to run due to a 'Text file busy' error (characterised in Steam by your portrait border going green then blue again). The easiest way to mend this is to just reboot your system. Upon logging back in FTL should run.<br />
<br />
The Steam overlay in FTL does not function as it is not a 3D accelerated game. Because of this the desktop notifications will be visible. If playing in fullscreen, therefore, these notifications in some systems may steal focus and revert you back to windowed mode with no way of going back to fullscreen without relaunching. The binaries for FTL on Steam have no DRM and it is possible to run the game ''without'' Steam running, so in some cases that may be optimum - just ensure that you launch FTL via the launcher script in {{ic|''GAME''/data/}} rather than the FTL binary in the $arch directory.<br />
<br />
==== Problems with open-source video driver ====<br />
<br />
FTL may fail to run if you are using an opensource driver for your video card. There are two solutions: install a proprietary video driver or delete (rename if you are unsure) the library "libstdc++.so.6" inside {{ic|''GAME''/data/amd64/lib}}. This is if you are using a 64bit system. In case you are using a 32bit system you have to remove (rename) the same library located into {{ic|''GAME''/data/x86/lib}}.<br />
<br />
==== Artifacts when launching, Problems with openGL ====<br />
<br />
Using the open source drivers, ATI for radeon cards, the game can display artifacts on screen. Run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=3.0 %command%}}<br />
<br />
=== Game Dev Tycoon ===<br />
<br />
==== Game does not start ====<br />
<br />
You might get an error about missing {{ic|libudev.so.0}}.<br />
<br />
Run the game with {{ic|1=LD_PRELOAD=/usr/lib/libudev.so.1}}.<br />
<br />
=== Garry's Mod ===<br />
<br />
==== Game does not start ====<br />
<br />
When an error about a missing {{ic|client.so}} appears, try the following:<br />
<br />
$ cd ~/.steam/root/steamapps/common/GarrysMod/bin/<br />
$ ln -s libawesomium-1-7.so.0 libawesomium-1-7.so.2<br />
$ ln -s ../garrysmod/bin/client.so ./<br />
<br />
If the error mentions a missing library for {{ic|libgconf-2.so.4}}, install {{AUR|lib32-gconf}}.<br />
<br />
==== Opening some menus causes the game to crash ====<br />
<br />
Most menus work fine, but ones with checkboxes (LAN multiplayer, mounted games list) do not work at all. This is a bug in the menu code.<br />
<br />
If you prefer the default menu style and do not mind a hacky solution: [https://github.com/Facepunch/garrysmod-issues/issues/86#issuecomment-30935491 Simon311] has written code with instructions to fix it.<br />
<br />
If you do not care for the default menu style and want a more stable but feature-incomplete solution, Facepunch developer [https://github.com/robotboy655/gmod-lua-menu robotboy655] has written a new menu.<br />
<br />
==== Game crashes after attempting to join server ====<br />
<br />
While in the process of joining a server, downloading resources, etc, the game seems to hang and after a while, perhaps during the "sending client info" portion the game crashes, usually without any error messages. Error does not give much information, however, the process for Garry's mod is killed.<br />
<br />
This issue arises more often when joining servers with many addons like DarkRP servers specifically.<br />
<br />
The problem seems to correlate with a weak GPU and the game is timing out from the server, so if the GPU is the problem, lowering the graphics settings to the minimum should fix the problem.<br />
<br />
The problem seems to be related to RAM usage, once you hit around 2GB of RAM used, the game will crash. Servers with many addons have much more RAM usage, and lowering graphics settings to the minimum lowers RAM usage and mitigates crashes.<br />
<br />
Using the experimental x86-64 branch may help mitigate this issue, however keep in mind that some addons may return errors while using this branch.<br />
<br />
=== Gods will be watching ===<br />
<br />
Follow [[#OpenSSL 1.0 setup]].<br />
<br />
=== GRID Autosport ===<br />
<br />
Follow [[#OpenSSL 1.0 setup]].<br />
<br />
==== Black screen when trying to play ====<br />
<br />
Run the game with {{ic|1=LC_ALL=C}}.<br />
<br />
=== Guns of Icarus Online ===<br />
<br />
If you encounter problems, check out the error log at<br />
<br />
~/.config/unity3d/Muse Games/GunsOfIcarusOnline/Player.log<br />
<br />
==== version `CURL_OPENSSL_4' not found (required by /usr/lib/libdebuginfod.so.1) ====<br />
<br />
Install the package {{Pkg|lib32-libcurl-compat}} and include 'libcurl.so.4' in your LD_PRELOAD in your shell environment like so:<br />
<br />
export LD_PRELOAD=$LD_PRELOAD libcurl.so.4<br />
<br />
=== Hack 'n' Slash ===<br />
<br />
==== Crashes when trying to load a game ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
=== Hacker Evolution ===<br />
<br />
Requires {{Pkg|lib32-sdl2_mixer}}.<br />
<br />
=== Half-Life ===<br />
<br />
==== Invisible text ====<br />
<br />
Half-Life uses microsoft fonts to display text, see [[Microsoft fonts]] for ways to install them.<br />
<br />
=== Half-Life 2 and episodes ===<br />
<br />
==== Cyrillic fonts problem ====<br />
<br />
This problem can be solved by deleting "Helvetica" font.<br />
<br />
=== Hammerwatch ===<br />
<br />
==== The game does not start via Steam ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
==== No sound ====<br />
<br />
Hammerwatch opens with a popup: "Sound Error" -- "Could not initialize OpenAL, no sounds will be played. Try updating your OpenAL drivers."<br />
<br />
OpenAL, which Hammerwatch uses, defaults to PulseAudio. To change that, add the following line to {{ic|/etc/openal/alsoft.conf}}:<br />
<br />
drivers=alsa,pulse<br />
<br />
This way, Hammerwatch will use ALSA. This solution was found [https://stackoverflow.com/questions/9547396/what-does-al-lib-pulseaudio-c612-context-did-not-connect-access-denied-me here].<br />
<br />
=== Harvest: Massive Encounter ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|lib32-sfml}}<br />
* {{Pkg|lib32-libjpeg6-turbo}}<br />
* {{Pkg|lib32-nvidia-cg-toolkit}}<br />
* {{pkg|lib32-gtk2}}<br />
* {{pkg|lib32-libvorbis}}<br />
* {{pkg|lib32-openal}}<br />
<br />
==== Compatibility ====<br />
<br />
If the game refuses to launch and throws you into a library installer loop, run the {{ic|Harvest}} executable instead of the {{ic|run_harvest}} script.<br />
<br />
=== Hatoful Boyfriend ===<br />
<br />
==== Japanese text invisible ====<br />
<br />
Install {{pkg|wqy-microhei}} and {{pkg|wqy-microhei-lite}}.<br />
<br />
=== HEARTBEAT ===<br />
<br />
==== If FontConfig Errors on Start ====<br />
<br />
Follow the same process described in [[#CrossCode]].<br />
<br />
=== HuniePop ===<br />
<br />
==== Game crashes upon launch ====<br />
<br />
Install {{pkg|lsb-release}}.<br />
<br />
=== Hyper Light Drifter ===<br />
<br />
==== The controller does not work ====<br />
<br />
[[Install]] {{pkg|lib32-sdl2}} and run the game with {{ic|1=LD_PRELOAD=libSDL2.so}}.<br />
<br />
See the following Steam Community discussions:<br />
<br />
* [https://steamcommunity.com/app/257850/discussions/1/365163686036494421 Controller Issues]<br />
* [https://steamcommunity.com/app/257850/discussions/1/365163686045397160/ Common Bugs + Known Issues]<br />
<br />
It is suggested to run the ''next_update'' branch to get new fixes,<br />
there however currently is a libcurl segfault keeping it from starting without special workarounds.<br />
<br />
==== Missing libcurl.so.4 or version CURL_OPENSSL_3 not found ====<br />
<br />
[[Install]] {{pkg|lib32-libcurl-compat}} and run the game with {{ic|1=LD_PRELOAD=libcurl.so.3}}.<br />
<br />
=== Imperator: Rome ===<br />
<br />
Paradox Launcher freezes or crashes after start.<br />
Set your launch options to: <br />
LD_PRELOAD=/usr/lib/libc.so.6 %command%<br />
<br />
=== The Impossible Game ===<br />
<br />
Dependencies:<br />
<br />
* {{pkg|lib32-sdl2}}<br />
* {{pkg|lib32-sdl2_image}}<br />
<br />
=== The Inner World ===<br />
<br />
Requires {{AUR|java-commons-codec}} for sound support.<br />
<br />
==== Bringing up the inventory or main menu ====<br />
<br />
Hold the tab key.<br />
<br />
===== Cutscenes =====<br />
<br />
The game has cutscenes. It starts directly with a cutscene before you start the actual game in the backyard. To see these cutscenes you need to use Oracle's [[Java]] instead of the OpenJDK.<br />
<br />
Furthermore you need the package {{aur|ffmpeg-compat-55}}.<br />
<br />
There seem to be problems with the Steam overlay. Try to run the game directly with {{ic|''GAME''/TIW_start.sh}}.<br />
<br />
Note that cutscenes open in a new window. So pay attention to that and switch to the new window to enjoy the movies.<br />
<br />
See the [https://steamcommunity.com/app/251430/discussions/0/611701360817206606/#c611701360827509770 Steam Forums] for details.<br />
<br />
=== Insurgency ===<br />
<br />
==== Game does not start ====<br />
<br />
Set the following launch option<br />
LD_PRELOAD='/usr/$LIB/libstdc++.so.6:/usr/$LIB/libgcc_s.so.1:/usr/$LIB/libxcb.so.1:/usr/$LIB/libgpg-error.so' %command%<br />
<br />
=== Interloper ===<br />
<br />
Requires {{pkg|alsa-lib}}.<br />
<br />
==== Game does not start ====<br />
<br />
The game can sometimes segfault due to an incompatibility with the Steam Runtime's {{ic|libasound.so.2}}.<br />
<br />
=== Invisible Apartment ===<br />
<br />
Requires {{pkg|qt5-multimedia}}.<br />
<br />
==== Game does not start ====<br />
<br />
If the game does not run when you launch it via Steam, try to directly run {{ic|./ia1}} in the game directory.<br />
<br />
=== Joe Danger 2: The Movie ===<br />
<br />
Requires {{pkg|lib32-libpulse}}.<br />
<br />
==== Compatibility ====<br />
<br />
Game only worked after obtaining from the [https://www.humblebundle.com/ Humble Bundle] directly and {{pkg|lib32-libpulse}} was installed.<br />
<br />
=== Kerbal Space Program ===<br />
<br />
See [[Kerbal Space Program]].<br />
<br />
=== Killing Floor ===<br />
<br />
==== Cannot change screen resolution ====<br />
<br />
If trying to modify the resolution in-game crashes your desktop environment, edit {{ic|~/.killingfloor/System/KillingFloor.ini}}:<br />
<br />
[WinDrv.WindowsClient]<br />
WindowedViewportX=''width''<br />
WindowedViewportY=''height''<br />
FullscreenViewportX=''width''<br />
FullscreenViewportY=''height''<br />
MenuViewportX=''width''<br />
MenuViewportY=''height''<br />
<br />
[SDLDrv.SDLClient]<br />
WindowedViewportX=''width''<br />
WindowedViewportY=''height''<br />
FullscreenViewportX=''width''<br />
FullscreenViewportY=''height''<br />
MenuViewportX=''width''<br />
MenuViewportY=''height''<br />
<br />
==== Windowed mode ====<br />
<br />
Uncheck fullscreen in the options menu, and press {{ic|Ctrl+g}} to stop mouse capturing.<br />
<br />
==== Stuttering sound ====<br />
<br />
KillingFloor comes with its own OpenAL library {{ic|''GAME''/System/openal.so}}.<br />
<br />
Back it up, [[install]] {{pkg|openal}} or {{pkg|lib32-openal}} (if using a 64bit system).<br />
<br />
Then symlink the installed system library ({{ic|/usr/lib32/libopenal.so.1}} or {{ic|/usr/lib/libopenal.so.1}}) to {{ic|openal.so}}.<br />
<br />
=== Left for Dead 2 ===<br />
<br />
==== Missing Chinese font ====<br />
<br />
L4D2 Requires {{Pkg|wqy-zenhei}}. Or add the following lines to {{ic|~/.config/fontconfig/fonts.conf}}<br />
<br />
<match target="pattern"><br />
<test qual="any" name="family"><br />
<string>WenQuanYi Zen Hei</string><br />
</test><br />
<edit name="family" mode="assign" binding="same"><br />
<string>Source Han Sans CN</string><br />
</edit><br />
</match><br />
<br />
=== Lethal League ===<br />
<br />
Requires {{Pkg|lib32-glew1.10}}.<br />
<br />
=== Life is Strange ===<br />
<br />
Requires {{Pkg|sdl2_image}} {{Pkg|librtmp0}} {{Pkg|libidn11}} {{AUR|gconf}}.<br />
<br />
=== Little Racers STREET ===<br />
<br />
Install {{Pkg|sdl2_mixer}}.<br />
<br />
Move/backup {{ic|''GAME''/lib64/libSDL2_mixer-2.0.so.0}}.<br />
<br />
Symlink {{ic|/usr/lib/libSDL2_mixer-2.0.so.0}} to {{ic|''GAME''/lib64/libSDL2_mixer-2.0.so.0}}.<br />
<br />
=== The Long Dark ===<br />
<br />
==== Game does not start ====<br />
<br />
The 64-bit version fails to start. Either use the 32-bit version {{ic|tld.x86}} in the game directory or start the 64-bit version like so:<br />
<br />
LD_PRELOAD=~/.steam/root/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0 ./tld.x86_64<br />
<br />
==== Game starts, but some overlay text is missing and cutscenes shows black screen ====<br />
<br />
In addition to the command above, add the following to the Steam launch command:<br />
<br />
-screen-fullscreen 0 -screen-width WIDTH_PIXELS -screen-height HEIGHT_PIXELS<br />
<br />
For example, if you have a screen resolution of 1280x720 and are launching the x64 version from the terminal (within the directory which contains the binaries), the full command would be:<br />
<br />
LD_PRELOAD=~/.steam/root/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0 ./tld.x86_64 -screen-fullscreen 0 -screen-width 1280 -screen-height 720<br />
<br />
and from Steam, the complete game [[launch option]]s would be:<br />
<br />
LD_PRELOAD=~/.steam/root/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0 %command% -screen-fullscreen 0 -screen-width 1280 -screen-height 720<br />
<br />
==== Cutscenes are still black ====<br />
<br />
Turn off Vertical Sync in the Display options, and/or set POST FX to Low in the Quality options, and/or turn global Quality options down a notch.<br />
<br />
==== Cursor disappears ====<br />
<br />
Go to Options > Controls, and set mouse locking to unlocked.<br />
<br />
The options is visible only if you are navigating using your (invisible) mouse. It will not show up when navigating with a controller.<br />
One solution is to go to Options -> Controls with a controller before switching to the mouse and trying to blindly it the setting.<br />
<br />
=== Grand Theft Auto V ===<br />
<br />
==== Game crashes in Online ====<br />
<br />
If you experience crashes in GTA Online (e.g. when creating a new character), set these launch options:<br />
<br />
PROTON_NO_ESYNC=1 WINEDLLOVERRIDES=winedbg.exe=d %command%<br />
<br />
=== Graphical Issues using a NVIDIA GPU ===<br />
<br />
Try launch options: -force-glcore42 -force-clamped<br />
<br />
=== Magicka 2 ===<br />
<br />
==== Indefinitely stuck at start ====<br />
<br />
The game does not start if the output of the command "ip -s link" is longer than 4096 characters. That is because, in the function bitsquid::network_info(char*), where they query the networking information, they do not handle that case correctly.<br />
See [https://i.imgur.com/AOTLoTY.png this picture] for reference.<br />
It was reported to upstream (Pieces Interactive) but Magicka 2 does not seem to be maintained anymore.<br />
<br />
A dirty fix is to wrap your ip binary, as such:<br />
<br />
{{bc|<br />
#!/bin/bash<br />
<nowiki>if [[ $@ == "-s link" ]]; then</nowiki><br />
echo "<paste a smaller subset of the normal output>"<br />
else<br />
/path/to/your/real/ip "$@"<br />
fi<br />
}}<br />
<br />
=== Mark of the Ninja ===<br />
<br />
==== Bad sound ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
=== Metro: Last Light ===<br />
<br />
The game does not allow you to change its resolution on a multi-monitor setup on GNOME with the AMD Catalyst drivers. A temporary workaround is to disable the side monitors.<br />
Jason over at [https://unencumberedbyfacts.com/2013/11/20/multiple-monitor-gaming-on-linux/ unencumbered by facts] managed to get it working with his multi-monitor setup using a single display server, he however is using Nvidia.<br />
<br />
=== Metro: 2033 Redux ===<br />
<br />
==== No sound ====<br />
<br />
Install {{Pkg|pulseaudio-alsa}}<br />
<br />
==== No image ====<br />
<br />
Try setting {{ic|r_fullscreen off}} in {{ic|~/.local/share/Steam/steamapps/common/Metro 2033 Redux/user.cfg}}.<br />
<br />
=== Middle-earth: Shadow of Mordor ===<br />
<br />
==== Floating heads ====<br />
<br />
Run the game with {{ic|1=__GL_ShaderPortabilityWarnings=0}}.<br />
<br />
=== Mount & Blade: Warband ===<br />
<br />
==== Segmentation fault (core dumped) with wayland ====<br />
<br />
Use [[Xorg]] instead.<br />
<br />
==== DLC Chooser ====<br />
<br />
Requires {{aur|lib32-nas}}.<br />
<br />
==== Crash on startup ====<br />
<br />
Set launch options to: <br />
LD_LIBRARY_PATH="." %command%<br />
<br />
=== Move or Die ===<br />
<br />
==== No Sound ====<br />
<br />
Install {{pkg|lib32-libpulse}}.<br />
<br />
=== Multiwinia ===<br />
<br />
Requires {{pkg|lib32-openal}}.<br />
<br />
==== Crash on startup ====<br />
<br />
If Multiwinia crashes on startup on X64 systems, force launching the 32-bit executable by replacing {{ic|''GAME''/run_steam.sh}} with the following script:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
./multiwinia.bin.x86<br />
}}<br />
<br />
See [https://steamcommunity.com/app/1530/discussions/0/864969481950542663/#c558746995160431396].<br />
<br />
=== Natural Selection 2 ===<br />
<br />
{{Pkg|sndio}} is required, furthermore, you must also execute<br />
$ ln -s /usr/lib/libsndio.so x64/libsndio.so.6.1<br />
within the root of the NS2 directory.<br />
This is because NS2 uses an older outdated version of sndio, but it is still compatible with the new version, thankfully.<br />
<br />
For a more minimal solution, one can attempt to set the audio driver used through the environment variable {{ic|SDL_AUDIODRIVER}}. For example, {{ic|1=SDL_AUDIODRIVER=sndio}} or {{ic|1=SDL_AUDIODRIVER=alsa}}.<br />
<br />
The environment variable {{ic|SDL_VIDEODRIVER}} must not be set to {{ic|wayland}}.<br />
Try setting {{ic|SDL_VIDEODRIVER}} to {{ic|x11}} if it still does not work.<br />
<br />
=== No Man's Sky ===<br />
<br />
==== Black screen at start ====<br />
<br />
Edit {{ic|~/Steam/SteamApps/common/No Man's Sky/Binaries/SETTINGS/TKGRAPHICSSETTINGS.MXML}} and set {{ic|FullScreen}} to {{ic|false}} and {{ic|Borderless}} to {{ic|true}}.<br />
<br />
==== White screen at start ====<br />
<br />
If you get a white screen, it may seem like the game has froze, but it has not. Hold down {{ic|e}} to continue.<br />
<br />
=== Nuclear Throne ===<br />
<br />
==== Missing libcurl.so.4 or version CURL_OPENSSL_3 not found ====<br />
<br />
[[Install]] {{pkg|lib32-libcurl-compat}} and run the game with {{ic|1=LD_PRELOAD=libcurl.so.3}}.<br />
<br />
=== OneShot ===<br />
<br />
==== Game fails to start ====<br />
<br />
This problem occurs because the game use outdated libraries. Go to the game directory and remove libdrm.so.2, libGLdispatch.so.0, libstdc++.so.6 and librt.so.1. Those files usually have an equivalent already installed on the system.<br />
<br />
==== File _______ will not run ====<br />
<br />
The executable _______ may fail when run from the Documents folder. It also exists in the game directory and will run from there.<br />
<br />
=== Oxygen Not Included ===<br />
<br />
==== World generation hangs ====<br />
<br />
This problem occurs with locales that use comas instead of dots to separate decimals.<br />
<br />
Set launch options in steam to {{ic|1=LANG=C %command%}}.[https://steamcommunity.com/app/457140/discussions/3/1488866180617243731/#c1488866813753688864]<br />
<br />
=== Penumbra: Overture ===<br />
<br />
Dependencies:<br />
<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libvorbis}}<br />
* {{pkg|lib32-libxft}}<br />
* {{pkg|lib32-openal}}<br />
* {{pkg|lib32-sdl_image}}<br />
* {{pkg|lib32-sdl_ttf}}<br />
<br />
==== Windowed mode ====<br />
<br />
There is no in-game option to change to the windowed mode, you will have to edit {{ic|~/.frictionalgames/Penumbra/Overture/settings.cfg}} to activate it.<br />
<br />
Find {{ic|FullScreen&#61;"true"}} and change it to {{ic|FullScreen&#61;"false"}}, after this the game should start in windowed mode.<br />
<br />
=== Portal 2 ===<br />
<br />
==== Game does not start ====<br />
<br />
Several OpenGL-related errors (such as {{ic|PROBLEM: You appear to have OpenGL 1.4.0, but we need at least 2.0.0!}} or {{ic|libGL error: driver pointer missing}}) are caused by Portal&nbsp;2 bundling an old libstdc++ file. This error is especially common with open source Radeon drivers ({{ic|radeonsi}}).<br />
<br />
A problem with libstdc can be fixed by running the game with {{ic|1=LD_PRELOAD='/usr/$LIB/libstdc++.so.6'}}.<br />
<br />
==== Resolution too low ====<br />
<br />
When the game starts with a resolution so low that you cannot reach the game settings,<br />
run the game in windowed mode using the {{ic|-windowed}} flag.<br />
<br />
==== Missing non Latin font ====<br />
<br />
The phenomenon is no menu in Portal. Portal and Portal2 use Helvetica, add the following lines to {{ic|~/.config/fontconfig/fonts.conf}}:<br />
<br />
<match target="pattern"><br />
<test qual="any" name="family"><br />
<string>Helvetica</string><br />
</test><br />
<edit name="family" mode="assign" binding="same"><br />
<string>Source Han Sans CN</string><br />
</edit><br />
</match><br />
<br />
You can replace "Source Han Sans CN" by your favoriate and existing font.<br />
<br />
=== Prison Architect ===<br />
<br />
==== ALSA error when using PulseAudio ====<br />
<br />
The error:<br />
<br />
{{ic|ALSA lib pcm_dmix.c:1018:(snd_pcm_dmix_open) unable to open slave}}<br />
<br />
was resolved by installing:<br />
<br />
* {{pkg|pulseaudio-alsa}}<br />
* {{pkg|lib32-libpulse}}<br />
<br />
per [[PulseAudio#ALSA]].<br />
<br />
Alternatively, if running the game through Steam, you can force the game to be ran through proton, and that can resolve other audio errors.<br />
<br />
You can do this by opening the game's properties through steam, and under "general" tick the "Force the use of a specific Steam Play comparability tool", and then select a proton version from the dropdown below<br />
<br />
==== Game only starting in safe mode ====<br />
<br />
If the game does not start, but steam thinks it is running, probably the Paradox launcher has problems running properly.<br><br />
If this is the case, you will find some processes running in background:<br />
<br />
{{ic|<nowiki> ps -ef|grep paradoxlauncher </nowiki>}}<br />
<br />
Kill them all, then modify the game startup options as follows:<br />
<br />
{{ic|1= LD_PRELOAD=/usr/lib64/libc.so %command% }}<br />
<br />
Eventually, if the above option has not worked, an option to skip it:<br />
<br />
{{ic|./PrisonArchitect %command% }}<br />
<br />
Note: even if we are using another executable to start the game, %command% has to be added at the end of the command to trick Steam.<br />
<br />
=== Project Zomboid ===<br />
<br />
Requires {{pkg|jre7-openjdk}}.<br />
<br />
==== No sound ====<br />
<br />
Prepend {{ic|/usr/lib}} to {{ic|LD_LIBRARY_PATH}}.<br />
<br />
In the game, go to the options and set all audio to the proper volume.<br />
<br />
=== Pyre ===<br />
<br />
==== Game does not start ====<br />
<br />
Remove {{ic|''GAME''/lib64/libSDL2-2.0.so.0}}.<br />
<br />
If this does not work, downgrade sdl2.<br />
<br />
$ pacman -U https://archive.archlinux.org/packages/s/sdl2/sdl2-2.0.6-2-x86_64.pkg.tar.xz<br />
<br />
Then add sdl2 to IgnorePkg in {{ic|/etc/pacman.conf}}.<br />
<br />
{{ic|1=IgnorePkg = sdl2}}<br />
<br />
=== Redshirt ===<br />
<br />
Requires {{pkg|lib32-libpulse}} if you use PulseAudio.<br />
<br />
=== Revenge of the Titans ===<br />
<br />
Requires {{pkg|libxtst}} and {{pkg|lib32-libxtst}}.<br />
<br />
=== Rise of the Tomb Raider ===<br />
<br />
Run in an X session.<br />
<br />
=== Risk of Rain ===<br />
<br />
Requires {{pkg|lib32-libcurl-compat}}.<br />
Refer to [[#Missing libcurl.so.4 or version CURL_OPENSSL_3 not found]].<br />
<br />
=== Rock Boshers DX: Directors Cut ===<br />
<br />
Requires {{Pkg|lib32-libcaca}}.<br />
<br />
=== Saints Row: The Third ===<br />
<br />
==== Impossible to save custom display settings ====<br />
<br />
Although game settings menu allows to choose custom display settings, the game may have problems saving them.<br />
<br />
In such case, adjust these settings manually in the game's {{ic|display.ini}} file at:<br />
<br />
"${HOME}/.local/share/Steam/steamapps/common/Saints Row the Third/display.ini"<br />
<br />
The comments in this file explain well all the settings and acceptable values.<br />
<br />
==== Incorrect screen resolution in game ====<br />
<br />
This can occur when game is launched in a multi-head environment, with some monitors rotated, etc., so the game detects available screen resolutions incorrectly.<br />
<br />
In such case, adjust {{ic|1=ResolutionWidth}} and {{ic|1=ResolutionHeight}} options in the {{ic|display.ini}} file. Also, one must set option {{ic|1=VerifyResolution = false}}.<br />
<br />
=== Saints Row IV ===<br />
<br />
==== Game fails to launch after update to new Nvidia drivers ====<br />
<br />
{{Accuracy|General settings not specific to this game}}<br />
<br />
Run the game with {{ic|/usr/lib32/libGLX_nvidia.so}} appended to the {{ic|LD_PRELOAD}}.<br />
<br />
==== Game causes GPU lockup with mesa drivers ====<br />
<br />
Saints Rows IV can cause a GPU lockup when trying to play on certain AMD<br />
hardware using open source drivers: [https://bugs.freedesktop.org/show_bug.cgi?id=93475 Bug 93475].<br />
<br />
A workaround is to run the game with {{ic|1=R600_DEBUG=nosb}}.<br />
<br />
=== Serious Sam 3: BFE ===<br />
<br />
==== No audio ====<br />
<br />
Try running:<br />
<br />
# mkdir -p /usr/lib/i386-linux-gnu/alsa-lib/<br />
# ln -s /usr/lib32/alsa-lib/libasound_module_pcm_pulse.so /usr/lib/i386-linux-gnu/alsa-lib/<br />
<br />
If that does not work, try tweaking {{ic|~/.alsoftrc}} as proposed by the [https://steamcommunity.com/app/221410/discussions/3/846940248238406974/ Steam community] (Serious Sam 3: BFE uses OpenAL to output sound). If you are not using Pulse Audio, you may want to write the following configuration:<br />
<br />
{{hc|~/.alsoftrc|<nowiki><br />
[general]<br />
drivers = alsa<br />
[alsa]<br />
device = default<br />
capture = default<br />
mmap = true<br />
</nowiki>}}<br />
<br />
=== SJ-19 Learns to Love ===<br />
<br />
If the game crashes at startup with this error in Steam's output:<br />
<br />
/home/username/.local/share/Steam/steamapps/common/SJ-19 Learns To Love/sj-19-linux/sj-19-learns-to-love.x86_64: error while loading shared libraries: libsteam_api.so: cannot open shared object file: No such file or directory<br />
<br />
Right click the game in steam, select Properties, and set this in Launch Options:<br />
<br />
LD_LIBRARY_PATH=./sj-19-linux %command%<br />
<br />
=== Slay the Spire ===<br />
<br />
If the game does not start or crashes at startup, install {{pkg|xorg-xrandr}}.<br />
<br />
If the game does not move sink input, you can edit the following file to allow sink moves:<br />
<br />
{{hc|~/.alsoftrc|<nowiki><br />
[pulse]<br />
allow-moves=yes<br />
</nowiki>}}<br />
<br />
=== Stick Fight: The Game ===<br />
If the game does not launch, try appending <nowiki>PROTON_USE_WINED3D=1 %command%</nowiki> to force using WINE direct3D.<br />
To do this you must have {{pkg|wine}} installed<br />
<br />
=== Songbringer ===<br />
<br />
==== Launch error with Wayland ====<br />
<br />
Install {{pkg|glfw-x11}} and run the game with {{ic|1=LD_PRELOAD=/usr/lib/libglfw.so.3}}.<br />
<br />
=== Space Pirates and Zombies ===<br />
<br />
Requires {{pkg|lib32-openal}}.<br />
<br />
==== No audio ====<br />
<br />
Try running:<br />
<br />
# mkdir -p /usr/lib/i386-linux-gnu/alsa-lib/<br />
# ln -s /usr/lib32/alsa-lib/libasound_module_pcm_pulse.so /usr/lib/i386-linux-gnu/alsa-lib/<br />
<br />
If that does not work, try tweaking {{ic|~/.alsoftrc}} as proposed by the Steam community (Serious Sam 3: BFE uses OpenAL to output sound). If you are not using Pulse Audio, you may want to write the following configuration:<br />
<br />
{{hc|~/.alsoftrc|<nowiki><br />
[general]<br />
drivers = alsa<br />
[alsa]<br />
device = default<br />
capture = default<br />
mmap = true<br />
</nowiki>}}<br />
<br />
=== Spacechem ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|lib32-sdl_mixer}}<br />
* {{pkg|lib32-sdl_image}}<br />
* {{pkg|lib32-sqlite}}<br />
<br />
==== Game crash ====<br />
<br />
The shipped x86 version of Spacechem does not work on x64 with the game's own libSDL* files, and crashes with some strange output.<br />
<br />
To solve this just remove the three files {{ic|libSDL-1.2.so.0}}, {{ic|libSDL_image-1.2.so.0}}, {{ic|libSDL_mixer-1.2.so.0}} from the game directory.<br />
<br />
=== Splice ===<br />
<br />
Requires {{pkg|glu}}.<br />
<br />
=== The Stanley Parable ===<br />
<br />
==== Game will not start ====<br />
<br />
As discussed in the Steam store page, remove {{ic|bin/libstdc++.so.6}} from the game folder.<br />
<br />
=== Shadow Tactics: Blades of the Shogun ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|lib32-libstdc++5}}<br />
* {{pkg|lib32-libxcursor}}<br />
* {{pkg|lib32-libxrandr}}<br />
<br />
=== Shadows of Adam ===<br />
<br />
==== Old Pango Version Dependency ====<br />
<br />
Build [https://github.com/archlinux/svntogit-packages/blob/3884efafe7de661e3aa2ef5467991648919fea74/trunk/PKGBUILD pango 1.27.1] and copy the libpango* libraries into the game directory as recommended [https://steamcommunity.com/app/506510/discussions/0/135510393195664956/?ctp=16#c2527030866868228210 here].<br />
<br />
=== Stardew Valley ===<br />
<br />
==== Unable to move or input text ====<br />
<br />
When in game, you are stuck in your bed as you cannot move your character or you cannot enter text into the input fields when starting a new game. This is a bug with the SDL2 lib bundled with the game.<br />
<br />
Install {{pkg|sdl2}}.<br />
<br />
Modify this config line:<br />
{{hc|~/.steam/steam/steamapps/common/Stardew\ Valley/MonoGame.Framework.dll.config|<nowiki><br />
<dllmap dll="SDL2.dll" os="linux" cpu="x86-64" target="./lib64/libSDL2-2.0.so.0"/><br />
</nowiki>}}<br />
<br />
To this (the period is removed at the beginning of target):<br />
{{hc|~/.steam/steam/steamapps/common/Stardew\ Valley/MonoGame.Framework.dll.config|<nowiki><br />
<dllmap dll="SDL2.dll" os="linux" cpu="x86-64" target="/lib64/libSDL2-2.0.so.0"/><br />
</nowiki>}}<br />
<br />
=== Steel Storm: Burning Retribution ===<br />
<br />
==== Start with black screen ====<br />
<br />
The game by default tries to launch in fullscreen mode with a resolution of 1024x768,<br />
which does not work on some devices (for example the Samsung Series9 laptop with Intel hd4000 video).<br />
<br />
Run the game in windowed mode by using the {{ic|-window}} flag. Then change the resolution in-game.<br />
<br />
=== Stellaris ===<br />
<br />
==== No window opening, only sound ====<br />
<br />
Happens with some AMD GPU and mesa combination, set multi_sampling=0 in ~/.local/share/Paradox\ Interactive/Stellaris/settings.txt.<br />
<br />
On some window managers (eg Xmonad) you should set fullScreen=no.<br />
<br />
==== Immediate crash to desktop ====<br />
<br />
It seems that Stellaris requires a 32bit libnss_sss.so.2 to operate. You can confirm if this is your problem by running <br />
# strace ~/.local/share/Steam/steamapps/common/Stellaris/stellaris 2>&1 | grep sss <br />
and seeing if you get output like <br />
# openat(AT_FDCWD, "/usr/lib32/tls/i686/sse2/libnss_sss.so.2", O_RDONLY|O_LARGEFILE|O_CLOEXEC) = -1 ENOENT (No such file or directory)<br />
<br />
If this is indeed your problem, download the libnss-sss package from Ubuntu's repository [https://packages.ubuntu.com/bionic/i386/libnss-sss/download], extract the libnss_sss.so.2 from the downloaded package, and place it at ~/.local/share/Steam/steamapps/common/Stellaris. The game should now load properly.<br />
<br />
=== Stephen's Sausage Roll ===<br />
<br />
==== No sound ====<br />
<br />
If using [[Steam/Troubleshooting#Steam native runtime|native libraries]] and {{pkg|libpulse}} is installed, Unity may try to use that library for sound and fail.<br />
To test if this is the problem, try removing {{pkg|libpulse}} or renaming the package files that are named {{ic|libpulse-simple*}}. To see which {{pkg|libpulse}} files are relevant, run:<br />
<br />
{{hc|$ pacman -Qql libpulse <nowiki>|</nowiki> grep /usr/lib/libpulse-simple|<br />
/usr/lib/libpulse-simple.so<br />
/usr/lib/libpulse-simple.so.0<br />
/usr/lib/libpulse-simple.so.0.1.0}}<br />
<br />
If renaming any of those files works for you, you can proceed with the following instructions (revert any renaming you just did). Browse to the game's directory:<br />
<br />
$ cd "$HOME/.steam/root/steamapps/common/Stephen's Sausage Roll"<br />
<br />
And create a sub-directory that we can use to hold 0-byte look-alike library files:<br />
<br />
$ mkdir noload/<br />
<br />
Use {{ic|touch}} to create 0-byte versions of the above files that we want the dynamic linker to skip, e.g.:<br />
<br />
$ touch noload/{libpulse-simple.so,libpulse-simple.so.0,libpulse-simple.so.0.1.0}<br />
<br />
{{Note|Only a 0-byte {{ic|libpulse-simple.so.0}} file may be required.}}<br />
<br />
After you have created these 0-byte files, you can now attempt to run the game binary directly, telling the dynamic linker to use our 0-byte files:<br />
<br />
$ LD_LIBRARY_PATH="noload/:$LD_LIBRARY_PATH" ./Sausage.x86_64<br />
<br />
If everything works up to this point, prepend {{ic|noload/}} to your {{ic|LD_LIBRARY_PATH}}.<br />
<br />
Again, this should work because Steam checks for a {{ic|noload/}} directory relative to the game's directory. The dynamic linker should respect the {{ic|$LD_LIBRARY_PATH}} variable and fail to load the necessary {{pkg|libpulse}} files. The game should then fallback to plain ALSA.<br />
<br />
=== Superbrothers: Sword & Sworcery EP ===<br />
<br />
Dependencies:<br />
<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libpulse}} if you use PulseAudio<br />
<br />
The game bundles an outdated version of libstdc++ which prevents the game from starting. [https://steamcommunity.com/app/204060/discussions/0/364039785161291413] The following can be observed when you run Steam and S&S from the terminal:<br />
<br />
libGL error: unable to load driver: i965_dri.so<br />
libGL error: driver pointer missing<br />
libGL error: failed to load driver: i965<br />
libGL error: unable to load driver: i965_dri.so<br />
libGL error: driver pointer missing<br />
libGL error: failed to load driver: i965<br />
libGL error: unable to load driver: swrast_dri.so<br />
libGL error: failed to load driver: swrast<br />
<br />
To solve this problem remove {{ic|''GAME''/lib/libstdc++.so.6*}}. After that the game will use the libstdc++ from Steam.<br />
<br />
=== System Shock 2 ===<br />
<br />
You get these errors when running it with the native client:<br />
<br />
C:\windows\system32\winedevice.exe: symbol lookup error: /usr/lib32/libX11.so.6: undefined symbol: xcb_wait_for_reply64<br />
C:\windows\system32\wineboot.exe: symbol lookup error: /usr/lib32/libX11.so.6: undefined symbol: xcb_wait_for_reply64<br />
<br />
Just delete or rename the libxcb library it got shipped with:<br />
<br />
mv /mnt/olhdd/steam/steamapps/common/SS2/lib/libxcb.so.1{,.old}<br />
mv /mnt/olhdd/steam/steamapps/common/SS2/lib/libxcb.so.1.1.0{,.old}<br />
<br />
==== Game will not launch ====<br />
<br />
If you encounter the game not launching do the following:<br />
<br />
Cut & Paste libsteam_api.so from the "SS2/Bin" folder within the main steam common folder and transfer it to "SS2" main game folder not the sub folder "SS2/bin"<br />
<br />
After Cut & Paste put LD_PRELOAD='/usr/$LIB/libxcb.so.1' %command% into the Launch options <br />
<br />
Once all of these have been implemented the game should work after hitting play on steam.<br />
<br />
==== Resolution fix ====<br />
<br />
You may encounter some resolution problems with this game on steam not working properly in full screen mode. Do the following:<br />
<br />
Open cam.cfg in the SS2 folder you may have to search for it via the search mode while in the game folder:<br />
<br />
Place game_screen_size 1024 768 or game_screen_size 1920 1080 depending on your resolution & put game_full_screen 1 into bottom of the cam.cfg file. <br />
<br />
Then go to cam_ext.cfg and next to the display setting place a simi-colon prefix next to the use_d3d_display option so it should be like this ;use_d3d_display it should then properly not go off-screen and should stay full screen within the active main screen.<br />
<br />
=== Tabletop Simulator ===<br />
<br />
==== CJK characters not showing in game ====<br />
<br />
Install {{pkg|wqy-microhei}} and {{pkg|wqy-microhei-lite}}.<br />
<br />
=== Team Fortress 2 ===<br />
<br />
Requires {{Pkg|lib32-libpng12}}.<br />
<br />
==== HRTF setup ====<br />
<br />
Assuming HRTF (head-related transfer function) has been properly set up in the operating system, HRTF will not be enabled unless you disable the original processing. To do so, use<br />
<br />
dsp_slow_cpu 1<br />
<br />
For best results, also change the following:<br />
<br />
snd_spatialize_roundrobin 1<br />
dsp_enhance_stereo 0<br />
snd_pitchquality 1<br />
<br />
==== Loading screen freeze ====<br />
<br />
If you are a non-English (speaking) user, you have to enable "en_US.UTF-8" in the locale.gen! Generate a new locale after that.<br />
<br />
==== No audio ====<br />
<br />
It happens if there is no PulseAudio in your system.<br />
If you want to use [[ALSA]], you need to launch Steam or the game directly with {{ic|1=SDL_AUDIODRIVER=alsa}}<br />
(From [https://steamcommunity.com/app/221410/discussions/0/882966056462819091/#c882966056470753683 SteamCommunity]).<br />
<br />
If it still does not work, you may also need to set the environment variable AUDIODEV. For instance {{ic|1=AUDIODEV=Live}}. Use {{ic|aplay -l}} to list the available sound cards.<br />
<br />
==== Slow loading textures ====<br />
<br />
If you are using Chris' FPS Configs or any other FPS config, you may have set {{ic|mat_picmip}} to {{ic|2}}. This spawns multiple threads for texture loading, which may cause more jittering and lag on Linux, especially on alternative kernels. Try setting it to {{ic|-1}}, the default.<br />
<br />
==== "Invalid color format" Error at loading screen on integrated Intel Atom/BayTrail HD Graphics ====<br />
<br />
Add the following to the game startup options:<br />
{{ic| -force_vendor_id 0x10DE -force_device_id 0x1180 }}<br />
<br />
These options deceive the game engine that we are having a Nvidia GPU, not Intel/AMD.<br />
<br />
=== Terraria ===<br />
<br />
See the KNOWN ISSUES & WORKAROUNDS section of the [https://forums.terraria.org/index.php?threads/terraria-1-3-0-8-can-mac-linux-come-out-play.30287/ release announcement].<br />
<br />
==== Input Issues ====<br />
<br />
The symptoms of this problem are: When moving after standing still, your character seems to vary their speed, if wearing running boots they do not activate. When jumping with an item for double jumping sometimes you double jump even if you just jumped once. Going up/down ropes seems slow/choppy.<br />
<br />
The solution is to preload the system SDL2 libraries: {{ic|1=LD_PRELOAD='/usr/$LIB/libSDL2-2.0.so:/usr/lib32/libSDL2-2.0.so' }} For more information: [https://forums.terraria.org/index.php?threads/keyboard-input-bug-involving-linux.56763/page-2#post-1533051 Terraria Forums]{{Dead link|2021|05|17|status=403}}<br />
<br />
=== This War of Mine ===<br />
<br />
==== Game does not start ====<br />
<br />
This happens because of an incompatibility with the newer version of {{ic|lib32-curl}}. To fix the problem , set your [[launch option]]s to:<br />
LD_PRELOAD=./libcurl.so.4 %command%<br />
<br />
==== Sound glitches with Steam native ====<br />
<br />
The bundled {{ic|libOpenAL}} might not work correctly, try symlinking {{ic|/usr/lib32/libopenal.so}} to {{ic|''GAME''/libOpenAL.so}}.<br />
<br />
=== Ticket to Ride ===<br />
<br />
Dependencies:<br />
<br />
* {{AUR|lib32-gstreamer0.10-base}}<br />
* {{AUR|lib32-pangox-compat}}<br />
<br />
As lib32-gstreamer0.10-base is quite hard to build you can use [[Unofficial_user_repositories#alucryd-multilib|alucryd-multilib]] repo for this package<br />
<br />
=== The Tiny Bang Story ===<br />
<br />
==== Missing libGLEW.so.1.6 ====<br />
<br />
# ln -s /usr/lib32/libGLEW.so.1.10.0 /usr/lib32/libGLEW.so.1.6<br />
<br />
=== Tomb Raider (2013) ===<br />
<br />
==== Game immediately closes when running with steam-native ====<br />
<br />
Tomb Raider has a very heavy amount of dependency on the Steam runtime, the easiest solution is to just run it using the runtime.<br />
<br />
==== Steam Controller not working in-game ====<br />
<br />
If your Steam Controller is correctly recognized and paired but still not working in-game try the following:<br />
<br />
* In Steam, non Big Screen, go to ''Settings > Account > Beta participation > Change...'' and in the dropdown select box select Steam Beta Update<br />
* Restart Steam<br />
* Go to Big Screen and start Tomb Raider<br />
<br />
Correctly recognized means you can control the desktop mouse and Steam in Big Picture mode and the controller is shown in the Big Picture settings.<br />
<br />
==== Failed to Initialize Direct3D ====<br />
<br />
This can happen when switching monitors.<br />
<br />
You need to manually edit the preferences file (found in ~/.local/share/feral-interactive/Tomb Raider/) and change the ExclusiveFullscreen option to 0. After this you should be able to successfully start the game (after which you may exit and revert that option to a 1 to restore fullscreen).<br />
<br />
==== Stuck at the start menu ====<br />
<br />
Tomb Raider for Linux will not start if there are any active VPNs that use TUN devices. This is because it makes incorrect assumptions about the return value of {{ic|getifaddrs()}}. The only reason it calls {{ic|getifaddrs()}} is to get the MAC address for a Version 1 UUID, and fall back to a different algorithm if {{ic|getifaddrs()}} returns no interfaces at all.<br />
<br />
One optional solution for such a situation is listed down below, which fixes assumptions made by Tomb Raiders about the output of {{ic|getifaddrs()}} (see [https://github.com/PinkPandaKatie/tomb_raider_vpn_fix/releases tomb_raider_vpn_fix/releases] for the original code):<br />
<br />
{{bc|1=<br />
#include <stdio.h><br />
#include <errno.h><br />
#include <ifaddrs.h><br />
<br />
int getifaddrs(struct ifaddrs **ifap) {<br />
fprintf(stderr, "\n\n\n---------------- dummied out getifaddrs()!\n\n\n");<br />
*ifap = NULL;<br />
return 0;<br />
}<br />
<br />
void freeifaddrs(struct ifaddrs *ifap) {<br />
/* do nothing */<br />
}<br />
}}<br />
<br />
Compile it using<br />
<br />
$ gcc -m32 -fPIC -shared ''file_name''.c -o ''file_name''.so -ldl -Wall<br />
<br />
Then use the following launch option:<br />
<br />
env LD_PRELOAD=$LD_PRELOAD:''path/to/file_name''.so %command%<br />
<br />
=== Torchlight 2 ===<br />
<br />
==== Libfreetype/libfontconfig Incompatibility ====<br />
<br />
If you are experiencing issues with launching games such as Torchlight 2 or Civilization IV, it could be due to using a newer libfontconfig than the game currently supports.<br />
<br />
Right click the game in Steam, and set the following as its launch option:<br />
<br />
LD_PRELOAD=/usr/lib/libfreetype.so.6 %command%<br />
<br />
then attempt launching the game. <br />
<br />
Alternately, re-naming or deleting these 2 files will force it to use your system's libraries:<br />
<br />
Torchlight 2/game/lib/libfreetype.so.6<br />
Torchlight 2/game/lib64/libfreetype.so.6<br />
<br />
==== Locale incompatibility ====<br />
<br />
Some users report that Torchlight 2 does not work if you do not have en_US.UTF8 in your locale. <br />
<br />
Double check you have generated the locale needed in [[Steam#Installation|Steam Installation Requirements]].<br />
<br />
=== Tower Unite ===<br />
<br />
==== Graphical Glitches ====<br />
<br />
This is a known issue, and it occurs because the shaders had not been ported to Linux yet by the developers.<br />
To minimize glitches and make the game playable add {{ic|-opengl4}} to your [[launch option]]s,<br />
set Ocean Quality to "Potato" and Effects Quality to "Low" in the game settings.<br />
<br />
=== Towns / Towns Demo ===<br />
<br />
Requires [[Java]].<br />
<br />
=== Transistor ===<br />
<br />
==== Crash on launch / FMOD binding crash / audio issues ====<br />
<br />
Run the game with:<br />
<br />
LD_PRELOAD='/usr/lib/libstdc++.so.6:/usr/lib/libgcc_s.so.1:/usr/lib/libxcb.so.1:/usr/lib/libasound.so.2'<br />
<br />
Otherwise, run the game via shell and set up proper audio device for FMOD, as discussed in [https://steamcommunity.com/app/237930/discussions/2/620695877176333955/].<br />
<br />
Also, check out this thread [https://steamcommunity.com/app/237930/discussions/2/492378265893557247/].<br />
<br />
=== Transmissions: Element 120 ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|lib32-libgcrypt15}}<br />
* {{pkg|lib32-libpng12}}<br />
<br />
==== Troubleshooting ====<br />
<br />
Make sure you have all libraries installed. Above the standard set required by Steam runtime, the game requires few additional ones. The typical error message that indicates that is<br />
<br />
AppFramework : Unable to load module vguimatsurface.so!<br />
<br />
To find missing dependencies go into the game directory and run:<br />
<br />
LD_LIBRARY_PATH=bin ldd bin/vguimatsurface.so<br />
<br />
Look for entries that say ''not found''.<br />
<br />
=== Transport Fever 2 ===<br />
<br />
==== Game will not launch ====<br />
<br />
Rename or delete the following files in game directory (~/.steam/steam/steamapps/common/Transport Fever 2) as discussed in [https://steamcommunity.com/app/1066780/discussions/0/1740010344363244243/]<br />
<br />
* libstdc++.so.6<br />
* libstdc++.so.6.0.25<br />
<br />
=== Trine 2 ===<br />
<br />
Dependencies:<br />
<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libxxf86vm}}<br />
* {{pkg|lib32-openal}}<br />
* {{pkg|xorg-xwininfo}}<br />
* {{pkg|lib32-libdrm}}<br />
<br />
* {{pkg|lib32-libpng12}}<br />
* {{pkg|lib32-libwrap}}<br />
<br />
==== Fullscreen ====<br />
<br />
Game crashes if started in fullscreen mode, but starts in windowed mode. After start the window can be set to fullscreen (borderless window) if your window manager supports this.<br />
[https://steamcommunity.com/app/35720/discussions/0/1735463620079681092/ steam forum]<br />
<br />
==== Colors ====<br />
<br />
If colors are wrong with FOSS drivers (r600g at least), try to run the game in windowed mode, rendering will be corrected. ([https://bugs.freedesktop.org/show_bug.cgi?id=60553 bug report])<br />
<br />
==== Sound ====<br />
<br />
{{Accuracy|General settings not specific to this game}}<br />
<br />
If sound plays choppy, try:<br />
<br />
{{hc|/etc/openal/alsoft.conf|<nowiki><br />
drivers=pulse,alsa<br />
frequency=48000<br />
</nowiki>}}<br />
<br />
==== Resolution ====<br />
<br />
If the game resolution is wrong when using a dual monitor setup and you cannot see the whole window edit {{ic|~/.frozenbyte/Trine2/options.txt}} and change the options {{ic|ForceFullscreenWidth}} and {{ic|ForceFullscreenHeight}} to the resolution of your monitor on which you want to play the game.<br />
<br />
==== Crash on start in libX11.so.6.3.0 ====<br />
<br />
gdb may report a crash in XGetICValues(), probably due to a bug in SDL1.3; fortunately SDL2.0 is compatible with trine 2, so just force it and see if it works by modifying the steam launch options (or by script/commandline if using the drm free version).<br />
<br />
{{bc|<nowiki><br />
LD_PRELOAD="/usr/lib32/libSDL2.so" %command%<br />
</nowiki>}}<br />
<br />
=== Tropico 5 ===<br />
<br />
==== Blank screen with sound only on startup ====<br />
<br />
Run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=4.0 MESA_GLSL_VERSION_OVERRIDE=400}}.<br />
<br />
=== Unbound: Worlds Apart ===<br />
<br />
If your controller doesn't work, try selecting the game in your inventory, click the gear icon on the right,<br />
then Properties, Controller, and select Disable Steam Input in the dropdown.<br />
<br />
=== Unity of Command ===<br />
<br />
Requires {{pkg|lib32-pango}}.<br />
<br />
==== Squares ====<br />
<br />
If squares are shown instead of text, try removing {{ic|''GAME''/bin/libpangoft2-1.0.so.0}}.<br />
<br />
==== No audio ====<br />
<br />
If you get this error:<br />
<br />
ALSA lib dlmisc.c:254:(snd1_dlobj_cache_get) Cannot open shared library /usr/lib/i386-linux-gnu/alsa-lib/libasound_module_pcm_pulse.so<br />
<br />
Try running:<br />
<br />
# mkdir -p /usr/lib/i386-linux-gnu/alsa-lib/<br />
# ln -s /usr/lib32/alsa-lib/libasound_module_pcm_pulse.so /usr/lib/i386-linux-gnu/alsa-lib/<br />
<br />
=== Unity3D ===<br />
<br />
Games based on the Unity3D engine, like ''War For The Overworld'' or ''Pixel Piracy'' may need the package {{pkg|lsb-release}} to understand that they run on Linux and work properly.<br />
<br />
==== Locale settings ====<br />
<br />
Games made in C# often have a problem with some locales (e.g. Russian, German) because developers do not specify locale-agnostic number formatting. This can result in some game screens loading only partially, problems with online features or other bugs.<br />
<br />
To work around this, run the game with {{ic|1=LC_ALL=C}}.<br />
<br />
Affected games: ''FORCED, Gone Home, Ichi, Nimble Quest, Syder Arcade''.<br />
<br />
==== Unity 5 sound problems ====<br />
<br />
The sound system in Unity 5 changed and to be able to play games created with it you must most likely install and run [[PulseAudio]].<br />
<br />
Another solution is to disable the Steam runtime: in the launch options for the game, write this: {{ic|1=LD_LIBRARY_PATH="" %command%}}<br />
<br />
Another solution is to prevent Unity from trying to use pulseaudio using {{AUR|pulsenomore}} package from the [[AUR]]. Once it is installed, use the following as launch options :{{ic|/usr/bin/pulsenomore %command%}}<br />
<br />
Affected games: ''Kerbal Space Program, SUPERHOT, ClusterTruck''<br />
<br />
==== Game launching on wrong monitor in fullscreen mode ====<br />
<br />
Unity games that do not support monitor selection will most likely launch the game on a wrong monitor.<br />
<br />
The problem is that Unity games write the default parameter {{ic|1=<pref name="UnitySelectMonitor" type="int">-1</pref>}} to the game config file.<br />
<br />
This will lead to the game launching on a non-primary monitor.<br />
<br />
When changing to value into {{ic|1=<pref name="UnitySelectMonitor" type="int">'''0'''</pref>}} for the according game, the game will start on the correct (primary) monitor.<br />
<br />
A Unity game config file usually resides in {{ic|~/.config/unity3d/''CompanyName''/''ProductName''/prefs}}.<br />
<br />
Affected games: ''Cities: Skylines, Tabletop Simulator, Assault Android Cactus, Wasteland 2, Tyranny, Beat Cop''.<br />
<br />
Be aware that some games do not support setting that parameter, it will simply be ignored. This is the case for ''Pillars of Eternity'', ''Kentucky Route Zero'', ''Sunless Sea''.<br />
<br />
==== Chinese/Japanese/Korean display bug ====<br />
<br />
Install {{pkg|wqy-microhei}} and {{pkg|wqy-microhei-lite}}. Then<br />
<br />
#fc-cache -fv<br />
<br />
==== Game does not respond ====<br />
<br />
Add the following line to your [[launch option]]s :<br />
<br />
SDL_DYNAMIC_API=/usr/lib/libSDL2-2.0.so %command%<br />
<br />
=== Unrest ===<br />
<br />
Requires {{pkg|fluidsynth}}.<br />
<br />
=== Volgarr the Viking ===<br />
<br />
Delete the {{ic|lib}} directory in the game directory to get rid of the libGL errors.<br />
<br />
=== War Thunder ===<br />
<br />
==== No audio ====<br />
<br />
If there is no audio after launching the game, install {{pkg|pulseaudio-alsa}}.<br />
<br />
==== Blank screen ====<br />
<br />
If having a green or blank screen on startup, run the game with {{ic|1=MESA_GL_VERSION_OVERRIDE=4.1COMPAT}}. [https://forum.warthunder.com/index.php?/topic/267809-linux-potential-workaround-for-mesa-drivers-black-screen/] [http://forum.warthunder.com/index.php?search_term=0030709&app=core&module=search&do=search&fromMainBar=1&search_app=forums%3Aforum%3A920&sort_field=&sort_order=&search_in=posts]{{Dead link|2020|04|03|status=404}}<br />
<br />
steam startup WarThunder need set startup options {{ic|<nowiki>XMODIFIERS="" %command%</nowiki>}}<br />
<br />
=== Warhammer 40,000: Dawn of War II ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|alsa-lib}}<br />
* {{Pkg|librtmp0}}<br />
<br />
The start script does not point to the right direction of {{ic|libasound.so.2}}.<br />
<br />
To fix it open {{ic|''GAME''/DawnOfWar2.sh}} and replace the following lines:<br />
<br />
{{bc|<nowiki>HAS_LSB_RELEASE=$(command -v lsb_release)<br />
if [ -n "${HAS_LSB_RELEASE}" ] && [ "$(lsb_release -c | cut -f2)" = "trusty" ]; then<br />
LD_PRELOAD_ADDITIONS="/usr/lib/x86_64-linux-gnu/libasound.so.2:${LD_PRELOAD_ADDITIONS}"<br />
fi </nowiki>}}<br />
<br />
with:<br />
<br />
{{bc|1=LD_PRELOAD_ADDITIONS="/usr/lib64/libasound.so.2:${LD_PRELOAD_ADDITIONS}"}}<br />
<br />
=== Wasteland 2 ===<br />
<br />
If Wasteland 2 immediately exits when you try to launch it there may not be enough system file descriptors available. To increase the descriptor limit edit '''/etc/security/limits.conf''' and add the line:<br />
<br />
<nowiki>* hard nofile 524288</nowiki><br />
<br />
Then reboot for the new limit to take effect, Wasteland 2 should now launch and this setting might also fix other games.<br />
<br />
=== We Were Here ===<br />
<br />
==== Stuck on black screen or logo on launch ====<br />
<br />
Add {{ic|-screen-fullscreen 0}} to launch options. [https://steamcommunity.com/app/582500/discussions/1/1470840994974091613/]<br />
<br />
=== Worms W.M.D ===<br />
<br />
The game includes several workarounds in the {{ic|Run.sh}} script, however these may not work and it is easy to get the game running without this script.<br />
<br />
First, try running the game directly from its game directory using {{ic|Worms W.M.Dx64}}. If you get a "No such file or directory" error about libcurl-gnutls, install {{pkg|libcurl-gnutls}}. If the game crashes after playing the intro movies, add the Steam Runtime dbus libraries to the game's library directory:<br />
<br />
$ ln -s ~/.steam/steam/ubuntu12_32/steam-runtime/amd64/lib/x86_64-linux-gnu/*dbus* ~/.steam/steam/steamapps/common/WormsWMD/lib<br />
<br />
Now the game should run using the default "Play Worms W.M.D" option. See also Steam community discussions [https://steamcommunity.com/app/327030/discussions/2/133257959065155871/] and [https://steamcommunity.com/app/327030/discussions/1/343785380902286766/].<br />
<br />
On some systems there are terrain bugs where holes in terrain are not rendered properly and worms can fall through terrain unexpectedly. These bugs can make the game unplayable in many situations and there is no known fix for them.<br />
<br />
=== Witcher 2: Assassin of Kings ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|lib32-gnutls}}<br />
* {{Pkg|lib32-libcurl-compat}}<br />
* {{Pkg|lib32-libcurl-gnutls}}<br />
* {{Pkg|lib32-sdl2_image}}<br />
* {{Pkg|lib32-sdl2}}<br />
<br />
==== Game does not start ====<br />
<br />
The game will not start with SDL set to use wayland. You can have only the game run in x11 by adding the following launch options in steam:<br />
<br />
$ SDL_VIDEODRIVER=x11 %command%<br />
<br />
If the game does not run, enable error messages:<br />
<br />
$ LIBGL_DEBUG=verbose ./witcher2<br />
<br />
=== Wizardry 6: Bane of the Cosmic Forge ===<br />
<br />
Requires [[DOSBox]].<br />
<br />
To fix the crash at start, open {{ic|''GAME''/dosbox_linux/launch_wizardry6.sh}} and:<br />
<br />
# comment the line {{ic|1=export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./libs}}<br />
# change the beginning of the line starting with {{ic|exec ./dosbox}} to {{ic|exec dosbox}}<br />
<br />
=== World of Goo ===<br />
<br />
==== Changing resolution ====<br />
<br />
To change the game resolution edit the ''Graphics display'' section in {{ic|''GAME''/properties/config.txt}}. For example:<br />
<br />
<nowiki><!-- Graphics display --></nowiki><br />
<param name="screen_width" value="1680" /><br />
<param name="screen_height" value="1050" /><br />
<param name="color_depth" value="0" /><br />
<param name="fullscreen" value="true" /><br />
<param name="ui_inset" value="10" /><br />
<br />
=== X3: Terran Conflict ===<br />
<br />
==== Game crashes on startup ====<br />
<br />
The game may crash on startup because it is linked to libz version 1.2.9, while the latest version of this library in Arch Linux is higher. The following message in the terminals appears in this case:<br />
./X3TC_config: lib/libz.so.1: version 'ZLIB_1.2.9' not found (required by /usr/lib32/libpng16.so.16<br />
<br />
Renaming or removing lib/libz.so.1 may help.<br />
<br />
=== X Rebirth ===<br />
<br />
==== Game crashes on startup ====<br />
<br />
The game may crash on startup because it is linked to the shadergl function of the game. Do the follow in the .../steamapps/common/X Rebirth/shadergl/shaders/common.fh file.<br />
<br />
--- ./common.fh.orig<br />
+++ ./common.fh<br />
<br />
@@ -574 +574 @@<br />
- /* OUT_COLOR.rgb *= 0.0001; OUT_COLOR.rgb += half3(specstr);/**/ \<br />
+ /* OUT_COLOR.rgb *= 0.0001; OUT_COLOR.rgb += half3(specstr);*/ \<br />
<br />
@@ -622 +622 @@<br />
- /* OUT_COLOR.rgb *= 0.0001; OUT_COLOR.rgb += LightColor.xyz/ 10;/**/ \<br />
+ /* OUT_COLOR.rgb *= 0.0001; OUT_COLOR.rgb += LightColor.xyz/ 10;*/ \<br />
<br />
After this workaround is implemented the game should load as normal.<br />
<br />
=== XCOM ===<br />
<br />
Dependencies:<br />
<br />
* {{Pkg|librtmp0}}<br />
* {{Pkg|sdl2_image}} (required to enable keyboard functionality in-game)<br />
<br />
==== Hangs on startup ====<br />
<br />
If you are running a [[hybrid graphics]] system, try:<br />
<br />
__GL_THREADED_OPTIMIZATIONS=0 primusrun %command%<br />
<br />
==== Graphical glitches on Intel HD ====<br />
<br />
XCOM: Enemy Unknown may not recognize the SDL2 shared libraries shipped with the Steam runtime.<br />
Check if the binary finds all required files and install missing packages if necessary ({{Pkg|sdl2}} and {{Pkg|sdl2_image}}).<br />
<br />
{{bc|ldd binaries/linux/game.x86_64 | grep "not found"}}<br />
<br />
=== XCOM 2 ===<br />
<br />
==== Unable to start with steam native ====<br />
<br />
needs {{ic|libgconf-2.so.4}} which is not avaliable in arch repos, loading it from steams runtime seems to work.<br />
<br />
LD_PRELOAD="$HOME/.local/share/Steam/ubuntu12_32/steam-runtime/usr/lib/x86_64-linux-gnu/libgconf-2.so.4" %command%</div>B6hgas5https://wiki.archlinux.org/index.php?title=SANE&diff=698107SANE2021-10-03T00:19:24Z<p>B6hgas5: /* Slow startup */ add example and show how different commands can be combined to make this decision</p>
<hr />
<div>[[Category:Digital imaging]]<br />
[[es:SANE]]<br />
[[it:SANE]]<br />
[[ja:SANE]]<br />
{{Related articles start}}<br />
{{Related|SANE/Scanner-specific problems}}<br />
{{Related|Scanner Button Daemon}}<br />
{{Related articles end}}<br />
<br />
[http://www.sane-project.org/ SANE] ([[wikipedia:Scanner Access Now Easy|Scanner Access Now Easy]]) provides a library and a command-line tool to use scanners under GNU/Linux.<br />
<br />
Check if your scanner supports [https://github.com/alexpevzner/sane-airscan#compatibility eSCL or WSD]; chances are good if your device is on this [https://support.apple.com/en-us/HT201311#printers Internet Printing Protocoll - IPP] list of devices that support eSCL. If your device has eSCL/WSD support, modern "driverless" scanning is recommended.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|sane-airscan}} package if the scanner is known to work in driverless mode. If your scanner is using USB connection, make sure to also [[install]] the {{Pkg|ipp-usb}} package and [[start/enable]] {{ic|ipp-usb.service}} to allow using IPP protocol over USB connection.<br />
<br />
If not, see [http://www.sane-project.org/sane-supported-devices.html] to check if SANE supports your scanner using a classic driver.<br />
<br />
[[Install]] the {{Pkg|sane}} package to use old driver-based scanning.<br />
<br />
== Verification ==<br />
<br />
Now you can try to see if sane recognizes your scanner.<br />
<br />
$ scanimage -L<br />
<br />
If that fails, run the command again as root to check for permission problems. If that fails as well, check that your scanner is plugged into the computer. You also might have to unplug/plug your scanner for {{ic|/usr/lib/udev/rules.d/65-sane.rules}} to recognize your scanner.<br />
<br />
Now you can see if it actually works<br />
<br />
$ scanimage --format=png --output-file test.png --progress<br />
<br />
If the scanning fails with the message {{ic|scanimage: sane_start: Invalid argument}} you may need to specify the device.<br />
<br />
{{hc|$ scanimage -L|<br />
device `v4l:/dev/video0' is a Noname Video WebCam virtual device<br />
device `pixma:04A91749_247936' is a CANON Canon PIXMA MG5200 multi-function peripheral<br />
}}<br />
<br />
Then you would need to run<br />
<br />
$ scanimage --device "pixma:04A91749_247936" --format=tiff --output-file test.tiff --progress<br />
<br />
Sane provides many special backend options for numerous scanner types. To see what these are for your device:<br />
<br />
$ scanimage -A<br />
<br />
== Installing a scanner driver ==<br />
<br />
Most scanners should work out of the box. If yours does not, see [[SANE/Scanner-specific problems]] for installation instructions.<br />
<br />
=== Firmware ===<br />
<br />
{{Note|This section is only needed if you need to upload firmware to your scanner.}}<br />
<br />
Firmwares usually have the '''{{ic|.bin}}''' extension. <br />
<br />
Firstly you need to put the firmware someplace safe, it is recommended to put it in a subdirectory of {{ic|/usr/share/sane/}}.<br />
<br />
Then you need to tell sane where the firmware is:<br />
<br />
* Find the name of the backend for your scanner from the [http://www.sane-project.org/sane-supported-devices.html sane supported devices list].<br />
* Open the file {{ic|/etc/sane.d/''backend-name''.conf}}.<br />
* Make sure the firmware entry is uncommented and let the file-path point to where you put the firmware file for your scanner. Be sure that members of the group {{ic|scanner}} can access the {{ic|/etc/sane.d/''backend-name''.conf}} file.<br />
<br />
If the backend of your scanner is not part of the sane package (such as {{ic|hpaio.conf}} which is part of {{Pkg|hplip}}), you need to uncomment the relevant entry in {{ic|/etc/sane.d/dll.d}} or in {{ic|/etc/sane.d/dll.conf}}.<br />
<br />
=== Fujitsu fi series ===<br />
<br />
For some of the Fujitsu fi series document scanners, the {{AUR|pfufs}} proprietary driver offers advanced functionality over the already mature SANE default driver, such as control of an optional imprinter for stamping scanned documents or requesting accurate status of the consumables from the host.<br />
<br />
== Install a frontend ==<br />
<br />
Many frontends exist for SANE, a non-exhaustive list of which can be found on the [http://www.sane-project.org/sane-frontends.html sane-project website].<br />
<br />
* {{App|[[Wikipedia:Scanner Access Now Easy#Simple_Scan|Simple Scan]]|Simplified GUI that is intended to be easier to use and better integrated into the [[GNOME]] desktop than XSane. It was initially written for Ubuntu and is maintained by Robert Ancell of Canonical Ltd. for GNU/Linux.|https://gitlab.gnome.org/GNOME/simple-scan|{{Pkg|simple-scan}}}}<br />
* {{App|[[Wikipedia:Skanlite|Skanlite]]|Simple image scanning application that does nothing more than scan and save images, based on the KSane backend.|https://www.kde.org/applications/graphics/skanlite|{{Pkg|skanlite}}}}<br />
* {{App|[[Wikipedia:Scanner Access Now Easy#XSane|XSane]]|Full-featured GTK-based frontend looking a bit old but providing extended functionalities.|http://www.xsane.org/|{{Pkg|xsane}}}}<br />
<br />
Some [[List of applications/Documents#OCR software|OCR software]] are able to scan images using SANE: gImageReader, [[Wikipedia:Scanner Access Now Easy#gscan2pdf|gscan2pdf]], Linux-Intelligent-Ocr-Solution, [[Wikipedia:OCRFeeder|OCRFeeder]], [https://openpaper.work Paperwork].<br />
<br />
{{Note|<br />
* Scanning directly to PDF using XSane in 16bit color depth mode is known to produces [https://bugs.launchpad.net/ubuntu/+source/xsane/+bug/539162 corrupted files] and a note in {{ic|pacman}} output warns so. 8bit mode is known to work.<br />
<br />
{{Accuracy|skanlite does not need to ''handle'' mDNS. As long as [[Avahi#Hostname resolution|mDNS hostname resolution]] is set up correctly and the scanner 's address is specified as {{ic|''hostname''.local}}, it should just work. This looks like a hplip limitation/bug.}}<br />
<br />
* Using a frontend does not mean you do not have to apply some tricks. This is especially true with devices configured via [[mDNS]]. For example, {{ic|skanlite}} needs to have additional info specified on the command line in order to detect a network scanner properly as it cannot handle mDNS. Here is an example with an HP Officejet Pro L7590: {{ic|1=skanlite --device "hpaio:/net/Officejet_Pro_L7500?ip=192.168.0.17"}}.<br />
}}<br />
<br />
== Network scanning ==<br />
<br />
=== Network attached scanners ===<br />
<br />
Many modern scanners will immediately work over the network as long as you have {{Pkg|sane-airscan}} installed.<br />
<br />
==== Scanning over the network with Canon PIXMA or imageCLASS all-in-one printer/scanners ====<br />
<br />
Find out your printer/scanner's IP address, and add it on a new line to {{ic|/etc/sane.d/pixma.conf}} in the format {{ic|bjnp://10.0.0.20}}. For imageCLASS printers you may need to use the format {{ic|mfnp://10.0.0.20}} instead.<br />
<br />
{{Tip|Instead of an IP address, if [[Avahi#Hostname resolution|mDNS resolution is set up]], you can use the [[mDNS]] {{ic|.local}} address. E.g. {{ic|bjnp://''MyPixmaPrinter''.local}}.}}<br />
<br />
Sane should now find your device. For more details refer to {{man|5|sane-pixma}}.<br />
<br />
Alternatively, {{AUR|scangearmp2}} can be used for some Canon PIXMA all-in-one printer/scanners which are not detected over the network.<br />
<br />
See [[SANE/Scanner-specific problems]] for additional information.<br />
<br />
==== Scanning over the network with EPSON WorkForce printer/scanners ====<br />
<br />
Install {{Pkg|imagescan}} and {{AUR|imagescan-plugin-networkscan}}.<br />
<br />
Edit the config file {{ic|/etc/utsushi/utsushi.conf}}. Find the {{ic|[devices]}} section and edit the template for {{ic|dev2}}. Replace the IP address accordingly. You can find the IP address on your printer screen. For example,<br />
<br />
{{bc|1=...<br />
dev2.udi = esci:networkscan://192.168.1.123:1865<br />
dev2.model = WF-2860<br />
dev2.vendor = EPSON<br />
...}}<br />
<br />
Meanwhile, comment out {{ic|epson2}} in {{ic|/etc/sane.d/dll.conf}} as it [https://download.ebz.epson.net/faq/linux/faq_ls_00007.html conflicts with ImageScan]. <br />
<br />
Once this is done you can use any SANE frontend to access this scanner.<br />
<br />
=== Sharing your scanner over a network ===<br />
<br />
You can share your scanner with other hosts on your network who use ''sane'', ''xsane'' or xsane-enabled ''GIMP''. To set up the server, first indicate which hosts on your network are allowed access.<br />
<br />
Change the {{ic|/etc/sane.d/saned.conf}} file to your liking, for example:<br />
<br />
# required<br />
localhost<br />
# allow local subnet<br />
192.168.0.0/24<br />
<br />
If you use [[iptables]], [[Kernel_modules|insert]] the {{ic|nf_conntrack_sane}} module to let the firewall track {{ic|saned}} connections.<br />
<br />
Conntrack helper seems to be disabled by default.[https://home.regit.org/wp-content/uploads/2011/11/secure-conntrack-helpers.html] You can activate it with <br />
<br />
# echo 1 > /proc/sys/net/netfilter/nf_conntrack_helper <br />
<br />
To configure this permanently, set the {{ic|1=nf_conntrack_helper=1}} option for the {{ic|nf_conntrack}} module, see [[Kernel module#Using files in /etc/modprobe.d/]].<br />
<br />
Now [[start/enable]] {{ic|saned.socket}}. Your scanner is now available over the network. For more information, see {{man|8|saned}}.<br />
<br />
{{Note|saned intentionally refuses to share scanners that use the net: backend (which includes some USB scanners). There is a crude patch to allow this in {{Bug|54786}}, but note it may cause problems on some networks. Check output of {{ic|scanimage -L}} on the server to see the scanner url.}}<br />
<br />
=== Accessing your scanner from a remote workstation ===<br />
<br />
{{Note|Some network scanners require a different approach. See [[SANE/Scanner-specific problems]].}}<br />
<br />
You can access your network-enabled scanner from a remote Arch Linux workstation.<br />
<br />
First, specify the server's host name or IP address in the {{ic|/etc/sane.d/net.conf}} file:<br />
<br />
# static IP address<br />
192.168.0.1<br />
# or host name<br />
stratus<br />
<br />
Now test your workstation's connection:<br />
<br />
$ scanimage -L<br />
<br />
The network scanner should now also show up in any [[#Install a frontend|front-end]].<br />
<br />
=== Windows clients ===<br />
<br />
Since the Windows port of SANE seems to be [https://web.archive.org/web/20151207111023/http://www.xsane.org/xsane-download.html unsupported, outdated and difficult to get], you can try [https://sourceforge.net/projects/sanewinds/ SANEWinDS] or [https://sanetwain.ozuzo.net/ SaneTwain] (old).<br />
<br />
== Troubleshooting ==<br />
<br />
:See also: [[SANE/Scanner-specific problems]]<br />
<br />
=== Invalid argument ===<br />
<br />
If you get an "Invalid argument" error with xsane or another sane front-end, this could be caused by one of the following reasons:<br />
<br />
==== Missing firmware file ====<br />
<br />
No firmware file was provided for the used scanner (see [[#Firmware]] for details).<br />
<br />
==== Wrong firmware file permissions ====<br />
<br />
The permissions for the used firmware file are wrong. Correct them using<br />
<br />
# chown root:scanner /usr/share/sane/''SCANNER_MODEL''/''FIRMWARE_FILE''<br />
# chmod ug+r /usr/share/sane/''SCANNER_MODEL''/''FIRMWARE_FILE''<br />
<br />
==== Multiple backends claim scanner ====<br />
<br />
It may happen, that multiple backends support (or pretend to support) your scanner, and sane chooses one that does not do after all (the scanner will not be displayed by {{ic|scanimage -L}} then). This has happened with older Epson scanners and the {{ic|epson2}} resp. {{ic|epson}} backends. In this case, the solution is to comment out the unwanted backend in {{ic|/etc/sane.d/dll.conf}}. In the Epson case, that would be to change<br />
<br />
epson2<br />
#epson<br />
<br />
to <br />
<br />
#epson2<br />
epson<br />
<br />
{{Out of date|1=The ''iscan'' and ''iscan-data'' packages have been dropped from the official repositories [https://lists.archlinux.org/pipermail/arch-commits/2021-June/1012859.html] without moving to the AUR. However, {{AUR|iscan-for-epson-v500-photo}} provides ''iscan'' and ''iscan-data'' (since "iscan[community] is out-of-date and buggy"), so it appears that the [https://aur.archlinux.org/packages/?SeB=n&K=iscan-plugin- AUR PKGBUILDs that depend on iscan and iscan-data] (and others) may be able to use ''iscan-for-epson-v500-photo'' instead. This still needs to be tested though.}}<br />
<br />
It may also be possible that the independent {{Pkg|iscan}}{{Broken package link|package not found}} {{ic|epkowa}} backend interferes with your {{ic|snapscan}} backend (epson scanners). You may get this error right after using the {{ic|scanimage -L}} command. Starting the scanner app (like {{Pkg|xsane}}) twice can also solve the problem. Otherwise check your {{ic|/etc/sane.d/epkowa.conf}} for wrong configurations or remove the {{Pkg|iscan}}{{Broken package link|package not found}} package.<br />
<br />
==== Communication via xHCI not working (older scanner models) ====<br />
<br />
Some older scanner models do not work when connected via an USB3 port. If you experience this issue, try setting the {{ic|1=SANE_USB_WORKAROUND=1}} [[environment variable]] before starting your frontend.[https://lists.alioth.debian.org/pipermail/sane-announce/2017/000036.html][https://salsa.debian.org/debian/sane-backends/-/blob/master/ChangeLog#L2251-2262]<br />
<br />
If that does not work, try one of the following workarounds:<br />
<br />
* Use an USB2 port instead of an USB3 port, if available.<br />
* Disable xHCI via BIOS/EFI. eHCI will consequently be used and communication with the scanner will work. On the downside, USB3 speed can not be reached on any port.<br />
* On (some) intel chipsets the {{ic|setpci}} command can be used to route specific usb ports to either the xHCI or the eHCI controller. See [https://forums.opensuse.org/showthread.php/507627-Suse-13-2-scanner-no-longer-working-on-64-bit-version?p=2714695#post2714695 here] and [https://superuser.com/questions/812022/force-a-single-usb-3-0-port-to-work-as-usb-2-0 here] (scroll down to where it says "setpci") for further information. With this it is possible to toggle single USB ports with a simple shell script.<br />
* Connect the scanner over the network instead if it is supported.<br />
<br />
==== Firewall ====<br />
<br />
When network scanning scanner hangs, then invalid argument error occured.<br />
<br />
saned uses data port range, so you must enable connections to 6566/tcp and data_portrange from /etc/sane.d/saned.conf or use conntrack firewall module for sane to enable data ports as described above.<br />
<br />
=== Slow startup ===<br />
<br />
If you encounter slow startup issue (e.g. {{ic|xsane}} or {{ic|scanimage -L}} does not return results nearly instantly), one of the drivers you do not use may be the culprit.<br />
<br />
You can resolve this by editing {{ic|/etc/sane.d/dll.conf}} and commenting out the scanner drivers you do not use. You can use {{ic|scanimage -L}} to determine which drivers you need:<br />
<br />
$ scanimage -L<br />
device `brother4:net1;dev0' is a Brother DCP-L2550DW<br />
device `v4l:/dev/video0' is a Noname Logitech Webcam C925e virtual device<br />
device `<nowiki>escl:http://192.168.1.2:80'</nowiki> is a Brother DCP-L2550DW series adf,platen scanner<br />
<br />
The parts between the {{ic|`}} and the {{ic|:}} in the output indicate the driver for the device. For example, if only want to use the Brother scanner and not the [[webcam]] or the generic scanner driver, you can comment out everything but the {{ic|brother4}} driver in {{ic|/etc/sane.d/dll.conf}}.<br />
<br />
=== Device busy ===<br />
<br />
{{Accuracy|The user should not need to be in the scanner group (see [[Users and groups#Pre-systemd groups]])}}<br />
<br />
If your USB device is listed with {{ic|scanimage -L}} but launching the test {{ic|1=scanimage pixma:04A9173E_11DAD1 --format=tiff --output-file test.tiff}} always return the 'Device busy' error, you might try to add your username to the scanner group {{ic|usermod -a -G scanner yourusername}} then blacklist the {{ic|usblp}} kernel module by writing {{ic|blacklist usblp}} in {{ic|/etc/modprobe.d/no-usblp.conf}} (it prevents {{ic|usblp}} from loading to support scanning, not needed by xsane and related tools, might also [[CUPS/Troubleshooting#Conflict_with_usblp|conflict with CUPS]]). Reboot to finish. [https://cromwell-intl.com/linux/canon-pixma-printer-scanner.html]<br />
<br />
In addition to this, some Cannon printers return "device busy" if the scan mode is set to "Computer". Setting this to the "Remote Scanner" mode should fix the issue.[https://alioth-lists.debian.net/pipermail/sane-devel/2014-March/032169.html]<br />
<br />
=== Permission problem ===<br />
<br />
With systemd, the {{ic|scanner}} and {{ic|lp}} groups are deprecated. No need to add your user to those groups. See [[Users and groups#Pre-systemd groups]] for detail.<br />
<br />
You can also try to change permissions of usb device but this is not recommended, a better solution is to fix the [[Udev rules]] so that your scanner is recognized.<br />
<br />
First check connected usb devices with {{ic|lsusb}}:<br />
<br />
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 003 Device 003: ID 04d9:1603 Holtek Semiconductor, Inc.<br />
Bus 003 Device 002: ID 04fc:0538 Sunplus Technology Co., Ltd<br />
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 001 Device 006: ID 03f0:2504 Hewlett-Packard<br />
Bus 001 Device 002: ID 046d:0802 Logitech, Inc. Webcam C200<br />
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
<br />
In our example we see the scanner: {{ic|Bus 001 Device 006: ID 03f0:2504 Hewlett-Packard}}. Here {{ic|03f0}} is the ''vendorID'' and {{ic|2504}} is the ''productID''.<br />
<br />
Alternatively, running {{ic|sane-find-scanner}} with root permission will also give you the same ''vendorID'' and ''productID''.<br />
<br />
Now open {{ic|/usr/lib/udev/rules.d/49-sane.rules}} and see if there is there is a line with the ''vendorID'' and ''productID'' of your scanner. If there is not any, create the new file {{ic|/etc/udev/rules.d/49-sane-missing-scanner.rules}}, with the following contents:<br />
<br />
ATTRS{idVendor}=="'''vendorID'''", ATTRS{idProduct}=="'''productID'''", MODE="0664", GROUP="lp", ENV{libsane_matched}="yes"<br />
<br />
Save the file, plug out and back in your scanner and the file permissions should be now correct.<br />
<br />
{{Accuracy|The scanner needs to be added to the right backend file, {{ic|hp4200.conf}} will not work for any scanner.}}<br />
<br />
Another tip, is that you can add your device (scanner) in backend file:<br />
<br />
Add {{ic|usb 0x03f0 0x2504}} to {{ic|/etc/sane.d/hp4200.conf}} so it looks like this:<br />
<br />
#<br />
# Configuration file for the hp4200 backend<br />
#<br />
#<br />
# HP4200<br />
#usb 0x03f0 0x0105<br />
usb 0x03f0 0x2504<br />
<br />
==== Parallel port scanners ====<br />
<br />
All devices attached to a parallel port are assumed to be printers, and are given a {{ic|lp}} group. Either create a [[udev]] rule to mark the relevant parallel port as {{ic|libsane_matched}}, or add your user to the {{ic|lp}} [[user group]]. CUPS also uses the {{ic|lp}} group for read-only access to configuration files, so there are potential security implications to adding users to the {{ic|lp}} group - see [[CUPS#Connection interfaces]] for more information.<br />
<br />
=== avahi-daemon is not mandatory ===<br />
<br />
{{Style|This is configuration, not troubleshooting.}}<br />
<br />
Some scanner applications may require you to start the ''avahi-daemon'' upon startup. This is actually the cause of SANE. If for some reason you do not want to enable the ''avahi-daemon'' service because you use a wired scanner or do not need it because your scanner's driver supports networking already on setup, then comment out the {{ic|net}} backend in the SANE config:<br />
<br />
{{hc|/etc/sane.d/dll.conf|<br />
# The next line enables the network backend; comment it out if you do not<br />
# need to use a remote SANE scanner over the network -- see sane-net(5)<br />
# and saned(8) for details.<br />
#net<br />
}}<br />
<br />
Then restart the {{ic|saned}} daemon.</div>B6hgas5https://wiki.archlinux.org/index.php?title=Graphics_tablet&diff=577342Graphics tablet2019-07-13T03:07:20Z<p>B6hgas5: /* USB-devices */ update path & tell the user to not edit files in /usr/</p>
<hr />
<div>[[Category:Input devices]]<br />
[[ja:Wacom タブレット]]<br />
[[zh-hans:Wacom tablet]]<br />
[[Wikipedia:Wacom (company)|Wacom]] does not officially support Linux. Linux support is provided by the [https://linuxwacom.github.io/ Linux Wacom Project]. Supported devices are listed on the [https://github.com/linuxwacom/input-wacom/wiki/Device-IDs Device IDs] page with a version number in the ''input-wacom'' column.<br />
<br />
== Installation ==<br />
<br />
The Arch Linux [[kernels]] include the [https://github.com/linuxwacom/input-wacom input-wacom] driver.<br />
<br />
Ensure your kernel recognizes your tablet. Connect your tablet via USB or [[Bluetooth]]. It should show up in {{ic|dmesg {{!}} grep -i wacom}} and be listed in {{ic|/proc/bus/input/devices}} (and if you use USB in the {{ic|lsusb}} output). If it does not, your only chance is that your tablet is supported by a more recent driver than the one in your kernel. In that case [[install]] the {{AUR|input-wacom-dkms}} package.<br />
<br />
[[Install]] the [[X]] driver, {{Pkg|xf86-input-wacom}}, and restart X so the new [[udev]] rules take effect.<br />
<br />
The command {{ic|xsetwacom list devices}} should now list some devices. If it does not, see [[#Manual setup]].<br />
<br />
The {{Pkg|kcm-wacomtablet}} package provides a [[KDE]] graphical user interface for tablet configuration and supports tablet-specific profiles and hotplugging.<br />
<br />
Support for the following Wacom tablets is provided via {{AUR|tuhi-git}}:<br />
* Bamboo Spark<br />
* Bamboo Slate<br />
* Intuos Pro Paper<br />
<br />
Consult README for the details of initial configuration. For setups with more than one monitor you'll probably want to fix aspect ratio using {{ic|Coordinate Transformation Matrix}} as described at [https://github.com/linuxwacom/xf86-input-wacom/wiki/Dual-and-Multi-Monitor-Set-Up dual and multimonitor set up].<br />
<br />
== Configuration ==<br />
<br />
The Xorg driver can be temporarily configured with {{ic|xsetwacom}}, see {{man|1|xsetwacom}}. Changes are lost after X server restarts or replugging your tablet.<br />
<br />
List the available devices:<br />
<br />
{{hc|$ xsetwacom list devices|<br />
Wacom Bamboo 16FG 4x5 Finger touch id: 12 type: TOUCH<br />
Wacom Bamboo 16FG 4x5 Finger pad id: 13 type: PAD <br />
Wacom Bamboo 16FG 4x5 Pen stylus id: 17 type: STYLUS <br />
Wacom Bamboo 16FG 4x5 Pen eraser id: 18 type: ERASER<br />
}}<br />
<br />
For the {{ic|get}} and {{ic|set}} commands, devices can be specified by name or id. Scripts should use names because ids can change after X server restarts or replugging.<br />
<br />
=== Permanent configuration ===<br />
<br />
{{Note|Because ''xorg.conf'' lacks options ''xsetwacom'' has and only lets you map buttons to mouse buttons, you may want to [[autostart]] a script with ''xsetwacom'' commands instead of using ''xorg.conf''.}}<br />
<br />
Configuration can be made persistent in [[xorg.conf]] and {{man|5|xorg.conf}}.<br />
<br />
You firstly need to find out your product names:<br />
<br />
{{hc|$ grep "Using input driver 'wacom'" /var/log/Xorg.0.log|<br />
[ 25059.351] (II) Using input driver 'wacom' for 'Wacom Intuos BT M Pen'<br />
[ 25059.409] (II) Using input driver 'wacom' for 'Wacom Intuos BT M Pad'<br />
[ 25059.428] (II) Using input driver 'wacom' for 'Wacom Intuos BT M Pen eraser'<br />
[ 25059.429] (II) Using input driver 'wacom' for 'Wacom Intuos BT M Pen cursor'<br />
}}<br />
<br />
For these product names the sections would be:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/72-wacom-options.conf|<br />
Section "InputClass"<br />
Identifier "WACOM OPTIONS pen"<br />
MatchDriver "wacom"<br />
MatchProduct "Pen"<br />
NoMatchProduct "eraser"<br />
NoMatchProduct "cursor"<br />
EndSection<br />
<br />
Section "InputClass"<br />
Identifier "WACOM OPTIONS pad"<br />
MatchDriver "wacom"<br />
MatchProduct "Pad"<br />
EndSection<br />
<br />
Section "InputClass"<br />
Identifier "WACOM OPTIONS eraser"<br />
MatchDriver "wacom"<br />
MatchProduct "eraser"<br />
EndSection<br />
<br />
Section "InputClass"<br />
Identifier "WACOM OPTIONS cursor"<br />
MatchDriver "wacom"<br />
MatchProduct "cursor"<br />
EndSection<br />
}}<br />
<br />
* The options described in {{man|4|wacom}} can be added to sections.<br />
* The product name needs to contain the {{ic|MatchProduct}} value in order for a section to match. Matching of parent devices requires negative matching.<br />
* The {{ic|Identifier}} can be arbitrary and is printed into the Xorg log when the section matches. Giving your identifiers a common prefix lets you easily [[grep]] for what sections were matched: {{bc|grep "WACOM OPT" /var/log/Xorg.0.log}}<br />
* Configuration changes require a X server restart to take effect.<br />
<br />
{{Note|''xorg.conf'' options can differ from ''xsetwacom'' options.}}<br />
<br />
''xsetwacom'' can try to print all current settings of a device in ''xorg.conf'' format with:<br />
<br />
$ xsetwacom get ''device'' all<br />
<br />
=== Remapping buttons ===<br />
<br />
The X driver lets you remap the buttons on tablets and pens. Buttons are identified by numbers. Tablet buttons start at 1, pen buttons start at 2 (1 is the tip contact event). By default the X driver maps button ''M'' to mouse button ''M''. Because X uses buttons 4-7 as the four scrolling directions, physical buttons 4 and higher are mapped to mouse buttons 8 and higher by default. While ''xorg.conf'' uses the actual button numbers and only lets you map to mouse buttons, ''xsetwacom'' uses the translated mouse button numbers and allows mapping to multiple keycodes (but not keysyms).<br />
<br />
If you have not yet remapped your buttons you can easily identify their ids with {{Pkg|xorg-xev}}, by running the following command, placing the mouse cursor on the created window and pressing a button:<br />
<br />
{{hc|$ xev -event button|<br />
Outer window is 0x1a00001, inner window is 0x1a00002<br />
<br />
ButtonPress event, serial 25, synthetic NO, window 0x1a00001,<br />
root 0x2a0, subw 0x0, time 3390669, (404,422), root:(1047,444),<br />
state 0x0, button 8, same_screen YES<br />
}}<br />
<br />
In this case the button number for ''xsetwacom'' is 8 and the actual button number for ''xorg.conf'' is 4.<br />
<br />
Alternatively, if you want an overview of your tablet's button layout you can look at your tablet's layout SVG. Firstly, find out the filename with a recursive [[grep]] search for the tablet name reported by {{ic|xsetwacom list devices}}:<br />
<br />
{{hc|$ grep -rl 'Wacom Bamboo 16FG 4x5' /usr/share/libwacom/*.tablet|2=<br />
/usr/share/libwacom/bamboo-16fg-s-t.tablet<br />
}}<br />
<br />
In this case the respective layout SVG is {{ic|/usr/share/libwacom/layouts/bamboo-16fg-s-t.svg}}. The letters in the SVG correspond to the button numbers: A=1, B=2, C=3, ...<br />
<br />
==== Mapping pad buttons to function keys ====<br />
<br />
If you want to bind your tablet buttons to different shortcuts in different applications, you may want to map your tablet buttons to function keys because applications generally do not let you bind keyboard shortcuts to mouse buttons.<br />
<br />
Firstly, map the pad buttons to mouse buttons 11 and higher so that you can distinguish them from regular mouse buttons. For example:<br />
<br />
xsetwacom set ''pad'' Button 1 11<br />
xsetwacom set ''pad'' Button 2 12<br />
...<br />
<br />
Then map the mouse buttons to the function keys. This can be done with [[xbindkeys]] and [[xdotool]] by adding an entry like the following for every pad to your {{ic|~/.xbindkeysrc}}:<br />
<br />
"xdotool key F21"<br />
b:11<br />
<br />
"xdotool key F22"<br />
b:12<br />
...<br />
<br />
==== The syntax ====<br />
<br />
The syntax of {{ic|xsetwacom}} is flexible but not very well documented. The general mapping syntax (extracted from the source code) for xsetwacom 0.17.0 is the following.<br />
<br />
KEYWORD [ARGS...] [KEYWORD [ARGS...] ...]<br />
<br />
KEYWORD + ARGS:<br />
key [+,-]KEY [[+,-]KEY ...] where +:key down, -:key up, no prefix:down and up<br />
button BUTTON [BUTTON ...] (1=left,2=middle,3=right mouse button, 4/5 scroll mouse wheel)<br />
modetoggle toggle absolute/relative tablet mode <br />
displaytoggle toggle cursor movement among all displays which include individual screens<br />
plus the whole desktop for the selected tool if it is not a pad.<br />
When the tool is a pad, the function applies to all tools that are asssociated<br />
with the tablet<br />
<br />
BUTTON: button ID as integer number<br />
<br />
KEY: MODIFIER, SPECIALKEY or ASCIIKEY<br />
MODIFIER: (each can be prefix with an '''l''' or an '''r''' for the left/right modifier (no prefix = left)<br />
ctrl=ctl=control, meta, alt, shift, super, hyper<br />
SPECIALKEY: f1-f35, esc=Esc, up,down,left,right, backspace=Backspace, tab, PgUp,PgDn<br />
ASCIIKEY: (usual characters the key produces, e.g. a,b,c,1,2,3 etc.)<br />
<br />
==== Some examples ====<br />
<br />
$ xsetwacom set ''pad'' Button 1 3 # right mouse button<br />
$ xsetwacom set ''pad'' Button 1 "key +ctrl z -ctrl"<br />
$ xsetwacom get ''pad'' Button 1<br />
key +Control_L +z -z -Control_L<br />
$ xsetwacom set ''pad'' Button 1 "key +shift button 1 key -shift"<br />
<br />
Even little macros are possible:<br />
<br />
$ xsetwacom set ''pad'' Button 1 "key +shift h -shift e l l o"<br />
<br />
{{Note|If you try to run a script with {{ic|xsetwacom}} commands from a udev rule, you might find that it will not work, as the Wacom input devices will not be ready at the time. A workaround is to add {{ic|sleep 1}} at the beginning of your script.}}<br />
<br />
==== Execute custom commands ====<br />
<br />
{{Style|Duplicates [[Xbindkeys]]. There are alternatives to xbindkeys.}}<br />
<br />
Mapping custom commands to the buttons is a little bit tricky but actually very simple. First, install [[xbindkeys]].<br />
<br />
To get well defined button codes add the following to your permanent configuration file, e.g. {{ic|/etc/X11/xorg.conf.d/52-wacom-options.conf}} in the InputClass section of your '''pad''' device. Map the tablet's buttons to some unused button ids.<br />
<br />
# Setting up buttons (preferably choose the correct button order, so the topmost key is mapped to 10 and so on)<br />
Option "Button1" "10"<br />
Option "Button2" "11"<br />
Option "Button3" "12"<br />
Option "Button4" "13"<br />
<br />
Then restart your ''Xorg'' server and verify the buttons using {{ic|xev}} or {{ic|xbindkeys -mk}}.<br />
<br />
Now set up your xbindkeys configuration, if you do not already have one you might want to create a default configuration<br />
<br />
$ xbindkeys --defaults > ~/.xbindkeysrc<br />
<br />
Then add your custom key mapping to {{ic|~/.xbindkeysrc}}, for example<br />
<br />
"firefox"<br />
m:0x10 + b:10 (mouse)<br />
"xterm"<br />
m:0x10 + b:11 (mouse)<br />
"xdotool key ctrl-z"<br />
m:0x10 + b:12 (mouse)<br />
"send-notify Test "No need for escaping the quotes""<br />
m:0x10 + b:13 (mouse)<br />
<br />
=== Adjusting aspect ratios ===<br />
<br />
Drawing areas of tablets are generally more square than the usual widescreen display with a 16:9 aspect ratio, leading to a slight vertical compression of your input. To resolve such an aspect ratio mismatch you need to compromise by either reducing the drawing area height (called ''Force Proportions'' on Windows) or reducing the screen area width. The former wastes drawing area and the latter prevents you from reaching the right edge of your screen with your Stylus. It is probably still a compromise worth to be made because it prevents your strokes from being skewed.<br />
<br />
Find out your tablet's resolution by running:<br />
<br />
$ xsetwacom get ''stylus'' Area<br />
<br />
==== Reducing the drawing area height ====<br />
<br />
Run:<br />
<br />
$ xsetwacom set ''stylus'' Area 0 0 ''tablet_width'' ''height''<br />
<br />
where ''height'' is ''tablet_width * screen_height / screen_width''.<br />
<br />
The tablet resolution can be reset back to the default using:<br />
<br />
$ xsetwacom set ''stylus'' ResetArea<br />
<br />
==== Reducing the screen area width ====<br />
<br />
Run:<br />
<br />
$ xsetwacom set ''stylus'' MapToOutput ''WIDTH''x''SCREEN_HEIGHT''+0+0<br />
<br />
where ''WIDTH'' is ''screen_height * tablet_width / tablet_height''.<br />
<br />
=== LEDs ===<br />
<br />
See the [https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-driver-wacom sysfs-driver-wacom] documentation. To make changes without requiring root permissions you will likely want to create a [[udev]] rule like so:<br />
<br />
{{hc|/etc/udev/rules.d/99-wacom.rules|<nowiki><br />
# Give the users group permissions to set Wacom device LEDs.<br />
ACTION=="add", SUBSYSTEM=="hid", DRIVERS=="wacom", RUN+="/usr/bin/sh -c 'chown :users /sys/%p/wacom_led/*'"<br />
</nowiki>}}<br />
<br />
Setting the Intuos OLEDs can be done using {{AUR|i4oled}} from the AUR.<br />
<br />
=== TwinView setup ===<br />
<br />
If you are going to use two monitors the aspect ratio while using the tablet might feel unnatural. In order to fix this you need to add:<br />
<br />
Option "TwinView" "horizontal"<br />
<br />
to all of your Wacom-InputDevice entries in the ''xorg.conf'' file. You may read more about that [http://ubuntuforums.org/showthread.php?t=640898 here].{{Dead link|2018|09|05}}<br />
<br />
==== Temporary TwinView setup ====<br />
<br />
For temporary mapping of a Wacom device to a single display ''while preserving the aspect ratio'', [https://gist.github.com/Quackmatic/6c19fe907945d735c045 this script] may be used. This will letter-box the surface area of the device as required to ensure the input is not stretched on the display. This script may be executed in your {{ic|.xinitrc}} file for it to automatically run.<br />
<br />
=== xrandr setup ===<br />
<br />
{{Style|Wording can be improved, personal writing style.}}<br />
<br />
[[xrandr]] sets two monitors as one big screen, mapping the tablet to the whole virtual screen and deforming aspect ratio. For a solution see this thread: [https://bbs.archlinux.org/viewtopic.php?pid=797617 Arch Linux forum].<br />
<br />
If you just want to map the tablet to one of your screens, first find out what the screens are called:<br />
<br />
$ xrandr<br />
Screen 0: minimum 320 x 200, current 3840 x 1080, maximum 16384 x 16384<br />
HDMI-0 disconnected (normal left inverted right x axis y axis)<br />
DVI-0 connected 1920x1080+0+0 (normal left inverted right x axis y axis) 477mm x 268mm<br />
1920x1080 60.0*+<br />
1680x1050 60.0 <br />
...<br />
VGA-0 connected 1920x1080+1920+0 (normal left inverted right x axis y axis) 477mm x 268mm<br />
1920x1080 60.0*+<br />
1680x1050 60.0 <br />
...<br />
<br />
Then you need to know what is the ID of your tablet.<br />
<br />
$ xsetwacom list devices<br />
WALTOP International Corp. Slim Tablet stylus id: 12 type: STYLUS<br />
<br />
In my case I want to map the tablet (ID: 12) to the screen on the right, which is ''VGA-0''. I can do that with this command<br />
<br />
$ xsetwacom set 12 MapToOutput VGA-0<br />
<br />
This should work immediately, no root necessary.<br />
<br />
Should this fail when using the NVIDIA binary driver, using ''HEAD-0'', ''HEAD-1'' and so on to refer to the monitors may work.<br />
<br />
If xsetwacom replies with "Unable to find an output ..." an X11 geometry string of the form {{ic|WIDTHxHEIGHT+X+Y}} can be specified instead of the screen identifier. In this example<br />
<br />
$ xsetwacom set 12 MapToOutput 1920x1080+1920+0<br />
<br />
should also map the tablet to the screen on the right.<br />
<br />
Alternatively, you can use [https://bitbucket.org/denilsonsa/small_scripts/src/3380435f92646190f860b87f566a39d0e215034c/xsetwacom_my_preferences.sh?at=default this bash script] to quickly map the tablet to one of your screens (or the entire desktop) and fix the aspect ratio.<br />
<br />
In case ''xsetwacom'' does not work, you can try ''xinput''.<br />
<br />
First, you need to find your tablet's ID.<br />
<br />
$ xinput list<br />
<br />
In my case, the output is:<br />
<br />
⎡ Virtual core pointer id=2 [master pointer (3)]<br />
⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)]<br />
⎜ ↳ Wacom Intuos PT S 2 Finger id=11 [slave pointer (2)]<br />
⎜ ↳ Wacom Intuos PT S 2 Pad id=12 [slave pointer (2)]<br />
⎜ ↳ USB Keyboard id=14 [slave pointer (2)]<br />
⎜ ↳ SynPS/2 Synaptics TouchPad id=16 [slave pointer (2)]<br />
⎜ ↳ TPPS/2 IBM TrackPoint id=17 [slave pointer (2)]<br />
⎜ ↳ SteelSeries Kinzu V2 Gaming Mouse id=9 [slave pointer (2)]<br />
⎜ ↳ Wacom Intuos PT S 2 Pen Pen (0x6281780c) id=20 [slave pointer (2)]<br />
⎣ Virtual core keyboard id=3 [master keyboard (2)]<br />
↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)]<br />
↳ Power Button id=6 [slave keyboard (3)]<br />
↳ Video Bus id=7 [slave keyboard (3)]<br />
↳ Sleep Button id=8 [slave keyboard (3)]<br />
↳ Wacom Intuos PT S 2 Pen id=10 [slave keyboard (3)]<br />
↳ USB Keyboard id=13 [slave keyboard (3)]<br />
↳ AT Translated Set 2 keyboard id=15 [slave keyboard (3)]<br />
↳ ThinkPad Extra Buttons id=18 [slave keyboard (3)]<br />
↳ USB Keyboard id=19 [slave keyboard (3)]<br />
<br />
This mean, my tablet's ID is ''20''. Now we map it with ''VGA-0'' screen:<br />
<br />
$ xinput map-to-output 20 VGA-0<br />
<br />
=== Pressure curve ===<br />
<br />
Use the [https://linuxwacom.github.io/bezier.html Wacom Pressure Curve and Threshold Graph] to find P1=red (eg. 50,0) and P2=purple (eg. 100,80) of your desired curve. The x-axis is the input pressure you apply to the pen; the y-axis is the output pressure the application is given.<br />
<br />
You can change the pressure curve with:<br />
<br />
$ xsetwacom set ''stylus'' PressureCurve ''x1 y1 x2 y2''<br />
<br />
== Application-specific configuration ==<br />
<br />
=== Blender ===<br />
<br />
To enable pad buttons and extra pen buttons in [[Blender]], you can create a xsetwacom wrapper to temporarily remap buttons for your blender session.<br />
<br />
Provided example (for Bamboo fun) adapted to ''Sculpt'' mode: [http://pastebin.archlinux.fr/1887946 blender_sculpt.sh]{{Dead link|2018|06|23}}<br />
<br />
It remaps:<br />
* Left tablet buttons to {{ic|Shift}} and {{ic|Ctrl}} ''(pan/tilt/zoom/smooth/invert)''<br />
* Right tablet buttons to {{ic|F}} ''(brush size/strenght)'' and {{ic|Ctrl-z}} ''(undo)''<br />
* Top pen button ton {{ic|m}} ''(mask control)''<br />
<br />
=== GIMP ===<br />
<br />
To enable proper usage, and pressure sensitive painting in [[GIMP]], just go to ''Edit > Input Devices''. Now for each of your ''eraser'', ''stylus'', and ''cursor'' ''devices'', set the ''mode'' to ''Screen'', and remember to save.<br />
<br />
* Please take note that if present, the ''pad'' ''device'' should be kept disabled as I do not think GIMP supports such things. Alternatively, to use such features of your tablet you should map them to keyboard commands with a program such as [http://hem.bredband.net/devel/wacom/ Wacom ExpressKeys].<br />
<br />
* You should also take note that the tool selected for the ''stylus'' is independent to that of the ''eraser''. This can actually be quite handy, as you can have the ''eraser'' set to be used as any tool you like.<br />
<br />
For more information checkout the ''Setting up GIMP'' section of [http://www.gimptalk.com/forum/topic.php?t=17992&start=1 GIMP Talk - Community - Install Guide: Getting Wacom Drawing Tablets To Work In Gimp].<br />
<br />
If the above was not enough, you may want to try setting up the tablet's stylus (and eraser) as a second mouse pointer (separating it from your mouse) by using the {{ic|xinput create-master}} and {{ic|xinput reattach}} commands. It can help when GIMP does not start painting even if the stylus touches the tablet.<br />
<br />
=== Inkscape ===<br />
<br />
Pressure sensitivity in [[Inkscape]] is enabled the same way as in GIMP. Go to ''Edit > Input Devices...''. Now for each of your ''eraser'', ''stylus'', and ''cursor'' ''devices'', set the ''mode'' to ''Screen'', and remember to save.<br />
<br />
=== Krita ===<br />
<br />
If your tablet does not draw in Krita (clicks/pressure are not registered) but works in the brush selection dialog which has a small test area, try putting Krita in full-screen or canvas-only mode.<br />
<br />
Krita only requires that Qt is able to use your tablet to function properly. If your tablet is not working in Krita, then make sure to check it is working in Qt first. The effect of tablet pressure can then be tweaked in the painttop configuration, for example by selecting opacity, then selecting pressure from the drop down and adjusting the curve to your preference.<br />
<br />
=== VirtualBox ===<br />
<br />
First, make sure that your tablet works well under Arch. Then, download and install the last driver from [http://www.wacom.com/downloads/drivers.php Wacom website] on the guest OS. Shutdown the virtual machine, go to ''Settings > USB''. Select ''Add Filter From Device'' and select your tablet (e.g. WACOM CTE-440-U V4.0-3 [0403]). Select ''Edit Filter'', and change the last item ''Remote'' to ''Any''.<br />
<br />
== Troubleshooting ==<br />
<br />
Newer tablets' drivers might not be in the kernel yet, and additional manipulations might be needed. A notable example is the newer Intuos line of tablets (Draw/Comic/Photo).<br />
<br />
=== Unknown device_type ===<br />
<br />
If your tablet does not get recognized by {{ic|xsetwacom}} and {{ic|dmesg}} complains about an unknown device_type, then you need to install a patched version of input-wacom.<br />
<br />
Download and install the for-4.4 branch from [http://sourceforge.net/p/linuxwacom/input-wacom/ci/jiri/for-4.4/~/tarball SourceForge].<br />
Your device should be recognized after you run<br />
<br />
# rmmod wacom<br />
# insmod /lib/modules/YOUR_KERNEL/kernel/drivers/hid/wacom.ko.gz<br />
<br />
=== Tablet recognized but xsetwacom and similar tools do not display it ===<br />
<br />
Your logs indicate that the correct driver is selected, and the tablet works. However, when running {{ic|xsetwacom list devices}} or use similar tools that depend on the correct driver, you get an empty list.<br />
<br />
A reason might be the execution order of your xorg configuration. {{ic|/usr/share/X11/xorg.conf.d}} gets executed first, then {{ic|/etc/X11/xorg.conf.d}}. The package {{pkg|xf86-input-wacom}} contains the file {{ic|/usr/share/X11/xorg.conf.d/70-wacom.conf}}. If there is a catchall for tablets, executed after this file, the previously selected {{ic|wacom}} driver will be overwritten with a generic one that does not work with xsetwacom et. al.<br />
<br />
To make sure, check the rules contained in the files executed after {{ic|/usr/share/X11/xorg.conf.d/70-wacom.conf}} for anything that looks like graphics tablets.<br />
<br />
=== Manual setup ===<br />
<br />
A manual configuration is done in {{ic|/etc/X11/xorg.conf}} or in a separate file in the {{ic|/etc/X11/xorg.conf.d/}} directory. The Wacom tablet device is accessed using a input event interface in {{ic|/dev/input/}} which is provided by the kernel driver. The interface number {{ic|event??}} is likely to change when unplugging and replugging into the same or especially a different ''USB'' port. Therefore it is wise to not refer to the device using its concrete {{ic|event??}} interface ('''static''' configuration) but by letting ''udev'' dynamically create a symbolic link to the correct {{ic|event}} file ('''dynamic''' configuration).<br />
<br />
==== Dynamic with udev ====<br />
<br />
{{Note|In AUR there is wacom-udev package, which includes udev-rules-file. You might skip this part and move on to the {{ic|xorg.conf}} configuration if you are using the wacom-udev package from AUR.}}<br />
<br />
Assuming ''udev'' is already installed you simply need to install {{AUR|wacom-udev}}{{Broken package link|{{aur-mirror|wacom-udev}}}} from the [[AUR]].<br />
<br />
===== USB-devices =====<br />
<br />
After (re-)plugging in your ''USB''-tablet (or at least after rebooting) some symbolic links should appear in {{ic|/dev/input}} referring to your tablet device.<br />
<br />
$ ls /dev/input/wacom* <br />
/dev/input/wacom /dev/input/wacom-stylus /dev/input/wacom-touch<br />
<br />
If not, your device is likely to be not yet included in the ''udev'' configuration from ''wacom-udev'' which resides in {{ic|/usr/lib/udev/rules.d/wacom.rules}}. Copy the file to {{ic|/etc/udev/rules.d/wacom.rules}} and modify it there.<br />
<br />
Add your device to the file by duplicating some line of another device and adapting ''idVendor'',''idProduct'' and the symlink name to your device.<br />
The two id's can be determined using<br />
<br />
$ lsusb | grep -i wacom<br />
Bus 002 Device 007: ID 056a:0062 Wacom Co., Ltd<br />
<br />
In this example idVendor is 056a and idProduct 0062. In case you have device with touch (e.g. Bamboo Pen&Touch) you might need to add a second line for the touch input interface. For details check the linuxwacom wiki [http://linuxwacom.sourceforge.net/wiki/index.php/Fixed_device_files_with_udev Fixed device files with udev].<br />
<br />
Save the file and reload udev's configuration profile using the command ''udevadm control --reload-rules'' Check again the content of ''/dev/input'' to make sure that the ''wacom'' symlinks appeared. Note that you may need to plug-in the tablet again for the device to appear.<br />
<br />
The files of further interest for the ''Xorg'' configuration are {{ic|/dev/input/wacom}} and for a touch-device also {{ic|/dev/input/wacom_touch}}.<br />
<br />
===== Serial devices =====<br />
<br />
The {{AUR|wacom-udev}}{{Broken package link|{{aur-mirror|wacom-udev}}}} should also include support for serial devices. Users of serial tablets might be also interested in the inputattach tool from {{Pkg|linuxconsole}} package. The inputattach command allows to bind serial device into /dev/input tree, for example with:<br />
<br />
# inputattach --w8001 /dev/ttyS0<br />
<br />
See ''man inputattach'' for help about available options. As for USB devices one should end up with a file {{ic|/dev/input/wacom}} and proceed with the ''Xorg'' configuration.<br />
<br />
==== Static setup ====<br />
<br />
Usually it is recommended to rely on [[Xorg]]'s auto-detection or to use a '''dynamic''' setup. However for an ''internal'' tablet device one might consider a '''static''' Xorg setup in case autodetection does not work. A static [[Xorg]] setup is usually not able to recognize your Wacom tablet when it is connected to a different ''USB'' port or even after unplugging and replugging it into the same port, and as such it should be considered as deprecated.<br />
<br />
If you insist in using a static setup just refer to your tablet in the ''Xorg'' configuration in the next section using the correct {{ic|/dev/input/event??}} files as one can find out by looking into {{ic|/proc/bus/input/devices}}.<br />
<br />
==== Xorg configuration ====<br />
<br />
In either case, dynamic or static setup you got now one or two files in {{ic|/dev/input/}} which refer to the correct input event devices of your tablet. All that is left to do is add the relevant information to {{ic|/etc/X11/xorg.conf}}, or a dedicated file under {{ic|/etc/X11/xorg.conf.d/}}. The exact configuration depends on your tablet's features of course. {{ic|xsetwacom list devices}} might give helpful information on what ''InputDevice'' sections are needed for your tablet.<br />
<br />
An example configuration for a ''Volito2'' might look like this<br />
<br />
Section "InputDevice"<br />
Driver "wacom"<br />
Identifier "stylus"<br />
Option "Device" "/dev/input/wacom" # or the corresponding event?? for a static setup<br />
Option "Type" "stylus"<br />
Option "USB" "on" # USB ONLY<br />
Option "Mode" "Relative" # other option: "Absolute"<br />
Option "Vendor" "WACOM"<br />
Option "tilt" "on" # add this if your tablet supports tilt<br />
Option "Threshold" "5" # the official linuxwacom howto advises this line<br />
EndSection<br />
Section "InputDevice"<br />
Driver "wacom"<br />
Identifier "eraser"<br />
Option "Device" "/dev/input/wacom" # or the corresponding event?? for a static setup<br />
Option "Type" "eraser"<br />
Option "USB" "on" # USB ONLY<br />
Option "Mode" "Relative" # other option: "Absolute"<br />
Option "Vendor" "WACOM"<br />
Option "tilt" "on" # add this if your tablet supports tilt<br />
Option "Threshold" "5" # the official linuxwacom howto advises this line<br />
EndSection<br />
Section "InputDevice"<br />
Driver "wacom"<br />
Identifier "cursor"<br />
Option "Device" "/dev/input/wacom" # or the corresponding event?? for a static setup<br />
Option "Type" "cursor"<br />
Option "USB" "on" # USB ONLY<br />
Option "Mode" "Relative" # other option: "Absolute"<br />
Option "Vendor" "WACOM"<br />
EndSection<br />
<br />
Make sure that you also change the path ({{Ic|"Device"}}) to your mouse, as it will be {{Ic|/dev/input/mouse_udev}} now.<br />
<br />
Section "InputDevice"<br />
Identifier "Mouse1"<br />
Driver "mouse"<br />
Option "CorePointer"<br />
Option "Device" "/dev/input/mouse_udev"<br />
Option "SendCoreEvents" "true"<br />
Option "Protocol" "IMPS/2"<br />
Option "ZAxisMapping" "4 5"<br />
Option "Buttons" "5"<br />
EndSection<br />
<br />
Add this to the ''ServerLayout'' section<br />
<br />
InputDevice "cursor" "SendCoreEvents" <br />
InputDevice "stylus" "SendCoreEvents"<br />
InputDevice "eraser" "SendCoreEvents"<br />
<br />
And finally make sure to update the identifier of your mouse in the ''ServerLayout'' section &ndash; as mine went from<br />
<br />
InputDevice "Mouse0" "CorePointer"<br />
<br />
to<br />
<br />
InputDevice "Mouse1" "CorePointer"<br />
<br />
=== Mouse Moving Erratically due to Proximity Sensor ===<br />
<br />
You can disable the mouse jumping due to a proximity sensor detecting a non-existing stylus. You can find your device with xinput --list, and after seeing the Stylus, disable it with: xinput disable "Your Device Name". This only works if you are not currently using a stylus.<br />
<br />
== See also ==<br />
<br />
* [[List of applications/Documents#Stylus note-taking]]<br />
* [https://github.com/linuxwacom/input-wacom/wiki input-wacom Wiki]<br />
* [https://github.com/linuxwacom/xf86-input-wacom/wiki xf86-input-wacom Wiki] (out of date)<br />
* [http://www.gimptalk.com/forum/topic.php?t=17992&start=1 GIMP Talk - Community - Install Guide: Getting Wacom Drawing Tablets To Work In Gimp]<br />
* [https://help.ubuntu.com/community/Wacom Ubuntu Help: Wacom]<br />
* [http://ubuntuforums.org/showthread.php?t=1038949 Ubuntu Forums - Install a LinuxWacom Kernel Driver for Tablet PC's]</div>B6hgas5https://wiki.archlinux.org/index.php?title=SANE/Scanner-specific_problems&diff=565283SANE/Scanner-specific problems2019-01-30T00:48:02Z<p>B6hgas5: /* Using a hostname */ I've done this before and it's worked fine, apparently no more.</p>
<hr />
<div>[[Category:Digital imaging]]<br />
[[ja:SANE/スキャナー別の問題]]<br />
This article contains scanner or manufacturer-specific instructions for [[SANE]].<br />
<br />
== Agfa ==<br />
=== Snapscan e40 ===<br />
<br />
Firmware {{ic|Snape40.bin}} from [https://sites.google.com/site/rameyarnaud/media/books/agfa-scanners-with-linux here] is required.<br />
<br />
If USB autosuspend is enabled, the printer may need to be turned off and on again before each scan. USB autosuspend can be disabled using [[powertop]].<br />
<br />
== BenQ/Acer ==<br />
If you own an USB scanner from Acer (now BenQ), you need to download a suitable firmware binary and configure {{ic|/etc/sane.d/snapscan.conf}}.<br />
<br />
* Find out which model you own and take note of the USB ID:<br />
{{hc|$ lsusb|<br />
Bus 002 Device 010: ID 04a5:20b0 Acer Peripherals Inc. (now BenQ Corp.) S2W 3300U/4300U}}<br />
* Go to [http://snapscan.sourceforge.net/ snapscan] main page and see whether your scanner is supported and which firmware you need (e.g, {{ic|u176v046.bin}}).<br />
* Search the firmware image on the Internet and download it to {{ic|/usr/share/sane/snapscan/}}.<br />
* Edit the head of {{ic|/etc/sane.d/snapscan.conf}} and configure the following two lines:<br />
firmware /usr/share/sane/snapscan/u176v046.bin<br />
/dev/usb/scanner0 bus=usb<br />
<br />
== Brother ==<br />
In order to install a Brother scanner or printer/scanner combo you need the right driver. To find the right one, search for your model at the [http://support.brother.com/g/s/id/linux/en/download_scn.html Brother Linux scanner page], or see the information below for scanners that aren't listed on that page.<br />
<br />
Then, install the appropriate package:<br />
* {{AUR|brscan2}}<br />
* {{AUR|brscan3}}<br />
* {{AUR|brscan4}} (MFC-J5620DW)<br />
* {{AUR|libsane-dsseries}}<br />
<br />
Now, the scanner should be recognized by SANE.<br />
<br />
For network scanners, Brother provides a different configuration tool for each brscan version (eg. brsaneconfig2 for brscan2 compatible devices):<br />
# brsaneconfig2 -a name=<ScannerName> model=<ScannerModel> ip=<ScannerIP><br />
Example:<br />
# brsaneconfig2 -a name=SCANNER_DCP770CW model=DCP-770CW ip=192.168.0.110<br />
<br />
=== Network Scanning ===<br />
<br />
In case of network scanning, e.g. by WiFi, Sane may still be unable to find the scanner. If so, you need to specify the IP address of the scanner in the {{ic|/etc/sane.d/net.conf}} file.<br />
<br />
Now use {{ic|scanimage --list-devices}} to check whether sane is able to find your scanner. If not, further check that Sane expects this device through the network (see [http://neithere.net/2013/02/18/archlinux_brother_7860.html]). Check that {{ic|/etc/sane.d/dll.conf}} contains {{ic|brother''X''}}, where the {{ic|''X''}} stands for the brscan version from above. If nothing was found, add {{ic|brother''X''}} to the end of the file.<br />
<br />
=== Invalid argument ===<br />
<br />
If all the necessary packages are installed but you still get the "invalid argument" error this could mean that the configuration file has been corrupted. Run the following command (in case of brscan4):<br />
# brsaneconfig4 -d <br />
<br />
The output should narrow down the problem. Most likely the connection isn't setup correctly. In case of a network scanner check if the IP address is right by opening the {{ic|/etc/opt/brother/scanner/brscan4//brsanenetdevice4.cfg}} with an editor. In case of a USB connection check if the path to the scanner in the configuration file is setup correctly. For that compare the values of the {{ic|lsusb}} command with your configuration file and change them if necessary.<br />
<br />
=== Scan-key-tool ===<br />
<br />
Brother has released a tool to enable scanning to be triggered by user interaction with the scanner itself (e.g. by selecting one of "Scan to email", "Scan to image", etc. on the scanner keypad) rather than by an attached computer. This can be set up by installing the {{aur|brscan-skey}} package and starting {{ic|brscan-skey.service}} [[systemd#Using units|using systemd]]. Note that by default this service runs as the '''brscan-skey''' user which is created by the package, whose home directory is located at {{ic|/srv/brscan-skey}}.<br />
<br />
Brother supplies some default scripts that are executed when a scan type is selected on the keypad. These may require the installation of some optional dependencies of the {{aur|brscan-skey}} package. For all options apart from "Scan to email" the resulting output can be found inside {{ic|$HOME/brscan}}, with {{ic|$HOME}} the home directory of the user running this tool (so {{ic|/srv/brscan-skey}} if started via systemd as a systemwide process).<br />
<br />
It is possible to change what action takes place when a given type of scan is selected on the keypad. This is done by editing {{ic|/opt/brother/scanner/brscan-skey/brscan-skey-0.2.4-0.cfg}}. For each variable {{ic|SCAN_COMMAND}} in {{ic|IMAGE}}, {{ic|OCR}}, {{ic|EMAIL}}, {{ic|FILE}}, the command<br />
<br />
$ $SCAN_COMMAND $SCANNER_DEVICE $SCANNER_FRIENDLY_NAME<br />
<br />
is executed when the corresponding scan type is selected. Note that {{ic|$SCAN_COMMAND}} is not quoted so may specify more than one positional parameter in the final command that is executed. {{ic|$SCANNER_DEVICE}} refers to the name of the device that should be specified to a sane frontend (e.g. via the {{ic|--device-name}} flag when using {{ic|scanimage}}), for example {{ic|brother3:bus4;dev2}}. {{ic|$SCANNER_FRIENDLY_NAME}} is the human-readable name of the scanner.<br />
<br />
=== xsane crashes ===<br />
<br />
{{Accuracy|<br />
*Should be mentioned on AUR page<br />
*This may only be relevant for the Brother DCP-150C scanner}}<br />
If xsane crashes with message "{{ic|1==bugchk_free(ptr==(nil))@brother_modelinf.c(482)}}", then you need to create the link {{ic|/usr/local/Brother -> /usr/share/brother}}.<br />
<br />
== Canon ==<br />
<br />
=== Scanning over the network with Canon Pixma all-in-one printer/scanners ===<br />
<br />
Find out your printer/scanner's IP address, and add it on a new line to {{ic|/etc/sane.d/pixma.conf}} in the format {{ic|bjnp://10.0.0.20}}.<br />
<br />
{{Tip|Instead of a IP address you can use the [[mDNS]] {{ic|.local}} address, e.g. {{ic|bjnp://''MyPixmaPrinter''.local}}.}}<br />
<br />
Sane should now find your device. For more details refer to {{man|5|sane-pixma}}.<br />
<br />
Alternative: for some Canon Pixma all-in-one printer/scanners, which are not detected over network, can be used {{AUR|scangearmp2}} package from AUR.<br />
<br />
== Epson ==<br />
<br />
With Epson scanners, you can use "Image Scan! for Linux".<br />
<br />
* Install the {{Pkg|iscan}} package<br />
* Install the appropriate iscan-plugin package for your scanner (for example, {{AUR|iscan-plugin-gt-x820}} for the Epson Perfection Photo V600)<br />
* Reboot, so that udev will recognize the device as a scanner and apply appropriate permissions<br />
<br />
For network (including Wi-Fi) scanners, install {{Pkg|iscan}} and {{AUR|iscan-plugin-network}}, then edit {{ic|/etc/sane.d/epkowa.conf}} and add the line:<br />
net {IP_OF_SCANNER}<br />
<br />
=== Image Scan v3 ===<br />
<br />
Some models require "Image Scan 3", which is different from "Image Scan! for Linux" and is not available in the official repositores. Install {{Aur|imagescan}} for the base program. It should detect supported USB scanners automatically by default. If you want to make use of a network scanner you also have to install {{Aur|imagescan-plugin-networkscan}}. Then edit {{ic|/etc/utsushi/utsushi.conf}}, and enter the ip address of your scanner to it.<br />
<br />
[devices]<br />
myscanner.udi = esci:networkscan://<ip-address-here>:1865<br />
myscanner.vendor = Epson<br />
myscanner.model = Model-name<br />
<br />
When you then start Image Scan v3, the name of the scan should be visible in the top left corner. If a connection problem happened, an error dialog will be shown.<br />
<br />
=== Epson Perfection V550 Photo ===<br />
<br />
Install {{aur|iscan-plugin-perfection-v550}}<br />
<br />
=== Epson Perfection 1270 ===<br />
<br />
For Epson Perfection 1270, you also need a firmware named {{ic|esfw3e.bin}}. It can be obtained by installing the Windows driver.<br />
<br />
Modify the configuration file of the snapscan backend, {{ic|/etc/sane.d/snapscan.conf}}. Change the firmware path line with yours:<br />
<br />
# Change to the fully qualified filename of your firmware file, if<br />
# firmware upload is needed by the scanner<br />
firmware /mnt/mydata/Backups/firmware/esfw3e.bin<br />
<br />
And add the following line in the end or anywhere you like<br />
<br />
# Epson Perfection 1270<br />
usb 0x04b8 0x0120<br />
<br />
You can get such code information ({{ic|usb 0x04b8 0x0120}}) by ''sane-find-scanner'' command.<br />
<br />
Also add such information lines to {{ic|/etc/hotplug/usb/libsane.usermap}} to setup your privilege, like:<br />
<br />
# Epson Perfection 1270<br />
libusbscanner 0x0003 0x04b8 0x0120 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000<br />
<br />
Replug scanner, you have a working Epson Perfection 1270 now.<br />
<br />
{{Note|I can scan image if I define the X and Y value, but without that error message occurs like: {{ic|scanimage: sane_start: Error during device I/O}}, if anyone knows any other reasons, please add them to this section.}}<br />
<br />
* To prevent {{ic|scanimage: sane_start: Error during device I/O}} and hangup of the scanner itself, when trying to scan with ADF (automatic document feed) enabled, I had to remove or comment out all Backends from {{ic|/etc/sane.d/dll.conf}} and instead just add this to the file: {{bc|snapscan}}<br />
<br />
If you still get the {{ic|Error during device I/O}} messages check that the transportation lock of the scanner (on the bottom of the scanner) is open.<br />
<br />
=== Epson Perfection 1670/2480/2580/3490/3590 ===<br />
<br />
{{Note|Installation instructions were only tested for Epson Perfection 3590 but should be similar to the other models. Check the instructions above and the links below and edit this wiki page if you can verify that your scanner works.}}<br />
<br />
Make sure to download the correct firmware for your Epson model. You can get an overview of some models and their drivers [https://wiki.ubuntuusers.de/Scanner/Epson%20Perfection/#Unterstuetze-Geraete here] and [http://snapscan.sourceforge.net/ here]. The download links of the firmware are broken, but you can use [https://wiki.ubuntuusers.de/Scanner/Epson_Perfection/Esfw52.bin/ this link] as alternative instead. Make sure to change the firmware filename of the link suiting your model. If you want to download and extract the firmware sources from the official epson sites yourself you can use [https://forum.ubuntuusers.de/topic/epson-perfection-3490-photo-on-ubuntu-9-04-64/ this guide].<br />
<br />
As an alternative you can also install the AUR package {{AUR|sane-epson-perfection-firmware}} which will download the firmware from the official sources, extract the binary and install those to {{ic|/usr/share/sane/snapscan/}}.<br />
<br />
Modify the configuration file of the snapscan backend, {{ic|/etc/sane.d/snapscan.conf}}. Change the firmware path line with yours:<br />
<br />
# Change to the fully qualified filename of your firmware file, if<br />
# firmware upload is needed by the scanner<br />
firmware /usr/share/sane/snapscan/esfw52.bin<br />
<br />
Other modifications were not needed for the Epson Perfection 3590 and might not be for other models as well. If you still have problems it can also help if you [[SANE#Multiple_backends_claim_scanner|completely remove]] the {{Pkg|iscan}} package.<br />
<br />
== Fujitsu ==<br />
<br />
=== ScanSnap S300/S300M ===<br />
<br />
For the operation of the ScanSnap scanners S300 and S300M a firmware file {{ic|/usr/share/sane/epjitsu/300M_0C00.nal}} is required, which can be downloaded [http://sange.fi/~atehwa/cgi-bin/piki.cgi/fujitsu%20scansnap%20s300%20firmware here] or extracted from the Windows driver. The {{ic|300M_0C00.nal}} and {{ic|300_0C00.nal}} files are interchangeable; the S300 device can use the {{ic|300M_0C00.nal}} file and the S300M device can use the {{ic|300_0C00.nal}} file. The file can be renamed to fit the entry in {{ic|/etc/sane.d/epjitsu.conf}}, or that entry can be edited to match the file name.<br />
<br />
== HP ==<br />
<br />
If your HP device [http://hplipopensource.com/hplip-web/supported_devices/index.html is supported by hplip], [[install]] the {{Pkg|hplip}} package.<br />
<br />
The latter comes with 3 tools:<br />
* ''hp-setup'' to add and setup the device<br />
* ''hp-plugin'' is the 'HPLIP Plugin Download and Install Utility'.<br />
* ''hp-scan'' is the 'HPLIP Scan Utility'. If you need that tool, you will need to install {{Pkg|python-pillow}}.<br />
<br />
''hp-setup'' requires Python Qt5 when run using the GUI (which is the default). As an alternative, you can run the CLI interface of hp-setup using {{ic|-i}} as argument.<br />
<br />
If the device is connected by USB, run ''hp-setup'' as root and follow the on screen instructions.<br />
<br />
If your device is connected on the network, use {{ic|hp-setup ''printer_ip''}} instead.<br />
<br />
=== Alternative way to scan with network HP scanner ===<br />
<br />
* Find out IP address of your network HP scanner, for example ''192.168.1.8''<br />
* Make device URI using hp-makeuri utility:<br />
<br />
{{hc|$ hp-makeuri 192.168.1.8|2=<br />
hpaio:/net/DeskJet_3630_series?ip=192.168.1.8<br />
}}<br />
<br />
* This URI could be given to xsane or scanimage tools, for example:<br />
<br />
$ xsane "hpaio:/net/DeskJet_3630_series?ip=192.168.1.8"<br />
$ scanimage --device "hpaio:/net/DeskJet_3630_series?ip=10.12.129.6" --format=png --resolution 300 >scan01.png<br />
<br />
== Medion ==<br />
<br />
If you own the USB scanner MD 9705 from Medion, you need to download a suitable firmware binary. This firmware file is in the device driver for Windows.<br />
<br />
Find out which model you own and take note of the USB ID:<br />
<br />
{{hc|$ lsusb|<br />
Bus 006 Device 007: ID 05d8:4003 Ultima Electronics Corp. Artec E+ 48U<br />
}}<br />
<br />
Download the windows driver from http://download.medion.com/downloads/treiber/scamd9705w9xxp.exe<br />
<br />
Then enter the following commands to extract the firmware file, and copy it to the location SANE expects it:<br />
<br />
$ unzip scamd9705w9xxp.exe Win2000/Artec48.usb<br />
# cp Win2000/Artec48.usb /usr/share/sane/artec_eplus48u/Artec48.usb<br />
<br />
== Mustek ==<br />
<br />
=== BearPaw 2400CU ===<br />
<br />
Works with sane-gt68xx ({{Pkg|sane-gt68xx-firmware}})<br />
<br />
== Samsung ==<br />
For some Samsung MFP printers you may need to edit {{ic|/etc/sane.d/xerox_mfp.conf}}.<br />
<br />
example entry:<br />
#Samsung SCX-3200<br />
usb 0x04e8 0x3441<br />
<br />
Change the printer model as needed. You can get the idVendor and idProduct code with {{ic|lsusb}}. See [https://bbs.archlinux.org/viewtopic.php?id=123934 this thread].<br />
<br />
To access the scanner over the network rather than the usb interface, add a line to {{ic|/etc/sane.d/xerox_mfp.conf}} such as<br />
<br />
#Samsung scx4500w wireless ip network address<br />
tcp xx.xx.xx.xx<br />
<br />
where xx.xx.xx.xx is the static ip address of the printer.</div>B6hgas5https://wiki.archlinux.org/index.php?title=SANE/Scanner-specific_problems&diff=565279SANE/Scanner-specific problems2019-01-29T23:54:06Z<p>B6hgas5: /* Brother */ add instructions on addressing brother scanners by name</p>
<hr />
<div>[[Category:Digital imaging]]<br />
[[ja:SANE/スキャナー別の問題]]<br />
This article contains scanner or manufacturer-specific instructions for [[SANE]].<br />
<br />
== Agfa ==<br />
=== Snapscan e40 ===<br />
<br />
Firmware {{ic|Snape40.bin}} from [https://sites.google.com/site/rameyarnaud/media/books/agfa-scanners-with-linux here] is required.<br />
<br />
If USB autosuspend is enabled, the printer may need to be turned off and on again before each scan. USB autosuspend can be disabled using [[powertop]].<br />
<br />
== BenQ/Acer ==<br />
If you own an USB scanner from Acer (now BenQ), you need to download a suitable firmware binary and configure {{ic|/etc/sane.d/snapscan.conf}}.<br />
<br />
* Find out which model you own and take note of the USB ID:<br />
{{hc|$ lsusb|<br />
Bus 002 Device 010: ID 04a5:20b0 Acer Peripherals Inc. (now BenQ Corp.) S2W 3300U/4300U}}<br />
* Go to [http://snapscan.sourceforge.net/ snapscan] main page and see whether your scanner is supported and which firmware you need (e.g, {{ic|u176v046.bin}}).<br />
* Search the firmware image on the Internet and download it to {{ic|/usr/share/sane/snapscan/}}.<br />
* Edit the head of {{ic|/etc/sane.d/snapscan.conf}} and configure the following two lines:<br />
firmware /usr/share/sane/snapscan/u176v046.bin<br />
/dev/usb/scanner0 bus=usb<br />
<br />
== Brother ==<br />
In order to install a Brother scanner or printer/scanner combo you need the right driver. To find the right one, search for your model at the [http://support.brother.com/g/s/id/linux/en/download_scn.html Brother Linux scanner page], or see the information below for scanners that aren't listed on that page.<br />
<br />
Then, install the appropriate package:<br />
* {{AUR|brscan2}}<br />
* {{AUR|brscan3}}<br />
* {{AUR|brscan4}} (MFC-J5620DW)<br />
* {{AUR|libsane-dsseries}}<br />
<br />
Now, the scanner should be recognized by SANE.<br />
<br />
For network scanners, Brother provides a different configuration tool for each brscan version (eg. brsaneconfig2 for brscan2 compatible devices):<br />
# brsaneconfig2 -a name=<ScannerName> model=<ScannerModel> ip=<ScannerIP><br />
Example:<br />
# brsaneconfig2 -a name=SCANNER_DCP770CW model=DCP-770CW ip=192.168.0.110<br />
<br />
=== Network Scanning ===<br />
<br />
In case of network scanning, e.g. by WiFi, Sane may still be unable to find the scanner. If so, you need to specify the IP address of the scanner in the {{ic|/etc/sane.d/net.conf}} file.<br />
<br />
Now use {{ic|scanimage --list-devices}} to check whether sane is able to find your scanner. If not, further check that Sane expects this device through the network (see [http://neithere.net/2013/02/18/archlinux_brother_7860.html]). Check that {{ic|/etc/sane.d/dll.conf}} contains {{ic|brother''X''}}, where the {{ic|''X''}} stands for the brscan version from above. If nothing was found, add {{ic|brother''X''}} to the end of the file.<br />
<br />
==== Using a hostname ====<br />
<br />
You can also configure brscan4 to use a hostname instead of an ip. Assuming you've configured your system to be able to access the scanner at {{ic|scanner.local}}, first add the scanner with the ip address:<br />
# brsaneconfig4 -a name=SCANNER_DCP770CW model=DCP-770CW ip=192.168.0.110<br />
<br />
And then go in and edit the {{ic|IP-ADDRESS} field of {{ic|/etc/opt/brother/scanner/brscan4//brsanenetdevice4.cfg}} to be {{ic|scanner.local}}. {{ic|brsaneconfig4}} will refuse to let you pass a name, but editing the config file will bypass this validation.<br />
<br />
=== Invalid argument ===<br />
<br />
If all the necessary packages are installed but you still get the "invalid argument" error this could mean that the configuration file has been corrupted. Run the following command (in case of brscan4):<br />
# brsaneconfig4 -d <br />
<br />
The output should narrow down the problem. Most likely the connection isn't setup correctly. In case of a network scanner check if the IP address is right by opening the {{ic|/etc/opt/brother/scanner/brscan4//brsanenetdevice4.cfg}} with an editor. In case of a USB connection check if the path to the scanner in the configuration file is setup correctly. For that compare the values of the {{ic|lsusb}} command with your configuration file and change them if necessary.<br />
<br />
=== Scan-key-tool ===<br />
<br />
Brother has released a tool to enable scanning to be triggered by user interaction with the scanner itself (e.g. by selecting one of "Scan to email", "Scan to image", etc. on the scanner keypad) rather than by an attached computer. This can be set up by installing the {{aur|brscan-skey}} package and starting {{ic|brscan-skey.service}} [[systemd#Using units|using systemd]]. Note that by default this service runs as the '''brscan-skey''' user which is created by the package, whose home directory is located at {{ic|/srv/brscan-skey}}.<br />
<br />
Brother supplies some default scripts that are executed when a scan type is selected on the keypad. These may require the installation of some optional dependencies of the {{aur|brscan-skey}} package. For all options apart from "Scan to email" the resulting output can be found inside {{ic|$HOME/brscan}}, with {{ic|$HOME}} the home directory of the user running this tool (so {{ic|/srv/brscan-skey}} if started via systemd as a systemwide process).<br />
<br />
It is possible to change what action takes place when a given type of scan is selected on the keypad. This is done by editing {{ic|/opt/brother/scanner/brscan-skey/brscan-skey-0.2.4-0.cfg}}. For each variable {{ic|SCAN_COMMAND}} in {{ic|IMAGE}}, {{ic|OCR}}, {{ic|EMAIL}}, {{ic|FILE}}, the command<br />
<br />
$ $SCAN_COMMAND $SCANNER_DEVICE $SCANNER_FRIENDLY_NAME<br />
<br />
is executed when the corresponding scan type is selected. Note that {{ic|$SCAN_COMMAND}} is not quoted so may specify more than one positional parameter in the final command that is executed. {{ic|$SCANNER_DEVICE}} refers to the name of the device that should be specified to a sane frontend (e.g. via the {{ic|--device-name}} flag when using {{ic|scanimage}}), for example {{ic|brother3:bus4;dev2}}. {{ic|$SCANNER_FRIENDLY_NAME}} is the human-readable name of the scanner.<br />
<br />
=== xsane crashes ===<br />
<br />
{{Accuracy|<br />
*Should be mentioned on AUR page<br />
*This may only be relevant for the Brother DCP-150C scanner}}<br />
If xsane crashes with message "{{ic|1==bugchk_free(ptr==(nil))@brother_modelinf.c(482)}}", then you need to create the link {{ic|/usr/local/Brother -> /usr/share/brother}}.<br />
<br />
== Canon ==<br />
<br />
=== Scanning over the network with Canon Pixma all-in-one printer/scanners ===<br />
<br />
Find out your printer/scanner's IP address, and add it on a new line to {{ic|/etc/sane.d/pixma.conf}} in the format {{ic|bjnp://10.0.0.20}}.<br />
<br />
{{Tip|Instead of a IP address you can use the [[mDNS]] {{ic|.local}} address, e.g. {{ic|bjnp://''MyPixmaPrinter''.local}}.}}<br />
<br />
Sane should now find your device. For more details refer to {{man|5|sane-pixma}}.<br />
<br />
Alternative: for some Canon Pixma all-in-one printer/scanners, which are not detected over network, can be used {{AUR|scangearmp2}} package from AUR.<br />
<br />
== Epson ==<br />
<br />
With Epson scanners, you can use "Image Scan! for Linux".<br />
<br />
* Install the {{Pkg|iscan}} package<br />
* Install the appropriate iscan-plugin package for your scanner (for example, {{AUR|iscan-plugin-gt-x820}} for the Epson Perfection Photo V600)<br />
* Reboot, so that udev will recognize the device as a scanner and apply appropriate permissions<br />
<br />
For network (including Wi-Fi) scanners, install {{Pkg|iscan}} and {{AUR|iscan-plugin-network}}, then edit {{ic|/etc/sane.d/epkowa.conf}} and add the line:<br />
net {IP_OF_SCANNER}<br />
<br />
=== Image Scan v3 ===<br />
<br />
Some models require "Image Scan 3", which is different from "Image Scan! for Linux" and is not available in the official repositores. Install {{Aur|imagescan}} for the base program. It should detect supported USB scanners automatically by default. If you want to make use of a network scanner you also have to install {{Aur|imagescan-plugin-networkscan}}. Then edit {{ic|/etc/utsushi/utsushi.conf}}, and enter the ip address of your scanner to it.<br />
<br />
[devices]<br />
myscanner.udi = esci:networkscan://<ip-address-here>:1865<br />
myscanner.vendor = Epson<br />
myscanner.model = Model-name<br />
<br />
When you then start Image Scan v3, the name of the scan should be visible in the top left corner. If a connection problem happened, an error dialog will be shown.<br />
<br />
=== Epson Perfection V550 Photo ===<br />
<br />
Install {{aur|iscan-plugin-perfection-v550}}<br />
<br />
=== Epson Perfection 1270 ===<br />
<br />
For Epson Perfection 1270, you also need a firmware named {{ic|esfw3e.bin}}. It can be obtained by installing the Windows driver.<br />
<br />
Modify the configuration file of the snapscan backend, {{ic|/etc/sane.d/snapscan.conf}}. Change the firmware path line with yours:<br />
<br />
# Change to the fully qualified filename of your firmware file, if<br />
# firmware upload is needed by the scanner<br />
firmware /mnt/mydata/Backups/firmware/esfw3e.bin<br />
<br />
And add the following line in the end or anywhere you like<br />
<br />
# Epson Perfection 1270<br />
usb 0x04b8 0x0120<br />
<br />
You can get such code information ({{ic|usb 0x04b8 0x0120}}) by ''sane-find-scanner'' command.<br />
<br />
Also add such information lines to {{ic|/etc/hotplug/usb/libsane.usermap}} to setup your privilege, like:<br />
<br />
# Epson Perfection 1270<br />
libusbscanner 0x0003 0x04b8 0x0120 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000<br />
<br />
Replug scanner, you have a working Epson Perfection 1270 now.<br />
<br />
{{Note|I can scan image if I define the X and Y value, but without that error message occurs like: {{ic|scanimage: sane_start: Error during device I/O}}, if anyone knows any other reasons, please add them to this section.}}<br />
<br />
* To prevent {{ic|scanimage: sane_start: Error during device I/O}} and hangup of the scanner itself, when trying to scan with ADF (automatic document feed) enabled, I had to remove or comment out all Backends from {{ic|/etc/sane.d/dll.conf}} and instead just add this to the file: {{bc|snapscan}}<br />
<br />
If you still get the {{ic|Error during device I/O}} messages check that the transportation lock of the scanner (on the bottom of the scanner) is open.<br />
<br />
=== Epson Perfection 1670/2480/2580/3490/3590 ===<br />
<br />
{{Note|Installation instructions were only tested for Epson Perfection 3590 but should be similar to the other models. Check the instructions above and the links below and edit this wiki page if you can verify that your scanner works.}}<br />
<br />
Make sure to download the correct firmware for your Epson model. You can get an overview of some models and their drivers [https://wiki.ubuntuusers.de/Scanner/Epson%20Perfection/#Unterstuetze-Geraete here] and [http://snapscan.sourceforge.net/ here]. The download links of the firmware are broken, but you can use [https://wiki.ubuntuusers.de/Scanner/Epson_Perfection/Esfw52.bin/ this link] as alternative instead. Make sure to change the firmware filename of the link suiting your model. If you want to download and extract the firmware sources from the official epson sites yourself you can use [https://forum.ubuntuusers.de/topic/epson-perfection-3490-photo-on-ubuntu-9-04-64/ this guide].<br />
<br />
As an alternative you can also install the AUR package {{AUR|sane-epson-perfection-firmware}} which will download the firmware from the official sources, extract the binary and install those to {{ic|/usr/share/sane/snapscan/}}.<br />
<br />
Modify the configuration file of the snapscan backend, {{ic|/etc/sane.d/snapscan.conf}}. Change the firmware path line with yours:<br />
<br />
# Change to the fully qualified filename of your firmware file, if<br />
# firmware upload is needed by the scanner<br />
firmware /usr/share/sane/snapscan/esfw52.bin<br />
<br />
Other modifications were not needed for the Epson Perfection 3590 and might not be for other models as well. If you still have problems it can also help if you [[SANE#Multiple_backends_claim_scanner|completely remove]] the {{Pkg|iscan}} package.<br />
<br />
== Fujitsu ==<br />
<br />
=== ScanSnap S300/S300M ===<br />
<br />
For the operation of the ScanSnap scanners S300 and S300M a firmware file {{ic|/usr/share/sane/epjitsu/300M_0C00.nal}} is required, which can be downloaded [http://sange.fi/~atehwa/cgi-bin/piki.cgi/fujitsu%20scansnap%20s300%20firmware here] or extracted from the Windows driver. The {{ic|300M_0C00.nal}} and {{ic|300_0C00.nal}} files are interchangeable; the S300 device can use the {{ic|300M_0C00.nal}} file and the S300M device can use the {{ic|300_0C00.nal}} file. The file can be renamed to fit the entry in {{ic|/etc/sane.d/epjitsu.conf}}, or that entry can be edited to match the file name.<br />
<br />
== HP ==<br />
<br />
If your HP device [http://hplipopensource.com/hplip-web/supported_devices/index.html is supported by hplip], [[install]] the {{Pkg|hplip}} package.<br />
<br />
The latter comes with 3 tools:<br />
* ''hp-setup'' to add and setup the device<br />
* ''hp-plugin'' is the 'HPLIP Plugin Download and Install Utility'.<br />
* ''hp-scan'' is the 'HPLIP Scan Utility'. If you need that tool, you will need to install {{Pkg|python-pillow}}.<br />
<br />
''hp-setup'' requires Python Qt5 when run using the GUI (which is the default). As an alternative, you can run the CLI interface of hp-setup using {{ic|-i}} as argument.<br />
<br />
If the device is connected by USB, run ''hp-setup'' as root and follow the on screen instructions.<br />
<br />
If your device is connected on the network, use {{ic|hp-setup ''printer_ip''}} instead.<br />
<br />
=== Alternative way to scan with network HP scanner ===<br />
<br />
* Find out IP address of your network HP scanner, for example ''192.168.1.8''<br />
* Make device URI using hp-makeuri utility:<br />
<br />
{{hc|$ hp-makeuri 192.168.1.8|2=<br />
hpaio:/net/DeskJet_3630_series?ip=192.168.1.8<br />
}}<br />
<br />
* This URI could be given to xsane or scanimage tools, for example:<br />
<br />
$ xsane "hpaio:/net/DeskJet_3630_series?ip=192.168.1.8"<br />
$ scanimage --device "hpaio:/net/DeskJet_3630_series?ip=10.12.129.6" --format=png --resolution 300 >scan01.png<br />
<br />
== Medion ==<br />
<br />
If you own the USB scanner MD 9705 from Medion, you need to download a suitable firmware binary. This firmware file is in the device driver for Windows.<br />
<br />
Find out which model you own and take note of the USB ID:<br />
<br />
{{hc|$ lsusb|<br />
Bus 006 Device 007: ID 05d8:4003 Ultima Electronics Corp. Artec E+ 48U<br />
}}<br />
<br />
Download the windows driver from http://download.medion.com/downloads/treiber/scamd9705w9xxp.exe<br />
<br />
Then enter the following commands to extract the firmware file, and copy it to the location SANE expects it:<br />
<br />
$ unzip scamd9705w9xxp.exe Win2000/Artec48.usb<br />
# cp Win2000/Artec48.usb /usr/share/sane/artec_eplus48u/Artec48.usb<br />
<br />
== Mustek ==<br />
<br />
=== BearPaw 2400CU ===<br />
<br />
Works with sane-gt68xx ({{Pkg|sane-gt68xx-firmware}})<br />
<br />
== Samsung ==<br />
For some Samsung MFP printers you may need to edit {{ic|/etc/sane.d/xerox_mfp.conf}}.<br />
<br />
example entry:<br />
#Samsung SCX-3200<br />
usb 0x04e8 0x3441<br />
<br />
Change the printer model as needed. You can get the idVendor and idProduct code with {{ic|lsusb}}. See [https://bbs.archlinux.org/viewtopic.php?id=123934 this thread].<br />
<br />
To access the scanner over the network rather than the usb interface, add a line to {{ic|/etc/sane.d/xerox_mfp.conf}} such as<br />
<br />
#Samsung scx4500w wireless ip network address<br />
tcp xx.xx.xx.xx<br />
<br />
where xx.xx.xx.xx is the static ip address of the printer.</div>B6hgas5https://wiki.archlinux.org/index.php?title=ZFS&diff=551891ZFS2018-10-29T07:39:56Z<p>B6hgas5: /* Monitoring / Mailing on Events */ explain how to use custom mailrc & switch to S-nail (which is installed by default) over msmtp</p>
<hr />
<div>[[Category:File systems]]<br />
[[Category:Oracle]]<br />
[[ja:ZFS]]<br />
[[ru:ZFS]]<br />
[[zh-hans:ZFS]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|ZFS/Virtual disks}}<br />
{{Related|Installing Arch Linux on ZFS}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:ZFS|ZFS]] is an advanced filesystem created by [[Wikipedia:Sun Microsystems|Sun Microsystems]] (now owned by Oracle) and released for OpenSolaris in November 2005. <br />
<br />
Features of ZFS include: pooled storage (integrated volume management – zpool), [[Wikipedia:Copy-on-write|Copy-on-write]], [[Wikipedia:Snapshot (computer storage)|snapshots]], data integrity verification and automatic repair (scrubbing), [[Wikipedia:RAID-Z|RAID-Z]], a maximum [[Wikipedia:Exabyte|16 Exabyte]] file size, and a maximum 256 Quadrillion [[Wikipedia:Zettabyte|Zettabytes]] storage with no limit on number of filesystems (datasets) or files[http://docs.oracle.com/cd/E19253-01/819-5461/zfsover-2/index.html]. ZFS is licensed under the [[Wikipedia:CDDL|Common Development and Distribution License]] (CDDL).<br />
<br />
Described as [http://web.archive.org/web/20060428092023/http://www.sun.com/2004-0914/feature/ "The last word in filesystems"] ZFS is stable, fast, secure, and future-proof. Being licensed under the CDDL, and thus incompatible with GPL, it is not possible for ZFS to be distributed along with the Linux Kernel. This requirement, however, does not prevent a native Linux kernel module from being developed and distributed by a third party, as is the case with [http://zfsonlinux.org/ zfsonlinux.org] (ZOL).<br />
<br />
ZOL is a project funded by the [https://www.llnl.gov/ Lawrence Livermore National Laboratory] to develop a native Linux kernel module for its massive storage requirements and super computers.<br />
<br />
{{Note|Due to potential legal incompatibilities between CDDL license of ZFS code and GPL of the Linux kernel ([https://sfconservancy.org/blog/2016/feb/25/zfs-and-linux/ ],[[wikipedia:Common_Development_and_Distribution_License#GPL_compatibility|CDDL-GPL]],[[wikipedia:ZFS#Linux|ZFS in Linux]]) - ZFS development is not supported by the kernel.<br />
<br />
As a result:<br />
* ZFSonLinux project must keep up with Linux kernel versions. After making stable ZFSonLinux release - Arch ZFS maintainers release them.<br />
* This situation sometimes locks down the normal rolling update process by unsatisfied dependencies because the new kernel version, proposed by update, is unsupported by ZFSonLinux.}}<br />
<br />
== Installation ==<br />
=== General ===<br />
<br />
{{warning|Unless you use the [[dkms]] versions of these packages, the ZFS and SPL kernel modules are tied to a specific kernel version. It would not be possible to apply any kernel updates until updated packages are uploaded to AUR or the [[Unofficial user repositories#archzfs|archzfs]] repository.}}<br />
<br />
{{Tip| You can [[downgrade]] your linux version to the one from [[Unofficial user repositories#archzfs|archzfs]] repo if your current kernel is newer.}}<br />
<br />
Install from the [[Arch User Repository]] or the [[Unofficial user repositories#archzfs|archzfs]] repository:<br />
* {{AUR|zfs-linux}} for [http://zfsonlinux.org/ stable] releases.<br />
* {{AUR|zfs-linux-git}} for [https://github.com/zfsonlinux/zfs/releases development] releases (with support of newer kernel versions).<br />
* {{AUR|zfs-linux-lts}} for stable releases for LTS kernels.<br />
* {{AUR|zfs-linux-lts-git}} for [https://github.com/zfsonlinux/zfs/releases development] releases for LTS kernels.<br />
* {{AUR|zfs-linux-hardened}} for stable releases for hardened kernels.<br />
* {{AUR|zfs-linux-hardened-git}} for [https://github.com/zfsonlinux/zfs/releases development] releases for hardened kernels.<br />
* {{AUR|zfs-linux-zen}} for stable releases for zen kernels.<br />
* {{AUR|zfs-linux-zen-git}} for [https://github.com/zfsonlinux/zfs/releases development] releases for zen kernels.<br />
* {{AUR|zfs-dkms}} for versions with dynamic kernel module support.<br />
* {{AUR|zfs-dkms-git}} for [https://github.com/zfsonlinux/zfs/releases development] releases for versions with dynamic kernel module support.<br />
<br />
These branches have (according to them) dependencies on the {{ic|zfs-utils}}, {{ic|spl}}, {{ic|spl-utils}} packages. SPL (Solaris Porting Layer) is a Linux Kernel module implementing Solaris APIs for ZFS compatibility.<br />
<br />
Test the installation by issuing {{ic|zpool status}} on the command line. If an "insmod" error is produced, try {{ic|depmod -a}}.<br />
<br />
=== Root on ZFS ===<br />
<br />
When performing an Arch install on ZFS, {{AUR|zfs-linux}} or {{AUR|zfs-dkms}} and its dependencies can be installed in the archiso environment as outlined in the previous section.<br />
<br />
It may be useful to prepare a [[#Embed the archzfs packages into an archiso|customized archiso]] with ZFS support builtin. For a much more detailed guide on installing Arch with ZFS as its root file system, see [[Installing Arch Linux on ZFS]].<br />
<br />
=== DKMS ===<br />
<br />
Users can make use of DKMS [[Dynamic Kernel Module Support]] to rebuild the ZFS modules automatically with every kernel upgrade. <br />
<br />
Install {{AUR|zfs-dkms}} or {{AUR|zfs-dkms-git}} and apply the post-install instructions given by these packages.<br />
<br />
{{Tip|Add an {{ic|IgnorePkg}} entry to [[pacman.conf]] to prevent these packages from upgrading when doing a regular update.}}<br />
<br />
== Experimenting with ZFS ==<br />
<br />
Users wishing to experiment with ZFS on ''virtual block devices'' (known in ZFS terms as VDEVs) which can be simple files like {{ic|~/zfs0.img}} {{ic|~/zfs1.img}} {{ic|~/zfs2.img}} etc. with no possibility of real data loss are encouraged to see the [[Experimenting with ZFS]] article. Common tasks like building a RAIDZ array, purposefully corrupting data and recovering it, snapshotting datasets, etc. are covered.<br />
<br />
== Configuration ==<br />
<br />
ZFS is considered a "zero administration" filesystem by its creators; therefore, configuring ZFS is very straight forward. Configuration is done primarily with two commands: {{ic|zfs}} and {{ic|zpool}}.<br />
<br />
=== Automatic Start ===<br />
<br />
For ZFS to live by its "zero administration" namesake, the zfs daemon must be loaded at startup. A benefit to this is that it is not necessary to mount the zpool in {{ic|/etc/fstab}}; the zfs daemon can import and mount zfs pools automatically. The daemon mounts the zfs pools reading the file {{ic|/etc/zfs/zpool.cache}}.<br />
<br />
For each pool you want automatically mounted by the zfs daemon execute:<br />
# zpool set cachefile=/etc/zfs/zpool.cache <pool><br />
<br />
Enable the service so it is automatically started at boot time:<br />
<br />
# systemctl enable zfs.target<br />
<br />
To manually start the daemon:<br />
<br />
# systemctl start zfs.target<br />
<br />
{{Note|Beginning with ZOL version 0.6.5.8 the ZFS service unit files have been changed so that you need to explicitly enable any ZFS services you want to run.<br />
<br />
See [https://github.com/archzfs/archzfs/issues/72 https://github.com/archzfs/archzfs/issues/72] for more information.<br />
<br />
}}<br />
<br />
In order to mount zfs pools automatically on boot you need to enable the following services and targets:<br />
<br />
# systemctl enable zfs-import-cache<br />
# systemctl enable zfs-mount<br />
# systemctl enable zfs-import.target<br />
<br />
or, as explained on [https://github.com/archzfs/archzfs/issues/72 the GitHub issue], use the [https://www.freedesktop.org/software/systemd/man/systemd.preset.html systemd preset file]:<br />
<br />
# systemctl preset $(tail -n +2 /usr/lib/systemd/system-preset/50-zfs.preset | cut -d ' ' -f 2)<br />
<br />
== Creating a storage pool ==<br />
<br />
Use {{ic| # parted --list}} to see a list of all available drives. It is not necessary nor recommended to partition the drives before creating the zfs filesystem.<br />
<br />
{{Note|If some or all device have been used in a software RAID set it is paramount to erase any old RAID configuration information. ([[Mdadm#Prepare the devices]]) }}<br />
<br />
{{Warning|For Advanced Format Disks with 4KB sector size, an ashift of 12 is recommended for best performance. Advanced Format disks emulate a sector size of 512 bytes for compatibility with legacy systems, this causes ZFS to sometimes use an ashift option number that is not ideal. Once the pool has been created, the only way to change the ashift option is to recreate the pool. Using an ashift of 12 would also decrease available capacity. See [https://github.com/zfsonlinux/zfs/wiki/faq#performance-considerations 1.10 What’s going on with performance?], [https://github.com/zfsonlinux/zfs/wiki/faq#advanced-format-disks 1.15 How does ZFS on Linux handle Advanced Format disks?], and [http://wiki.illumos.org/display/illumos/ZFS+and+Advanced+Format+disks ZFS and Advanced Format disks].}}<br />
<br />
Having identified the list of drives, it is now time to get the IDs of the drives to add to the zpool. The [https://github.com/zfsonlinux/zfs/wiki/faq#selecting-dev-names-when-creating-a-pool zfs on Linux developers recommend] using device IDs when creating ZFS storage pools of less than 10 devices. To find the IDs, simply:<br />
<br />
# ls -lh /dev/disk/by-id/<br />
<br />
The IDs should look similar to the following:<br />
<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JKRR -> ../../sdc<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JTM1 -> ../../sde<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KBP8 -> ../../sdd<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KDGY -> ../../sdb<br />
<br />
{{Warning|If you create zpools using device names (e.g. /dev/sda,/dev/sdb,...) ZFS might not be able to detect zpools intermittently on boot.}}<br />
<br />
{{Style|Missing references to [[Persistent block device naming]], it is useless to explain the differences (or even what they are) here.}}<br />
<br />
Disk labels and UUID can also be used for ZFS mounts by using [[GUID Partition Table|GPT]] partitions. ZFS drives have labels but Linux is unable to read them at boot. Unlike [[Master Boot Record|MBR]] partitions, GPT partitions directly support both UUID and labels independent of the format inside the partition. Partitioning rather than using the whole disk for ZFS offers two additional advantages. The OS does not generate bogus partition numbers from whatever unpredictable data ZFS has written to the partition sector, and if desired, you can easily over provision SSD drives, and slightly over provision spindle drives to ensure that different models with slightly different sector counts can zpool replace into your mirrors. This is a lot of organization and control over ZFS using readily available tools and techniques at almost zero cost.<br />
<br />
Use [[GUID Partition Table|gdisk]] to partition the all or part of the drive as a single partition. gdisk does not automatically name partitions so if partition labels are desired use gdisk command "c" to label the partitions. Some reasons you might prefer labels over UUID are: labels are easy to control, labels can be titled to make the purpose of each disk in your arrangement readily apparent, and labels are shorter and easier to type. These are all advantages when the server is down and the heat is on. GPT partition labels have plenty of space and can store most international characters [[wikipedia:GUID_Partition_Table#Partition_entries]] allowing large data pools to be labeled in an organized fashion.<br />
<br />
Drives partitioned with GPT have labels and UUID that look like this. <br />
<br />
# ls -l /dev/disk/by-partlabel<br />
# lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata1 -> ../../sdd1<br />
# lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata2 -> ../../sdc1<br />
# lrwxrwxrwx 1 root root 10 Apr 30 01:59 zfsl2arc -> ../../sda1<br />
<br />
# ls -l /dev/disk/by-partuuid<br />
# lrwxrwxrwx 1 root root 10 Apr 30 01:44 148c462c-7819-431a-9aba-5bf42bb5a34e -> ../../sdd1<br />
# lrwxrwxrwx 1 root root 10 Apr 30 01:59 4f95da30-b2fb-412b-9090-fc349993df56 -> ../../sda1<br />
# lrwxrwxrwx 1 root root 10 Apr 30 01:44 e5ccef58-5adf-4094-81a7-3bac846a885f -> ../../sdc1<br />
<br />
Now, finally, create the ZFS pool:<br />
<br />
# zpool create -f -m <mount> <pool> [raidz(2|3)|mirror] <ids><br />
<br />
* '''create''': subcommand to create the pool.<br />
<br />
* '''-f''': Force creating the pool. This is to overcome the "EFI label error". See [[#Does not contain an EFI label]].<br />
<br />
* '''-m''': The mount point of the pool. If this is not specified, then the pool will be mounted to {{ic|/<pool>}}.<br />
<br />
* '''pool''': This is the name of the pool.<br />
<br />
* '''raidz(2|3)|mirror''': This is the type of virtual device that will be created from the pool of devices, raidz is a single disk of parity, raidz2 for 2 disks of parity and raidz3 for 3 disks of parity, similar to raid5 and raid6. Also available is '''mirror''', which is similar to raid1 or raid10, but isn't constrained to just 2 device. If not specified, each device will be added as a vdev which is similar to raid0. After creation, a device can be added to each single drive vdev to turn it into a mirror, which can be useful for migrating data.<br />
<br />
* '''ids''': The names of the drives or partitions that to include into the pool. Get it from {{ic|/dev/disk/by-id}}.<br />
<br />
Create pool with single raidz vdev:<br />
<br />
# zpool create -f -m /mnt/data bigdata \<br />
raidz \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
Create pool with two mirror vdevs:<br />
<br />
# zpool create -f -m /mnt/data bigdata \<br />
mirror \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
mirror \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
=== Advanced Format disks ===<br />
<br />
At pool creation, '''ashift=12''' should always be used, except with SSDs that have 8k sectors where '''ashift=13''' is correct. A vdev of 512 byte disks using 4k sectors will not experience performance issues, but a 4k disk using 512 byte sectors will. Since '''ashift''' cannot be changed after pool creation, even a pool with only 512 byte disks should use 4k because those disks may need to be replaced with 4k disks or the pool may be expanded by adding a vdev composed of 4k disks. Because correct detection of 4k disks is not reliabile, {{ic|<nowiki>-o ashift=12</nowiki>}} should always be specified during pool creation. See the [https://github.com/zfsonlinux/zfs/wiki/faq#advanced-format-disks ZFS on Linux FAQ] for more details.<br />
<br />
Create pool with ashift=12 and single raidz vdev:<br />
<br />
# zpool create -f -o ashift=12 -m /mnt/data bigdata \<br />
raidz \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
=== Verifying pool creation ===<br />
<br />
If the command is successful, there will be no output. Using the {{ic|$ mount}} command will show that the pool is mounted. Using {{ic|# zpool status}} will show that the pool has been created.<br />
<br />
{{hc|# zpool status|<br />
pool: bigdata<br />
state: ONLINE<br />
scan: none requested<br />
config:<br />
<br />
NAME STATE READ WRITE CKSUM<br />
bigdata ONLINE 0 0 0<br />
-0 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KDGY-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JKRR-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KBP8-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JTM1-part1 ONLINE 0 0 0<br />
<br />
errors: No known data errors<br />
}}<br />
<br />
At this point it would be good to reboot the machine to ensure that the ZFS pool is mounted at boot. It is best to deal with all errors before transferring data.<br />
<br />
=== GRUB-compatible pool creation ===<br />
<br />
{{note|This section frequently goes out of date with updates to GRUB and ZFS. Consult the manual pages for the most up-to-date information.}}<br />
<br />
By default, ''zpool create'' enables all features on a pool. If {{ic|/boot}} resides on ZFS when using [[GRUB]] you must only enable features supported by GRUB otherwise GRUB will not be able to read the pool. GRUB 2.02 supports the read-write features {{ic|lz4_compress}}, {{ic|hole_birth}}, {{ic|embedded_data}}, {{ic|extensible_dataset}}, and {{ic|large_blocks}}; this is not suitable for all the features of ZFSonLinux 0.7.1, and must have unsupported features disabled.<br />
<br />
You can create a pool with the incompatible features disabled:<br />
<br />
# zpool create -o feature@multi_vdev_crash_dump=disabled \<br />
-o feature@large_dnode=disabled \<br />
-o feature@sha512=disabled \<br />
-o feature@skein=disabled \<br />
-o feature@edonr=disabled \<br />
$POOL_NAME $VDEVS<br />
<br />
When running the git version of ZFS on Linux, make sure to also add {{ic|1=-o feature@encryption=disabled}}.<br />
<br />
=== Importing a pool created by id ===<br />
<br />
Eventually a pool may fail to auto mount and you need to import to bring your pool back. Take care to avoid the most obvious solution.<br />
<br />
# ###zpool import zfsdata # Do not do this! Always use -d<br />
<br />
This will import your pools using {{ic|/dev/sd?}} which will lead to problems the next time you rearrange your drives. This may be as simple as rebooting with a USB drive left in the machine, which harkens back to a time when PCs would not boot when a floppy disk was left in a machine. Adapt one of the following commands to import your pool so that pool imports retain the persistence they were created with.<br />
<br />
# zpool import -d /dev/disk/by-id zfsdata<br />
# zpool import -d /dev/disk/by-partlabel zfsdata<br />
# zpool import -d /dev/disk/by-partuuid zfsdata<br />
<br />
== Tuning ==<br />
<br />
=== General ===<br />
<br />
Many parameters are available for zfs file systems, you can view a full list with {{ic|zfs get all <pool>}}. Two common ones to adjust are '''atime''' and '''compression'''.<br />
<br />
Atime is enabled by default but for most users, it represents superfluous writes to the zpool and it can be disabled using the zfs command:<br />
# zfs set atime=off <pool><br />
<br />
As an alternative to turning off atime completely, '''relatime''' is available. This brings the default ext4/xfs atime semantics to ZFS, where access time is only updated if the modified time or changed time changes, or if the existing access time has not been updated within the past 24 hours. It is a compromise between atime=off and atime=on. This property ''only'' takes effect if '''atime''' is '''on''':<br />
# zfs set relatime=on <pool><br />
<br />
Compression is just that, transparent compression of data. ZFS supports a few different algorithms, presently lz4 is the default. '''gzip''' is also available for seldom-written yet highly-compressable data; consult the man page for more details. Enable compression using the zfs command:<br />
# zfs set compression=on <pool><br />
<br />
Other options for zfs can be displayed again, using the zfs command:<br />
# zfs get all <pool><br />
<br />
=== SSD Caching ===<br />
<br />
You can add SSD devices as a write intent log (external ZIL or SLOG) and also as a layer 2 adaptive replacement cache (L2ARC). The process to add them is very similar to adding a new VDEV.<br />
<br />
All of the below references to device-id are the IDs from {{ic|/dev/disk/by-id/*}}.<br />
<br />
==== SLOG ====<br />
<br />
To add a mirrored SLOG:<br />
# zpool add <pool> log mirror <device-id-1> <device-id-2><br />
<br />
Or to add a single device SLOG (unsafe):<br />
# zpool add <pool> log <device-id><br />
<br />
Because the SLOG device stores data that has not been written to the pool, it is important to use devices that can finish writes when power is lost. It is also important to use redundancy, since a device failure can cause data loss. In addition, the SLOG is only used for sync writes, so may not provide any performance improvement.<br />
<br />
==== L2ARC ====<br />
<br />
To add L2ARC:<br />
# zpool add <pool> cache <device-id><br />
<br />
Because every block cached in L2ARC uses a small amount of memory, it is generally only useful in workloads where the amount of hot data is *bigger* than the maximum amount of memory that can fit in the computer, but small enough to fit into L2ARC. It is also cleared at reboot and is only a read cache, so redundancy is unnecessary. Un-intuitively, L2ARC can actually harm performance since it takes memory away from ARC.<br />
<br />
<br />
<br />
=== Database ===<br />
<br />
ZFS, unlike most other file systems, has a variable record size, or what is commonly referred to as a block size. By default, the recordsize on ZFS is 128KiB, which means it will dynamically allocate blocks of any size from 512B to 128KiB depending on the size of file being written. This can often help fragmentation and file access, at the cost that ZFS would have to allocate new 128KiB blocks each time only a few bytes are written to.<br />
<br />
Most RDBMSes work in 8KiB-sized blocks by default. Although the block size is tunable for [[MySQL|MySQL/MariaDB]], [[PostgreSQL]], and [[Oracle]], all three of them use an 8KiB block size ''by default''. For both performance concerns and keeping snapshot differences to a minimum (for backup purposes, this is helpful), it is usually desirable to tune ZFS instead to accommodate the databases, using a command such as:<br />
# zfs set recordsize=8K <pool>/postgres<br />
<br />
These RDBMSes also tend to implement their own caching algorithm, often similar to ZFS's own ARC. In the interest of saving memory, it is best to simply disable ZFS's caching of the database's file data and let the database do its own job:<br />
# zfs set primarycache=metadata <pool>/postgres<br />
<br />
If your pool has no configured log devices, ZFS reserves space on the pool's data disks for its intent log (the ZIL). ZFS uses this for crash recovery, but databases are often syncing their data files to the file system on their own transaction commits anyway. The end result of this is that ZFS will be committing data '''twice''' to the data disks, and it can severely impact performance. You can tell ZFS to prefer to not use the ZIL, and in which case, data is only committed to the file system once. Setting this for non-database file systems, or for pools with configured log devices, can actually ''negatively'' impact the performance, so beware:<br />
# zfs set logbias=throughput <pool>/postgres<br />
<br />
These can also be done at file system creation time, for example:<br />
# zfs create -o recordsize=8K \<br />
-o primarycache=metadata \<br />
-o mountpoint=/var/lib/postgres \<br />
-o logbias=throughput \<br />
<pool>/postgres<br />
<br />
Please note: these kinds of tuning parameters are ideal for specialized applications like RDBMSes. You can easily ''hurt'' ZFS's performance by setting these on a general-purpose file system such as your /home directory.<br />
<br />
=== /tmp ===<br />
<br />
If you would like to use ZFS to store your /tmp directory, which may be useful for storing arbitrarily-large sets of files or simply keeping your RAM free of idle data, you can generally improve performance of certain applications writing to /tmp by disabling file system sync. This causes ZFS to ignore an application's sync requests (eg, with {{ic|fsync}} or {{ic|O_SYNC}}) and return immediately. While this has severe application-side data consistency consequences (never disable sync for a database!), files in /tmp are less likely to be important and affected. Please note this does ''not'' affect the integrity of ZFS itself, only the possibility that data an application expects on-disk may not have actually been written out following a crash.<br />
# zfs set sync=disabled <pool>/tmp<br />
<br />
Additionally, for security purposes, you may want to disable '''setuid''' and '''devices''' on the /tmp file system, which prevents some kinds of privilege-escalation attacks or the use of device nodes:<br />
# zfs set setuid=off <pool>/tmp<br />
# zfs set devices=off <pool>/tmp<br />
<br />
Combining all of these for a create command would be as follows:<br />
# zfs create -o setuid=off -o devices=off -o sync=disabled -o mountpoint=/tmp <pool>/tmp<br />
<br />
Please note, also, that if you want /tmp on ZFS, you will need to mask (disable) [[systemd]]'s automatic tmpfs-backed /tmp, else ZFS will be unable to mount your dataset at boot-time or import-time:<br />
# systemctl mask tmp.mount<br />
<br />
=== ZVOLs ===<br />
<br />
ZFS volumes (ZVOLs) can suffer from the same block size-related issues as RDBMSes, but it is worth noting that the default recordsize for ZVOLs is 8KiB already. If possible, it is best to align any partitions contained in a ZVOL to your recordsize (current versions of fdisk and gdisk by default automatically align at 1MiB segments, which works), and file system block sizes to the same size. Other than this, you might tweak the '''recordsize''' to accommodate the data inside the ZVOL as necessary (though 8KiB tends to be a good value for most file systems, even when using 4KiB blocks on that level).<br />
<br />
==== RAIDZ and Advanced Format physical disks ====<br />
<br />
Each block of a ZVOL gets its own parity disks, and if you have physical media with logical block sizes of 4096B, 8192B, or so on, the parity needs to be stored in whole physical blocks, and this can drastically increase the space requirements of a ZVOL, requiring 2× or more physical storage capacity than the ZVOL's logical capacity. Setting the '''recordsize''' to 16k or 32k can help reduce this footprint drastically.<br />
<br />
See [https://github.com/zfsonlinux/zfs/issues/1807 ZFS on Linux issue #1807 for details]<br />
<br />
== Usage ==<br />
<br />
Users can optionally create a dataset under the zpool as opposed to manually creating directories under the zpool. Datasets allow for an increased level of control (quotas for example) in addition to snapshots. To be able to create and mount a dataset, a directory of the same name must not pre-exist in the zpool. To create a dataset, use:<br />
<br />
# zfs create <nameofzpool>/<nameofdataset><br />
<br />
It is then possible to apply ZFS specific attributes to the dataset. For example, one could assign a quota limit to a specific directory within a dataset:<br />
<br />
# zfs set quota=20G <nameofzpool>/<nameofdataset>/<directory><br />
<br />
To see all the commands available in ZFS, use :<br />
<br />
$ man zfs<br />
<br />
or:<br />
<br />
$ man zpool<br />
<br />
=== Native encryption ===<br />
Native ZFS encryption has been made available in 0.7.0.r26 or newer provided by packages like {{AUR|zfs-linux-git}}, {{AUR|zfs-dkms-git}} or other development builds. Despite the fact that version 0.7 has been released, this feature is still not enabled in the stable version as of 0.7.3, so a development build still needs to be used. An easy way of telling if encryption is available in the version of zfs you have installed is to check for the ZFS_PROP_ENCRYPTION definition in /usr/src/zfs-*/include/sys/fs/zfs.h.<br />
<br />
* Supported encryption options: {{ic|aes-128-ccm}}, {{ic|aes-192-ccm}}, {{ic|aes-256-ccm}}, {{ic|aes-128-gcm}}, {{ic|aes-192-gcm}} and {{ic|aes-256-gcm}}. When encryption is set to {{ic|on}}, {{ic|aes-256-ccm}} will be used.<br />
* Supported keyformats: {{ic|passphrase}}, {{ic|raw}}, {{ic|hex}}<br />
You can also specify iterations of PBKDF2 with {{ic|-o pbkdf2iters <n>}} (it takes time to decrypt the key)<br />
<br />
To create a dataset including native encryption with a passphrase, use:<br />
<br />
# zfs create -o encryption=on -o keyformat=passphrase <nameofzpool>/<nameofdataset><br />
<br />
To use a key instead of using a passphrase:<br />
<br />
# dd if=/dev/urandom of=/path/to/key bs=1 count=32<br />
# zfs create -o encryption=on -o keyformat=raw -o keylocation=file:///path/to/key <nameofzpool>/<nameofdataset><br />
<br />
You can also manually load the keys and then mount the encrypted dataset:<br />
# zfs load-key <nameofzpool>/<nameofdataset> # load key for a specific dataset<br />
# zfs load-key -a # load all keys<br />
# zfs load-key -r zpool/dataset # load all keys in a dataset<br />
<br />
When importing a pool that contains encrypted datasets: ZFS will by default not decrypt these datasets. To do this use {{ic|-l}}<br />
# zpool import -l pool<br />
<br />
You can automate this at boot with a custom systemd unit. For example: <br />
{{hc|/etc/systemd/system/zfs-key@.service|2=<nowiki><br />
[Unit]<br />
Description=Load storage encryption keys<br />
DefaultDependencies=no<br />
Before=systemd-user-sessions.service<br />
Before=zfs-mount.service<br />
After=zfs-import.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/bash -c 'systemd-ask-password "Encrypted storage password (%i): " | /usr/bin/zfs load-key zpool/%i'<br />
<br />
[Install]<br />
WantedBy=zfs-mount.service<br />
</nowiki>}}<br />
and enable a service instance for each encrypted volume: {{ic|# systemctl enable zfs-key@dataset}}.<br />
<br />
The Before= reference to systemd-user-sessions.service ensures that systemd-ask-password is invoked before the local IO devices are handed over to the system UI<br />
<br />
=== Scrub ===<br />
{{Accuracy|Since when do pools have to be scrubbed at least once a week? Unsubstantiated claim.}}<br />
ZFS pools should be scrubbed at least once a week. To scrub the pool:<br />
<br />
# zpool scrub <pool><br />
<br />
To do automatic scrubbing once a week, set the following line in the root crontab:<br />
<br />
{{hc|# crontab -e|<br />
...<br />
30 19 * * 5 zpool scrub <pool><br />
...<br />
}}<br />
<br />
Replace {{ic|<pool>}} with the name of the ZFS pool.<br />
<br />
=== Check zfs pool status ===<br />
<br />
To print a nice table with statistics about the ZFS pool, including and read/write errors, use<br />
<br />
# zpool status -v<br />
<br />
=== Destroy a storage pool ===<br />
<br />
ZFS makes it easy to destroy a mounted storage pool, removing all metadata about the ZFS device. This command destroys any data contained in the pool:<br />
<br />
# zpool destroy <pool><br />
<br />
And now when checking the status:<br />
<br />
{{hc|# zpool status|no pools available}}<br />
<br />
To find the name of the pool, see [[#Check zfs pool status]].<br />
<br />
=== Exporting a storage pool ===<br />
<br />
If a storage pool is to be used on another system, it will first need to be exported. It is also necessary to export a pool if it has been imported from the archiso as the hostid is different in the archiso as it is in the booted system. The zpool command will refuse to import any storage pools that have not been exported. It is possible to force the import with the {{ic|-f}} argument, but this is considered bad form.<br />
<br />
Any attempts made to import an un-exported storage pool will result in an error stating the storage pool is in use by another system. This error can be produced at boot time abruptly abandoning the system in the busybox console and requiring an archiso to do an emergency repair by either exporting the pool, or adding the {{ic|zfs_force&#61;1}} to the kernel boot parameters (which is not ideal). See [[#On boot the zfs pool does not mount stating: "pool may be in use from other system"]]<br />
<br />
To export a pool:<br />
<br />
# zpool export <pool><br />
<br />
=== Renaming a zpool ===<br />
<br />
Renaming a zpool that is already created is accomplished in 2 steps:<br />
<br />
# zpool export oldname<br />
# zpool import oldname newname<br />
<br />
=== Setting a different mount point ===<br />
<br />
The mount point for a given zpool can be moved at will with one command:<br />
# zfs set mountpoint=/foo/bar poolname<br />
<br />
=== Access Control Lists ===<br />
To use [[ACL]] on a ZFS pool:<br />
<br />
# zfs set acltype=posixacl <nameofzpool>/<nameofdataset><br />
# zfs set xattr=sa <nameofzpool>/<nameofdataset><br />
<br />
Setting {{ic|xattr}} is recommended for performance reasons [https://github.com/zfsonlinux/zfs/issues/170#issuecomment-27348094].<br />
<br />
=== Swap volume ===<br />
<br />
ZFS does not allow to use swapfiles, but users can use a ZFS volume (ZVOL) as swap. It is importart to set the ZVOL block size to match the system page size, which can be obtained by the {{ic|getconf PAGESIZE}} command (default on x86_64 is 4KiB). Another option useful for keeping the system running well in low-memory situations is not caching the ZVOL data.<br />
<br />
Create a 8 GiB zfs volume:<br />
<br />
# zfs create -V 8G -b $(getconf PAGESIZE) \<br />
-o logbias=throughput -o sync=always\<br />
-o primarycache=metadata \<br />
-o com.sun:auto-snapshot=false <pool>/swap<br />
<br />
Prepare it as swap partition:<br />
<br />
# mkswap -f /dev/zvol/<pool>/swap<br />
# swapon /dev/zvol/<pool>/swap<br />
<br />
To make it permanent, edit {{ic|/etc/fstab}}. ZVOLs support discard, which can potentially help ZFS's block allocator and reduce fragmentation for all other datasets when/if swap is not full.<br />
<br />
Add a line to {{ic|/etc/fstab}}:<br />
<br />
/dev/zvol/<pool>/swap none swap discard 0 0<br />
<br />
{{Out of date|The hibernate hook is deprecated. Does the limitation still apply?}}<br />
Keep in mind the Hibernate hook must be loaded before filesystems, so using ZVOL as swap will not allow to use hibernate function. If you need hibernate, keep a partition for it.<br />
<br />
=== Automatic snapshots ===<br />
<br />
==== ZFS Automatic Snapshot Service for Linux ====<br />
<br />
The {{AUR|zfs-auto-snapshot-git}} package from [[AUR]] provides a shell script to automate the management of snapshots, with each named by date and label (hourly, daily, etc), giving quick and convenient snapshotting of all ZFS datasets. The package also installs cron tasks for quarter-hourly, hourly, daily, weekly, and monthly snapshots. Optionally adjust the --keep parameter from the defaults depending on how far back the snapshots are to go (the monthly script by default keeps data for up to a year).<br />
<br />
To prevent a dataset from being snapshotted at all, set {{ic|1=com.sun:auto-snapshot=false}} on it. Likewise, set more fine-grained control as well by label, if, for example, no monthlies are to be kept on a snapshot, for example, set {{ic|1=com.sun:auto-snapshot:monthly=false}}.<br />
<br />
{{Note|zfs-auto-snapshot-git will not create snapshots during scrubbing ([[#Scrub|scrub]]). It is possible to override this by editing provided systemd unit ([[Systemd#Editing provided units]]) and removing `--skip-scrub` from `ExecStart` line. Consequences not known, someone please edit.<br />
}}<br />
<br />
==== ZFS Snapshot Manager ====<br />
<br />
The {{AUR|zfs-snap-manager}} package from [[AUR]] provides a python service that takes daily snapshots from a configurable set of ZFS datasets and cleans them out in a [[wikipedia:Backup_rotation_scheme#Grandfather-father-son|"Grandfather-father-son"]] scheme. It can be configured to e.g. keep 7 daily, 5 weekly, 3 monthly and 2 yearly snapshots. <br />
<br />
The package also supports configurable replication to other machines running ZFS by means of {{ic|zfs send}} and {{ic|zfs receive}}. If the destination machine runs this package as well, it could be configured to keep these replicated snapshots for a longer time. This allows a setup where a source machine has only a few daily snapshots locally stored, while on a remote storage server a much longer retention is available.<br />
<br />
== Troubleshooting ==<br />
=== Creating a zpool fails ===<br />
<br />
If the following error occurs then it can be fixed.<br />
<br />
# the kernel failed to rescan the partition table: 16<br />
# cannot label 'sdc': try using parted(8) and then provide a specific slice: -1<br />
<br />
One reason this can occur is because [https://github.com/zfsonlinux/zfs/issues/2582 ZFS expects pool creation to take less than 1 second]. This is a reasonable assumption under ordinary conditions, but in many situations it may take longer. Each drive will need to be cleared again before another attempt can be made.<br />
<br />
# parted /dev/sda rm 1<br />
# parted /dev/sda rm 1<br />
# dd if=/dev/zero of=/dev/sdb bs=512 count=1<br />
# zpool labelclear /dev/sda<br />
<br />
A brute force creation can be attempted over and over again, and with some luck the ZPool creation will take less than 1 second.<br />
Once cause for creation slowdown can be slow burst read writes on a drive. By reading from the disk in parallell to ZPool creation, it may be possible to increase burst speeds.<br />
<br />
# dd if=/dev/sda of=/dev/null<br />
<br />
This can be done with multiple drives by saving the above command for each drive to a file on separate lines and running <br />
<br />
# cat $FILE | parallel<br />
<br />
Then run ZPool creation at the same time.<br />
<br />
=== ZFS is using too much RAM ===<br />
<br />
By default, ZFS caches file operations ([[wikipedia:Adaptive replacement cache|ARC]]) using up to two-thirds of available system memory on the host. To adjust the ARC size, add the following to the [[Kernel parameters]] list:<br />
<br />
zfs.zfs_arc_max=536870912 # (for 512MB)<br />
<br />
For a more detailed description, as well as other configuration options, see [http://wiki.gentoo.org/wiki/ZFS#ARC gentoo-wiki:zfs#arc].<br />
<br />
=== Does not contain an EFI label ===<br />
<br />
The following error will occur when attempting to create a zfs filesystem,<br />
<br />
/dev/disk/by-id/<id> does not contain an EFI label but it may contain partition<br />
<br />
The way to overcome this is to use {{ic|-f}} with the zfs create command.<br />
<br />
=== No hostid found ===<br />
<br />
An error that occurs at boot with the following lines appearing before initscript output:<br />
<br />
ZFS: No hostid found on kernel command line or /etc/hostid.<br />
<br />
This warning occurs because the ZFS module does not have access to the spl hosted. There are two solutions, for this. Either place the spl hostid in the [[kernel parameters]] in the boot loader. For example, adding {{ic|1=spl.spl_hostid=0x00bab10c}}.<br />
<br />
The other solution is to make sure that there is a hostid in {{ic|/etc/hostid}}, and then [[regenerate the initramfs]] image. Which will copy the hostid into the initramfs image.<br />
<br />
=== Pool cannot be found while booting from SAS/SCSI devices ===<br />
<br />
In case you are booting a SAS/SCSI based, you might occassionally get boot problems where the pool you are trying to boot from cannot be found. A likely reason for this is that your devices are initialized too late into the process. That means that zfs cannot find any devices at the time when it tries to assemble your pool.<br />
<br />
In this case you should force the scsi driver to wait for devices to come online before continuing. You can do this by putting this into {{ic|/etc/modprobe.d/zfs.conf}}:<br />
<br />
{{hc|1=/etc/modprobe.d/zfs.conf|2=<br />
options scsi_mod scan=sync<br />
}}<br />
<br />
Afterwards, [[regenerate the initramfs]].<br />
<br />
This works because the zfs hook will copy the file at {{ic|/etc/modprobe.d/zfs.conf}} into the initcpio which will then be used at build time.<br />
<br />
=== On boot the zfs pool does not mount stating: "pool may be in use from other system" ===<br />
<br />
==== Unexported pool ====<br />
<br />
If the new installation does not boot because the zpool cannot be imported, chroot into the installation and properly export the zpool. See [[#Emergency chroot repair with archzfs]].<br />
<br />
Once inside the chroot environment, load the ZFS module and force import the zpool,<br />
<br />
# zpool import -a -f<br />
<br />
now export the pool:<br />
<br />
# zpool export <pool><br />
<br />
To see the available pools, use,<br />
<br />
# zpool status<br />
<br />
It is necessary to export a pool because of the way ZFS uses the hostid to track the system the zpool was created on. The hostid is generated partly based on the network setup. During the installation in the archiso the network configuration could be different generating a different hostid than the one contained in the new installation. Once the zfs filesystem is exported and then re-imported in the new installation, the hostid is reset. See [http://osdir.com/ml/zfs-discuss/2011-06/msg00227.html Re: Howto zpool import/export automatically? - msg#00227].<br />
<br />
If ZFS complains about "pool may be in use" after every reboot, properly export pool as described above, and then [[regenerate the initramfs]] in normally booted system.<br />
<br />
==== Incorrect hostid ====<br />
<br />
Double check that the pool is properly exported. Exporting the zpool clears the hostid marking the ownership. So during the first boot the zpool should mount correctly. If it does not there is some other problem.<br />
<br />
Reboot again, if the zfs pool refuses to mount it means the hostid is not yet correctly set in the early boot phase and it confuses zfs. Manually tell zfs the correct number, once the hostid is coherent across the reboots the zpool will mount correctly.<br />
<br />
Boot using zfs_force and write down the hostid. This one is just an example.<br />
% hostid<br />
0a0af0f8<br />
<br />
This number have to be added to the [[kernel parameters]] as {{ic|spl.spl_hostid&#61;0x0a0af0f8}}. Another solution is writing the hostid inside the initram image, see the [[Installing Arch Linux on ZFS#After the first boot|installation guide]] explanation about this.<br />
<br />
Users can always ignore the check adding {{ic|zfs_force&#61;1}} in the [[kernel parameters]], but it is not advisable as a permanent solution.<br />
<br />
=== Devices have different sector alignment ===<br />
<br />
Once a drive has become faulted it should be replaced A.S.A.P. with an identical drive.<br />
<br />
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -f<br />
<br />
but in this instance, the following error is produced:<br />
<br />
cannot replace ata-ST3000DM001-9YN166_S1F0KDGY with ata-ST3000DM001-1CH166_W1F478BD: devices have different sector alignment<br />
<br />
ZFS uses the ashift option to adjust for physical block size. When replacing the faulted disk, ZFS is attempting to use {{ic|<nowiki>ashift=12</nowiki>}}, but the faulted disk is using a different ashift (probably {{ic|<nowiki>ashift=9</nowiki>}}) and this causes the resulting error. <br />
<br />
For Advanced Format Disks with 4KB blocksize, an ashift of 12 is recommended for best performance. See [https://github.com/zfsonlinux/zfs/wiki/faq#performance-considerations 1.10 What’s going on with performance?] and [http://wiki.illumos.org/display/illumos/ZFS+and+Advanced+Format+disks ZFS and Advanced Format disks].<br />
<br />
Use zdb to find the ashift of the zpool: {{ic|zdb | grep ashift}}, then use the {{ic|-o}} argument to set the ashift of the replacement drive:<br />
<br />
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -o ashift=9 -f<br />
<br />
Check the zpool status for confirmation:<br />
<br />
{{hc|# zpool status -v|<br />
pool: bigdata<br />
state: DEGRADED<br />
status: One or more devices is currently being resilvered. The pool will<br />
continue to function, possibly in a degraded state.<br />
action: Wait for the resilver to complete.<br />
scan: resilver in progress since Mon Jun 16 11:16:28 2014<br />
10.3G scanned out of 5.90T at 81.7M/s, 20h59m to go<br />
2.57G resilvered, 0.17% done<br />
config:<br />
<br />
NAME STATE READ WRITE CKSUM<br />
bigdata DEGRADED 0 0 0<br />
raidz1-0 DEGRADED 0 0 0<br />
replacing-0 OFFLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KDGY OFFLINE 0 0 0<br />
ata-ST3000DM001-1CH166_W1F478BD ONLINE 0 0 0 (resilvering)<br />
ata-ST3000DM001-9YN166_S1F0JKRR ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KBP8 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JTM1 ONLINE 0 0 0<br />
<br />
errors: No known data errors}}<br />
<br />
=== Pool resilvering stuck/restarting/slow? ===<br />
According to the ZFSonLinux github it's a known issue since 2012 with ZFS-ZED which causes the resilvering process to constantly restart, sometimes get stuck and be generally slow for some hardware. The simplest mitigation is to stop zfs-zed.service until the resilver completes<br />
<br />
=== Fix slow boot caused by failed import of unavailable pools in the initramfs zpool.cache ===<br />
<br />
Your boot time can be significantly impacted if you update your intitramfs (eg when doing a kernel update) when you have additional but non-permanently attached pools imported because these pools will get added to your initramfs zpool.cache and ZFS will attempt to import these extra pools on every boot, regardless of whether you have exported it and removed it from your regular zpool.cache.<br />
<br />
If you notice ZFS trying to import unavailable pools at boot, first run:<br />
<br />
$ zdb -C<br />
<br />
To check you zpool.cache for pools you don't want imported at boot. If this command is showing (a) additional, currently unavailable pool(s), run:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache zroot<br />
<br />
To clear the zpool.cache of any pools other than zroot, then rebuild your initramfs:<br />
<br />
# mkinitcpio -p linux<br />
<br />
== Tips and tricks ==<br />
<br />
===Embed the archzfs packages into an archiso===<br />
<br />
Follow the [[Archiso]] steps for creating a fully functional Arch Linux live CD/DVD/USB image.<br />
<br />
Enable the [[Unofficial user repositories#archzfs|archzfs]] repository:<br />
<br />
{{hc|~/archlive/pacman.conf|<nowiki><br />
...<br />
[archzfs]<br />
Server = http://archzfs.com/$repo/x86_64<br />
</nowiki>}}<br />
<br />
Add the {{ic|archzfs-linux}} group to the list of packages to be installed (the {{ic|archzfs}} repository provides packages for the x86_64 architecture only).<br />
<br />
{{hc|~/archlive/packages.x86_64|<br />
...<br />
archzfs-linux<br />
}}<br />
<br />
Complete [[Archiso#Build_the_ISO|Build the ISO]] to finally build the iso.<br />
<br />
{{Note|If you later have problems running modprobe zfs, you should include the linux-headers in the packages.x86_64. }}<br />
<br />
=== Encryption in ZFS using dm-crypt ===<br />
The stable release version of ZFS on Linux does not support encryption directly, but zpools can be created in dm-crypt block devices. Since the zpool is created on the plain-text abstraction, it is possible to have the data encrypted while having all the advantages of ZFS like deduplication, compression, and data robustness.<br />
<br />
dm-crypt, possibly via LUKS, creates devices in {{ic|/dev/mapper}} and their name is fixed. So you just need to change {{ic|zpool create}} commands to point to that names. The idea is configuring the system to create the {{ic|/dev/mapper}} block devices and import the zpools from there. Since zpools can be created in multiple devices (raid, mirroring, striping, ...), it is important all the devices are encrypted otherwise the protection might be partially lost.<br />
<br />
For example, an encrypted zpool can be created using plain dm-crypt (without LUKS) with:<br />
<br />
# cryptsetup --hash=sha512 --cipher=twofish-xts-plain64 --offset=0 \<br />
--key-file=/dev/sdZ --key-size=512 open --type=plain /dev/sdX enc<br />
# zpool create zroot /dev/mapper/enc<br />
<br />
In the case of a root filesystem pool, the {{ic|mkinitcpio.conf}} HOOKS line will enable the keyboard for the password, create the devices, and load the pools. It will contain something like:<br />
<br />
HOOKS="... keyboard encrypt zfs ..."<br />
<br />
Since the {{ic|/dev/mapper/enc}} name is fixed no import errors will occur.<br />
<br />
Creating encrypted zpools works fine. But if you need encrypted directories, for example to protect your users' homes, ZFS loses some functionality.<br />
<br />
ZFS will see the encrypted data, not the plain-text abstraction, so compression and deduplication will not work. The reason is that encrypted data has always high entropy making compression ineffective and even from the same input you get different output (thanks to salting) making deduplication impossible. To reduce the unnecessary overhead it is possible to create a sub-filesystem for each encrypted directory and use [[eCryptfs]] on it.<br />
<br />
For example to have an encrypted home: (the two passwords, encryption and login, must be the same)<br />
<br />
# zfs create -o compression=off -o dedup=off -o mountpoint=/home/<username> <zpool>/<username><br />
# useradd -m <username><br />
# passwd <username><br />
# ecryptfs-migrate-home -u <username><br />
<log in user and complete the procedure with ecryptfs-unwrap-passphrase><br />
<br />
=== Emergency chroot repair with archzfs ===<br />
<br />
To get into the ZFS filesystem from live system for maintenance, there are two options:<br />
<br />
# Build custom archiso with ZFS as described in [[#Embed the archzfs packages into an archiso]].<br />
# Boot the latest official archiso and bring up the network. Then enable [[Unofficial_user_repositories#archzfs|archzfs]] repository inside the live system as usual, sync the pacman package database and install the ''archzfs-archiso-linux'' package.<br />
<br />
To start the recovery, load the ZFS kernel modules:<br />
<br />
# modprobe zfs<br />
<br />
Import the pool:<br />
<br />
# zpool import -a -R /mnt<br />
<br />
Mount the boot partitions (if any):<br />
<br />
# mount /dev/sda2 /mnt/boot<br />
# mount /dev/sda1 /mnt/boot/efi<br />
<br />
Chroot into the ZFS filesystem:<br />
<br />
# arch-chroot /mnt /bin/bash<br />
<br />
Check the kernel version:<br />
<br />
# pacman -Qi linux<br />
# uname -r<br />
<br />
uname will show the kernel version of the archiso. If they are different, run depmod (in the chroot) with the correct kernel version of the chroot installation:<br />
<br />
# depmod -a 3.6.9-1-ARCH (version gathered from pacman -Qi linux but using the matching kernel modules directory name under the chroot's /lib/modules)<br />
<br />
This will load the correct kernel modules for the kernel version installed in the chroot installation.<br />
<br />
Regenerate the ramdisk:<br />
<br />
# mkinitcpio -p linux<br />
<br />
There should be no errors.<br />
<br />
=== Bind mount ===<br />
Here a bind mount from /mnt/zfspool to /srv/nfs4/music is created. The configuration ensures that the zfs pool is ready before the bind mount is created.<br />
<br />
==== fstab ====<br />
See [http://www.freedesktop.org/software/systemd/man/systemd.mount.html systemd.mount] for more information on how systemd converts fstab into mount unit files with [http://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html systemd-fstab-generator].<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
/mnt/zfspool /srv/nfs4/music none bind,defaults,nofail,x-systemd.requires=zfs-mount.service 0 0<br />
</nowiki>}}<br />
<br />
=== Monitoring / Mailing on Events ===<br />
See [https://ramsdenj.com/2016/08/29/arch-linux-on-zfs-part-3-followup.html ZED: The ZFS Event Daemon] for more information.<br />
<br />
An email forwarder, such as [[S-nail]] (installed as part of {{Pkg|base}}), is required to accomplish this. Test it to be sure it is working correctly.<br />
<br />
Uncomment the following in the configuration file:<br />
<br />
{{hc|/etc/zfs/zed.d/zed.rc|<nowiki><br />
ZED_EMAIL_ADDR="root"<br />
ZED_EMAIL_PROG="mailx"<br />
ZED_NOTIFY_VERBOSE=0<br />
ZED_EMAIL_OPTS="-s '@SUBJECT@' @ADDRESS@"<br />
</nowiki>}}<br />
<br />
Update 'root' in {{ic|1=ZED_EMAIL_ADDR="root"}} to the email address you want to receive notifications at.<br />
<br />
If you're keeping your mailrc in your home directory, you can tell mail to get it from there by setting {{ic|MAILRC}}:<br />
<br />
{{hc|/etc/zfs/zed.d/zed.rc|<nowiki><br />
export MAILRC=/home/<user>/.mailrc<br />
</nowiki>}}<br />
<br />
This works because ZED sources this file, so {{ic|mailx}} sees this environment variable.<br />
<br />
If you want to receive an email no matter the state of your pool, you will want to set {{ic|1=ZED_NOTIFY_VERBOSE=1}}. You will need to do this temporary to test.<br />
<br />
Start and enable {{ic|zfs-zed.service}}.<br />
<br />
With {{ic|1=ZED_NOTIFY_VERBOSE=1}}, you can test by running a scrub: {{ic|1=sudo zpool scrub <pool-name>}}.<br />
<br />
===Wrap shell commands in pre & post snapshots===<br />
Since it's so cheap to make a snapshot, we can use this as a measure of security for sensitive commands such as system and package upgrades. If we make a snapshot before, and one after, we can later diff these snapshots to find out what changed on the filesystem after the command executed. Furthermore we can also rollback in case the outcome was not desired.<br />
<br />
E.g.:<br />
<br />
# zfs snapshot -r zroot@pre<br />
# pacman -Syyu # dangerous command<br />
# zfs snapshot -r zroot@post<br />
# zfs diff zroot@pre zroot@post <br />
# zfs rollback zroot@pre<br />
<br />
<br />
A utility that automates the creation of pre and post snapshots around a shell command is [https://gist.github.com/erikw/eeec35be33e847c211acd886ffb145d5 znp].<br />
<br />
E.g.:<br />
<br />
# znp pacman -Syyu<br />
# znp find / -name "something*" -delete<br />
<br />
and you would get snapshots created before and after the supplied command, and also output of the commands logged to file for future reference so we know what command created the diff seen in a pair of pre/post snapshots.<br />
<br />
== See also ==<br />
<br />
* [https://pthree.org/2012/12/04/zfs-administration-part-i-vdevs/ Aaron Toponce's 17-part blog on ZFS]<br />
* [http://zfsonlinux.org/ ZFS on Linux]<br />
* [https://github.com/zfsonlinux/zfs/wiki/faq ZFS on Linux FAQ]<br />
* [https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/zfs.html FreeBSD Handbook -- The Z File System]<br />
* [https://docs.oracle.com/cd/E19253-01/819-5461/index.html Oracle Solaris ZFS Administration Guide]<br />
* [http://www.solarisinternals.com/wiki/index.php/ZFS_Troubleshooting_Guide Solaris Internals -- ZFS Troubleshooting Guide]{{Dead link|2017|05|30}}<br />
* [http://royal.pingdom.com/2013/06/04/zfs-backup/ How Pingdom uses ZFS to back up 5TB of MySQL data every day]<br />
* [https://www.linuxquestions.org/questions/linux-from-scratch-13/%5Bhow-to%5D-add-zfs-to-the-linux-kernel-4175514510/ Tutorial on adding the modules to a custom kernel]</div>B6hgas5https://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=525661Pacman/Tips and tricks2018-06-12T01:57:28Z<p>B6hgas5: /* With size */ add oneliner for listing size that doesn't require installing anything.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
Figuring out which packages are largest can be useful when trying to free space on your hard drive. There are two options here: get the size of individual packages, or get the size of packages & their dependencies.<br />
<br />
===== Individual packages =====<br />
<br />
The following command will list all installed packages and their individual sizes:<br />
<br />
$ pacman -Qi | awk '/^Installed Size/{print $4$5, name} /^Name/{name=$3}' | sort -h<br />
<br />
===== Packages & dependencies =====<br />
<br />
To list package sizes with their dependencies,<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(wget -q -O - https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | awk '/^.+(-cvs|-svn|-git|-hg|-bzr|-darcs)$/'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{AUR|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner (requires {{Pkg|pacman-contrib}}):<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver which other computers can use as a first mirror:<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try {{Pkg|pacredir}}, [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is provided by {{pkg|pacman-contrib}}) can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Bacman does not currently honor the {{ic|COMPRESS}} options in {{ic|makepkg.conf}}.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqe > pkglist.txt<br />
<br />
{{Note|If the option {{ic|-t}} was used, when reinstalling the list all the non-top-level packages would be set as dependencies. With option {{ic|-n}}, foreign packages (e.g. from AUR) would be omitted from the list.}}<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
In case the list includes foreign packages, such as [[AUR]] packages, remove them first:<br />
<br />
# pacman -S $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
If you would like to keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/packages.txt'<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were got corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget --passive-ftp -c -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{Pkg|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|1=Aarchup|2=Fork of archup. Has the same options as archup plus a few other features. For differences between both please check [https://bbs.archlinux.org/viewtopic.php?id=119129 changelog].|3=https://github.com/aericson/aarchup/|4={{AUR|aarchup}}}}<br />
* {{App|Arch-Update|Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|A collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME packagekit|GTK based package management tool|http://www.freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Gnome Software App. (Curated selection for GNOME)|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|A small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pcurses|Package management in a curses frontend|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|1=PkgBrowser|2=Application for searching and browsing Arch packages, showing details on selected packages.|3=https://bitbucket.org/kachelaqa/pkgbrowser/wiki/Home|4={{AUR|pkgbrowser}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>B6hgas5https://wiki.archlinux.org/index.php?title=Termite&diff=351367Termite2014-12-21T14:25:01Z<p>B6hgas5: /* Troubleshooting */</p>
<hr />
<div>[[Category:Terminal emulators]]<br />
[https://www.github.com/thestinger/termite Termite] is a minimal [[:Category:Terminal emulators|terminal emulator]] designed for use with tiling [[window manager]]s. It is a ''modal'' application, similar to [[Vim]], with an insert mode and command mode where keybindings have different functions.<br />
<br />
The configuration file allows to change color and keybindings, and Termite supports transparency and 256 colors. It has a similar look and feel to [[urxvt]], but with fewer dependencies and lower resource use.<br />
<br />
== Installation ==<br />
<br />
Termite is based on the vte terminal emulator library, and is available from the [[Arch User Repository]] in {{AUR|termite-git}}.<br />
<br />
== Usage ==<br />
<br />
Termite starts in insert mode by default. Text may be selected using the mouse, or by using command-mode keys. In insert mode, {{ic|Ctrl-Shift-c}} is used to copy selected text to the [[Xorg|X]] clipboard, {{ic|Ctrl-Shift-v}} to paste. {{ic|Ctrl-tab}} starts scrollback completion, and {{ic|Ctrl-Shift-up}} / {{ic|Ctrl-Shift-down}} scroll the screen up or down.<br />
<br />
{{ic|Ctrl-Shift-space}} enters command-mode. Many commands are borrowed from [[Vim]], for example {{ic|v}} for visual mode, {{ic|Shift-v}} for visual line mode, {{ic|Ctrl-v}} for visual block mode, {{ic|y}} to copy ("yank") selected text, {{ic|/}} and {{ic|?}} for searching, {{ic|w}}, {{ic|b}}, {{ic|^}}, {{ic|$}} for movement, and {{ic|Escape}} to go back to insert mode.<br />
<br />
== Configuration ==<br />
Termite looks for configuration files in {{ic|$XDG_CONFIG_HOME/termite/config}}, {{ic|~/.config/termite/config}}, {{ic|$XDG_CONFIG_DIRS/termite/config}} and {{ic|/etc/xdg/termite.cfg}}. The configuration file is used to change options such as font, colors, window hints, etc. The configuration file is in ''ini'' format, with three sections: ''options'', ''colors'', and ''hints''.<br />
<br />
=== Font ===<br />
Fonts are specified in the format {{ic|1=font=<font_name> <font_size>}} under the ''options'' section. {{ic|<font_name>}} is specified according to [[Font Configuration|fontconfig]], not [[X Logical Font Description|Xft]]. Use {{ic|fc-list}} to see which fonts are available on the system (see also [[Font_configuration#Font_paths]]).<br />
<br />
{{hc|~/.config/termite/config|2=<br />
[options]<br />
font = Monospace 9<br />
font = Terminus (TTF) 8<br />
font = Droid Sans Mono 8}}<br />
<br />
=== Colors ===<br />
Colors consist of either a 24-bit hex value (e.g. {{ic|#4a32b1}}), or an rgba vector (e.g. {{ic|rgba(16, 32, 64, 0.5)}}). Valid properties for colors are {{ic|foreground}}, {{ic|foreground_bold}}, {{ic|foreground_dim}}, {{ic|background}}, {{ic|cursor}}, and {{ic|colorN}} (where N is an integer from zero through 254; used to assign a 24-bit color value to terminal colorN).<br />
<br />
{{hc|~/.config/termite/config|2=<br />
[colors]<br />
foreground = #dcdccc<br />
background = #3f3f3f}}<br />
<br />
== Transparency ==<br />
As of version 9, Termite supports true transparency via color definitions that specify an alpha channel value [https://github.com/thestinger/termite/issues/191]. This requires a compositor to be running, such as [[Compton]] or {{pkg|xcompmgr}}. Most compositors do not require special configuration for Termite to use transparency.<br />
<br />
{{hc|~/.config/termite/config|2=<br />
[colors]<br />
background = rgba(63, 63, 63, 0.8)<br />
}}<br />
<br />
{{Note|At least in [[i3]], even in tiling mode, this shows all windows "stacked" on top of one another, in the order they were most recently in the foreground, rather than showing the desktop (aka. X "root window") directly behind Termite. This is probably due to i3 reordering windows rather than hiding invisible windows in tiling mode.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Colored ls output ===<br />
<br />
Due to a recent update it is necessary to use a custom LS_COLORS [[environment variable]] for colored {{ic|ls}} output. Generate a new {{ic|dircolors}} file with <br />
<br />
$ dircolors -p > ~/.dircolors<br />
<br />
Then edit {{ic|~/.dircolors}} file, and append<br />
<br />
TERM xterm-termite<br />
<br />
to the end of the list of terminals, and save the file.<br />
<br />
For [[Bash]] in {{ic|~/.bashrc}} and [[Zsh]] in {{ic|~/.zshrc}}, add:<br />
<br />
eval $(dircolors ~/.dircolors)<br />
<br />
and restart the terminal. For [[fish]], add <br />
<br />
eval (dircolors -c ~/.dircolors | sed 's/>&\/dev\/null$//')<br />
<br />
to {{ic|~/.config/fish/config.fish}} and relogin or reload the config via:<br />
<br />
. ~/.config/fish/config.fish<br />
<br />
=== Ctrl-T not working ===<br />
<br />
Ctrl-T should open a new tab, but it sometimes fails with certain shells. If the termite window outputs {{ic|no directory uri set}} when this happens, the solution is to add <br />
<br />
. /etc/profile.d/vte.sh<br />
<br />
to your {{ic|~/.zshrc}}.<br />
<br />
See [http://unix.stackexchange.com/questions/93476/gnome-terminal-keep-track-of-directory-in-new-tab this stackexchange question] for more details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/thestinger/termite/blob/master/README.rst Termite readme]</div>B6hgas5https://wiki.archlinux.org/index.php?title=Systemd&diff=341745Systemd2014-10-25T14:58:10Z<p>B6hgas5: /* Filtering output */</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Daemons and system services]]<br />
[[Category:Boot process]]<br />
[[ar:Systemd]]<br />
[[el:Systemd]]<br />
[[es:Systemd]]<br />
[[fr:Systemd]]<br />
[[it:Systemd]]<br />
[[ja:Systemd]]<br />
[[pt:Systemd]]<br />
[[ru:Systemd]]<br />
[[zh-CN:Systemd]]<br />
[[zh-TW:Systemd]]<br />
{{Related articles start}}<br />
{{Related|systemd/User}}<br />
{{Related|systemd/Services}}<br />
{{Related|systemd/Timers}}<br />
{{Related|systemd FAQ}}<br />
{{Related|init}}<br />
{{Related|init Rosetta}}<br />
{{Related|Daemons List}}<br />
{{Related|udev}}<br />
{{Related|Improve boot performance}}<br />
{{Related|Allow users to shutdown}}<br />
{{Related articles end}}<br />
<br />
From the [http://freedesktop.org/wiki/Software/systemd project web page]:<br />
<br />
:''systemd'' is a system and service manager for Linux, compatible with SysV and LSB init scripts. systemd provides aggressive parallelization capabilities, uses socket and [[D-Bus]] activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux [[cgroups|control groups]], supports snapshotting and restoring of the system state, maintains mount and automount points and implements an elaborate transactional dependency-based service control logic.<br />
<br />
{{Note|1=For a detailed explanation as to why Arch has moved to ''systemd'', see [https://bbs.archlinux.org/viewtopic.php?pid=1149530#p1149530 this forum post].}}<br />
<br />
== Basic systemctl usage ==<br />
<br />
The main command used to introspect and control ''systemd'' is ''systemctl''. Some of its uses are examining the system state and managing the system and services. See {{ic|man 1 systemctl}} for more details.<br />
<br />
{{Tip|You can use all of the following ''systemctl'' commands with the {{ic|-H ''user''@''host''}} switch to control a ''systemd'' instance on a remote machine. This will use [[SSH]] to connect to the remote ''systemd'' instance.}}<br />
<br />
{{Note|''systemadm'' is the official graphical frontend for ''systemctl''. It is provided by {{Pkg|systemd-ui}} from the [[official repositories]] or by {{AUR|systemd-ui-git}} from the [[AUR]] for the development version.}}<br />
<br />
=== Analyzing the system state ===<br />
<br />
List running units:<br />
<br />
$ systemctl<br />
<br />
or:<br />
<br />
$ systemctl list-units<br />
<br />
List failed units:<br />
<br />
$ systemctl --failed<br />
<br />
The available unit files can be seen in {{ic|/usr/lib/systemd/system/}} and {{ic|/etc/systemd/system/}} (the latter takes precedence). You can see a list of the installed unit files with:<br />
<br />
$ systemctl list-unit-files<br />
<br />
=== Using units ===<br />
<br />
Units can be, for example, services (''.service''), mount points (''.mount''), devices (''.device'') or sockets (''.socket'').<br />
<br />
When using ''systemctl'', you generally have to specify the complete name of the unit file, including its suffix, for example ''sshd.socket''. There are however a few short forms when specifying the unit in the following ''systemctl'' commands:<br />
<br />
* If you do not specify the suffix, systemctl will assume ''.service''. For example, {{ic|netcfg}} and {{ic|netcfg.service}} are equivalent.<br />
* Mount points will automatically be translated into the appropriate ''.mount'' unit. For example, specifying {{ic|/home}} is equivalent to {{ic|home.mount}}.<br />
* Similar to mount points, devices are automatically translated into the appropriate ''.device'' unit, therefore specifying {{ic|/dev/sda2}} is equivalent to {{ic|dev-sda2.device}}.<br />
<br />
See {{ic|man systemd.unit}} for details.<br />
<br />
{{Note|Some unit names contain an {{ic|@}} sign (e.g. {{ic|name@''string''.service}}): this means that they are [http://0pointer.de/blog/projects/instances.html instances] of a ''template'' unit, whose actual file name does not contain the {{ic|''string''}} part (e.g. {{ic|name@.service}}). {{ic|''string''}} is called the ''instance identifier'', and is similar to an argument that is passed to the template unit when called with the ''systemctl'' command: in the unit file it will substitute the {{ic|%i}} specifier. <br />
<br />
To be more accurate, ''before'' trying to instantiate the {{ic|name@.suffix}} template unit, ''systemd'' will actually look for a unit with the exact {{ic|name@string.suffix}} file name, although by convention such a "clash" happens rarely, i.e. most unit files containing an {{ic|@}} sign are meant to be templates. Also, if a template unit is called without an instance identifier, it will just fail, since the {{ic|%i}} specifier cannot be substituted.<br />
}}<br />
<br />
{{Tip|Most of the following commands also work if multiple units are specified, see {{ic|man systemctl}} for more information.}}<br />
<br />
Activate a unit immediately:<br />
<br />
# systemctl start ''unit''<br />
<br />
Deactivate a unit immediately:<br />
<br />
# systemctl stop ''unit''<br />
<br />
Restart a unit:<br />
<br />
# systemctl restart ''unit''<br />
<br />
Ask a unit to reload its configuration:<br />
<br />
# systemctl reload ''unit''<br />
<br />
Show the status of a unit, including whether it is running or not:<br />
<br />
$ systemctl status ''unit''<br />
<br />
Check whether a unit is already enabled or not:<br />
<br />
$ systemctl is-enabled ''unit''<br />
<br />
Enable a unit to be started on bootup:<br />
<br />
# systemctl enable ''unit''<br />
<br />
Disable a unit to not start during bootup:<br />
<br />
# systemctl disable ''unit''<br />
<br />
Show the manual page associated with a unit (this has to be supported by the unit file):<br />
<br />
$ systemctl help ''unit''<br />
<br />
Reload ''systemd'', scanning for new or changed units:<br />
<br />
# systemctl daemon-reload<br />
<br />
=== Power management ===<br />
<br />
[[polkit]] is necessary for power management as an unprivileged user. If you are in a local ''systemd-logind'' user session and no other session is active, the following commands will work without root privileges. If not (for example, because another user is logged into a tty), ''systemd'' will automatically ask you for the root password.<br />
<br />
Shut down and reboot the system:<br />
<br />
$ systemctl reboot<br />
<br />
Shut down and power-off the system:<br />
<br />
$ systemctl poweroff<br />
<br />
Suspend the system:<br />
<br />
$ systemctl suspend<br />
<br />
Put the system into hibernation:<br />
<br />
$ systemctl hibernate<br />
<br />
Put the system into hybrid-sleep state (or suspend-to-both):<br />
<br />
$ systemctl hybrid-sleep<br />
<br />
== Writing unit files ==<br />
<br />
The syntax of ''systemd'''s [http://www.freedesktop.org/software/systemd/man/systemd.unit.html unit files] is inspired by XDG Desktop Entry Specification ''.desktop'' files, which are in turn inspired by Microsoft Windows ''.ini'' files. Unit files are loaded from two locations. From lowest to highest precedence they are:<br />
<br />
* {{ic|/usr/lib/systemd/system/}}: units provided by installed packages<br />
* {{ic|/etc/systemd/system/}}: units installed by the system administrator<br />
<br />
{{Note|The load paths are completely different when running ''systemd'' in [[systemd/User#How it works|user mode]].}}<br />
<br />
Look at the units installed by your packages for examples, or see [[systemd/Services]].<br />
<br />
{{Tip|Comments prepended with {{ic|#}} may be used in unit-files as well, but only in new lines. Do not use end-line comments after ''systemd'' parameters or the unit will fail to activate.}}<br />
<br />
=== Handling dependencies ===<br />
<br />
With ''systemd'', dependencies can be resolved by designing the unit files correctly. The most typical case is that the unit ''A'' requires the unit ''B'' to be running before ''A'' is started. In that case add {{ic|1=Requires=''B''}} and {{ic|1=After=''B''}} to the {{ic|[Unit]}} section of ''A''. If the dependency is optional, add {{ic|1=Wants=''B''}} and {{ic|1=After=''B''}} instead. Note that {{ic|1=Wants=}} and {{ic|1=Requires=}} do not imply {{ic|1=After=}}, meaning that if {{ic|1=After=}} is not specified, the two units will be started in parallel.<br />
<br />
Dependencies are typically placed on services and not on targets. For example, ''network.target'' is pulled in by whatever service configures your network interfaces, therefore ordering your custom unit after it is sufficient since ''network.target'' is started anyway.<br />
<br />
=== Service types ===<br />
<br />
There are several different start-up types to consider when writing a custom service file. This is set with the {{ic|1=Type=}} parameter in the {{ic|[Service]}} section:<br />
<br />
* {{ic|1=Type=simple}} (default): ''systemd'' considers the service to be started up immediately. The process must not fork. Do not use this type if other services need to be ordered on this service, unless it is socket activated.<br />
* {{ic|1=Type=forking}}: ''systemd'' considers the service started up once the process forks and the parent has exited. For classic daemons use this type unless you know that it is not necessary. You should specify {{ic|1=PIDFile=}} as well so ''systemd'' can keep track of the main process.<br />
* {{ic|1=Type=oneshot}}: this is useful for scripts that do a single job and then exit. You may want to set {{ic|1=RemainAfterExit=yes}} as well so that ''systemd'' still considers the service as active after the process has exited.<br />
* {{ic|1=Type=notify}}: identical to {{ic|1=Type=simple}}, but with the stipulation that the daemon will send a signal to ''systemd'' when it is ready. The reference implementation for this notification is provided by ''libsystemd-daemon.so''.<br />
* {{ic|1=Type=dbus}}: the service is considered ready when the specified {{ic|BusName}} appears on DBus's system bus.<br />
* {{ic|1=Type=idle}}: behavior of idle is very similar to {{ic|1=Type=simple}}; however, actual execution of the service binary is delayed until all jobs are dispatched. This may be used to avoid interleaving of output of shell services with the status output on the console.<br />
<br />
See {{ic|man systemd.service}} for a more detailed explanation.<br />
<br />
=== Editing provided unit files ===<br />
<br />
To edit a unit file provided by a package, you can create a directory called {{ic|/etc/systemd/system/''unit''.d/}} for example {{ic|/etc/systemd/system/httpd.service.d/}} and place ''*.conf'' files in there to override or add new options. ''systemd'' will parse these ''*.conf'' files and apply them on top of the original unit. For example, if you simply want to add an additional dependency to a unit, you may create the following file:<br />
<br />
{{hc|/etc/systemd/system/''unit''.d/customdependency.conf|2=<br />
[Unit]<br />
Requires=''new dependency''<br />
After=''new dependency''<br />
}}<br />
<br />
As another example, in order to replace the {{ic|ExecStart}} directive for a unit that is not of type {{ic|oneshot}}, create the following file:<br />
<br />
{{hc|/etc/systemd/system/''unit''.d/customexec.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=''new command''<br />
}}<br />
<br />
Note how {{ic|ExecStart}} must be cleared before being re-assigned ([https://bugzilla.redhat.com/show_bug.cgi?id=756787#c9]).<br />
<br />
One more example to automatically restart a service:<br />
<br />
{{hc|/etc/systemd/system/''unit''.d/restart.conf|2=<br />
[Service]<br />
Restart=always<br />
RestartSec=30<br />
}}<br />
<br />
Then run the following for your changes to take effect:<br />
<br />
# systemctl daemon-reload<br />
# systemctl restart ''unit''<br />
<br />
Alternatively you can copy the old unit file from {{ic|/usr/lib/systemd/system/}} to {{ic|/etc/systemd/system/}} and make your changes there. A unit file in {{ic|/etc/systemd/system/}} always overrides the same unit in {{ic|/usr/lib/systemd/system/}}. Note that when the original unit in {{ic|/usr/lib/}} is changed due to a package upgrade, these changes will not automatically apply to your custom unit file in {{ic|/etc/}}. Additionally you will have to manually reenable the unit with {{ic|systemctl reenable ''unit''}}. It is therefore recommended to use the ''*.conf'' method described before instead.<br />
<br />
{{Note|You can use '''systemd-delta''' to see which unit files have been overridden and what exactly has been changed. Doing so regularly is important for system maintenance as well, to check updates the provided unit files may have received.}}<br />
<br />
{{Tip|Syntax highlighting for ''systemd'' unit files within [[Vim]] can be enabled by installing {{Pkg|vim-systemd}} from the [[official repositories]].}}<br />
<br />
== Targets ==<br />
<br />
''systemd'' uses ''targets'' which serve a similar purpose as runlevels but act a little different. Each ''target'' is named instead of numbered and is intended to serve a specific purpose with the possibility of having multiple ones active at the same time. Some ''target''s are implemented by inheriting all of the services of another ''target'' and adding additional services to it. There are ''systemd'' ''target''s that mimic the common SystemVinit runlevels so you can still switch ''target''s using the familiar {{ic|telinit RUNLEVEL}} command.<br />
<br />
=== Get current targets ===<br />
<br />
The following should be used under ''systemd'' instead of running {{ic|runlevel}}:<br />
<br />
$ systemctl list-units --type=target<br />
<br />
=== Create custom target ===<br />
<br />
The runlevels that are assigned a specific purpose on vanilla Fedora installs; 0, 1, 3, 5, and 6; have a 1:1 mapping with a specific ''systemd'' ''target''. Unfortunately, there is no good way to do the same for the user-defined runlevels like 2 and 4. If you make use of those it is suggested that you make a new named ''systemd'' ''target'' as {{ic|/etc/systemd/system/''your target''}} that takes one of the existing runlevels as a base (you can look at {{ic|/usr/lib/systemd/system/graphical.target}} as an example), make a directory {{ic|/etc/systemd/system/''your target''.wants}}, and then symlink the additional services from {{ic|/usr/lib/systemd/system/}} that you wish to enable.<br />
<br />
=== Targets table ===<br />
<br />
{| class="wikitable"<br />
! SysV Runlevel !! systemd Target !! Notes<br />
|-<br />
| 0 || runlevel0.target, poweroff.target || Halt the system.<br />
|-<br />
| 1, s, single || runlevel1.target, rescue.target || Single user mode.<br />
|-<br />
| 2, 4 || runlevel2.target, runlevel4.target, multi-user.target || User-defined/Site-specific runlevels. By default, identical to 3.<br />
|-<br />
| 3 || runlevel3.target, multi-user.target || Multi-user, non-graphical. Users can usually login via multiple consoles or via the network.<br />
|-<br />
| 5 || runlevel5.target, graphical.target || Multi-user, graphical. Usually has all the services of runlevel 3 plus a graphical login.<br />
|-<br />
| 6 || runlevel6.target, reboot.target || Reboot<br />
|-<br />
| emergency || emergency.target || Emergency shell<br />
|-<br />
|}<br />
<br />
=== Change current target ===<br />
<br />
In ''systemd'' targets are exposed via ''target units''. You can change them like this:<br />
<br />
# systemctl isolate graphical.target<br />
<br />
This will only change the current target, and has no effect on the next boot. This is equivalent to commands such as {{ic|telinit 3}} or {{ic|telinit 5}} in Sysvinit.<br />
<br />
=== Change default target to boot into ===<br />
<br />
The standard target is ''default.target'', which is aliased by default to ''graphical.target'' (which roughly corresponds to the old runlevel 5). To change the default target at boot-time, append one of the following [[kernel parameters]] to your bootloader:<br />
<br />
* {{ic|1=systemd.unit=multi-user.target}} (which roughly corresponds to the old runlevel 3),<br />
* {{ic|1=systemd.unit=rescue.target}} (which roughly corresponds to the old runlevel 1).<br />
<br />
Alternatively, you may leave the bootloader alone and change ''default.target''. This can be done using ''systemctl'':<br />
<br />
# systemctl set-default multi-user.target<br />
<br />
To be able to override the previously set ''default.target'', use the force option:<br />
<br />
# systemctl set-default -f multi-user.target<br />
<br />
The effect of this command is output by ''systemctl''; a symlink to the new default target is made at {{ic|/etc/systemd/system/default.target}}.<br />
<br />
== Temporary files ==<br />
<br />
"''systemd-tmpfiles'' creates, deletes and cleans up volatile and temporary files and directories." It reads configuration files in {{ic|/etc/tmpfiles.d/}} and {{ic|/usr/lib/tmpfiles.d/}} to discover which actions to perform. Configuration files in the former directory take precedence over those in the latter directory.<br />
<br />
Configuration files are usually provided together with service files, and they are named in the style of {{ic|/usr/lib/tmpfiles.d/''program''.conf}}. For example, the [[Samba]] daemon expects the directory {{ic|/run/samba}} to exist and to have the correct permissions. Therefore, the {{Pkg|samba}} package ships with this configuration:<br />
<br />
{{hc|/usr/lib/tmpfiles.d/samba.conf|<br />
D /run/samba 0755 root root}}<br />
<br />
Configuration files may also be used to write values into certain files on boot. For example, if you used {{ic|/etc/rc.local}} to disable wakeup from USB devices with {{ic|echo USBE > /proc/acpi/wakeup}}, you may use the following tmpfile instead:<br />
<br />
{{hc|/etc/tmpfiles.d/disable-usb-wake.conf|<br />
w /proc/acpi/wakeup - - - - USBE}}<br />
<br />
See the {{ic|systemd-tmpfiles(8)}} and {{ic|tmpfiles.d(5)}} man pages for details.<br />
<br />
{{Note|This method may not work to set options in {{ic|/sys}} since the ''systemd-tmpfiles-setup'' service may run before the appropriate device modules is loaded. In this case you could check whether the module has a parameter for the option you want to set with {{ic|modinfo ''module''}} and set this option with a [[Modprobe.d#Configuration|config file in /etc/modprobe.d]]. Otherwise you will have to write a [[Udev#About_udev_rules|udev rule]] to set the appropriate attribute as soon as the device appears.}}<br />
<br />
== Timers ==<br />
<br />
A timer is a unit configuration file whose name ends with ''.timer'' and encodes information about a timer controlled and supervised by ''systemd'', for timer-based activation. See [[systemd/Timers]].<br />
<br />
{{Note|Timers can replace ''cron'' functionality to a great extent. See [[systemd/Timers#As a cron replacement]].}}<br />
<br />
== Journal ==<br />
<br />
''systemd'' has its own logging system called the journal; therefore, running a {{ic|syslog}} daemon is no longer required. To read the log, use:<br />
<br />
# journalctl<br />
<br />
In Arch Linux, the directory {{ic|/var/log/journal/}} is a part of the {{Pkg|systemd}} package, and the journal (when {{ic|1=Storage=}} is set to {{ic|auto}} in {{ic|/etc/systemd/journald.conf}}) will write to {{ic|/var/log/journal/}}. If you or some program delete that directory, ''systemd'' will '''not''' recreate it automatically; however, it will be recreated during the next update of the ''systemd'' package. Until then, logs will be written to {{ic|/run/systemd/journal}}, and logs will be lost on reboot.<br />
<br />
{{Tip|If {{ic|/var/log/journal/}} resides in a [[btrfs]] file system, you should consider disabling Copy-on-Write for the directory. See the main article for details: [[Btrfs#Copy-On-Write (CoW)]].}}<br />
<br />
=== Filtering output ===<br />
<br />
''journalctl'' allows you to filter the output by specific fields. Be aware that if there are many messages to display or filtering of large time span has to be done, the output of this command can be delayed for quite some time.<br />
<br />
{{Tip|While the journal is stored in a binary format, the content of stored messages is not modified. This means it is viewable with ''strings'', for example for recovery in an environment which does not have ''systemd'' installed. Example command:<br />
{{ic|$ strings /mnt/arch/var/log/journal/af4967d77fba44c6b093d0e9862f6ddd/system.journal <nowiki>| grep</nowiki> ''message''}}<br />
}}<br />
<br />
Examples:<br />
<br />
* Show all messages from this boot: {{bc|# journalctl -b}} However, often one is interested in messages not from the current, but from the previous boot (e.g. if an unrecoverable system crash happened). This is possible through optional offset parameter of the {{ic|-b}} flag: {{ic|journalctl -b -0}} shows messages from the current boot, {{ic|journalctl -b -1}} from the previous boot, {{ic|journalctl -b -2}} from the second previous and so on. See {{ic|man 1 journalctl}} for full description, the semantics is much more powerful.<br />
* Show all messages from date (and optional time): {{bc|1=# journalctl --since="2012-10-30 18:17:16"}}<br />
* Show all messages since 20 minutes ago: {{bc|1=# journalctl --since "20 min ago"}}<br />
* Follow new messages: {{bc|# journalctl -f}}<br />
* Show all messages by a specific executable: {{bc|# journalctl /usr/lib/systemd/systemd}}<br />
* Show all messages by a specific process: {{bc|1=# journalctl _PID=1}}<br />
* Show all messages by a specific unit: {{bc|# journalctl -u netcfg}}<br />
* Show kernel ring buffer: {{bc|1=# journalctl -k}}<br />
<br />
See {{ic|man 1 journalctl}}, {{ic|man 7 systemd.journal-fields}}, or Lennart's [http://0pointer.de/blog/projects/journalctl.html blog post] for details.<br />
<br />
{{Tip|1=<br />
By default, ''journalctl'' truncates lines longer than screen width, but in some cases, it may be better to enable wrapping instead of truncating. This can be controlled by the {{ic|SYSTEMD_LESS}} [[Environment variables|environment variable]], which contains options passed to [[Core utilities#less|less]] (the default pager) and defaults to {{ic|FRSXMK}} (see {{ic|man 1 less}} and {{ic|man 1 journalctl}} for details).<br />
<br />
By omitting the {{ic|S}} option, the output will be wrapped instead of truncated. For example, start ''journalctl'' as follows:<br />
<br />
$ SYSTEMD_LESS=FRXMK journalctl<br />
<br />
If you'd like set this behaviour as default, [[Environment variables#Defining variables locally|export]] the variable from {{ic|~/.bashrc}} or {{ic|~/.zshrc}}.<br />
}}<br />
<br />
=== Journal size limit ===<br />
<br />
If the journal is persistent (non-volatile), its size limit is set to a default value of 10% of the size of the respective file system. For example, with {{ic|/var/log/journal}} located on a 50 GiB root partition this would lead to 5 GiB of journal data. The maximum size of the persistent journal can be controlled by {{ic|SystemMaxUse}} in {{ic|/etc/systemd/journald.conf}}, so to limit it for example to 50 MiB uncomment and edit the corresponding line to:<br />
<br />
SystemMaxUse=50M<br />
<br />
Refer to {{ic|man journald.conf}} for more info.<br />
<br />
=== Journald in conjunction with syslog ===<br />
<br />
Compatibility with a classic [[Syslog-ng|syslog]] implementation can be provided by letting ''systemd'' forward all messages via the socket {{ic|/run/systemd/journal/syslog}}. To make the syslog daemon work with the journal, it has to bind to this socket instead of {{ic|/dev/log}} ([http://lwn.net/Articles/474968/ official announcement]). The {{Pkg|syslog-ng}} package in the repositories automatically provides the necessary configuration. <br />
<br />
As of ''systemd'' 216 the default {{ic|journald.conf}} for forwarding to the socket is {{ic|no}}. This means you will need to set the option {{ic|1=ForwardToSyslog=yes}} in {{ic|/etc/systemd/journald.conf}} to actually use ''syslog-ng'' with ''journald''. See [[Syslog-ng#Overview]] for details. <br />
<br />
If you use {{Pkg|rsyslog}} instead, it is not necessary to change the option because [[rsyslog]] pulls the messages from the journal by [http://lists.freedesktop.org/archives/systemd-devel/2014-August/022295.html#journald itself].<br />
<br />
=== Forward journald to /dev/tty12 ===<br />
<br />
In {{ic|/etc/systemd/journald.conf}} enable the following:<br />
<br />
ForwardToConsole=yes<br />
TTYPath=/dev/tty12<br />
MaxLevelConsole=info<br />
<br />
Restart journald with:<br />
<br />
# systemctl restart systemd-journald<br />
<br />
== Troubleshooting ==<br />
<br />
=== Investigating systemd errors ===<br />
<br />
As an example, we will investigate an error with {{ic|systemd-modules-load}} service:<br />
<br />
'''1.''' Lets find the ''systemd'' services which fail to start:<br />
<br />
{{hc|1=$ systemctl --state=failed|2=<br />
systemd-modules-load.service loaded '''failed failed''' Load Kernel Modules<br />
}}<br />
<br />
'''2.''' Ok, we found a problem with {{ic|systemd-modules-load}} service. We want to know more:<br />
{{hc|$ systemctl status systemd-modules-load|2=<br />
systemd-modules-load.service - Load Kernel Modules<br />
Loaded: loaded (/usr/lib/systemd/system/systemd-modules-load.service; static)<br />
Active: '''failed''' (Result: exit-code) since So 2013-08-25 11:48:13 CEST; 32s ago<br />
Docs: man:systemd-modules-load.service(8).<br />
man:modules-load.d(5)<br />
Process: '''15630''' ExecStart=/usr/lib/systemd/systemd-modules-load ('''code=exited, status=1/FAILURE''')<br />
}}<br />
If the {{ic|Process ID}} is not listed, just restart the failed service with {{ic|systemctl restart systemd-modules-load}}<br />
<br />
'''3.''' Now we have the process id (PID) to investigate this error in depth. Enter the following command with the current {{ic|Process ID}} (here: 15630):<br />
{{hc|1=$ journalctl -b _PID=15630|2=<br />
-- Logs begin at Sa 2013-05-25 10:31:12 CEST, end at So 2013-08-25 11:51:17 CEST. --<br />
Aug 25 11:48:13 mypc systemd-modules-load[15630]: '''Failed to find module 'blacklist usblp''''<br />
Aug 25 11:48:13 mypc systemd-modules-load[15630]: '''Failed to find module 'install usblp /bin/false'''' <br />
}}<br />
<br />
'''4.''' We see that some of the kernel module configs have wrong settings. Therefore we have a look at these settings in {{ic|/etc/modules-load.d/}}:<br />
{{hc|$ ls -Al /etc/modules-load.d/|<br />
...<br />
-rw-r--r-- 1 root root 79 1. Dez 2012 blacklist.conf<br />
-rw-r--r-- 1 root root 1 2. Mär 14:30 encrypt.conf<br />
-rw-r--r-- 1 root root 3 5. Dez 2012 printing.conf<br />
-rw-r--r-- 1 root root 6 14. Jul 11:01 realtek.conf<br />
-rw-r--r-- 1 root root 65 2. Jun 23:01 virtualbox.conf<br />
...<br />
}}<br />
<br />
'''5.''' The {{ic|Failed to find module 'blacklist usblp'}} error message might be related to a wrong setting inside of {{ic|blacklist.conf}}. Lets deactivate it with inserting a trailing '''#''' before each option we found via step 3:<br />
{{hc|/etc/modules-load.d/blacklist.conf|<br />
'''#''' blacklist usblp<br />
'''#''' install usblp /bin/false<br />
}}<br />
<br />
'''6.''' Now, try to start {{ic|systemd-modules-load}}:<br />
$ systemctl start systemd-modules-load<br />
If it was successful, this should not prompt anything. If you see any error, go back to step 3 and use the new PID for solving the errors left.<br />
<br />
If everything is ok, you can verify that the service was started successfully with:<br />
{{hc|$ systemctl status systemd-modules-load|2=<br />
systemd-modules-load.service - Load Kernel Modules<br />
Loaded: '''loaded''' (/usr/lib/systemd/system/systemd-modules-load.service; static)<br />
Active: '''active (exited)''' since So 2013-08-25 12:22:31 CEST; 34s ago<br />
Docs: man:systemd-modules-load.service(8)<br />
man:modules-load.d(5)<br />
Process: 19005 ExecStart=/usr/lib/systemd/systemd-modules-load (code=exited, status=0/SUCCESS)<br />
Aug 25 12:22:31 mypc systemd[1]: '''Started Load Kernel Modules'''.<br />
}}<br />
<br />
Often you can solve these kind of problems like shown above. For further investigation look at [[#Diagnosing boot problems]].<br />
<br />
=== Diagnosing boot problems ===<br />
<br />
Boot with these parameters on the kernel command line:<br />
{{ic|<nowiki>systemd.log_level=debug systemd.log_target=kmsg log_buf_len=1M</nowiki>}}<br />
<br />
[http://freedesktop.org/wiki/Software/systemd/Debugging More Debugging Information].<br />
<br />
=== Diagnosing problems with a specific service ===<br />
<br />
If some ''systemd'' service misbehaves and you want to get more information about what is going on, set the {{ic|SYSTEMD_LOG_LEVEL}} [[environment variable]] to {{ic|debug}}. For example, to run the ''systemd-networkd'' daemon in debug mode:<br />
<br />
# systemctl stop systemd-networkd<br />
# SYSTEMD_LOG_LEVEL=debug /lib/systemd/systemd-networkd<br />
<br />
Or, equivalently, modify the service file temporarily for gathering enough output. For example: <br />
<br />
{{hc|/lib/systemd/system/systemd-networkd.service|2=<br />
[Service]<br />
...<br />
Environment=SYSTEMD_LOG_LEVEL=debug<br />
....<br />
}}<br />
<br />
If debug information is required long-term, add the variable the [[#Editing provided unit files|regular]] way.<br />
<br />
=== Shutdown/reboot takes terribly long ===<br />
<br />
If the shutdown process takes a very long time (or seems to freeze) most likely a service not exiting is to blame. ''systemd'' waits some time for each service to exit before trying to kill it. To find out if you are affected, see [http://freedesktop.org/wiki/Software/systemd/Debugging/#shutdowncompleteseventually this article].<br />
<br />
=== Short lived processes do not seem to log any output ===<br />
<br />
If {{ic|journalctl -u foounit}} does not show any output for a short lived service, look at the PID instead. For example, if {{ic|systemd-modules-load.service}} fails, and {{ic|systemctl status systemd-modules-load}} shows that it ran as PID 123, then you might be able to see output in the journal for that PID, i.e. {{ic|journalctl -b _PID&#61;123}}. Metadata fields for the journal such as _SYSTEMD_UNIT and _COMM are collected asynchronously and rely on the {{ic|/proc}} directory for the process existing. Fixing this requires fixing the kernel to provide this data via a socket connection, similar to SCM_CREDENTIALS.<br />
<br />
=== Disabling application crash dumps journaling ===<br />
<br />
{{Accuracy|{{ic|/etc/sysctl.d}} overwrite files of the same name, however {{ic|50-coredump.conf}} is no longer present in Arch; journal dump behaviour is regulated in {{ic|/etc/systemd/coredump.conf}} [http://www.freedesktop.org/software/systemd/man/coredump.conf.html]. Core dumps are by default not written to the journal, but to {{ic|/var/lib/systemd/coredump}}.}}<br />
<br />
Run the following in order to overwrite the settings from {{ic|/lib/sysctl.d/}}:<br />
<br />
# ln -s /dev/null /etc/sysctl.d/50-coredump.conf<br />
# sysctl kernel.core_pattern=core<br />
<br />
This will disable logging of coredumps to the journal.<br />
<br />
Note that the default RLIMIT_CORE of 0 means that no core files are written, either.<br />
If you want them, you also need to "unlimit" the core file size in the shell:<br />
<br />
$ ulimit -c unlimited<br />
<br />
See [http://www.freedesktop.org/software/systemd/man/sysctl.d.html sysctl.d] and [https://www.kernel.org/doc/Documentation/sysctl/kernel.txt the documentation for /proc/sys/kernel] for more information.<br />
<br />
=== Error message on reboot or shutdown ===<br />
<br />
==== cgroup : option or name mismatch, new: 0x0 "", old: 0x4 "systemd" ====<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1372562#p1372562 this thread] for an explanation.<br />
<br />
==== watchdog watchdog0: watchdog did not stop! ====<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1372562#p1372562 this thread] for an explanation.<br />
<br />
=== Boot time increasing over time ===<br />
<br />
After using {{ic|systemd-analyze}} a number of users have noticed that their boot time has increased significantly in comparison with what it used to be. After using {{ic|systemd-analyze blame}} [[NetworkManager]] is being reported as taking an unusually large amount of time to start. <br />
<br />
The problem for some users has been due to {{ic|/var/log/journal}} becoming too large. This may have other impacts on performance, such as for {{ic|systemctl status}} or {{ic|journalctl}}. As such the solution is to remove every file within the folder (ideally making a backup of it somewhere, at least temporarily) and then setting a journal file size limit as described in [[#Journal size limit]].<br />
<br />
== See also ==<br />
<br />
*[http://www.freedesktop.org/wiki/Software/systemd Official web site]<br />
*[[Wikipedia:systemd|Wikipedia article]]<br />
*[http://0pointer.de/public/systemd-man/ Manual pages]<br />
*[http://freedesktop.org/wiki/Software/systemd/Optimizations systemd optimizations]<br />
*[http://www.freedesktop.org/wiki/Software/systemd/FrequentlyAskedQuestions FAQ]<br />
*[http://www.freedesktop.org/wiki/Software/systemd/TipsAndTricks Tips and tricks]<br />
*[http://0pointer.de/public/systemd-ebook-psankar.pdf systemd for Administrators (PDF)]<br />
*[http://fedoraproject.org/wiki/Systemd About systemd on Fedora Project]<br />
*[http://fedoraproject.org/wiki/How_to_debug_Systemd_problems How to debug systemd problems]<br />
*[http://www.h-online.com/open/features/Control-Centre-The-systemd-Linux-init-system-1565543.html Two] [http://www.h-online.com/open/features/Booting-up-Tools-and-tips-for-systemd-1570630.html part] introductory article in ''The H Open'' magazine.<br />
*[http://0pointer.de/blog/projects/systemd.html Lennart's blog story]<br />
*[http://0pointer.de/blog/projects/systemd-update.html Status update]<br />
*[http://0pointer.de/blog/projects/systemd-update-2.html Status update2]<br />
*[http://0pointer.de/blog/projects/systemd-update-3.html Status update3]<br />
*[http://0pointer.de/blog/projects/why.html Most recent summary]<br />
*[http://fedoraproject.org/wiki/SysVinit_to_Systemd_Cheatsheet Fedora's SysVinit to systemd cheatsheet]<br />
*[http://wiki.gentoo.org/wiki/Systemd Gentoo Wiki systemd page]</div>B6hgas5https://wiki.archlinux.org/index.php?title=GRUB&diff=339925GRUB2014-10-13T13:58:26Z<p>B6hgas5: /* Generating main configuration file */</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[ar:GRUB]]<br />
[[cs:GRUB2]]<br />
[[de:GRUB]]<br />
[[el:GRUB]]<br />
[[es:GRUB]]<br />
[[fr:GRUB2]]<br />
[[id:GRUB2]]<br />
[[it:GRUB2]]<br />
[[ja:GRUB]]<br />
[[ru:GRUB]]<br />
[[tr:GRUB2]]<br />
[[zh-CN:GRUB2]]<br />
[[zh-TW:GRUB2]]<br />
{{Related articles start}}<br />
{{Related|GRUB Legacy}}<br />
{{Related|Arch boot process}}<br />
{{Related|Boot loaders}}<br />
{{Related|Master Boot Record}}<br />
{{Related|GUID Partition Table}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related|GRUB EFI Examples}}<br />
{{Related articles end}}<br />
[https://www.gnu.org/software/grub/ GRUB] — not to be confused with [[GRUB Legacy]] — is the next generation of the GRand Unified Bootloader. GRUB is derived from [http://www.nongnu.org/pupa/ PUPA] which was a research project to develop the next generation of what is now GRUB Legacy. GRUB has been rewritten from scratch to clean up everything and provide modularity and portability [https://www.gnu.org/software/grub/grub-faq.html#q1].<br />
<br />
In brief, the ''bootloader'' is the first software program that runs when a computer starts. It is responsible for loading and transferring control to the Linux kernel. The kernel, in turn, initializes the rest of the operating system.<br />
<br />
== Preface ==<br />
* The name ''GRUB'' officially refers to version ''2'' of the software, see [https://www.gnu.org/software/grub/]. If you are looking for the article on the legacy version, see [[GRUB Legacy]].<br />
* GRUB supports [[Btrfs]] as root (without a separate {{ic|/boot}} file system) compressed with either zlib or LZO<br />
* GRUB does not support [[F2fs]] as root so you will need a separate {{ic|/boot}} with a supported file system.<br />
<br />
=== Notes for GRUB Legacy users ===<br />
* Upgrading from [[GRUB Legacy]] to GRUB is much the same as freshly installing GRUB. This topic is covered [[#Installation|here]].<br />
* There are differences in the commands of GRUB Legacy and GRUB. Familiarize yourself with [https://www.gnu.org/software/grub/manual/grub.html#Commands GRUB commands] before proceeding (e.g. "find" has been replaced with "search").<br />
* GRUB is now ''modular'' and no longer requires "stage 1.5". As a result, the bootloader itself is limited -- modules are loaded from the hard drive as needed to expand functionality (e.g. for [[LVM]] or RAID support).<br />
* Device naming has changed between GRUB Legacy and GRUB. Partitions are numbered from 1 instead of 0 while drives are still numbered from 0, and prefixed with partition-table type. For example, {{ic|/dev/sda1}} would be referred to as {{ic|(hd0,msdos1)}} (for MBR) or {{ic|(hd0,gpt1)}} (for GPT).<br />
* GRUB is noticeably bigger than GRUB legacy (occupies ~13 MB in {{ic|/boot}}). If you are booting from a separate {{ic|/boot}} partition, and this partition is smaller than 32 MB, you will run into disk space issues, and pacman will refuse to install new kernels.<br />
<br />
==== Backup important data ====<br />
Although a GRUB installation should run smoothly, it is strongly recommended to keep the GRUB Legacy files before upgrading to GRUB v2.<br />
<br />
# mv /boot/grub /boot/grub-legacy<br />
<br />
Backup the MBR which contains the boot code and partition table (replace {{ic|/dev/sd''X''}} with your actual disk path):<br />
<br />
# dd if=/dev/sd''X'' of=/path/to/backup/mbr_backup bs=512 count=1<br />
<br />
Only 446 bytes of the MBR contain boot code, the next 64 contain the partition table. If you do not want to overwrite your partition table when restoring, it is strongly advised to backup only the MBR boot code:<br />
<br />
# dd if=/dev/sd''X'' of=/path/to/backup/bootcode_backup bs=446 count=1<br />
<br />
If unable to install GRUB2 correctly, see [[#Restore GRUB Legacy|Restore GRUB Legacy]].<br />
<br />
=== Preliminary requirements ===<br />
==== BIOS systems ====<br />
===== GUID Partition Table (GPT) specific instructions =====<br />
<br />
On a BIOS/[[GPT]] configuration a [http://www.gnu.org/software/grub/manual/html_node/BIOS-installation.html BIOS boot partition] is required. GRUB embeds its {{ic|core.img}} into this partition.<br />
<br />
{{Note|<br />
* Before attempting this method keep in mind that not all systems will be able to support this partitioning scheme, read more on [[GUID_Partition_Table#BIOS_systems|GUID partition tables]].<br />
* This additional partition is only needed on a GRUB, BIOS/GPT partitioning scheme. Previously, for a GRUB, BIOS/MBR partitioning scheme, GRUB used the Post-MBR gap for the embedding the {{ic|core.img}}). GRUB for GPT, however, does not use the Post-GPT gap to confirm to GPT specifications that require 1_mebibyte/2048_sector disk boundaries.<br />
* For [[UEFI]] systems this extra partition is not required as no embedding of boot sectors takes place in that case.}}<br />
<br />
Create a mebibyte partition {{{ic|1=+1MiB}} with {{ic|gdisk}}) on the disk with no file system and type {{ic|ef02}} (or {{ic|bios_grub}} in {{ic|parted}}). This partition can be in any position order but has to be on the first 2 TiB of the disk. This partition needs to be created before GRUB installation. When the partition is ready, install the bootloader as per the instructions below and be sure to include the {{ic|1=--target=i386-pc}} option (as GRUB may mistaken the configuration as EFI-GPT).<br />
<br />
The Post-GPT gap can also be used as the BIOS boot partition though it will be out of GPT alignment specification. Since the partition will not be regularly accessed performance issues can be disregarded (though some disk utilities will display a warning about it). In {{ic|gdisk}} create a '''n'''ew partition starting at sector 34 and spanning to 2047 and set the type. To to have the viewable partitions begin at the base consider adding this partition last.<br />
<br />
===== Master Boot Record (MBR) specific instructions =====<br />
Usually the post-[[MBR]] gap (after the 512 byte MBR region and before the start of the 1st partition) in many MBR (or msdos disklabel) partitioned systems is 31 KiB when DOS compatibility cylinder alignment issues are satisfied in the partition table. However a post-MBR gap of about 1 to 2 MiB is recommended to provide sufficient room for embedding GRUB's {{ic|core.img}} ({{bug|24103}}). It is advisable to use a partitioner which supports 1 MiB partition alignment to obtain this space as well as satisfy other non-512 byte sector issues (which are unrelated to embedding of {{ic|core.img}}).<br />
<br />
==== UEFI systems ====<br />
{{Note|It is recommended to read and understand the [[UEFI]], [[GPT]] and [[UEFI Bootloaders]] pages.}}<br />
<br />
===== Check if you have GPT and an ESP =====<br />
An EFI System Partition (ESP) is needed on every disc you want to boot using EFI. GPT is not strictly necessary, but it is highly recommended and is the only method currently supported in this article. If you are installing Arch Linux on an EFI-capable computer with an already-working operating system, like Windows 8 for example, it is very likely that you already have an ESP. To check for GPT and for an ESP, use {{ic|parted}} as root to print the partition table of the disk you want to boot from. (We are calling it {{ic|/dev/sda}}.)<br />
<br />
# parted /dev/sda print<br />
<br />
For GPT, you are looking for "Partition Table: GPT". For EFI, you are looking for a small (512 MiB or less) partition with a vfat file system and the ''boot'' flag enabled. On it, there should be a directory named "EFI". If these criteria are met, this is your ESP. Make note of the partition number. You will need to know which one it is, so you can mount it later on while installing GRUB to it.<br />
<br />
===== Create an ESP =====<br />
If you do not have an ESP, you will need to create it. Follow [[UEFI#EFI System Partition]] for instructions on creating an ESP.<br />
<br />
== Installation ==<br />
{{Note|If you are performing an [[Installation guide|initial installation]] from the Arch live CD, make sure you have chrooted into the installed system before installing grub. Using the CD's own grub installation scripts may result in an invalid {{ic|grub.cfg}}, or other problems that will prevent the system from booting.}}<br />
<br />
=== BIOS systems ===<br />
GRUB can be [[pacman|installed]] with the {{Pkg|grub}} package from the [[official repositories]]. It will replace {{AUR|grub-legacy}} , if it is installed.<br />
<br />
{{Note|Simply installing the package will not update the {{ic|/boot/grub/i386-pc/core.img}} file and the GRUB modules in {{ic|/boot/grub/i386-pc}}. You need to update them manually using {{ic|grub-install}} as explained below.}}<br />
<br />
==== Install boot files ====<br />
There are 4 ways to install GRUB boot files in BIOS booting:<br />
<br />
* [[#Install to disk|Install to disk]] (recommended)<br />
* [[#Install to external USB stick|Install to external USB stick]] (for recovery)<br />
* [[#Install to partition or partitionless disk|Install to partition or partitionless disk]] (not recommended)<br />
* [[#Generate core.img alone|Generate core.img alone]] (safest method, but requires another BIOS bootloader like [[Syslinux]] to be installed to chainload {{ic|/boot/grub/i386-pc/core.img}})<br />
<br />
{{Note|See https://www.gnu.org/software/grub/manual/html_node/BIOS-installation.html for additional documentation.}}<br />
<br />
===== Install to disk =====<br />
{{Note|The method is specific to installing GRUB to a partitioned (MBR or GPT) disk, with GRUB files installed to {{ic|/boot/grub}} and its first stage code installed to the 440-byte MBR boot code region (not to be confused with MBR partition table). For partitionless disk (super-floppy) please refer to [[#Install to partition or partitionless disk]]}}<br />
<br />
To set up GRUB in the 440-byte Master Boot Record boot code region, populate the {{ic|/boot/grub}} directory, generate the {{ic|/boot/grub/i386-pc/core.img}} file, and embed it in the 31 KiB (minimum size - varies depending on partition alignment) post-MBR gap in case of MBR partitioned disk (or BIOS Boot Partition in case of GPT partitioned disk, denoted by {{ic|bios_grub}} flag in parted and EF02 type code in gdisk), run:<br />
<br />
# grub-install --target=i386-pc --recheck --debug /dev/sd''x''<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note| {{ic|1=--target=i386-pc}} instructs {{ic|grub-install}} to install for BIOS systems only. It is recommended to always use this option to remove ambiguity in grub-install.<br />
}}<br />
<br />
If you use [[LVM]] for your {{ic|/boot}}, you can install GRUB on multiple physical disks.<br />
<br />
===== Install to external USB stick =====<br />
Assume your USB stick's first partition is FAT32 and it's partition is /dev/sdy1<br />
<br />
# mkdir -p /mnt/usb ; mount /dev/sdy1 /mnt/usb <br />
# grub-install --target=i386-pc --recheck --debug --boot-directory=/mnt/usb/boot /dev/sdy<br />
# grub-mkconfig -o /mnt/usb/boot/grub/grub.cfg<br />
<br />
# optional, backup config files of grub.cfg<br />
# mkdir -p /mnt/usb/etc/default<br />
# cp /etc/default/grub /mnt/usb/etc/default<br />
# cp -a /etc/grub.d /mnt/usb/etc<br />
<br />
# sync ; umount /mnt/usb<br />
<br />
===== Install to partition or partitionless disk =====<br />
{{Note|GRUB does not encourage installation to a partition boot sector or a partitionless disk like GRUB Legacy or Syslinux does. This kind of setup is prone to breakage, especially during updates, and is not supported by Arch devs.}}<br />
<br />
To set up grub to a partition boot sector, to a partitionless disk (also called superfloppy) or to a floppy disk, run (using for example {{ic|/dev/sdaX}} as the {{ic|/boot}} partition):<br />
<br />
# chattr -i /boot/grub/i386-pc/core.img<br />
# grub-install --target=i386-pc --recheck --debug --force /dev/sdaX<br />
# chattr +i /boot/grub/i386-pc/core.img<br />
<br />
{{Note|<br />
* {{ic|/dev/sdaX}} used for example only.<br />
* {{ic|1=--target=i386-pc}} instructs {{ic|grub-install}} to install for BIOS systems only. It is recommended to always use this option to remove ambiguity in ''grub-install''.<br />
}}<br />
<br />
You need to use the {{ic|--force}} option to allow usage of blocklists and should not use {{ic|1=--grub-setup=/bin/true}} (which is similar to simply generating {{ic|core.img}}).<br />
<br />
{{ic|grub-install}} will give out warnings like which should give you the idea of what might go wrong with this approach:<br />
<br />
/sbin/grub-setup: warn: Attempting to install GRUB to a partitionless disk or to a partition. This is a BAD idea.<br />
/sbin/grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists. <br />
However, blocklists are UNRELIABLE and their use is discouraged.<br />
<br />
Without {{ic|--force}} you may get the below error and {{ic|grub-setup}} will not setup its boot code in the partition boot sector:<br />
<br />
/sbin/grub-setup: error: will not proceed with blocklists<br />
<br />
With {{ic|--force}} you should get:<br />
<br />
Installation finished. No error reported.<br />
<br />
The reason why {{ic|grub-setup}} does not by default allow this is because in case of partition or a partitionless disk is that GRUB relies on embedded blocklists in the partition bootsector to locate the {{ic|/boot/grub/i386-pc/core.img}} file and the prefix directory {{ic|/boot/grub}}. The sector locations of {{ic|core.img}} may change whenever the file system in the partition is being altered (files copied, deleted etc.). For more info, see https://bugzilla.redhat.com/show_bug.cgi?id=728742 and https://bugzilla.redhat.com/show_bug.cgi?id=730915.<br />
<br />
The workaround for this is to set the immutable flag on {{ic|/boot/grub/i386-pc/core.img}} (using {{ic|chattr}} command as mentioned above) so that the sector locations of the {{ic|core.img}} file in the disk is not altered. The immutable flag on {{ic|/boot/grub/i386-pc/core.img}} needs to be set only if GRUB is installed to a partition boot sector or a partitionless disk, not in case of installation to MBR or simple generation of {{ic|core.img}} without embedding any bootsector (mentioned above).<br />
<br />
Unfortunately, the grub.cfg file that is created will not contain the proper UUID in order to boot, even if it reports no errors. see https://bbs.archlinux.org/viewtopic.php?pid=1294604#p1294604. <br />
In order to fix this issue the following commands:<br />
<br />
# mount /dev/sdxY /mnt #Your root partition.<br />
# mount /dev/sdxZ /mnt/boot #Your boot partition (if you have one).<br />
# arch-chroot /mnt<br />
# pacman -S linux<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
===== Generate core.img alone =====<br />
To populate the {{ic|/boot/grub}} directory and generate a {{ic|/boot/grub/i386-pc/core.img}} file '''without''' embedding any GRUB bootsector code in the MBR, post-MBR region, or the partition bootsector, add {{ic|1=--grub-setup=/bin/true}} to {{ic|grub-install}}:<br />
<br />
# grub-install --target=i386-pc --grub-setup=/bin/true --recheck --debug /dev/sda<br />
<br />
{{Note|<br />
* {{ic|/dev/sda}} used for example only.<br />
* {{ic|1=--target=i386-pc}} instructs {{ic|grub-install}} to install for BIOS systems only. It is recommended to always use this option to remove ambiguity in grub-install.<br />
}}<br />
<br />
You can then chainload GRUB's {{ic|core.img}} from GRUB Legacy or syslinux as a Linux kernel or as a multiboot kernel.<br />
<br />
=== UEFI systems ===<br />
{{Note|UEFI firmware are not implemented consistently by hardware manufacturers. The installation examples provided are intended to work on the widest range of UEFI systems possible. Those experiencing problems despite applying these methods are encouraged to share detailed information for their hardware-specific cases, especially where solving these problems. A [[GRUB EFI Examples]] article has been provided for such cases.}}<br />
<br />
Install {{Pkg|grub}}, {{Pkg|dosfstools}} (manipulate UEFI partitions post-installation), and {{Pkg|efibootmgr}} (create bootable {{ic|.efi}} stub entries, used by the grub installation script). <br />
<br />
Simply installing the packages will not update the {{ic|core.efi}} file and the GRUB modules in the UEFI partition. This is undertaken by running the automated grub installation script, as explained below.<br />
<br />
==== Recommended installation method ====<br />
{{note|The below command assumes you are using installing GRUB for x86_64 systems ({{ic|x86_64-efi}}). For i686 systems replace {{ic|x86_64-efi}} with {{ic|i386-efi}} in the below commands. It is also necessary to ensure that the installation medium has been booted via UEFI - not in legacy mode - as otherwise the installation may fail.}}<br />
<br />
First, ensure that the UEFI partition has been mounted (e.g. created as {{ic|/boot}} or {{ic|/boot/efi}}). Grub is not particular about the mountpoint, so either will be fine. Once complete, the following command will install the GRUB UEFI application to {{ic|$esp/EFI/grub}}, install its modules to {{ic|/boot/grub/x86_64-efi}}, and place the bootable {{ic|grubx64.efi}} stub in {{ic|$esp/EFI/arch_grub}}:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=$esp --bootloader-id=arch_grub --recheck --debug<br />
<br />
{{Note|<br />
* If you have a problem when running grub-install with sysfs or procfs and it says you have to "modprobe efivars", try [[Unified_Extensible_Firmware_Interface#Switch_to_efivarfs]].<br />
* When installing GRUB on a LVM system in a chroot environment (e.g. during System installation), you may receive warnings like {{ic|/run/lvm/lvmetad.socket: connect failed: No such file or directory}} or {{ic|WARNING: failed to connect to lvmetad: No such file or directory. Falling back to internal scanning.}} This is because {{ic|/run}} is not available inside the chroot. These warnings will not prevent the system from booting, provided that everything has been done correctly, so you may continue with the installation.<br />
* Without {{ic|--target}} or {{ic|--directory}} option, grub-install cannot determine for which firmware to install. In such cases {{ic|grub-install}} will print {{ic|source_dir does not exist. Please specify --target or --directory}}.<br />
* {{ic|--efi-directory}} and {{ic|--bootloader-id}} are specific to GRUB UEFI. {{ic|--efi-directory}} specifies the mountpoint of the ESP. It replaces {{ic|--root-directory}}, which is deprecated. {{ic|--bootloader-id}} specifies the name of the directory used to store the {{ic|grubx64.efi}} file.<br />
* If you notice carefully, there is no <device_path> option (Eg: {{ic|/dev/sda}}) at the end of the {{ic|grub-install}} command unlike the case of setting up GRUB for BIOS systems. Any <device_path> provided will be ignored by the install script, as UEFI bootloaders do not use MBR or Partition boot sectors at all.<br />
}}<br />
<br />
GRUB is now installed. Do not forget to [[#Generating main configuration file|generate the main configuration file]].<br />
<br />
===== UEFI firmware workaround =====<br />
Some UEFI firmware requires that the bootable {{ic|.efi}} stub have a specific name and be placed in a specific location: {{ic|$esp/EFI/boot/bootx64.efi}} (where {{ic|$esp}} is the UEFI partition mountpoint). Failure to do so in such instances will result in an unbootable installation. Fortunately, this will not cause any problems with other firmware that does not require this.<br />
<br />
To do so, first create the necessary directory, and then copy across the grub {{ic|.efi}} stub, renaming it in the process:<br />
<br />
# mkdir $esp/EFI/boot<br />
# cp $esp/EFI/arch_grub/grubx64.efi $esp/EFI/boot/bootx64.efi<br />
<br />
==== Alternative method ====<br />
If you want to keep all of the GRUB boot files inside the EFI System Partition itself, add {{ic|--boot-directory&#61;$esp/EFI}} to the grub-install command:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=$esp --bootloader-id=grub --boot-directory=$esp/EFI --recheck --debug<br />
<br />
This puts the GRUB modules in {{ic|$esp/EFI/grub}}. ('/grub' is hard coded onto the end of this path.) Using this method, grub.cfg is kept on the EFI System Partition as well, so make sure you point grub-mkconfig to the right place in the configuration phase:<br />
<br />
# grub-mkconfig -o $esp/EFI/grub/grub.cfg<br />
<br />
Configuration is otherwise the same.<br />
<br />
==== Create a GRUB entry in the firmware boot manager ====<br />
{{ic|grub-install}} automatically tries to create a menu entry in the boot manager. If it does not, then see [[UEFI#efibootmgr]] for instructions to use {{ic|efibootmgr}} to create a menu entry. However, the problem is likely to be that you have not booted your CD/USB in UEFI mode, as in [[UEFI#Create UEFI bootable USB from ISO]].<br />
<br />
==== GRUB standalone ====<br />
It is possible to create a {{ic|grubx64_standalone.efi}} application which has all the modules embedded in a tar archive within the UEFI application, thus removing the need for having a separate directory populated with all of the GRUB UEFI modules and other related files. This is done using the {{ic|grub-mkstandalone}} command (included in {{Pkg|grub}}) as follows:<br />
<br />
# echo 'configfile ${cmdpath}/grub.cfg' > /tmp/grub.cfg ## use single quotes, ${cmdpath}/grub.cfg should be present as it is<br />
# grub-mkstandalone -d /usr/lib/grub/x86_64-efi/ -O x86_64-efi --modules="part_gpt part_msdos" --fonts="unicode" --locales="en@quot" --themes="" -o "$esp/EFI/grub/grubx64_standalone.efi" "boot/grub/grub.cfg=/tmp/grub.cfg" -v<br />
<br />
Then copy the GRUB config file to {{ic|$esp/EFI/grub/grub.cfg}} and create a UEFI Boot Manager entry for {{ic|$esp/EFI/grub/grubx64_standalone.efi}} using [[UEFI#efibootmgr|efibootmgr]].<br />
<br />
{{Note|The option {{ic|1=--modules="part_gpt part_msdos"}} (with the quotes) is necessary for the {{ic|${cmdpath} }} feature to work properly.}}<br />
<br />
{{Warning|You may find that the {{ic|grub.cfg}} file is not loaded due to {{ic|${cmdpath} }} missing a slash (i.e. {{ic|(hd1,msdos2)EFI/Boot}} instead of {{ic|(hd1,msdos2)/EFI/Boot}}) and so you are dropped into a GRUB shell. If this happens determine what {{ic|${cmdpath} }} is set to ({{ic|echo ${cmdpath} }}) and then load the config file manually (e.g. {{ic|configfile (hd1,msdos2)/EFI/Boot/grub.cfg}}).}}<br />
<br />
===== Technical information =====<br />
The GRUB EFI file always expects its config file to be at {{ic|${prefix}/grub.cfg}}. However in the standalone GRUB EFI file, the {{ic|${prefix} }} is located inside a tar archive and embedded inside the standalone GRUB EFI file itself (inside the GRUB environment, it is denoted by {{ic|"(memdisk)"}}, without quotes). This tar archive contains all the files that would be stored normally at {{ic|/boot/grub}} in case of a normal GRUB EFI install. <br />
<br />
Due to this embedding of {{ic|/boot/grub}} contents inside the standalone image itself, it does not rely on actual (external) {{ic|/boot/grub}} for anything. Thus in case of standalone GRUB EFI file {{ic|1=${prefix}==(memdisk)/boot/grub}} and the standalone GRUB EFI file reads expects the config file to be at {{ic|1=${prefix}/grub.cfg==(memdisk)/boot/grub/grub.cfg}}. <br />
<br />
Hence to make sure the standalone GRUB EFI file reads the external {{ic|grub.cfg}} located in the same directory as the EFI file (inside the GRUB environment, it is denoted by {{ic|${cmdpath} }}), we create a simple {{ic|/tmp/grub.cfg}} which instructs GRUB to use {{ic|${cmdpath}/grub.cfg}} as its config ({{ic|configfile ${cmdpath}/grub.cfg}} command in {{ic|(memdisk)/boot/grub/grub.cfg}}). We then instruct grub-mkstandalone to copy this {{ic|/tmp/grub.cfg}} file to {{ic|${prefix}/grub.cfg}} (which is actually {{ic|(memdisk)/boot/grub/grub.cfg}}) using the option {{ic|1="boot/grub/grub.cfg=/tmp/grub.cfg"}}.<br />
<br />
This way, the standalone GRUB EFI file and actual {{ic|grub.cfg}} can be stored in any directory inside the EFI System Partition (as long as they are in the same directory), thus making them portable.<br />
<br />
== Generating main configuration file ==<br />
After the installation, the main configuration file {{ic|grub.cfg}} needs to be generated. The generation process can be influenced by a variety of options in {{ic|/etc/default/grub}} and scripts in {{ic|/etc/grub.d/}}, this is covered in the [[#Basic configuration]] and [[#Advanced configuration]] sections.<br />
<br />
{{Note|Remember that {{ic|grub.cfg}} has to be re-generated after any change to {{ic|/etc/default/grub}} or {{ic|/etc/grub.d/*}}.}}<br />
<br />
Use the ''grub-mkconfig'' tool to generate {{ic|grub.cfg}}:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|<br />
* The file path is {{ic|/boot/grub/grub.cfg}}, NOT {{ic|/boot/grub/i386-pc/grub.cfg}}.<br />
* If you are trying to run ''grub-mkconfig'' in a chroot or ''systemd-nspawn'' container, you might notice that it does not work, complaining that ''grub-probe'' cannot get the "canonical path of /dev/sdaX". In this case, try using ''arch-chroot'' as described [https://bbs.archlinux.org/viewtopic.php?pid&#61;1225067#p1225067 here].<br />
* When generating the GRUB config file on a LVM system in a chroot environment (even ''arch-chroot'', e.g. during System installation), you may receive warnings like {{ic|/run/lvm/lvmetad.socket: connect failed: No such file or directory}} or {{ic|WARNING: failed to connect to lvmetad: No such file or directory. Falling back to internal scanning.}} This is because {{ic|/run}} is not available inside the chroot. These warnings will not prevent the system from booting, provided that everything has been done correctly, so you may continue with the installation.<br />
* If you are looking to detect additional OSes, make sure you have the {{pkg|os-prober}} package installed.<br />
}}<br />
<br />
By default the generation scripts automatically add menu entries for Arch Linux to any generated configuration. However, entries for other operating systems do not work out of the box. On BIOS systems, you may want to install {{Pkg|os-prober}}, which detects other operating systems installed on your machine and adds entries for them into {{ic|grub.cfg}}. If installed, it will be executed when running ''grub-mkconfig''. See [[#Dual-booting]] for advanced configuration.<br />
<br />
=== Converting GRUB Legacy's config file to the new format ===<br />
If {{ic|grub-mkconfig}} fails, convert your {{ic|/boot/grub/menu.lst}} file to {{ic|/boot/grub/grub.cfg}} using:<br />
<br />
# grub-menulst2cfg /boot/grub/menu.lst /boot/grub/grub.cfg<br />
<br />
{{Note|This option works only in BIOS systems, not in UEFI systems.}}<br />
<br />
For example:<br />
<br />
{{hc|/boot/grub/menu.lst|<nowiki><br />
default=0<br />
timeout=5<br />
<br />
title Arch Linux Stock Kernel<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux.img<br />
<br />
title Arch Linux Stock Kernel Fallback<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux-fallback.img<br />
</nowiki>}}<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set default='0'; if [ x"$default" = xsaved ]; then load_env; set default="$saved_entry"; fi<br />
set timeout=5<br />
<br />
menuentry 'Arch Linux Stock Kernel' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux.img' '/initramfs-linux.img'<br />
}<br />
<br />
menuentry 'Arch Linux Stock Kernel Fallback' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux-fallback.img' '/initramfs-linux-fallback.img'<br />
}<br />
</nowiki>}}<br />
<br />
If you forgot to create a GRUB {{ic|/boot/grub/grub.cfg}} config file and simply rebooted into GRUB Command Shell, type:<br />
<br />
sh:grub> insmod legacycfg<br />
sh:grub> legacy_configfile ${prefix}/menu.lst<br />
<br />
Boot into Arch and re-create the proper GRUB {{ic|/boot/grub/grub.cfg}} config file.<br />
<br />
== Basic configuration ==<br />
This section covers only editing the {{ic|/etc/default/grub}} configuration file. See [[#Advanced configuration]] if you need more.<br />
<br />
{{Note|Remember to always [[#Generating main configuration file|re-generate the main configuration file]] after you make changes to {{ic|/etc/default/grub}}.}}<br />
<br />
==== Additional arguments ====<br />
To pass custom additional arguments to the Linux image, you can set the {{ic|GRUB_CMDLINE_LINUX}} + {{ic|GRUB_CMDLINE_LINUX_DEFAULT}} variables in {{ic|/etc/default/grub}}. The two are appended to each other and passed to kernel when generating regular boot entries. For the ''recovery'' boot entry, only {{ic|GRUB_CMDLINE_LINUX}} is used in the generation. <br />
<br />
It is not necessary to use both, but can be useful. For example, you could use {{ic|<nowiki>GRUB_CMDLINE_LINUX_DEFAULT="resume=/dev/sdaX</nowiki> quiet"}} where {{ic|sda'''X'''}} is your swap partition to enable resume after hibernation. This would generate a recovery boot entry without the resume and without ''quiet'' suppressing kernel messages during a boot from that menu entry. Though, the other (regular) menu entries would have them as options. <br />
<br />
For generating the GRUB recovery entry you also have to comment out {{ic|<nowiki>#GRUB_DISABLE_RECOVERY=true</nowiki>}} in {{ic|/etc/default/grub}}. <br />
<br />
You can also use {{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/disk/by-uuid/${swap_uuid}"</nowiki>}}, where {{ic|${swap_uuid} }} is the [[Persistent_block_device_naming|UUID]] of your swap partition.<br />
<br />
Multiple entries are separated by spaces within the double quotes. So, for users who want both resume and systemd it would look like this:<br />
{{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/sdaX init=/usr/lib/systemd/systemd"</nowiki>}}<br />
<br />
See [[Kernel parameters]] for more info.<br />
<br />
=== Visual configuration ===<br />
In GRUB it is possible, by default, to change the look of the menu. Make sure to initialize, if not done already, GRUB graphical terminal, gfxterm, with proper video mode, gfxmode, in GRUB. This can be seen in the section [[#"No suitable mode found" error]]. This video mode is passed by GRUB to the linux kernel via 'gfxpayload' so any visual configurations need this mode in order to be in effect.<br />
<br />
==== Setting the framebuffer resolution ====<br />
GRUB can set the framebuffer for both GRUB itself and the kernel. The old {{ic|1=vga=}} way is deprecated. The preferred method is editing {{ic|/etc/default/grub}} as the following sample:<br />
<br />
GRUB_GFXMODE=1024x768x32<br />
GRUB_GFXPAYLOAD_LINUX=keep<br />
<br />
To generate the changes, run: <br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
The {{ic|gfxpayload}} property will make sure the kernel keeps the resolution.<br />
<br />
{{Note|<br />
* If this example does not work for you try to replace {{ic|1=gfxmode="1024x768x32"}} by {{ic|1=vbemode="0x105"}}. Remember to replace the specified resolution with one suitable for your screen<br />
* To show all the modes you can use {{ic|1=# hwinfo --framebuffer}} (hwinfo is available in [community]), while at GRUB prompt you can use the {{ic|1=vbeinfo}} command<br />
}}<br />
<br />
If this method does not work for you, the deprecated {{ic|1=vga=}} method will still work. Just<br />
add it next to the {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="}} line in {{ic|/etc/default/grub}}<br />
for example: {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="quiet splash vga=792"}} will give you a {{ic|1024x768}} resolution.<br />
<br />
You can choose one of these resolutions: {{ic|640×480}}, {{ic|800×600}}, {{ic|1024×768}}, {{ic|1280×1024}}, {{ic|1600×1200}}, {{ic|1920×1200}}<br />
<br />
==== 915resolution hack ====<br />
Some times for Intel graphic adapters neither {{ic|1=# hwinfo --framebuffer}} nor {{ic|1=vbeinfo}} will show you the desired resolution. In this case you can use {{ic|915resolution}} hack. This hack will temporarily modify video BIOS and add needed resolution. See [http://915resolution.mango-lang.org/ 915resolution's home page]<br />
<br />
First you need to find a video mode which will be modified later. For that we need the GRUB command shell:<br />
{{hc|sh:grub> 915resolution -l|<br />
Intel 800/900 Series VBIOS Hack : version 0.5.3<br />
[...]<br />
'''Mode 30''' : 640x480, 8 bits/pixel<br />
[...]<br />
}}<br />
Next, we overwrite the {{ic|Mode 30}} with {{ic|1440x900}} resolution:<br />
{{hc|/etc/grub.d/00_header|<br />
[...]<br />
'''915resolution 30 1440 900 # Inserted line'''<br />
set gfxmode&#61;${GRUB_GFXMODE}<br />
[...]<br />
}}<br />
Lastly we need to set {{ic|GRUB_GFXMODE}} as described earlier, regenerate {{ic|grub.cfg}} and reboot to test changes.<br />
<br />
==== Background image and bitmap fonts ====<br />
GRUB comes with support for background images and bitmap fonts in {{ic|pf2}} format. The unifont font is included in the {{Pkg|grub}} package under the filename {{ic|unicode.pf2}}, or, as only ASCII characters under the name {{ic|ascii.pf2}}.<br />
<br />
Image formats supported include tga, png and jpeg, providing the correct modules are loaded. The maximum supported resolution depends on your hardware.<br />
<br />
Make sure you have set up the proper [[#Setting the framebuffer resolution|framebuffer resolution]].<br />
<br />
Edit {{ic|/etc/default/grub}} like this:<br />
GRUB_BACKGROUND="/boot/grub/myimage"<br />
#GRUB_THEME="/path/to/gfxtheme"<br />
GRUB_FONT="/path/to/font.pf2"<br />
<br />
{{Note|If you have installed GRUB on a separate partition, {{ic|/boot/grub/myimage}} becomes {{ic|/grub/myimage}}.}}<br />
<br />
[[#Generating main configuration file|Re-generate]] {{ic|grub.cfg}} to apply the changes. If adding the splash image was successful, the user will see {{ic|"Found background image..."}} in the terminal as the command is executed. If this phrase is not seen, the image information was probably not incorporated into the {{ic|grub.cfg}} file.<br />
<br />
If the image is not displayed, check:<br />
* The path and the filename in {{ic|/etc/default/grub}} are correct<br />
* The image is of the proper size and format (tga, png, 8-bit jpg)<br />
* The image was saved in the RGB mode, and is not indexed<br />
* The console mode is not enabled in {{ic|/etc/default/grub}}<br />
* The command {{ic|grub-mkconfig}} must be executed to place the background image information into the {{ic|/boot/grub/grub.cfg}} file<br />
<br />
==== Theme ====<br />
Here is an example for configuring Starfield theme which was included in GRUB package.<br />
<br />
Edit {{ic|/etc/default/grub}}<br />
GRUB_THEME="/usr/share/grub/themes/starfield/theme.txt"<br />
<br />
[[#Generating main configuration file|Re-generate]] {{ic|grub.cfg}} to apply the changes. If configuring the theme was successful, you will see {{ic|Found theme: /usr/share/grub/themes/starfield/theme.txt}} in the terminal.<br />
<br />
Your splash image will usually not be displayed when using a theme.<br />
<br />
==== Menu colors ====<br />
You can set the menu colors in GRUB. The available colors for GRUB can be found in [https://www.gnu.org/software/grub/manual/html_node/Theme-file-format.html the GRUB Manual].<br />
Here is an example:<br />
<br />
Edit {{ic|/etc/default/grub}}:<br />
GRUB_COLOR_NORMAL="light-blue/black"<br />
GRUB_COLOR_HIGHLIGHT="light-cyan/blue"<br />
<br />
==== Hidden menu ====<br />
One of the unique features of GRUB is hiding/skipping the menu and showing it by holding {{ic|Esc}} when needed. You can also adjust whether you want to see the timeout counter.<br />
<br />
Edit {{ic|/etc/default/grub}} as you wish. Here is an example where the comments from the beginning of the two lines have been removed to enable the feature, the timeout has been set to five seconds and to be shown to the user:<br />
GRUB_TIMEOUT=0<br />
GRUB_HIDDEN_TIMEOUT=5<br />
GRUB_HIDDEN_TIMEOUT_QUIET=false<br />
GRUB_HIDDEN_TIMEOUT is how many seconds before displaying menu. You also need to set GRUB_TIMEOUT=0 if you want to hide menu.<br />
<br />
==== Disable framebuffer ====<br />
Users who use NVIDIA proprietary driver might wish to disable GRUB's framebuffer as it can cause problems with the binary driver.<br />
<br />
To disable framebuffer, edit {{ic|/etc/default/grub}} and uncomment the following line:<br />
GRUB_TERMINAL_OUTPUT=console<br />
<br />
Another option if you want to keep the framebuffer in GRUB is to revert to text mode just before starting the kernel. To do that modify the variable in {{ic|/etc/default/grub}}:<br />
GRUB_GFXPAYLOAD_LINUX=text<br />
<br />
=== Persistent block device naming ===<br />
One naming scheme for [[Persistent block device naming]] is the use of globally unique UUIDs to detect partitions instead of the "old" {{ic|/dev/sd*}}. Advantages are covered up in the above linked article. <br />
<br />
Persistent naming via file system UUIDs are used by default in GRUB. <br />
<br />
{{Note|The {{ic|/boot/grub.cfg}} file needs regeneration with the new UUID in {{ic|/etc/default/grub}} every time a relevant file system is resized or recreated. Remember this when modifying partitions & file systems with a Live-CD.}}<br />
<br />
Whether to use UUIDs is controlled by an option in {{ic|/etc/default/grub}}:<br />
<br />
GRUB_DISABLE_LINUX_UUID=true<br />
<br />
=== Recall previous entry ===<br />
GRUB can remember the last entry you booted from and use this as the default entry to boot from next time. This is useful if you have multiple kernels (i.e., the current Arch one and the LTS kernel as a fallback option) or operating systems. To do this, edit {{ic|/etc/default/grub}} and change the value of {{ic|GRUB_DEFAULT}}:<br />
<br />
GRUB_DEFAULT=saved<br />
<br />
This ensures that GRUB will default to the saved entry. To enable saving the selected entry, add the following line to {{ic|/etc/default/grub}}:<br />
<br />
GRUB_SAVEDEFAULT=true<br />
<br />
{{Note|Manually added menu items, e.g. Windows in {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}}, will need {{ic|savedefault}} added.}}<br />
<br />
=== Changing the default menu entry ===<br />
To change the default selected entry, edit {{ic|/etc/default/grub}} and change the value of {{ic|GRUB_DEFAULT}}:<br />
<br />
Using numbers :<br />
GRUB_DEFAULT=0<br />
Grub identifies entries in generated menu counted from zero. That means 0 for the first entry which is the default value, 1 for the second and so on.<br />
<br />
Or using menu titles :<br />
GRUB_DEFAULT='Arch Linux, with Linux core repo kernel'<br />
<br />
=== Disable submenu ===<br />
If you have multiple kernels installed, say linux and linux-lts, by default {{ic|grub-mkconfig}} groups them in a submenu. <br />
If you do not like this behaviour you can go back to one single menu by adding the following line to {{ic|/etc/default/grub}}:<br />
<br />
GRUB_DISABLE_SUBMENU=y<br />
<br />
=== Root encryption ===<br />
<br />
To let GRUB automatically add the kernel parameters for root encryption,<br />
add {{ic|1=cryptdevice=/dev/yourdevice:label}} to {{ic|GRUB_CMDLINE_LINUX}} in {{ic|/etc/default/grub}}.<br />
<br />
See [[Dm-crypt/System Configuration#Boot loader]] for more details.<br />
<br />
{{Tip|If you are upgrading from a working GRUB Legacy configuration, check {{ic|/boot/grub/menu.lst.pacsave}} for the correct device/label to add. Look for them after the text {{ic|kernel /vmlinuz-linux}}.}}<br />
<br />
Example with root mapped to {{ic|/dev/mapper/root}}:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/sda2:root"<br />
<br />
{{Accuracy|1=The following step was added with [https://wiki.archlinux.org/index.php?title=GRUB&diff=184194&oldid=183020], but there is not a clear reason to disable the usage of UUIDs for the root file system.}}<br />
<br />
If you experience trouble booting with UFEI and GPT and dm-crypt, disable the usage of UUIDs for the rootfs:<br />
<br />
GRUB_DISABLE_LINUX_UUID=true<br />
<br />
and make sure to use non-uuid references, use /dev/sdb3 instead of /dev/disk/by-uuid/42d934c7-6199-4f11-9e01-807530111df6 or UUID=42d934c7-6199-4f11-9e01-807530111df6<br />
<br />
=== Boot non-default entry only once ===<br />
The command {{ic|grub-reboot}} is very helpful to boot another entry than the default only once. GRUB loads the entry passed in the first command line argument, when the system is rebooted the next time. Most importantly GRUB returns to loading the default entry for all future booting. Changing the configuration file or selecting an entry in the GRUB menu is not necessary.<br />
{{Note|This requires {{ic|1=GRUB_DEFAULT=saved}} in {{ic|/etc/default/grub}} (and then regenerating {{ic|grub.cfg}}) or, in case of hand-made {{ic|grub.cfg}}, the line {{ic|1=set default="${saved_entry}"}}.}}<br />
<br />
== Advanced configuration ==<br />
This section covers manual editing of {{ic|grub.cfg}}, writing custom scripts in {{ic|/etc/grub.d/}} and other advanced settings.<br />
<br />
=== Manually creating grub.cfg ===<br />
{{Warning|Editing this file is strongly discouraged. The file is generated by the {{ic|grub-mkconfig}} command, and it is best to edit your {{ic|/etc/default/grub}} or one of the scripts in the {{ic|/etc/grub.d}} directory.}}<br />
<br />
A basic GRUB config file uses the following options:<br />
* {{ic|(hd''X'',''Y'')}} is the partition ''Y'' on disk ''X'', partition numbers starting at 1, disk numbers starting at 0<br />
* {{ic|1=set default=''N''}} is the default boot entry that is chosen after timeout for user action<br />
* {{ic|1=set timeout=''M''}} is the time ''M'' to wait in seconds for a user selection before default is booted<br />
* {{ic|<nowiki>menuentry "title" {entry options}</nowiki>}} is a boot entry titled {{ic|title}}<br />
* {{ic|1=set root=(hd''X'',''Y'')}} sets the boot partition, where the kernel and GRUB modules are stored (boot need not be a separate partition, and may simply be a directory under the "root" partition ({{ic|/}})<br />
<br />
An example configuration:<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
# Config file for GRUB - The GNU GRand Unified Bootloader<br />
# /boot/grub/grub.cfg<br />
<br />
# DEVICE NAME CONVERSIONS<br />
#<br />
# Linux Grub<br />
# -------------------------<br />
# /dev/fd0 (fd0)<br />
# /dev/sda (hd0)<br />
# /dev/sdb2 (hd1,2)<br />
# /dev/sda3 (hd0,3)<br />
#<br />
<br />
# Timeout for menu<br />
set timeout=5<br />
<br />
# Set default boot entry as Entry 0<br />
set default=0<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
set root=(hd0,1)<br />
linux /vmlinuz-linux root=/dev/sda3 ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
## (1) Windows<br />
#menuentry "Windows" {<br />
# set root=(hd0,3)<br />
# chainloader +1<br />
#}<br />
</nowiki>}}<br />
<br />
=== Dual-booting ===<br />
{{Tip|If you want GRUB to automatically search for other systems, you may wish to install {{Pkg|os-prober}}.}}<br />
<br />
==== Automatically generating using /etc/grub.d/40_custom and grub-mkconfig ====<br />
The best way to add other entries is editing the {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}}. The entries in this file will be automatically added when running {{ic|grub-mkconfig}}.<br />
After adding the new lines, run:<br />
{{bc|<nowiki># grub-mkconfig -o /boot/grub/grub.cfg</nowiki>}}<br />
or, for UEFI-GPT Mode (as per alternate method):<br />
{{bc|<nowiki># grub-mkconfig -o /boot/efi/EFI/GRUB/grub.cfg</nowiki>}}<br />
to generate an updated {{ic|grub.cfg}}.<br />
<br />
For example, a typical {{ic|/etc/grub.d/40_custom}} file, could appear similar to the following one, created for [http://h10025.www1.hp.com/ewfrf/wc/product?cc=us&destPage=product&lc=en&product=5402703&tmp_docname= HP Pavilion 15-e056sl Notebook PC], originally with Microsoft Windows 8 preinstalled. Each {{ic|menuentry}} should mantain a structure similar to the following ones. Note that the UEFI partition {{ic|/dev/sda2}} within GRUB is called {{ic|hd0,gpt2}} and {{ic|ahci0,gpt2}} (see [[#Windows Installed in UEFI-GPT Mode menu entry|here]] for more info).<br />
<br />
{{hc|/etc/grub.d/40_custom|<nowiki>#!/bin/sh<br />
exec tail -n +3 $0<br />
# This file provides an easy way to add custom menu entries.&nbsp; Simply type the<br />
# menu entries you want to add after this comment.&nbsp; Be careful not to change<br />
# the 'exec tail' line above.<br />
<br />
menuentry "HP / Microsoft Windows 8.1" {<br />
echo "Loading HP / Microsoft Windows 8.1..."<br />
insmod part_gpt<br />
insmod fat<br />
insmod search_fs_uuid<br />
insmod chain<br />
search --fs-uuid --no-floppy --set=root --hint-bios=hd0,gpt2 --hint-efi=hd0,gpt2 --hint-baremetal=ahci0,gpt2 763A-9CB6<br />
chainloader /EFI/Microsoft/Boot/bootmgfw.efi<br />
}<br />
<br />
menuentry "HP / Microsoft Control Center" {<br />
echo "Loading HP / Microsoft Control Center..."<br />
insmod part_gpt<br />
insmod fat<br />
insmod search_fs_uuid<br />
insmod chain<br />
search --fs-uuid --no-floppy --set=root --hint-bios=hd0,gpt2 --hint-efi=hd0,gpt2 --hint-baremetal=ahci0,gpt2 763A-9CB6<br />
chainloader /EFI/HP/boot/bootmgfw.efi<br />
}<br />
<br />
menuentry "System shutdown" {<br />
echo "System shutting down..."<br />
halt<br />
}<br />
<br />
menuentry "System restart" {<br />
echo "System rebooting..."<br />
reboot<br />
}</nowiki>}}<br />
<br />
===== GNU/Linux menu entry =====<br />
Assuming that the other distro is on partition {{ic|sda2}}:<br />
<br />
{{bc|<nowiki>menuentry "Other Linux" {<br />
set root=(hd0,2)<br />
linux /boot/vmlinuz (add other options here as required)<br />
initrd /boot/initrd.img (if the other kernel uses/needs one)<br />
}</nowiki>}}<br />
<br />
===== FreeBSD menu entry =====<br />
Requires that FreeBSD is installed on a single partition with UFS. Assuming it is installed on {{ic|sda4}}:<br />
<br />
{{bc|<nowiki>menuentry "FreeBSD" {<br />
set root=(hd0,4)<br />
chainloader +1<br />
}</nowiki>}}<br />
<br />
===== Windows XP menu entry=====<br />
This assumes that your Windows partition is {{ic|sda3}}. Remember you need to point set root and chainloader to the system reserve partition that windows made when it installed, not the actual partition windows is on. This example works if your system reserve partition is {{ic|sda3}}.<br />
<br />
{{bc|<nowiki># (2) Windows XP<br />
menuentry "Windows XP" {<br />
set root="(hd0,3)"<br />
chainloader +1<br />
}</nowiki>}}<br />
<br />
If the Windows bootloader is on an entirely different hard drive than GRUB, it may be necessary to trick Windows into believing that it is the first hard drive. This was possible with {{ic|drivemap}}. Assuming GRUB is on {{ic|hd0}} and Windows is on {{ic|hd2}}, you need to add the following after {{ic|set root}}:<br />
<br />
{{bc|drivemap -s hd0 hd2}}<br />
<br />
===== Windows installed in UEFI-GPT Mode menu entry =====<br />
<br />
{{Note|This menuentry will work only in UEFI boot mode and only if the Windows bitness matches the uefi bitness. It '''WILL NOT WORK''' in bios installed grub(2). See [[Windows_and_Arch_Dual_Boot#Windows_UEFI_vs_BIOS_limitations|this]] and [[Windows_and_Arch_Dual_Boot#Bootloader_UEFI_vs_BIOS_limitations|this]] for more info.}}<br />
<br />
{{bc|<nowiki>if [ "${grub_platform}" == "efi" ]; then<br />
menuentry "Microsoft Windows Vista/7/8/8.1 UEFI-GPT" {<br />
insmod part_gpt<br />
insmod fat<br />
insmod search_fs_uuid<br />
insmod chain<br />
search --fs-uuid --set=root $hints_string $fs_uuid<br />
chainloader /EFI/Microsoft/Boot/bootmgfw.efi<br />
}<br />
fi</nowiki>}}<br />
<br />
where {{ic|$hints_string}} and {{ic|$fs_uuid}} are obtained with the following two commands. {{ic|$fs_uuid}}'s command:<br />
<br />
{{bc|<nowiki># grub-probe --target=fs_uuid $esp/EFI/Microsoft/Boot/bootmgfw.efi<br />
1ce5-7f28</nowiki>}}<br />
<br />
{{ic|$hints_string}}'s command:<br />
<br />
{{bc|<nowiki># grub-probe --target=hints_string $esp/EFI/Microsoft/Boot/bootmgfw.efi<br />
--hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1</nowiki>}}<br />
<br />
These two commands assume the ESP Windows uses is mounted at {{ic|$esp}}. There might be case differences in the path to Windows's EFI file, what with being Windows, and all.<br />
<br />
===== "Shutdown" menu entry =====<br />
{{bc|<nowiki>menuentry "System shutdown" {<br />
echo "System shutting down..."<br />
halt<br />
}</nowiki>}}<br />
<br />
===== "Restart" menu entry =====<br />
{{bc|<nowiki>menuentry "System restart" {<br />
echo "System rebooting..."<br />
reboot<br />
}</nowiki>}}<br />
<br />
===== Windows installed in BIOS-MBR mode =====<br />
{{Poor writing|This section does not fit into the others, should be slimmed down a bit.}}<br />
<br />
{{Note|GRUB supports booting {{ic|bootmgr}} directly and chainload of partition boot sector is no longer required to boot Windows in a BIOS-MBR setup.}}<br />
<br />
{{Warning|It is the '''system partition''' that has {{ic|/bootmgr}}, not your "real" Windows partition (usually C:). In {{ic|blkid}} output, the system partition is the one with {{ic|LABEL&#61;"SYSTEM RESERVED"}} or {{ic|LABEL&#61;"SYSTEM"}} and is only about 100 to 200 MB in size (much like the boot partition for Arch). See [[Wikipedia:System partition and boot partition]] for more info.}}<br />
<br />
Throughout this section, it is assumed your Windows partition is {{ic|/dev/sda1}}. A different partition will change every instance of hd0,msdos1. First, find the UUID of the NTFS file system of the Windows's SYSTEM PARTITION where the {{ic|bootmgr}} and its files reside. For example, if Windows {{ic|bootmgr}} exists at {{ic|/media/SYSTEM_RESERVED/bootmgr}}:<br />
<br />
For Windows Vista/7/8/8.1:<br />
<br />
# grub-probe --target=fs_uuid /media/SYSTEM_RESERVED/bootmgr<br />
69B235F6749E84CE<br />
<br />
# grub-probe --target=hints_string /media/SYSTEM_RESERVED/bootmgr<br />
--hint-bios=hd0,msdos1 --hint-efi=hd0,msdos1 --hint-baremetal=ahci0,msdos1<br />
<br />
{{Note|For Windows XP, replace {{ic|bootmgr}} with {{ic|NTLDR}} in the above commands. And note that there may not be a separate SYSTEM_RESERVED partition; just probe the file NTLDR on your Windows partition.}}<br />
<br />
Then, add the below code to {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} and regenerate {{ic|grub.cfg}} with {{ic|grub-mkconfig}} as explained above to boot Windows (XP, Vista, 7 or 8) installed in BIOS-MBR mode:<br />
<br />
{{Note|These menuentries will work only in Legacy BIOS boot mode. It WILL NOT WORK in uefi installed grub(2). See [[Windows_and_Arch_Dual_Boot#Windows_UEFI_vs_BIOS_limitations]] and [[Windows_and_Arch_Dual_Boot#Bootloader_UEFI_vs_BIOS_limitations]].}}<br />
<br />
For Windows Vista/7/8/8.1:<br />
<br />
if [ "${grub_platform}" == "pc" ]; then<br />
menuentry "Microsoft Windows Vista/7/8/8.1 BIOS-MBR" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --set=root --hint-bios=hd0,msdos1 --hint-efi=hd0,msdos1 --hint-baremetal=ahci0,msdos1 69B235F6749E84CE<br />
ntldr /bootmgr<br />
}<br />
fi<br />
<br />
For Windows XP:<br />
<br />
if [ "${grub_platform}" == "pc" ]; then<br />
menuentry "Microsoft Windows XP" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --set=root --hint-bios=hd0,msdos1 --hint-efi=hd0,msdos1 --hint-baremetal=ahci0,msdos1 69B235F6749E84CE<br />
ntldr /bootmgr<br />
}<br />
fi<br />
<br />
{{Note|In some cases, mine I have installed GRUB before a clean Windows 8, you cannot boot Windows having an error with {{ic|\boot\bcd}} (error code {{ic|0xc000000f}}). You can fix it going to Windows Recovery Console (cmd from install disk) and executing:<br />
x:\> "bootrec.exe /fixboot" <br />
x:\> "bootrec.exe /RebuildBcd".<br />
Do '''not''' use {{ic|bootrec.exe /Fixmbr}} because it will wipe GRUB out.}}<br />
<br />
{{ic|/etc/grub.d/40_custom}} can be used as a template to create {{ic|/etc/grub.d/nn_custom}}. Where {{ic|nn}} defines the precendence, indicating the order the script is executed. The order scripts are executed determine the placement in the grub boot menu.<br />
<br />
{{Note|{{ic|nn}} should be greater than 06 to ensure necessary scripts are executed first.}}<br />
<br />
==== With Windows via EasyBCD and NeoGRUB ====<br />
{{Merge|NeoGRUB|New page has been created, so this section should be merged there.}}<br />
<br />
Since EasyBCD's NeoGRUB currently does not understand the GRUB menu format, chainload to it by replacing the contents of your {{ic|C:\NST\menu.lst}} file with lines similar to the following:<br />
<br />
default 0<br />
timeout 1<br />
<br />
title Chainload into GRUB v2<br />
root (hd0,7)<br />
kernel /boot/grub/i386-pc/core.img<br />
<br />
Finally, recreate your {{ic|grub.cfg}} using {{ic|grub-mkconfig}}.<br />
<br />
=== Booting ISO9660 image file directly via GRUB ===<br />
<br />
GRUB supports booting from ISO images directly via loopback devices, see [[Multiboot USB drive#Using GRUB and loopback devices]] for examples.<br />
<br />
=== LVM ===<br />
If you use [[LVM]] for your {{ic|/boot}}, add the following before menuentry lines:<br />
<br />
insmod lvm<br />
<br />
and specify your root in the menuentry as:<br />
<br />
set root=lvm/''lvm_group_name''-''lvm_logical_boot_partition_name''<br />
<br />
Example:<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
insmod lvm<br />
set root=lvm/VolumeGroup-lv_boot<br />
# you can only set following two lines<br />
linux /vmlinuz-linux root=/dev/mapper/VolumeGroup-root ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
=== RAID ===<br />
GRUB provides convenient handling of RAID volumes. You need to add {{ic|insmod mdraid}} which allows you to address the volume natively. For example, {{ic|/dev/md0}} becomes:<br />
set root=(md/0)<br />
<br />
whereas a partitioned RAID volume (e.g. {{ic|/dev/md0p1}}) becomes:<br />
set root=(md/0,1)<br />
<br />
To install grub when using RAID1 as the {{ic|/boot}} partition (or using {{ic|/boot}} housed on a RAID1 root partition), on devices with GPT ef02/'BIOS boot partition', simply run ''grub-install'' on both of the drives, such as:<br />
# grub-install --target=i386-pc --recheck --debug /dev/sda<br />
# grub-install --target=i386-pc --recheck --debug /dev/sdb<br />
<br />
Where the RAID 1 array housing {{ic|/boot}} is housed on {{ic|/dev/sda}} and {{ic|/dev/sdb}}.<br />
<br />
=== Using labels ===<br />
It is possible to use labels, human-readable strings attached to file systems, by using the {{ic|--label}} option to {{ic|search}}. First of all, label your existing partition:<br />
# tune2fs -L ''LABEL'' ''PARTITION''<br />
<br />
Then, add an entry using labels. An example of this:<br />
<br />
menuentry "Arch Linux, session texte" {<br />
search --label --set=root archroot<br />
linux /boot/vmlinuz-linux root=/dev/disk/by-label/archroot ro<br />
initrd /boot/initramfs-linux.img<br />
}<br />
<br />
=== Password protection of GRUB menu ===<br />
If you want to secure GRUB so it is not possible for anyone to change boot parameters or use the command line, you can add a user/password combination to GRUB's configuration files. To do this, run the command {{ic|grub-mkpasswd-pbkdf2}}. Enter a password and confirm it:<br />
<br />
{{hc|grub-mkpasswd-pbkdf2|<br />
[...]<br />
Your PBKDF2 is grub.pbkdf2.sha512.10000.C8ABD3E93C4DFC83138B0C7A3D719BC650E6234310DA069E6FDB0DD4156313DA3D0D9BFFC2846C21D5A2DDA515114CF6378F8A064C94198D0618E70D23717E82.509BFA8A4217EAD0B33C87432524C0B6B64B34FBAD22D3E6E6874D9B101996C5F98AB1746FE7C7199147ECF4ABD8661C222EEEDB7D14A843261FFF2C07B1269A<br />
}}<br />
<br />
Then, add the following to {{ic|/etc/grub.d/40_custom}}:<br />
<br />
{{hc|/etc/grub.d/40_custom|<br />
cat << EOF<br />
<br />
set superusers<nowiki>=</nowiki>"'''username'''"<br />
password_pbkdf2 '''username''' '''<password>'''<br />
<br />
EOF<br />
}}<br />
<br />
where {{ic|<password>}} is the string generated by {{ic|grub-mkpasswd_pbkdf2}}.<br />
<br />
Regenerate your configuration file. Your GRUB command line, boot parameters and all boot entries are now protected.<br />
<br />
This can be relaxed and further customized with more users as described in the "Security" part of [https://www.gnu.org/software/grub/manual/grub.html#Security the GRUB manual].<br />
<br />
=== Hide GRUB unless the Shift key is held down ===<br />
In order to achieve the fastest possible boot, instead of having GRUB wait for a timeout, it is possible for GRUB to hide the menu, unless the {{ic|Shift}} key is held down during GRUB's start-up.<br />
<br />
In order to achieve this, you should add the following line to {{ic|/etc/default/grub}}:<br />
<br />
GRUB_FORCE_HIDDEN_MENU="true"<br />
<br />
And the following file should be created and made executable:<br />
<br />
{{hc|/etc/grub.d/31_hold_shift|<nowiki><br />
#! /bin/sh<br />
set -e<br />
<br />
# grub-mkconfig helper script.<br />
# Copyright (C) 2006,2007,2008,2009 Free Software Foundation, Inc.<br />
#<br />
# GRUB is free software: you can redistribute it and/or modify<br />
# it under the terms of the GNU General Public License as published by<br />
# the Free Software Foundation, either version 3 of the License, or<br />
# (at your option) any later version.<br />
#<br />
# GRUB is distributed in the hope that it will be useful,<br />
# but WITHOUT ANY WARRANTY; without even the implied warranty of<br />
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br />
# GNU General Public License for more details.<br />
#<br />
# You should have received a copy of the GNU General Public License<br />
# along with GRUB. If not, see <http://www.gnu.org/licenses/>.<br />
<br />
prefix="/usr"<br />
exec_prefix="${prefix}"<br />
datarootdir="${prefix}/share"<br />
<br />
export TEXTDOMAIN=grub<br />
export TEXTDOMAINDIR="${datarootdir}/locale"<br />
source "${datarootdir}/grub/grub-mkconfig_lib"<br />
<br />
found_other_os=<br />
<br />
make_timeout () {<br />
<br />
if [ "x${GRUB_FORCE_HIDDEN_MENU}" = "xtrue" ] ; then <br />
if [ "x${1}" != "x" ] ; then<br />
if [ "x${GRUB_HIDDEN_TIMEOUT_QUIET}" = "xtrue" ] ; then<br />
verbose=<br />
else<br />
verbose=" --verbose"<br />
fi<br />
<br />
if [ "x${1}" = "x0" ] ; then<br />
cat <<EOF<br />
if [ "x\${timeout}" != "x-1" ]; then<br />
if keystatus; then<br />
if keystatus --shift; then<br />
set timeout=-1<br />
else<br />
set timeout=0<br />
fi<br />
else<br />
if sleep$verbose --interruptible 3 ; then<br />
set timeout=0<br />
fi<br />
fi<br />
fi<br />
EOF<br />
else<br />
cat << EOF<br />
if [ "x\${timeout}" != "x-1" ]; then<br />
if sleep$verbose --interruptible ${GRUB_HIDDEN_TIMEOUT} ; then<br />
set timeout=0<br />
fi<br />
fi<br />
EOF<br />
fi<br />
fi<br />
fi<br />
}<br />
<br />
adjust_timeout () {<br />
if [ "x$GRUB_BUTTON_CMOS_ADDRESS" != "x" ]; then<br />
cat <<EOF<br />
if cmostest $GRUB_BUTTON_CMOS_ADDRESS ; then<br />
EOF<br />
make_timeout "${GRUB_HIDDEN_TIMEOUT_BUTTON}" "${GRUB_TIMEOUT_BUTTON}"<br />
echo else<br />
make_timeout "${GRUB_HIDDEN_TIMEOUT}" "${GRUB_TIMEOUT}"<br />
echo fi<br />
else<br />
make_timeout "${GRUB_HIDDEN_TIMEOUT}" "${GRUB_TIMEOUT}"<br />
fi<br />
}<br />
<br />
adjust_timeout<br />
<br />
cat <<EOF<br />
if [ "x\${timeout}" != "x-1" ]; then<br />
if keystatus; then<br />
if keystatus --shift; then<br />
set timeout=-1<br />
else<br />
set timeout=0<br />
fi<br />
else<br />
if sleep$verbose --interruptible 3 ; then<br />
set timeout=0<br />
fi<br />
fi<br />
fi<br />
EOF<br />
</nowiki>}}<br />
<br />
Make that file executable and then regenerate your grub config:<br />
chmod a+x /etc/grub.d/31_hold_shift<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Combining the use of UUIDs and basic scripting ===<br />
If you like the idea of using UUIDs to avoid unreliable BIOS mappings or are struggling with GRUB's syntax, here is an example boot menu item that uses UUIDs and a small script to direct GRUB to the proper disk partitions for your system. All you need to do is replace the UUIDs in the sample with the correct UUIDs for your system. The example applies to a system with a boot and root partition. You will obviously need to modify the GRUB configuration if you have additional partitions:<br />
<br />
{{bc|<nowiki><br />
menuentry "Arch Linux 64" {<br />
# Set the UUIDs for your boot and root partition respectively<br />
set the_boot_uuid=ece0448f-bb08-486d-9864-ac3271bd8d07<br />
set the_root_uuid=c55da16f-e2af-4603-9e0b-03f5f565ec4a<br />
<br />
# (Note: This may be the same as your boot partition)<br />
<br />
# Get the boot/root devices and set them in the root and grub_boot variables<br />
search --fs-uuid $the_root_uuid --set=root<br />
search --fs-uuid $the_boot_uuid --set=grub_boot<br />
<br />
# Check to see if boot and root are equal.<br />
# If they are, then append /boot to $grub_boot (Since $grub_boot is actually the root partition)<br />
if [ $the_boot_uuid == $the_root_uuid ] ; then<br />
set grub_boot=($grub_boot)/boot<br />
else<br />
set grub_boot=($grub_boot)<br />
fi<br />
<br />
# $grub_boot now points to the correct location, so the following will properly find the kernel and initrd<br />
linux $grub_boot/vmlinuz-linux root=/dev/disk/by-uuid/$the_root_uuid ro<br />
initrd $grub_boot/initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
== Using the command shell ==<br />
Since the MBR is too small to store all GRUB modules, only the menu and a few basic commands reside there. The majority of GRUB functionality remains in modules in {{ic|/boot/grub}}, which are inserted as needed. In error conditions (e.g. if the partition layout changes) GRUB may fail to boot. When this happens, a command shell may appear.<br />
<br />
GRUB offers multiple shells/prompts. If there is a problem reading the menu but the bootloader is able to find the disk, you will likely be dropped to the "normal" shell:<br />
sh:grub><br />
<br />
If there is a more serious problem (e.g. GRUB cannot find required files), you may instead be dropped to the "rescue" shell:<br />
grub rescue><br />
<br />
The rescue shell is a restricted subset of the normal shell, offering much less functionality. If dumped to the rescue shell, first try inserting the "normal" module, then starting the "normal" shell:<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
grub rescue> insmod (hdX,Y)/boot/grub/i386-pc/normal.mod<br />
rescue:grub> normal<br />
<br />
=== Pager support ===<br />
GRUB supports pager for reading commands that provide long output (like the {{ic|help}} command). This works only in normal shell mode and not in rescue mode. To enable pager, in GRUB command shell type:<br />
sh:grub> set pager=1<br />
<br />
=== Using the command shell environment to boot operating systems ===<br />
grub> <br />
<br />
The GRUB's command shell environment can be used to boot operating systems.<br />
A common scenario may be to boot Windows / Linux stored on a drive/partition via '''chainloading'''.<br />
<br />
''Chainloading'' means to load another boot-loader from the current one, ie, chain-loading.<br />
<br />
The other bootloader may be embedded at the starting of the disk(MBR) or at the starting of a partition.<br />
<br />
==== Chainloading a partition ====<br />
set root=(hdX,Y)<br />
chainloader +1<br />
boot<br />
<br />
X=0,1,2...<br />
Y=1,2,3...<br />
<br />
For example to chainload Windows stored in the first partiton of the first hard disk, <br />
<br />
set root=(hd0,1)<br />
chainloader +1<br />
boot<br />
<br />
Similarly GRUB installed to a partition can be chainloaded.<br />
<br />
==== Chainloading a disk/drive ====<br />
set root=hdX<br />
chainloader +1<br />
boot<br />
<br />
==== Chainloading Windows/Linux installed in UEFI mode ====<br />
<br />
insmod ntfs<br />
set root=(hd0,gpt4)<br />
chainloader (${root})/EFI/Microsoft/Boot/bootmgfw.efi<br />
boot<br />
<br />
''insmod ntfs'' used for loading the ntfs file system module for loading Windows.<br />
(hd0,gpt4) or /dev/sda4 is my EFI System Partition (ESP).<br />
The entry in the ''chainloader'' line specifies the path of the .efi file to be chain-loaded.<br />
<br />
==== Normal loading ====<br />
See the examples in [[Grub#Using_the_rescue_console|#Using_the_rescue_console]]<br />
<br />
== GUI configuration tools ==<br />
Following package may be installed:<br />
* {{App|grub-customizer|Customize the bootloader (GRUB or BURG)|https://launchpad.net/grub-customizer|{{AUR|grub-customizer}}}}<br />
* {{App|grub2-editor|KDE4 control module for configuring the GRUB bootloader|http://kde-apps.org/content/show.php?content&#61;139643|{{AUR|grub2-editor}}}}<br />
* {{App|startupmanager|GUI app for changing the settings of GRUB Legacy, GRUB, Usplash and Splashy ([https://launchpad.net/startup-manager/+announcement/8300 abandonned])|http://sourceforge.net/projects/startup-manager/|{{AUR|startupmanager}}}}<br />
<br />
== parttool for hide/unhide ==<br />
If you have a Windows 9x paradigm with hidden {{ic|C:\}} disks GRUB can hide/unhide it using {{ic|parttool}}. For example, to boot the third {{ic|C:\}} disk of three Windows 9x installations on the CLI enter the CLI and:<br />
parttool hd0,1 hidden+ boot-<br />
parttool hd0,2 hidden+ boot-<br />
parttool hd0,3 hidden- boot+<br />
set root=hd0,3<br />
chainloader +1<br />
boot<br />
<br />
== Using the rescue console ==<br />
See [[#Using the command shell]] first. If unable to activate the standard shell, one possible solution is to boot using a live CD or some other rescue disk to correct configuration errors and reinstall GRUB. However, such a boot disk is not always available (nor necessary); the rescue console is surprisingly robust.<br />
<br />
The available commands in GRUB rescue include {{ic|insmod}}, {{ic|ls}}, {{ic|set}}, and {{ic|unset}}. This example uses {{ic|set}} and {{ic|insmod}}. {{ic|set}} modifies variables and {{ic|insmod}} inserts new modules to add functionality.<br />
<br />
Before starting, the user must know the location of their {{ic|/boot}} partition (be it a separate partition, or a subdirectory under their root):<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
<br />
where X is the physical drive number and Y is the partition number.<br />
<br />
To expand console capabilities, insert the {{ic|linux}} module:<br />
grub rescue> insmod i386-pc/linux.mod<br />
<br />
{{Note|With a separate boot partition, omit {{ic|/boot}} from the path, (i.e. type {{ic|1=set prefix=(hdX,Y)/grub}}).}}<br />
<br />
This introduces the {{ic|linux}} and {{ic|initrd}} commands, which should be familiar (see [[#Advanced configuration]]).<br />
<br />
An example, booting Arch Linux:<br />
set root=(hd0,5)<br />
linux /boot/vmlinuz-linux root=/dev/sda5<br />
initrd /boot/initramfs-linux.img<br />
boot<br />
<br />
With a separate boot partition, again change the lines accordingly:<br />
set root=(hd0,5)<br />
linux /vmlinuz-linux root=/dev/sda6<br />
initrd /initramfs-linux.img<br />
boot<br />
<br />
{{Note|If you experienced {{ic|error: premature end of file /YOUR_KERNEL_NAME}} during execution of {{ic|linux}} command, you can try {{ic|linux16}} instead.}}<br />
<br />
After successfully booting the Arch Linux installation, users can correct {{ic|grub.cfg}} as needed and then reinstall GRUB.<br />
<br />
To reinstall GRUB and fix the problem completely, changing {{ic|/dev/sda}} if needed. See [[#Installation]] for details.<br />
<br />
== Troubleshooting ==<br />
=== Intel BIOS not booting GPT ===<br />
<br />
==== MBR ====<br />
Some Intel BIOS's require at least one bootable MBR partition to be present at boot, causing GPT-partitioned boot setups to be unbootable.<br />
<br />
This can be circumvented by using (for instance) fdisk to mark one of the GPT partitions (preferably the 1007 KiB partition you have created for GRUB already) bootable in the MBR. This can be achieved, using fdisk, by the following commands: Start fdisk against the disk you are installing, for instance {{ic|fdisk /dev/sda}}, then press {{ic|a}} and select the partition you wish to mark as bootable (probably #1) by pressing the corresponding number, finally press {{ic|w}} to write the changes to the MBR.<br />
<br />
{{Note|The bootable-marking must be done in {{ic|fdisk}} or similar, not in GParted or others, as they will not set the bootable flag in the MBR.}}<br />
<br />
With cfdisk, the steps are similar, just {{ic|cfdisk /dev/sda}}, choose bootable (at the left) in the desired hard disk, and quit saving.<br />
<br />
More information is available [http://www.rodsbooks.com/gdisk/bios.html here]<br />
<br />
==== EFI path ====<br />
<br />
Some UEFI firmwares require a bootable file at a known location before they will show UEFI NVRAM boot entries. If this is the case, {{ic|grub-install}} will claim {{ic|efibootmgr}} has added an entry to boot GRUB, however the entry will not show up in the VisualBIOS boot order selector. The solution is to place a file at one of the known locations. Assuming the EFI partition is at {{ic|/boot/efi/}} this will work:<br />
<br />
mkdir /boot/efi/EFI/boot<br />
cp /boot/efi/EFI/grub/grubx64.efi /boot/efi/EFI/boot/bootx64.efi<br />
<br />
This solution worked for an Intel DH87MC motherboard with firmware dated Jan 2014.<br />
<br />
=== Enable debug messages ===<br />
Add:<br />
<br />
set pager=1<br />
set debug=all<br />
<br />
to {{ic|grub.cfg}}.<br />
<br />
=== "No suitable mode found" error ===<br />
If you get this error when booting any menuentry:<br />
<br />
error: no suitable mode found<br />
Booting however<br />
<br />
Then you need to initialize GRUB graphical terminal ({{ic|gfxterm}}) with proper video mode ({{ic|gfxmode}}) in GRUB. This video mode is passed by GRUB to the linux kernel via 'gfxpayload'. In case of UEFI systems, if the GRUB video mode is not initialized, no kernel boot messages will be shown in the terminal (atleast until KMS kicks in).<br />
<br />
Copy {{ic|/usr/share/grub/unicode.pf2}} to ${GRUB_PREFIX_DIR} ({{ic|/boot/grub/}} in case of BIOS and UEFI systems). If GRUB UEFI was installed with {{ic|1=--boot-directory=$esp/EFI}} set, then the directory is {{ic|$esp/EFI/grub/}}:<br />
<br />
# cp /usr/share/grub/unicode.pf2 ${GRUB_PREFIX_DIR}<br />
<br />
If {{ic|/usr/share/grub/unicode.pf2}} does not exist, install {{Pkg|bdf-unifont}}, create the {{ic|unifont.pf2}} file and then copy it to {{ic|${GRUB_PREFIX_DIR<nowiki>}</nowiki>}}:<br />
<br />
# grub-mkfont -o unicode.pf2 /usr/share/fonts/misc/unifont.bdf<br />
<br />
Then, in the {{ic|grub.cfg}} file, add the following lines to enable GRUB to pass the video mode correctly to the kernel, without of which you will only get a black screen (no output) but booting (actually) proceeds successfully without any system hang.<br />
<br />
BIOS systems:<br />
<br />
insmod vbe<br />
<br />
UEFI systems:<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
<br />
After that add the following code (common to both BIOS and UEFI):<br />
<br />
insmod font<br />
<br />
if loadfont ${prefix}/fonts/unicode.pf2<br />
then<br />
insmod gfxterm<br />
set gfxmode=auto<br />
set gfxpayload=keep<br />
terminal_output gfxterm<br />
fi<br />
<br />
As you can see for gfxterm (graphical terminal) to function properly, {{ic|unicode.pf2}} font file should exist in {{ic|${GRUB_PREFIX_DIR<nowiki>}</nowiki>}}.<br />
<br />
=== msdos-style error message ===<br />
grub-setup: warn: This msdos-style partition label has no post-MBR gap; embedding will not be possible!<br />
grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists.<br />
However, blocklists are UNRELIABLE and its use is discouraged.<br />
grub-setup: error: If you really want blocklists, use --force.<br />
<br />
This error may occur when you try installing GRUB in a VMware container. Read more about it [https://bbs.archlinux.org/viewtopic.php?pid=581760#p581760 here]. It happens when the first partition starts just after the MBR (block 63), without the usual space of 1 MiB (2048 blocks) before the first partition. Read [[#Master Boot Record (MBR) specific instructions]]<br />
<br />
=== GRUB UEFI drops to shell ===<br />
If GRUB loads but drops you into the rescue shell with no errors, it may be because of a missing or misplaced {{ic|grub.cfg}}. This will happen if GRUB UEFI was installed with {{ic|--boot-directory}} and {{ic|grub.cfg}} is missing OR if the partition number of the boot partition changed (which is hard-coded into the {{ic|grubx64.efi}} file).<br />
<br />
=== GRUB UEFI not loaded ===<br />
An example of a working EFI:<br />
{{hc|# efibootmgr -v|<br />
BootCurrent: 0000<br />
Timeout: 3 seconds<br />
BootOrder: 0000,0001,0002<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\efi\grub\grub.efi)<br />
Boot0001* Shell HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\EfiShell.efi)<br />
Boot0002* Festplatte BIOS(2,0,00)P0: SAMSUNG HD204UI<br />
}}<br />
<br />
If the screen only goes black for a second and the next boot option is tried afterwards, according to [https://bbs.archlinux.org/viewtopic.php?pid=981560#p981560 this post], moving GRUB to the partition root can help. The boot option has to be deleted and recreated afterwards. The entry for GRUB should look like this then:<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\grub.efi)<br />
<br />
=== Invalid signature ===<br />
If trying to boot Windows results in an "invalid signature" error, e.g. after reconfiguring partitions or adding additional hard drives, (re)move GRUB's device configuration and let it reconfigure:<br />
# mv /boot/grub/device.map /boot/grub/device.map-old<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
{{ic|grub-mkconfig}} should now mention all found boot options, including Windows. If it works, remove {{ic|/boot/grub/device.map-old}}.<br />
<br />
=== Boot freezes ===<br />
If booting gets stuck without any error message after GRUB loading the kernel and the initial ramdisk, try removing the {{ic|add_efi_memmap}} kernel parameter.<br />
<br />
=== Restore GRUB Legacy ===<br />
* Move GRUB v2 files out of the way:<br />
<br />
# mv /boot/grub /boot/grub.nonfunctional<br />
<br />
* Copy GRUB Legacy back to {{ic|/boot}}:<br />
<br />
# cp -af /boot/grub-legacy /boot/grub<br />
<br />
* Replace MBR and next 62 sectors of sda with backed up copy<br />
<br />
{{Warning|This command also restores the partition table, so be careful of overwriting a modified partition table with the old one. It '''will''' mess up your system.}}<br />
<br />
# dd if=/path/to/backup/first-sectors of=/dev/sdX bs=512 count=1<br />
<br />
A safer way is to restore only the MBR boot code use:<br />
<br />
# dd if=/path/to/backup/mbr-boot-code of=/dev/sdX bs=446 count=1<br />
<br />
=== Arch not found from other OS ===<br />
Some have reported that other distributions have trouble finding Arch Linux automatically with {{ic|os-prober}}. If this problem arises, it has been reported that detection can be improved with the presence of {{ic|/etc/lsb-release}}. This file and updating tool is available with the package {{Pkg|lsb-release}} in the [[official repositories]].<br />
<br />
== See also ==<br />
# Official GRUB Manual - https://www.gnu.org/software/grub/manual/grub.html<br />
# Ubuntu wiki page for GRUB - https://help.ubuntu.com/community/Grub2<br />
# GRUB wiki page describing steps to compile for UEFI systems - https://help.ubuntu.com/community/UEFIBooting<br />
# Wikipedia's page on [[Wikipedia:BIOS Boot partition|BIOS Boot partition]]<br />
# http://members.iinet.net/~herman546/p20/GRUB2%20Configuration%20File%20Commands.html - quite complete description of how to configure GRUB</div>B6hgas5https://wiki.archlinux.org/index.php?title=AMD_Catalyst&diff=339877AMD Catalyst2014-10-13T00:10:40Z<p>B6hgas5: Add easy copy-paste version</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X Server]]<br />
[[es:ATI Catalyst]]<br />
[[fr:ATI#Catalyst]]<br />
[[it:AMD Catalyst]]<br />
[[ja:AMD Catalyst]]<br />
[[zh-CN:AMD Catalyst]]<br />
{{Related articles start}}<br />
{{Related|ATI}}<br />
{{Related|Xorg}}<br />
{{Related articles end}}<br />
<br />
Owners of ATI/AMD video cards have a choice between AMD's proprietary driver ({{AUR|catalyst}}) and the [[ATI|open source driver]] ({{Pkg|xf86-video-ati}}). This article covers the proprietary driver.<br />
<br />
AMD's Linux driver package ''catalyst'' was previously named ''fglrx'' ('''F'''ire'''GL''' and '''R'''adeon '''X'''). Only the package name has changed, while the kernel module retains its original ''fglrx.ko'' filename. Therefore, any mention of fglrx below is specifically in reference to the ''kernel module'', '''not the package'''.<br />
<br />
'''Catalyst packages are no longer offered in the official repositories.''' In the past, Catalyst [https://www.archlinux.org/news/ati-catalyst-support-dropped/ has been dropped] from official Arch support because of dissatisfaction with the quality and speed of development. After a brief return they were dropped again in April 2013 and they have not returned since.<br />
<br />
Compared with the open source driver, Catalyst performs better in both 2D and 3D rendering, also having better power management, but it lacks efficient multi-head support. Supported devices are [[wikipedia:Radeon|ATI/AMD Radeon]] video cards with chipset R600 and newer (Radeon HD 2xxx and newer). See the Xorg [http://www.x.org/wiki/RadeonFeature/#index5h2 decoder ring] or [[wikipedia:Comparison of AMD graphics processing units|this table]], to translate ''model'' names (X1900, HD4850) to/from ''chip'' names (R580, RV770 respectively).<br />
<br />
== Installation ==<br />
<br />
There are three ways of installing Catalyst on your system. One way is to use [https://aur.archlinux.org/account/Vi0l0/ Vi0L0's] (Arch's unofficial Catalyst maintainer) repository. This repository contains all the necessary packages. The second method you can use is the AUR; PKGBUILDs offered here are also made by Vi0L0 and are the same he uses to built packages for his repository. Lastly, you can install the driver directly from AMD.<br />
<br />
Before choosing the method you prefer, you will have to see which driver you need. Since Catalyst 12.4, AMD has separated its development for Radeon HD 2xxx, 3xxx and 4xxx cards into the '''legacy''' Catalyst driver. For Radeon HD 5xxx and newer, there is the regular Catalyst driver. Regardless of the driver you need, you will also need the Catalyst utilities.<br />
<br />
{{Note|After the instructions for every method of installing, you will find general instructions '''everyone''' has to perform, regardless of the method you used.}}<br />
<br />
=== Installing the driver ===<br />
<br />
==== Installing from the unofficial repository ====<br />
<br />
If you don't fancy building the packages from the [[Arch User Repository|AUR]], this is the way to go. The repository is maintained by our unofficial Catalyst maintainer, [[User:Vi0L0|Vi0l0]]. All packages are signed and are considered safe to use. As you will see later on in this article, Vi0L0 is also responsible for many other packages that will help you get your system working with your ATI graphic cards. <br />
<br />
Vi0L0 has three different Catalyst repositories, each having different drivers:<br />
* [[Unofficial user repositories#catalyst|catalyst]] for the regular Catalyst driver needed by Radeon HD 5xxx and up, it contains the latest (stable or beta) Catalyst release.<br />
* ''catalyst-stable'' for the regular Catalyst driver needed by Radeon HD 5xxx and up, with the latest stable driver.<br />
* [[Unofficial user repositories#catalyst-hd234k|catalyst-hd234k]] for the legacy Catalyst driver needed by Radeon HD 2xxx, 3xxx and 4xxx cards.<br />
<br />
To enable one of these, follow the instructions in [[Unofficial user repositories]]. Remember to add the chosen repository '''above all other repositories''' in {{ic|pacman.conf}}.<br />
<br />
{{Note|The ''catalyst'' and ''catalyst-stable'' repositories share the same URL. To enable ''catalyst-stable'', follow the instructions for enabling ''catalyst'' and replace {{ic|[catalyst]}} with {{ic|[catalyst-stable]}} in {{ic|pacman.conf}}. If you need to stick with an old version, there are also some versioned repositories using the same URL (for example ''catalyst-stable-13.4'').}}<br />
<br />
{{Warning|<br />
* The legacy Catalyst driver does not support Xorg Server 1.13. Should you want to use this driver, see [[#Xorg repositories]] for instructions on how to roll back to Xorg Server 1.12.<br />
}}<br />
<br />
{{Tip|Because catalyst.wirephire.com will go down if a certain bandwidth limit is exceeded (this happened in the past) or may be too slow at your location, repository mirrors are provided by rtsinformatique at [http://mirror.rts-informatique.fr/archlinux-catalyst/] (France) and goll at [http://mirror.hactar.bz/Vi0L0/] (DE). These mirrors however come with no warranty and are not guaranteed to always be operational. Uncomment the line for the mirror closest to your location. It is also a good idea to keep alternatives in case of mirror downtime.<br />
<br />
Repository mirroring can be easily achieved using {{ic|rsync://mirror.rts-informatique.fr::archlinux-catalyst}}.<br />
}}<br />
<br />
Once you have added some Catalyst repository, update pacman's database and [[pacman|install]] these packages (see [[#Tools]] for more information):<br />
<br />
* ''catalyst-hook''<br />
* ''catalyst-utils''<br />
* ''catalyst-libgl''<br />
* ''opencl-catalyst'' - optional, needed for OpenCL support<br />
* ''lib32-catalyst-utils'' - optional, needed for 32-bit OpenGL support on 64-bit systems<br />
* ''lib32-catalyst-libgl'' - optional, needed for 32-bit OpenGL support on 64-bit systems<br />
* ''lib32-opencl-catalyst'' - optional, needed for 32-bit OpenCL support on 64-bit systems<br />
<br />
# pacman -S catalyst-hook catalyst-utils opencl-catalyst \<br />
lib32-catalyst-utils lib32-catalyst-libgl lib32-opencl-catalyst<br />
<br />
If you are using a notebook with hybrid Intel/AMD graphics card, the set of packages will be slightly different:<br />
<br />
* ''catalyst-hook''<br />
* ''catalyst-utils-pxp''<br />
* ''lib32-catalyst-utils-pxp'' - optional, needed for 32-bit OpenGL support on 64-bit systems<br />
<br />
{{Note|If pacman asks you about removing '''libgl''' you can safely do so.}}<br />
<br />
{{Warning|catalyst package was removed from Vi0L0's repository, its place was taken by catalyst-hook.}}<br />
<br />
==== Installing from the AUR ====<br />
The second way to install Catalyst is from the [[Arch User Repository|AUR]]. If you want to built the packages specifically for your computer, this is your way to go. Note that this is also the most tedious way to install Catalyst; it requires the most work and also requires manual updates upon every kernel update.<br />
<br />
{{Warning|If you install the Catalyst package from the AUR, you will have to rebuild Catalyst every time the kernel is updated. Otherwise X '''will''' fail to start.}}<br />
<br />
All packages mentioned above in Vi0L0's unofficial repository are also available on the [[Arch User Repository|AUR]]:<br />
* {{AUR|catalyst}}<br />
* {{AUR|catalyst-generator}}<br />
* {{AUR|catalyst-hook}}<br />
* {{AUR|catalyst-utils}}<br />
* {{AUR|lib32-catalyst-utils}}<br />
<br />
The AUR also holds some packages that are '''not''' found in any of the repositories. These packages contain the so-called ''Catalyst-total'' packages and the beta versions:<br />
* {{AUR|catalyst-total}}<br />
* {{AUR|catalyst-total-pxp}}<br />
* {{AUR|catalyst-total-hd234k}}<br />
* {{AUR|catalyst-test}}<br />
<br />
The {{AUR|catalyst-total}} packages are made to make the lives of AUR users easier. It builds the driver, the kernel utilities and the 32 bit kernel utilities. It also builds the {{AUR|catalyst-hook}} package, which described in [[#Tools]].<br />
<br />
{{AUR|catalyst-total-pxp}} builds Catalyst with experimental powerXpress support.<br />
<br />
=== Configuring the driver ===<br />
After you have installed the driver via your chosen method, you will have to configure X to work with Catalyst. Also, you will have to make sure the module gets loaded at boot. Also, one should disable [[KMS|kernel mode setting]].<br />
<br />
==== Configuring X ====<br />
To configure X, you will have to create an {{ic|xorg.conf}} file. Catalyst provides its own {{ic|aticonfig}} tool to create and/or modify this file.<br />
It also can configure virtually every aspect of the card for it also accesses the {{ic|/etc/ati/amdpcsdb}} file. For a complete list of {{ic|aticonfig}} options, run:<br />
<br />
# aticonfig --help | less<br />
<br />
{{Warning|Use the {{ic|--output}} option before committing to {{ic|/etc/X11/}} as an {{ic|xorg.conf}} file will override anything in {{ic|/etc/X11/xorg.conf.d/}}}}<br />
<br />
{{Note|To adhere to the new config location use {{ic|# aticonfig [...] --output}} to adapt the {{ic|Device}} section to {{ic|/etc/X11/xorg.conf.d/20-radeon.conf}}. The drawback is that many {{ic|aticonfig}} options rely on an {{ic|xorg.conf}}, and will be unavailable.}}<br />
<br />
Now, to configure Catalyst. If you have only one monitor, run this:<br />
<br />
# aticonfig --initial<br />
<br />
{{Note | If you have a PowerXpress problem you should probably install {{AUR|catalyst-total-pxp}}.}}<br />
<br />
However, if you have two monitors and want to use both of them, you can run the command stated below. Note that this will generate a dual head configuration with the second screen located above the first screen.<br />
<br />
# aticonfig --initial=dual-head --screen-layout=above<br />
<br />
{{Note|See [[#Double Screen (Dual Head / Dual Screen / Xinerama)]] for more information on setting up dual monitors.}}<br />
<br />
You can compare the generated file to one of the [[Xorg#Sample configurations|Sample Xorg.conf]] examples listed on the Xorg page.<br />
<br />
Although the current Xorg versions auto-detect most options when started, you may want to specify some in case the defaults change between versions.<br />
<br />
Here is an example (with notes) '''for reference'''. Entries with {{ic|#}} should be required, add entries with {{ic|##}} as needed:<br />
<br />
{{hc|/etc/X11/xorg.conf|2=<br />
Section "ServerLayout"<br />
Identifier "Arch"<br />
Screen 0 "Screen0" 0 0 # 0's are necessary.<br />
EndSection<br />
Section "Module"<br />
Load [...]<br />
[...]<br />
EndSection<br />
Section "Monitor"<br />
Identifier "Monitor0"<br />
[...]<br />
EndSection<br />
Section "Device"<br />
Identifier "Card0"<br />
Driver "fglrx" # Essential.<br />
BusID "PCI:1:0:0" # Recommended if autodetect fails.<br />
Option "OpenGLOverlay" "0" ##<br />
Option "XAANoOffscreenPixmaps" "false" ##<br />
EndSection<br />
Section "Screen"<br />
Identifier "Screen0"<br />
Device "Card0"<br />
Monitor "Monitor0"<br />
DefaultDepth 24<br />
SubSection "Display"<br />
Viewport 0 0<br />
Depth 24 # Should not change from '24'<br />
Modes "1280x1024" "2048x1536" ## 1st value=default resolution, 2nd=maximum.<br />
Virtual 1664 1200 ## (x+64, y) to workaround potential OGL rect. artifacts/<br />
EndSubSection ## fixed in Catalyst 9.8<br />
EndSection<br />
Section "DRI"<br />
Mode 0666 # May help enable direct rendering.<br />
EndSection<br />
}}<br />
<br />
{{Note|With '''every''' Catalyst update you should remove {{ic|amdpcsdb}} file in this way: kill X, remove {{ic|/etc/ati/amdpcsdb}}, start X and then run {{ic|amdcccle}} - otherwise the version of Catalyst may display wrongly in {{ic|amdcccle}}.}}<br />
<br />
''If you need more information on Catalyst, visit [https://bbs.archlinux.org/viewtopic.php?id=57084 this thread].''<br />
<br />
==== Loading the module at boot ====<br />
We have to blacklist the {{ic|radeon}} module to prevent it from auto-loading. To do so, blacklist ''radeon'' in {{ic|/etc/modprobe.d/modprobe.conf}}. Also, make sure that it is not loaded by any file under {{ic|/etc/modules-load.d/}}. For more information, see [[kernel modules#Blacklisting]]. <br />
<br />
Then we will have to make sure that the {{ic|fglrx}} module gets auto-loaded. Either add {{ic|fglrx}} on a new line of an existing module file located under {{ic|/etc/modules-load.d/}}, or create a new file and add {{ic|fglrx}}.<br />
<br />
==== Disable kernel mode setting ====<br />
<br />
{{Note|Don't do this if you are using {{ic|catalyst-utils-pxp}} or {{ic|catalyst-total-pxp}} because intel driver needs it.}}<br />
<br />
Disabling kernel mode setting is important, as the driver doesn't take advantage of [[KMS]] yet. If you do not deactivate KMS, your system might freeze when trying to switch to a TTY or even when shutting down via your DE.<br />
<br />
To disable kernel mode setting, add {{ic|nomodeset}} to your [[kernel parameters]].<br />
<br />
==== Checking operation ====<br />
<br />
Assuming that a reboot to your login was successful, you can check if {{ic|fglrx}} is running properly with the following commands:<br />
<br />
$ lsmod | grep fglrx<br />
$ fglrxinfo<br />
<br />
If you get output, it works. Finally, run X with {{ic|$ startx}} or by using GDM/KDM and verify that direct rendering is enabled by running the following command in a terminal:<br />
<br />
$ glxinfo | grep "direct rendering"<br />
<br />
If it says {{ic|"direct rendering: yes"}} then you're good to go! If the {{ic|$ glxinfo}} command is not found install the {{Pkg|mesa-demos}} package.<br />
<br />
{{Note|You can also use:<br />
$ fgl_glxgears<br />
as the fglrx alternative test to {{ic|glxgears}}.<br />
}}<br />
<br />
{{Warning|In recent versions of Xorg, the paths of libs are changed. So, sometimes {{ic|libGL.so}} cannot be correctly loaded even if it's installed. Check this if your GL is not working. Please read [[#Troubleshooting]] section for details.}}<br />
<br />
=== Custom kernels ===<br />
<br />
{{Note|If you are at all uncomfortable or inexperienced with making packages, read up the [[ABS]] wiki page first so things go smoothly.}}<br />
<br />
To install catalyst for a custom kernel, you'll need to build your own {{ic|catalyst-$kernel}} package:<br />
<br />
# Obtain the {{ic|PKGBUILD}} and {{ic|catalyst.install}} files from [[AUR|Catalyst]].<br />
# Editing the PKGBUILD. Two changes need to be made here:<br />
## Change {{ic|1=pkgname=catalyst}} to {{ic|1=pkgname=catalyst-$kernel_name}}, where {{ic|$kernel_name}} is whatever you want (e.g. custom, mm, themostawesomekernelever).<br />
## Change the dependency of {{ic|linux}} to {{ic|$kernel_name}}.<br />
# Build your package and install; run {{ic|makepkg -i}} or {{ic|makepkg}} followed by {{ic|# pacman -U pkgname.pkg.tar.gz}}<br />
<br />
{{Note|<br />
*If you run multiple kernels, you have to install the {{AUR|catalyst-utils}} packages for all kernels. They won't conflict with one another.<br />
*{{AUR|catalyst-generator}} is able to build {{ic|<nowiki>catalyst-{kernver}</nowiki>}} packages for you so you do not actually need to perform all those steps manually. For more information, see [[#Tools| Tools section]].}}<br />
<br />
=== PowerXpress support ===<br />
<br />
PowerXpress technology allows switching notebooks with dual-graphic capability from integrated graphics (IGP) to discrete graphics either to increase battery life or to achieve better 3D rendering capabilities.<br />
<br />
To use such functionality on Arch you will have to:<br />
* Get and build {{AUR|catalyst-total-pxp}} package from the [[Arch User Repository|AUR]], or<br />
* Install '''catalyst-utils-pxp''' package from the [catalyst] repository (plus additional lib32-catalyst-utils-pxp, if needed).<br />
<br />
To perform a switch into Intel's IGP you will also have to install the {{pkg|mesa-libgl}} package and Intel's drivers: {{pkg|xf86-video-intel}} and {{pkg|intel-dri}}.<br />
<br />
{{Note|'''With the latest version of Catalyst, version 13.1 (not Catalyst legacy) ChrisXY was able to work on the newest {{pkg|xorg-server}} (version 1.13.1), {{Pkg|mesa}} 9.0.1 and {{pkg|xf86-video-intel}} 2.20.18'''.<br />
<br />
On any version of Catalyst below 13.1 (and all versions of Catalyst legacy) there are some problems with the new Intel drivers and the '''last noted working version of {{pkg|xf86-video-intel}} is 2.20.2-2''', so you will probably have to downgrade from the latest version that you have gotten from Arch's repositories (although we recommend to test the newest one before downgrading - there's always some possibility that it will work).<br />
<br />
{{pkg|xf86-video-intel}} 2.20.2-2 works only with xorg-server 1.12 and so it is a part of the '''xorg112 repository'''. If you want to use it you will have to downgrade xorg-server as well. For information on this, see [[#Xorg repositories]].}}<br />
<br />
Now you can switch between the integrated and the discrete GPU, using these commands:<br />
<br />
{{bc|1=<br />
# aticonfig --px-igpu #for integrated GPU<br />
# aticonfig --px-dgpu #for discrete GPU<br />
}}<br />
<br />
Just remember that fglrx needs {{ic|/etc/X11/xorg.conf}} configured for AMD's card with {{ic|fglrx}} inside.<br />
<br />
You can also use the {{ic|pxp_switch_catalyst}} switching script that will perform some additional usefull operations:<br />
* Switching {{ic|xorg.conf}} - it will rename {{ic|xorg.conf}} into {{ic|xorg.conf.cat}} (if there's fglrx inside) or {{ic|xorg.conf.oth}} (if there's intel inside) and then it will create a symlink to {{ic|xorg.conf}}, depending on what you chose.<br />
* Running {{ic|aticonfig --px-Xgpu}}.<br />
* Running {{ic|switchlibGL}}.<br />
* Adding/removing {{ic|fglrx}} into/from {{ic|/etc/modules-load.d/catalyst.conf}}.<br />
<br />
Usage:<br />
{{bc|1=<br />
# pxp_switch_catalyst amd<br />
# pxp_switch_catalyst intel<br />
}}<br />
<br />
If you have got problems when you try to run X on Intel's driver you may try to force "UXA" acceleration. Just make sure you got {{ic|Option "AccelMethod" "uxa"}} in {{ic|xorg.conf}}:<br />
{{hc|/etc/X11/xorg.conf|2=<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
#Option "AccelMethod" "sna"<br />
'''Option "AccelMethod" "uxa"'''<br />
#Option "AccelMethod" "xaa"<br />
EndSection<br />
}}<br />
<br />
==== Running two X servers (one using the Intel driver, another one using fglrx) simultaneously ====<br />
Because fglrx is crash-prone (regarding PowerXpress), it could be a good idea to use the Intel driver in the main X server and have a secondary X server using fglrx when 3D acceleration is needed. However, simply switching to the discrete GPU from the integrated GPU using {{ic|aticonfig}} or {{ic|amdcccle}} will cause all sorts of weird bugs when starting the second X.<br />
<br />
To run two X servers at the same time (each using different drivers), you should firstly set up a fully working X with Catalyst and then move its {{ic|xorg.conf}} to a temporary place (for example, {{ic|/etc/X11/xorg.conf.fglrx}}. The next time X is started, it will use the Intel driver by default instead of fglrx.<br />
<br />
To start a second X server using fglrx, simply move {{ic|xorg.conf}} back to the proper place ({{ic|/etc/X11/xorg.conf}}) before starting X. This method even allows you to switch between running X sessions. When you are done using fglrx, move {{ic|xorg.conf}} somewhere else again.<br />
<br />
The only disadvantage of this method is not having 3D acceleration using the Intel driver. 2D acceleration, however, is fully functional. Other than that, this will provide us with a completely stable desktop.<br />
<br />
==== Issues with PowerXpress laptops running in AMD mode (pxp_switch_catalyst amd) with external / secondary monitor ====<br />
When using a PowerXpress laptop in AMD-only mode (ie, setting the discrete card to render everything) you sometimes run into issues with artifacting/duplicating between displays. This is a known issue, and seems to effect 7xxxM series cards.<br />
<br />
The artifacting disappears when you transform one of the monitors by either rotating or scaling. So you can use xrandr to fix this:<br />
<br />
{{bc|1=<br />
xrandr --output HDMI1 --left-of LVDS1 --primary --scale 1x1 --output LVDS1 --scale 1.0001x1.0001<br />
}}<br />
<br />
== Xorg repositories ==<br />
Catalyst is notorious for its slow update process. As such, it is common that a new Xorg version is pushed down from upstream that will break compatibility for Catalyst. This means that Catalyst users either have to build Xorg packages on their own, or use a backported repository that only contains the Xorg packages that should be hold back. Vi0L0 has stepped in to fulfil this task and provides several backported repositories. <br />
<br />
To enable one of these, follow the instructions in [[Unofficial user repositories]] (use the same PGP key as for the [[Unofficial user repositories#catalyst|catalyst]] repository). Remember to add the chosen repository '''above all other repositories''' in {{ic|pacman.conf}}, even above your ''catalyst'' repository, should you use one.<br />
<br />
=== xorg115 ===<br />
Catalyst < 14.9 doesn't support xorg-server 1.16<br />
<br />
{{bc|<nowiki><br />
[xorg115]<br />
Server = http://catalyst.wirephire.com/repo/xorg115/$arch<br />
## Mirrors, if the primary server does not work or is too slow:<br />
#Server = http://mirror.rts-informatique.fr/archlinux-catalyst/repo/xorg115/$arch<br />
#Server = http://mirror.hactar.bz/Vi0L0/xorg115/$arch<br />
</nowiki>}}<br />
<br />
=== xorg114 ===<br />
Catalyst < 14.1 doesn't support xorg-server 1.15.<br />
<br />
{{bc|<nowiki><br />
[xorg114]<br />
Server = http://catalyst.wirephire.com/repo/xorg114/$arch<br />
## Mirrors, if the primary server does not work or is too slow:<br />
#Server = http://mirror.rts-informatique.fr/archlinux-catalyst/repo/xorg114/$arch<br />
#Server = http://mirror.hactar.bz/Vi0L0/xorg114/$arch<br />
</nowiki>}}<br />
<br />
=== xorg113 ===<br />
Catalyst < 13.6 doesn't support xorg-server 1.14.<br />
<br />
{{bc|<nowiki><br />
[xorg113]<br />
Server = http://catalyst.wirephire.com/repo/xorg113/$arch<br />
## Mirrors, if the primary server does not work or is too slow:<br />
#Server = http://mirror.rts-informatique.fr/archlinux-catalyst/repo/xorg113/$arch<br />
#Server = http://mirror.hactar.bz/Vi0L0/xorg113/$arch<br />
</nowiki>}}<br />
<br />
=== xorg112 ===<br />
Catalyst < 12.10 and Catalyst Legacy do not support xorg-server 1.13.<br />
<br />
{{bc|<nowiki><br />
[xorg112]<br />
Server = http://catalyst.wirephire.com/repo/xorg112/$arch<br />
## Mirrors, if the primary server does not work or is too slow:<br />
#Server = http://mirror.rts-informatique.fr/archlinux-catalyst/repo/xorg112/$arch<br />
#Server = http://mirror.hactar.bz/Vi0L0/xorg112/$arch<br />
</nowiki>}}<br />
<br />
== Tools ==<br />
<br />
=== Catalyst-hook ===<br />
{{AUR|Catalyst-hook}} is a [[systemd]] service that will automatically rebuild the {{ic|fglrx}} modules while the system shuts down or reboots, but only if it's necessary (e.g. after an update).<br />
<br />
Before using this package make sure that both the {{Grp|base-devel}} group and the {{Pkg|linux-headers}} package (the one specific to the kernel you use) are installed.<br />
<br />
To enable the automatic update, enable the {{ic|catalyst-hook.service}}:<br />
<br />
# systemctl enable catalyst-hook<br />
# systemctl start catalyst-hook<br />
<br />
You can also use this package to build the {{ic|fglrx}} module manually. Simply run the {{ic|catalyst_build_module}} script after the kernel has been updated:<br />
<br />
# catalyst_build_module all<br />
<br />
'''A few more technical details:'''<br />
<br />
The {{ic|catalyst-hook.service}} is stopping the systemd "river" and is forcing systemd to wait until catalyst-hook finishes its job.<br />
<br />
The {{ic|catalyst-hook.service}} is calling the {{ic|catalyst_build_module check}} function which checks if fglrx rebuilds are really necessary.<br />
<br />
The {{ic|check}} function is checking if the {{ic|fglrx}} module exists, if it:<br />
<br />
*doesn't exist, it will build it;<br />
<br />
*does exist, it will compare the two values to be sure that a rebuild is necessary.<br />
<br />
These values are md5sums of the {{ic|/usr/lib/modules/<kernel_version>/build/Module.symvers}} file (because I, Vi0L0, noticed that this file is unique and different for every kernel's release). The first value is the md5sum of the existing {{ic|Module.symvers}} file. The second value is the md5sum of the {{ic|Module.symvers}} file which existed in a moment of the {{ic|fglrx}} module creation. This value was compiled into the {{ic|fglrx}} module by a {{ic|catalyst_build_module}} script.<br />
<br />
If the values are different, it will compile the new {{ic|fglrx}} module.<br />
<br />
The check is checking the whole {{ic|/usr/lib/modules/}} directory and building modules for all of the installed kernels if it's necessary. If the build or rebuild isn't necessary, the whole process takes only some milliseconds to complete before it gets killed by systemd.<br />
<br />
=== Catalyst-generator ===<br />
<br />
{{AUR|catalyst-generator}} is a package that is able to build and install the {{ic|fglrx}} module packed into pacman compliant {{ic|<nowiki>catalyst-${kernver}</nowiki>}} packages. The basic difference from [[#Catalyst-hook]] is that you will have to trigger this command manually, whereas Catalyst-hook will do this automatically at boot when a new kernel got installed.<br />
<br />
It creates {{ic|<nowiki>catalyst-${kernver}</nowiki>}} packages using [[makepkg]] and installs them with [[pacman]]. {{ic|${kernver}}} is the kernel version for which each package was built (e.g. catalyst-2.6.35-ARCH package was built for 2.6.35-ARCH kernel).<br />
<br />
To build and install {{ic|<nowiki>catalyst-${kernver}</nowiki>}} package for a currently booted kernel as an unprivileged user (non-root; safer way), use {{ic|catalyst_build_module}}. You will be asked for your root password to proceed to package installation.<br />
<br />
A short summary on how to use this package:<br />
<br />
# As root: {{ic|catalyst_build_module remove}}. This will remove all unused {{ic|<nowiki>catalyst-{kernver}</nowiki>}} packages.<br />
# As unprivileged user: {{ic|<nowiki>catalyst_build_module ${kernver}</nowiki>}}, where {{ic|<nowiki>${kernver}</nowiki>}} is the version of the kernel to which you just updated. For example: {{ic|catalyst_build_module 2.6.36-ARCH}}. You can also build {{ic|<nowiki>catalyst-{kernver}</nowiki>}} for all installed kernels by using {{ic|catalyst_build_module all}}.<br />
# If you want to remove {{ic|catalyst-generator}}, it's best to run this as root before removing catalyst-generator: {{ic|catalyst_build_module remove_all}}. '''This will remove all {{ic|<nowiki>catalyst-{kernver}</nowiki>}} packages from the system.'''<br />
<br />
{{ic|Catalyst-generator}} isn't able to remove all those {{ic|<nowiki>catalyst-{kernver}</nowiki>}} packages automatically while being removed because there can not be more than one instance of pacman running. If you forget to run {{ic|# catalyst_build_module remove_all}} before using {{ic|# pacman -R catalyst-generator}} catalyst-generator will tell you which {{ic|<nowiki>catalyst-{kernver}</nowiki>}} packages you will have to remove manually after removing catalyst-generator itself.<br />
<br />
Catalyst-generator is most safe and KISS-friendly solution because:<br />
<br />
# you can use unprivileged user to build the package;<br />
# it is building modules in a fakeroot environment;<br />
# it is not throwing files here and there, [[pacman]] always knows where they are;<br />
# all you have to do is to remember to use it<br />
<br />
{{Note|If you see those warnings:<br />
<br />
'''WARNING:''' Package contains reference to $srcdir<br />
<br />
'''WARNING:''' '.pkg' is not a valid archive extension.<br />
<br />
while building {{ic|<nowiki>catalyst-{kernver}</nowiki>}} package, do not be concerned, it's normal.}}<br />
<br />
=== OpenCL and OpenGL development ===<br />
<br />
Since years AMD is working on tools for OpenCL and OpenGL developement.<br />
<br />
Now under the banner of '''"Heterogeneous Computing"''' AMD is providing even more of them, fortunately most of their computing tools are available also for Linux.<br />
<br />
In the AUR and the [catalyst] repositories you will find packages that represent the most important work from AMD, namely; [https://aur.archlinux.org/packages/amdapp-aparapi amdapp-aparapi], [https://aur.archlinux.org/packages/amdapp-sdk amdapp-sdk] and [https://aur.archlinux.org/packages/amdapp-codexl amdapp-codexl].<br />
<br />
APP shortcut stands for Accelerated Parallel Processing.<br />
<br />
==== amdapp-aparapi ====<br />
AMD's Aparapi is an API for expressing data parallel workloads in Java and a runtime component capable of converting the Java bytecode of compatible workloads into OpenCL so that it can be executed on a variety of GPU devices. If Aparapi can’t execute on the GPU, it will execute in a Java thread pool.<br />
<br />
You can find more information about Aparapi [http://developer.amd.com/tools/heterogeneous-computing/aparapi/ here].<br />
<br />
==== amdapp-sdk (formerly known as amdstream) ====<br />
The AMD APP Software Development Kit (SDK) is a complete development platform created by AMD to allow you to quickly and easily develop applications accelerated by AMD APP technology. The SDK provides samples, documentation and other materials to quickly get you started leveraging accelerated compute using OpenCL, Bolt, or C++ AMP in your C/C++ application.<br />
<br />
Since version 2.8 amdapp-sdk is providing aparapiUtil as well as aparapi's samples. A package is available on the [catalyst] repository; it depends on the {{AUR|amdapp-aparapi}} package. The AUR's package will let you decide whether you want aparapi's additions or not.<br />
<br />
Version 2.8 does not provide Profiler functionality, it has been moved to CodeXL.<br />
<br />
You can find more information about AMD APP SDK [http://developer.amd.com/tools/heterogeneous-computing/amd-accelerated-parallel-processing-app-sdk/ here].<br />
<br />
==== amdapp-codexl ====<br />
CodeXL is an OpenCL and OpenGL Debugger and Profiler, with a static OpenCL kernel analyzer. It's a GUI application written atop of the well known [https://aur.archlinux.org/packages/gdebugger gDEBugger] and is available only for x86_64 systems.<br />
<br />
You can find more informations about CodeXL [http://developer.amd.com/tools/heterogeneous-computing/codexl/ here].<br />
<br />
== Features ==<br />
<br />
=== Tear Free Rendering ===<br />
<br />
Presented in '''Catalyst 11.1''', the ''Tear Free Desktop'' feature reduces tearing in 2D, 3D and video applications. This likely adds triple-buffering and v-sync. Do note that it requires additional GPU processing.<br />
<br />
To enable 'Tear Free Desktop' run {{ic|amdcccle}} and go to: {{ic|Display Options}} → {{ic|Tear Free}}.<br />
<br />
Or as root run:<br />
<br />
# aticonfig --set-pcs-u32=DDX,EnableTearFreeDesktop,1<br />
<br />
To disable, again use {{ic|amdcccle}} or run as root:<br />
<br />
# aticonfig --del-pcs-key=DDX,EnableTearFreeDesktop<br />
<br />
=== Video acceleration ===<br />
<br />
'''[[wikipedia:Video_Acceleration_API|Video Acceleration API]] (VA API)''' is an open source software library (libVA) and API specification which provides GPU acceleration for video processing on Linux/UNIX based operating systems. The process works by enabling hardware accelerated video decode at various entry-points (VLD, IDCT, Motion Compensation, deblocking) for common encoding standards (MPEG-2, MPEG-4 ASP/H.263, MPEG-4 AVC/H.264, and VC-1/WMV3).<br />
<br />
VA-API gained a proprietary backend (in November 2009) called {{AUR|xvba-video}}, that allows VA-API programmed applications to take advantage of AMD Radeons UVD2 chipsets via the [[wikipedia:XvBA|XvBA (X-Video Bitstream Acceleration API designed by AMD)]] library.<br />
<br />
XvBA support and xvba-video is still under development, however it is '''working very well in most cases'''. Build (or install from Vi0L0's repo) the proprietary {{AUR|xvba-video}} package, or if you have problems with that version, install {{AUR|libva-xvba-driver}}; and also install {{Pkg|mplayer-vaapi}} and {{Pkg|libva}}. Then just set your video player to use vaapi:gl as video output:<br />
<br />
$ mplayer -vo vaapi:gl movie.avi<br />
<br />
These options can be added to your mplayer configuration file, see [[MPlayer]].<br />
<br />
For '''smplayer''':<br />
<br />
Options → Preferences → General → Video (tab) → Output driver: User Defined : vaapi:gl<br />
Options → Preferences → General → Video (tab) → Double buffering '''on'''<br />
Options → Preferences → General → General → Screenshots → Turn screenshots '''off'''<br />
Options → Preferences → Performance → Threads for decoding: '''1''' (to turn off -lavdopts parameter)<br />
<br />
{{Note|If Tear Free Desktop is enabled it's better to use:<br />
Options → Preferences → General → Video (tab) → Output driver: vaapi<br />
If Video Output '''vaapi:gl''' isn't working - please check:<br />
'''vaapi''', '''vaapi:gl2''' or simply '''xv(0 - AMD Radeon [[wikipedia:Avivo|AVIVO Video]])'''.<br />
}}<br />
<br />
For '''VLC''':<br />
<br />
Tools → Preferences → Input & Codecs → Use GPU accelerated decoding<br />
<br />
It might help to enable v-sync in '''amdcccle''':<br />
<br />
3D → More Settings → Wait for vertical refresh = Always On<br />
<br />
{{Note|If you are using '''Compiz/KWin''', the only way to '''avoid video flickering''' is to watch videos in '''full-screen''' and only when '''Unredirect Fullscreen is off'''.<br />
<br />
In '''compiz''' you need to set '''Redirected Direct Rendering''' in General Options of ccsm. If it is still flickering, try to disable this option in CCSM. It's off by default in '''KWin''', but if you see flickering try to turn "Suspend desktop effects for fullscreen windows" on or off in {{ic|System Settings}} → {{ic|Desktop Effects}} → {{ic|Advanced}}.}}<br />
<br />
=== GPU/Mem frequency, Temperature, Fan speed, Overclocking utilities ===<br />
<br />
You can get the GPU/Mem clocks with: {{ic|$ aticonfig --od-getclocks}}.<br />
<br />
You can get the fan speed with: {{ic|$ aticonfig --pplib-cmd "get fanspeed 0"}}<br />
<br />
You can get the temperature with: {{ic|$ aticonfig --odgt}}<br />
<br />
To set the fanspeed with: {{ic|$ aticonfig --pplib-cmd "set fanspeed 0 50"}} Query Index: 50, Speed in percent<br />
<br />
To overclock and/or underclock it's easier to use a GUI, like '''ATi Overclocking Utility''', which is very simple and requires qt to work. It might be out of date/old, but you can get it [http://kde-apps.org/content/show.php/ATI+Overclock?content=47796 here].<br />
<br />
Another, more complex utility to perform such operations is '''AMDOverdriveCtrl'''. Its homepage is [http://sourceforge.net/projects/amdovdrvctrl here] and you can build {{AUR|amdoverdrivectrl}} from the AUR or from Vi0L0's unofficial repositories.<br />
<br />
=== Double Screen (Dual Head / Dual Screen / Xinerama) ===<br />
<br />
==== Introduction ====<br />
<br />
{{Warning| you should know that there isn't one specific solution because each setup differs and needs its own configuration. That's why you will have to adapt the steps below to your own needs. It is possible that you have to try more than once. Therefore, you should save your working {{ic|/etc/X11/xorg.conf}} '''before''' you start modifying and be able to recover from a command-line environment.}}<br />
<br />
* In this chapter, we will describe the installation of two different-sized screens on only one graphics card with two different output ports (DVI + HDMI) using a "BIG Desktop" configuration.<br />
<br />
* The Xinerama solution has some inconveniences, especially because it is not compatible with XrandR. For that very reason, you should not use this solution, because XrandR is a must for our later configuration.<br />
<br />
* The Dual Head solution would allow you to have 2 different sessions (one for each screen). It could be what you want, but you will not be able to move windows from one screen to another. If you have only one screen, you will have to define the mouse inside your Xorg session for each of the two sessions inside the Server Layout section.<br />
<br />
[http://support.amd.com/us/kbarticles/Pages/1105-HowCanIConfigureMultip.aspx ATI Documentation]<br />
<br />
==== ATI Catalyst Control Center ====<br />
<br />
The GUI tool shipped by ATI is very useful and we will try to use it as much as we can. To launch it, open a terminal and use the following command:<br />
<br />
$ {kdesu/gksu} amdcccle<br />
<br />
{{Warning|Do '''not''' use sudo directly with a GUI. Sudo gives you admin rights with user account information. Instead, use ''gksu'' (GNOME) or ''kdesu'' (KDE).}}<br />
<br />
==== Installation ====<br />
<br />
Before we start, make sure that your hardware is plugged in correctly, that power is on and that you know your hardware characteristics (screen dimensions, sizes, refreshment rates, etc.) Normally, both screens are recognized during boot time but not necessarily identified properly, especially if you are not using any Xorg base configuration file ({{ic|/etc/X11/xorg.conf}}) but relying on the hot-plugging feature.<br />
<br />
The first step is to make sure that you screens will be recognized by your DE and by X. For this, you need to generate a basic Xorg configuration file for your two screens:<br />
<br />
# aticonfig --initial --desktop-setup=horizontal --overlay-on=1<br />
<br />
or<br />
<br />
# aticonfig --initial=dual-head --screen-layout=left<br />
<br />
{{Note|{{ic|overlay}} is important because it allows you to have 1 pixel (or more) shared between the 2 screens.}}<br />
{{Tip|For the other possible and available options, do not hesitate to type {{ic|aticonfig --help}} inside a terminal to display all available command lines.}}<br />
<br />
Now you should have a basic Xorg configuration file that you can edit to add your screen resolutions. It is important to use the precise resolution, especially if you have screens of different sizes. These resolutions have to be added in the "Screen" section:<br />
<br />
SubSection "Display"<br />
Depth 24<br />
Modes "X-resolution screen 1xY-resolution screen 1" "Xresolution screen 2xY-resolution screen 2"<br />
EndSubSection<br />
<br />
From now on, instead of editing the {{ic|xorg.conf}} file manually, let us use the ATI GUI tool. Restart X to be sure that your two screens are properly supported and that the resolutions are properly recognized (Screens must be independent, not mirrored).<br />
<br />
==== Configuration ====<br />
<br />
Now you will only have to launch the ATI control center with root privileges, go to the display menu and choose how you would like to set your configuration (small arrow of the drop down menu). A last restart of X and you should be done!<br />
<br />
Before you restart X, do not hesitate to verify your new {{ic|xorg.conf}} file. At this stage, inside the "Display" sub-section of the "Screen" section, you should see a "Virtual" command line, of which the resolution should be the sum of both screens. The "Server Layout" section says all the rest.<br />
<br />
== Uninstallation ==<br />
<br />
If for any reason this driver is not working for you or if you simply want to try out the open source driver, remove the {{ic|catalyst}} and {{ic|catalyst-utils}} packages. Also you should remove {{AUR|catalyst-generator}}, {{AUR|catalyst-hook}} and {{AUR|lib32-catalyst-utils}} packages if they have been installed on your system.<br />
<br />
{{Warning|<br />
*You may need to use {{ic|# pacman -Rdd}} to remove {{AUR|catalyst-utils}} (and/or {{AUR|lib32-catalyst-utils}}) because that package contains ''gl'' related files and many of your installed packages depend on them. These dependencies will be satisfied again when you install {{Pkg|xf86-video-ati}}.<br />
*You may need to remove {{ic|/etc/profile.d/ati-flgrx.sh}} and {{ic|/etc/profile.d/lib32-catalyst}} (if it exists on your system), otherwise {{ic|r600_dri.so}} will fail to load and you would not have 3D support.}}<br />
<br />
{{Note|You should remove unofficial repositories from your {{ic|/etc/pacman.conf}} and run {{ic|# pacman -Syu}}, because those repositories include out-dated Xorg packages to allow use of {{ic|catalyst}} and the {{Pkg|xf86-video-ati}} package needs up-to-date Xorg packages from the [[Official repositories]].}}<br />
<br />
Also follow these steps:<br />
<br />
* If you have the {{ic|/etc/modprobe.d/blacklist-radeon.conf}} file remove it or comment the line {{ic|blacklist radeon}} in that file.<br />
* If you have a file in {{ic|/etc/modules-load.d}} to load the {{ic|fglrx}} module on boot, remove it or comment the line containing {{ic|fglrx}}.<br />
* Make sure to remove or backup {{ic|/etc/X11/xorg.conf}}.<br />
* If you have installed the {{AUR|catalyst-hook}} package, make sure to disable the systemd service.<br />
* If you used the {{ic|nomodeset}} option in your [[kernel parameters]] and plan to use [[#Kernel mode-setting (KMS)|KMS]], remove it.<br />
* '''Reboot''' before installing another driver.<br />
<br />
== Troubleshooting ==<br />
<br />
If you can still boot to command-line, then the problem probably lies in {{ic|/etc/X11/xorg.conf}}<br />
<br />
You can parse the whole {{ic|/var/log/Xorg.0.log}} or, for clues:<br />
<br />
$ grep '(EE)' /var/log/Xorg.0.log<br />
$ grep '(WW)' /var/log/Xorg.0.log<br />
<br />
If you are still confused about what is going on, search the forums first. Then post a message in the [https://bbs.archlinux.org/viewtopic.php?pid=1166052#p1166052/ thread specific to ATI/AMD]. Provide the information from {{ic|xorg.conf}} and both commands mentioned above.<br />
<br />
=== 3D Wine applications freeze ===<br />
If you use a 3D Wine application and it hangs, you have to disable TLS. To do this, either use {{ic|aticonfig}} or edit {{ic|/etc/X11/xorg.conf}}. To use {{ic|aticonfig}}:<br />
<br />
# aticonfig --tls=off<br />
<br />
Or, to edit {{ic|/etc/X11/xorg.conf}}; first open the file in an editor as root and then add {{ic|Option "UseFastTLS" "off"}} to the ''Device'' section of this file. <br />
<br />
After applying either of the solutions, restart X for it to take effect.<br />
<br />
=== Problems with video colours ===<br />
<br />
You may still use {{ic|vaapi:gl}} to avoid video flickering, but without video acceleration:<br />
<br />
* Run '''mplayer''' without {{ic|-vo vaapi}} switch.<br />
<br />
* Run '''smplayer''' remove {{ic|-vo vaapi}} from Options → Preferences → Advanced → Options for MPlayer → Options: -vo vaapi<br />
<br />
Plus for '''smplayer''' you may now safely turn screenshots on.<br />
<br />
=== KWin and composite ===<br />
<br />
You may use XRender if the rendering with OpenGL is slow. However, XRender might also be slower than OpenGL depending on your card.<br />
XRender also solves artefact issues in some cases, for instance when resizing Konsole.<br />
<br />
=== Black screen with complete lockups and/or hangs after reboot or startx ===<br />
<br />
Ensure you have added the {{ic|nomodeset}} option to the kernel options line in your bootloader (see [[#Disable kernel mode setting]]).<br />
<br />
If you are using the legacy driver ({{ic|catalyst-hd234k}}) and get a black screen, try downgrading xorg-server to 1.11 by using the [[#&#91;xorg111&#93;]] repository.<br />
<br />
==== Faulty ACPI hardware calls ====<br />
It is possible that fglrx doesn't cooperate well with the system's ACPI hardware calls, so it auto-disables itself and there is no screen output.<br />
<br />
If so, try to run this:<br />
<br />
$ aticonfig --acpi-services=off<br />
<br />
=== KDM disappears after logout ===<br />
<br />
If you are running Catalyst proprietary driver and you get a console (tty1) instead of the expected KDM greeting when you log out, you must instruct KDM to restart the X server after each logout. Uncomment the following line under the section titled {{ic|[X-:*-Core]}}<br />
<br />
{{hc|/usr/share/config/kdm/kdmrc|2=<br />
TerminateServer=True<br />
}}<br />
<br />
KDM should now appear when you log out of KDE.<br />
<br />
=== Direct Rendering does not work ===<br />
<br />
This problem may occur when using the proprietary '''Catalyst''' driver.<br />
<br />
{{Warning|This error would also appear if you have not '''rebooted''' your system after the installation or upgrade of catalyst. The system needs to load the fglrx.ko module in order to make the driver work.}}<br />
<br />
If you have problem with direct rendering, run:<br />
<br />
$ LIBGL_DEBUG=verbose glxinfo > /dev/null<br />
<br />
at the command prompt. At the very start of the output, it'll usually give you a nice error message saying why you do not have direct rendering.<br />
<br />
Common errors and their solutions, are:<br />
<br />
libGL error: XF86DRIQueryDirectRenderingCapable returned false<br />
<br />
* Ensure that you are loading the correct agp modules for your AGP chipset before you load the {{ic|fglrx}} kernel module. To determine which agp modules you'll need, run {{ic|# hwdetect --show-agp}}. Then open your {{ic|/etc/modules-load.d/fglrx.conf}} and add the agp module on a line '''before''' the {{ic|fglrx}} line.<br />
<br />
libGL error: failed to open DRM: Operation not permitted<br />
libGL error: reverting to (slow) indirect rendering<br />
<br />
libGL: OpenDriver: trying /usr/lib/xorg/modules/dri//fglrx_dri.so<br />
libGL error: dlopen /usr/lib/xorg/modules/dri//fglrx_dri.so failed<br />
(/usr/lib/xorg/modules/dri//fglrx_dri.so: cannot open shared object file: No such file or directory)<br />
libGL error: unable to find driver: fglrx_dri.so<br />
<br />
* Something has not been installed correctly. If the paths in the error message are {{ic|/usr/X11R6/lib/modules/dri/fglrx_dri.so}}, then ensure you've logged completely out of your system, then back in. If you're using a graphical login manager (gdm, kdm, xdm), ensure that {{ic|/etc/profile}} is sourced every time you log in. This is usually accomplished by adding {{ic|source /etc/profile}} into {{ic|~/.xsession}} or {{ic|~/.xinitrc}}, but this may vary between login managers.<br />
<br />
* If the paths above in your error message ''are'' {{ic|/usr/lib/xorg/modules/dri/fglrx_dri.so}}, then something has not been correctly installed. Try reinstalling the {{AUR|catalyst}} package.<br />
<br />
Errors such as:<br />
<br />
fglrx: libGL version undetermined - OpenGL module is using glapi fallback<br />
<br />
could be caused by having multiple versions of {{ic|libGL.so}} on your system. The command below should return the following output:<br />
<br />
{{hc|$ locate libGL.s|<br />
/usr/lib/libGL.so<br />
/usr/lib/libGL.so.1<br />
/usr/lib/libGL.so.1.2}}<br />
<br />
These are the only three libGL.so files you should have on your system. If you have any more (e.g. {{ic|/usr/X11R6/lib/libGL.so.1.2}}), then remove them. This should fix your problem.<br />
<br />
You might not get any error to indicate that this is a problem. If you are using X11R7, make sure you do '''not''' have these files on your system:<br />
<br />
/usr/X11R6/lib/libGL.so.1.2<br />
/usr/X11R6/lib/libGL.so.1<br />
<br />
=== Hibernate/Sleep issues ===<br />
<br />
==== Video fails to resume from suspend2ram ====<br />
<br />
ATI's proprietary Catalyst driver cannot resume from suspend if the framebuffer is enabled. To disable the framebuffer, add {{ic|1=vga=0}} to your kernel [[kernel parameters]].<br />
<br />
To see where you need to add this with other bootloaders, see [[#Disable kernel mode setting]].<br />
<br />
=== System freezes/Hard locks ===<br />
<br />
* The {{ic|radeonfb}} framebuffer drivers have been known in the past to cause problems of this nature. If your kernel has radeonfb support compiled in, you may want to try a different kernel and see if this helps.<br />
<br />
* If you experience system freezes when exiting your DE (shut down, suspend, switching to tty etc.) you probably forgot to deactivate KMS. (See [[#Disable kernel mode setting]])<br />
<br />
=== Hardware conflicts ===<br />
<br />
Radeon cards used in conjunction with some versions of the nForce3 chipset (e.g. nForce 3 250Gb) won't have 3D acceleration. Currently the cause of this issue is unknown, but some sources indicate that it may be possible to get acceleration with this combination of hardware by booting Windows with the drivers from nVIDIA and then rebooting the system. This can be verified by getting output something similar to this (using an nForce3-based system):<br />
<br />
{{hc|<nowiki>$ dmesg | grep agp</nowiki>|<br />
agpgart: Detected AGP bridge 0<br />
agpgart: Setting up Nforce3 AGP.<br />
agpgart: aperture base > 4G<br />
}}<br />
<br />
and also if issuing the following command gets you the following output:<br />
<br />
{{hc|<nowiki>$ tail -n 100 /var/log/Xorg.0.log | grep agp</nowiki>|<br />
(EE) fglrx(0): [agp] unable to acquire AGP, error "xf86_ENODEV"}}<br />
<br />
you have this bug.<br />
<br />
Some sources indicate that in some situations, downgrading the motherboard BIOS may help, but this cannot be verified in all cases. Also, '''a bad BIOS downgrade can render your hardware useless, so beware.'''<br />
<br />
See [http://bugzilla.kernel.org/show_bug.cgi?id=6350/ this bugreport] for more information and a potential fix.<br />
<br />
=== Temporary hangs when playing video ===<br />
<br />
This problem may occur when using the proprietary Catalyst.<br />
<br />
If you experience temporary hangs lasting from a few seconds to several minutes occuring randomly during playback with mplayer, check the system logs for output like:<br />
<br />
{{hc|/var/log/messages.log|2=<br />
Nov 28 18:31:56 pandemonium [<c01c64a6>] ? proc_get_sb+0xc6/0x160<br />
Nov 28 18:31:56 pandemonium [<c01c64a6>] ? proc_get_sb+0xc6/0x160<br />
Nov 28 18:31:56 pandemonium [<f8bc628c>] ? ip_firegl_ioctl+0x1c/0x30 [fglrx]<br />
Nov 28 18:31:56 pandemonium [<c01c64a6>] ? proc_get_sb+0xc6/0x160<br />
Nov 28 18:31:56 pandemonium [<c0197038>] ? vfs_ioctl+0x78/0x90<br />
Nov 28 18:31:56 pandemonium [<c01970b7>] ? do_vfs_ioctl+0x67/0x2f0<br />
Nov 28 18:31:56 pandemonium [<c01973a6>] ? sys_ioctl+0x66/0x70<br />
Nov 28 18:31:56 pandemonium [<c0103ef3>] ? sysenter_do_call+0x12/0x33<br />
Nov 28 18:31:56 pandemonium [<c01c64a6>] ? proc_get_sb+0xc6/0x160<br />
Nov 28 18:31:56 pandemonium =======================<br />
}}<br />
<br />
Adding the {{ic|nopat}} and/or {{ic|nomodeset}} [[kernel parameters]] should work.<br />
<br />
=== "aticonfig: No supported adapters detected" ===<br />
<br />
If you get the following:<br />
<br />
{{hc|# aticonfig --initial|<br />
aticonfig: No supported adapters detected<br />
}}<br />
<br />
It may still be possible to get Catalyst working by manually setting the device in your your {{ic|etc/X11/xorg.conf}} file or by copying an older working {{ic|/etc/ati/control}} file (preferred - this also fixes the watermark issue).<br />
<br />
To get an older control file, download a previous version of fglrx from AMD and run it with {{ic|--extract driver}} parameter. You'll find the control file in {{ic|driver/common/etc/ati/control}}. Copy the extracted file over the system file and restart Xorg. You can try different versions of the file.<br />
<br />
To set your model in {{ic|xorg.conf}}, edit the device section of {{ic|/etc/X11/xorg.conf}} to:<br />
<br />
{{hc|/etc/X11/xorg.conf|<br />
Section "Device"<br />
Identifier "ATI radeon '''****'''"<br />
Driver "fglrx"<br />
EndSection<br />
}}<br />
<br />
Where {{ic|****}} should be replaced with your device's marketing number (e.g. 6870 for the HD 6870 and 6310 for the E-350 APU).<br />
<br />
Xorg will start and it is possible to use {{ic|amdcccle}} instead of {{ic|aticonfig}}. There will be an "AMD Unsupported hardware" watermark.<br />
<br />
You can remove this watermark using the following script:<br />
<br />
#!/bin/sh<br />
DRIVER=/usr/lib/xorg/modules/drivers/fglrx_drv.so<br />
for x in $(objdump -d $DRIVER|awk '/call/&&/EnableLogo/{print "\\x"$2"\\x"$3"\\x"$4"\\x"$5"\\x"$6}'); do<br />
sed -i "s/$x/\x90\x90\x90\x90\x90/g" $DRIVER<br />
done<br />
<br />
and then reboot your machine.<br />
<br />
=== WebGL support in Chromium ===<br />
<br />
Google has blacklisted Linux's Catalyst driver from supporting webGL in their Chromium/Chrome browsers.<br />
<br />
You can turn webGL on by editing and adding {{ic|--ignore-gpu-blacklist}} flag into the {{ic|Exec}} line so it looks like this:<br />
<br />
{{hc|/usr/share/applications/chromium.desktop|2=<br />
Exec=chromium %U '''--ignore-gpu-blacklist'''<br />
}}<br />
<br />
You can also run chromium from console with the same {{ic|--ignore-gpu-blacklist}} flag:<br />
<br />
$ chromium '''--ignore-gpu-blacklist'''<br />
<br />
{{Warning|Catalyst does not support the {{ic|GL_ARB_robustness}} extension, so it is possible that a malicious site could use WebGL to perform a DoS attack on your graphic card.}}<br />
<br />
=== Lag/freezes when watching flash videos via Adobe's flashplugin ===<br />
<br />
Edit:<br />
<br />
{{hc|/etc/adobe/mms.cfg|2=<br />
#EnableLinuxHWVideoDecode=1<br />
OverrideGPUValidation=true<br />
}}<br />
<br />
If you are using KDE make sure that "Suspend desktop effects for fullscreen windows" is unchecked under {{ic|System Settings}} → {{ic|Desktop Effects}} → {{ic|Advanced}}.<br />
<br />
=== Lag/slow windows movement in GNOME3 ===<br />
<br />
You can try this solution, it is working for many people.<br />
<br />
Add this line into {{ic|~/.profile}} or into {{ic|/etc/profile}}:<br />
<br />
export CLUTTER_VBLANK=none<br />
<br />
Restart X server or reboot your system.<br />
<br />
=== Not using full screen resolution at 1920x1080 (underscanning, black borders around the screen) ===<br />
<br />
This usually happens when you use a HDMI connection to connect your monitor/TV to your computer.<br />
<br />
Seemed to be a feature by AMD/ATI to work with all HDTVs that could be adjusted via the amdccle.<br />
<br />
Using the amdcccle GUI you can select the affected display, go to adjustments, and set underscan to 0% (aticonfig defaults to 15% underscan). It is possible as well that the underscan slider won't show under the display's adjustments, as sometimes in (at least) version 14.10.<br />
<br />
The problem is that the settings will not persist after restarting X server or rebooting or wake up or might even revert after changing TTYs.<br />
<br />
For the changes to become permanent, you will need to adjust the underscan settings manually using "aticonfig" via console (as root) or manually edit the file {{ic|/etc/ati/amdpcsdb}} (as root)<br />
<br />
'''using aticonfig method:'''<br />
<br />
# aticonfig --set-pcs-u32=MCIL,DigitalHDTVDefaultUnderscan,0<br />
<br />
After changing the settings, reboot.<br />
<br />
For newer version (for example, 12.11), if Catalyst control center repeatedly fails to save the overscan setting you can also try:<br />
<br />
# aticonfig --set-pcs-u32=MCIL,TVEnableOverscan,0<br />
<br />
'''Manually editing /etc/ati/amdpcsdb method:'''<br />
<br />
Add the following line anywhere under the following header {{ic|[AMDPCSROOT/SYSTEM/MCIL]}}<br />
<br />
# DigitalHDTVDefaultUnderscan=V0<br />
<br />
For newer version (for example, 12.11), if Catalyst control center repeatedly fails to save the overscan setting you can also try:<br />
locate under {{ic|[AMDPCSROOT/SYSTEM/MCIL]}} the following line <br />
<br />
# TVEnableOverscan=V1<br />
<br />
and change it to<br />
<br />
# TVEnableOverscan=V0<br />
<br />
After changing the settings, reboot.<br />
<br />
{{note|You might find that the file {{ic|/etc/ati/amdpcsdb}} will be overwritten and revert no matter what you do as user or as root even with log in/log out/reboot, ergo the modification will not stick.<br />
For the amd database file not to be overwritten you have to modify it without the fgrlx driver running.<br />
This can be made by rebooting in any "safe mode" that will not use the driver or directly booting into console mode}}<br />
<br />
'''Workaround:'''<br />
For whatever reason you can find yourself not wanting to touch ATI's config files you can circumvent the problem by forcing the panel's position and resolution:<br />
as user:<br />
<br />
# aticonfig --set-dispattrib=DISPLAYTYPE,positionX:0<br />
# aticonfig --set-dispattrib=DISPLAYTYPE,positionY:0<br />
# aticonfig --set-dispattrib=DISPLAYTYPE,sizeX:1920<br />
# aticonfig --set-dispattrib=DISPLAYTYPE,sizeY:1080<br />
<br />
{{ic|DISPLAYTYPE}} will be the name of the monitor you want to change it's attributes, for example "dfp9".<br />
To get the name of your {{ic|DISPLAYTYPE}} run the following command:<br />
<br />
# xrandr --current<br />
<br />
Should RandR be not enabled use:<br />
<br />
# aticonfig --query-monitor<br />
<br />
Using the display switch or DISPLAY variable set to the appropriate display/screen (:0.1 for example) might be necessary.<br />
<br />
That will show you which displays are connected and disconnected and it's properties<br />
<br />
This workaround will not persist but it is a quick fix that will show that the panel works just fine and that the above solutions are to be put into place.<br />
<br />
{{note|{{ic|<nowiki>aticonfig --set-pcs-val=MCIL,DigitalHDTVDefaultUnderscan,0</nowiki>}} should not be used on newer versions of the driver as it is deprecated and will be soon removed as stated by ATI.}}<br />
<br />
Try {{ic|<nowiki>aticonfig --help | grep set-pcs-val</nowiki>}} to read ATI's notice<br />
<br />
=== Dual Screen Setup: general problems with acceleration, OpenGL, compositing, performance ===<br />
Try to disable xinerama and xrandr12. Check out ie. this way:<br />
<br />
Type those commands:<br />
# aticonfig --initial<br />
# aticonfig --set-pcs-str="DDX,EnableRandR12,FALSE"<br />
Then reboot your system. In {{ic|/etc/X11/xorg.conf}} check that xinerama is disabled, if it's not disable it and reboot your system.<br />
<br />
Next run {{ic|amdcccle}} and pick up amdcccle → display manager → multi-display → multidisplay desktop with display(s) 2.<br />
<br />
Reboot again and set up your display layout whatever you desire.<br />
<br />
=== Disabling VariBright feature ===<br />
Type the following command to disable VariBright:<br />
# aticonfig --set-pcs-u32=MCIL,PP_UserVariBrightEnable,0<br />
<br />
=== Hybrid/PowerXpress: turning off discrete GPU ===<br />
When you are using {{AUR|catalyst-total-pxp}} or catalyst-utils-pxp and you are switching to integrated GPU you may notice that discrete GPU is still working, consuming power and making your system's temperature higher. <br />
<br />
Sometimes ie. when your integrated GPU is intel's one you can use {{ic|vgaswitcheroo}} to turn the discrete GPU off.<br />
Sometimes unfortunatelly, it's not working.<br />
<br />
Then you may check out [https://aur.archlinux.org/packages/?O=0&K=acpi_call acpi_call]. MrDeepPurple has prepared the script which he's using to perform 'turn off' task, he's calling script via systemd service while booting and resuming his system.<br />
Here's his script:<br />
#!/bin/sh<br />
libglx=$(/usr/lib/fglrx/switchlibglx query)<br />
modprobe acpi_call<br />
if [ "$libglx" = "intel" ]; then<br />
echo '\_SB.PCI0.PEG0.PEGP._OFF' > /proc/acpi/call<br />
fi<br />
<br />
=== Switching from X session to TTYs gives a blank screen/low resolution TTY ===<br />
Workaround for this "feature", which appeared in catalyst 13.2 betas, is to use {{ic|1=vga=}} kernel option, like {{ic|1=vga=792}}.<br />
You can get the list of supported resolutions with the<br />
$ hwinfo --framebuffer<br />
command. Get the one that corresponds to your wanted resolution, and copy-paste it into kernel line of your bootloader, so it could look like ie. {{ic|1=vga=0x03d4}}<br />
<br />
=== Switching to TTYs then back to X session gives a black screen with a mouse cursor ===<br />
If you experience this bug, try adding<br />
Option "XAANoOffscreenPixmaps" "true"<br />
to the 'Device' section of your xorg.conf file.<br />
<br />
=== 30 FPS / Tear-Free / V-Sync bug ===<br />
Bug introduced in Catalyst 13.6 beta, not fixed till now (13.9).<br />
<br />
After enabling "Tear-Free" functionality every freshly started OpenGL application is lagging, often generates only 30 FPS, it also touches composited desktop.<br />
<br />
Workaround is pretty simple and was found by M132. Here are the steps, do everything in "AMD Catalyst Control Center" (amdcccle) application:<br />
<br />
1. Enable Tear-Free, it will set 3D V-Sync option to "Always on".<br />
2. Set 3D V-Sync to "Always Off".<br />
3. Make sure Tear-Free is still on.<br />
4. Restart X / Re-login.<br />
<br />
It is working well on KDE 4.11.x, but in case of problems M132 suggests: "Try disabling "Detect refresh rate" and specify monitor's refresh rate in the Composite plugin."<br />
<br />
=== Backlight adjustment does not work===<br />
If you have a problem with backlight adjustment, you can try the following command: <br />
# aticonfig --set-pcs-u32=MCIL,PP_PhmUseDummyBackEnd,1<br />
Some users reported that this can decrease FPS. To restore defaults, run:<br />
# aticonfig --set-pcs-u32=MCIL,PP_PhmUseDummyBackEnd,0<br />
[http://ati.cchtml.com/show_bug.cgi?id=711 Read more about this bug]<br />
<br />
== See also ==<br />
<br />
* [http://wiki.cchtml.com/index.php/Main_Page Unofficial Wiki for the ATI Linux Driver]<br />
* [http://ati.cchtml.com/query.cgi Unofficial ATI Linux Driver Bugzilla]</div>B6hgas5