https://wiki.archlinux.org/api.php?action=feedcontributions&user=Jstjohn&feedformat=atomArchWiki - User contributions [en]2024-03-19T02:02:42ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Mkosi&diff=650455Mkosi2021-02-01T22:51:21Z<p>Jstjohn: /* Example: Create and boot a Debian-Image */ remove Pkg template, as this is referencing a package for Debian, not for Arch</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Virtualization]]<br />
[[ja:Mkosi]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|systemd-nspawn}}<br />
{{Related|Linux Containers}}<br />
{{Related|Docker}}<br />
{{Related articles end}}<br />
<br />
'''[https://github.com/systemd/mkosi mkosi]''' stands for ''Make Operating System Image'', and is a tool for generating an OS tree or image that can be booted.<br />
<br />
== Installation ==<br />
Install {{Pkg|mkosi}} or {{Aur|mkosi-git}}. Depending on what Distribution you want to build install further packages:<br />
{| class="wikitable"<br />
! Distribution<br />
! Package<br />
|-<br />
| Arch<br />
| {{pkg|arch-install-scripts}}<br />
|-<br />
| Debian<br />
| {{pkg|debootstrap}}, {{pkg|debian-archive-keyring}}<br />
|-<br />
| Ubuntu<br />
| {{pkg|debootstrap}}, {{pkg|ubuntu-keyring}}<br />
|-<br />
| Fedora<br />
| {{aur|dnf}}<br />
|-<br />
| OpenSUSE<br />
| {{aur|zypper-git}}<br />
|-<br />
| CentOS<br />
| {{aur|dnf-legacy-utils}}<br />
|-<br />
|}<br />
<br />
== Basic usage ==<br />
You can create an image by calling mkosi as root<br />
# mkosi<br />
<br />
You can specify option as arguments or by editing files in the current folder.<br />
<br />
=== Example: Create and boot a Debian-Image ===<br />
The following command will create a bootable image with the latest Debian version and the package "openssh-clients" installed:<br />
$ mkosi -d debian -t gpt_ext4 -b --checksum --password password --package openssh-clients,vim -o image.raw<br />
<br />
you can boot it with [[systemd-nspawn]]:<br />
# systemd-nspawn -b -i image.raw<br />
<br />
or boot it virtualized with [[QEMU]] and <br />
$ qemu-system-x86_64 -m 512 -smp 2 -bios /usr/share/ovmf/x64/OVMF_CODE.fd -drive format=raw,file=image.raw<br />
<br />
You can also write this image to a USB drive and use it to boot your computer.<br />
<br />
=== 2. Example: Using Config-files ===<br />
The same image can be created by creating a configuration file:<br />
<br />
{{hc|mkosi.default|<nowiki><br />
[Distribution]<br />
Distribution=debian<br />
Release=stretch<br />
<br />
[Output]<br />
Format=gpt_ext4<br />
Bootable=yes<br />
Output=image.raw<br />
<br />
[Packages]<br />
Packages=<br />
openssh-client<br />
vim<br />
<br />
[Validation]<br />
Password=password<br />
<br />
</nowiki>}}<br />
<br />
{{tip|If you create a folder {{ic|mkosi.cache}} in current working directory, mkosi will save all downloaded packages there, so you can recreate images faster.}}<br />
<br />
=== Configurations ===<br />
Basic options can be specified as command-line arguments or in a file called {{ic|mkosi.default}} in your current directory.<br />
Most important options:<br />
{| class="wikitable" style="width:100%"<br />
! Argument<br />
! Option in mkosi.default<br />
! Description<br />
|-<br />
| -d<br />
| [Distribution]<br />
Distribution=<br />
| Which distribution should be installed: fedora,debian,ubuntu,arch,opensuse<br />
|-<br />
| -r<br />
| [Distribution]<br />
Release=<br />
| The version of the distribution: jessie, 21, …<br />
|-<br />
| -t<br />
| [Output]<br />
Format=<br />
| Format of the image to create:<br />
* '''gpt_ext4''': Image file with GPT partition table and [[ext4]] file system<br />
* '''gpt_btrfs''': Image file with GPT partition table and [[btrfs]] file system<br />
* '''gpt_squashfs''': Image file with GPT partition table and [[File_systems#Read-only_file_systems|squashfs]] file system<br />
* '''directory''': A plain directory<br />
* '''subvolume''': A btrfs subvolume<br />
* '''tar''': A tar-ball of a plain directory<br />
|-<br />
| -b<br />
| [Output]<br />
Bootable=yes<br />
| make the image bootable<br />
|-<br />
| --root-size<br />
| [Output]<br />
RootSize=<br />
| Size of the root file system<br />
|-<br />
| -p<br />
| [Packages]<br />
Packages=<br />
| List of packages to be installed into the image<br />
|-<br />
| -o<br />
| [Output]<br />
Output=<br />
| File/directory-Name<br />
|- <br />
| --password<br />
| [Validation]<br />
Password=test<br />
| Set the initial root password<br />
|}<br />
<br />
== See also ==<br />
* [https://github.com/systemd/mkosi Mkosi on Github]<br />
* [http://0pointer.net/blog/mkosi-a-tool-for-generating-os-images.html Longer introduction]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=ZFS&diff=649975ZFS2021-01-26T23:12:15Z<p>Jstjohn: /* Storage pools */ add templates in the first section</p>
<hr />
<div>[[Category:File systems]]<br />
[[Category:Oracle]]<br />
[[ja:ZFS]]<br />
[[pt: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|zettabyte]] 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 [https://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|<br />
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 />
<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 />
<br />
== Installation ==<br />
<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 [[Unofficial user repositories#archzfs|archzfs]] repository or alternatively the [[Arch User Repository]]:<br />
<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 development releases for LTS kernels.<br />
* {{AUR|zfs-linux-hardened}} for stable releases for hardened kernels.<br />
* {{AUR|zfs-linux-hardened-git}} for development releases for hardened kernels.<br />
* {{AUR|zfs-linux-zen}} for stable releases for zen kernels.<br />
* {{AUR|zfs-linux-zen-git}} for development releases for zen kernels.<br />
* {{AUR|zfs-dkms}} for versions with dynamic kernel module support.<br />
* {{AUR|zfs-dkms-git}} for development releases for versions with dynamic kernel module support.<br />
<br />
These branches have (according to them) dependency on the {{ic|zfs-utils}} package.<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 />
See [[Install_Arch_Linux_on_ZFS#Installation|Installation]].<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 />
Currently, by default, the kernel module is not loaded at boot (see more details in https://github.com/zfsonlinux/zfs/issues/6083). To automatically load {{Ic|zfs}} module on boot, see [[Kernel module#Automatic module loading with systemd]].<br />
<br />
For ZFS to live by its "zero administration" namesake, {{Ic|zfs-import-cache.service}} must be enabled to import the pools and {{Ic|zfs-mount.service}} must be enabled to mount the filesystems available in the pools. A benefit to this is that it is not necessary to mount ZFS filesystems in {{ic|/etc/fstab}}. {{Ic|zfs-import-cache.service}} imports the zfs pools reading the file {{ic|/etc/zfs/zpool.cache}}.<br />
<br />
For each [[#Importing a pool created by id|imported pool]] you want automatically imported by {{Ic|zfs-import-cache.service}} execute:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache <pool><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. See [https://github.com/archzfs/archzfs/issues/72 https://github.com/archzfs/archzfs/issues/72] for more information.}}<br />
<br />
Enable the relevant service and target so the pools are automatically imported at boot time:<br />
<br />
# systemctl enable zfs-import-cache<br />
# systemctl enable zfs-import.target<br />
<br />
To mount the ZFS filesystems, you have 2 choices:<br />
* Enable the [[#Using zfs-mount.service|zfs-mount.service]]<br />
* Using [[#Using zfs-mount-generator|zfs-mount-generator]]<br />
<br />
==== Using zfs-mount.service ====<br />
<br />
In order to mount ZFS filesystems automatically on boot you need to enable the following services and targets:<br />
<br />
# systemctl enable zfs-mount<br />
# systemctl enable zfs.target<br />
<br />
==== Using zfs-mount-generator ====<br />
<br />
You can also use the zfs-mount-generator to create systemd mount units for your ZFS filesystems at boot. systemd will automatically mount the filesystems based on the mount units without having to use the {{Ic|zfs-mount.service}}. To do that, you need to:<br />
<br />
# Create the {{Ic|/etc/zfs/zfs-list.cache}} directory.<br />
# Enable the ZFS Event Daemon(ZED) script (called a ZEDLET) required to create a list of mountable ZFS filesystems. (This link is created automatically if you are using OpenZFS >= 2.0.0.) {{bc|# ln -s /usr/lib/zfs/zed.d/history_event-zfs-list-cacher.sh /etc/zfs/zed.d}}<br />
# Enable and start the ZFS Event Daemon. This service is responsible for running the script in the previous step. {{bc|# systemctl enable zfs-zed.service<br># systemctl enable zfs.target<br># systemctl start zfs-zed.service}}<br />
# You need to create an empty file named after your pool in {{Ic|/etc/zfs/zfs-list.cache}}. The ZEDLET will only update the list of filesystems if the file for the pool already exists. {{bc|# touch /etc/zfs/zfs-list.cache/<pool-name>}}<br />
# Check the contents of {{Ic|/etc/zfs/zfs-list.cache/<pool-name>}}. If it is empty, make sure that the {{Ic|zfs-zed.service}} is running and just change the canmount property of any of your ZFS filesystem by running: {{bc|1=zfs set canmount=off zroot/fs1}} This change causes ZFS to raise an event which is captured by ZED, which in turn runs the ZEDLET to update the file in {{Ic|/etc/zfs/zfs-list.cache}}. If the file in {{Ic|/etc/zfs/zfs-list.cache}} is updated, you can set the {{Ic|canmount}} property of the filesystem back by running: {{bc|1=zfs set canmount=on zroot/fs1}}<br />
You need to add a file in {{Ic|/etc/zfs/zfs-list.cache}} for each ZFS pool in your system. Make sure the pools are imported by enabling {{Ic|zfs-import-cache.service}} and {{Ic|zfs-import.target}} as [[#Automatic Start|explained above]].<br />
<br />
== Storage pools ==<br />
<br />
It is not necessary to partition the drives before creating the ZFS filesystem. It is recommended to point ZFS at an entire disk (ie. {{ic|/dev/sdx}} rather than {{ic|/dev/sdx1}}), which will [https://www.reddit.com/r/zfs/comments/667na0/zfs_on_raw_or_gpt/dgh0l9t/ automatically create a GPT partition table] and add an 8 MB reserved partition at the end of the disk for legacy bootloaders. However, you can specify a partition or a file within an existing filesystem, if you wish to create multiple volumes with different redundancy properties.<br />
<br />
{{Note|If some or all device have been used in a software RAID set it is paramount to [[mdadm#Prepare the devices|erase any old RAID configuration information]].}}<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 />
=== Identify disks ===<br />
<br />
[https://github.com/zfsonlinux/zfs/wiki/faq#selecting-dev-names-when-creating-a-pool ZFS on Linux] recommends using device IDs when creating ZFS storage pools of less than 10 devices. Use [[Persistent block device naming#by-id and by-path]] to identify the list of drives to be used for ZFS pool. <br />
<br />
The disk IDs should look similar to the following:<br />
<br />
{{hc|$ ls -lh /dev/disk/by-id/|<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. {{ic|/dev/sda}},{{ic|/dev/sdb}},...) ZFS might not be able to detect zpools intermittently on boot.}}<br />
<br />
==== Using GPT labels ====<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 />
{{hc|$ 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 />
{{hc|$ 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 />
{{Tip|To minimize typing and copy/paste errors, set a local variable with the target PARTUUID: {{ic|<nowiki>$ UUID=$(lsblk --noheadings --output PARTUUID /dev/sd</nowiki>''XY''<nowiki>)</nowiki>}} }}<br />
<br />
=== Creating ZFS pools ===<br />
<br />
To create a ZFS pool:<br />
<br />
# zpool create -f -m <mount> <pool> [raidz(2|3)|mirror] <ids><br />
<br />
{{Tip|One may want to read [[#Advanced Format disks]] first as it may be recommend to set {{ic|ashift}} on pool creation.}}<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 is not 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 [[Persistent_block_device_naming#by-id_and_by-path|ID's]] of the drives or partitions that to include into the pool.<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 reliable, {{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 />
{{Tip|Use {{man|8|blockdev}} (part of {{Pkg|util-linux}}) to print the sector size reported by the device's ioctls: {{ic|blockdev --getpbsz /dev/sd''XY''}} as the root user.}}<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 />
==== 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.8.0, and must have unsupported features disabled. We can explicitly name features to enable with the {{ic|-d}} argument to {{ic|zpool create}}, which disables all features by default.<br />
<br />
You can create a pool with only the compatible features enabled:<br />
<br />
# zpool create -d -o feature@allocation_classes=enabled \<br />
-o feature@async_destroy=enabled \<br />
-o feature@bookmarks=enabled \<br />
-o feature@embedded_data=enabled \<br />
-o feature@empty_bpobj=enabled \<br />
-o feature@enabled_txg=enabled \<br />
-o feature@extensible_dataset=enabled \<br />
-o feature@filesystem_limits=enabled \<br />
-o feature@hole_birth=enabled \<br />
-o feature@large_blocks=enabled \<br />
-o feature@lz4_compress=enabled \<br />
-o feature@project_quota=enabled \<br />
-o feature@resilver_defer=enabled \<br />
-o feature@spacemap_histogram=enabled \<br />
-o feature@spacemap_v2=enabled \<br />
-o feature@userobj_accounting=enabled \<br />
-o feature@zpool_checkpoint=enabled \<br />
$POOL_NAME $VDEVS<br />
<br />
=== Verifying pool status ===<br />
<br />
If the command is successful, there will be no output. Using the [[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 -v|<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 />
=== 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 />
{{Warning|Do not run {{ic|zpool import ''pool''}}! 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.}}<br />
<br />
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 bigdata<br />
# zpool import -d /dev/disk/by-partlabel bigdata<br />
# zpool import -d /dev/disk/by-partuuid bigdata<br />
<br />
{{Note|Use the {{ic|-l}} flag when importing a pool that contains [[#Native encryption|encrypted datasets keys]]:<br />
# zpool import -l -d /dev/disk/by-id bigdata<br />
}}<br />
<br />
Finally check the state of the pool:<br />
<br />
# zpool status -v bigdata<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.<br />
<br />
{{Warning|This command destroys '''any data''' containing in the pool and/or dataset.}}<br />
<br />
To destroy the pool:<br />
# zpool destroy <pool><br />
<br />
To destroy a dataset:<br />
# zfs destroy <pool>/<dataset><br />
<br />
And now when checking the status:<br />
<br />
{{hc|# zpool status|<br />
no pools available<br />
}}<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 />
=== Extending an existing zpool ===<br />
<br />
A device (a partition or a disk) can be added to an existing zpool:<br />
<br />
# zpool add <pool> <device-id><br />
<br />
To import a pool which consists of multiple devices:<br />
<br />
# zpool import -d <device-id-1> -d <device-id-2> <pool><br />
<br />
or simply:<br />
<br />
# zpool import -d /dev/disk-by-id/ <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 />
== Creating datasets ==<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, see {{man|8|zfs|url=}} or {{man|8|zpool|url=}}.<br />
<br />
=== Native encryption ===<br />
<br />
ZFS offers the following 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-gcm}} will be used.<br />
<br />
The following keyformats are supported: {{ic|passphrase}}, {{ic|raw}}, {{ic|hex}}.<br />
<br />
One can also specify/increase the default iterations of PBKDF2 when using {{ic|passphrase}} with {{ic|-o pbkdf2iters <n>}}, although it may increase the decryption time.<br />
<br />
{{Note|<br />
* Native ZFS encryption has been made available in the stable 0.8.0 release or newer. Previously it was only available in development versions provided by packages like {{AUR|zfs-linux-git}}, {{AUR|zfs-dkms-git}} or other development builds. Users who were only using the development versions for the native encryption, may now switch to the stable releases if they wish.<br />
* The default encryption suite was changed from {{ic|aes-256-ccm}} to {{ic|aes-256-gcm}} in the 0.8.4 release.<br />
* To import a pool with keys, one needs to specify the {{ic|-l}} flag, without this flag encrypted datasets will be left unavailable until the keys are loaded. See [[#Importing a pool created by id]].}}<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/random 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 />
To verify the key location:<br />
# zfs get keylocation <nameofzpool>/<nameofdataset><br />
<br />
To change the key location:<br />
<br />
# zfs set keylocation=file:///path/to/key <nameofzpool>/<nameofdataset><br />
<br />
You can also manually load the keys by using one of the following commands:<br />
<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 />
To mount the created encrypted dataset:<br />
<br />
# zfs mount <nameofzpool>/<nameofdataset><br />
<br />
==== Unlock at boot time: systemd ====<br />
It is possible to automatically unlock a pool dataset on boot time by using a [[systemd]] unit. For example create the following service to unlock any specific dataset: <br />
<br />
{{hc|/etc/systemd/system/zfs-load-key@.service|2=<br />
[Unit]<br />
Description=Load %I encryption keys<br />
Before=systemd-user-sessions.service<br />
After=zfs-import.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/bash -c 'until (systemd-ask-password "Encrypted ZFS password for %I" --no-tty <nowiki>|</nowiki> zfs load-key %I); do echo "Try again!"; done'<br />
<br />
[Install]<br />
WantedBy=zfs-mount.service<br />
}}<br />
<br />
[[Enable]]/[[start]] the service for each encrypted dataset, e.g. {{ic|systemctl enable zfs-load-key@pool0-dataset0}} as the root user. Note the use of {{ic|-}}, which is an escaped {{ic|/}} in systemd unit definitions. See {{ic|systemd-escape(1)}} for more info.<br />
{{Note|The {{ic|1=Before=systemd-user-sessions.service}} ensures that systemd-ask-password is invoked before the local IO devices are handed over to the [[desktop environment]].}}<br />
<br />
An alternative is to load all possible keys:<br />
<br />
{{hc|/etc/systemd/system/zfs-load-key.service|2=<br />
[Unit]<br />
Description=Load encryption keys<br />
DefaultDependencies=no<br />
After=zfs-import.target<br />
Before=zfs-mount.service<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/zfs load-key -a<br />
<br />
[Install]<br />
WantedBy=zfs-mount.service<br />
}}<br />
<br />
[[Enable]]/[[start]] {{ic|zfs-load-key.service}}.<br />
<br />
==== Unlock at login time: PAM ====<br />
If you are not encrypting the root volume, but only the home volume or a user-specific volume, another idea is to [https://blog.trifork.com/2020/05/22/linux-homedir-encryption/ wait until login to decrypt it]. The advantages of this method are that the system boots uninterrupted, and that when the user logs in, the same password can be used both to authenticate and to decrypt the home volume, so that the password is only entered once.<br />
<br />
First set the mountpoint to legacy to avoid having it mounted by {{ic|zfs mount -a}}:<br />
{{bc|1=zfs set mountpoint=legacy zroot/data/home}}<br />
Ensure that it's in /etc/fstab so that {{ic|mount /home}} will work:<br />
{{hc|/etc/fstab|zroot/data/home /home zfs rw,xattr,posixacl,noauto 0 0}}<br />
<br />
On a single-user system, with only one /home volume having the same encryption password as the user's password, it can be decrypted at login as follows: first create /sbin/mount-zfs-homedir<br />
{{hc|/sbin/mount-zfs-homedir|2=<br />
#!/bin/bash<br />
<br />
# simplified from https://talldanestale.dk/2020/04/06/zfs-and-homedir-encryption/<br />
<br />
set -eu<br />
<br />
# Password is given to us via stdin, save it in a variable for later<br />
PASS=$(cat -)<br />
<br />
VOLNAME="zroot/data/home"<br />
<br />
# Unlock and mount the volume<br />
zfs load-key "$VOLNAME" <<< "$PASS" {{!}}{{!}} continue<br />
zfs mount "$VOLNAME" {{!}}{{!}} true # ignore errors<br />
}}<br />
<br />
don't forget {{ic|chmod a+x /sbin/mount-zfs-homedir}}; then get PAM to run it by adding the following line to /etc/pam.d/system-auth:<br />
<br />
{{hc|/etc/pam.d/system-auth|auth optional pam_exec.so expose_authtok /sbin/mount-zfs-homedir}}<br />
<br />
Now it will transparently decrypt and mount the /home volume when you log in anywhere: on the console, via ssh, etc. A caveat is that since your ~/.ssh directory isn't mounted, if you log in via ssh, you must use the default password authentication the first time rather than relying on {{ic|~/.ssh/authorized_keys}}.<br />
<br />
If you want to have separate volumes for each user, each encrypted with the user's password, try the [https://blog.trifork.com/2020/05/22/linux-homedir-encryption/ linked method].<br />
<br />
=== Swap volume ===<br />
<br />
{{Warning|On systems with extremely high memory pressure, using a zvol for swap can result in lockup, regardless of how much swap is still available. This issue is currently being investigated in https://github.com/zfsonlinux/zfs/issues/7734}}<br />
{{Warning|Swap on zvol does not support resume from hibernation, attempt to resume will [[User:M0p/Root_on_ZFS_Native_Encryption#Resume_from_ZFS_will_corrupt_the_pool|result in pool corruption]]. }}<br />
ZFS does not allow to use swapfiles, but users can use a ZFS volume (ZVOL) as swap. It is important 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) -o compression=zle \<br />
-o logbias=throughput -o sync=always\<br />
-o primarycache=metadata -o secondarycache=none \<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 />
=== Access Control Lists ===<br />
<br />
To use [[ACL]] on a dataset:<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 />
It may be preferable to enable ACL on the zpool as datasets will inherit the ACL parameters. Setting {{ic|1=aclinherit=passthrough}} may be wanted as the default mode is {{ic|restricted}} [https://docs.oracle.com/cd/E19120-01/open.solaris/817-2271/gbaaz/index.html]:<br />
<br />
# zfs set aclinherit=passthrough <nameofzpool><br />
# zfs set acltype=posixacl <nameofzpool><br />
# zfs set xattr=sa <nameofzpool><br />
<br />
=== Databases ===<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 Database]], 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 />
<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 />
<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 />
<br />
# zfs set logbias=throughput <pool>/postgres<br />
<br />
These can also be done at file system creation time, for example:<br />
<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 />
<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 />
<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 />
<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 />
<br />
# systemctl mask tmp.mount<br />
<br />
== Tuning ==<br />
<br />
=== General ===<br />
<br />
ZFS pools and datasets can be further adjusted using parameters.<br />
<br />
{{Note|All settable properties, with the exception of quotas and reservations, inherit their value from the parent dataset.}}<br />
<br />
To retrieve the current pool parameter status:<br />
<br />
# zfs get all <pool><br />
<br />
To retrieve the current dataset parameter status:<br />
<br />
# zfs get all <pool>/<dataset><br />
<br />
To disable access time (atime), which is enabled by default:<br />
<br />
# zfs set atime=off <pool><br />
<br />
To disable access time (atime) on a particular dataset:<br />
<br />
# zfs set atime=off <pool>/<dataset><br />
<br />
An alternative to turning off atime completely, {{ic|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 {{ic|1=atime=off}} and {{ic|1=atime=on}}. This property ''only'' takes effect if {{ic|atime}} is {{ic|on}}:<br />
<br />
# zfs set atime=on <pool><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-compressible data; consult the [http://open-zfs.org/wiki/Performance_tuning#Compression OpenZFS Wiki] for more details.<br />
<br />
To enable compression:<br />
<br />
# zfs set compression=on <pool><br />
<br />
To reset a property of a pool and/or dataset to it's default state, use {{ic|zfs inherit}}:<br />
<br />
# zfs inherit -rS atime <pool><br />
# zfs inherit -rS atime <pool>/<dataset><br />
<br />
{{Warning|Using the {{ic|-r}} flag will recursively reset all datasets of the zpool.}}<br />
<br />
=== Scrubbing ===<br />
<br />
Whenever data is read and ZFS encounters an error, it is silently repaired when possible, rewritten back to disk and logged so you can obtain an overview of errors on your pools. There is no fsck or equivalent tool for ZFS. Instead, ZFS supports a feature known as scrubbing. This traverses through all the data in a pool and verifies that all blocks can be read.<br />
<br />
To scrub a pool:<br />
<br />
# zpool scrub <pool><br />
<br />
To cancel a running scrub:<br />
<br />
# zpool scrub -s <pool><br />
<br />
==== How often should I do this? ====<br />
<br />
From the Oracle blog post [https://blogs.oracle.com/wonders-of-zfs-storage/disk-scrub-why-and-when-v2 Disk Scrub - Why and When?]:<br />
<br />
:This question is challenging for Support to answer, because as always the true answer is "It Depends". So before I offer a general guideline, here are a few tips to help you create an answer more tailored to your use pattern.<br />
<br />
:* What is the expiration of your oldest backup? You should probably scrub your data at least as often as your oldest tapes expire so that you have a known-good restore point.<br />
:* How often are you experiencing disk failures? While the recruitment of a hot-spare disk invokes a "resilver" -- a targeted scrub of just the VDEV which lost a disk -- you should probably scrub at least as often as you experience disk failures on average in your specific environment.<br />
:* How often is the oldest piece of data on your disk read? You should scrub occasionally to prevent very old, very stale data from experiencing bit-rot and dying without you knowing it.<br />
<br />
:If any of your answers to the above are "I do not know", the general guideline is: you should probably be scrubbing your zpool at least once per month. It is a schedule that works well for most use cases, provides enough time for scrubs to complete before starting up again on all but the busiest & most heavily-loaded systems, and even on very large zpools (192+ disks) should complete fairly often between disk failures.<br />
<br />
In the [https://pthree.org/2012/12/11/zfs-administration-part-vi-scrub-and-resilver/ ZFS Administration Guide] by Aaron Toponce, he advises to scrub consumer disks once a week.<br />
<br />
==== Start with a service or timer ====<br />
Using a [[systemd]] timer/service it is possible to automatically scrub pools.<br />
<br />
To perform scrubbing monthly on a particular pool:<br />
<br />
{{hc|/etc/systemd/system/zfs-scrub@.timer|2=<br />
[Unit]<br />
Description=Monthly zpool scrub on %i<br />
<br />
[Timer]<br />
OnCalendar=monthly<br />
AccuracySec=1h<br />
Persistent=true<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/zfs-scrub@.service|2=<br />
[Unit]<br />
Description=zpool scrub on %i<br />
<br />
[Service]<br />
Nice=19<br />
IOSchedulingClass=idle<br />
KillSignal=SIGINT<br />
ExecStart=/usr/bin/zpool scrub %i<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
[[Enable]]/[[start]] {{ic|zfs-scrub@''pool-to-scrub''.timer}} unit for monthly scrubbing the specified zpool.<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 />
<br />
# zpool add <pool> log mirror <device-id-1> <device-id-2><br />
<br />
Or to add a single device SLOG (unsafe):<br />
<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 />
<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 />
=== 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 8 KiB 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 8 KiB tends to be a good value for most file systems, even when using 4 KiB 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 />
=== I/O Scheduler ===<br />
<br />
While ZFS is expected to work well with modern schedulers including {{ic|deadline}}, {{ic|mq-deadline}}, {{ic|noop}}, and {{ic|none}}, experimenting with [[Improving_performance#Changing_I/O_scheduler|manually setting]] the I/O scheduler on ZFS disks may yield performance gains.<br />
<br />
== Troubleshooting ==<br />
<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 />
One 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 512MiB)<br />
<br />
In case that the default value of {{ic|zfs_arc_min}} (1/32 of system memory) is higher than the specified {{ic|zfs_arc_max}} it is needed to add also the following to the [[Kernel parameters]] list:<br />
<br />
zfs.zfs_arc_min=268435456 # (for 256MiB, needs to be lower than zfs.zfs_arc_max)<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]{{Dead link|2020|04|03|status=404}}.<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 />
<br />
{{hc|$ hostid|<br />
0a0af0f8<br />
}}<br />
<br />
This number have to be added to the [[kernel parameters]] as {{ic|1=spl.spl_hostid=0x0a0af0f8}}. Another solution is writing the hostid inside the initram image, see the [[Installing Arch Linux on ZFS#After the first boot|installation guide]]{{Broken section link}} explanation about this.<br />
<br />
Users can always ignore the check adding {{ic|1=zfs_force=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 />
<br />
=== Pool resilvering stuck/restarting/slow? ===<br />
<br />
According to the ZFSonLinux github it is 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 your zpool.cache for pools you do not 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 the pool named zroot. Sometimes there is no need to refresh your zpool.cache, but instead all you need to do is [[regenerate the initramfs]].<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 />
SigLevel = Optional TrustAll<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 />
=== 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 {{ic|--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|scrubbing]]. It is possible to override this by [[Systemd#Editing provided units|editing provided systemd unit]] and removing {{ic|--skip-scrub}} from {{ic|ExecStart}} line. Consequences not known, someone please edit.}}<br />
<br />
Once the package has been installed, [[systemd/Timers|enable and start the selected timers]] ({{ic|<nowiki>zfs-auto-snapshot-{frequent,daily,weekly,monthly}.timer</nowiki>}}).<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 />
==== zrepl ====<br />
<br />
The {{AUR|zrepl}} package from the [[AUR]] provides a ZFS automatic replication service, which could also be used as a snapshotting service much like [[snapper]].<br />
<br />
For details on how to configure the zrepl daemon, see the zrepl [https://zrepl.github.io/ documentation]. The configuration file should be located at {{ic|/etc/zrepl/zrepl.yml}}. Then, run {{ic|zrepl configcheck}} to make sure that the syntax of the config file is correct. Finally, enable {{ic|zrepl.service}}.<br />
<br />
==== bieaz ====<br />
<br />
{{AUR|bieaz}} is a boot environment manager. It supports GRUB integration, separate boot pool on {{ic|/boot}} and arbitrary system container names {{ic|rpool_uniq/a/b/c/sysdataset}}. {{ic|bieaz}} requires a properly configured system dataset layout, see [https://gitlab.com/m_zhou/bieaz/-/blob/master/README.md documentation]. A compatible [[User:M0p/Root_on_ZFS_Native_Encryption|Arch on ZFS installation guide]] is available.<br />
<br />
{{aur|rozb3-pac}} is a pacman hook using {{aur|bieaz}}.<br />
<br />
=== Creating a share ===<br />
<br />
ZFS has support for creating shares by [[NFS]] or [[SMB]].<br />
<br />
==== NFS ====<br />
<br />
Make sure [[NFS]] has been installed/configured, note there is no need to edit the {{ic|/etc/exports}} file. For sharing over NFS the services {{ic|nfs-server.service}} and {{ic|zfs-share.service}} should be [[start|started]].<br />
<br />
To make a pool available on the network:<br />
<br />
# zfs set sharenfs=on ''nameofzpool''<br />
<br />
To make a dataset available on the network:<br />
<br />
# zfs set sharenfs=on ''nameofzpool''/''nameofdataset''<br />
<br />
To enable read/write access for a specific ip-range(s):<br />
<br />
# zfs set sharenfs="rw=@192.168.1.100/24,rw=@10.0.0.0/24" ''nameofzpool''/''nameofdataset''<br />
<br />
To check if the dataset is exported successful:<br />
<br />
{{hc|# showmount -e `hostname`|<br />
Export list for hostname:<br />
/path/of/dataset 192.168.1.100/24<br />
}}<br />
<br />
To view the current loaded exports state in more detail, use:<br />
<br />
{{hc|# exportfs -v|2=<br />
''/path/of/dataset''<br />
192.168.1.100/24(sync,wdelay,hide,no_subtree_check,mountpoint,sec=sys,rw,secure,no_root_squash,no_all_squash)<br />
}}<br />
<br />
To view the current NFS share list by ZFS:<br />
<br />
# zfs get sharenfs<br />
<br />
==== SMB ====<br />
<br />
When sharing through SMB, using {{ic|usershares}} in {{ic|/etc/samba/smb.conf}} will allow ZFS to setup and create the shares.<br />
<br />
{{bc|1=<br />
# [global]<br />
# usershare path = /var/lib/samba/usershares<br />
# usershare max shares = 100<br />
# usershare allow guests = yes<br />
# usershare owner only = no<br />
}}<br />
<br />
Create and set permissions on the user directory as root<br />
<br />
# mkdir /var/lib/samba/usershares<br />
# chmod +t /var/lib/samba/usershares<br />
<br />
To make a pool available on the network:<br />
<br />
# zfs set sharesmb=on ''nameofzpool''<br />
<br />
To make a dataset available on the network:<br />
<br />
# zfs set sharesmb=on ''nameofzpool''/''nameofdataset''<br />
<br />
To check if the dataset is exported successfully:<br />
<br />
{{hc|# smbclient -L localhost -U%|<br />
Sharename Type Comment<br />
--------- ---- -------<br />
IPC$ IPC IPC Service (SMB Server Name)<br />
''nameofzpool''_''nameofdataset'' Disk Comment: path/of/dataset<br />
SMB1 disabled -- no workgroup available<br />
}}<br />
<br />
To view the current SMB share list by ZFS:<br />
<br />
# zfs get sharesmb<br />
<br />
=== Encryption in ZFS using dm-crypt ===<br />
<br />
The stable release version of ZFS on Linux used to not support encryption directly (now it's available, see [[#Native encryption]]), but zpools can be created on 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 initramfs]]. There should be no errors.<br />
<br />
=== Bind mount ===<br />
<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 />
<br />
See [https://www.freedesktop.org/software/systemd/man/systemd.mount.html systemd.mount] for more information on how systemd converts fstab into mount unit files with [https://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 />
<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]], 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 are 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|2=<br />
export MAILRC=/home/<user>/.mailrc<br />
}}<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 as root: {{ic|1=zpool scrub <pool-name>}}.<br />
<br />
=== Wrap shell commands in pre & post snapshots ===<br />
<br />
Since it is 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 />
==== rozb3-pac ====<br />
{{aur|rozb3-pac}} is a pacman hook supporting ZFS boot environments. It depends on {{aur|bieaz}}, a ZFS boot environment manager ported from [https://github.com/vermaden/beadm FreeBSD beadm].<br />
<br />
{{aur|rozb3-pac}} is based on {{pkg|snap-pac}}.<br />
<br />
==== znp ====<br />
E.g.:<br />
<br />
# zfs snapshot -r zroot@pre<br />
# pacman -Syu<br />
# zfs snapshot -r zroot@post<br />
# zfs diff zroot@pre zroot@post <br />
# zfs rollback zroot@pre<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 -Syu<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 />
=== Remote unlocking of ZFS encrypted root ===<br />
<br />
As of [https://github.com/archzfs/archzfs/pull/261 PR #261], {{ic|archzfs}} supports SSH unlocking of natively-encrypted ZFS datasets. This section describes how to use this feature, and is largely based on [[dm-crypt/Specialties#Remote unlocking (hooks: netconf, dropbear, tinyssh, ppp)]].<br />
<br />
#Install {{Pkg|mkinitcpio-netconf}} to provide hooks for setting up early user space networking.<br />
#Choose an SSH server to use in early user space. The options are {{Pkg|mkinitcpio-tinyssh}} or {{Pkg|mkinitcpio-dropbear}}, and are mutually exclusive.<br />
##If using {{Pkg|mkinitcpio-tinyssh}}, it is also recommended to install {{Pkg|tinyssh-convert}} or {{AUR|tinyssh-convert-git}}. This tool converts an existing OpenSSH hostkey to the TinySSH key format, preserving the key fingerprint and avoiding connection warnings. The TinySSH and Dropbear mkinitcpio install scripts will automatically convert existing hostkeys when generating a new initcpio image.<br />
#Decide whether to use an existing OpenSSH key or generate a new one (recommended) for the host that will be connecting to and unlocking the encrypted ZFS machine. Copy the public key into {{ic|/etc/tinyssh/root_key}} or {{ic|/etc/dropbear/root_key}}. When generating the initcpio image, this file will be added to {{ic|authorized_keys}} for the root user and is only valid in the initrd environment.<br />
#Add the {{ic|1=ip=}} [[kernel parameter]] to your boot loader configuration. The {{ic|ip}} string is [https://www.kernel.org/doc/html/latest/admin-guide/nfs/nfsroot.html highly configurable]. A simple DHCP example is shown below.{{bc|1=ip=:::::eth0:dhcp}}<br />
#Edit {{ic|/etc/mkinitcpio.conf}} to include the {{ic|netconf}}, {{ic|dropbear}} or {{ic|tinyssh}}, and {{ic|zfsencryptssh}} hooks before the {{ic|zfs}} hook:{{bc|1=HOOKS=(... netconf <tinyssh>{{!}}<dropbear> zfsencryptssh zfs ...)}}<br />
#[[Regenerate the initramfs]].<br />
#Reboot and try it out!<br />
<br />
====Changing the SSH server port====<br />
<br />
By default, {{Pkg|mkinitcpio-tinyssh}} and {{Pkg|mkinitcpio-dropbear}} listen on port {{ic|22}}. You may wish to change this.<br />
<br />
For '''TinySSH''', copy {{ic|/usr/lib/initcpio/hooks/tinyssh}} to {{ic|/etc/initcpio/hooks/tinyssh}}, and find/modify the following line in the {{ic|run_hook()}} function:<br />
<br />
{{hc|/etc/initcpio/hooks/tinyssh|<br />
/usr/bin/tcpserver -HRDl0 0.0.0.0 <new_port> /usr/sbin/tinysshd -v /etc/tinyssh/sshkeydir &<br />
}}<br />
<br />
For '''Dropbear''', copy {{ic|/usr/lib/initcpio/hooks/dropbear}} to {{ic|/etc/initcpio/hooks/dropbear}}, and find/modify the following line in the {{ic|run_hook()}} function:<br />
<br />
{{hc|/etc/initcpio/hooks/tinyssh|<br />
/usr/sbin/dropbear -E -s -j -k -p <new_port><br />
}}<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
==== Unlocking from a Windows machine using PuTTY/Plink ====<br />
<br />
First, we need to use {{ic|puttygen.exe}} to import and convert the OpenSSH key generated earlier into PuTTY's ''.ppk'' private key format. Let us call it {{ic|zfs_unlock.ppk}} for this example.<br />
<br />
The mkinitcpio-netconf process above does not setup a shell (nor do we need need one). However, because there is no shell, PuTTY will immediately close after a successful connection. This can be disabled in the PuTTY SSH configuration (''Connection -> SSH -> [X] Do not start a shell or command at all''), but it still does not allow us to see stdout or enter the encryption passphrase. Instead, we use {{ic|plink.exe}} with the following parameters:<br />
<br />
plink.exe -ssh -l root -i c:\path\to\zfs_unlock.ppk <hostname><br />
<br />
The plink command can be put into a batch script for ease of use.<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 />
* [https://web.archive.org/web/20161028084224/http://www.solarisinternals.com/wiki/index.php/ZFS_Best_Practices_Guide ZFS Best Practices Guide]<br />
* [https://docs.oracle.com/cd/E23823_01/html/819-5461/gavwg.html ZFS Troubleshooting Guide]<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]<br />
* [https://github.com/danboid/creating-ZFS-disks-under-Linux How to create cross platform ZFS disks under Linux]<br />
* [https://blog.heckel.xyz/2017/01/08/zfs-encryption-openzfs-zfs-on-linux/ How-To: Using ZFS Encryption at Rest in OpenZFS (ZFS on Linux, ZFS on FreeBSD, …)]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Install_Arch_Linux_on_ZFS&diff=649974Install Arch Linux on ZFS2021-01-26T23:09:06Z<p>Jstjohn: /* Loading password from USB-Stick */ fix grammar and add some missing templates</p>
<hr />
<div>[[Category:Installation process]]<br />
[[ja:ZFS に Arch Linux をインストール]]<br />
{{Related articles start}}<br />
{{Related|ZFS}}<br />
{{Related|Experimenting with ZFS}}<br />
{{Related articles end}}<br />
This article details the steps required to install Arch Linux onto a ZFS root filesystem.<br />
<br />
{{Warning| Blindly copying and pasting this wiki will not work. It is necessary to take the time to understand the boot process, and what is done when creating the pool and datasets. Here are some useful links:<br />
* [https://www.freebsd.org/doc/handbook/zfs.html FreeBSD ZFS Handbook]<br />
* [https://github.com/zfsonlinux/zfs/wiki ZFSOnLinux wiki]<br />
* [http://open-zfs.org/wiki/System_Administration OpenZFS wiki]<br />
* [https://pthree.org/2012/04/17/install-zfs-on-debian-gnulinux/ Aaron Toponce Install ZFS on Debian GNU/Linux]{{Dead link|2020|12|27|status=SSL error}}<br />
}}<br />
<br />
== Installation ==<br />
<br />
To install Archlinux on ZFS, you need to boot archiso system with ZFS module.<br />
<br />
=== Get ZFS module on archiso system ===<br />
<br />
A script to easily install and load the ZFS module on running archiso system. It should work on any archiso version.<br />
<br />
See [https://github.com/eoli3n/archiso-zfs eoli3n/archiso-zfs]<br />
<br />
=== Embedding ZFS module into custom archiso ===<br />
<br />
To build custom archiso, see [[ZFS#Embed_the_archzfs_packages_into_an_archiso|ZFS]] article.<br />
<br />
== Partition the destination drive ==<br />
{{Accuracy|GRUB lacks support for many OpenZFS features. To work around this, separate pool for / and /boot must be created; separate swap partition preferred over swap on zvol|section=Update partition scheme for separate boot pool, root pool and swap partition}}<br />
Review [[Partitioning]] for information on determining the partition table type to use for ZFS. ZFS supports GPT and MBR partition tables.<br />
<br />
ZFS manages its own partitions, so only a basic partition table scheme is required. The partition that will contain the ZFS filesystem should be of the type {{ic|bf00}}, or "Solaris Root".<br />
<br />
Drives larger than 2TB require a GPT partition table. GRUB on BIOS/GPT configurations require a small (1~2MiB) BIOS boot partition to embed its image of boot code.<br />
<br />
Depending upon your machine's firmware or your choice of boot mode, booting may or may not require an EFI partition. On a BIOS machine (or a UEFI machine booting in legacy mode) EFI partition is not required. Consult [[Arch boot process#Boot loader]] for more information.<br />
<br />
=== Partition scheme ===<br />
<br />
Here is an example of a basic partition scheme that could be employed for your ZFS root install on a BIOS/MBR installation using GRUB:<br />
<br />
{{bc|<nowiki><br />
Part Size Type<br />
---- ---- -------------------------<br />
1 XXXG Solaris Root (bf00)</nowiki><br />
}}<br />
<br />
Using GRUB on a BIOS (or UEFI machine in legacy boot mode) machine but using a GPT partition table:<br />
<br />
{{bc|<nowiki><br />
Part Size Type<br />
---- ---- -------------------------<br />
1 2M BIOS boot partition (ef02)<br />
2 XXXG Solaris Root (bf00)</nowiki><br />
}}<br />
<br />
Another example, this time using a UEFI-specific bootloader (such as [[rEFInd]]) with an GPT partition table:<br />
<br />
{{bc|<nowiki><br />
Part Size Type<br />
---- ---- -------------------------<br />
1 100M EFI boot partition (ef00)<br />
2 XXXG Solaris Root (bf00)</nowiki><br />
}}<br />
<br />
ZFS does not support swap files. If you require a swap partition, see [[ZFS#Swap volume]] for creating a swap ZVOL.<br />
<br />
{{Tip|Bootloaders with support for ZFS are described in [[#Install and configure the bootloader]].}}<br />
{{Warning|Several GRUB bugs ([https://savannah.gnu.org/bugs/?42861 bug #42861], [https://github.com/zfsonlinux/grub/issues/5 zfsonlinux/grub/issues/5]) complicate installing it on ZFS partitions, see [[#Install and configure the bootloader]] for a workaround}}<br />
<br />
=== Example parted commands ===<br />
Here are some example commands to partition a drive for the second scenario above ie using BIOS/legacy boot mode with a GPT partition table and a (slighty more than) 1MB BIOS boot partition for GRUB:<br />
<br />
# parted /dev/sdx<br />
(parted)mklabel gpt<br />
(parted)mkpart non-fs 0% 2<br />
(parted)mkpart primary 2 100%<br />
(parted)set 1 bios_grub on<br />
(parted)set 2 boot on<br />
(parted)quit<br />
<br />
You can achieve the above in a single command like so:<br />
<br />
parted --script /dev/sdx mklabel gpt mkpart non-fs 0% 2 mkpart primary 2 100% set 1 bios_grub on set 2 boot on<br />
<br />
If you are creating an EFI partition then that should have the boot flag set instead of the root partition.<br />
<br />
== Format the destination disk ==<br />
<br />
If you have opted for a boot partition as well as any other non-ZFS system partitions then format them. Do not do anything to the Solaris partition nor to the BIOS boot partition. ZFS will manage the first, and your bootloader the second.<br />
<br />
== Setup the ZFS filesystem ==<br />
<br />
First, make sure the ZFS modules are loaded,<br />
<br />
# modprobe zfs<br />
<br />
=== Create the root zpool ===<br />
<br />
Create your pool and set all default dataset options. All dataset created on the zpool will inherit of each {{ic|-O}} set at the zpool creation.<br />
Default options are detailed in [https://openzfs.github.io/openzfs-docs/Getting%20Started/Debian/Debian%20Buster%20Root%20on%20ZFS.html#step-2-disk-formatting Debian Buster Root on ZFS. Step 2: Disk Formatting].<br />
<br />
{{Note|use {{ic|1=-o ashift=9}} for disks with a 512 byte physical sector size or {{ic|1=-o ashift=12}} for disks with a 4096 byte physical sector size. See {{ic|lsblk -S -o NAME,PHY-SEC}} to get the physical sector size of each SCSI/SATA disk. Remove -S if you want the same value from all devices.}}<br />
<br />
{{Note|Setting {{ic|1=normalization=formD}} eliminates some corner cases relating to UTF-8 filename normalization. It also implies {{ic|1=utf8only=on}}, which means that only UTF-8 filenames are allowed. If you care to support non-UTF-8 filenames, do not use this option. For a discussion of why requiring UTF-8 filenames may be a bad idea, see [http://utcc.utoronto.ca/~cks/space/blog/linux/ForcedUTF8Filenames The problems with enforced UTF-8 only filenames].}}<br />
<br />
# zpool create -f -o ashift=12 \<br />
-O acltype=posixacl \<br />
-O relatime=on \<br />
-O xattr=sa \<br />
-O dnodesize=legacy \<br />
-O normalization=formD \<br />
-O mountpoint=none \<br />
-O canmount=off \<br />
-O devices=off \<br />
-R /mnt \<br />
zroot /dev/disk/by-id/''id-to-partition-partx''<br />
<br />
==== Compression and native encryption ====<br />
{{Accuracy|GRUB will not boot a pool with native encryption, separate unencrypted boot pool mounted at /boot must be created|section=Update partition scheme for separate boot pool, root pool and swap partition}}<br />
This will enable compression and native encryption by default on all datasets:<br />
<br />
# zpool create -f -o ashift=12 \<br />
-O acltype=posixacl \<br />
-O relatime=on \<br />
-O xattr=sa \<br />
-O dnodesize=legacy \<br />
-O normalization=formD \<br />
-O mountpoint=none \<br />
-O canmount=off \<br />
-O devices=off \<br />
-R /mnt \<br />
-O compression=lz4 \<br />
-O encryption=aes-256-gcm \<br />
-O keyformat=passphrase \<br />
-O keylocation=prompt \<br />
zroot /dev/disk/by-id/''id-to-partition-partx''<br />
<br />
{{Warning|<br />
* Always use id names when working with ZFS, otherwise import errors will occur.<br />
* The zpool command will normally activate all features. See [[ZFS#GRUB-compatible pool creation]] when using [[GRUB]].}}<br />
<br />
=== Create your datasets ===<br />
<br />
Instead of using conventional disk partitions, ZFS has the concept of datasets to manage your storage. Unlike disk partitions, datasets have no fixed size and allow for different attributes, such as compression, to be applied per dataset. Normal ZFS datasets are mounted automatically by ZFS whilst legacy datasets are required to be mounted using fstab or with the traditional mount command.<br />
<br />
One of the most useful features of ZFS is boot environments. Boot environments allow you to create a bootable snapshot of your system that you can revert to at any time instantly by simply rebooting and booting from that boot environment. This can make doing system updates much safer and is also incredibly useful for developing and testing software. In order to be able to use a boot environment manager such as [https://github.com/b333z/beadm beadm], {{AUR|bieaz}}(port based on beadm, supports pacman hook with {{aur|rozb3-pac}}), {{AUR|zectl}} (systemd-boot), or {{AUR|zedenv}} (GRUB) to manage boot environments, your datasets must be configured properly. Key to this are that you split your data directories (such as {{ic|/home}}) into datasets that are distinct from your system datasets and that you do not place data in the root of the pool as this cannot be moved afterwards. <br />
<br />
You should always create a dataset for at least your root filesystem and in nearly all cases you will also want {{ic|/home}} to be in a separate dataset. You may decide you want your logs to persist over boot environments. If you are a running any software that stores data outside of {{ic|/home}} (such as is the case for database servers) you should structure your datasets so that the data directories of the software you want to run are separated out from the root dataset.<br />
<br />
With these example commands, we will create a basic boot environment compatible configuration comprising of just root and {{ic|/home}} datasets. It inherits default options from [[#Create the root zpool|zpool creation.]]<br />
<br />
# zfs create -o mountpoint=none zroot/data<br />
# zfs create -o mountpoint=none zroot/ROOT<br />
# zfs create -o mountpoint=/ -o canmount=noauto zroot/ROOT/default<br />
# zfs create -o mountpoint=/home zroot/data/home<br />
<br />
You can also create your ROOT dataset without having to specify mountpoint to / since GRUB will mount it to / anyway. <br />
That gives you possibility to boot into some old versions of root just by cloning it and putting as menuentry of GRUB. <br />
In such, you can create ROOT with the following command:<br />
# zfs create -o mountpoint=/roots/default zroot/ROOT/default<br />
<br />
You can store {{ic|/root}} in your {{ic|zroot/data/home}} dataset.<br />
<br />
# zfs create -o mountpoint=/root zroot/data/home/root<br />
<br />
You will need to enable some options for datasets which hold specific directories:<br />
<br />
{| class="wikitable" style="text-align: left;"<br />
|+ Options required by specific directories<br />
! scope="col" | Directory<br />
! scope="col" | Dataset Option<br />
! scope="col" | Details<br />
|-<br />
! {{ic|/}}<br />
| {{ic|1=canmount=noauto}} <br />
|<br />
|-<br />
|-<br />
! {{ic|/var/log/journal}}<br />
| {{ic|1=acltype=posixacl}}<br />
| [[Systemd#systemd-tmpfiles-setup.service fails to start at boot]]<br />
|-<br />
|}<br />
<br />
==== System datasets ====<br />
<br />
To create datasets for system directories, use {{ic|1=canmount=off}}.<br />
<br />
For some examples, please read [https://openzfs.github.io/openzfs-docs/Getting%20Started/Debian/Debian%20Buster%20Root%20on%20ZFS.html#step-3-system-installation Debian-Buster-Root-on-ZFS#step-3-system-installation]<br />
<br />
# zfs create -o mountpoint=/var -o canmount=off zroot/var<br />
# zfs create zroot/var/log<br />
# zfs create -o mountpoint=/var/lib -o canmount=off zroot/var/lib<br />
# zfs create zroot/var/lib/libvirt<br />
# zfs create zroot/var/lib/docker<br />
<br />
=== Export/Import your datasets ===<br />
<br />
To validate your configurations, export then reimport all your zpools.<br />
<br />
{{Warning|Do not skip this, otherwise you will be required to use {{ic|-f}} when importing your pools. This unloads the imported pool.}}<br />
{{Note|This might fail if you added a swap partition. You need to turn it off with the ''swapoff'' command.}}<br />
<br />
# zpool export zroot<br />
# zpool import -d /dev/disk/by-id -R /mnt zroot -N<br />
<br />
{{Note|{{ic|-d}} is not the actual device id, but the {{ic|/dev/by-id}} directory containing the symbolic links.<br />
If this command fails and you are asked to import your pool via its numeric ID, run {{ic|zpool import}} to <br />
find out the ID of your pool then use a command such as:<br />
{{ic|zpool import 9876543212345678910 -R /mnt zroot}}<br />
}}<br />
<br />
If you used native encryption, load zfs key.<br />
<br />
# zfs load-key zroot<br />
<br />
Manually mount your rootfs dataset because it uses {{ic|1=canmount=noauto}}, then mount all others datasets.<br />
<br />
# zfs mount zroot/ROOT/default<br />
# zfs mount -a<br />
<br />
The ZFS filesystem is now ready to use.<br />
<br />
=== Configure the root filesystem ===<br />
<br />
If you used legacy datasets, it must be listed in {{ic|/etc/fstab}}.<br />
<br />
Set the bootfs property on the descendant root filesystem so the boot loader knows where to find the operating system.<br />
<br />
# zpool set bootfs=zroot/ROOT/default zroot<br />
<br />
Be sure to bring the {{ic|zpool.cache}} file into your new system. This is required later for the ZFS daemon to start.<br />
<br />
# cp /etc/zfs/zpool.cache /mnt/etc/zfs/zpool.cache<br />
<br />
if you do not have {{ic|/etc/zfs/zpool.cache}}, create it:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache zroot<br />
<br />
== Install and configure Arch Linux ==<br />
<br />
Follow the following steps using the [[Installation guide]]. It will be noted where special consideration must be taken for ZFSonLinux.<br />
<br />
* First mount any legacy or non-ZFS boot or system partitions using the mount command.<br />
<br />
* Install the base system.<br />
<br />
* The procedure described in [[Installation guide#Fstab]] is usually overkill for ZFS. ZFS usually auto mounts its own partitions, so we do not need ZFS partitions in {{ic|fstab}} file, unless the user made legacy datasets of system directories. To generate the {{ic|fstab}} for filesystems, use:<br />
<br />
# genfstab -U -p /mnt >> /mnt/etc/fstab<br />
<br />
* Edit the {{ic|/etc/fstab}}:<br />
<br />
{{Note|<br />
* If you chose to create legacy datasets for system directories, keep them in this {{ic|fstab}}!<br />
* Comment out all non-legacy datasets apart from the swap file and the boot/EFI partition. It is a convention to replace the swap's uuid with {{ic|/dev/zvol/zroot/swap}}.<br />
}}<br />
<br />
* You need to add the [[Unofficial_user_repositories#archzfs|Arch ZFS]] repository to {{ic|/etc/pacman.conf}}, sign its key and [[install]] '''zfs-linux''' (or '''zfs-linux-lts''' if you are running the LTS kernel) within the arch-chroot before you can update the ramdisk with ZFS support.<br />
<br />
* When creating the initial ramdisk, first edit {{ic|/etc/mkinitcpio.conf}} and add {{ic|zfs}} before filesystems. Also, move {{ic|keyboard}} hook before {{ic|zfs}} so you can type in console if something goes wrong. You may also remove fsck (if you are not using Ext3 or Ext4). Your {{ic|HOOKS}} line should look something like this:<br />
HOOKS="base udev autodetect modconf block keyboard zfs filesystems"<br />
<br />
When using systemd in the initrd, you need to install {{AUR|mkinitcpio-sd-zfs}} and add the {{ic|sd-zfs}} hook after the {{ic|systemd}} hook instead of the {{ic|zfs}} hook. Keep in mind that this hook uses different kernel parameters than the default {{ic|zfs}} hook, more information can be found at the [https://github.com/dasJ/sd-zfs project page].<br />
{{Note|<br />
{{ic|sd-zfs}} doesn't support native encryption yet [https://github.com/dasJ/sd-zfs/issues/4 dasJ/sd-zfs/issues/4]<br />
}}<br />
<br />
{{Note|<br />
* If you are using a separate dataset for {{ic|/usr}} and have followed the instructions below, you must make sure you have the {{ic|usr}} hook enabled after {{ic|zfs}}, or your system will not boot.<br />
* When you generate the initramfs, the {{ic|zpool.cache}} is copied into the initrd. If you didn't generate it before, or needed to regenerate it, remember to regenerate the initramfs again.<br />
* You can also use {{ic|legacy}} mountpoint to let fstab mount it<br />
}}<br />
<br />
* [[Regenerate the initramfs]].<br />
<br />
== Install and configure the bootloader ==<br />
<br />
=== Using GRUB for EFI/BIOS ===<br />
<br />
If you use GRUB, you can store your {{ic|/boot}} on a zpool.<br />
Please read [https://github.com/openzfs/zfs/wiki/Debian-Buster-Root-on-ZFS#step-3-system-installation Debian-Buster-Root-on-ZFS#step-3-system-installation].<br />
<br />
Install GRUB onto your disk as instructed here: [[GRUB#BIOS systems]] or [[GRUB#UEFI systems]]. The GRUB [https://www.gnu.org/software/grub/manual/grub.html#Configuration manual] provides detailed information on manually configuring the software which you can supplement with [[GRUB]] and [[GRUB/Tips and tricks]].<br />
<br />
==== Root pool missing from grub.cfg ====<br />
When grub-probe fails, the current code is to just stuff an empty result in which causes the user to not knowingly have a system that no longer boots.<br />
<br />
grub-probe can fail because the ZFS pool that contains the root filesystem might have features that grub does not yet support which is a common configuration for people with a rpool and a bpool.<br />
<br />
One must manually add back root pool name before a new GRUB release containing [https://lists.gnu.org/archive/html/grub-devel/2020-12/msg00239.html this fix], or else the system will not boot.<br />
<br />
==== error: failed to get canonical path of ====<br />
<br />
{{ic|grub-mkconfig}} fails to properly generate entries for systems hosted on ZFS.<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
/usr/bin/grub-probe: error: failed to get canonical path of `/dev/bus-Your_Disk_ID-part#'<br />
<br />
grub-install: error: failed to get canonical path of `/dev/bus-Your_Disk_ID-part#'<br />
<br />
To work around this you must set this environment variable: {{ic|1=ZPOOL_VDEV_NAME_PATH=1}}. For example:<br />
<br />
# ZPOOL_VDEV_NAME_PATH=1 grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
==== Booting your kernel and initrd from ZFS ====<br />
<br />
You may skip this section if you have your kernel and initrd on a separate {{ic|/boot}} partition using something like ext4 or vfat.<br />
<br />
Otherwise grub needs to load your kernel and initrd are from a ZFS dataset the kernel and initrd paths have to be in the following format:<br />
<br />
/dataset/@/actual/path <br />
<br />
Example with Arch installed on the root dataset:<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set timeout=5<br />
set default=0<br />
<br />
menuentry "Arch Linux" {<br />
search -u UUID<br />
linux /@/boot/vmlinuz-linux zfs=zroot rw<br />
initrd /@/boot/initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
Example with Arch installed on a nested dataset:<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set timeout=5<br />
set default=0<br />
<br />
menuentry "Arch Linux" {<br />
search -u UUID<br />
linux /ROOT/default/@/boot/vmlinuz-linux zfs=zroot/ROOT/default rw <br />
initrd /ROOT/default/@/boot/initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
==== Booting your kernel and initrd from separate boot partition ====<br />
Example with a separate non-ZFS {{ic|/boot}} partition and Arch installed on a nested dataset: <br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set timeout=5<br />
set default=0<br />
<br />
menuentry "Arch Linux" {<br />
search -u UUID<br />
linux /vmlinuz-linux zfs=zroot/ROOT/default rw<br />
initrd /initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
=== Using systemd-boot for EFI only ===<br />
<br />
Systemd-boot can't open ZFS zpools, you must store your {{ic|/boot}} on a separated VFAT or ext4 partition.<br />
<br />
{{Note|To be able to manage your Boot Environments with {{AUR|zectl}}, follow [https://github.com/johnramsden/zectl/blob/master/docs/plugins/systemdboot.md zectl/docs/plugins/systemdboot.md] }}<br />
<br />
Install bootloader on your {{ic|esp}}, following [[Systemd-boot#Installing the EFI boot manager]].<br />
<br />
Create a boot entry:<br />
<br />
{{hc|/efi/loader/entries/archlinux.conf|<nowiki><br />
title Arch Linux<br />
linux vmlinuz-linux<br />
initrd intel-ucode.img<br />
initrd initramfs-linux.img<br />
options zfs=zroot/ROOT/default rw<br />
</nowiki>}}<br />
<br />
=== Using rEFInd for UEFI ===<br />
<br />
Use {{ic|EFISTUB}} and {{ic|rEFInd}} for the UEFI boot loader. The kernel parameters in {{ic|refind_linux.conf}} for ZFS should include {{ic|1=zfs=bootfs}} or {{ic|1=zfs=zroot}} so the system can boot from ZFS. The {{ic|root}} and {{ic|rootfstype}} parameters are not needed.<br />
<br />
Before booting ZFS with rEFInd, a third-party EFI driver for ZFS must be installed, as rEFInd does not ship with ZFS driver. Currently [https://efi.akeo.ie/downloads/efifs-latest/x64/zfs_x64.efi zfs_x64.efi provided by Pete Bartard], a wrapper of GRUB ZFS driver, is the only available driver.<br />
<br />
{{ic|zfs_x64.efi}} will hang or crash rEFInd on some EFI-enabled computers, such as HP EliteBook 820 G3.<br />
<br />
== Configure systemd ZFS mounts ==<br />
<br />
For your system to be able to reboot without issues, you need to enable the {{ic|zfs.target}} to auto mount the pools and set the hostid.<br />
<br />
For each pool you want automatically mounted execute:<br />
# zpool set cachefile=/etc/zfs/zpool.cache <pool><br />
Enable the target with [[systemd]]:<br />
# systemctl enable zfs.target --root=/mnt<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 --root=/mnt<br />
# systemctl enable zfs-mount --root=/mnt<br />
# systemctl enable zfs-import.target --root=/mnt<br />
<br />
When running ZFS on root, the machine's hostid will not be available at the time of mounting the root filesystem. There are two solutions to this. You can either place your spl hostid in the [[kernel parameters]] in your boot loader. For example, adding {{ic|<nowiki>spl.spl_hostid=0x00bab10c</nowiki>}}, to get your number use the {{ic|hostid}} command.<br />
<br />
The other, and suggested, 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. To write the hostid file safely you need to use the {{ic|zgenhostid}} command.<br />
<br />
{{Note|Run it in {{ic|arch-chroot}} because zgenhostid will only write in {{ic|/etc/hostid}}}}<br />
<br />
To use the libc-generated hostid (recommended):<br />
# arch-chroot /mnt zgenhostid $(hostid)<br />
To use a custom hostid (must be hexadecimal and 8 characters long):<br />
# arch-chroot /mnt zgenhostid deadbeef<br />
To let the tool generate a hostid:<br />
# arch-chroot /mnt zgenhostid<br />
<br />
Don't forget to regenerate your image using [[mkinitcpio]].<br />
<br />
== Unmount and restart ==<br />
<br />
We are almost done!<br />
# umount /mnt/boot (if you have a legacy boot partition)<br />
# zfs umount -a<br />
# zpool export zroot<br />
<br />
Now reboot.<br />
<br />
{{Warning|If you do not properly export the zpool, the pool will refuse to import in the ramdisk environment and you will be stuck at the busybox terminal.}}<br />
<br />
=== Loading password from USB-Stick ===<br />
<br />
It is possible to store the password on a USB drive and load it when booting:<br />
Save the password on the first bytes of the USB drive:<br />
# dd if=your_password_file bs=32 count=1 of=/dev/disk/by-id/usb_stick<br />
<br />
To create a ZFS partition, you can either use previous described method with password prompt or pipe with [[dd]]:<br />
# dd if=/dev/disk/by-id/usb_stick bs=32 count=1 | zfs create -o encryption=on -o keyformat=passphrase zroot/ROOT<br />
<br />
The next step is modifying the zfs hook. By default ZFS prompts for a password. You have to change it to have it piped with {{ic|dd}} from your USB drive. In order to do so, modify {{ic|/usr/lib/initcpio/hooks/zfs}} and change the line:<br />
# ! eval zfs load-key "${encryptionroot}"; do<br />
to:<br />
# ! eval dd if=/dev/disk/by-id/usb_stick bs=32 count=1 | zfs load-key "${encryptionroot}"; do<br />
<br />
You are modifying your zfs hook, so don't forget to regenerate your image using [[mkinitcpio]].<br />
Now ZFS should load the password from your USB drive on boot.<br />
<br />
== Troubleshooting ==<br />
<br />
=== System fails to boot due to: cannot import zroot: no such pool available ===<br />
<br />
You can try the following steps and see if they can help.<br />
<br />
* Use the kernel modules from the [[Unofficial user repositories#archzfs|archzfs repo]] instead of the dkms version. You can go back to the dkms version after a sucessfull boot.<br />
* Remove the {{ic|/etc/zfs/zpool.cache}} and run:<br />
# zpool set cachefile=none zroot<br />
* Remove the {{ic|/etc/hostid}}.<br />
* Rebuild your initramfs.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/dajhorn/pkg-zfs/wiki/HOWTO-install-Ubuntu-to-a-Native-ZFS-Root-Filesystem HOWTO install Ubuntu to a Native ZFS Root]<br />
* [http://lildude.co.uk/zfs-cheatsheet ZFS cheatsheet]<br />
* [http://www.funtoo.org/wiki/ZFS_Install_Guide Funtoo ZFS install guide]<br />
* [https://kiljan.org/2018/09/23/a-reference-guide-to-zfs-on-arch-linux/ A reference guide to ZFS on Arch Linux]<br />
* [https://ramsdenj.com/2016/06/23/arch-linux-on-zfs-part-2-installation.html Arch Linux On Zfs ]<br />
* [https://www.youtube.com/watch?v=mLbtJQmfumI Youtube: Open-ZFS Bootcamp]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Install_Arch_Linux_on_ZFS&diff=649973Install Arch Linux on ZFS2021-01-26T23:06:01Z<p>Jstjohn: /* Booting your kernel and initrd from separate boot partition */ add ic template</p>
<hr />
<div>[[Category:Installation process]]<br />
[[ja:ZFS に Arch Linux をインストール]]<br />
{{Related articles start}}<br />
{{Related|ZFS}}<br />
{{Related|Experimenting with ZFS}}<br />
{{Related articles end}}<br />
This article details the steps required to install Arch Linux onto a ZFS root filesystem.<br />
<br />
{{Warning| Blindly copying and pasting this wiki will not work. It is necessary to take the time to understand the boot process, and what is done when creating the pool and datasets. Here are some useful links:<br />
* [https://www.freebsd.org/doc/handbook/zfs.html FreeBSD ZFS Handbook]<br />
* [https://github.com/zfsonlinux/zfs/wiki ZFSOnLinux wiki]<br />
* [http://open-zfs.org/wiki/System_Administration OpenZFS wiki]<br />
* [https://pthree.org/2012/04/17/install-zfs-on-debian-gnulinux/ Aaron Toponce Install ZFS on Debian GNU/Linux]{{Dead link|2020|12|27|status=SSL error}}<br />
}}<br />
<br />
== Installation ==<br />
<br />
To install Archlinux on ZFS, you need to boot archiso system with ZFS module.<br />
<br />
=== Get ZFS module on archiso system ===<br />
<br />
A script to easily install and load the ZFS module on running archiso system. It should work on any archiso version.<br />
<br />
See [https://github.com/eoli3n/archiso-zfs eoli3n/archiso-zfs]<br />
<br />
=== Embedding ZFS module into custom archiso ===<br />
<br />
To build custom archiso, see [[ZFS#Embed_the_archzfs_packages_into_an_archiso|ZFS]] article.<br />
<br />
== Partition the destination drive ==<br />
{{Accuracy|GRUB lacks support for many OpenZFS features. To work around this, separate pool for / and /boot must be created; separate swap partition preferred over swap on zvol|section=Update partition scheme for separate boot pool, root pool and swap partition}}<br />
Review [[Partitioning]] for information on determining the partition table type to use for ZFS. ZFS supports GPT and MBR partition tables.<br />
<br />
ZFS manages its own partitions, so only a basic partition table scheme is required. The partition that will contain the ZFS filesystem should be of the type {{ic|bf00}}, or "Solaris Root".<br />
<br />
Drives larger than 2TB require a GPT partition table. GRUB on BIOS/GPT configurations require a small (1~2MiB) BIOS boot partition to embed its image of boot code.<br />
<br />
Depending upon your machine's firmware or your choice of boot mode, booting may or may not require an EFI partition. On a BIOS machine (or a UEFI machine booting in legacy mode) EFI partition is not required. Consult [[Arch boot process#Boot loader]] for more information.<br />
<br />
=== Partition scheme ===<br />
<br />
Here is an example of a basic partition scheme that could be employed for your ZFS root install on a BIOS/MBR installation using GRUB:<br />
<br />
{{bc|<nowiki><br />
Part Size Type<br />
---- ---- -------------------------<br />
1 XXXG Solaris Root (bf00)</nowiki><br />
}}<br />
<br />
Using GRUB on a BIOS (or UEFI machine in legacy boot mode) machine but using a GPT partition table:<br />
<br />
{{bc|<nowiki><br />
Part Size Type<br />
---- ---- -------------------------<br />
1 2M BIOS boot partition (ef02)<br />
2 XXXG Solaris Root (bf00)</nowiki><br />
}}<br />
<br />
Another example, this time using a UEFI-specific bootloader (such as [[rEFInd]]) with an GPT partition table:<br />
<br />
{{bc|<nowiki><br />
Part Size Type<br />
---- ---- -------------------------<br />
1 100M EFI boot partition (ef00)<br />
2 XXXG Solaris Root (bf00)</nowiki><br />
}}<br />
<br />
ZFS does not support swap files. If you require a swap partition, see [[ZFS#Swap volume]] for creating a swap ZVOL.<br />
<br />
{{Tip|Bootloaders with support for ZFS are described in [[#Install and configure the bootloader]].}}<br />
{{Warning|Several GRUB bugs ([https://savannah.gnu.org/bugs/?42861 bug #42861], [https://github.com/zfsonlinux/grub/issues/5 zfsonlinux/grub/issues/5]) complicate installing it on ZFS partitions, see [[#Install and configure the bootloader]] for a workaround}}<br />
<br />
=== Example parted commands ===<br />
Here are some example commands to partition a drive for the second scenario above ie using BIOS/legacy boot mode with a GPT partition table and a (slighty more than) 1MB BIOS boot partition for GRUB:<br />
<br />
# parted /dev/sdx<br />
(parted)mklabel gpt<br />
(parted)mkpart non-fs 0% 2<br />
(parted)mkpart primary 2 100%<br />
(parted)set 1 bios_grub on<br />
(parted)set 2 boot on<br />
(parted)quit<br />
<br />
You can achieve the above in a single command like so:<br />
<br />
parted --script /dev/sdx mklabel gpt mkpart non-fs 0% 2 mkpart primary 2 100% set 1 bios_grub on set 2 boot on<br />
<br />
If you are creating an EFI partition then that should have the boot flag set instead of the root partition.<br />
<br />
== Format the destination disk ==<br />
<br />
If you have opted for a boot partition as well as any other non-ZFS system partitions then format them. Do not do anything to the Solaris partition nor to the BIOS boot partition. ZFS will manage the first, and your bootloader the second.<br />
<br />
== Setup the ZFS filesystem ==<br />
<br />
First, make sure the ZFS modules are loaded,<br />
<br />
# modprobe zfs<br />
<br />
=== Create the root zpool ===<br />
<br />
Create your pool and set all default dataset options. All dataset created on the zpool will inherit of each {{ic|-O}} set at the zpool creation.<br />
Default options are detailed in [https://openzfs.github.io/openzfs-docs/Getting%20Started/Debian/Debian%20Buster%20Root%20on%20ZFS.html#step-2-disk-formatting Debian Buster Root on ZFS. Step 2: Disk Formatting].<br />
<br />
{{Note|use {{ic|1=-o ashift=9}} for disks with a 512 byte physical sector size or {{ic|1=-o ashift=12}} for disks with a 4096 byte physical sector size. See {{ic|lsblk -S -o NAME,PHY-SEC}} to get the physical sector size of each SCSI/SATA disk. Remove -S if you want the same value from all devices.}}<br />
<br />
{{Note|Setting {{ic|1=normalization=formD}} eliminates some corner cases relating to UTF-8 filename normalization. It also implies {{ic|1=utf8only=on}}, which means that only UTF-8 filenames are allowed. If you care to support non-UTF-8 filenames, do not use this option. For a discussion of why requiring UTF-8 filenames may be a bad idea, see [http://utcc.utoronto.ca/~cks/space/blog/linux/ForcedUTF8Filenames The problems with enforced UTF-8 only filenames].}}<br />
<br />
# zpool create -f -o ashift=12 \<br />
-O acltype=posixacl \<br />
-O relatime=on \<br />
-O xattr=sa \<br />
-O dnodesize=legacy \<br />
-O normalization=formD \<br />
-O mountpoint=none \<br />
-O canmount=off \<br />
-O devices=off \<br />
-R /mnt \<br />
zroot /dev/disk/by-id/''id-to-partition-partx''<br />
<br />
==== Compression and native encryption ====<br />
{{Accuracy|GRUB will not boot a pool with native encryption, separate unencrypted boot pool mounted at /boot must be created|section=Update partition scheme for separate boot pool, root pool and swap partition}}<br />
This will enable compression and native encryption by default on all datasets:<br />
<br />
# zpool create -f -o ashift=12 \<br />
-O acltype=posixacl \<br />
-O relatime=on \<br />
-O xattr=sa \<br />
-O dnodesize=legacy \<br />
-O normalization=formD \<br />
-O mountpoint=none \<br />
-O canmount=off \<br />
-O devices=off \<br />
-R /mnt \<br />
-O compression=lz4 \<br />
-O encryption=aes-256-gcm \<br />
-O keyformat=passphrase \<br />
-O keylocation=prompt \<br />
zroot /dev/disk/by-id/''id-to-partition-partx''<br />
<br />
{{Warning|<br />
* Always use id names when working with ZFS, otherwise import errors will occur.<br />
* The zpool command will normally activate all features. See [[ZFS#GRUB-compatible pool creation]] when using [[GRUB]].}}<br />
<br />
=== Create your datasets ===<br />
<br />
Instead of using conventional disk partitions, ZFS has the concept of datasets to manage your storage. Unlike disk partitions, datasets have no fixed size and allow for different attributes, such as compression, to be applied per dataset. Normal ZFS datasets are mounted automatically by ZFS whilst legacy datasets are required to be mounted using fstab or with the traditional mount command.<br />
<br />
One of the most useful features of ZFS is boot environments. Boot environments allow you to create a bootable snapshot of your system that you can revert to at any time instantly by simply rebooting and booting from that boot environment. This can make doing system updates much safer and is also incredibly useful for developing and testing software. In order to be able to use a boot environment manager such as [https://github.com/b333z/beadm beadm], {{AUR|bieaz}}(port based on beadm, supports pacman hook with {{aur|rozb3-pac}}), {{AUR|zectl}} (systemd-boot), or {{AUR|zedenv}} (GRUB) to manage boot environments, your datasets must be configured properly. Key to this are that you split your data directories (such as {{ic|/home}}) into datasets that are distinct from your system datasets and that you do not place data in the root of the pool as this cannot be moved afterwards. <br />
<br />
You should always create a dataset for at least your root filesystem and in nearly all cases you will also want {{ic|/home}} to be in a separate dataset. You may decide you want your logs to persist over boot environments. If you are a running any software that stores data outside of {{ic|/home}} (such as is the case for database servers) you should structure your datasets so that the data directories of the software you want to run are separated out from the root dataset.<br />
<br />
With these example commands, we will create a basic boot environment compatible configuration comprising of just root and {{ic|/home}} datasets. It inherits default options from [[#Create the root zpool|zpool creation.]]<br />
<br />
# zfs create -o mountpoint=none zroot/data<br />
# zfs create -o mountpoint=none zroot/ROOT<br />
# zfs create -o mountpoint=/ -o canmount=noauto zroot/ROOT/default<br />
# zfs create -o mountpoint=/home zroot/data/home<br />
<br />
You can also create your ROOT dataset without having to specify mountpoint to / since GRUB will mount it to / anyway. <br />
That gives you possibility to boot into some old versions of root just by cloning it and putting as menuentry of GRUB. <br />
In such, you can create ROOT with the following command:<br />
# zfs create -o mountpoint=/roots/default zroot/ROOT/default<br />
<br />
You can store {{ic|/root}} in your {{ic|zroot/data/home}} dataset.<br />
<br />
# zfs create -o mountpoint=/root zroot/data/home/root<br />
<br />
You will need to enable some options for datasets which hold specific directories:<br />
<br />
{| class="wikitable" style="text-align: left;"<br />
|+ Options required by specific directories<br />
! scope="col" | Directory<br />
! scope="col" | Dataset Option<br />
! scope="col" | Details<br />
|-<br />
! {{ic|/}}<br />
| {{ic|1=canmount=noauto}} <br />
|<br />
|-<br />
|-<br />
! {{ic|/var/log/journal}}<br />
| {{ic|1=acltype=posixacl}}<br />
| [[Systemd#systemd-tmpfiles-setup.service fails to start at boot]]<br />
|-<br />
|}<br />
<br />
==== System datasets ====<br />
<br />
To create datasets for system directories, use {{ic|1=canmount=off}}.<br />
<br />
For some examples, please read [https://openzfs.github.io/openzfs-docs/Getting%20Started/Debian/Debian%20Buster%20Root%20on%20ZFS.html#step-3-system-installation Debian-Buster-Root-on-ZFS#step-3-system-installation]<br />
<br />
# zfs create -o mountpoint=/var -o canmount=off zroot/var<br />
# zfs create zroot/var/log<br />
# zfs create -o mountpoint=/var/lib -o canmount=off zroot/var/lib<br />
# zfs create zroot/var/lib/libvirt<br />
# zfs create zroot/var/lib/docker<br />
<br />
=== Export/Import your datasets ===<br />
<br />
To validate your configurations, export then reimport all your zpools.<br />
<br />
{{Warning|Do not skip this, otherwise you will be required to use {{ic|-f}} when importing your pools. This unloads the imported pool.}}<br />
{{Note|This might fail if you added a swap partition. You need to turn it off with the ''swapoff'' command.}}<br />
<br />
# zpool export zroot<br />
# zpool import -d /dev/disk/by-id -R /mnt zroot -N<br />
<br />
{{Note|{{ic|-d}} is not the actual device id, but the {{ic|/dev/by-id}} directory containing the symbolic links.<br />
If this command fails and you are asked to import your pool via its numeric ID, run {{ic|zpool import}} to <br />
find out the ID of your pool then use a command such as:<br />
{{ic|zpool import 9876543212345678910 -R /mnt zroot}}<br />
}}<br />
<br />
If you used native encryption, load zfs key.<br />
<br />
# zfs load-key zroot<br />
<br />
Manually mount your rootfs dataset because it uses {{ic|1=canmount=noauto}}, then mount all others datasets.<br />
<br />
# zfs mount zroot/ROOT/default<br />
# zfs mount -a<br />
<br />
The ZFS filesystem is now ready to use.<br />
<br />
=== Configure the root filesystem ===<br />
<br />
If you used legacy datasets, it must be listed in {{ic|/etc/fstab}}.<br />
<br />
Set the bootfs property on the descendant root filesystem so the boot loader knows where to find the operating system.<br />
<br />
# zpool set bootfs=zroot/ROOT/default zroot<br />
<br />
Be sure to bring the {{ic|zpool.cache}} file into your new system. This is required later for the ZFS daemon to start.<br />
<br />
# cp /etc/zfs/zpool.cache /mnt/etc/zfs/zpool.cache<br />
<br />
if you do not have {{ic|/etc/zfs/zpool.cache}}, create it:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache zroot<br />
<br />
== Install and configure Arch Linux ==<br />
<br />
Follow the following steps using the [[Installation guide]]. It will be noted where special consideration must be taken for ZFSonLinux.<br />
<br />
* First mount any legacy or non-ZFS boot or system partitions using the mount command.<br />
<br />
* Install the base system.<br />
<br />
* The procedure described in [[Installation guide#Fstab]] is usually overkill for ZFS. ZFS usually auto mounts its own partitions, so we do not need ZFS partitions in {{ic|fstab}} file, unless the user made legacy datasets of system directories. To generate the {{ic|fstab}} for filesystems, use:<br />
<br />
# genfstab -U -p /mnt >> /mnt/etc/fstab<br />
<br />
* Edit the {{ic|/etc/fstab}}:<br />
<br />
{{Note|<br />
* If you chose to create legacy datasets for system directories, keep them in this {{ic|fstab}}!<br />
* Comment out all non-legacy datasets apart from the swap file and the boot/EFI partition. It is a convention to replace the swap's uuid with {{ic|/dev/zvol/zroot/swap}}.<br />
}}<br />
<br />
* You need to add the [[Unofficial_user_repositories#archzfs|Arch ZFS]] repository to {{ic|/etc/pacman.conf}}, sign its key and [[install]] '''zfs-linux''' (or '''zfs-linux-lts''' if you are running the LTS kernel) within the arch-chroot before you can update the ramdisk with ZFS support.<br />
<br />
* When creating the initial ramdisk, first edit {{ic|/etc/mkinitcpio.conf}} and add {{ic|zfs}} before filesystems. Also, move {{ic|keyboard}} hook before {{ic|zfs}} so you can type in console if something goes wrong. You may also remove fsck (if you are not using Ext3 or Ext4). Your {{ic|HOOKS}} line should look something like this:<br />
HOOKS="base udev autodetect modconf block keyboard zfs filesystems"<br />
<br />
When using systemd in the initrd, you need to install {{AUR|mkinitcpio-sd-zfs}} and add the {{ic|sd-zfs}} hook after the {{ic|systemd}} hook instead of the {{ic|zfs}} hook. Keep in mind that this hook uses different kernel parameters than the default {{ic|zfs}} hook, more information can be found at the [https://github.com/dasJ/sd-zfs project page].<br />
{{Note|<br />
{{ic|sd-zfs}} doesn't support native encryption yet [https://github.com/dasJ/sd-zfs/issues/4 dasJ/sd-zfs/issues/4]<br />
}}<br />
<br />
{{Note|<br />
* If you are using a separate dataset for {{ic|/usr}} and have followed the instructions below, you must make sure you have the {{ic|usr}} hook enabled after {{ic|zfs}}, or your system will not boot.<br />
* When you generate the initramfs, the {{ic|zpool.cache}} is copied into the initrd. If you didn't generate it before, or needed to regenerate it, remember to regenerate the initramfs again.<br />
* You can also use {{ic|legacy}} mountpoint to let fstab mount it<br />
}}<br />
<br />
* [[Regenerate the initramfs]].<br />
<br />
== Install and configure the bootloader ==<br />
<br />
=== Using GRUB for EFI/BIOS ===<br />
<br />
If you use GRUB, you can store your {{ic|/boot}} on a zpool.<br />
Please read [https://github.com/openzfs/zfs/wiki/Debian-Buster-Root-on-ZFS#step-3-system-installation Debian-Buster-Root-on-ZFS#step-3-system-installation].<br />
<br />
Install GRUB onto your disk as instructed here: [[GRUB#BIOS systems]] or [[GRUB#UEFI systems]]. The GRUB [https://www.gnu.org/software/grub/manual/grub.html#Configuration manual] provides detailed information on manually configuring the software which you can supplement with [[GRUB]] and [[GRUB/Tips and tricks]].<br />
<br />
==== Root pool missing from grub.cfg ====<br />
When grub-probe fails, the current code is to just stuff an empty result in which causes the user to not knowingly have a system that no longer boots.<br />
<br />
grub-probe can fail because the ZFS pool that contains the root filesystem might have features that grub does not yet support which is a common configuration for people with a rpool and a bpool.<br />
<br />
One must manually add back root pool name before a new GRUB release containing [https://lists.gnu.org/archive/html/grub-devel/2020-12/msg00239.html this fix], or else the system will not boot.<br />
<br />
==== error: failed to get canonical path of ====<br />
<br />
{{ic|grub-mkconfig}} fails to properly generate entries for systems hosted on ZFS.<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
/usr/bin/grub-probe: error: failed to get canonical path of `/dev/bus-Your_Disk_ID-part#'<br />
<br />
grub-install: error: failed to get canonical path of `/dev/bus-Your_Disk_ID-part#'<br />
<br />
To work around this you must set this environment variable: {{ic|1=ZPOOL_VDEV_NAME_PATH=1}}. For example:<br />
<br />
# ZPOOL_VDEV_NAME_PATH=1 grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
==== Booting your kernel and initrd from ZFS ====<br />
<br />
You may skip this section if you have your kernel and initrd on a separate {{ic|/boot}} partition using something like ext4 or vfat.<br />
<br />
Otherwise grub needs to load your kernel and initrd are from a ZFS dataset the kernel and initrd paths have to be in the following format:<br />
<br />
/dataset/@/actual/path <br />
<br />
Example with Arch installed on the root dataset:<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set timeout=5<br />
set default=0<br />
<br />
menuentry "Arch Linux" {<br />
search -u UUID<br />
linux /@/boot/vmlinuz-linux zfs=zroot rw<br />
initrd /@/boot/initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
Example with Arch installed on a nested dataset:<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set timeout=5<br />
set default=0<br />
<br />
menuentry "Arch Linux" {<br />
search -u UUID<br />
linux /ROOT/default/@/boot/vmlinuz-linux zfs=zroot/ROOT/default rw <br />
initrd /ROOT/default/@/boot/initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
==== Booting your kernel and initrd from separate boot partition ====<br />
Example with a separate non-ZFS {{ic|/boot}} partition and Arch installed on a nested dataset: <br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set timeout=5<br />
set default=0<br />
<br />
menuentry "Arch Linux" {<br />
search -u UUID<br />
linux /vmlinuz-linux zfs=zroot/ROOT/default rw<br />
initrd /initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
=== Using systemd-boot for EFI only ===<br />
<br />
Systemd-boot can't open ZFS zpools, you must store your {{ic|/boot}} on a separated VFAT or ext4 partition.<br />
<br />
{{Note|To be able to manage your Boot Environments with {{AUR|zectl}}, follow [https://github.com/johnramsden/zectl/blob/master/docs/plugins/systemdboot.md zectl/docs/plugins/systemdboot.md] }}<br />
<br />
Install bootloader on your {{ic|esp}}, following [[Systemd-boot#Installing the EFI boot manager]].<br />
<br />
Create a boot entry:<br />
<br />
{{hc|/efi/loader/entries/archlinux.conf|<nowiki><br />
title Arch Linux<br />
linux vmlinuz-linux<br />
initrd intel-ucode.img<br />
initrd initramfs-linux.img<br />
options zfs=zroot/ROOT/default rw<br />
</nowiki>}}<br />
<br />
=== Using rEFInd for UEFI ===<br />
<br />
Use {{ic|EFISTUB}} and {{ic|rEFInd}} for the UEFI boot loader. The kernel parameters in {{ic|refind_linux.conf}} for ZFS should include {{ic|1=zfs=bootfs}} or {{ic|1=zfs=zroot}} so the system can boot from ZFS. The {{ic|root}} and {{ic|rootfstype}} parameters are not needed.<br />
<br />
Before booting ZFS with rEFInd, a third-party EFI driver for ZFS must be installed, as rEFInd does not ship with ZFS driver. Currently [https://efi.akeo.ie/downloads/efifs-latest/x64/zfs_x64.efi zfs_x64.efi provided by Pete Bartard], a wrapper of GRUB ZFS driver, is the only available driver.<br />
<br />
{{ic|zfs_x64.efi}} will hang or crash rEFInd on some EFI-enabled computers, such as HP EliteBook 820 G3.<br />
<br />
== Configure systemd ZFS mounts ==<br />
<br />
For your system to be able to reboot without issues, you need to enable the {{ic|zfs.target}} to auto mount the pools and set the hostid.<br />
<br />
For each pool you want automatically mounted execute:<br />
# zpool set cachefile=/etc/zfs/zpool.cache <pool><br />
Enable the target with [[systemd]]:<br />
# systemctl enable zfs.target --root=/mnt<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 --root=/mnt<br />
# systemctl enable zfs-mount --root=/mnt<br />
# systemctl enable zfs-import.target --root=/mnt<br />
<br />
When running ZFS on root, the machine's hostid will not be available at the time of mounting the root filesystem. There are two solutions to this. You can either place your spl hostid in the [[kernel parameters]] in your boot loader. For example, adding {{ic|<nowiki>spl.spl_hostid=0x00bab10c</nowiki>}}, to get your number use the {{ic|hostid}} command.<br />
<br />
The other, and suggested, 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. To write the hostid file safely you need to use the {{ic|zgenhostid}} command.<br />
<br />
{{Note|Run it in {{ic|arch-chroot}} because zgenhostid will only write in {{ic|/etc/hostid}}}}<br />
<br />
To use the libc-generated hostid (recommended):<br />
# arch-chroot /mnt zgenhostid $(hostid)<br />
To use a custom hostid (must be hexadecimal and 8 characters long):<br />
# arch-chroot /mnt zgenhostid deadbeef<br />
To let the tool generate a hostid:<br />
# arch-chroot /mnt zgenhostid<br />
<br />
Don't forget to regenerate your image using [[mkinitcpio]].<br />
<br />
== Unmount and restart ==<br />
<br />
We are almost done!<br />
# umount /mnt/boot (if you have a legacy boot partition)<br />
# zfs umount -a<br />
# zpool export zroot<br />
<br />
Now reboot.<br />
<br />
{{Warning|If you do not properly export the zpool, the pool will refuse to import in the ramdisk environment and you will be stuck at the busybox terminal.}}<br />
<br />
=== Loading password from USB-Stick ===<br />
<br />
It is possible to store password on usb-stick and load it when booting:<br />
Save password on first bytes of usb-stick:<br />
# dd if=your_password_file bs=32 count=1 of=/dev/disk/by-id/usb_stick<br />
To create partition zfs partition you can either use previous described method with password prompt or pipe with [[dd]]:<br />
# dd if=/dev/disk/by-id/usb_stick bs=32 count=1 | zfs create -o encryption=on -o keyformat=passphrase zroot/ROOT<br />
Next step is modyfing zfs hook. By default zfs prompts for password. You have to change it to have it piped with dd from your pendrive. In order to do so modify /usr/lib/initcpio/hooks/zfs and change line:<br />
# ! eval zfs load-key "${encryptionroot}"; do<br />
to:<br />
# ! eval dd if=/dev/disk/by-id/usb_stick bs=32 count=1 | zfs load-key "${encryptionroot}"; do<br />
You are modifying your zfs hook so don't forget to regenerate your image using [[mkinitcpio]].<br />
Now zfs should load password from your usb-stick on boot.<br />
<br />
== Troubleshooting ==<br />
<br />
=== System fails to boot due to: cannot import zroot: no such pool available ===<br />
<br />
You can try the following steps and see if they can help.<br />
<br />
* Use the kernel modules from the [[Unofficial user repositories#archzfs|archzfs repo]] instead of the dkms version. You can go back to the dkms version after a sucessfull boot.<br />
* Remove the {{ic|/etc/zfs/zpool.cache}} and run:<br />
# zpool set cachefile=none zroot<br />
* Remove the {{ic|/etc/hostid}}.<br />
* Rebuild your initramfs.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/dajhorn/pkg-zfs/wiki/HOWTO-install-Ubuntu-to-a-Native-ZFS-Root-Filesystem HOWTO install Ubuntu to a Native ZFS Root]<br />
* [http://lildude.co.uk/zfs-cheatsheet ZFS cheatsheet]<br />
* [http://www.funtoo.org/wiki/ZFS_Install_Guide Funtoo ZFS install guide]<br />
* [https://kiljan.org/2018/09/23/a-reference-guide-to-zfs-on-arch-linux/ A reference guide to ZFS on Arch Linux]<br />
* [https://ramsdenj.com/2016/06/23/arch-linux-on-zfs-part-2-installation.html Arch Linux On Zfs ]<br />
* [https://www.youtube.com/watch?v=mLbtJQmfumI Youtube: Open-ZFS Bootcamp]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Install_Arch_Linux_on_ZFS&diff=649972Install Arch Linux on ZFS2021-01-26T23:05:04Z<p>Jstjohn: /* Create your datasets */ add ic templates to dataset options table</p>
<hr />
<div>[[Category:Installation process]]<br />
[[ja:ZFS に Arch Linux をインストール]]<br />
{{Related articles start}}<br />
{{Related|ZFS}}<br />
{{Related|Experimenting with ZFS}}<br />
{{Related articles end}}<br />
This article details the steps required to install Arch Linux onto a ZFS root filesystem.<br />
<br />
{{Warning| Blindly copying and pasting this wiki will not work. It is necessary to take the time to understand the boot process, and what is done when creating the pool and datasets. Here are some useful links:<br />
* [https://www.freebsd.org/doc/handbook/zfs.html FreeBSD ZFS Handbook]<br />
* [https://github.com/zfsonlinux/zfs/wiki ZFSOnLinux wiki]<br />
* [http://open-zfs.org/wiki/System_Administration OpenZFS wiki]<br />
* [https://pthree.org/2012/04/17/install-zfs-on-debian-gnulinux/ Aaron Toponce Install ZFS on Debian GNU/Linux]{{Dead link|2020|12|27|status=SSL error}}<br />
}}<br />
<br />
== Installation ==<br />
<br />
To install Archlinux on ZFS, you need to boot archiso system with ZFS module.<br />
<br />
=== Get ZFS module on archiso system ===<br />
<br />
A script to easily install and load the ZFS module on running archiso system. It should work on any archiso version.<br />
<br />
See [https://github.com/eoli3n/archiso-zfs eoli3n/archiso-zfs]<br />
<br />
=== Embedding ZFS module into custom archiso ===<br />
<br />
To build custom archiso, see [[ZFS#Embed_the_archzfs_packages_into_an_archiso|ZFS]] article.<br />
<br />
== Partition the destination drive ==<br />
{{Accuracy|GRUB lacks support for many OpenZFS features. To work around this, separate pool for / and /boot must be created; separate swap partition preferred over swap on zvol|section=Update partition scheme for separate boot pool, root pool and swap partition}}<br />
Review [[Partitioning]] for information on determining the partition table type to use for ZFS. ZFS supports GPT and MBR partition tables.<br />
<br />
ZFS manages its own partitions, so only a basic partition table scheme is required. The partition that will contain the ZFS filesystem should be of the type {{ic|bf00}}, or "Solaris Root".<br />
<br />
Drives larger than 2TB require a GPT partition table. GRUB on BIOS/GPT configurations require a small (1~2MiB) BIOS boot partition to embed its image of boot code.<br />
<br />
Depending upon your machine's firmware or your choice of boot mode, booting may or may not require an EFI partition. On a BIOS machine (or a UEFI machine booting in legacy mode) EFI partition is not required. Consult [[Arch boot process#Boot loader]] for more information.<br />
<br />
=== Partition scheme ===<br />
<br />
Here is an example of a basic partition scheme that could be employed for your ZFS root install on a BIOS/MBR installation using GRUB:<br />
<br />
{{bc|<nowiki><br />
Part Size Type<br />
---- ---- -------------------------<br />
1 XXXG Solaris Root (bf00)</nowiki><br />
}}<br />
<br />
Using GRUB on a BIOS (or UEFI machine in legacy boot mode) machine but using a GPT partition table:<br />
<br />
{{bc|<nowiki><br />
Part Size Type<br />
---- ---- -------------------------<br />
1 2M BIOS boot partition (ef02)<br />
2 XXXG Solaris Root (bf00)</nowiki><br />
}}<br />
<br />
Another example, this time using a UEFI-specific bootloader (such as [[rEFInd]]) with an GPT partition table:<br />
<br />
{{bc|<nowiki><br />
Part Size Type<br />
---- ---- -------------------------<br />
1 100M EFI boot partition (ef00)<br />
2 XXXG Solaris Root (bf00)</nowiki><br />
}}<br />
<br />
ZFS does not support swap files. If you require a swap partition, see [[ZFS#Swap volume]] for creating a swap ZVOL.<br />
<br />
{{Tip|Bootloaders with support for ZFS are described in [[#Install and configure the bootloader]].}}<br />
{{Warning|Several GRUB bugs ([https://savannah.gnu.org/bugs/?42861 bug #42861], [https://github.com/zfsonlinux/grub/issues/5 zfsonlinux/grub/issues/5]) complicate installing it on ZFS partitions, see [[#Install and configure the bootloader]] for a workaround}}<br />
<br />
=== Example parted commands ===<br />
Here are some example commands to partition a drive for the second scenario above ie using BIOS/legacy boot mode with a GPT partition table and a (slighty more than) 1MB BIOS boot partition for GRUB:<br />
<br />
# parted /dev/sdx<br />
(parted)mklabel gpt<br />
(parted)mkpart non-fs 0% 2<br />
(parted)mkpart primary 2 100%<br />
(parted)set 1 bios_grub on<br />
(parted)set 2 boot on<br />
(parted)quit<br />
<br />
You can achieve the above in a single command like so:<br />
<br />
parted --script /dev/sdx mklabel gpt mkpart non-fs 0% 2 mkpart primary 2 100% set 1 bios_grub on set 2 boot on<br />
<br />
If you are creating an EFI partition then that should have the boot flag set instead of the root partition.<br />
<br />
== Format the destination disk ==<br />
<br />
If you have opted for a boot partition as well as any other non-ZFS system partitions then format them. Do not do anything to the Solaris partition nor to the BIOS boot partition. ZFS will manage the first, and your bootloader the second.<br />
<br />
== Setup the ZFS filesystem ==<br />
<br />
First, make sure the ZFS modules are loaded,<br />
<br />
# modprobe zfs<br />
<br />
=== Create the root zpool ===<br />
<br />
Create your pool and set all default dataset options. All dataset created on the zpool will inherit of each {{ic|-O}} set at the zpool creation.<br />
Default options are detailed in [https://openzfs.github.io/openzfs-docs/Getting%20Started/Debian/Debian%20Buster%20Root%20on%20ZFS.html#step-2-disk-formatting Debian Buster Root on ZFS. Step 2: Disk Formatting].<br />
<br />
{{Note|use {{ic|1=-o ashift=9}} for disks with a 512 byte physical sector size or {{ic|1=-o ashift=12}} for disks with a 4096 byte physical sector size. See {{ic|lsblk -S -o NAME,PHY-SEC}} to get the physical sector size of each SCSI/SATA disk. Remove -S if you want the same value from all devices.}}<br />
<br />
{{Note|Setting {{ic|1=normalization=formD}} eliminates some corner cases relating to UTF-8 filename normalization. It also implies {{ic|1=utf8only=on}}, which means that only UTF-8 filenames are allowed. If you care to support non-UTF-8 filenames, do not use this option. For a discussion of why requiring UTF-8 filenames may be a bad idea, see [http://utcc.utoronto.ca/~cks/space/blog/linux/ForcedUTF8Filenames The problems with enforced UTF-8 only filenames].}}<br />
<br />
# zpool create -f -o ashift=12 \<br />
-O acltype=posixacl \<br />
-O relatime=on \<br />
-O xattr=sa \<br />
-O dnodesize=legacy \<br />
-O normalization=formD \<br />
-O mountpoint=none \<br />
-O canmount=off \<br />
-O devices=off \<br />
-R /mnt \<br />
zroot /dev/disk/by-id/''id-to-partition-partx''<br />
<br />
==== Compression and native encryption ====<br />
{{Accuracy|GRUB will not boot a pool with native encryption, separate unencrypted boot pool mounted at /boot must be created|section=Update partition scheme for separate boot pool, root pool and swap partition}}<br />
This will enable compression and native encryption by default on all datasets:<br />
<br />
# zpool create -f -o ashift=12 \<br />
-O acltype=posixacl \<br />
-O relatime=on \<br />
-O xattr=sa \<br />
-O dnodesize=legacy \<br />
-O normalization=formD \<br />
-O mountpoint=none \<br />
-O canmount=off \<br />
-O devices=off \<br />
-R /mnt \<br />
-O compression=lz4 \<br />
-O encryption=aes-256-gcm \<br />
-O keyformat=passphrase \<br />
-O keylocation=prompt \<br />
zroot /dev/disk/by-id/''id-to-partition-partx''<br />
<br />
{{Warning|<br />
* Always use id names when working with ZFS, otherwise import errors will occur.<br />
* The zpool command will normally activate all features. See [[ZFS#GRUB-compatible pool creation]] when using [[GRUB]].}}<br />
<br />
=== Create your datasets ===<br />
<br />
Instead of using conventional disk partitions, ZFS has the concept of datasets to manage your storage. Unlike disk partitions, datasets have no fixed size and allow for different attributes, such as compression, to be applied per dataset. Normal ZFS datasets are mounted automatically by ZFS whilst legacy datasets are required to be mounted using fstab or with the traditional mount command.<br />
<br />
One of the most useful features of ZFS is boot environments. Boot environments allow you to create a bootable snapshot of your system that you can revert to at any time instantly by simply rebooting and booting from that boot environment. This can make doing system updates much safer and is also incredibly useful for developing and testing software. In order to be able to use a boot environment manager such as [https://github.com/b333z/beadm beadm], {{AUR|bieaz}}(port based on beadm, supports pacman hook with {{aur|rozb3-pac}}), {{AUR|zectl}} (systemd-boot), or {{AUR|zedenv}} (GRUB) to manage boot environments, your datasets must be configured properly. Key to this are that you split your data directories (such as {{ic|/home}}) into datasets that are distinct from your system datasets and that you do not place data in the root of the pool as this cannot be moved afterwards. <br />
<br />
You should always create a dataset for at least your root filesystem and in nearly all cases you will also want {{ic|/home}} to be in a separate dataset. You may decide you want your logs to persist over boot environments. If you are a running any software that stores data outside of {{ic|/home}} (such as is the case for database servers) you should structure your datasets so that the data directories of the software you want to run are separated out from the root dataset.<br />
<br />
With these example commands, we will create a basic boot environment compatible configuration comprising of just root and {{ic|/home}} datasets. It inherits default options from [[#Create the root zpool|zpool creation.]]<br />
<br />
# zfs create -o mountpoint=none zroot/data<br />
# zfs create -o mountpoint=none zroot/ROOT<br />
# zfs create -o mountpoint=/ -o canmount=noauto zroot/ROOT/default<br />
# zfs create -o mountpoint=/home zroot/data/home<br />
<br />
You can also create your ROOT dataset without having to specify mountpoint to / since GRUB will mount it to / anyway. <br />
That gives you possibility to boot into some old versions of root just by cloning it and putting as menuentry of GRUB. <br />
In such, you can create ROOT with the following command:<br />
# zfs create -o mountpoint=/roots/default zroot/ROOT/default<br />
<br />
You can store {{ic|/root}} in your {{ic|zroot/data/home}} dataset.<br />
<br />
# zfs create -o mountpoint=/root zroot/data/home/root<br />
<br />
You will need to enable some options for datasets which hold specific directories:<br />
<br />
{| class="wikitable" style="text-align: left;"<br />
|+ Options required by specific directories<br />
! scope="col" | Directory<br />
! scope="col" | Dataset Option<br />
! scope="col" | Details<br />
|-<br />
! {{ic|/}}<br />
| {{ic|1=canmount=noauto}} <br />
|<br />
|-<br />
|-<br />
! {{ic|/var/log/journal}}<br />
| {{ic|1=acltype=posixacl}}<br />
| [[Systemd#systemd-tmpfiles-setup.service fails to start at boot]]<br />
|-<br />
|}<br />
<br />
==== System datasets ====<br />
<br />
To create datasets for system directories, use {{ic|1=canmount=off}}.<br />
<br />
For some examples, please read [https://openzfs.github.io/openzfs-docs/Getting%20Started/Debian/Debian%20Buster%20Root%20on%20ZFS.html#step-3-system-installation Debian-Buster-Root-on-ZFS#step-3-system-installation]<br />
<br />
# zfs create -o mountpoint=/var -o canmount=off zroot/var<br />
# zfs create zroot/var/log<br />
# zfs create -o mountpoint=/var/lib -o canmount=off zroot/var/lib<br />
# zfs create zroot/var/lib/libvirt<br />
# zfs create zroot/var/lib/docker<br />
<br />
=== Export/Import your datasets ===<br />
<br />
To validate your configurations, export then reimport all your zpools.<br />
<br />
{{Warning|Do not skip this, otherwise you will be required to use {{ic|-f}} when importing your pools. This unloads the imported pool.}}<br />
{{Note|This might fail if you added a swap partition. You need to turn it off with the ''swapoff'' command.}}<br />
<br />
# zpool export zroot<br />
# zpool import -d /dev/disk/by-id -R /mnt zroot -N<br />
<br />
{{Note|{{ic|-d}} is not the actual device id, but the {{ic|/dev/by-id}} directory containing the symbolic links.<br />
If this command fails and you are asked to import your pool via its numeric ID, run {{ic|zpool import}} to <br />
find out the ID of your pool then use a command such as:<br />
{{ic|zpool import 9876543212345678910 -R /mnt zroot}}<br />
}}<br />
<br />
If you used native encryption, load zfs key.<br />
<br />
# zfs load-key zroot<br />
<br />
Manually mount your rootfs dataset because it uses {{ic|1=canmount=noauto}}, then mount all others datasets.<br />
<br />
# zfs mount zroot/ROOT/default<br />
# zfs mount -a<br />
<br />
The ZFS filesystem is now ready to use.<br />
<br />
=== Configure the root filesystem ===<br />
<br />
If you used legacy datasets, it must be listed in {{ic|/etc/fstab}}.<br />
<br />
Set the bootfs property on the descendant root filesystem so the boot loader knows where to find the operating system.<br />
<br />
# zpool set bootfs=zroot/ROOT/default zroot<br />
<br />
Be sure to bring the {{ic|zpool.cache}} file into your new system. This is required later for the ZFS daemon to start.<br />
<br />
# cp /etc/zfs/zpool.cache /mnt/etc/zfs/zpool.cache<br />
<br />
if you do not have {{ic|/etc/zfs/zpool.cache}}, create it:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache zroot<br />
<br />
== Install and configure Arch Linux ==<br />
<br />
Follow the following steps using the [[Installation guide]]. It will be noted where special consideration must be taken for ZFSonLinux.<br />
<br />
* First mount any legacy or non-ZFS boot or system partitions using the mount command.<br />
<br />
* Install the base system.<br />
<br />
* The procedure described in [[Installation guide#Fstab]] is usually overkill for ZFS. ZFS usually auto mounts its own partitions, so we do not need ZFS partitions in {{ic|fstab}} file, unless the user made legacy datasets of system directories. To generate the {{ic|fstab}} for filesystems, use:<br />
<br />
# genfstab -U -p /mnt >> /mnt/etc/fstab<br />
<br />
* Edit the {{ic|/etc/fstab}}:<br />
<br />
{{Note|<br />
* If you chose to create legacy datasets for system directories, keep them in this {{ic|fstab}}!<br />
* Comment out all non-legacy datasets apart from the swap file and the boot/EFI partition. It is a convention to replace the swap's uuid with {{ic|/dev/zvol/zroot/swap}}.<br />
}}<br />
<br />
* You need to add the [[Unofficial_user_repositories#archzfs|Arch ZFS]] repository to {{ic|/etc/pacman.conf}}, sign its key and [[install]] '''zfs-linux''' (or '''zfs-linux-lts''' if you are running the LTS kernel) within the arch-chroot before you can update the ramdisk with ZFS support.<br />
<br />
* When creating the initial ramdisk, first edit {{ic|/etc/mkinitcpio.conf}} and add {{ic|zfs}} before filesystems. Also, move {{ic|keyboard}} hook before {{ic|zfs}} so you can type in console if something goes wrong. You may also remove fsck (if you are not using Ext3 or Ext4). Your {{ic|HOOKS}} line should look something like this:<br />
HOOKS="base udev autodetect modconf block keyboard zfs filesystems"<br />
<br />
When using systemd in the initrd, you need to install {{AUR|mkinitcpio-sd-zfs}} and add the {{ic|sd-zfs}} hook after the {{ic|systemd}} hook instead of the {{ic|zfs}} hook. Keep in mind that this hook uses different kernel parameters than the default {{ic|zfs}} hook, more information can be found at the [https://github.com/dasJ/sd-zfs project page].<br />
{{Note|<br />
{{ic|sd-zfs}} doesn't support native encryption yet [https://github.com/dasJ/sd-zfs/issues/4 dasJ/sd-zfs/issues/4]<br />
}}<br />
<br />
{{Note|<br />
* If you are using a separate dataset for {{ic|/usr}} and have followed the instructions below, you must make sure you have the {{ic|usr}} hook enabled after {{ic|zfs}}, or your system will not boot.<br />
* When you generate the initramfs, the {{ic|zpool.cache}} is copied into the initrd. If you didn't generate it before, or needed to regenerate it, remember to regenerate the initramfs again.<br />
* You can also use {{ic|legacy}} mountpoint to let fstab mount it<br />
}}<br />
<br />
* [[Regenerate the initramfs]].<br />
<br />
== Install and configure the bootloader ==<br />
<br />
=== Using GRUB for EFI/BIOS ===<br />
<br />
If you use GRUB, you can store your {{ic|/boot}} on a zpool.<br />
Please read [https://github.com/openzfs/zfs/wiki/Debian-Buster-Root-on-ZFS#step-3-system-installation Debian-Buster-Root-on-ZFS#step-3-system-installation].<br />
<br />
Install GRUB onto your disk as instructed here: [[GRUB#BIOS systems]] or [[GRUB#UEFI systems]]. The GRUB [https://www.gnu.org/software/grub/manual/grub.html#Configuration manual] provides detailed information on manually configuring the software which you can supplement with [[GRUB]] and [[GRUB/Tips and tricks]].<br />
<br />
==== Root pool missing from grub.cfg ====<br />
When grub-probe fails, the current code is to just stuff an empty result in which causes the user to not knowingly have a system that no longer boots.<br />
<br />
grub-probe can fail because the ZFS pool that contains the root filesystem might have features that grub does not yet support which is a common configuration for people with a rpool and a bpool.<br />
<br />
One must manually add back root pool name before a new GRUB release containing [https://lists.gnu.org/archive/html/grub-devel/2020-12/msg00239.html this fix], or else the system will not boot.<br />
<br />
==== error: failed to get canonical path of ====<br />
<br />
{{ic|grub-mkconfig}} fails to properly generate entries for systems hosted on ZFS.<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
/usr/bin/grub-probe: error: failed to get canonical path of `/dev/bus-Your_Disk_ID-part#'<br />
<br />
grub-install: error: failed to get canonical path of `/dev/bus-Your_Disk_ID-part#'<br />
<br />
To work around this you must set this environment variable: {{ic|1=ZPOOL_VDEV_NAME_PATH=1}}. For example:<br />
<br />
# ZPOOL_VDEV_NAME_PATH=1 grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
==== Booting your kernel and initrd from ZFS ====<br />
<br />
You may skip this section if you have your kernel and initrd on a separate {{ic|/boot}} partition using something like ext4 or vfat.<br />
<br />
Otherwise grub needs to load your kernel and initrd are from a ZFS dataset the kernel and initrd paths have to be in the following format:<br />
<br />
/dataset/@/actual/path <br />
<br />
Example with Arch installed on the root dataset:<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set timeout=5<br />
set default=0<br />
<br />
menuentry "Arch Linux" {<br />
search -u UUID<br />
linux /@/boot/vmlinuz-linux zfs=zroot rw<br />
initrd /@/boot/initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
Example with Arch installed on a nested dataset:<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set timeout=5<br />
set default=0<br />
<br />
menuentry "Arch Linux" {<br />
search -u UUID<br />
linux /ROOT/default/@/boot/vmlinuz-linux zfs=zroot/ROOT/default rw <br />
initrd /ROOT/default/@/boot/initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
==== Booting your kernel and initrd from separate boot partition ====<br />
Example with a separate non-ZFS /boot partition and Arch installed on a nested dataset: <br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set timeout=5<br />
set default=0<br />
<br />
menuentry "Arch Linux" {<br />
search -u UUID<br />
linux /vmlinuz-linux zfs=zroot/ROOT/default rw<br />
initrd /initramfs-linux.img<br />
}<br />
</nowiki>}}<br />
<br />
=== Using systemd-boot for EFI only ===<br />
<br />
Systemd-boot can't open ZFS zpools, you must store your {{ic|/boot}} on a separated VFAT or ext4 partition.<br />
<br />
{{Note|To be able to manage your Boot Environments with {{AUR|zectl}}, follow [https://github.com/johnramsden/zectl/blob/master/docs/plugins/systemdboot.md zectl/docs/plugins/systemdboot.md] }}<br />
<br />
Install bootloader on your {{ic|esp}}, following [[Systemd-boot#Installing the EFI boot manager]].<br />
<br />
Create a boot entry:<br />
<br />
{{hc|/efi/loader/entries/archlinux.conf|<nowiki><br />
title Arch Linux<br />
linux vmlinuz-linux<br />
initrd intel-ucode.img<br />
initrd initramfs-linux.img<br />
options zfs=zroot/ROOT/default rw<br />
</nowiki>}}<br />
<br />
=== Using rEFInd for UEFI ===<br />
<br />
Use {{ic|EFISTUB}} and {{ic|rEFInd}} for the UEFI boot loader. The kernel parameters in {{ic|refind_linux.conf}} for ZFS should include {{ic|1=zfs=bootfs}} or {{ic|1=zfs=zroot}} so the system can boot from ZFS. The {{ic|root}} and {{ic|rootfstype}} parameters are not needed.<br />
<br />
Before booting ZFS with rEFInd, a third-party EFI driver for ZFS must be installed, as rEFInd does not ship with ZFS driver. Currently [https://efi.akeo.ie/downloads/efifs-latest/x64/zfs_x64.efi zfs_x64.efi provided by Pete Bartard], a wrapper of GRUB ZFS driver, is the only available driver.<br />
<br />
{{ic|zfs_x64.efi}} will hang or crash rEFInd on some EFI-enabled computers, such as HP EliteBook 820 G3.<br />
<br />
== Configure systemd ZFS mounts ==<br />
<br />
For your system to be able to reboot without issues, you need to enable the {{ic|zfs.target}} to auto mount the pools and set the hostid.<br />
<br />
For each pool you want automatically mounted execute:<br />
# zpool set cachefile=/etc/zfs/zpool.cache <pool><br />
Enable the target with [[systemd]]:<br />
# systemctl enable zfs.target --root=/mnt<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 --root=/mnt<br />
# systemctl enable zfs-mount --root=/mnt<br />
# systemctl enable zfs-import.target --root=/mnt<br />
<br />
When running ZFS on root, the machine's hostid will not be available at the time of mounting the root filesystem. There are two solutions to this. You can either place your spl hostid in the [[kernel parameters]] in your boot loader. For example, adding {{ic|<nowiki>spl.spl_hostid=0x00bab10c</nowiki>}}, to get your number use the {{ic|hostid}} command.<br />
<br />
The other, and suggested, 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. To write the hostid file safely you need to use the {{ic|zgenhostid}} command.<br />
<br />
{{Note|Run it in {{ic|arch-chroot}} because zgenhostid will only write in {{ic|/etc/hostid}}}}<br />
<br />
To use the libc-generated hostid (recommended):<br />
# arch-chroot /mnt zgenhostid $(hostid)<br />
To use a custom hostid (must be hexadecimal and 8 characters long):<br />
# arch-chroot /mnt zgenhostid deadbeef<br />
To let the tool generate a hostid:<br />
# arch-chroot /mnt zgenhostid<br />
<br />
Don't forget to regenerate your image using [[mkinitcpio]].<br />
<br />
== Unmount and restart ==<br />
<br />
We are almost done!<br />
# umount /mnt/boot (if you have a legacy boot partition)<br />
# zfs umount -a<br />
# zpool export zroot<br />
<br />
Now reboot.<br />
<br />
{{Warning|If you do not properly export the zpool, the pool will refuse to import in the ramdisk environment and you will be stuck at the busybox terminal.}}<br />
<br />
=== Loading password from USB-Stick ===<br />
<br />
It is possible to store password on usb-stick and load it when booting:<br />
Save password on first bytes of usb-stick:<br />
# dd if=your_password_file bs=32 count=1 of=/dev/disk/by-id/usb_stick<br />
To create partition zfs partition you can either use previous described method with password prompt or pipe with [[dd]]:<br />
# dd if=/dev/disk/by-id/usb_stick bs=32 count=1 | zfs create -o encryption=on -o keyformat=passphrase zroot/ROOT<br />
Next step is modyfing zfs hook. By default zfs prompts for password. You have to change it to have it piped with dd from your pendrive. In order to do so modify /usr/lib/initcpio/hooks/zfs and change line:<br />
# ! eval zfs load-key "${encryptionroot}"; do<br />
to:<br />
# ! eval dd if=/dev/disk/by-id/usb_stick bs=32 count=1 | zfs load-key "${encryptionroot}"; do<br />
You are modifying your zfs hook so don't forget to regenerate your image using [[mkinitcpio]].<br />
Now zfs should load password from your usb-stick on boot.<br />
<br />
== Troubleshooting ==<br />
<br />
=== System fails to boot due to: cannot import zroot: no such pool available ===<br />
<br />
You can try the following steps and see if they can help.<br />
<br />
* Use the kernel modules from the [[Unofficial user repositories#archzfs|archzfs repo]] instead of the dkms version. You can go back to the dkms version after a sucessfull boot.<br />
* Remove the {{ic|/etc/zfs/zpool.cache}} and run:<br />
# zpool set cachefile=none zroot<br />
* Remove the {{ic|/etc/hostid}}.<br />
* Rebuild your initramfs.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/dajhorn/pkg-zfs/wiki/HOWTO-install-Ubuntu-to-a-Native-ZFS-Root-Filesystem HOWTO install Ubuntu to a Native ZFS Root]<br />
* [http://lildude.co.uk/zfs-cheatsheet ZFS cheatsheet]<br />
* [http://www.funtoo.org/wiki/ZFS_Install_Guide Funtoo ZFS install guide]<br />
* [https://kiljan.org/2018/09/23/a-reference-guide-to-zfs-on-arch-linux/ A reference guide to ZFS on Arch Linux]<br />
* [https://ramsdenj.com/2016/06/23/arch-linux-on-zfs-part-2-installation.html Arch Linux On Zfs ]<br />
* [https://www.youtube.com/watch?v=mLbtJQmfumI Youtube: Open-ZFS Bootcamp]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Mkosi&diff=649351Mkosi2021-01-21T03:09:21Z<p>Jstjohn: /* 2. Example: Using Config-files */ remove erroneous mkosi.default section "[Files]"</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Virtualization]]<br />
[[ja:Mkosi]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|systemd-nspawn}}<br />
{{Related|Linux Containers}}<br />
{{Related|Docker}}<br />
{{Related articles end}}<br />
<br />
'''[https://github.com/systemd/mkosi mkosi]''' stands for ''Make Operating System Image'', and is a tool for generating an OS tree or image that can be booted.<br />
<br />
== Installation ==<br />
Install {{Pkg|mkosi}} or {{Aur|mkosi-git}}. Depending on what Distribution you want to build install further packages:<br />
{| class="wikitable"<br />
! Distribution<br />
! Package<br />
|-<br />
| Arch<br />
| {{pkg|arch-install-scripts}}<br />
|-<br />
| Debian<br />
| {{pkg|debootstrap}}, {{pkg|debian-archive-keyring}}<br />
|-<br />
| Ubuntu<br />
| {{pkg|debootstrap}}, {{pkg|ubuntu-keyring}}<br />
|-<br />
| Fedora<br />
| {{aur|dnf}}<br />
|-<br />
| OpenSUSE<br />
| {{aur|zypper-git}}<br />
|-<br />
| CentOS<br />
| {{aur|dnf-legacy-utils}}<br />
|-<br />
|}<br />
<br />
== Basic usage ==<br />
You can create an image by calling mkosi as root<br />
# mkosi<br />
<br />
You can specify option as arguments or by editing files in the current folder.<br />
<br />
=== Example: Create and boot a Debian-Image ===<br />
The following command will create a bootable image with latest debian-version and the package {{Pkg|openssh-clients}} installed:<br />
$ mkosi -d debian -t gpt_ext4 -b --checksum --password password --package openssh-clients,vim -o image.raw<br />
<br />
you can boot it with [[systemd-nspawn]]:<br />
# systemd-nspawn -b -i image.raw<br />
<br />
or boot it virtualized with [[QEMU]] and <br />
$ qemu-system-x86_64 -m 512 -smp 2 -bios /usr/share/ovmf/x64/OVMF_CODE.fd -drive format=raw,file=image.raw<br />
<br />
You can also write this image to a USB drive and use it to boot your computer.<br />
<br />
=== 2. Example: Using Config-files ===<br />
The same image can be created by creating a configuration file:<br />
<br />
{{hc|mkosi.default|<nowiki><br />
[Distribution]<br />
Distribution=debian<br />
Release=stretch<br />
<br />
[Output]<br />
Format=gpt_ext4<br />
Bootable=yes<br />
Output=image.raw<br />
<br />
[Packages]<br />
Packages=<br />
openssh-client<br />
vim<br />
<br />
[Validation]<br />
Password=password<br />
<br />
</nowiki>}}<br />
<br />
{{tip|If you create a folder {{ic|mkosi.cache}} in current working directory, mkosi will save all downloaded packages there, so you can recreate images faster.}}<br />
<br />
=== Configurations ===<br />
Basic options can be specified as command-line arguments or in a file called {{ic|mkosi.default}} in your current directory.<br />
Most important options:<br />
{| class="wikitable" style="width:100%"<br />
! Argument<br />
! Option in mkosi.default<br />
! Description<br />
|-<br />
| -d<br />
| [Distribution]<br />
Distribution=<br />
| Which distribution should be installed: fedora,debian,ubuntu,arch,opensuse<br />
|-<br />
| -r<br />
| [Distribution]<br />
Release=<br />
| The version of the distribution: jessie, 21, …<br />
|-<br />
| -t<br />
| [Output]<br />
Format=<br />
| Format of the image to create:<br />
* '''gpt_ext4''': Image file with GPT partition table and [[ext4]] file system<br />
* '''gpt_btrfs''': Image file with GPT partition table and [[btrfs]] file system<br />
* '''gpt_squashfs''': Image file with GPT partition table and [[File_systems#Read-only_file_systems|squashfs]] file system<br />
* '''directory''': A plain directory<br />
* '''subvolume''': A btrfs subvolume<br />
* '''tar''': A tar-ball of a plain directory<br />
|-<br />
| -b<br />
| [Output]<br />
Bootable=yes<br />
| make the image bootable<br />
|-<br />
| --root-size<br />
| [Output]<br />
RootSize=<br />
| Size of the root file system<br />
|-<br />
| -p<br />
| [Packages]<br />
Packages=<br />
| List of packages to be installed into the image<br />
|-<br />
| -o<br />
| [Output]<br />
Output=<br />
| File/directory-Name<br />
|- <br />
| --password<br />
| [Validation]<br />
Password=test<br />
| Set the initial root password<br />
|}<br />
<br />
== See also ==<br />
* [https://github.com/systemd/mkosi Mkosi on Github]<br />
* [http://0pointer.net/blog/mkosi-a-tool-for-generating-os-images.html Longer introduction]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=User:Jstjohn&diff=649300User:Jstjohn2021-01-20T01:44:01Z<p>Jstjohn: state that i'm no longer an active maintainer</p>
<hr />
<div>__NOTOC__<br />
[[ArchWiki:Maintainers|Retired ArchWiki Maintainer]]<br />
<br />
== ArchWiki guidelines ==<br />
* [[Writing Article Overviews]]<br />
* [[Help:Style]]<br />
<br />
== ArchWiki suggestions ==<br />
* There should be increased spacing (approximately 1 extra line break's worth) between sections/headings to break them into better defined chunks.<br />
* Non-English ArchWiki pages should have their ArchWiki links be automatically "i18n"ed for the reader if an i18n version of the linked article exists. If the article doesn't exist, direct the reader to the English version of the article. For example, when <nowiki>[[Xorg]]</nowiki> is in the source of [[NVIDIA (Italiano)]], the link should automatically become <nowiki>[[Xorg (Italiano)|Xorg]]</nowiki> as long as the [[Xorg (Italiano)]] page exists.<br />
<br />
== Frequently used formatting ==<br />
Check the [[Special:MostLinkedTemplates|most linked templates]] or see below:<br />
<br />
=== Text box ===<br />
* [[Template:Note|<nowiki>{{Note|This message should be noted.}}</nowiki>]]<br />
* [[Template:Warning|<nowiki>{{Warning|This message should be heeded.}}</nowiki>]]<br />
* [[Template:Tip|<nowiki>{{Tip|This message should be considered.}}</nowiki>]]<br />
<br />
=== Text style ===<br />
* [[Template:ic|<nowiki>{{ic|Inline code}}</nowiki>]]<br />
* [[Template:bc|<nowiki>{{bc|Block code without header}}</nowiki>]]<br />
* [[Template:hc|<nowiki>{{hc|Block code with header}}</nowiki>]]<br />
* [[Template:Pkg|<nowiki>{{Pkg|package}}</nowiki>]]<br />
* [[Template:AUR|<nowiki>{{AUR|package}}</nowiki>]]<br />
<br />
=== Other ===<br />
* <nowiki>{{Dead link|yyyy|mm|dd}}</nowiki><br />
* <nowiki>{{bug|12345}}</nowiki><br />
* <nowiki>{{out of date}}</nowiki><br />
* <nowiki>{{remove}}</nowiki><br />
* <nowiki>{{translateme}}</nowiki><br />
* <nowiki>{{style}}</nowiki><br />
* <nowiki>{{lowercase title}}</nowiki><br />
* <nowiki>{{accuracy}}</nowiki><br />
* <nowiki>{{DISPLAYTITLE:foo bar}}</nowiki><br />
<br />
=== Special characters ===<br />
* Em dash: —<br />
* En dash: –<br />
* Ellipsis: …<br />
<br />
* Left arrow: ←<br />
* Right arrow: →<br />
* Up arrow: ↑<br />
* Down arrow: ↓<br />
<br />
== Miscellaneous ==<br />
=== ArchWiki ===<br />
* [[ArchWiki:Reports]]<br />
* [[ArchWiki:Requests]]<br />
* [[Help:Cheatsheet|ArchWiki Cheatsheet]]<br />
* [[Special:LinkSearch]]<br />
<br />
I also like to babysit some of the wireless and wired networking wiki articles, so if you notice a problem with one of them, I would be more than happy to help clean it up. :)<br />
<br />
<br />
{{Note|This layout was borrowed from [[User:Filam]].}}</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Mkosi&diff=649299Mkosi2021-01-20T01:42:37Z<p>Jstjohn: /* Basic usage */ minor style improvements</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Virtualization]]<br />
[[ja:Mkosi]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|systemd-nspawn}}<br />
{{Related|Linux Containers}}<br />
{{Related|Docker}}<br />
{{Related articles end}}<br />
<br />
'''[https://github.com/systemd/mkosi mkosi]''' stands for ''Make Operating System Image'', and is a tool for generating an OS tree or image that can be booted.<br />
<br />
== Installation ==<br />
Install {{Pkg|mkosi}} or {{Aur|mkosi-git}}. Depending on what Distribution you want to build install further packages:<br />
{| class="wikitable"<br />
! Distribution<br />
! Package<br />
|-<br />
| Arch<br />
| {{pkg|arch-install-scripts}}<br />
|-<br />
| Debian<br />
| {{pkg|debootstrap}}, {{pkg|debian-archive-keyring}}<br />
|-<br />
| Ubuntu<br />
| {{pkg|debootstrap}}, {{pkg|ubuntu-keyring}}<br />
|-<br />
| Fedora<br />
| {{aur|dnf}}<br />
|-<br />
| OpenSUSE<br />
| {{aur|zypper-git}}<br />
|-<br />
| CentOS<br />
| {{aur|dnf-legacy-utils}}<br />
|-<br />
|}<br />
<br />
== Basic usage ==<br />
You can create an image by calling mkosi as root<br />
# mkosi<br />
<br />
You can specify option as arguments or by editing files in the current folder.<br />
<br />
=== Example: Create and boot a Debian-Image ===<br />
The following command will create a bootable image with latest debian-version and the package {{Pkg|openssh-clients}} installed:<br />
$ mkosi -d debian -t gpt_ext4 -b --checksum --password password --package openssh-clients,vim -o image.raw<br />
<br />
you can boot it with [[systemd-nspawn]]:<br />
# systemd-nspawn -b -i image.raw<br />
<br />
or boot it virtualized with [[QEMU]] and <br />
$ qemu-system-x86_64 -m 512 -smp 2 -bios /usr/share/ovmf/x64/OVMF_CODE.fd -drive format=raw,file=image.raw<br />
<br />
You can also write this image to a USB drive and use it to boot your computer.<br />
<br />
=== 2. Example: Using Config-files ===<br />
The same image can be created by creating a configuration file:<br />
<br />
{{hc|mkosi.default|<nowiki><br />
[Files]<br />
[Distribution]<br />
Distribution=debian<br />
Release=stretch<br />
<br />
[Output]<br />
Format=gpt_ext4<br />
Bootable=yes<br />
Output=image.raw<br />
<br />
[Packages]<br />
Packages=<br />
openssh-client<br />
vim<br />
<br />
[Validation]<br />
Password=password<br />
<br />
</nowiki>}}<br />
<br />
{{tip|If you create a folder {{ic|mkosi.cache}} in current working directory, mkosi will save all downloaded packages there, so you can recreate images faster.}}<br />
<br />
=== Configurations ===<br />
Basic options can be specified as command-line arguments or in a file called {{ic|mkosi.default}} in your current directory.<br />
Most important options:<br />
{| class="wikitable" style="width:100%"<br />
! Argument<br />
! Option in mkosi.default<br />
! Description<br />
|-<br />
| -d<br />
| [Distribution]<br />
Distribution=<br />
| Which distribution should be installed: fedora,debian,ubuntu,arch,opensuse<br />
|-<br />
| -r<br />
| [Distribution]<br />
Release=<br />
| The version of the distribution: jessie, 21, …<br />
|-<br />
| -t<br />
| [Output]<br />
Format=<br />
| Format of the image to create:<br />
* '''gpt_ext4''': Image file with GPT partition table and [[ext4]] file system<br />
* '''gpt_btrfs''': Image file with GPT partition table and [[btrfs]] file system<br />
* '''gpt_squashfs''': Image file with GPT partition table and [[File_systems#Read-only_file_systems|squashfs]] file system<br />
* '''directory''': A plain directory<br />
* '''subvolume''': A btrfs subvolume<br />
* '''tar''': A tar-ball of a plain directory<br />
|-<br />
| -b<br />
| [Output]<br />
Bootable=yes<br />
| make the image bootable<br />
|-<br />
| --root-size<br />
| [Output]<br />
RootSize=<br />
| Size of the root file system<br />
|-<br />
| -p<br />
| [Packages]<br />
Packages=<br />
| List of packages to be installed into the image<br />
|-<br />
| -o<br />
| [Output]<br />
Output=<br />
| File/directory-Name<br />
|- <br />
| --password<br />
| [Validation]<br />
Password=test<br />
| Set the initial root password<br />
|}<br />
<br />
== See also ==<br />
* [https://github.com/systemd/mkosi Mkosi on Github]<br />
* [http://0pointer.net/blog/mkosi-a-tool-for-generating-os-images.html Longer introduction]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Autofs&diff=649297Autofs2021-01-20T00:33:51Z<p>Jstjohn: /* NFS network mounts */ some formatting and style improvements</p>
<hr />
<div>[[Category:File systems]]<br />
[[es:Autofs]]<br />
[[it:Autofs]]<br />
[[ja:Autofs]]<br />
[[ru:Autofs]]<br />
[[zh-hans:Autofs]]<br />
AutoFS provides automounting of removable media or network shares when they are inserted or accessed.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|autofs}} package.<br />
<br />
{{Note|You no longer need to load {{ic|autofs4}} module.}}<br />
<br />
== Configuration ==<br />
<br />
AutoFS uses template files for configuration which are located in {{ic|/etc/autofs}} The main template is called {{ic|auto.master}}, which can point to one or more other templates for specific media types.<br />
<br />
* Open the file {{ic|/etc/autofs/auto.master}} with your favorite editor, you will see something similar to this:<br />
<br />
{{hc|/etc/autofs/auto.master|2=<br />
#/media /etc/autofs/auto.media<br />
<br />
}}<br />
<br />
The first value on each line determines the base directory under which all the media in a template are mounted, the second value is which template to use. The default base path is {{ic|/media}}, but you can change this to any other location you prefer. For instance:<br />
<br />
{{hc|/etc/autofs/auto.master|2=<br />
/media/misc /etc/autofs/auto.misc --timeout=5<br />
/media/net /etc/autofs/auto.net --timeout=60<br />
<br />
}}<br />
{{Note|Make sure there is an empty line on the end of template files (press {{ic|ENTER}} after last word). If there is no correct EOF (end of file) line, the AutoFS daemon will not properly load.}}<br />
<br />
The optional parameter {{ic|timeout}} sets the amount of seconds after which to unmount directories.<br />
<br />
The base directory will be created if it does not exist on your system. The base directory will be mounted on to load the dynamically loaded media, which means any content in the base directory will not be accessible while autofs is on. This procedure is however non-destructive, so if you accidentally automount into a live directory you can just change the location in {{ic|auto.master}} and restart AutoFS to regain the original contents.<br />
<br />
If you still want to automount to a target non-empty directory and want to have the original files available even after the dynamically loaded directories are mounted, you can use autofs to mount them to another directory (e.g. /var/autofs/net) and create soft links.<br />
<br />
# ln -s /var/autofs/net/share_name /media/share_name<br />
<br />
Alternatively, you can have autofs mount your media to a specific folder, rather than inside a common folder.<br />
<br />
{{hc|/etc/autofs/auto.master|2=<br />
/- /etc/autofs/auto.template<br />
}}<br />
{{hc|/etc/autofs/auto.template|2=<br />
/path/to/folder -options :/device/path<br />
/home/user/usbstick -fstype=auto,async,nodev,nosuid,umask=000 :/dev/sdb1<br />
}}<br />
{{Note|This can cause problems with resources getting locked if the connection to the share is lost. When trying to access the folder, programs will get locked into waiting for a response, and either the connection has to be restored or the process has to be forcibly killed before unmounting is possible. To mitigate this, only use if you will always be connected to the share, and do not use your home folder or other commonly used folders lest your file browser reads ahead into the disconnected folder}}<br />
<br />
* Open the file {{ic|/etc/nsswitch.conf}} and add an entry for automount:<br />
automount: files<br />
<br />
* When you are done configuring your templates (see below), launch the AutoFS daemon as root by [[enabling]] and starting the {{ic|autofs.service}}.<br />
<br />
Devices are now automatically mounted when they are accessed, they will remain mounted as long as you access them.<br />
<br />
=== Removable media ===<br />
<br />
Removable devices are assigned block device locations according to the next available spot, e.g. if {{ic|/dev/sd{a,b,c} }} are already occupied, the next removable media will be given block {{ic|/dev/sdd}}. Instead of assigning a mount point based on an unreliable block device path, a more robust approach is to use the UUID or PARTUUID of the removable media as the location in the map file.<br />
<br />
For example, to mount a specific USB drive to the path {{ic|/mnt/black}}, configure the template file and map file:<br />
{{hc|/etc/autofs/auto.master|2=<br />
# master template file<br />
/mnt /etc/autofs/auto.mnt # [options here]<br />
<br />
}}<br />
<br />
Use {{ic|blkid}} to find the UUID of the partition to mount, then generate the map file:<br />
<nowiki># _ID=$( blkid --output value --match-tag PARTUUID /dev/sd</nowiki>''XY'' )<br />
# printf "%s %s\n" "black -fstype=auto :PARTUUID=" "${_ID}" >/etc/autofs/auto.mnt<br />
<br />
<br />
<br />
=== NFS network mounts ===<br />
<br />
{{Style|"New" compared to what? In what way?; don't show systemctl start; formatting cleanup}}<br />
<br />
AutoFS provides a new way of automatically discovering and mounting [[NFS]]-shares on remote servers (the AutoFS network template in {{ic|/etc/autofs/auto.net}} has been removed in autofs5). To enable automatic discovery and mounting of network shares from all accessible servers without any further configuration, you will need to add the following to the {{ic|/etc/autofs/auto.master}} file:<br />
<br />
/net -hosts --timeout=60<br />
<br />
{{Note|Each host name needs to be resolveable, e.g. the name and IP address in {{ic|/etc/hosts}} or via [[Wikipedia:Domain_Name_System|DNS]] and make sure you have {{Pkg|nfs-utils}} installed and configured. You also have to [[enable]] {{ic|rpcbind}} to browse shared directories.}}<br />
<br />
For instance, if you have a remote server ''fileserver'' (the name of the directory is the hostname of the server) with an NFS share named {{ic|/home/share}}, you can just access the share by typing:<br />
<br />
# cd /net/fileserver/home/share<br />
<br />
{{Note|Please note that ''ghosting'' (i.e. automatically creating directory placeholders before mounting shares) is enabled by default; although, AutoFS installation notes claim to remove that option from {{ic|/etc/conf.d/autofs}} in order to start the AutoFS daemon.}}<br />
<br />
The {{ic|-hosts}} option uses a similar mechanism as the {{ic|showmount}} command to detect remote shares. You can see the exported shares by typing:<br />
<br />
# showmount <servername> -e <br />
<br />
Replacing ''<servername>'' with the name of your own server.<br />
<br />
==== Manual NFS configuration ====<br />
To mount a NFS share on server_name called {{ic|/srv/shared_dir}} to another computer named {{ic|client_pc}} at location {{ic|/mnt/foo}}, edit {{ic|auto.master}} and create a configuration file for the share (auto.server_name):<br />
{{hc|<nowiki>/etc/autofs/auto.master</nowiki>|<nowiki>/mnt /etc/autofs/auto.server_name --timeout 60</nowiki>}}<br />
{{hc|<nowiki>/etc/autofs/auto.server_name</nowiki>|<nowiki>foo -rw,soft,intr,rsize=8192,wsize=8192 server_name:/srv/shared_dir</nowiki>}}<br />
<br />
=== Samba ===<br />
<br />
==== Single shares ====<br />
<br />
Add the following to {{ic|/etc/autofs/auto.master}}:<br />
/media/[my_server] /etc/autofs/auto.[my_server] --timeout 60 --browse<br />
where {{ic|--timeout}} defines how many seconds to wait before the file system is unmounted. The {{ic|--browse}} option creates empty folders for each mount-point in the file in order to prevent timeouts, if a network share cannot be contacted. <br />
<br />
Next create a file {{ic|/etc/autofs/auto.[my_server]}}<br />
[any_name] -fstype=cifs,[other_options] ://[remote_server]/[remote_share_name]<br />
<br />
You can specify a user name and password to use with the share in the {{ic|other_options}} section:<br />
[any_name] -fstype=cifs,username=[username],password=[password],[other_options] ://[remote_server]/[remote_share_name]<br />
<br />
{{Note|Escape &#36;, and other characters, with a backslash when neccessary.}}<br />
<br />
==== Multiple shares ====<br />
<br />
You may be specify multiple shares in the {{ic|/etc/autofs/auto.[my_server]}}, for instance:<br />
<br />
[any_name] -fstype=cifs,[other_options] /photos ://[remote_server]/photos /music ://[remote_server]/music /video ://[remote_server]/video<br />
<br />
==== Auto discovery ====<br />
<br />
See the comments in {{ic|/etc/autofs/auto.smb}}.<br />
<br />
=== FTP and SSH (with FUSE) ===<br />
<br />
Remote FTP and [[SSH]] servers can be accessed seamlessly with AutoFS using [[Wikipedia:Filesystem in Userspace|FUSE]], a virtual file system layer. <br />
<br />
==== Remote FTP ====<br />
<br />
First, install the {{Pkg|curlftpfs}} package.<br />
Load the '''fuse''' module:<br />
<br />
# modprobe fuse<br />
<br />
Create a {{ic|/etc/modules-load.d/fuse.conf}} file containg {{ic|fuse}} to load it on each system boot.<br />
<br />
Next, add a new entry for FTP servers in {{ic|/etc/autofs/auto.master}}:<br />
<br />
/media/ftp /etc/autofs/auto.ftp --timeout=60<br />
<br />
Create the file {{ic|/etc/autofs/auto.ftp}} and add a server using the {{ic|ftp://myuser:mypassword@host:port/path}} format:<br />
<br />
servername -fstype=curl,rw,allow_other,nodev,nonempty,noatime :ftp\://myuser\:mypassword\@remoteserver<br />
<br />
{{Note| Your passwords are plainly visible for anyone that can run {{ic|df}} (only for mounted servers) or view the file {{ic|/etc/autofs/auto.ftp}}.}}<br />
If you want slightly more security you can create the file {{ic|~root/.netrc}} and add the passwords there. <br />
Passwords are still plain text, but you can have mode 600, and {{ic|df}} command will not show them (mounted or not).<br />
This method is also less sensitive to special characters (that else must be escaped) in the passwords. The format is:<br />
<br />
machine remoteserver <br />
login myuser<br />
password mypassword<br />
<br />
The line in {{ic|/etc/autofs/auto.ftp}} looks like this without user and password:<br />
<br />
servername -fstype=curl,allow_other :ftp\://remoteserver<br />
<br />
Create the file {{ic|/sbin/mount.curl}} with this code:<br />
<br />
{{hc|/sbin/mount.curl|<nowiki><br />
#! /bin/sh<br />
curlftpfs $1 $2 -o $4,disable_eprt<br />
</nowiki>}}<br />
<br />
Create the file {{ic|/sbin/umount.curl}} with this code:<br />
<br />
{{hc|/sbin/umount.curl|<nowiki><br />
#! /bin/sh<br />
fusermount -u $1<br />
</nowiki>}}<br />
<br />
Set the permissions for both files:<br />
<br />
# chmod 755 /sbin/mount.curl<br />
# chmod 755 /sbin/umount.curl<br />
<br />
After a restart your new FTP server should be accessible through {{ic|/media/ftp/servername}}.<br />
<br />
==== Remote SSH ====<br />
<br />
{{Accuracy|1=All the ''ssh*'' commands should be executed as the same user, as before [https://wiki.archlinux.org/index.php?title=Autofs&diff=prev&oldid=318335 this edit]. It should not matter if it is root or unprivileged.}}<br />
<br />
These are basic instructions to access a remote filesystem over [[SSH]] with AutoFS. <br />
<br />
{{Note|Password-less authentication may be convenient but also has security implications. See [[Using SSH Keys|SSH keypair]] for more details}}<br />
<br />
Install the {{Pkg|sshfs}} package.<br />
<br />
Load the {{ic|fuse}} module:<br />
<br />
# modprobe fuse<br />
<br />
Create a {{ic|/etc/modules-load.d/fuse.conf}} file containg {{ic|fuse}} to load it on each system boot if you have not one yet.<br />
<br />
Install {{Pkg|openssh}}.<br />
<br />
Generate an [[Using SSH Keys|SSH keypair]]:<br />
$ ssh-keygen<br />
<br />
When the generator ask for a passphrase, just press {{ic|ENTER}}. Using SSH keys without a passphrase is less secure, yet running AutoFS together with passphrases poses some additional difficulties which are not (yet) covered in this article. <br />
<br />
Next, copy the public key to the remote SSH server:<br />
$ ssh-copy-id username@remotehost<br />
<br />
'''As root''', see that you can login to the remote server:<br />
# ssh username@remotehost<br />
<br />
{{Note|This will add the remote server to root's list of {{ic|known_hosts}}. Hosts can be also be manually added to {{ic|/etc/ssh/ssh_known_hosts}}.}}<br />
<br />
Create a new entry for SSH servers in {{ic|/etc/autofs/auto.master}}:<br />
/media/ssh /etc/autofs/auto.ssh --timeout=60<br />
<br />
Create the file {{ic|/etc/autofs/auto.ssh}} and add an SSH server:<br />
{{hc|/etc/autofs/auto.ssh|2=<br />
servername -fstype=fuse,rw,allow_other,IdentityFile=/home/username/.ssh/id_rsa :sshfs\#username@host\:/<br />
}}<br />
<br />
After a restart your SSH server should be accessible through {{ic|/media/ssh/servername}}.<br />
<br />
== MTP ==<br />
<br />
Media Transfer Protocol ([[MTP]]) is used in some Android devices.<br />
<br />
Install the {{Pkg|mtpfs}} package.<br />
<br />
Create a new entry for MTP Device in {{ic|/etc/autofs/auto.misc}}:<br />
android -fstype=fuse,allow_other,umask=000 :mtpfs<br />
<br />
== Troubleshooting and tweaks ==<br />
<br />
This section contains a few solutions for common issues with AutoFS.<br />
<br />
=== Using NIS ===<br />
<br />
Version 5.0.5 of AutoFS has more advanced support for [[NIS]]. To use AutoFS together with NIS, add {{ic|yp:}} in front of the template names in {{ic|/etc/autofs/auto.master}}:<br />
<br />
/home yp:auto_home --timeout=60 <br />
/sbtn yp:auto_sbtn --timeout=60<br />
+auto.master<br />
<br />
On earlier versions of NIS (before 5.0.4), you should add {{ic|nis}} to {{ic|/etc/nsswitch.conf}}:<br />
automount: files nis<br />
<br />
=== Optional parameters ===<br />
<br />
You can set parameters like {{ic|timeout}} systemwide for all AutoFS media in {{ic|/etc/default/autofs}}:<br />
<br />
* Open the {{ic|/etc/default/autofs}} file and edit the {{ic|OPTIONS}} line:<br />
OPTIONS='--timeout=5'<br />
<br />
* To enable logging (default is no logging at all), uncomment and add {{ic|--verbose}} to the {{ic|OPTIONS}} line in {{ic|/etc/default/autofs}} e.g.:<br />
OPTIONS='--verbose --timeout=5'<br />
<br />
After restarting the {{ic|autofs}} daemon, verbose output is visible in {{ic|systemctl status}} or in {{ic|journalctl}}.<br />
<br />
=== Identify multiple devices ===<br />
<br />
If you use multiple USB drives/sticks and want to easily tell them apart, you can use AutoFS to set up the mount points and [[Udev]] to create distinct names for your USB drives. See [[udev#Setting static device names]] for instructions on setting up Udev rules.<br />
<br />
=== AutoFS permissions ===<br />
<br />
If AutoFS is not working for you, make sure that the permissions of the templates files are correct, otherwise AutoFS will not start. This may happen if you backed up your configuration files in a manner which did not preserve file modes. Here are what the modes should be on the configuration files:<br />
<br />
*0644 - /etc/autofs/auto.master<br />
*0644 - /etc/autofs/auto.media<br />
*0644 - /etc/autofs/auto.misc<br />
*0644 - /etc/conf.d/autofs<br />
<br />
In general, scripts (like previous {{ic|auto.net}}) should have executable ({{ic|chmod a+x filename}}) bits set and lists of mounts should not.<br />
<br />
If you are getting errors in {{ic|/var/log/daemon.log}} similar to this, you have a permissions problem:<br />
<br />
May 7 19:44:16 peterix automount[15218]: lookup(program): lookup for petr failed<br />
May 7 19:44:16 peterix automount[15218]: failed to mount /media/cifs/petr<br />
<br />
=== fusermount problems ===<br />
With certain versions of util-linux, you may not be able to unmount a fuse file system drive mounted by autofs, even if you use the "user=" option. See the discussion here:<br />
http://fuse.996288.n3.nabble.com/Cannot-umount-as-non-root-user-anymore-tp689p697.html<br />
<br />
=== Debugging auto mount issues ===<br />
For better debugging you might try running automount in foreground.<br />
<br />
# systemctl stop autofs.service<br />
# automount -f -v<br />
<br />
Of if you want more debug info than try:<br />
# automount -f --debug<br />
<br />
== Alternatives to AutoFS ==<br />
<br />
* [[Systemd]] can automount filesystems upon demand; see [[Fstab#Automount_with_systemd|here]] for the description and the article on [[SSHFS#On demand|sshfs]] for an example.<br />
* [[Thunar Volume Manager]] is an automount system for users of the [[Thunar]] file manager.<br />
* [[PCManFM]] is a lightweight file manager with built-in support for accessing remote shares<br />
* [[Udisks]] is a minimalistic automatic disk mounting service<br />
<br />
== See also ==<br />
<br />
* FTP and SFTP usage with AutoFS is based on this Gentoo Wiki article: https://web.archive.org/web/20130414074212/http://en.gentoo-wiki.com/wiki/Mounting_SFTP_and_FTP_shares<br />
* More information on SSH can be found on the [[SSH]] and [[Using SSH Keys]] pages of this wiki.<br />
* Ubuntu's Autofs help wiki is at https://help.ubuntu.com/community/Autofs<br />
* For filesystem specific mount options check http://manpages.ubuntu.com/manpages/focal/man8/mount.8.html#filesystem-specific%20mount%20options<br />
* For fuse specific mount options check http://manpages.ubuntu.com/manpages/precise/man8/mount.fuse.8.html</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Cinnamon&diff=364862Cinnamon2015-03-10T05:19:41Z<p>Jstjohn: /* Video tearing */ add template</p>
<hr />
<div>[[Category:Desktop environments]]<br />
[[ja:Cinnamon]]<br />
[[ru:Cinnamon]]<br />
[[zh-CN:Cinnamon]]<br />
[[tr:Cinnamon_Masaüstü_Ortamı]]<br />
{{Related articles start}}<br />
{{Related|Nemo}}<br />
{{Related|GNOME}}<br />
{{Related|MATE}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related articles end}}<br />
<br />
[http://cinnamon.linuxmint.com/ Cinnamon] is a [[desktop environment]] which provides advanced innovative features and a traditional user experience. <br />
The desktop layout is similar to GNOME Panel (GNOME 2); however, the underlying technology was forked from GNOME Shell (GNOME 3).<br />
The emphasis is put on making users feel at home and providing them with an easy to use and comfortable desktop experience. As of version 2.0, Cinnamon is a complete desktop environment and not merely a frontend for GNOME like GNOME Shell and Unity.<br />
<br />
== Installation ==<br />
<br />
Cinnamon can be [[Pacman|installed]] with the package {{Pkg|cinnamon}}, available in the [[official repositories]].<br />
<br />
== Starting Cinnamon ==<br />
<br />
=== Graphical log-in ===<br />
<br />
Choose ''Cinnamon'' or ''Cinnamon (Software Rendering)'' from the menu in a [[display manager]] of choice. Cinnamon is the 3D accelerated version, which should normally be used. If you experience problems with your video driver (e.g. artifacts or crashing), try the ''Cinnamon (Software Rendering)'' session, which disables 3D acceleration.<br />
<br />
=== Starting Cinnamon manually ===<br />
<br />
If you prefer to start Cinnamon manually from the console, add the following line to [[Xinitrc]] (cinnamon 1.9 and up):<br />
<br />
{{hc|~/.xinitrc|<br />
exec cinnamon-session<br />
}}<br />
<br />
If the ''Cinnamon (Software Rendering)'' session is required, use {{ic|cinnamon-session-cinnamon2d}} instead of {{ic|cinnamon-session}}.<br />
<br />
== Configuration ==<br />
<br />
Cinnamon is quite easy to configure &mdash; a lot of the configuration that most people will want can be done graphically. Its usability can be customized with [http://cinnamon-spices.linuxmint.com/applets applets] and [http://cinnamon-spices.linuxmint.com/extensions extensions], and also it supports [http://cinnamon-spices.linuxmint.com/themes theming]. <br />
<br />
=== Cinnamon settings ===<br />
<br />
''cinnamon-settings'' launches a settings module specified on the command line. Without (correct) arguments, it launches ''System Settings''. For example, to start the panel settings:<br />
<br />
$ cinnamon-settings panel<br />
<br />
To list all available modules:<br />
<br />
$ pacman -Ql cinnamon | grep -o "cs_.*\.py" | awk -F'[_.]' '{ print $2 }'<br />
<br />
==== Networking ====<br />
<br />
To add support for the networking module, enable [[NetworkManager#Configuration|Network Manager]]. In order for NetworkManager to store Wi-Fi passwords, you will need to also install [[GNOME Keyring]].<br />
<br />
==== Bluetooth ====<br />
<br />
{{warning|{{AUR|cinnamon-bluetooth}} is incompatible with GNOME 3.10 and above. See the [[Bluetooth]] article for alternatives.}}<br />
<br />
A GNOME bluetooth frontend for Cinnamon Panel and Cinnamon Settings is available in the AUR under the name {{AUR|cinnamon-bluetooth}}. However, as of 18th November 2014 neither of the cinnamon-bluetooth packages currently build or work properly.<br />
<br />
=== Applets and extensions ===<br />
<br />
While an '''applet''' is an addition to the Cinnamon panel, an '''extension''' can fully change the Cinnamon experience. They can be installed from the [[AUR]], ([https://aur.archlinux.org/packages.php?O=0&K=cinnamon-&do_Search=Go package search]), or from inside Cinnamon (''Get more online''):<br />
<br />
$ cinnamon-settings applets<br />
$ cinnamon-settings extensions<br />
<br />
Alternatively, install manually from [http://cinnamon-spices.linuxmint.com/ Cinnamon spices].<br />
<br />
{{Note|If applets do not appear, restart Cinnamon with {{ic|r}} in the {{ic|Alt+F2}} dialog box.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Creating custom applets/themes ===<br />
<br />
The official tutorial on creating an '''applet''' can be found [http://cinnamon.linuxmint.com/?p=156 here], and on creating a '''custom theme''' can be found [http://cinnamon.linuxmint.com/?p=144 here].<br />
<br />
=== Default desktop background wallpaper path ===<br />
<br />
When you add a wallpaper from a custom path in Cinnamon Settings, Cinnamon copies it to {{ic|~/.cinnamon/backgrounds}}. Thus, with every change of your wallpaper you would have to add your updated wallpaper again from the settings menu or copy / symlink it manually to {{ic|~/.cinnamon/backgrounds}}.<br />
<br />
=== Show home, filesystem desktop icons ===<br />
<br />
By default Cinnamon starts with desktop icons enabled but with no desktop icons on screen. To show desktop icons for the home folder, the filesystem, the trash, mounted volumes and network servers open Cinnamon settings and click on desktop. Enable the checkboxes of the icons you want to see on screen.<br />
<br />
=== Adding custom command launchers to the Menu applet ===<br />
<br />
The Menu applet supports launching custom commands. Right click on the applet, click on ''Configure...'' and then ''Open the menu editor''. Select a sub-menu (or create a new one) and select ''New Item''. Set ''Name'', ''Command'' and ''Comment''. Check the launch in terminal checkbox if needed. Leave unchecked for graphical applications. Click ''OK'' and close the menu editor afterwards. The launcher is added to the menu.<br />
<br />
=== Workspaces ===<br />
<br />
A workspace pager can be added to the panel. Right click the panel and choose the option ''Add applets to the panel''. Add the ''Workspace switch'' applet to the panel. To change its position right click on the panel and change the ''Panel edit mode'' on/off switch to on. Click and drag the switcher to the desired position and turn the panel edit mode off when finished.<br />
<br />
By default there are 2 workspaces. To add more, hit {{ic|Control+Alt+Up}} to show all workspaces. Then click on the plus sign button on the right of the screen to add more workspaces.<br />
<br />
Alternatively, you can choose the number by command-line:<br />
$ gsettings set org.cinnamon number-workspaces 4<br />
Replacing 4 with the number of workspaces you want. To apply the change you need to reboot Cinnamon (for example : Alt-F2 and command r).<br />
<br />
=== Hide desktop icons ===<br />
<br />
The desktop icons rendering feature is enabled in nemo by default. To disable this feature, change the setting with the following command: <br />
<br />
$ gsettings set org.nemo.desktop show-desktop-icons false<br />
<br />
=== GTK themes and icons ===<br />
<br />
Linux Mint styled themes and icons can be installed from AUR using packages {{AUR|mint-themes}} and {{AUR|mint-x-icons}}. The themes can be edited in {{ic|Settings → Themes → Other settings}}.<br />
<br />
=== Resize windows by mouse ===<br />
<br />
To resize windows with {{ic|Alt+Right click}}, use {{ic|gsettings}}:<br />
<br />
gsettings set org.cinnamon.desktop.wm.preferences resize-with-right-button true<br />
<br />
=== Portable keybindings ===<br />
<br />
To export your keyboard shortcut keys, you should do:<br />
<br />
dconf dump /org/cinnamon/muffin/keybindings/ >keybindings-backup.dconf<br />
<br />
To later import it (for example) on another computer, do:<br />
<br />
dconf load /org/cinnamon/muffin/keybindings/ <keybindings-backup.dconf<br />
<br />
== Troubleshooting ==<br />
<br />
=== QGtkStyle unable to detect the current theme ===<br />
<br />
Installing {{Pkg|libgnome-data}} solves the problem partially, and QGtkStyle will detect the current GTK+ theme. However, to set the same icon and cursor theme, users must specify them explicitly.<br />
<br />
The icon theme for Qt apps can be configured by the following command:<br />
<br />
$ gconftool-2 --set --type string /desktop/gnome/interface/icon_theme Faenza-Dark<br />
<br />
This sets the icon theme to Faenza-Dark located in {{ic|/usr/share/icons/Faenza-Dark}}. <br />
<br />
The cursor theme for Qt apps can be selected by creating a symbolic link:<br />
<br />
$ mkdir ~/.icons<br />
$ ln -s /usr/share/icons/Adwaita ~/.icons/default<br />
<br />
This sets the cursor theme to Adwaita located in {{ic|/usr/share/icons/Adwaita}}.<br />
<br />
=== Pressing power buttons suspend the system ===<br />
<br />
This is the default behaviour. To change the setting open the {{ic|cinnamon-settings}} panel and click on the "Power Management" option. Change the "When the power button is pressed" option to your desired behaviour.<br />
<br />
=== Volume level is not saved ===<br />
<br />
The volume level is not be saved after reboot. The volume will be at 0 but not muted. Installing {{Pkg|alsa-utils}} will solve the problem.<br />
<br />
=== cinnamon-settings: No module named Image ===<br />
<br />
If {{ic|cinnamon-settings}} does not start with the message that it cannot find a certain module, e.g. the Image module, it is likely that it uses outdated compiled files which refer to no longer existing file locations. In this case remove all {{ic|*.pyc}} files in {{ic|/usr/lib/cinnamon-settings}} and its sub-folders.<br />
<br />
=== Cannot add/remove/change languages used in Cinnamon ===<br />
<br />
The language module was removed from the Cinnamon Control Panel with the release of Cinnamon 2.2 and provided a new package for changing the language settings.<br />
<br />
'''To add/remove languages''', see [[Locale]].<br />
<br />
'''To change between enabled languages''', install the {{AUR|mintlocale}} package.<br />
<br />
=== Video tearing ===<br />
<br />
If you experience video tearing while playing videos or games under Cinnamon, you should add the following lines to the end of {{ic|/etc/environment}}:<br />
<br />
CLUTTER_PAINT=disable-clipped-redraws:disable-culling<br />
CLUTTER_VBLANK=True<br />
<br />
After rebooting, you should have much smoother video under Cinnamon.</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Improve_pacman_performance&diff=364861Improve pacman performance2015-03-10T05:04:47Z<p>Jstjohn: /* pacget (aria2) mirror script */ add templates and improve wording</p>
<hr />
<div>[[Category:Package management]]<br />
[[de:Pacman beschleunigen]]<br />
[[es:Improve Pacman Performance]]<br />
[[fr:Ameliorer Pacman]]<br />
[[it:Improve Pacman Performance]]<br />
[[ja:Pacman のパフォーマンスの向上]]<br />
[[ru:Improve Pacman Performance]]<br />
[[tr:Pacman_verimini_arttırmak]]<br />
[[zh-CN:Improve Pacman Performance]]<br />
[[zh-TW:Improve Pacman Performance]]<br />
== Improving database access speeds ==<br />
<br />
Pacman stores all package information in a collection of small files, one for each package. Improving database access speeds reduces the time taken in database-related tasks, e.g. searching packages and resolving package dependencies. The safest and easiest method is to run as root:<br />
<br />
# pacman-optimize<br />
<br />
This will attempt to put all the small files together in one (physical) location on the hard disk so that the hard disk head does not have to move so much when accessing all the data. This method is safe, but is not foolproof: it depends on your filesystem, disk usage and empty space fragmentation. Another, more aggressive, option would be to first remove uninstalled packages from cache and to remove unused repositories before database optimization:<br />
<br />
# pacman -Sc && pacman-optimize<br />
<br />
For those who regularly optimize database place command in cron or use a [[systemd/Timers|systemd timer]] provided by the {{AUR|systemd-timer-pacman-optimize-git}} package.<br />
<br />
== Improving 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 />
Pacman's speed in downloading packages can be improved by using a different application to download packages instead of Pacman'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 />
=== Using Powerpill ===<br />
<br />
Powerpill is a full wrapper for Pacman that uses parallel and segmented downloads to speed up the download process. Normally Pacman will download one package at a time, waiting for it to complete before beginning the next download. Powerpill takes a different approach: it tries to download as many packages as possible at once.<br />
<br />
The [[Powerpill | Powerpill wiki page]] provides basic configuration and usage examples along with package and upstream links.<br />
<br />
=== Using wget ===<br />
<br />
This is also very handy if you need more powerful proxy settings than pacman's built-in capabilities. <br />
<br />
To use {{ic|wget}}, first install it with {{ic|pacman -S wget}} and then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget -c --passive-ftp -c %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 />
=== Using 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'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 the [[Improve pacman performance#Using_Powerpill | powerpill]] section above.}}<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 -c --file-allocation=none --log-level=error -m2 -x2 --max-file-not-found=5 -k5M --no-conf -Rtrue --summary-interval=60 -t5 -d / -o %o %u<br />
<br />
{{Tip|1=<nowiki></nowiki><br />
* Using this XferCommand gives less useful, but much more readable, output:<br />
:{{bc|<nowiki>XferCommand = /usr/bin/printf 'Downloading ' && echo %u | awk -F/ '{printf $NF}' && printf '...' && /usr/bin/aria2c -q --allow-overwrite=true -c --file-allocation=none --log-level=error -m2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=0 -t5 -d / -o %o %u && echo ' Complete!'</nowiki>}}<br />
<br />
* [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 />
Option details:<br />
<br />
{{ic|/usr/bin/aria2c}}<br />
:The full PATH to the aria2 executable.<br />
<br />
{{ic|1=--allow-overwrite=true}}<br />
:Restart download if a corresponding control file does not exist. (Default: false)<br />
<br />
{{ic|-c, --continue}}<br />
:Continue downloading a partially downloaded file if a corresponding control file exists.<br />
<br />
{{ic|1=--file-allocation=none}}<br />
:Do not pre-allocate file space before download begins. (Default: prealloc)<br />
:{{ic|1=--file-allocation=falloc}} is recommended for newer file systems such as ext4 (with extents support), btrfs or xfs as it allocates large files (GB) almost instantly. Do not use falloc with legacy file systems such as ext3 as prealloc consumes approximately the same amount of time as standard allocation would while locking the aria2 process from proceeding to download.<br />
<br />
{{ic|1=--log-level=error}}<br />
:Set log level to output errors only. (Default: debug)<br />
<br />
{{ic|1=-m2, --max-tries=2}}<br />
:Make 2 maximum attempts to download specified file(s) per mirror. (Default: 5)<br />
<br />
{{ic|1=-x2, --max-connection-per-server=2}}<br />
:Set a maximum of 2 connections to each mirror per file. (Default: 1)<br />
<br />
{{ic|1=--max-file-not-found=5}}<br />
:Force download to fail if a single byte is not received within 5 attempts. (Default: 0)<br />
<br />
{{ic|1=-k5M, --min-split-size=5M}}<br />
:Only split the file if the size is larger than 2;5MB = 10MB. (Default: 20M)<br />
<br />
{{ic|--no-conf}}<br />
:Disable loading an {{ic|aria2.conf}} file if it exists. (Default: {{ic|~/.aria2/aria2.conf}})<br />
<br />
{{ic|1=-Rtrue, --remote-time=true}}<br />
:Apply timestamps of the remote file(s) and apply them to the local file(s). (Default: false)<br />
<br />
{{ic|1=--summary-interval=60}}<br />
:Output download progress summary every 60 seconds. (Default: 60)<br />
:{{ic|1=--summary-interval=0}} supresses download progress summary output and may improve overall performance. Logs will continue to be output according to the value specified in the {{Ic|log-level}} option.<br />
<br />
{{ic|1=-t5, --timeout=5}}<br />
:Set a 5 second timeout per mirror after a connection is established. (Default: 60)<br />
<br />
{{ic|-d, --dir}}<br />
:The directory to store the downloaded file(s) as specified by [[pacman]].<br />
<br />
{{ic|-o, --out}}<br />
:The output file name(s) of the downloaded file(s). <br />
<br />
{{ic|%o}}<br />
:Variable which represents the local filename(s) as specified by pacman.<br />
<br />
{{ic|%u}}<br />
:Variable which represents the download URL as specified by pacman.<br />
<br />
=== pacget (aria2) mirror script ===<br />
<br />
This script uses the servers in {{ic|/etc/pacman.d/mirrorlist}} as mirrors in aria2. What happens is that aria2 downloads a single package from multiple servers simultaneously which may offer an increase in download speed.<br />
<br />
{{Note|You have to put {{ic|exec}} before {{ic|/usr/bin/pacget}} in the {{ic|XferCommand}}. This is needed so that when you terminate pacget or aria2 (with process ID used by pacget), pacman would also terminate. This would prevent inconvenience because pacman would not persist downloading a file when you tell it not to.}}<br />
<br />
{{Warning|You may experience some problems if the mirrors used are out-of-sync or are simply not up-to-date. Just use the [[Reflector]] script to generate a list of up-to-date and ''fast'' mirrors. Also, ftp.archlinux.org resolves to two IP addresses. You may want to choose only one of them and hard code ftp.archlinux.org and the chosen IP address to {{ic|/etc/hosts}}.}}<br />
<br />
{{hc|/usr/bin/pacget|<nowiki><br />
#!/bin/bash<br />
<br />
msg() {<br />
echo ""<br />
echo -e " \033[1;34m->\033[1;0m \033[1;1m${1}\033[1;0m" >&2<br />
}<br />
<br />
error() {<br />
echo -e "\033[1;31m==> ERROR:\033[1;0m \033[1;1m$1\033[1;0m" >&2<br />
}<br />
<br />
CONF=/etc/pacget.conf<br />
STATS=/etc/pacget.stats<br />
ARIA2=$(which aria2c 2> /dev/null)<br />
<br />
# ----- do some checks first -----<br />
if [ ! -x "$ARIA2" ]; then<br />
error "aria2c was not found or isn't executable."<br />
exit 1<br />
fi<br />
<br />
if [ $# -ne 2 ]; then<br />
error "Incorrect number of arguments"<br />
exit 1<br />
fi<br />
<br />
filename=$(basename $1)<br />
server=${1%/$filename}<br />
arch=$(grep ^Architecture /etc/pacman.conf | cut -d '=' -f2 | sed 's/ //g')<br />
if [[ $arch = "auto" ]]; then<br />
arch=$(uname -m)<br />
fi<br />
# Determine which repo is being used<br />
repo=$(awk -F'/' '$(NF-2)~/^(community|core|extra|testing|comunity-testing|multilib)$/{print $(NF-2)}' <<< $server)<br />
[ -z $repo ] && repo="custom"<br />
<br />
# For db files, or when using a custom repo (which most likely doesn't have any mirror),<br />
# use only the URL passed by pacman; Otherwise, extract the list of servers (from the include file of the repo) to download from<br />
url=$1<br />
if ! [[ $filename = *.db || $repo = "custom" ]]; then<br />
mirrorlist=$(awk -F' *= *' '$0~"^\\["r"\\]",/Include *= */{l=$2} END{print l}' r=$repo /etc/pacman.conf)<br />
if [ -n mirrorlist ]; then<br />
num_conn=$(grep ^split $CONF | cut -d'=' -f2)<br />
url=$(sed -r '/^Server *= */!d; s/Server *= *//; s/\$repo'"/$repo/"'; s/\$arch'"/$arch/; s/$/\/$filename/" $mirrorlist | head -n $(($num_conn *2)) )<br />
fi<br />
fi<br />
<br />
msg "Downloading $filename"<br />
cd /var/cache/pacman/pkg/<br />
<br />
touch $STATS<br />
<br />
$ARIA2 --conf-path=$CONF --max-tries=1 --max-file-not-found=5 \<br />
--uri-selector=adaptive --server-stat-if=$STATS --server-stat-of=$STATS \<br />
--allow-overwrite=true --remote-time=true --log-level=error --summary-interval=0 \<br />
$url --out=${filename}.pacget && [ ! -f ${filename}.pacget.aria2 ] && mv ${filename}.pacget $2 && chmod 644 $2<br />
<br />
exit $?<br />
</nowiki>}}<br />
<br />
{{hc|/etc/pacget.conf|<nowiki><br />
# The log file<br />
log=/var/log/pacget.log<br />
# Number of servers to download from<br />
split=5<br />
# Minimum file size that justifies a split, i.e. concurrent download (default 20M)<br />
min-split-size=1M<br />
# Maximum download speed (0 = unrestricted)<br />
max-download-limit=0<br />
# Minimum download speed (0 = do not care)<br />
lowest-speed-limit=0<br />
# Server timeout period<br />
timeout=5<br />
# 'none' or 'falloc'<br />
file-allocation=none<br />
</nowiki>}}<br />
<br />
Save this script as {{ic|/usr/bin/pacget}}, and make the script executable using the command below:<br />
# chmod 755 /usr/bin/pacget<br />
<br />
In {{ic|/etc/pacman.conf}}, in the {{ic|[options]}} section, the following needs to be added:<br />
XferCommand = exec /usr/bin/pacget %u %o<br />
<br />
{{Note|If you use ftp.archlinux.org as the first server listed in your include files ({{ic|/etc/pacman.d/*}}), some problems may occur when the mirrors you are using have not yet synced. To make great use of this script, choose a mirror (that syncs in a timely manner) that is more appropriate for you, then put that on top of the server lists. This is to prevent downloading only from ftp.archlinux.org when the mirrors have not yet synced. The rankmirrors script can be useful in this case.}}<br />
<br />
=== Using 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 />
<br />
== Choosing the fastest mirror ==<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 />
== Sharing packages over your LAN ==<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'll get into troubles.<br />
<br />
See [[Pacman tips#Network_shared_pacman_cache]].</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=PPTP_Client&diff=361431PPTP Client2015-02-16T17:20:14Z<p>Jstjohn: add troubleshooting section with a suggestion to allow GRE through the firewall</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[zh-CN:Microsoft VPN client setup with pptpclient]]<br />
pptpclient is a program implementing the Microsoft PPTP protocol. As such, it can be used to connect to a Microsoft VPN network (or any PPTP-based VPN) provided by a school or workplace.<br />
<br />
== Installing PPTP Client ==<br />
<br />
Install {{Pkg|pptpclient}} from the [[official repositories]].<br />
<br />
== Configure ==<br />
<br />
To configure pptpclient you will need to collect the following information from your network administrator:<br />
<br />
* The IP address or hostname of the VPN server.<br />
* The username you will use to connect.<br />
* The password you will use to connect.<br />
* The authentication (Windows) domain name. This is not necessary for certain networks.<br />
<br />
You must also decide what to name the tunnel.<br />
<br />
=== Configure using ''pptpsetup'' ===<br />
<br />
You can configure and delete tunnels by running the ''pptpsetup'' tool as root. For example:<br />
<br />
pptpsetup --create my_tunnel --server vpn.example.com --username alice --password foo --encrypt<br />
pptpsetup --delete my_tunnel<br />
<br />
You can [[#Connect]] after a tunnel has been configured.<br />
<br />
=== Configure by hand ===<br />
<br />
You can also edit all necessary configuration files by hand, rather than relying on ''pptpsetup''.<br />
<br />
==== Edit The options File ====<br />
<br />
The {{ic|/etc/ppp/options}} file sets security options for your VPN client. If you have trouble connecting to your network, you may need to relax the options. At a minimum, this file should contain the options {{ic|lock}}, {{ic|noauth}}, {{ic|nobsdcomp}} and {{ic|nodeflate}}.<br />
<br />
{{hc|/etc/ppp/options|# Lock the port<br />
lock<br />
# We don't need the tunnel server to authenticate itself<br />
noauth<br />
# Turn off compression protocols we know won't be used<br />
nobsdcomp<br />
nodeflate<br />
# We won't do PAP, EAP, CHAP, or MSCHAP, but we will accept MSCHAP-V2<br />
# (you may need to remove these refusals if the server is not using MPPE)<br />
refuse-pap<br />
refuse-eap<br />
refuse-chap<br />
refuse-mschap}}<br />
<br />
==== Edit The chap-secrets File ====<br />
<br />
The {{ic|/etc/ppp/chap-secrets}} file contains credentials for authenticating a tunnel. Make sure no one except root can read this file, as it contains sensitive information.<br />
chmod 0600 /etc/ppp/chap-secrets<br />
<br />
Edit the file. It has the following format:<br />
{{hc|/etc/ppp/chap-secrets|<DOMAIN>\\<USERNAME> PPTP <PASSWORD> *}}<br />
<br />
Replace each bracketed term with an appropriate value. Omit {{ic|<DOMAIN>\\}} if your connection does not require a domain.<br />
<br />
{{Note|Place your password in double quotation marks ({{ic|"}}) if it contains special characters such as {{ic|$}}.}}<br />
{{Warning|This file contains passwords in plain text. Guard it well!}}<br />
<br />
==== Name Your Tunnel ====<br />
<br />
The {{ic|/etc/ppp/peers/<TUNNEL>}} file contains tunnel-specific configuration options. {{ic|<TUNNEL>}} is the name you wish to use for your VPN connection. The file should look like this:<br />
{{hc|/etc/ppp/peers/<TUNNEL>|pty "pptp <SERVER> --nolaunchpppd"<br />
name <DOMAIN>\\<USERNAME><br />
remotename PPTP<br />
require-mppe-128<br />
file /etc/ppp/options<br />
ipparam <TUNNEL>}}<br />
<br />
Again, omit {{ic|<DOMAIN>\\}} if your connection does not require a domain. {{ic|<SERVER>}} is the remote address of the VPN server, {{ic|<DOMAIN>}} is the domain your user belongs to, {{ic|<USERNAME>}} is the name you will use to connect to the server, and {{ic|<TUNNEL>}} is the name of the connection.<br />
<br />
{{Note|{{ic|remotename PPTP}} is used to find {{ic|<PASSWORD>}} in the {{ic|/etc/ppp/chap-secrets}} File.}}<br />
{{Note|If you do not need MPPE support, you should remove the {{ic|require-mppe-128}} option from this file and from {{ic|/etc/ppp/options}}}}<br />
<br />
== Connect ==<br />
<br />
To make sure that everything is configured properly, as root execute:<br />
# pon <TUNNEL> debug dump logfd 2 nodetach<br />
<br />
If everything has been configured correctly, the {{ic|pon}} command should not terminate. Once you are satisfied that it has connected successfully, you can terminate the command.<br />
<br />
{{Note|As an additional verification you can run {{ic|ip addr show}} and ensure that a new device, {{ic|ppp0}}, is available.}}<br />
<br />
To connect to your VPN normally, simply execute:<br />
# pon <TUNNEL><br />
<br />
Where {{ic|<TUNNEL>}} is the name of the tunnel you established earlier. Note that this command should be run as root.<br />
<br />
=== Routing ===<br />
<br />
Once you have connected to your VPN, you should be able to interact with anything available on the VPN server. To access anything on the remote network, you need to add a new route to your routing table.<br />
<br />
{{Note|Depending on your configuration, you may need to re-add the routing information every time you connect to your VPN.}}<br />
<br />
For more information on how to add routes, you can read this article which has many more examples: [http://pptpclient.sourceforge.net/routing.phtml PPTP Routing Howto]<br />
<br />
==== Split Tunneling ====<br />
<br />
Packets with a destination of your VPN's network should be routed through the VPN interface (usually {{ic|ppp0}}). To do this, you create the route:<br />
# ip route add 192.168.10.0/24 dev ppp0<br />
<br />
This will route all the traffic with a destination of 192.168.10.* through your VPN's interface, ({{ic|ppp0}}).<br />
<br />
==== Route All Traffic ====<br />
<br />
It may be desirable to route ''all'' traffic through your VPN connection. You can do this by running:<br />
# ip route add default dev ppp0<br />
<br />
{{Note|Routing all traffic through the VPN may result in slower over all connection speed because your traffic will be routed through the remote VPN before being routed normally.}}<br />
<br />
==== Route All Traffic by /etc/ppp/ip-up.d ====<br />
<br />
{{Note|All scripts in {{ic|/etc/ppp/ip-up.d/}} will called when the VPN connection is established.}}<br />
<br />
{{hc|/etc/ppp/ip-up.d/01-routes.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# This script is called with the following arguments:<br />
# Arg Name<br />
# $1 Interface name<br />
# $2 The tty<br />
# $3 The link speed<br />
# $4 Local IP number<br />
# $5 Peer IP number<br />
# $6 Optional ``ipparam'' value foo<br />
<br />
ip route add default via $4<br />
</nowiki>}}<br />
<br />
Make sure the script is executable.<br />
<br />
==== Split Tunneling based on port by /etc/ppp/ip-up.d ====<br />
<br />
{{Note|All scripts in {{ic|/etc/ppp/ip-up.d/}} will called when the VPN connection is established.}}<br />
<br />
{{hc|/etc/ppp/ip-up.d/01-routebyport.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# This script is called with the following arguments:<br />
# Arg Name<br />
# $1 Interface name<br />
# $2 The tty<br />
# $3 The link speed<br />
# $4 Local IP number<br />
# $5 Peer IP number<br />
# $6 Optional ``ipparam'' value foo<br />
<br />
echo 0 > /proc/sys/net/ipv4/conf/$1/rp_filter<br />
echo 1 > /proc/sys/net/ipv4/ip_forward<br />
echo 1 > /proc/sys/net/ipv4/ip_dynaddr<br />
<br />
ip route flush table vpn<br />
ip route add default via $5 dev $1 table vpn<br />
<br />
# forward only IRC ports over VPN<br />
iptables -t mangle -A OUTPUT -p tcp -m multiport --dports 6667,6697 -j MARK --set-mark 0x1<br />
iptables -t nat -A POSTROUTING -o $1 -j MASQUERADE<br />
<br />
ip rule add fwmark 0x1 pri 100 lookup vpn<br />
ip rule add from $4 pri 200 table vpn<br />
ip route flush cache<br />
</nowiki>}}<br />
<br />
Make sure the script is executable and that the vpn table is added to {{ic|/etc/iproute2/rt_tables}}<br />
<br />
201 vpn<br />
<br />
== Disconnect ==<br />
<br />
Execute the following to disconnect from a VPN:<br />
<br />
# poff <TUNNEL><br />
<br />
{{ic|<TUNNEL>}} is the name of your tunnel.<br />
<br />
== Making A VPN Daemon and Connecting On Boot==<br />
<br />
{{Out of date|recent changes to systemd. see https://wiki.archlinux.org/index.php/Systemd/Services}}<br />
<br />
You can create a simple daemon for your VPN connection by creating an appropriate {{ic|/etc/rc.d/*}} script:<br />
<br />
{{Note|As always, {{ic|<TUNNEL>}} is the name of your tunnel. {{ic|<ROUTING COMMAND>}} is the command you use to add the appropriate route to the routing table.}}<br />
<br />
{{Note|1=The ''stop'' functionality of this script '''will not work''' if the {{ic|updetach}} and {{ic|persist}} arguments are passed to {{ic|/usr/bin/pon}} when pon is started. The reason for this is that the {{ic|/usr/bin/poff}} script contains a bug when determining the PID of the specified {{ic|pppd}} process if arguments were passed to {{ic|pon}}.<br />
<br />
To resolve this issue, you can patch your {{ic|/usr/bin/poff}} file by making the following changes on line 93:<br />
{{bc|<nowiki>-PID=`ps axw | grep "[ /]pppd call $1 *\$" | awk '{print $1}'`<br />
+PID=`ps axw | grep "[ /]pppd call $1" | awk '{print $1}'`</nowiki>}}}}<br />
<br />
{{hc|/etc/rc.d/name-of-your-vpn|<nowiki><br />
#!/bin/bash<br />
<br />
. /etc/rc.conf<br />
. /etc/rc.d/functions<br />
<br />
DAEMON=<TUNNEL>-vpn<br />
ARGS=<br />
<br />
[ -r /etc/conf.d/$DAEMON ] && . /etc/conf.d/$DAEMON<br />
<br />
<br />
case "$1" in<br />
start)<br />
stat_busy "Starting $DAEMON"<br />
pon <TUNNEL> updetach persist &>/dev/null && <ROUTING COMMAND> &>/dev/null<br />
if [ $? = 0 ]; then<br />
add_daemon $DAEMON<br />
stat_done<br />
else<br />
stat_fail<br />
exit 1<br />
fi<br />
;;<br />
stop)<br />
stat_busy "Stopping $DAEMON"<br />
poff <TUNNEL> &>/dev/null<br />
if [ $? = 0 ]; then<br />
rm_daemon $DAEMON<br />
stat_done<br />
else<br />
stat_fail<br />
exit 1<br />
fi<br />
;;<br />
restart)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "usage: $0 {start|stop|restart}" <br />
esac<br />
</nowiki>}}<br />
<br />
{{Note|We call {{ic|pon}} in the script with two additional arguments: {{ic|updetach}} and {{ic|persist}}. The argument {{ic|updetach}} makes pon block until the connection has been established. The other argument, {{ic|persist}}, makes the network automatically reconnect in the event of a failure. To connect at boot add @<TUNNEL>-vpn to the end of your {{ic|DAEMONS}} array in {{ic|/etc/rc.conf}}.}}<br />
<br />
== Troubleshooting ==<br />
If client connections keep timing out, make sure that GRE is allowed through the client firewall. For iptables, the necessary command is:<br />
# iptables -A ACCEPT -p 47 -j ACCEPT<br />
<br />
== Remarks ==<br />
<br />
You can find more information about configuring pptpclient at their website: [http://pptpclient.sourceforge.net/ pptpclient website]. The contents of this article were adapted from their Ubuntu How-To which also provides some hints on how to do things such as connecting on boot. These examples should be easy to adapt into daemons or other scripts to help automate your configuration.<br />
<br />
== See also ==<br />
<br />
[[PPTP server]]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Android&diff=355447Android2015-01-05T02:09:56Z<p>Jstjohn: /* Configuring adb */ add template and fix grammar</p>
<hr />
<div>[[Category:Development]]<br />
[[Category:Mobile devices]]<br />
[[it:Android]]<br />
[[ja:Android]]<br />
[[ru:Android]]<br />
[[zh-CN:Android]]<br />
{{Related articles start}}<br />
{{Related|Android notifier}}<br />
{{Related|Android tethering}}<br />
{{Related articles end}}<br />
<br />
== Exploring Android device ==<br />
<br />
There are few methods of exploring your device:<br />
<br />
*[[MTP]] over USB for files transferring.<br />
*[[#Connecting to a real device - Android Debug Bridge (ADB)|ADB/Fastboot]] for development purposes.<br />
*[[#Alternative connection methods|Alternative methods]] (such as FTP, SSH).<br />
<br />
== Android development ==<br />
<br />
There are 3 steps that need to be performed before you can develop Android applications on your Arch Linux box:<br />
<br />
# Install the Android SDK core component,<br />
# Install one or several Android SDK Platform packages,<br />
# Install one of the IDEs compatible with the Android SDK.<br />
<br />
=== Android SDK core components ===<br />
<br />
{{Note|First, if you are running a 64-bit system, make sure the [[multilib]] repository is enabled in [[Pacman#Repositories|pacman.conf]].}}<br />
<br />
Before developing Android applications, you need to install the Android SDK, which is made of 3 distinct packages, all installable from [[Arch User Repository|AUR]]:<br />
<br />
# {{AUR|android-sdk}}<br />
# {{AUR|android-sdk-platform-tools}}<br />
# {{AUR|android-sdk-build-tools}}<br />
<br />
Android-sdk will be installed on {{ic|/opt/android-sdk}}. This folder has root permissions, so keep in mind to run sdk manager as root, otherwise you will not be able to install/update/modify anything on /opt/android-sdk. However, if you intend to use it as a regular user, create an android sdk users group (or use any group name you want):<br />
# groupadd sdkusers<br />
<br />
Add your user into this group:<br />
# gpasswd -a <user> sdkusers<br />
<br />
Change folder's owner and group.<br />
# chown -R <user>:sdkusers /opt/android-sdk/<br />
<br />
Change permissions of the folder so you will be able to read/write/execute in it:<br />
# chmod -R 0774 /opt/android-sdk/<br />
<br />
{{Note|As an alternative to a global install with the [[AUR]] packages, the SDK can be installed to a user's home directory via [https://developer.android.com/sdk/index.html the upstream instructions].}}<br />
<br />
=== Android SDK platform API ===<br />
<br />
Install the desired Android SDK Platform package from the [[AUR]]:<br />
<br />
* {{aur|android-platform}} (latest)<br />
* {{aur|android-platform-21}}<br />
* {{aur|android-platform-20}}<br />
* {{aur|android-platform-19}}<br />
* {{aur|android-platform-18}}<br />
* {{aur|android-platform-17}}<br />
* {{aur|android-platform-16}}<br />
* {{aur|android-platform-15}}<br />
* {{aur|android-platform-14}}<br />
* {{aur|android-platform-13}}<br />
* {{aur|android-platform-12}}<br />
* {{aur|android-platform-11}}<br />
* {{aur|android-platform-10}}<br />
* {{aur|android-platform-9}}<br />
* {{aur|android-platform-8}}<br />
* {{aur|android-platform-7}}<br />
* {{aur|android-platform-7}}<br />
* {{aur|android-platform-6}}<br />
* {{aur|android-platform-5}}<br />
* {{aur|android-platform-4}}<br />
* {{aur|android-platform-3}}<br />
* {{aur|android-platform-2}}<br />
<br />
=== Development environment ===<br />
<br />
Android Studio is the new official Android development environment based on IntelliJ IDEA. Alternatively, you can use [[Eclipse]] with the official but deprecated ADT plugin, or [[Netbeans]] with the NBAndroid plugin. All are described below.<br />
<br />
==== Android Studio ====<br />
<br />
[http://developer.android.com/sdk/installing/studio.html Android Studio] is the new official Android development environment based on IntelliJ IDEA. Similar to Eclipse with the ADT Plugin, Android Studio provides integrated Android developer tools for development and debugging.<br />
<br />
You can download and install it with the {{AUR|android-studio}} package from the AUR. If you get an error about a missing SDK, refer to the section Getting Android SDK platform API above.<br />
<br />
If you are using a tiling window manager, you will need to apply one of the fixes mentioned in [https://code.google.com/p/android/issues/detail?id=57675 this] issue page.<br />
<br />
==== Eclipse ====<br />
<br />
{{Note|Since 2014-12-08, the ADT plugin is officially considered deprecated and Android Studio is now the official IDE.}}<br />
<br />
Most stuff required for Android development in Eclipse is already packaged in AUR:<br />
<br />
Official plugin by Google &ndash; [http://developer.android.com/sdk/eclipse-adt.html Eclipse ADT]:<br />
# {{AUR|eclipse-android}}<br />
<br />
Dependencies:<br />
# {{AUR|eclipse-emf}}<br />
# {{AUR|eclipse-gef}}<br />
# {{AUR|eclipse-wtp}}<br />
<br />
{{Note|<br />
* if you get a message about unresolvable dependencies, install [[Java]] manually and try again.<br />
* as an alternative, you can install the ADT via eclipse's built in "add new software" command (see instructions on ADT site).<br />
* if you are in real trouble, it is also possible to download Android SDK and use the bundled Eclipse. This usually works without problems.<br />
* if you need to install extra SDK plugins not found in the AUR, you must change the file ownership of /opt/android-sdk first. You can do this with {{ic|# chgrp -R users /opt/android-sdk ; chmod -R 0775 /opt/android-sdk}} (see [[File Permissions]] for more details).<br />
}}<br />
<br />
Enter the path to the Android SDK Location in<br />
<br />
Windows -> Preferences -> Android<br />
<br />
{{Note|<br />
If the plugins do not show up in Eclipse after the AUR package has been upgraded, then eclipse probably has out-of-date caches. Running {{ic|sudo eclipse -clean}} once should clear them. If the problem persists, uninstall eclipse and all the plugins, delete {{ic|/usr/share/eclipse}}, and reinstall everything.<br />
}}<br />
<br />
==== Netbeans ====<br />
<br />
If you prefer using [[Netbeans]] as your IDE and want to develop Android applications, download the [http://www.nbandroid.org NBAndroid] by going to:<br />
<br />
Tools -> Plugins -> Settings<br />
<br />
Add the following URL: http://nbandroid.org/updates/updates.xml<br />
<br />
Then go to '''Available Plugins''' and install the '''Android''' and '''JUnit''' plugins. Once you have installed go to:<br />
<br />
Tools -> Options -> Miscellaneous -> Android<br />
<br />
and select the path where the SDK is installed (/opt/android-sdk by default). That is it, now you can create a new Android project and start developing using Netbeans.<br />
<br />
=== Connecting to a real device - Android Debug Bridge (ADB) ===<br />
<br />
{{Tip|For some devices, you may have to enable MTP on the device, before ADB will work.}}<br />
<br />
To get ADB to connect to a real device or phone under Arch, you must:<br />
<br />
* Install {{Pkg|android-tools}}.<br />
* Enable USB Debugging on your phone or device:<br />
** Jelly Bean (4.2) and newer: Go to {{ic|Settings --> About Phone}} tap “Build Number” until you get a popup that you have become a developer (about 10 times). Then go to {{ic|Settings --> Developer --> USB debugging}} and enable it.<br />
** Older versions: This is usually done from {{ic|Settings --> Applications --> Development --> USB debugging}}. Reboot the phone after checking this option to make sure USB debugging is enabled.<br />
* install {{Pkg|android-udev}} to connect the device to the proper {{ic|/dev/}} entries.<br />
* Add yourself to the ''adbusers'' group. ({{ic|gpasswd -a ''username'' adbusers}})<br />
<br />
If [[#Does it work?|ADB recognizes your device]] (it is visible and accessible in IDE), you are done. Otherwise see instructions below.<br />
<br />
==== Figure out device IDs ====<br />
<br />
Each Android device has a USB vendor/product ID. An example for HTC Evo is:<br />
<br />
vendor id: 0bb4<br />
product id: 0c8d<br />
<br />
Plug in your device and execute:<br />
<br />
$ lsusb<br />
<br />
It should come up something like this:<br />
<br />
Bus 002 Device 006: ID 0bb4:0c8d High Tech Computer Corp.<br />
<br />
==== Adding udev Rules ====<br />
<br />
Use the rules from [http://source.android.com/source/initializing.html#configuring-usb-access Android developer] or you can use the following template for your udev rules, just replace [VENDOR ID] and [PRODUCT ID] with yours. Copy these rules into {{ic|/etc/udev/rules.d/51-android.rules}}:<br />
<br />
{{hc|/etc/udev/rules.d/51-android.rules|2=<nowiki>SUBSYSTEM=="usb", ATTR{idVendor}=="[VENDOR ID]", MODE="0666"<br />
SUBSYSTEM=="usb",ATTR{idVendor}=="[VENDOR ID]",ATTR{idProduct}=="[PRODUCT ID]",SYMLINK+="android_adb"<br />
SUBSYSTEM=="usb",ATTR{idVendor}=="[VENDOR ID]",ATTR{idProduct}=="[PRODUCT ID]",SYMLINK+="android_fastboot"</nowiki>}}<br />
<br />
Then, to reload your new udev rules, execute:<br />
# udevadm control --reload-rules<br />
<br />
==== Configuring adb ====<br />
<br />
Instead of using udev rules, you may create/edit {{ic|~/.android/adb_usb.ini}} which contains a list of vendor IDs.<br />
<br />
$ cat ~/.android/adb_usb.ini <br />
0x27e8<br />
<br />
==== Does it work? ====<br />
<br />
After you have setup the udev rules, unplug your device and replug it.<br />
<br />
After running:<br />
<br />
$ adb devices<br />
<br />
you should see something like:<br />
<br />
List of devices attached <br />
HT07VHL00676 device<br />
<br />
You can now use adb to transfer files between the device and your computer. To transfer files to the device, use<br />
$ adb push ''<what-to-copy>'' ''<where-to-place>''<br />
<br />
To transfer files from the device, use<br />
$ adb pull ''<what-to-pull>'' ''<where-to-place>''<br />
<br />
If you do not have the '''adb''' program (usually available in {{Ic|/opt/android-sdk/platform-tools/}}), it means you have not installed the platform tools.<br />
<br />
If you are getting an empty list (your device is not there), it may be because you have not enabled USB debugging on your device. You can do that by going to Settings => Applications => Development and enabling USB debugging. On Android 4.2 (Jelly Bean) the Development menu is hidden; to enable it go to Settings => About phone and tap Build number 7 times.<br />
<br />
If there are still problems such as ''adb'' displaying {{ic|???????? no permissions}} under devices, try restarting the adb server as root.<br />
# adb kill-server<br />
# adb start-server<br />
<br />
=== NVIDIA Tegra platform ===<br />
<br />
If you target your application at NVIDIA Tegra platform, you might also want to install tools, samples and documentation provided by NVIDIA. In [http://developer.nvidia.com/category/zone/mobile-development NVIDIA Developer Zone for Mobile] there are two tools: <br />
<br />
# The [http://developer.nvidia.com/tegra-resources Tegra Android Development Pack] provides tools (NVIDIA Debug Manager) related to [http://developer.android.com/sdk/eclipse-adt.html Eclipse ADT] and their documentation. <br />
# The [http://developer.nvidia.com/tegra-resources Tegra Toolkit] provides tools (mostly CPU and GPU optimization related), samples and documentation. <br />
<br />
Both are currently not available in the [[AUR]] anymore, because NVIDIA requires a registration/login for the download.<br />
<br />
== Building Android ==<br />
<br />
Please note that these instructions are based on the [http://source.android.com/source/building.html official AOSP build instructions]. Other Android-derived systems such as CyanogenMod will often require extra steps.<br />
<br />
=== OS bitness ===<br />
<br />
Android 2.2.x (Froyo) and below are the only versions of Android that will build on a 32-bit system. For 2.3.x (Gingerbread) and above, you will need a 64-bit installation. <br />
<br />
=== Required packages ===<br />
<br />
To build any version of Android, you need to install these packages:<br />
<br />
* 32-bit and 64-bit systems: {{Pkg|gcc}} {{Pkg|git}} {{Pkg|gnupg}} {{Pkg|flex}} {{Pkg|bison}} {{Pkg|gperf}} {{Pkg|sdl}} {{Pkg|wxgtk}} {{Pkg|squashfs-tools}} {{Pkg|curl}} {{Pkg|ncurses}} {{Pkg|zlib}} {{Pkg|schedtool}} {{Pkg|perl-switch}} {{Pkg|zip}} {{Pkg|unzip}} {{Pkg|libxslt}} {{Pkg|python2-virtualenv}} {{Pkg|bc}}<br />
<br />
* 64-bit systems only: {{Pkg|gcc-multilib}} {{Pkg|lib32-zlib}} {{Pkg|lib32-ncurses}} {{Pkg|lib32-readline}}<br />
<br />
=== Java Development Kit ===<br />
<br />
Android 5 (Lollipop) can be built with {{Pkg|jdk7-openjdk}}.<br />
<br />
Older versions [http://source.android.com/source/initializing.html require] a working '''Oracle JDK''' installed on your build system. It '''will not''' work with OpenJDK.<br />
*For Gingerbread through KitKat (2.3 - 4.4), Java 6 is required, which is available as {{AUR|jdk6}} from the AUR. See [[Java]] if you want to use it besides another (newer) JDK version.<br />
*For Cupcake through Froyo (1.5 - 2.2), Java 5 is required, which is no longer available for Arch Linux.<br />
<br />
=== Setting up the build environment ===<br />
<br />
Download the {{ic|repo}} utility.<br />
<br />
$ mkdir ~/bin<br />
$ export PATH=~/bin:$PATH<br />
$ curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo<br />
$ chmod a+x ~/bin/repo<br />
<br />
Create a directory to build.<br />
<br />
$ mkdir ~/android<br />
$ cd ~/android<br />
<br />
You will need to change the default Python from version 3 to version 2:<br />
<br />
$ virtualenv2 venv # Creates a directory, venv/, containing the Virtualenv<br />
<br />
{{Note|During build you may receive error pertaining to missing python modules. A quick and dirty fix is to symlink /usr/lib/python2.7/* to ~/android/venv/python2.7/ (Change ~/android to reflect your build directory if different than above).<br />
Example:<br />
$ ln -s /usr/lib/python2.7/* /Data/Android_Build/venv/lib/python2.7/<br />
}}<br />
Activate the Virtualenv, which will update $PATH to point at Python 2.<br />
<br />
{{Note|this activation is only active for the current terminal session.<br />
}}<br />
<br />
$ source venv/bin/activate<br />
<br />
=== Downloading the source code ===<br />
<br />
This will clone the repositories. You '''only''' need to do this the first time you build Android, or if you want to switch branches.<br />
<br />
* The {{ic|repo}} has a {{ic|-j}} switch that operates similarly to the one used with {{ic|make}}. Since it controls the number of simultaneous downloads, you should adjust the value depending on downstream network bandwidth.<br />
<br />
* You will need to specify a '''branch''' (release of Android) to check out with the {{ic|-b}} switch. If you leave the switch out, you will get the so-called '''master branch'''.<br />
<br />
$ repo init -u https://android.googlesource.com/platform/manifest -b master<br />
$ repo sync -j4<br />
<br />
Wait a long time. Just the uncompiled source code, along with the {{ic|.repo}} and {{ic|.git}} directories that are used to keep track of it, are well over 10 GB.<br />
<br />
{{Note|If you want to update your local copy of the Android source, at a later time, simply enter the build directory, load the Virtualenv, and re-sync:<br />
$ repo sync<br />
}}<br />
<br />
=== Building the code ===<br />
<br />
This should do what you need for AOSP:<br />
<br />
$ source build/envsetup.sh<br />
$ lunch full-eng<br />
$ make -j4<br />
<br />
If you run '''lunch''' without arguments, it will ask what build you want to create. Use -j with a number between one and two times number of cores/threads.<br />
<br />
The build takes a very long time.<br />
<br />
{{Note|Make sure you have enough RAM.<br />
Android will use the /tmp directory heavily. By default the size of the partition the /tmp folder is mounted on is half the size of your RAM. If it fills up, the build will fail. 4GB of RAM or more is recommended.<br />
* Alternatively, you can get rid of the tmpfs from [[Fstab|fstab]] all together. <br />
}}<br />
<br />
=== Testing the build ===<br />
<br />
When finished, run/test the final image(s).<br />
<br />
$ emulator<br />
<br />
=== Creating a Flashable Image ===<br />
To create an image that can be flashed it is necessary to:<br />
<br />
make -j8 updatepackage<br />
<br />
This will create a zip image under '''out/target/product/hammerhead''' (hammerhead being the device name) that can be flashed.<br />
<br />
== Alternative connection methods ==<br />
<br />
=== AirDroid ===<br />
<br />
AirDroid is an Android app to access files from your web browser.<br />
<br />
=== FTP ===<br />
<br />
You run a FTP server on Arch and connect to it from your phone, or the other way around: run a FTP server on your phone and connect to it from Arch.<br />
<br />
See [[List of applications/Internet#FTP]]. There are a lot of FTP clients/servers available for Android.<br />
<br />
=== SSH Server ===<br />
<br />
There are many SSH servers available for Android, it allows you to transfer files using {{ic|scp}} command. See also [[SSH]].<br />
<br />
=== Samba ===<br />
<br />
See [[Samba]].<br />
<br />
== Tips & Tricks ==<br />
<br />
=== During Debugging "Source not found" ===<br />
<br />
Most probably the debugger wants to step into the Java code. As the source code of Android does not come with the Android SDK, this leads to an error. The best solution is to use step filters to not jump into the Java source code. Step filters are not activated by default. To activate them: <br />
Window -> Preferences -> Java -> Debug -> Step Filtering<br />
Consider to select them all. If appropriate you can add the android.* package. See the forum post for more information: http://www.eclipsezone.com/eclipse/forums/t83338.rhtml<br />
<br />
=== Linux distribution on the sdcard ===<br />
<br />
You can install Debian like in this [http://forum.xda-developers.com/showthread.php?t=631389 thread]. Excellent guide to installing Arch in chroot (in parallel with Android) can be found on [http://archlinuxarm.org/forum/viewtopic.php?f=27&t=1361&start=40 archlinuxarm.org forum].<br />
<br />
== Troubleshooting ==<br />
<br />
=== aapt: No such file or directory ===<br />
<br />
The build tools include 32-bit binaries. For this reason they require 32-bit libraries. If you happened to install the SDK manually, you will additionally need to install<br />
'''multilib/lib32-libstdc++5''' and '''multilib/lib32-zlib'''.<br />
<br />
=== ValueError: unsupported pickle protocoll ===<br />
<br />
Just issue 'rm ~/.repopickle_.gitconfig'</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Software_access_point&diff=349221Software access point2014-12-09T02:33:49Z<p>Jstjohn: fix spelling of "Wi-Fi" throughout; fix other minor typos/grammar issues</p>
<hr />
<div>[[ru:Software Access Point]]<br />
[[Category:Wireless Networking]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related articles end}}<br />
A software access point is used when you want your computer to act as a Wi-Fi access point for the local network. It saves you the trouble of getting a separate wireless router.<br />
<br />
== Requirements ==<br />
<br />
=== Wi-Fi device must support AP mode ===<br />
<br />
You need a [http://wireless.kernel.org/en/developers/Documentation/nl80211 nl80211] compatible wireless device, which supports the AP [http://wireless.kernel.org/en/users/Documentation/modes operating mode]. This can be verified by running {{ic|iw list}} command, under the {{ic|Supported interface modes}} block there should be {{ic|AP}} listed:<br />
<br />
{{hc|$ iw list|<br />
Wiphy phy1<br />
...<br />
Supported interface modes:<br />
* IBSS<br />
* managed<br />
* '''AP'''<br />
* AP/VLAN<br />
* WDS<br />
* monitor<br />
* mesh point<br />
...<br />
}}<br />
<br />
=== Wireless client and software AP with a single Wi-Fi device ===<br />
<br />
Creating a software AP is independent from your own network connection (Ethernet, wireless, ...). Many wireless devices even support ''simultaneous'' operation both as AP and as wireless "client" at the same time. Using that capability you can create a software AP acting as a "wireless repeater" for an existing network, using a single wireless device. The capability is listed in the following section in the output of {{ic|iw list}}:<br />
<br />
{{hc|1=$ iw list|2=<br />
Wiphy phy1<br />
...<br />
valid interface combinations:<br />
* #{ managed } <= 2048, #{ AP, mesh point } <= 8, #{ P2P-client, P2P-GO } <= 1,<br />
total <= 2048, #channels <= 1, STA/AP BI must match<br />
...<br />
}}<br />
The constraint {{ic|1=#channels <= 1}} means that your software AP must operate on the same channel as your Wi-Fi client connection; see the {{ic|channel}} setting in {{ic|hostapd.conf}} below.<br />
<br />
If you want to use the capability/feature, perhaps because an Ethernet connection is not available, you need to create two separate ''virtual interfaces'' for using it. <br />
Virtual interfaces for a physical device {{ic|wlan0}} can be created as follows: <br />
First, the ''virtual interfaces'' are created for the network connection ({{ic|wlan0_sta}}) itself and for the software AP/hostapd "wireless repeater":<br />
<br />
# iw dev wlan0 interface add wlan0_sta type station <br />
# iw dev wlan0 interface add wlan0_ap type __ap <br />
Second, the interfaces are assigned separate MAC addresses (use custom unique addresses): <br />
# ip link set dev wlan0_sta address 12:34:56:78:ab:cd<br />
# ip link set dev wlan0_ap address 12:34:56:78:ab:ce<br />
<br />
== Overview ==<br />
<br />
Setting up an access point comprises two main parts:<br />
* Setting up the '''Wi-Fi link layer''', so that wireless clients can associate to your computer's "software access point" and send/receive IP packets from/to your computer; this is what the hostapd package will do for you.<br />
* Setting up the '''network configuration''' on you computer, so that your computer will properly relay IP packets from/to its own Internet connection from/to wireless clients.<br />
<br />
== Wi-Fi Link Layer ==<br />
<br />
The actual Wi-Fi link is established via the {{Pkg|hostapd}} package (available in the [[official repositories]]). The package has WPA2 support.<br />
<br />
Adjust the options in ''hostapd'' configuration file if necessary. Especially, change the {{ic|ssid}} and the {{ic|wpa_passphrase}}. See [http://wireless.kernel.org/en/users/Documentation/hostapd hostapd Linux documentation page] for more information.<br />
<br />
{{hc|/etc/hostapd/hostapd.conf|<nowiki><br />
ssid=YourWiFiName<br />
wpa_passphrase=Somepassphrase<br />
interface=wlan0<br />
bridge=br0<br />
auth_algs=3<br />
channel=7<br />
driver=nl80211<br />
hw_mode=g<br />
logger_stdout=-1<br />
logger_stdout_level=2<br />
max_num_sta=5<br />
rsn_pairwise=CCMP<br />
wpa=2<br />
wpa_key_mgmt=WPA-PSK<br />
wpa_pairwise=TKIP CCMP<br />
</nowiki>}}<br />
<br />
For automatically starting hostapd, [[Daemon|enable]] the {{ic|hostapd.service}}.<br />
{{Warning|The wireless channels allowed for access point operation differ according to geography. Depending on the wireless firmware, you may have to set the region correctly to use legal channels. '''Do not''' choose another region, as you may be illegally disturbing network traffic, affecting wireless functionality of your own device and others within its reach! To set the region see [[Wireless network configuration#Respecting the regulatory domain]].}} <br />
<br />
{{Note|If you have a card based on RTL8192CU chipset, install {{AUR|hostapd-8192cu}} in the [[AUR]] and replace {{ic|1=driver=nl80211}} with {{ic|1=driver=rtl871xdrv}} in the {{ic|hostapd.conf}} file.}}<br />
<br />
== Network configuration ==<br />
<br />
There are two basic ways for implementing this:<br />
# '''bridge''': create a network ''bridge'' on your computer (wireless clients will appear to access the same network interface and the same subnet that's used by your computer)<br />
# '''NAT''': with IP forwarding/masquerading and DHCP service (wireless clients will use a dedicated subnet, data from/to that subnet is NAT-ted -- similar to a normal Wi-Fi router that's connected to your DSL or cable modem)<br />
<br />
The bridge approach is simpler, but it requires that any service that's needed by your wireless clients (like, DHCP) is available on your computers external interface. That means it will not work if you have a dial-up connection (e.g., via PPPoE or a 3G modem) or if you're using a cable modem that will supply exactly one IP address to you via DHCP.<br />
<br />
The NAT approach is more versatile, as it clearly separates Wi-Fi clients from your computer and it's completely transparent to the outside world. It will work with any kind of network connection, and (if needed) you can introduce traffic policies using the usual iptables approach.<br />
<br />
Of course, it is possible to ''combine both things''. For that, studying both articles would be necessary. Example: Like having a bridge that contains both an ethernet device and the wireless device with an static ip, offering DHCP and setting NAT configured to relay the traffic to an additional network device - that can be ppp or eth.<br />
<br />
=== Bridge Setup ===<br />
<br />
You need to create a network ''bridge'' and add your network interface (e.g. {{ic|eth0}}) to it. You '''should not''' add the wireless device (e.g. {{ic|wlan0}}) to the bridge; hostapd will add it on its own. <br />
<br />
If you use [[netctl]], see [[Bridge with netctl]] for details (just do not add {{ic|tap0}} used in that example).<br />
<br />
{{Tip|You may wish to reuse an existing bridge, if you have one (e.g. used by a virtual machine).}}<br />
<br />
=== NAT Setup ===<br />
<br />
See [[Internet sharing]] for details.<br />
<br />
On that article, the device connected to the LAN is {{ic|net0}}. That device would be in this case your wireless device (e.g. {{ic|wlan0}}).<br />
<br />
== Tools ==<br />
<br />
=== create_ap ===<br />
<br />
The [https://bbs.archlinux.org/viewtopic.php?pid=1269258 create_ap] script combines {{Pkg|hostapd}}, [[dnsmasq]] and [[iptables]] to create a Bridged/NATed Access Point (available in the [[AUR]] {{Aur|create_ap}}).<br />
<br />
=== RADIUS ===<br />
<br />
See [https://me.m01.eu/blog/2012/05/wpa-2-enterprise-from-scratch-on-a-raspberry-pi/] for instructions to run a [http://freeradius.org/ FreeRADIUS] server for [[WPA2 Enterprise]].<br />
<br />
== Troubleshooting ==<br />
<br />
===WLAN is very slow===<br />
<br />
This could be caused by low entropy. Consider installing [[haveged]].<br />
<br />
===NetworkManager is interfering===<br />
<br />
hostapd may not work, if the device is managed by NetworkManager. You can mask the device:<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[keyfile]<br />
unmanaged-devices=mac:<hwaddr><br />
</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [[Router]]<br />
* [http://nims11.wordpress.com/2012/04/27/hostapd-the-linux-way-to-create-virtual-wifi-access-point/ Hostapd : The Linux Way to create Virtual Wi-Fi Access Point]<br />
* [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html tutorial and script for configuring a subnet with DHCP and DNS]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Sony_Vaio_VGN-SA/SB&diff=349220Sony Vaio VGN-SA/SB2014-12-09T02:29:56Z<p>Jstjohn: /* 2.2.1 Disable discrete graphics on boot with a systemd unit */ add missing templates; fix misc. formatting issues</p>
<hr />
<div>[[Category:Sony]]<br />
SONY VAIO SA/SB ( S series )<br />
'''Model No. VPCSA**/VPCSB**'''<br />
Getting started instruction. <br />
<br />
Please edit this article, keep fresh, your own idea to touch and go.<br />
<br />
== 1. Features ==<br />
<br />
* Sandy/Ivy PCI bridge: Intel Core i platform, generation 2nd/3rd. GPU integrated<br />
* VGA(Internal/External): Intel GMA3000 or 4000 / ATI(AMD) RADEON HD 6600M or nVIDIA GeForce GT 640M LE<br />
* Chipset: intel HM67 Express<br />
* RAID: intel 82801 Mobile SATA controller<br />
* Wireless: Centrino Wireless-N + WiMAX 6150(Bluetooth, WiFi, WiMAX)<br />
* Wired: Ethernet: Realtek RTL8111/8168B<br />
* Additional USB3.0 Host: NEC uPD720200(External), 1 Port<br />
* TPM is also available(Optional).<br />
<br />
* First edition of this article: kernel 3.3.5<br />
<br />
== 2. Hardware ==<br />
=== 2.1 Wired/Wireless ===<br />
There is nothing to do. Some udev errors are shown at boot like this,<br />
<br />
{{bc|<br />
[ 16.369825] Bad LUN (0:2)<br />
<br />
[ 16.392657] Bad target number (1:0)<br />
<br />
[ 16.405941] Bad target number (2:0)<br />
<br />
[ 16.419294] Bad target number (3:0)<br />
<br />
[ 16.469295] Bad target number (4:0)<br />
<br />
[ 16.522611] Bad target number (5:0)<br />
<br />
[ 16.575913] Bad target number (6:0)<br />
<br />
[ 16.629228] Bad target number (7:0)<br />
}}<br />
<br />
However, nothing to effect in use. If you want to solve these messages, realtek official drivers may be required.<br />
<br />
=== 2.2 Hybrid Graphics ===<br />
'''"STAMINA-SPEED" switch is designed as a software switch. This DIP switch is located on one of the individual circuit from mainboard, separately.''' For easy to understand it, just imagine such as a wireless switch on laptop computers. Therefore, there is nothing to do; feel free to control this switch. Follows are only suggestions within ATI models, your style to go.<br />
==== 2.2.1 Disable discrete graphics on boot with a systemd unit ====<br />
You can use systemd to automatically disable your discrete graphics card on boot. You need to make a script file and a service file. You won't need to do what's in section 2.2.2 if you do this<br />
<br />
1) First, make a script file in {{ic|/usr/lib/systemd/scripts}} an example name would be {{ic|ati_off}}.<br />
#!/bin/bash<br />
echo OFF > /sys/kernel/debug/vgaswitcheroo/switch<br />
<br />
2) Next, make a service file (e.g. atioff.service) in {{ic|/usr/lib/systemd/system}}.<br />
[Unit]<br />
Description=Turn off the discrete graphics card on boot<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/bash /usr/lib/systemd/scripts/ati_off<br />
RemainAfterExit=no<br />
<br />
[Install]<br />
Wantedby=multi-user.target<br />
<br />
Now run: <br />
# systemctl enable atioff<br />
This enables the ''atioff'' service and makes it run every time the computer boots.<br />
<br />
==== 2.2.2 ATI disabled on boot. Get long battery life. ====<br />
If you want to get more long battery life first, take this method is recommended.<br />
<br />
1) mounting debugfs<br />
<br />
# mount -t debugfs debugfs /sys/kernel/debug<br />
<br />
or /etc/fstab<br />
<br />
debugfs /sys/kernel/debug debugfs 0 0<br />
<br />
2) disable ATI using "vga_switcheroo"<br />
<br />
Radeon module should be loaded.<br />
<br />
# modprobe radeon<br />
<br />
Power OFF ATI.<br />
<br />
# echo OFF > /sys/kernel/debug/vgaswitcheroo/switch<br />
<br />
Check status correct or not.<br />
<br />
cat /sys/kernel/debug/vgaswitcheroo/switch<br />
<br />
Result;<br />
{{bc|<br />
0:IGD:+:Pwr:0000:00:02.0<br />
<br />
1:DIS: :Off:0000:01:00.0<br />
}}<br />
<br />
When you use these setting on boot, putting these lines into rc.local is useful.<br />
{{Warning|initscripts is obsolete [[systemd]] should be used for startup scripts instead.}}<br />
<br />
==== 2.2.3 Use both at any time. Switchable. ====<br />
If you want to use both intel and ati, commands are avaiable.<br />
<br />
1) mounting debugfs<br />
<br />
2) using "vga_switcheroo"<br />
Radeon module should be loaded.<br />
<br />
Enable ATI<br />
<br />
# echo DDIS > /sys/kernel/debug/vgaswitcheroo/switch<br />
<br />
Enable intel<br />
<br />
# echo DIGD > /sys/kernel/debug/vgaswitcheroo/switch<br />
<br />
Power ON/OFF<br />
<br />
# echo OFF > /sys/kernel/debug/vgaswitcheroo/switch<br />
# echo ON > /sys/kernel/debug/vgaswitcheroo/switch<br />
<br />
Check current status<br />
<br />
cat /sys/kernel/debug/vgaswitcheroo/switch<br />
<br />
==== 2.2.3 New functions. Set variety. ====<br />
For more control completely, there is a way to use various functions which you like, e.g. setkeycode.<br />
<br />
Please note: Unfortunatelly BIOS on this machine has no option in order to select which cards you want to use definitly.<br />
<br />
=== 2.3 Keyboard, Automatic light sensor ===<br />
There is nothing to do; within its simply works. Automatic light sensor is located on the right side of hybrid graphics switch.<br />
<br />
=== 2.4 Touchpad ===<br />
ALPS touchpad is recognized as Im/PS2 Wheel Mouse with scrolling on the right edge. It is hard to be recognized as ALPS currently.<br />
A fix that allows for multitouch has been provided here: http://nwoki.wordpress.com/2012/10/02/multitouch-fix-for-alps-touchpad/ <br />
<br />
=== 2.5 Fingerprint ===<br />
Not tested.<br />
<br />
=== 2.6 Web Camera ===<br />
Not tested.<br />
<br />
=== 2.7 TPM ===<br />
Not tested.<br />
<br />
=== 2.8 Optical(Secondary Channel) ===<br />
The button to open this optical drive on the top of keybaord is available by default, power management timer is also good to work (see 3.Power Management > 3.5 Chipset, Optical, USB and more). When it remove/replacement, you can easy to turn only 2 screws or disable from BIOS.<br />
<br />
=== 2.9 HDD/SSD(Primary Channel) ===<br />
You can easy to access in order to remove/replacement. Just open back pannel in front of this machine, then you could see battery on the right, memory module slot on the top-left, and 2.5 inch drive space (9mm height) on this bottom.<br />
<br />
Please note: Press release bar at the bottom of battery, remove it first.<br />
<br />
=== 2.10 Display brightness, Sound volume ===<br />
There is nothing to do; keyboard shortcuts with Fn key are available by default.<br />
<br />
=== 2.11 Gravity Sensor ===<br />
Not tested.<br />
<br />
== 3. Power Management ==<br />
You can get battery life into 4-5 hours (HDDs), 6-7 hours and more (SSDs), even if "ondemand" governor. You never have to give up a performance working with built-in battery only.<br />
<br />
=== 3.1 ACPI modules ===<br />
There is nothing to do. Kernel supports sony_acpi module.<br />
<br />
=== 3.2 Sandy/Ivy bridge issue ===<br />
Sandy/Ivy bridge platforms have to add special options on your [[kernel line]] for intel video power management. These options would be deprecated for near the future. <br />
<br />
pcie_aspm=force i915.i915_enable_rc6=1 i915.i915_enable_fbc=1 i915.lvds_downclock=1<br />
<br />
Please note: Options should be selected by your using style, to know what effects are expected on every option. In fact, some electric reports show less or no evaluate battery life than ever before.<br />
<br />
=== 3.3 Hybrid Graphics ===<br />
Please refer to "2. Hardware > 2.2 Hybrid Graphics" in this article.<br />
<br />
=== 3.4 Wireless (WiFi, Bluetooth, WiMAX) ===<br />
Please refer to wireless wiki, in order to set power management is ON.<br />
<br />
=== 3.5 Chipset, Optical, USB and more ===<br />
Tlp is comletely available and functional except ThinkPad features. To set them manually, please refer to laptop wiki.<br />
<br />
=== 3.6 CPU ===<br />
Cpufrequtils is useful to set govonors. To change voltage manually, cpupower provides better solution currently. <br />
<br />
Please note: If you try to use Gnome 3 with cpupower, confliction with cpufrequtils may arouse. To avoid this, pacman "-Sddf" option is also unfunctional. Please refer to bug report.</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Firefox/Tweaks&diff=349219Firefox/Tweaks2014-12-09T02:27:41Z<p>Jstjohn: /* Turn off OCSP validation */ fix spelling of "Wi-Fi"</p>
<hr />
<div>[[tr:Firefox İpuçları]]<br />
[[Category:Web Browser]]<br />
{{Related articles start}}<br />
{{Related|Firefox}}<br />
{{Related|Browser plugins}}<br />
{{Related|Firefox Ramdisk}}<br />
{{Related articles end}}<br />
<br />
This page contains advanced Firefox configuration options and performance tweaks.<br />
<br />
== Performance ==<br />
<br />
Improving Firefox's performance is divided into parameters that can be inputted while running Firefox or otherwise modifying its configuration as intended by the developers, and advanced procedures that involve foreign programs or scripts.<br />
<br />
{{Note|Always use the latest version of Firefox.}}<br />
<br />
=== Advanced Firefox options ===<br />
This section contains advanced Firefox options for performance tweaking. For additional information see [http://kb.mozillazine.org/Category:Tweaking_preferences these Mozillazine forum posts].<br />
<br />
==== Network settings ====<br />
<br />
Advanced network settings can be found on the {{ic|about:config}} page (try searching for ''network'').<br />
<br />
{| class="wikitable"<br />
|+ Suggested values<br />
! Key || Value || Description<br />
|-<br />
| network.http.pipelining || true || Enable [http://www-archive.mozilla.org/projects/netlib/http/pipelining-faq.html pipelining] for normal connections<br />
|-<br />
| network.http.proxy.pipelining || true || Enable pipelining for proxy connections<br />
|}<br />
<br />
==== Turn off anti-phishing ====<br />
{{Note|Deleting files from your profile folder is potentially dangerous, so it is recommended that you back it up first.}}<br />
<br />
The anti-phishing features of Firefox may cause Firefox to become slow to start or exit. The problem is that Firefox maintains an [[Sqlite]] database that can grow quite big which makes reading and writing slower after repeated use. If you feel that you do not need Firefox to tell you which sites may be suspect you can disable this feature:<br />
<br />
* Turn off the following options under the security tab in preferences: ''"Block reported attack sites"'' and ''"Block reported web forgeries"''.<br />
<br />
* Delete all files beginning with {{ic|urlclassifier}} in your profile folder ({{ic|~/.mozilla/firefox/<profile_dir>/}}):<br />
$ rm -i ~/.mozilla/firefox/<profile_dir>/urlclassifier*<br />
<br />
:Some of these files might be recreated by Firefox, but they won't grow any larger than their initial size.<br />
<br />
==== Stop urlclassifier3.sqlite from being created again ====<br />
If you did remove all the {{ic|urlclassifier*}} files as mentioned above, you may find out that {{ic|urlclassifier3.sqlite}} keeps growing again after a certain time. Here is a simple solution to avoid it for now and ever.<br />
<br />
$ cd ~/.mozilla/firefox/<profile_dir><br />
$ echo "" > urlclassifier3.sqlite<br />
$ chmod 400 urlclassifier3.sqlite<br />
<br />
This effectively makes the file empty and then read-only so Firefox cannot write to it anymore.<br />
<br />
==== Turn off OCSP validation ====<br />
OCSP validation may cause Firefox [http://news.netcraft.com/archives/2013/04/16/certificate-revocation-and-the-performance-of-ocsp.html to become slower] for each (HTTPS) connection to a new server. This is worse, recently, where web gadgets are included in pages via HTTPS (e.g., "like" buttons of the social networks), resulting in many connections for a single URL.<br />
<br />
* Turn off the following option under Preferences -> Advanced -> Certificates -> Validation: ''"Use the Online Certificate Status Protocol (OCSP) to confirm the current validity of certificates"''.<br />
<br />
{{Warning|Disabling OCSP causes vulnerabilities to man-in-the-middle attacks. If you are using a potentially vulnerable connection such as Wi-Fi or VPN, it is strongly advised to leave OCSP on.}}<br />
<br />
==== Turn off the disk cache ====<br />
Every object loaded (html pages, jpeg images, css stylesheets, gif banners) is saved in the Firefox cache, to be loaded in the future without to download it again from the server, but only fraction of these objects will be really reused without download (usually the 30%). This because of too short expiration times for the objects, updates or simply the user behavior (to load new pages instead the ones already visited). The Firefox cache is divided in memory and disk cache and using the disk cache results to frequent disk writes, because every time an object loaded it is written to the disk and some older object is removed.<br />
<br />
* Turn on the following option under the advanced tab in preferences -> Network -> Validation: ''"Override automatic cache management"'' and specify zero in ''"Limit cache to"''.<br />
<br />
==== Longer interval to save session ====<br />
The Firefox session store automatically saves the current status (opened urls, cookies, history and bookmarks) to the disk every 15 seconds. It may be too frequent for the user needs, resulting in a frequent disk access. <br />
<br />
This setting can be found on the {{ic|about:config}} page (try searching for ''sessionstore'').<br />
<br />
* browser.sessionstore.interval 300000<br />
<br />
==== Immediate rendering of pages ====<br />
Mozilla applications render web pages incrementally - they display what's been received of a page before the entire page has been downloaded. Since the start of a web page normally doesn't have much useful information to display, Mozilla applications will wait a short interval before first rendering a page. This preference controls that interval. Note that if you are on slower connections (dial up) changing this setting might make web pages load for longer times even though the page appears faster.<br />
<br />
This setting can be created in the {{ic|about:config}} page as <br />
<br />
* nglayout.initialpaint.delay with a value of 0.<br />
<br />
=== Other modifications ===<br />
This section contains some other modifications that may increase Firefox's performance.<br />
<br />
==== Reduce load time by compressing the Firefox binary with UPX ====<br />
[http://upx.sourceforge.net/ UPX] is an executable packer that supports very fast decompression and induces no memory overhead. It can be [[pacman|installed]] with the {{Pkg|upx}} package, availalble in the [[official repositories]].<br />
<br />
Before using {{ic|upx}} to compress the Firefox executable, make a backup of the binary:<br />
# cp /usr/lib/firefox/firefox /usr/lib/firefox/firefox.backup<br />
<br />
Finally, invoke {{ic|upx}}, applying the best possible compression level:<br />
# upx --best /usr/lib/firefox/firefox<br />
<br />
==== Defragment the profile's SQLite databases ====<br />
{{Warning|This procedure may damage the databases in such a way that sessions are not saved properly.}}<br />
<br />
In Firefox 3.0, bookmarks, history, passwords are kept in an SQLite databases. SQLite databases become fragmented over time and empty spaces appear all around. But, since there are no managing processes checking and optimizing the database, these factors eventually result in a performance hit. A good way to improve start-up and some other bookmarks and history related tasks is to defragment and trim unused space from these databases.<br />
<br />
{{AUR|profile-cleaner}} in the [[AUR]] does just this.<br />
<br />
{| class="wikitable"<br />
|+ Sample size differences comparison<br />
! SQLite database || Size Before || Size After || % change<br />
|- <br />
|urlclassifier3.sqlite|| 37 M || 30 M || 19 %<br />
|-<br />
|places.sqlite || 16 M || 2.4 M || 85 %<br />
|-<br />
|}<br />
<br />
==== Cache the entire profile into RAM via tmpfs ====<br />
If the system has memory to spare, {{ic|tmpfs}} can be used to [[Firefox Ramdisk|cache the entire profile directory]], which might result in increased Firefox responsiveness.<br />
<br />
== Appearance ==<br />
=== Fonts ===<br />
See the main article: [[Font configuration]]<br />
<br />
==== Configure the DPI value ====<br />
Modifying the following value can help improve the way fonts looks in Firefox if the system's DPI is below 96. Firefox, by default, uses 96 and only uses the system's DPI if it is a higher value. To force the system's DPI regardless of its value, type {{ic|about:config}} into the address bar and set {{ic|layout.css.dpi}} to '''0'''.<br />
<br />
Note that the above method only affects the Firefox user interface's DPI settings. Web page contents still use a DPI value of 96, which may look ugly or, in the case of high-resolution displays, may be rendered too small to read. A solution is to change {{ic|layout.css.devPixelsPerPx}} to system's DPI divided by 96. For example, if your system's DPI is 144, then the value to add is 144/96 = 1.5. Changing {{ic|layout.css.devPixelsPerPx}} to '''1.5''' makes web page contents use a DPI of 144, which looks much better.<br />
<br />
See also [[HiDPI#Firefox]] for information about HiDPI displays.<br />
<br />
==== Default font settings from Microsoft Windows ====<br />
Below are the default font preferences when Firefox is installed in Microsoft Windows. Many web sites use the Microsoft fonts.<br />
{{bc|<br />
Proportional: Serif Size (pixels): 16<br />
Serif: Times New Roman<br />
Sans-serif: Arial<br />
Monospace: Courier New Size (pixels): 13<br />
}}<br />
<br />
=== General user interface CSS settings ===<br />
Firefox's user interface can be modified by editing the {{ic|userChrome.css}} and {{ic|userContent.css}} files in {{ic|~/.mozilla/firefox/<profile_dir>/chrome/}} (''profile_dir'' is of the form ''hash.name'', where the ''hash'' is an 8 character, seemingly random string and the profile ''name'' is usually ''default'').<br />
<br />
{{Note|The {{ic|chrome/}} folder and {{ic|userChrome.css}}/{{ic|userContent.css}} files may not necessarily exist, so they may need to be created.}}<br />
<br />
This section only deals with the {{ic|userChrome.css}} file which modifies Firefox's user interface, and not web pages.<br />
<br />
==== Change the font ====<br />
The setting effectively overrides the global GTK+ font preferences, and does not affect webpages, only the user interface itself:<br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userChrome.css|<br />
* {<br />
font-family: "FONT_NAME";<br />
}<br />
}}<br />
<br />
==== Hide button icons ====<br />
Enables text-only buttons:<br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userChrome.css|<br />
.button-box .button-icon {<br />
display: none;<br />
}<br />
}}<br />
<br />
==== Hiding various tab buttons ====<br />
These settings hide the arrows that appear to the horizontal edges of the tab bar, the button that toggles the "all tabs" drop-down list, and the plus sign button that creates a new tab.<br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userChrome.css|<nowiki><br />
/* Tab bar */<br />
<br />
.tabbrowser-strip *[class^="scrollbutton"] {<br />
/* Hide tab scroll buttons */<br />
display: none;<br />
}<br />
<br />
.tabbrowser-strip *[class^="tabs-alltabs"] {<br />
/* Hide tab drop-down list */<br />
display: none;<br />
}<br />
<br />
.tabbrowser-strip *[class^="tabs-newtab-button"] {<br />
/* Hide new-tab button */<br />
display: none;<br />
}</nowiki><br />
}}<br />
<br />
==== Horizontal tabs ====<br />
To place the tab bar horizontally stacked along the sides of the browser window:<br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userChrome.css|<br />
/* Display the tabbar on the left */<br />
#content > tabbox {<br />
-moz-box-orient: horizontal;<br />
}<br />
<br />
.tabbrowser-strip {<br />
-moz-box-orient: vertical;<br />
/*<br />
* You can set this to -moz-scrollbars-vertical instead,<br />
* but then the scrollbar will *always* be visible. this way<br />
* there is never a scrollbar, so it behaves like the tab bar<br />
* normally does<br />
*/<br />
overflow: -moz-scrollbars-none;<br />
}<br />
<br />
.tabbrowser-tabs {<br />
-moz-box-orient: horizontal;<br />
min-width: 20ex; /* You may want to increase this value */<br />
-mox-box-pack: start;<br />
-moz-box-align: start;<br />
}<br />
<br />
.tabbrowser-tabs > hbox {<br />
-moz-box-orient: vertical;<br />
-moz-box-align: stretch;<br />
-moz-box-pack: start;<br />
}<br />
<br />
.tabbrowser-tabs > hbox > tab {<br />
-moz-box-align: start;<br />
-moz-box-orient: horizontal;<br />
}<br />
}}<br />
<br />
==== Auto-hide Bookmarks Toolbar ====<br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userChrome.css|<br />
#PersonalToolbar {<br />
visibility: collapse !important;<br />
}<br />
<br />
#navigator-toolbox:hover > #PersonalToolbar {<br />
visibility: visible !important;<br />
}<br />
}}<br />
<br />
==== Remove sidebar width restrictions ====<br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userChrome.css|<br />
/* remove maximum/minimum width restriction of sidebar */<br />
#sidebar {<br />
max-width: none !important;<br />
min-width: 0px !important;<br />
}<br />
}}<br />
<br />
=== Web content CSS settings ===<br />
This section deals with the {{ic|userContent.css}} file in which you can add custom CSS rules for web content. Changes to this file will take effect once the browser is restarted.<br />
<br />
This file can be used for making small fixes or to apply personal styles to frequently visited websites. Custom stylesheets for popular websites are available from sources such as [http://userstyles.org/ userstyles.org]. You can install an add-on such as [https://addons.mozilla.org/en-US/firefox/addon/superusercontent/ superUserContent] to manage themes. This add-on creates the directory {{ic|chrome/userContent.css.d}} and applies changes to the CSS files therein when the page is refreshed.<br />
<br />
==== Import other CSS files ==== <br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userContent.css|<br />
@import url("./imports/some_file.css");<br />
}}<br />
<br />
==== Block certain parts of a domain ====<br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userContent.css|<br />
@-moz-document domain(example.com) {<br />
div#header {<br />
background-image: none !important;<br />
} <br />
}<br />
}}<br />
<br />
==== Add [pdf] after links to PDF files ====<br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userContent.css|<nowiki><br />
/* add '[pdf]' next to links to PDF files */<br />
a[href$=".pdf"]:after {<br />
font-size: smaller;<br />
content: " [pdf]";<br />
}</nowiki><br />
}}<br />
<br />
==== Show URLs at the bottom of the screen when hovering a link ====<br />
{{hc|~/.mozilla/firefox/<profile_dir>/chrome/userContent.css|<br />
a[href]:hover {<br />
text-decoration: none !important;<br />
}<br />
<br />
a[href]:hover:after {<br />
content: attr(href);<br />
position: fixed; left: 0px; bottom: 0px;<br />
padding: 0 2px !important;<br />
max-width: 95%; overflow: hidden;<br />
white-space: nowrap; text-overflow: ellipsis;<br />
font:10pt sans-serif !important;<br />
background-color: black !important;<br />
color: white !important;<br />
opacity: 0.7;<br />
z-index: 9999;<br />
}<br />
}}<br />
<br />
==== Firefox 4 New Menu Bar/Firefox Button ====<br />
To toggle between the new Firefox button and the classic menu bar:<br />
* if the button is active, check ''Preferences > Menu Bar'', or right click in the toolbar area and check ''Menu Bar''.<br />
* if the menu bar is active, uncheck ''View > Toolbars > Menu Bar'', or right click in the toolbar area and uncheck ''Menu Bar''.<br />
<br />
In GNU/Linux, you will just get a plain grey button instead of the new orange one from Windows. However you can change this to either a Firefox icon or the icon followed by the "Firefox" text.<br />
<br />
Adding the following to your {{ic|~/.mozilla/firefox/userprofile/chrome/userChrome.css}} file will place the icon before the text:<br />
{{bc|<br />
#appmenu-toolbar-button {<br />
list-style-image: url("chrome://branding/content/icon16.png");<br />
}<br />
}}<br />
<br />
Adding the following to the same file will ''remove'' the "Firefox" text:<br />
{{bc|<br />
#appmenu-toolbar-button > .toolbarbutton-text,<br />
#appmenu-toolbar-button > .toolbarbutton-menu-dropmarker {<br />
display: none !important;<br />
}<br />
}}<br />
<br />
This userChrome.css configuration copies the default Windows Firefox 4+ look and adds an orange background to the button, with a purple background in Private Browsing mode:<br />
{{bc|<br />
#main-window:not([privatebrowsingmode]) #appmenu-toolbar-button {<br />
-moz-appearance: none !important;<br />
color: #FEEDFC !important;<br />
background: -moz-linear-gradient(hsl(34,85%,60%), hsl(26,72%,53%) 95%) !important;<br />
border: 1px solid #000000 !important;<br />
}<br />
<br />
#main-window:not([privatebrowsingmode]) #appmenu-toolbar-button:hover:not(:active):not([open]) {<br />
-moz-appearance: none !important;<br />
color: #FEEDFC !important;<br />
background: -moz-linear-gradient(hsl(26,72%,53%), hsl(34,85%,60%) 95%) !important;<br />
border: 1px solid #000000 !important;<br />
}<br />
<br />
<br />
#main-window:not([privatebrowsingmode]) #appmenu-toolbar-button:hover:active,<br />
#main-window:not([privatebrowsingmode]) #appmenu-toolbar-button[open] {<br />
-moz-appearance: none !important;<br />
color: #FEEDFC !important;<br />
background: -moz-linear-gradient(hsl(26,72%,53%), hsl(26,72%,53%) 95%) !important;<br />
border: 1px solid #000000 !important;<br />
}<br />
<br />
#appmenu-toolbar-button {<br />
-moz-appearance: none !important;<br />
color: #FEEDFC !important;<br />
background: -moz-linear-gradient(hsl(279,70%,46%), hsl(276,75%,38%) 95%) !important;<br />
border: 1px solid #000000 !important;<br />
}<br />
<br />
<br />
#main-window #appmenu-toolbar-button:hover:not(:active):not([open]) {<br />
-moz-appearance: none !important;<br />
color: #FEEDFC !important;<br />
background: -moz-linear-gradient(hsl(276,75%,38%), hsl(279,70%,46%) 95%) !important;<br />
border: 1px solid #000000 !important;<br />
}<br />
<br />
<br />
#main-window #appmenu-toolbar-button:hover:active,<br />
#main-window #appmenu-toolbar-button[open] {<br />
-moz-appearance: none !important;<br />
color: #FEEDFC !important;<br />
background: -moz-linear-gradient(hsl(276,75%,38%), hsl(276,75%,38%) 95%) !important;<br />
border: 1px solid #000000 !important;<br />
}<br />
}}<br />
<br />
{{Note|You need to create both the {{ic|chrome}} directory and {{ic|userChrome.css}}, if they do not already exist.}}<br />
<br />
==== Block ads ====<br />
<br />
See [http://www.floppymoose.com floppymoose.com] for an example of how to use {{ic|userContent.css}} as a basic ad-blocker.<br />
<br />
== Miscellaneous ==<br />
<br />
Other tips and tweaks.<br />
<br />
=== Mouse wheel scroll speed ===<br />
<br />
To modify the default values (i.e. speed-up) of the mouse wheel scroll speed, go to {{ic|about:config}} and search for {{ic|mousewheel.acceleration}}. This will show the available options, modifying the following:<br />
<br />
* Set {{ic|mousewheel.acceleration.start}} to '''-1'''.<br />
* Set {{ic|mousewheel.acceleration.factor}} to the desired number (10 to 20 are common values).<br />
<br />
Alternatively you can install the [http://smoothwheel.mozdev.org/ SmoothWheel add-on].<br />
<br />
=== Change the order of search engines in the Firefox Search Bar ===<br />
<br />
To change the order search engines are displayed in:<br />
* Open the drop-down list of search engines and click ''Manage Search Engines...'' entry.<br />
* Highlight the engine you want to move and use ''Move Up'' or ''Move Down'' to move it. Alternatively, you can use drag-and-drop.<br />
<br />
=== How to open a *.doc automatically with Abiword or LibreOffice Writer ===<br />
<br />
Go to ''Preferences > Applications'' and search for ''Word Document'' (or ''Word 2007 Document'' for {{ic|*.docx}}). After finding it, click the drop-down list and select ''Use other...''. From there you have to specify the exact path to the Abiword or Writer executable (i.e.{{ic|/usr/bin/abiword}} or {{ic|/usr/bin/lowriter}}).<br />
<br />
=== "I'm Feeling Lucky" mode ===<br />
<br />
Some search engines have a "feeling lucky" feature. For example, Google has "I'm Feeling Lucky", and DuckDuckGo has "I'm Feeling Ducky".<br />
<br />
To activate them:<br />
# Type {{ic|about:config}} in the address bar.<br />
# Search for the string {{ic|keyword.url}}.<br />
# Modify its value (if any) to the URL of the search engine. <br />
<br />
For Google, set it to:<br />
{{bc|<nowiki>https://www.google.com/search?btnI=I%27m+Feeling+Lucky&q=</nowiki>}}<br />
For DuckDuckGo, set it to:<br />
{{bc|<nowiki>https://duckduckgo.com/?q=\</nowiki>}}<br />
<br />
=== Secure DNS with DNSSEC validator ===<br />
<br />
You can enable [[DNSSEC]] support for safer browsing.<br />
<br />
=== Adding magnet protocol association ===<br />
<br />
In {{ic|about:config}} set {{ic|network.protocol-handler.expose.magnet}} to '''false'''.<br />
<br />
The next time you open a magnet link, you will be prompted with a {{ic|Launch Application}} dialogue. From there simply select your chosen torrent client. This technique can also be used with other protocols.<br />
<br />
=== Prevent accidental closing ===<br />
<br />
The [https://addons.mozilla.org/en-us/firefox/addon/disable-ctrl-q-shortcut/ Disable Ctrl-Q Shortcut] extension can be installed to prevent unwanted closing of the browser.<br />
<br />
An alternative is to add a rule in your window manager configuration file. For example in openbox add:<br />
<keybind key="C-q"><br />
<action name="Execute"><br />
<execute>false</execute><br />
</action><br />
</keybind><br />
in the ''<keyboard>'' section of your {{ic|rc.xml}} file.<br />
{{Note|This will be effective for every application used under a graphic server.}}<br />
<br />
=== Plugins don't work with latest version ===<br />
<br />
Due to Arch's bleeding edge nature, there can be some compatibility issues with plugins not working with the latest Firefox install (e.g. [http://5digits.org/pentadactyl/index Pentadactyl]). If possible, try installing the nightly/beta builds available, or see [[Downgrading packages]].<br />
<br />
[https://addons.mozilla.org/en-us/firefox/addon/checkcompatibility/?src=userprofile Disable Add-on Compatibility Checks] plugin should take care of spurious compatibility issues when the plugins get disabled, even though they work just fine with the new version.<br />
<br />
=== Jerky or choppy scrolling ===<br />
<br />
Scrolling in Firefox can feel "jerky" or "choppy". A post on [http://forums.mozillazine.org/viewtopic.php?f=8&t=2749475/ MozillaZine] gives settings that work on Gentoo, but reportedly work on Arch Linux as well: <br />
<br />
# Set {{ic|mousewheel.min_line_scroll_amount}} to 40<br />
# Set {{ic|general.smoothScroll}} and {{ic|general.smoothScroll.pages}} to '''false'''<br />
# Set {{ic|image.mem.min_discard_timeout_ms}} to something really large such as 2100000000 but no more than 2140000000. Above that number Firefox will not accept your entry and complain with the error code: "The text you entered is not a number." <br />
# Set {{ic|image.mem.max_decoded_image_kb}} to at least 512K<br />
<br />
Now scrolling should flow smoothly.<br />
<br />
=== WebRTC exposes LAN IP address ===<br />
<br />
{{warning|This method disables WebRTC.}}<br />
To prevent websites from getting your local IP address via [https://en.wikipedia.org/wiki/WebRTC WebRTC]'s peer-to-peer (and JavaScript), open {{ic|about:config}} and set {{ic|media.peerconnection.enabled}} to '''false''' (or use this [https://addons.mozilla.org/en-US/firefox/addon/happy-bonobo-disable-webrtc/ addon]).<br />
<br />
== See also ==<br />
<br />
* [http://kb.mozillazine.org/Knowledge_Base MozillaZine Wiki]<br />
* [http://kb.mozillazine.org/About:config_entries about:config Entries Explained]<br />
* [http://linuxtidbits.wordpress.com/2009/08/01/better-fox-cat-and-weasel/ Firefox tuneup: configuration necessities]<br />
* [http://linuxtidbits.wordpress.com/2013/03/08/firefox-defining-font-type-and-size/ Firefox: Defining font type and size]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=GNOME/Keyring&diff=349218GNOME/Keyring2014-12-09T02:26:36Z<p>Jstjohn: add missing templates; fix grammar; fix capitalization issues in section headings</p>
<hr />
<div>[[Category:GNOME]]<br />
From [https://live.gnome.org/GnomeKeyring/ GnomeKeyring]:<br />
:''GNOME Keyring is a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications.''<br />
{{Note| 1=GNOME Keyring does not support ECDSA keys. See [https://bugzilla.gnome.org/show_bug.cgi?id=641082 Bug 641082].}}<br />
== Installation ==<br />
When using GNOME, gnome-keyring is installed automatically as a part of the {{grp|gnome}} group. Otherwise install {{Pkg|gnome-keyring}} from the [[official repositories]].<br />
<br />
== Manage using GUI ==<br />
# pacman -S seahorse<br />
It is possible to leave the GNOME keyring password blank or change it. In seahorse, in the "View" drop-down menu, select "By Keyring". On the Passwords tab, right click on "Passwords: login" and pick "Change password." Enter the old password and leave empty the new password. You will be warned about using unencrypted storage; continue by pushing "Use Unsafe Storage."<br />
<br />
== Use without GNOME, and without a display manager ==<br />
=== Automatic login ===<br />
If you are using automatic login, then you can disable the keyring manager by setting a blank password on the login keyring.<br />
{{Note| The passwords are stored unencrypted in this case.}}<br />
<br />
=== Console login ===<br />
When using console-based login, the keyring daemon can be started by either [[Wikipedia:Pluggable authentication module|PAM]] or [[xinitrc]]. PAM can also unlock the keyring automatically at login.<br />
<br />
==== PAM method ====<br />
Start the gnome-keyring-daemon from{{ic|/etc/pam.d/login}}:<br />
<br />
Add {{ic|auth optional pam_gnome_keyring.so}} at the end of the {{ic|auth}} section and {{ic|session optional pam_gnome_keyring.so auto_start}} at the end of the {{ic|session}} section.<br />
<br />
{{hc|/etc/pam.d/login|<br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth include system-local-login<br />
auth optional pam_gnome_keyring.so<br />
account include system-local-login<br />
session include system-local-login<br />
session optional pam_gnome_keyring.so auto_start}}<br />
<br />
Next, add {{ic|password optional pam_gnome_keyring.so}} to the end of {{ic|/etc/pam.d/passwd}}.<br />
{{hc|/etc/pam.d/passwd|<br />
<nowiki>#%PAM-1.0<br />
<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
password optional pam_gnome_keyring.so</nowiki>}}<br />
<br />
{{Note|To use automatic unlocking, the same password for the user account and the keyring have to be set.}}<br />
<br />
{{Note|You will still need the code in {{ic|~/.xinitrc}} below in order to export the environment variables required.}}<br />
<br />
==== xinitrc method ====<br />
<br />
Start the gnome-keyring-daemon from [[Xinit]]:<br />
<br />
{{hc|~/.xinitrc|<nowiki><br />
eval $(/usr/bin/gnome-keyring-daemon --start --components=pkcs11,secrets,ssh)<br />
export SSH_AUTH_SOCK<br />
</nowiki>}}<br />
<br />
The skeleton {{ic|.xinitrc}} will start a D-Bus session. See {{bug|13986}} for more info.<br />
<br />
{{Note|{{ic|GNOME_KEYRING_PID}} has been removed, and {{ic|GNOME_KEYRING_CONTROL}} is not written if {{ic|XDG_RUNTIME_DIR}} is set. See [http://ftp.gnome.org/pub/GNOME/sources/gnome-keyring/3.11/gnome-keyring-3.11.92.changes]}}<br />
<br />
If you experience problems retrieving information from the keyring, make sure that the variables {{ic|DBUS_SESSION_BUS_ADDRESS}} is exported in the target environment. ({{ic|DBUS_SESSION_BUS_PID}} is no longer exported)<br />
<br />
See [[Xfce#SSH_Agents|SSH Agents]] for use in Xfce.<br />
<br />
== Use without GNOME, but with a display manager ==<br />
When using a display manager, the keyring works out of the box for most cases. The following display managers automatically unlock the keyring once you log in:<br />
* GNOME's login manager {{pkg|gdm}}<br />
* Slim {{pkg|slim}}<br />
* LightDM {{pkg|lightdm}}<br />
<br />
For KDM, see [[KDM#KDM_and_Gnome-keyring]].<br />
<br />
If you are using the keyring to unlock your SSH keys though, make sure to configure {{ic|~/.zshenv}} as shown below.<br />
<br />
{{hc|~/.zshenv|<nowiki><br />
if [ -n "$DESKTOP_SESSION" ];then<br />
eval $(gnome-keyring-daemon --start --components=ssh)<br />
export SSH_AUTH_SOCK<br />
fi</nowiki>}}<br />
<br />
{{Note| 1=The GNOME Keyring Daemon no longer exposes {{ic|GNOME_KEYRING_PID}}. See [https://mail.gnome.org/archives/commits-list/2014-March/msg03864.html commit].}}<br />
<br />
== Disable keyring daemon ==<br />
In case if you run your own version of the SSH agent (e.g. [[SSH keys#ssh-agent|ssh-agent]]), you need to disable the SSH component in GNOME keyring daemon:<br />
ln -sf /dev/null /etc/xdg/autostart/gnome-keyring-ssh.desktop<br />
Then you need to logout to make the effect.<br />
<br />
== SSH keys ==<br />
To add your SSH key:<br />
<br />
$ ssh-add ~/.ssh/id_dsa<br />
Enter passphrase for /home/mith/.ssh/id_dsa:<br />
<br />
To list automatically loaded keys:<br />
<br />
$ ssh-add -L<br />
<br />
To disable all keys;<br />
<br />
$ ssh-add -D<br />
<br />
Now when you connect to a server, the key will be found and a dialog will popup asking you for the passphrase. It has an option to automatically unlock the key when you log in. If you check this, you will not need to enter your passphrase again!<br />
<br />
Alternatively, to permanently save the a passphrase in the keyring, use seahorse-ssh-askpass from package {{pkg|seahorse}}:<br />
<br />
/usr/lib/seahorse/seahorse-ssh-askpass my_key<br />
<br />
{{Note|You have to have a have the corresponding {{ic|.pub}} file in the same directory as the private key ({{ic|~/.ssh/id_dsa.pub}} in the example). Also, make sure that the public key is the file name of the private key plus {{ic|.pub}} (for example, {{ic|my_key.pub}}).}}<br />
<br />
== Integration with applications ==<br />
<br />
* [[Firefox#GNOME_Keyring_integration]]<br />
<br />
== GNOME Keyring dialog and SSH ==<br />
<br />
Run in a terminal, the following:<br />
<br />
$ gnome-keyring-daemon -s<br />
<br />
Output will get a few lines, but in reality we are interested, {{ic|SSH_AUTH_SOCK}}, example:<br />
<br />
GNOME_KEYRING_C.................<br />
SSH_AUTH_SOCK=/run/user/1000/keyring-XXXXXX/ssh<br />
GPG_AGENT_INF...................<br />
<br />
Now you should add to your {{ic|~/.bashrc}}, according to the output of the previous command, for example:<br />
<br />
SSH_AUTH_SOCK=`ss -xl | grep -o '/run/user/1000/keyring.*/ssh'`<br />
[ -z "$SSH_AUTH_SOCK" ] || export SSH_AUTH_SOCK<br />
<br />
If you run on your terminal the following:<br />
<br />
$ echo $SSH_AUTH_SOCK<br />
<br />
will return something like the following:<br />
<br />
/run/user/1000/keyringXXXXXX/ssh<br />
<br />
Now when you connect with ssh, gnome-keyring dialog will launch the "entry of the passphrase"<br />
<br />
== Flushing passphrases ==<br />
<br />
gnome-keyring-daemon -r -d<br />
<br />
This command starts gnome-keyring-daemon, shutting down previously running instances.<br />
<br />
== GNOME Keyring and Git ==<br />
The GNOME keyring is useful in conjuction with [[Git]] when you are pushing over HTTPS.<br />
<br />
First install the package {{pkg|libgnome-keyring}} from the [[official repositories]].<br />
<br />
Next compile the helper:<br />
$ cd /usr/share/git/credential/gnome-keyring<br />
# make<br />
Set Git up to use the helper:<br />
$ git config --global credential.helper /usr/share/git/credential/gnome-keyring/git-credential-gnome-keyring<br />
Next time you do a ''git push'', you are asked to unlock your keyring, if not unlocked already.<br />
<br />
== Useful tools ==<br />
=== gnome-keyring-query ===<br />
{{AUR|gnome-keyring-query}} from the AUR provides a simple command-line tool for querying passwords from the password store of the GNOME Keyring.</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Cinnamon&diff=349217Cinnamon2014-12-09T01:22:36Z<p>Jstjohn: /* Networking */ fix capitalization</p>
<hr />
<div>[[Category:Desktop environments]]<br />
[[ja:Cinnamon]]<br />
[[ru:Cinnamon]]<br />
[[zh-CN:Cinnamon]]<br />
[[tr:Cinnamon_Masaüstü_Ortamı]]<br />
{{Related articles start}}<br />
{{Related|Nemo}}<br />
{{Related|GNOME}}<br />
{{Related|MATE}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related articles end}}<br />
<br />
[http://cinnamon.linuxmint.com/ Cinnamon] is a Linux desktop which provides advanced innovative features and a traditional user experience. <br />
The desktop layout is similar to GNOME Panel (GNOME 2); however, the underlying technology was forked from GNOME Shell (GNOME 3).<br />
The emphasis is put on making users feel at home and providing them with an easy to use and comfortable desktop experience. As of version 2.0, Cinnamon is a complete desktop environment and not merely a frontend for GNOME like GNOME Shell and Unity.<br />
<br />
== Installation ==<br />
<br />
Cinnamon can be [[Pacman|installed]] with the package {{Pkg|cinnamon}}, available in the [[official repositories]].<br />
<br />
== Starting Cinnamon ==<br />
<br />
=== Graphical log-in ===<br />
<br />
Choose ''Cinnamon'' or ''Cinnamon (Software Rendering)'' from the menu in a [[display manager]] of choice. Cinnamon is the 3D accelerated version, which should normally be used. If you experience problems with your video driver (e.g. artifacts or crashing), try the ''Cinnamon (Software Rendering)'' session, which disables 3D acceleration.<br />
<br />
=== Starting Cinnamon manually ===<br />
<br />
If you prefer to start Cinnamon manually from the console, add the following line to [[Xinitrc]] (cinnamon 1.9 and up):<br />
<br />
{{hc|~/.xinitrc|<br />
exec cinnamon-session<br />
}}<br />
<br />
If the ''Cinnamon (Software Rendering)'' session is required, use {{ic|cinnamon-session-cinnamon2d}} instead of {{ic|cinnamon-session}}.<br />
<br />
== Configuration ==<br />
<br />
Cinnamon is quite easy to configure &mdash; a lot of the configuration that most people will want can be done graphically. Its usability can be customized with [http://cinnamon-spices.linuxmint.com/applets applets] and [http://cinnamon-spices.linuxmint.com/extensions extensions], and also it supports [http://cinnamon-spices.linuxmint.com/themes theming]. <br />
<br />
=== Cinnamon settings ===<br />
<br />
''cinnamon-settings'' launches a settings module specified on the command line. Without (correct) arguments, it launches ''System Settings''. For example, to start the panel settings:<br />
<br />
$ cinnamon-settings panel<br />
<br />
To list all available modules:<br />
<br />
$ pacman -Ql cinnamon | grep -o "cs_.*\.py" | awk -F'[_.]' '{ print $2 }'<br />
<br />
==== Networking ====<br />
<br />
To add support for the networking module, enable [[NetworkManager#Configuration|Network Manager]]. In order for NetworkManager to store Wi-Fi passwords, you will need to also install [[GNOME Keyring]].<br />
<br />
==== Bluetooth ====<br />
<br />
{{warning|{{AUR|cinnamon-bluetooth}} is incompatible with GNOME 3.10 and above. See the [[Bluetooth]] article for alternatives.}}<br />
<br />
A GNOME bluetooth frontend for Cinnamon Panel and Cinnamon Settings is available in the AUR under the name {{AUR|cinnamon-bluetooth}}. However, as of 18th November 2014 neither of the cinnamon-bluetooth packages currently build or work properly.<br />
<br />
=== Applets and extensions ===<br />
<br />
While an '''applet''' is an addition to the Cinnamon panel, an '''extension''' can fully change the Cinnamon experience. They can be installed from the [[AUR]], ([https://aur.archlinux.org/packages.php?O=0&K=cinnamon-&do_Search=Go package search]), or from inside Cinnamon (''Get more online''):<br />
<br />
$ cinnamon-settings applets<br />
$ cinnamon-settings extensions<br />
<br />
Alternatively, install manually from [http://cinnamon-spices.linuxmint.com/ Cinnamon spices].<br />
<br />
{{Note|If applets do not appear, restart Cinnamon with {{ic|r}} in the {{ic|Alt+F2}} dialog box.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Creating custom applets/themes ===<br />
<br />
The official tutorial on creating an '''applet''' can be found [http://cinnamon.linuxmint.com/?p=156 here], and on creating a '''custom theme''' can be found [http://cinnamon.linuxmint.com/?p=144 here].<br />
<br />
=== Default desktop background wallpaper path ===<br />
<br />
When you add a wallpaper from a custom path in Cinnamon Settings, Cinnamon copies it to {{ic|~/.cinnamon/backgrounds}}. Thus, with every change of your wallpaper you would have to add your updated wallpaper again from the settings menu or copy / symlink it manually to {{ic|~/.cinnamon/backgrounds}}.<br />
<br />
=== Show home, filesystem desktop icons ===<br />
<br />
By default Cinnamon starts with desktop icons enabled but with no desktop icons on screen. To show desktop icons for the home folder, the filesystem, the trash, mounted volumes and network servers open Cinnamon settings and click on desktop. Enable the checkboxes of the icons you want to see on screen.<br />
<br />
=== Adding custom command launchers to the Menu applet ===<br />
<br />
The Menu applet supports launching custom commands. Right click on the applet, click on ''Configure...'' and then ''Open the menu editor''. Select a sub-menu (or create a new one) and select ''New Item''. Set ''Name'', ''Command'' and ''Comment''. Check the launch in terminal checkbox if needed. Leave unchecked for graphical applications. Click ''OK'' and close the menu editor afterwards. The launcher is added to the menu.<br />
<br />
=== Workspaces ===<br />
<br />
A workspace pager can be added to the panel. Right click the panel and choose the option ''Add applets to the panel''. Add the ''Workspace switch'' applet to the panel. To change its position right click on the panel and change the ''Panel edit mode'' on/off switch to on. Click and drag the switcher to the desired position and turn the panel edit mode off when finished.<br />
<br />
By default there are 2 workspaces. To add more, hit {{ic|Control+Alt+Up}} to show all workspaces. Then click on the plus sign button on the right of the screen to add more workspaces.<br />
<br />
Alternatively, you can choose the number by command-line:<br />
$ gsettings set org.cinnamon number-workspaces 4<br />
Replacing 4 with the number of workspaces you want. To apply the change you need to reboot Cinnamon (for example : Alt-F2 and command r).<br />
<br />
=== Hide desktop icons ===<br />
<br />
The desktop icons rendering feature is enabled in nemo by default. To disable this feature, change the setting with the following command: <br />
<br />
$ gsettings set org.nemo.desktop show-desktop-icons false<br />
<br />
=== GTK themes and icons ===<br />
<br />
Linux Mint styled themes and icons can be installed from AUR using packages {{AUR|mint-themes}} and {{AUR|mint-x-icons}}. The themes can be edited in {{ic|Settings → Themes → Other settings}}.<br />
<br />
=== Resize windows by mouse ===<br />
<br />
To resize windows with {{ic|Alt+Right click}}, use {{ic|gsettings}}:<br />
<br />
gsettings set org.cinnamon.desktop.wm.preferences resize-with-right-button true<br />
<br />
=== Portable keybindings ===<br />
<br />
To export your keyboard shortcut keys, you should do:<br />
<br />
dconf dump /org/cinnamon/muffin/keybindings/ >keybindings-backup.dconf<br />
<br />
To later import it (for example) on another computer, do:<br />
<br />
dconf load /org/cinnamon/muffin/keybindings/ <keybindings-backup.dconf<br />
<br />
== Troubleshooting ==<br />
<br />
=== QGtkStyle unable to detect the current theme ===<br />
<br />
Installing {{Pkg|libgnome-data}} solves the problem partially, and QGtkStyle will detect the current GTK+ theme. However, to set the same icon and cursor theme, users must specify them explicitly.<br />
<br />
The icon theme for Qt apps can be configured by the following command:<br />
<br />
$ gconftool-2 --set --type string /desktop/gnome/interface/icon_theme Faenza-Dark<br />
<br />
This sets the icon theme to Faenza-Dark located in {{ic|/usr/share/icons/Faenza-Dark}}. <br />
<br />
The cursor theme for Qt apps can be selected by creating a symbolic link:<br />
<br />
$ mkdir ~/.icons<br />
$ ln -s /usr/share/icons/Adwaita ~/.icons/default<br />
<br />
This sets the cursor theme to Adwaita located in {{ic|/usr/share/icons/Adwaita}}.<br />
<br />
=== Pressing power buttons suspend the system ===<br />
<br />
This is the default behaviour. To change the setting open the {{ic|cinnamon-settings}} panel and click on the "Power Management" option. Change the "When the power button is pressed" option to your desired behaviour.<br />
<br />
=== Volume level is not saved ===<br />
<br />
The volume level is not be saved after reboot. The volume will be at 0 but not muted. Installing {{Pkg|alsa-utils}} will solve the problem.<br />
<br />
=== cinnamon-settings: No module named Image ===<br />
<br />
If {{ic|cinnamon-settings}} does not start with the message that it cannot find a certain module, e.g. the Image module, it is likely that it uses outdated compiled files which refer to no longer existing file locations. In this case remove all {{ic|*.pyc}} files in {{ic|/usr/lib/cinnamon-settings}} and its sub-folders.<br />
<br />
=== Cannot add/remove/change languages used in Cinnamon ===<br />
<br />
The language module was removed from the Cinnamon Control Panel with the release of Cinnamon 2.2 and provided a new package for changing the language settings.<br />
<br />
'''To add/remove languages''', see [[Locale]].<br />
<br />
'''To change between enabled languages''', install the {{AUR|mintlocale}} package.</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Laptop/Lenovo&diff=349216Laptop/Lenovo2014-12-09T01:20:27Z<p>Jstjohn: /* ThinkPad */ fix link to non-existent article</p>
<hr />
<div>[[Category:Hardware Compatibility List]]<br />
{{Hardware compatibility list navigation}}<br />
{{HCL/Laptops navigation}}<br />
<br><br />
<br />
== IBM/Lenovo ==<br />
<br />
=== ThinkPad ===<br />
<br />
{{HCL/Laptops table header}}<br />
| IBM ThinkPad 380ED || NA|| NA || NA || NA || No || NA || NA || NA || ||<br />
|-<br />
| [[IBM ThinkPad T21]] || Yes* || Yes || Yes || NA || NA || Yes* || NA || NA || See below ||<br />
|-<br />
| [[IBM ThinkPad T23]] || Yes || Yes || Yes || NA || NA || Yes || NA || NA || ||<br />
|-<br />
| [[IBM ThinkPad T42]] || Yes || Yes || Yes || Yes || NA || Yes || NA || NA || ||<br />
|-<br />
| IBM ThinkPad T60 || Yes || Yes || Yes || Yes || Yes || Yes || ? || NA || ||<br />
|-<br />
| IBM ThinkPad T60p || Yes || Yes || Yes || Yes || Yes || Yes || ? || ThinkFinger || ||<br />
|-<br />
| [[IBM ThinkPad T61]] || Yes || Yes || Yes || Yes* || NA || Yes || NA || || ||<br />
|-<br />
| IBM ThinkPad T61p || Yes || Yes || Yes || Yes || Yes || Yes || NA || || ||<br />
|-<br />
| IBM ThinkPad X23 || Yes || Yes || Yes || NA || NA || Yes || NA || NA || ||<br />
|-<br />
| [[IBM ThinkPad X60s]] || Yes|| Yes || Yes || Yes || Yes || Yes || NA || NA || ||<br />
|-<br />
| Lenovo ThinkPad X61s || Yes || Yes || Yes || Yes || Yes || Yes || Yes || SD slot || ||<br />
|-<br />
| Lenovo ThinkPad R60 || Yes || Yes || Yes || Yes || Yes || Yes || NA || NA || ||<br />
|-<br />
| Lenovo 3000 N200 || Yes || Yes* || Yes || Yes || Yes || Yes* || NA || NA || See below ||<br />
|-<br />
| IBM ThinkPad R50,R52 || Yes || Yes || Yes || Yes || NA || Yes || Yes || Infrared* || ||<br />
|-<br />
| [[Lenovo ThinkPad X100e]] || Yes|| Yes || Yes || Yes || Yes || Yes || Not tested || SD card (Yes), Webcam (Yes) || ||<br />
|-<br />
| [[Lenovo ThinkPad X200]] || Yes|| Yes || Yes || Yes || Yes || Yes || NA || NA || ||<br />
|-<br />
| Lenovo IdeaPad S10 || Yes || Yes || Yes || Yes* || NA || Yes || NA || NA || ||<br />
|-<br />
| [[Lenovo IdeaPad S400 Touch]] || Yes || Yes || Yes || Yes || Yes || Yes || Not tested || NA || ||<br />
|-<br />
| [[Lenovo IdeaPad Flex 10]] || Yes || Yes* || Yes || NA || Yes || Yes || Yes || NA || Touchscreen* || ||<br />
|-<br />
| [[Lenovo ThinkPad T400]] || Yes || Yes || Yes || Yes || Yes || Yes || NA || NA || ||<br />
|-<br />
| [[Lenovo ThinkPad T400s]] || Yes || Yes || Yes || Yes || Yes || Yes || NA || NA || ||<br />
|-<br />
| [[Lenovo ThinkPad T410]] || Yes || Yes || Yes || Yes || Yes || Yes || NA || NA || ||<br />
|-<br />
| [[Lenovo ThinkPad T420]] || Yes || Yes || Yes || Yes || Not tested|| Yes* || NA || NA || ||<br />
|-<br />
| [[Lenovo ThinkPad T420s]] || Yes || Yes || Yes || Yes || Yes || Yes || NA || Card Reader || See below ||<br />
|-<br />
| [[#Lenovo_ThinkPad_T440p|Lenovo ThinkPad T440p]] || Yes || Yes || Yes || Yes || Yes || Yes* || NA || Card Reader || See below ||<br />
|-<br />
| Lenovo ThinkPad T500 || Yes || Yes || Yes || Yes || Not tested || Yes || NA || NA || ||<br />
|-<br />
| [[Lenovo ThinkPad T520]] || Yes || Yes || Yes || Yes || Yes || Yes || NA || NA || ||<br />
|-<br />
| [[Lenovo ThinkPad T530]] || Yes || Yes || Yes || Yes || Yes || Yes || Yes || NA || ||<br />
|-<br />
| Lenovo ThinkPad E420s || Yes || Yes || Yes || Yes || Not tested || Yes || NA || SDcard (Yes), Webcam (Yes), Trackpoint (No) || ||<br />
|-<br />
| Lenovo ThinkPad L420 || Yes || Yes || Yes || Yes || Yes || Not tested || Yes || NA || ||<br />
|-<br />
| Lenovo ThinkPad L430 || Yes || Yes || Yes || Yes || Yes || Yes || Yes || NA || Trackpoint* ||<br />
|-<br />
| Lenovo ThinkPad L530 || Yes || Yes || Yes || Yes || Yes || Yes || Yes || NA || Trackpoint*, Fingerprint reader ||<br />
|-<br />
| [[Lenovo ThinkPad Edge E430]] || Yes || Yes || Yes* || Yes* || Not tested || Yes || NA || SD card (yes) || ||<br />
|-<br />
| [[Lenovo ThinkPad Edge E530]] || Yes || Yes || Yes* || Yes* || Yes || Yes || NA || SD card (yes), Finger Print (not tested) || ||<br />
|-<br />
|}<br />
<br />
== Special Notes (*): ==<br />
<br />
=== IBM ThinkPad T21 ===<br />
* Video: <br />
** Incapable of running DRM at 1024x768 and 24-bit color due to 8 MB VRAM. Must drop color or resolution to get DRM.<br />
** For whatever reason, external VGA output (for an external monitor) was disabled. This was fixed by doing this:<br />
*** {{ic|echo 1 > /proc/acpi/video/VID/DOS}}<br />
<br />
=== [[Lenovo Thinkpad T61]] ===<br />
* Wireless:<br />
** While both the ''iwl3945'' and ''ipw3956'' drivers work, the ''iwl3956'' driver provides better transfer speeds and a working Wi-Fi LED activity light.<br />
<br />
=== Lenovo 3000 N200 ===<br />
* Sound: <br />
** You may have to append <code>options snd_hda_intel model=lenovo</code> to <code>/etc/modprobe.d/modprobe.conf</code> for sound to work.<br />
<br />
=== IBM ThinkPad R52 ===<br />
* USB network tethering<br />
** Inbound networking via interface ''usb0'' works.<br />
<br />
=== Lenovo IdeaPad S10 ===<br />
* Wireless:<br />
** Install {{AUR|broadcom-wl}} driver. See: [[Broadcom BCM4312]]<br />
<br />
=== Lenovo ThinkPad T420 ===<br />
==== Power management ====<br />
<br />
TP_smapi is not currently supported.<br />
<br />
==== Backlight controls ====<br />
<br />
One user has reported that the brightness controls (fn+home, fn+end) did not work in some desktop environments. This could be fixed by adding the following kernel options:<br />
<br />
acpi_backlight=vendor acpi_osi=Linux<br />
<br />
Also try to adjust the display in the console and not in X windows. If you don't have the keybindings correct in X, it will cause a problem. This can be bypassed if you use a virtual console to adjust the brightness.<br />
<br />
=== Lenovo ThinkPad T420s ===<br />
Multi-touch trackpad works along with scrolling and gestures, just [[pacman|install]] {{Pkg|xf86-input-synaptics}}.<br />
<br />
For more information on the installation process, refer to [http://snott.net/linux/thinkparch-archlinux-on-a-thinkpad/ this page].<br />
<br />
=== Lenovo ThinkPad T440p ===<br />
<br />
Nearly everything Just Works out of the box. Gotchas:<br />
<br />
* UEFI. gummiboot works fine, and dual-booting Windows works nicely.<br />
* ClickPad: the whole trackpad clicks, and disabling the trackpad using synclient makes the trackpoint essentially unusable.<br />
** If you don't use the trackpoint, that shouldn't be a problem.<br />
** If you ''do'' use the trackpoint, read [http://who-t.blogspot.com.au/2014/03/xorg-synaptics-support-for-lenovo-t440.html this article] (as yet untested, but the [http://who-t.blogspot.com.au/2013/12/lenovo-t440-touchpad-button.html previous version] works "fine").<br />
* Audio:<br />
** HDMI audio is the default audio output device. Consult the [[Advanced_Linux_Sound_Architecture|ALSA]] page for details on changing the default.<br />
** Like the X100e/Mini10, it's possible to mute the headset and speaker outputs separately to the master. Bizarrely, muting the speaker output improves bass output on the headset port.<br />
* The fingerprint sensor is a Validity VFS5011, which requires [https://github.com/abbradar/fprint_vfs5011 a patched fprintd] and is apparently highly unreliable.<br />
* thinkpad_acpi:<br />
** Controlling the Fn-Lock, Mute, Mic Mute or 'glowing I' LEDs is apparently not possible.<br />
** fan control doesn't seem to work.<br />
* Graphics and Video:<br />
** With the integrated GPU, [[xrandr]] can crash while attaching or detaching displays connected via the dock.<br />
** The built-in miniDisplayPort will sometimes spew I²C issues into the kernel log.<br />
** [[VA-API]] is highly recommended as it performs significantly better than CPU decoding of large media files.<br />
** '''The BIOS should not be upgraded past version 1.14, as newer BIOSes cause memory corruption when used with Bumblebee.''' See [https://github.com/Bumblebee-Project/bbswitch/issues/78#issuecomment-42741698 Bumblebee GitHub]<br />
* Connectivity:<br />
** Bluetooth is ''extremely'' fragile. The controller works fine most of the time, but can cause the system to wedge totally on sleep/wake cycles, especially if a connection was active at sleep. Disable the controller using {{ic|bluetoothctl}} before sleeping.<br />
<br />
=== Lenovo ThinkPad E430 ===<br />
See [[Lenovo ThinkPad Edge E430]] for more information.<br />
* Ethernet:<br />
** Default card is a Realtek RTL8111/8168B. Thus the {{Pkg|r8168}} module should be used.<br />
* Wireless:<br />
** The kernel module ''rtl8192ce'' can be moody. So far, the best fix is to disable the firmware low-power state with {{ic|1=fwlps=0}}.<br />
* SD card:<br />
** Device will be accessible at {{ic|/dev/mmcX}}<br />
* Power management:<br />
** tp_smapi is not supported, but normal power management may be achieved in the usual ways.<br />
<br />
=== Lenovo ThinkPad L430/L530 ===<br />
<br />
==== tpacpi-bat ====<br />
There is an issue with tpacpi-bat not reporting the right value for the stop threshold. This seems to be related to a buggy BIOS and can not be fixed application wise. <br />
<br />
See https://github.com/teleshoes/tpacpi-bat/issues/44<br />
<br />
==== Trackpoint ====<br />
<br />
{{Note|As of kernel 3.17, this workaround is no longer necessary, as the trackpoint fully works out of the box.}}<br />
There are some issues regarding the trackpoint on the ThinkPad L530 and L430 series. See https://bugzilla.kernel.org/show_bug.cgi?id=33292<br />
<br />
{{Warning|The following solution will remove the two-finger-scroll functionality of the touchpad}}<br />
<br />
Load the kernelmodule psmouse with the options proto=bare:<br />
<br />
# echo "options psmouse proto=bare" | sudo tee /etc/modprobe.d/trackpoint-elantech.conf <br />
<br />
To activate the scroll function, create the file {{ic|/usr/share/X11/xorg.conf.d/11-trackpoint-elantech.conf}}:<br />
<br />
{{bc|Section "InputClass"<br />
Identifier "Elantech Trackpoint"<br />
MatchProduct "PS/2 Generic Mouse"<br />
MatchDevicePath "/dev/input/event*"<br />
Option "EmulateWheel" "true"<br />
Option "EmulateWheelButton" "2"<br />
Option "EmulateWheelTimeout" "200" <br />
Option "YAxisMapping" "4 5" # vertikales Scrollen<br />
Option "XAxisMapping" "6 7" # horizontales Scrollen<br />
EndSection}}<br />
<br />
Reload the kernelmodule, the trackpoint should now be usable:<br />
<br />
# modprobe -rv psmouse<br />
# modprobe -v psmouse <br />
<br />
{{Note|For more information see: http://wiki.ubuntuusers.de/Trackpoint#Trackpoint-wird-nicht-erkannt-nur-ThinkPad-L430-530 (German)}}</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Udev&diff=345164Udev2014-11-17T22:31:54Z<p>Jstjohn: /* See also */ lowercase "udev" is the correct formatting; use HTTPS link</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Hardware detection and troubleshooting]]<br />
[[cs:Udev]]<br />
[[de:Udev]]<br />
[[es:Udev]]<br />
[[fr:Udev]]<br />
[[it:Udev]]<br />
[[ja:Udev]]<br />
[[ru:Udev]]<br />
[[zh-CN:Udev]]<br />
[[zh-TW:Udev]]<br />
{{Related articles start}}<br />
{{Related|udisks}}<br />
{{Related articles end}}<br />
<br />
{{ic|udev}} replaces the functionality of both {{ic|hotplug}} and {{ic|hwdetect}}.<br />
<br />
From [[Wikipedia:Udev|Wikipedia article]]:<br />
:''"Udev is the device manager for the Linux kernel. Primarily, it manages device nodes in {{ic|/dev}}. It is the successor of devfs and hotplug, which means that it handles the {{ic|/dev}} directory and all user space actions when adding/removing devices, including firmware load."''<br />
<br />
Udev loads kernel modules by utilizing coding parallelism to provide a potential performance advantage versus loading these modules serially. The modules are therefore loaded asynchronously. The inherent disadvantage of this method is that udev does not always load modules in the same order on each boot. If the machine has multiple block devices, this may manifest itself in the form of device nodes changing designations randomly. For example, if the machine has two hard drives, {{ic|/dev/sda}} may randomly become {{ic|/dev/sdb}}. See below for more info on this.<br />
<br />
== Installation ==<br />
<br />
Udev is now part of {{Pkg|systemd}} and is installed by default on Arch Linux systems. See {{ic|man systemd-udevd.service}} for information.<br />
<br />
== About udev rules ==<br />
<br />
Udev rules written by the administrator go in {{ic|/etc/udev/rules.d/}}, their file name has to end with ''.rules''. The udev rules shipped with various packages are found in {{ic|/usr/lib/udev/rules.d/}}. If there are two files by the same name under {{ic|/usr/lib}} and {{ic|/etc}}, the ones in {{ic|/etc}} take precedence.<br />
<br />
=== Writing udev rules ===<br />
<br />
{{Warning|To mount removable drives, do not call {{ic|mount}} from udev rules. In case of FUSE filesystems, you will get {{ic|Transport endpoint not connected}} errors. Instead use [[udisks]] that handles automount correctly.}}<br />
<br />
* To learn how to write udev rules, see [http://www.reactivated.net/writing_udev_rules.html Writing udev rules].<br />
* To see an example udev rule, follow the [http://www.reactivated.net/writing_udev_rules.html#example-printer Examples] section of the above guide.<br />
<br />
This is an example of a rule that places a symlink {{ic|/dev/video-cam1}} when a webcamera is connected. First, we have found out that this camera is connected and has loaded with the device {{ic|/dev/video2}}. The reason for writing this rule is that at the next boot the device might just as well show up under a different name like {{ic|/dev/video0}}.<br />
<br />
{{hc|# udevadm info -a -p $(udevadm info -q path -n /dev/video2)|<nowiki><br />
Udevadm info starts with the device specified by the devpath and then walks up the chain of parent devices. It prints for every device found, all possible attributes in the udev rules key format. A rule to match, can be composed by the attributes of the device and the attributes from one single parent device.<br />
<br />
looking at device '/devices/pci0000:00/0000:00:04.1/usb3/3-2/3-2:1.0/video4linux/video2':<br />
KERNEL=="video2"<br />
SUBSYSTEM=="video4linux"<br />
...<br />
looking at parent device '/devices/pci0000:00/0000:00:04.1/usb3/3-2/3-2:1.0':<br />
KERNELS=="3-2:1.0"<br />
SUBSYSTEMS=="usb"<br />
...<br />
looking at parent device '/devices/pci0000:00/0000:00:04.1/usb3/3-2':<br />
KERNELS=="3-2"<br />
SUBSYSTEMS=="usb"<br />
...<br />
ATTRS{idVendor}=="05a9"<br />
...<br />
ATTRS{manufacturer}=="OmniVision Technologies, Inc."<br />
ATTRS{removable}=="unknown"<br />
ATTRS{idProduct}=="4519"<br />
ATTRS{bDeviceClass}=="00"<br />
ATTRS{product}=="USB Camera"<br />
...<br />
</nowiki>}}<br />
<br />
From the video4linux device we use {{ic|<nowiki>KERNEL=="video2"</nowiki>}} and {{ic|<nowiki>SUBSYSTEM=="video4linux"</nowiki>}}, then we match the webcam using vendor and product ID's from the usb parent {{ic|<nowiki>SUBSYSTEMS=="usb"</nowiki>}}, {{ic|<nowiki>ATTRS{idVendor}=="05a9"</nowiki>}} and {{ic|<nowiki>ATTRS{idProduct}=="4519"</nowiki>}}.<br />
<br />
{{hc|/etc/udev/rules.d/83-webcam.rules|<nowiki><br />
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="05a9", ATTRS{idProduct}=="4519", SYMLINK+="video-cam1"<br />
</nowiki>}}<br />
<br />
In the example above we create a symlink using {{ic|<nowiki>SYMLINK+="video-cam1"</nowiki>}} but we could easily set user {{ic|<nowiki>OWNER="john"</nowiki>}} or group using {{ic|<nowiki>GROUP="video"</nowiki>}} or set the permissions using {{ic|<nowiki>MODE="0660"</nowiki>}}. However, if you intend to write a rule to do something when a device is being removed, be aware that device attributes may not be accessible. In this case, you will have to work with preset device [[environment variables]]. To monitor those environment variables, execute the following command while unplugging your device:<br />
<br />
# udevadm monitor --environment --udev<br />
<br />
In this command's output, you will see value pairs such as ID_VENDOR_ID and ID_MODEL_ID, which match your previously used attributes "idVendor" and "idProduct". A rule that uses device environment variables may look like this:<br />
<br />
{{hc|/etc/udev/rules.d/83-webcam-removed.rules|<nowiki><br />
ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="05a9", ENV{ID_MODEL_ID}=="4519", RUN+="/path/to/your/script"<br />
</nowiki>}}<br />
<br />
=== List attributes of a device ===<br />
<br />
To get a list of all of the attributes of a device you can use to write rules, run this command:<br />
<br />
# udevadm info -a -n [device name]<br />
<br />
Replace {{ic|[device name]}} with the device present in the system, such as {{ic|/dev/sda}} or {{ic|/dev/ttyUSB0}}.<br />
<br />
If you do not know the device name you can also list all attributes of a specific system path:<br />
<br />
# udevadm info -a -p /sys/class/backlight/acpi_video0<br />
<br />
=== Testing rules before loading ===<br />
<br />
# udevadm test $(udevadm info -q path -n [device name]) 2>&1<br />
<br />
This will not perform all actions in your new rules but it will however process symlink rules on existing devices which might come in handy if you are unable to load them otherwise. You can also directly provide the path to the device you want to test the udev rule for:<br />
<br />
# udevadm test /sys/class/backlight/acpi_video0/<br />
<br />
=== Loading new rules ===<br />
<br />
Udev automatically detects changes to rules files, so changes take effect immediately without requiring udev to be restarted. However, the rules are not re-triggered automatically on already existing devices. Hot-pluggable devices, such as USB devices, will probably have to be reconnected for the new rules to take effect, or at least unloading and reloading the ohci-hcd and ehci-hcd kernel modules and thereby reloading all USB drivers.<br />
<br />
If rules fail to reload automatically<br />
<br />
# udevadm control --reload-rules<br />
<br />
To manually force udev to trigger your rules<br />
<br />
# udevadm trigger<br />
<br />
== Udisks ==<br />
<br />
See [[Udisks]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Accessing firmware programmers and USB virtual comm devices ===<br />
<br />
The following ruleset will allow normal users (within the "users" group) the ability to access the [http://www.ladyada.net/make/usbtinyisp/ USBtinyISP] USB programmer for AVR microcontrollers and a generic (SiLabs [http://www.silabs.com/products/interface/usbtouart CP2102]) USB to UART adapter, the [http://www.atmel.com/tools/AVRDRAGON.aspx?tab=overview Atmel AVR Dragon] programmer, and the [http://www.atmel.com/tools/AVRISPMKII.aspx Atmel AVR ISP mkII]. Adjust the permissions accordingly. Verified as of 31-10-2012.<br />
<br />
{{hc|/etc/udev/rules.d/50-embedded_devices.rules|2=<nowiki><br />
# USBtinyISP Programmer rules<br />
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1781", ATTRS{idProduct}=="0c9f", GROUP="users", MODE="0666"<br />
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="0479", GROUP="users", MODE="0666"<br />
# USBasp Programmer rules http://www.fischl.de/usbasp/<br />
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05dc", GROUP="users", MODE="0666"<br />
<br />
# Mdfly.com Generic (SiLabs CP2102) 3.3v/5v USB VComm adapter<br />
SUBSYSTEMS=="usb", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", GROUP="users", MODE="0666"<br />
<br />
#Atmel AVR Dragon (dragon_isp) rules<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2107", GROUP="users", MODE="0666"<br />
<br />
#Atmel AVR JTAGICEMKII rules<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2103", GROUP="users", MODE="0666"<br />
<br />
#Atmel Corp. AVR ISP mkII<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2104", GROUP="users", MODE="0666"<br />
</nowiki>}}<br />
<br />
=== Execute on USB insert ===<br />
<br />
See the [[Execute on USB insert]] article or the [http://igurublog.wordpress.com/downloads/script-devmon/ devmon wrapper script].<br />
<br />
=== Execute on VGA cable plug in ===<br />
<br />
Create the rule {{ic|/etc/udev/rules.d/95-monitor-hotplug.rules}} with the following content to launch {{Pkg|arandr}} on plug in of a VGA monitor cable:<br />
<br />
KERNEL=="card0", SUBSYSTEM=="drm", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/''username''/.Xauthority", RUN+="/usr/bin/arandr"<br />
<br />
=== Detect new eSATA drives ===<br />
<br />
If your eSATA drive is not detected when you plug it in, there are a few things you can try. You can reboot with the eSATA plugged in. Or you could try<br />
<br />
# echo 0 0 0 | tee /sys/class/scsi_host/host*/scan<br />
<br />
Or you could install {{AUR|scsiadd}} (from the AUR) and try<br />
<br />
# scsiadd -s<br />
<br />
Hopefully, your drive is now in {{ic|/dev}}. If it is not, you could try the above commands while running<br />
<br />
# udevadm monitor<br />
<br />
to see if anything is actually happening.<br />
<br />
=== Mark internal SATA ports as eSATA ===<br />
<br />
If you connected a eSATA bay or an other eSATA adapter the system will still recognize this disk as an internal SATA drive. [[GNOME]] and [[KDE]] will ask you for your root password all the time. The following rule will mark the specified SATA-Port as an external eSATA-Port. With that, a normal GNOME user can connect their eSATA drives to that port like a USB drive, without any root password and so on.<br />
<br />
{{hc|/etc/udev/rules.d/10-esata.rules|2=<nowiki><br />
DEVPATH=="/devices/pci0000:00/0000:00:1f.2/host4/*", ENV{UDISKS_SYSTEM}="0"<br />
</nowiki>}}<br />
<br />
{{Note|The {{ic|DEVPATH}} can be found after connection the eSATA drive with the following commands (replace {{ic|sdb}} accordingly):<br />
<br />
# udevadm info -q path -n /dev/sdb<br />
/devices/pci0000:00/0000:00:1f.2/host4/target4:0:0/4:0:0:0/block/sdb<br />
<br />
# find /sys/devices/ -name sdb<br />
/sys/devices/pci0000:00/0000:00:1f.2/host4/target4:0:0/4:0:0:0/block/sdb<br />
}}<br />
<br />
=== Setting static device names ===<br />
<br />
Because udev loads all modules asynchronously, they are initialized in a different order. This can result in devices randomly switching names. A udev rule can be added to use static device names.<br />
<br />
See also [[Persistent block device naming]] for block devices and [[Network configuration#Device names]] for network devices.<br />
<br />
==== Video devices ====<br />
<br />
For setting up the webcam in the first place, refer to [[Webcam_Setup#Webcam configuration|Webcam configuration]].<br />
<br />
Using multiple webcams, useful for example with {{pkg|motion}} (software motion detector which grabs images from video4linux devices and/or from webcams), will assign video devices as /dev/video0..n randomly on boot. The recommended solution is to create symlinks using an ''udev'' rule (as in the example in [[#Writing udev rules]]):<br />
<br />
{{hc|/etc/udev/rules.d/83-webcam.rules|<nowiki><br />
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="05a9", ATTRS{idProduct}=="4519", SYMLINK+="video-cam1"<br />
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="08f6", SYMLINK+="video-cam2"<br />
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="0840", SYMLINK+="video-cam3"<br />
</nowiki>}}<br />
<br />
{{Note|Using names other than {{ic|/dev/video*}} will break preloading of {{ic|v4l1compat.so}} and perhaps {{ic|v4l2convert.so}}}}<br />
<br />
==== Printers ====<br />
<br />
If you use multiple printers, {{ic|/dev/lp[0-9]}} devices will be assigned randomly on boot, which will break e.g. [[CUPS]] configuration. <br />
<br />
You can create following rule, which will create symlinks under {{ic|/dev/lp/by-id}} and {{ic|/dev/lp/by-path}}, similar to [[Persistent block device naming]] scheme:<br />
<br />
{{hc|/etc/udev/rules.d/60-persistent-printer.rules|<nowiki><br />
ACTION=="remove", GOTO="persistent_printer_end"<br />
<br />
# This should not be necessary<br />
#KERNEL!="lp*", GOTO="persistent_printer_end"<br />
<br />
SUBSYSTEMS=="usb", IMPORT{builtin}="usb_id"<br />
ENV{ID_TYPE}!="printer", GOTO="persistent_printer_end"<br />
<br />
ENV{ID_SERIAL}=="?*", SYMLINK+="lp/by-id/$env{ID_BUS}-$env{ID_SERIAL}"<br />
<br />
IMPORT{builtin}="path_id"<br />
ENV{ID_PATH}=="?*", SYMLINK+="lp/by-path/$env{ID_PATH}"<br />
<br />
LABEL="persistent_printer_end"<br />
</nowiki>}}<br />
<br />
=== Waking from suspend with USB device ===<br />
<br />
First, find vendor and product ID of your device, for example<br />
<br />
{{hc|<nowiki># lsusb | grep Logitech</nowiki>|Bus 007 Device 002: ID 046d:c52b Logitech, Inc. Unifying Receiver}}<br />
<br />
Now change the {{ic|power/wakeup}} attribute of the device and the USB controller it is connected to, which is in this case {{ic|driver/usb7/power/wakeup}}. Use the following rule:<br />
<br />
{{hc|/etc/udev/rules.d/50-wake-on-device.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c52b", ATTR{power/wakeup}="enabled", ATTR{driver/usb7/power/wakeup}="enabled"<br />
</nowiki>}}<br />
<br />
{{Note|Also make sure the USB controller is enabled in {{ic|/proc/acpi/wakeup}}.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Blacklisting modules ===<br />
<br />
In rare cases, udev can make mistakes and load the wrong modules. To prevent it from doing this, you can blacklist modules. Once blacklisted, udev will never load that module. See [[blacklisting]]. Not at boot-time ''or'' later on when a hotplug event is received (eg, you plug in your USB flash drive).<br />
<br />
=== udevd hangs at boot ===<br />
<br />
After migrating to LDAP or updating an LDAP-backed system udevd can hang at boot at the message "Starting UDev Daemon". This is usually caused by udevd trying to look up a name from LDAP but failing, because the network is not up yet. The solution is to ensure that all system group names are present locally.<br />
<br />
Extract the group names referenced in udev rules and the group names actually present on the system:<br />
<br />
# fgrep -r GROUP /etc/udev/rules.d/ /usr/lib/udev/rules.d | perl -nle '/GROUP\s*=\s*"(.*?)"/ && print $1;' | sort | uniq > udev_groups<br />
# cut -f1 -d: /etc/gshadow /etc/group | sort | uniq > present_groups<br />
<br />
To see the differences, do a side-by-side diff:<br />
<br />
# diff -y present_groups udev_groups<br />
...<br />
network <<br />
nobody <<br />
ntp <<br />
optical optical<br />
power | pcscd<br />
rfkill <<br />
root root<br />
scanner scanner<br />
smmsp <<br />
storage storage<br />
...<br />
<br />
In this case, the {{ic|pcscd}} group is for some reason not present in the system. [[Users and groups#Group management|Add the missing groups]]. Also, make sure that local resources are looked up before resorting to LDAP. {{ic|/etc/nsswitch.conf}} should contain the following line:<br />
<br />
group: files ldap<br />
<br />
=== BusLogic devices can be broken and will cause a freeze during startup ===<br />
<br />
This is a kernel bug and no fix has been provided yet.<br />
<br />
=== Some devices, that should be treated as removable, are not ===<br />
<br />
Create a custom udev rule, setting {{ic|UDISKS_SYSTEM_INTERNAL<nowiki>=</nowiki>0}}. For more details, see the manpage of ''udisks''.<br />
<br />
=== Sound problems with some modules not loaded automatically ===<br />
<br />
Some users have traced this problem to old entries in {{ic|/etc/modprobe.d/sound.conf}}. Try cleaning that file out and trying again.<br />
<br />
{{Note|Since {{ic|1=udev>=171}}, the OSS emulation modules ({{ic|snd_seq_oss}}, {{ic|snd_pcm_oss}}, {{ic|snd_mixer_oss}}) are not automatically loaded by default.}}<br />
<br />
=== IDE CD/DVD-drive support ===<br />
<br />
Starting with version 170, udev does not support CD-ROM/DVD-ROM drives that are loaded as traditional IDE drives with the {{ic|ide_cd_mod}} module and show up as {{ic|/dev/hd*}}. The drive remains usable for tools which access the hardware directly, like ''cdparanoia'', but is invisible for higher userspace programs, like KDE.<br />
<br />
A cause for the loading of the ide_cd_mod module prior to others, like sr_mod, could be e.g. that you have for some reason the module piix loaded with your [[initramfs]]. In that case you can just replace it with ata_piix in your {{ic|/etc/mkinitcpio.conf}}.<br />
<br />
=== Optical drives have group ID set to "disk" ===<br />
<br />
If the group ID of your optical drive is set to {{ic|disk}} and you want to have it set to {{ic|optical}}, you have to create a custom udev rule:<br />
<br />
{{hc|/etc/udev/rules.d|2=<nowiki><br />
# permissions for IDE CD devices<br />
SUBSYSTEMS=="ide", KERNEL=="hd[a-z]", ATTR{removable}=="1", ATTRS{media}=="cdrom*", GROUP="optical"<br />
<br />
# permissions for SCSI CD devices<br />
SUBSYSTEMS=="scsi", KERNEL=="s[rg][0-9]*", ATTRS{type}=="5", GROUP="optical"</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [https://www.kernel.org/pub/linux/utils/kernel/hotplug/udev/udev.html udev home page]<br />
* [https://www.linux.com/news/hardware/peripherals/180950-udev An Introduction to udev]<br />
* [http://vger.kernel.org/vger-lists.html#linux-hotplug udev mailing list information]<br />
* [http://jasonwryan.com/blog/2014/01/20/udev/ Scripting with udev]<br />
* [http://www.reactivated.net/writing_udev_rules.html Writing udev rules]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Udev&diff=345161Udev2014-11-17T22:05:02Z<p>Jstjohn: /* Detect new eSATA drives */ add missing templates</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Hardware detection and troubleshooting]]<br />
[[cs:Udev]]<br />
[[de:Udev]]<br />
[[es:Udev]]<br />
[[fr:Udev]]<br />
[[it:Udev]]<br />
[[ja:Udev]]<br />
[[ru:Udev]]<br />
[[zh-CN:Udev]]<br />
[[zh-TW:Udev]]<br />
{{Related articles start}}<br />
{{Related|udisks}}<br />
{{Related articles end}}<br />
<br />
{{ic|udev}} replaces the functionality of both {{ic|hotplug}} and {{ic|hwdetect}}.<br />
<br />
From [[Wikipedia:Udev|Wikipedia article]]:<br />
:''"Udev is the device manager for the Linux kernel. Primarily, it manages device nodes in {{ic|/dev}}. It is the successor of devfs and hotplug, which means that it handles the {{ic|/dev}} directory and all user space actions when adding/removing devices, including firmware load."''<br />
<br />
Udev loads kernel modules by utilizing coding parallelism to provide a potential performance advantage versus loading these modules serially. The modules are therefore loaded asynchronously. The inherent disadvantage of this method is that udev does not always load modules in the same order on each boot. If the machine has multiple block devices, this may manifest itself in the form of device nodes changing designations randomly. For example, if the machine has two hard drives, {{ic|/dev/sda}} may randomly become {{ic|/dev/sdb}}. See below for more info on this.<br />
<br />
== Installation ==<br />
<br />
Udev is now part of {{Pkg|systemd}} and is installed by default on Arch Linux systems. See {{ic|man systemd-udevd.service}} for information.<br />
<br />
== About udev rules ==<br />
<br />
Udev rules written by the administrator go in {{ic|/etc/udev/rules.d/}}, their file name has to end with ''.rules''. The udev rules shipped with various packages are found in {{ic|/usr/lib/udev/rules.d/}}. If there are two files by the same name under {{ic|/usr/lib}} and {{ic|/etc}}, the ones in {{ic|/etc}} take precedence.<br />
<br />
=== Writing udev rules ===<br />
<br />
{{Warning|To mount removable drives, do not call {{ic|mount}} from udev rules. In case of FUSE filesystems, you will get {{ic|Transport endpoint not connected}} errors. Instead use [[udisks]] that handles automount correctly.}}<br />
<br />
* To learn how to write udev rules, see [http://www.reactivated.net/writing_udev_rules.html Writing udev rules].<br />
* To see an example udev rule, follow the [http://www.reactivated.net/writing_udev_rules.html#example-printer Examples] section of the above guide.<br />
<br />
This is an example of a rule that places a symlink {{ic|/dev/video-cam1}} when a webcamera is connected. First, we have found out that this camera is connected and has loaded with the device {{ic|/dev/video2}}. The reason for writing this rule is that at the next boot the device might just as well show up under a different name like {{ic|/dev/video0}}.<br />
<br />
{{hc|# udevadm info -a -p $(udevadm info -q path -n /dev/video2)|<nowiki><br />
Udevadm info starts with the device specified by the devpath and then walks up the chain of parent devices. It prints for every device found, all possible attributes in the udev rules key format. A rule to match, can be composed by the attributes of the device and the attributes from one single parent device.<br />
<br />
looking at device '/devices/pci0000:00/0000:00:04.1/usb3/3-2/3-2:1.0/video4linux/video2':<br />
KERNEL=="video2"<br />
SUBSYSTEM=="video4linux"<br />
...<br />
looking at parent device '/devices/pci0000:00/0000:00:04.1/usb3/3-2/3-2:1.0':<br />
KERNELS=="3-2:1.0"<br />
SUBSYSTEMS=="usb"<br />
...<br />
looking at parent device '/devices/pci0000:00/0000:00:04.1/usb3/3-2':<br />
KERNELS=="3-2"<br />
SUBSYSTEMS=="usb"<br />
...<br />
ATTRS{idVendor}=="05a9"<br />
...<br />
ATTRS{manufacturer}=="OmniVision Technologies, Inc."<br />
ATTRS{removable}=="unknown"<br />
ATTRS{idProduct}=="4519"<br />
ATTRS{bDeviceClass}=="00"<br />
ATTRS{product}=="USB Camera"<br />
...<br />
</nowiki>}}<br />
<br />
From the video4linux device we use {{ic|<nowiki>KERNEL=="video2"</nowiki>}} and {{ic|<nowiki>SUBSYSTEM=="video4linux"</nowiki>}}, then we match the webcam using vendor and product ID's from the usb parent {{ic|<nowiki>SUBSYSTEMS=="usb"</nowiki>}}, {{ic|<nowiki>ATTRS{idVendor}=="05a9"</nowiki>}} and {{ic|<nowiki>ATTRS{idProduct}=="4519"</nowiki>}}.<br />
<br />
{{hc|/etc/udev/rules.d/83-webcam.rules|<nowiki><br />
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="05a9", ATTRS{idProduct}=="4519", SYMLINK+="video-cam1"<br />
</nowiki>}}<br />
<br />
In the example above we create a symlink using {{ic|<nowiki>SYMLINK+="video-cam1"</nowiki>}} but we could easily set user {{ic|<nowiki>OWNER="john"</nowiki>}} or group using {{ic|<nowiki>GROUP="video"</nowiki>}} or set the permissions using {{ic|<nowiki>MODE="0660"</nowiki>}}. However, if you intend to write a rule to do something when a device is being removed, be aware that device attributes may not be accessible. In this case, you will have to work with preset device [[environment variables]]. To monitor those environment variables, execute the following command while unplugging your device:<br />
<br />
# udevadm monitor --environment --udev<br />
<br />
In this command's output, you will see value pairs such as ID_VENDOR_ID and ID_MODEL_ID, which match your previously used attributes "idVendor" and "idProduct". A rule that uses device environment variables may look like this:<br />
<br />
{{hc|/etc/udev/rules.d/83-webcam-removed.rules|<nowiki><br />
ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="05a9", ENV{ID_MODEL_ID}=="4519", RUN+="/path/to/your/script"<br />
</nowiki>}}<br />
<br />
=== List attributes of a device ===<br />
<br />
To get a list of all of the attributes of a device you can use to write rules, run this command:<br />
<br />
# udevadm info -a -n [device name]<br />
<br />
Replace {{ic|[device name]}} with the device present in the system, such as {{ic|/dev/sda}} or {{ic|/dev/ttyUSB0}}.<br />
<br />
If you do not know the device name you can also list all attributes of a specific system path:<br />
<br />
# udevadm info -a -p /sys/class/backlight/acpi_video0<br />
<br />
=== Testing rules before loading ===<br />
<br />
# udevadm test $(udevadm info -q path -n [device name]) 2>&1<br />
<br />
This will not perform all actions in your new rules but it will however process symlink rules on existing devices which might come in handy if you are unable to load them otherwise. You can also directly provide the path to the device you want to test the udev rule for:<br />
<br />
# udevadm test /sys/class/backlight/acpi_video0/<br />
<br />
=== Loading new rules ===<br />
<br />
Udev automatically detects changes to rules files, so changes take effect immediately without requiring udev to be restarted. However, the rules are not re-triggered automatically on already existing devices. Hot-pluggable devices, such as USB devices, will probably have to be reconnected for the new rules to take effect, or at least unloading and reloading the ohci-hcd and ehci-hcd kernel modules and thereby reloading all USB drivers.<br />
<br />
If rules fail to reload automatically<br />
<br />
# udevadm control --reload-rules<br />
<br />
To manually force udev to trigger your rules<br />
<br />
# udevadm trigger<br />
<br />
== Udisks ==<br />
<br />
See [[Udisks]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Accessing firmware programmers and USB virtual comm devices ===<br />
<br />
The following ruleset will allow normal users (within the "users" group) the ability to access the [http://www.ladyada.net/make/usbtinyisp/ USBtinyISP] USB programmer for AVR microcontrollers and a generic (SiLabs [http://www.silabs.com/products/interface/usbtouart CP2102]) USB to UART adapter, the [http://www.atmel.com/tools/AVRDRAGON.aspx?tab=overview Atmel AVR Dragon] programmer, and the [http://www.atmel.com/tools/AVRISPMKII.aspx Atmel AVR ISP mkII]. Adjust the permissions accordingly. Verified as of 31-10-2012.<br />
<br />
{{hc|/etc/udev/rules.d/50-embedded_devices.rules|2=<nowiki><br />
# USBtinyISP Programmer rules<br />
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1781", ATTRS{idProduct}=="0c9f", GROUP="users", MODE="0666"<br />
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="0479", GROUP="users", MODE="0666"<br />
# USBasp Programmer rules http://www.fischl.de/usbasp/<br />
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05dc", GROUP="users", MODE="0666"<br />
<br />
# Mdfly.com Generic (SiLabs CP2102) 3.3v/5v USB VComm adapter<br />
SUBSYSTEMS=="usb", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", GROUP="users", MODE="0666"<br />
<br />
#Atmel AVR Dragon (dragon_isp) rules<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2107", GROUP="users", MODE="0666"<br />
<br />
#Atmel AVR JTAGICEMKII rules<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2103", GROUP="users", MODE="0666"<br />
<br />
#Atmel Corp. AVR ISP mkII<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2104", GROUP="users", MODE="0666"<br />
</nowiki>}}<br />
<br />
=== Execute on USB insert ===<br />
<br />
See the [[Execute on USB insert]] article or the [http://igurublog.wordpress.com/downloads/script-devmon/ devmon wrapper script].<br />
<br />
=== Execute on VGA cable plug in ===<br />
<br />
Create the rule {{ic|/etc/udev/rules.d/95-monitor-hotplug.rules}} with the following content to launch {{Pkg|arandr}} on plug in of a VGA monitor cable:<br />
<br />
KERNEL=="card0", SUBSYSTEM=="drm", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/''username''/.Xauthority", RUN+="/usr/bin/arandr"<br />
<br />
=== Detect new eSATA drives ===<br />
<br />
If your eSATA drive is not detected when you plug it in, there are a few things you can try. You can reboot with the eSATA plugged in. Or you could try<br />
<br />
# echo 0 0 0 | tee /sys/class/scsi_host/host*/scan<br />
<br />
Or you could install {{AUR|scsiadd}} (from the AUR) and try<br />
<br />
# scsiadd -s<br />
<br />
Hopefully, your drive is now in {{ic|/dev}}. If it is not, you could try the above commands while running<br />
<br />
# udevadm monitor<br />
<br />
to see if anything is actually happening.<br />
<br />
=== Mark internal SATA ports as eSATA ===<br />
<br />
If you connected a eSATA bay or an other eSATA adapter the system will still recognize this disk as an internal SATA drive. [[GNOME]] and [[KDE]] will ask you for your root password all the time. The following rule will mark the specified SATA-Port as an external eSATA-Port. With that, a normal GNOME user can connect their eSATA drives to that port like a USB drive, without any root password and so on.<br />
<br />
{{hc|/etc/udev/rules.d/10-esata.rules|2=<nowiki><br />
DEVPATH=="/devices/pci0000:00/0000:00:1f.2/host4/*", ENV{UDISKS_SYSTEM}="0"<br />
</nowiki>}}<br />
<br />
{{Note|The {{ic|DEVPATH}} can be found after connection the eSATA drive with the following commands (replace {{ic|sdb}} accordingly):<br />
<br />
# udevadm info -q path -n /dev/sdb<br />
/devices/pci0000:00/0000:00:1f.2/host4/target4:0:0/4:0:0:0/block/sdb<br />
<br />
# find /sys/devices/ -name sdb<br />
/sys/devices/pci0000:00/0000:00:1f.2/host4/target4:0:0/4:0:0:0/block/sdb<br />
}}<br />
<br />
=== Setting static device names ===<br />
<br />
Because udev loads all modules asynchronously, they are initialized in a different order. This can result in devices randomly switching names. A udev rule can be added to use static device names.<br />
<br />
See also [[Persistent block device naming]] for block devices and [[Network configuration#Device names]] for network devices.<br />
<br />
==== Video devices ====<br />
<br />
For setting up the webcam in the first place, refer to [[Webcam_Setup#Webcam configuration|Webcam configuration]].<br />
<br />
Using multiple webcams, useful for example with {{pkg|motion}} (software motion detector which grabs images from video4linux devices and/or from webcams), will assign video devices as /dev/video0..n randomly on boot. The recommended solution is to create symlinks using an ''udev'' rule (as in the example in [[#Writing udev rules]]):<br />
<br />
{{hc|/etc/udev/rules.d/83-webcam.rules|<nowiki><br />
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="05a9", ATTRS{idProduct}=="4519", SYMLINK+="video-cam1"<br />
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="08f6", SYMLINK+="video-cam2"<br />
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="0840", SYMLINK+="video-cam3"<br />
</nowiki>}}<br />
<br />
{{Note|Using names other than {{ic|/dev/video*}} will break preloading of {{ic|v4l1compat.so}} and perhaps {{ic|v4l2convert.so}}}}<br />
<br />
==== Printers ====<br />
<br />
If you use multiple printers, {{ic|/dev/lp[0-9]}} devices will be assigned randomly on boot, which will break e.g. [[CUPS]] configuration. <br />
<br />
You can create following rule, which will create symlinks under {{ic|/dev/lp/by-id}} and {{ic|/dev/lp/by-path}}, similar to [[Persistent block device naming]] scheme:<br />
<br />
{{hc|/etc/udev/rules.d/60-persistent-printer.rules|<nowiki><br />
ACTION=="remove", GOTO="persistent_printer_end"<br />
<br />
# This should not be necessary<br />
#KERNEL!="lp*", GOTO="persistent_printer_end"<br />
<br />
SUBSYSTEMS=="usb", IMPORT{builtin}="usb_id"<br />
ENV{ID_TYPE}!="printer", GOTO="persistent_printer_end"<br />
<br />
ENV{ID_SERIAL}=="?*", SYMLINK+="lp/by-id/$env{ID_BUS}-$env{ID_SERIAL}"<br />
<br />
IMPORT{builtin}="path_id"<br />
ENV{ID_PATH}=="?*", SYMLINK+="lp/by-path/$env{ID_PATH}"<br />
<br />
LABEL="persistent_printer_end"<br />
</nowiki>}}<br />
<br />
=== Waking from suspend with USB device ===<br />
<br />
First, find vendor and product ID of your device, for example<br />
<br />
{{hc|<nowiki># lsusb | grep Logitech</nowiki>|Bus 007 Device 002: ID 046d:c52b Logitech, Inc. Unifying Receiver}}<br />
<br />
Now change the {{ic|power/wakeup}} attribute of the device and the USB controller it is connected to, which is in this case {{ic|driver/usb7/power/wakeup}}. Use the following rule:<br />
<br />
{{hc|/etc/udev/rules.d/50-wake-on-device.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c52b", ATTR{power/wakeup}="enabled", ATTR{driver/usb7/power/wakeup}="enabled"<br />
</nowiki>}}<br />
<br />
{{Note|Also make sure the USB controller is enabled in {{ic|/proc/acpi/wakeup}}.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Blacklisting modules ===<br />
<br />
In rare cases, udev can make mistakes and load the wrong modules. To prevent it from doing this, you can blacklist modules. Once blacklisted, udev will never load that module. See [[blacklisting]]. Not at boot-time ''or'' later on when a hotplug event is received (eg, you plug in your USB flash drive).<br />
<br />
=== udevd hangs at boot ===<br />
<br />
After migrating to LDAP or updating an LDAP-backed system udevd can hang at boot at the message "Starting UDev Daemon". This is usually caused by udevd trying to look up a name from LDAP but failing, because the network is not up yet. The solution is to ensure that all system group names are present locally.<br />
<br />
Extract the group names referenced in udev rules and the group names actually present on the system:<br />
<br />
# fgrep -r GROUP /etc/udev/rules.d/ /usr/lib/udev/rules.d | perl -nle '/GROUP\s*=\s*"(.*?)"/ && print $1;' | sort | uniq > udev_groups<br />
# cut -f1 -d: /etc/gshadow /etc/group | sort | uniq > present_groups<br />
<br />
To see the differences, do a side-by-side diff:<br />
<br />
# diff -y present_groups udev_groups<br />
...<br />
network <<br />
nobody <<br />
ntp <<br />
optical optical<br />
power | pcscd<br />
rfkill <<br />
root root<br />
scanner scanner<br />
smmsp <<br />
storage storage<br />
...<br />
<br />
In this case, the {{ic|pcscd}} group is for some reason not present in the system. [[Users and groups#Group management|Add the missing groups]]. Also, make sure that local resources are looked up before resorting to LDAP. {{ic|/etc/nsswitch.conf}} should contain the following line:<br />
<br />
group: files ldap<br />
<br />
=== BusLogic devices can be broken and will cause a freeze during startup ===<br />
<br />
This is a kernel bug and no fix has been provided yet.<br />
<br />
=== Some devices, that should be treated as removable, are not ===<br />
<br />
Create a custom udev rule, setting {{ic|UDISKS_SYSTEM_INTERNAL<nowiki>=</nowiki>0}}. For more details, see the manpage of ''udisks''.<br />
<br />
=== Sound problems with some modules not loaded automatically ===<br />
<br />
Some users have traced this problem to old entries in {{ic|/etc/modprobe.d/sound.conf}}. Try cleaning that file out and trying again.<br />
<br />
{{Note|Since {{ic|1=udev>=171}}, the OSS emulation modules ({{ic|snd_seq_oss}}, {{ic|snd_pcm_oss}}, {{ic|snd_mixer_oss}}) are not automatically loaded by default.}}<br />
<br />
=== IDE CD/DVD-drive support ===<br />
<br />
Starting with version 170, udev does not support CD-ROM/DVD-ROM drives that are loaded as traditional IDE drives with the {{ic|ide_cd_mod}} module and show up as {{ic|/dev/hd*}}. The drive remains usable for tools which access the hardware directly, like ''cdparanoia'', but is invisible for higher userspace programs, like KDE.<br />
<br />
A cause for the loading of the ide_cd_mod module prior to others, like sr_mod, could be e.g. that you have for some reason the module piix loaded with your [[initramfs]]. In that case you can just replace it with ata_piix in your {{ic|/etc/mkinitcpio.conf}}.<br />
<br />
=== Optical drives have group ID set to "disk" ===<br />
<br />
If the group ID of your optical drive is set to {{ic|disk}} and you want to have it set to {{ic|optical}}, you have to create a custom udev rule:<br />
<br />
{{hc|/etc/udev/rules.d|2=<nowiki><br />
# permissions for IDE CD devices<br />
SUBSYSTEMS=="ide", KERNEL=="hd[a-z]", ATTR{removable}=="1", ATTRS{media}=="cdrom*", GROUP="optical"<br />
<br />
# permissions for SCSI CD devices<br />
SUBSYSTEMS=="scsi", KERNEL=="s[rg][0-9]*", ATTRS{type}=="5", GROUP="optical"</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [https://www.kernel.org/pub/linux/utils/kernel/hotplug/udev/udev.html Udev Homepage]<br />
* [http://www.linux.com/news/hardware/peripherals/180950-udev An Introduction to Udev]<br />
* [http://vger.kernel.org/vger-lists.html#linux-hotplug Udev mailing list information]<br />
* [http://jasonwryan.com/blog/2014/01/20/udev/ Scripting with udev]<br />
* [http://www.reactivated.net/writing_udev_rules.html Writing udev rules]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Backlight&diff=344674Backlight2014-11-14T20:52:13Z<p>Jstjohn: /* xbacklight */ apply style guide to repo name; use HTTPS in link</p>
<hr />
<div>[[Category:Laptops]]<br />
[[Category:Power management]]<br />
[[ru:Backlight]]<br />
[[ja:Backlight]]<br />
Screen brightness might be tricky to control. On some machines physical hardware switches are missing and software solutions may not work well. However, it is generally posssible; be sure to use a method that works for your hardware.<br />
<br />
There are many ways to adjust the screen backlight of a monitor, laptop or integrated panel (such as the iMac) using software, but depending on hardware and model, sometimes only some options are available. This article aims to summarize all possible ways to adjust the backlight.<br />
<br />
== Overview ==<br />
<br />
There are many ways to control brightness. According to this [https://bugs.launchpad.net/ubuntu/+source/xserver-xorg-video-intel/+bug/397617 discussion] and this wiki page [https://wiki.ubuntu.com/Kernel/Debugging/Backlight] the control method could be divided into these categories:<br />
<br />
* brightness is controlled by vendor-specified hotkey and there is no interface for the OS to adjust the brightness.<br />
* brightness is controlled by the either by ACPI or the graphic driver.<br />
* brightness is controlled by HW register through setpci.<br />
<br />
All methods are exposed to the user through {{ic|/sys/class/backlight}} and xrandr/xbacklight can choose one method to control brightness. It is still not very clear which one xbacklight prefers by default.<br />
<br />
{{note|1=See {{Bug|27677}} for xbacklight, if you get "No outputs have backlight property."'' There is a temporary fix if xrandr/xbacklight does not choose the right directory in {{ic|/sys/class/backlight}}: You can specify the one you want in xorg.conf by setting the "Backlight" option of the Device section to the name of that directory (see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=651741 at the bottom of the page for details).}}<br />
<br />
== ACPI ==<br />
<br />
The brightness of the screen backlight is adjusted by setting the power level of the backlight LEDs or cathodes. The power level can often be controlled using the ACPI kernel module for video. An interface to this module is provided via a folder in the sysfs at {{ic|/sys/class/backlight}}.<br />
<br />
The name of the folder depends on the graphics card model.<br />
{{hc|# ls /sys/class/backlight/|<br />
intel_backlight<br />
}}<br />
<br />
A backlight to adjust example: is managed by an Intel graphics card. It is called {{ic|acpi_video0}} on an ATI card. In the following example, acpi_video0 is used.<br />
<br />
The directory contains the following files and folders:<br />
<br />
actual_brightness brightness max_brightness subsystem/ uevent <br />
bl_power device/ power/ type<br />
<br />
The maximum brightness can be found by reading from {{ic|max_brightness}}, which is often 15.<br />
<br />
{{hc|/sys/class/backlight/acpi_video0/max_brightness|<br />
15<br />
}}<br />
<br />
The brightness can be set by writing a number to {{ic|brightness}}. It is not possible to go any higher than the maximum brightness. <br />
<br />
# tee /sys/class/backlight/acpi_video0/brightness <<< 5<br />
<br />
=== Kernel command-line options ===<br />
<br />
Sometimes, ACPI does not work well due to different motherboard implementations and ACPI quirks. This includes some laptops with dual graphics (e.g. Nvidia/Radeon dedicated GPU with Intel/AMD integrated GPU). On Nvidia Optimus laptops, the kernel parameter nomodeset can interfere with the ability to adjust the backlight. Additionally, ACPI sometimes register its own {{ic|acpi_video0}} backlight even if one already exists (such as {{ic|intel_backlight}}), which results in non working backlight keys. You can try adding the following kernel parameters in your [[bootloader]] to stop ACPI from registering its own backlight interface if one already exists:<br />
<br />
video.use_native_backlight=1<br />
<br />
This is the default as of {{pkg|linux}} 3.16. If that does not work, you can try to adjust the list of supported OS interfaces:<br />
<br />
acpi_osi="!Windows 2012"<br />
<br />
{{Tip|1=<br />
On an Asus notebooks you might also need to do:<br />
<br />
{{bc|# modprobe asus-nb-wmi}}<br />
}}<br />
<br />
{{Note|Disabling legacy boot on Dell XPS13 breaks backlight support.}}<br />
<br />
=== Udev rule ===<br />
<br />
If the ACPI interface is available, the backlight level can be set at boot using a udev rule.<br />
<br />
{{hc|/etc/udev/rules.d/81-backlight.rules|<nowiki><br />
# Set backlight level to 8<br />
SUBSYSTEM=="backlight", ACTION=="add", KERNEL=="acpi_video0", ATTR{brightness}="8"</nowiki>}}<br />
<br />
The systemd-backlight service restores the previous backlight brightness level at boot, whereas this rule sets it to a fixed value. If you want to use this rule, it is necessary to mask the system-backlight service, as explained in [[#systemd-backlight service]].<br />
<br />
== Switching off the backlight ==<br />
<br />
Switching off the backlight (for example when one locks the notebook) can be useful to conserve battery energy. Ideally the following command inside of a graphical session should work:<br />
sleep 1 && xset dpms force off<br />
The backlight should switch on again on mouse movement or keyboard input. If the previous command does not work, there is a chance that {{ic|vbetool}} works. Note, however, that in this case the backlight must be manually activated again. The command is as follows:<br />
vbetool dpms off<br />
To activate the backlight again:<br />
vbetool dpms on<br />
<br />
For example, this can be put to use when closing the notebook lid as outlined in the entry for [[Acpid#Laptop_Monitor_Power_Off|Acipd]].<br />
<br />
== systemd-backlight service ==<br />
<br />
The [[systemd]] package includes the service systemd-backlight@.service, which is enabled by default and "static". It saves the backlight brightness level at shutdown and restores it at boot. The service uses the ACPI method described in [[Backlight#ACPI]], generating services for each folder found in {{ic|/sys/class/backlight/}}. For example, if there is a folder named {{ic|acpi_video0}}, it generates a service called {{ic|systemd-backlight@backlight:acpi_video0.service}}. When using other methods of setting the backlight at boot, it is recommended to mask the service systemd-backlight@.service.<br />
<br />
== Backlight utilities ==<br />
<br />
=== xbacklight ===<br />
<br />
You can adjust the backlight through the xorg-server command {{ic|xbacklight}}. The utility is provided by the {{Pkg|xorg-xbacklight}} package in the ''extra'' repository.<br />
<br />
A useful demonstration was posted by [https://www.youtube.com/watch?v=_pi3iKMAJcY gotbletu on YouTube]. He suggests the following commands to adjust the backlight up and down:<br />
<br />
xbacklight -inc 40<br />
xbacklight -dec 40<br />
<br />
{{Tip|These commands can be bound to keyboard keys as described in [[Extra keyboard keys in Xorg]].}}<br />
<br />
=== power-backlight ===<br />
<br />
Set screen backlight brightness dependent on power source type; with udev rule backlight is adjusted on change of power source. Requires graphic driver support for ACPI in {{ic|/sys/class/backlight}}. Install with the AUR package {{aur|power-backlight-git}}.<br />
<br />
=== light ===<br />
<br />
More information can be found on the [[Light]] page.<br />
<br />
=== relight ===<br />
<br />
[http://xyne.archlinux.ca/projects/relight relight] is available in [http://xyne.archlinux.ca/repos Xyne's repos] and as package {{AUR|relight}} in the [[AUR]]. The package provides {{ic|relight.service}}, a [[systemd]] service to automatically restore previous backlight settings during reboot along using the ACPI method explained above, and ''relight-menu'', a dialog-based menu for selecting and configuring backlights for different screens.<br />
<br />
=== setpci (use with great care) ===<br />
<br />
It is possible to set the register of the graphic card to adjust the backlight. It means you adjust the backlight by manipulating the hardware directly, which can be risky and generally is not a good idea. Not all of the graphic cards support this method.<br />
<br />
When using this method, you need to use {{ic|lspci}} first to find out where your graphic card is.<br />
# setpci -s 00:02.0 F4.B=0<br />
<br />
=== Calise ===<br />
<br />
The software [http://calise.sourceforge.net/wordpress/ calise] can be found in AUR.<br />
* Stable version: {{AUR|calise}}<br />
* Development version: {{AUR|calise-git}} <br />
<br />
It basically computes ambient brightness, and set screen's correct backlight, simply making captures from the webcam, for laptop without light sensor.<br />
For more information, calise has its own wiki: [http://calise.sourceforge.net/mediawiki/index.php/Main_Page Calise wiki].<br />
<br />
The main features of this program are that it is very precise, very light on resource usage, and with the daemon version (.service file for systemd users available too), it has practically no impact on battery life.<br />
<br />
=== brightd ===<br />
<br />
Macbook-inspired {{AUR|brightd}} automatically dims (but does not put to standby) the screen when there is no user input for some time. A good companion of [[Display Power Management Signaling]] so that the screen does not blank out in a sudden.<br />
<br />
=== KDE ===<br />
<br />
[[KDE]] users can adjust the backlight via ''System Settings > Power Management > Energy Saving''.<br />
If you want to set backlight before kdm just put in /usr/share/config/kdm/Xsetup :<br />
<br />
xbacklight -inc 10<br />
<br />
== Color correction ==<br />
<br />
=== xcalib ===<br />
<br />
{{Note|''xcalib'' does ''not'' change the backlight power, it just modifies the video LUT table: this means that your battery life will be unaffected by the change. Nevertheless, it could be useful when no backlight control is available (Desktop PCs). Use {{ic|xcalib -clear}} to reset the LUT.}}<br />
<br />
The package {{AUR|xcalib}} ([http://xcalib.sourceforge.net/ upstream URL]) is available in the [[AUR]] and can be used to dim the screen. A demonstration video is available on [https://www.youtube.com/watch?v=A9xsvntT6i4 YouTube]. This program can correct gamma, invert colors, and reduce contrast, the latter of which we use in this case. For example, to dim down:<br />
<br />
$ xcalib -co 40 -a<br />
<br />
This program uses ICC technology to interact with X11 and while the screen is dimmed, you may find that the mouse cursor is just as bright as before.<br />
<br />
=== redshift ===<br />
<br />
The program [[redshift]] in the official repositories uses {{ic|randr}} to adjust the screen brightness depending on the time of day and your geographic position. It can also do RGB gamma corrections and set color temperatures. As with {{ic|xcalib}}, this is very much a software solution and the look of the mouse cursor is unaffected. To execute a single quick adjustment of the brightness, try something like this:<br />
<br />
redshift -o -l 0:0 -b 0.8 -t 6500:6500<br />
<br />
{{Tip|If your longitude is west or your latitude is south, you should input it as negative.<br />
Example for Berkeley, CA: <br />
redshift-gtk -l 37.8717:-122.2728 <br />
}}<br />
<br />
=== NVIDIA settings ===<br />
<br />
Users of [[NVIDIA|NVIDIA's proprietary drivers]] users can change display brightness via the nvidia-settings utility under "X Server Color Correction." However, note that this has absolutely nothing to do with backlight (intensity), it merely adjusts the color output. (Reducing brightness this way is a power-inefficient last resort when all other options fail; increasing brightness spoils your color output completely, in a way similar to overexposed photos.)<br />
<br />
== Specific models ==<br />
<br />
=== Backlight PWM modulation frequency (Intel i915 only) ===<br />
<br />
Laptops with LED backlight are known to have screen flicker sometimes. The reason for this, is that it is hard enough to dim LEDs by limiting direct current flowing through. It is easier to control brightness by switching LEDs on and off fast enough.<br />
<br />
However, frequency of the switching (so-called PWM modulation frequency) is not high enough actually, and some people may notice flicker either explicitly or by feeling headache and eyestrain.<br />
<br />
If you have an Intel i915 GPU, then it may be possible to adjust PWM modulation frequency to eliminate flicker.<br />
<br />
Install {{Pkg|intel-gpu-tools}} from the official repositories. Get value of the register, that determines PWM modulation frequency<br />
<br />
{{hc|# intel_reg_read 0xC8254|<br />
0xC8254 : 0x12281228<br />
}}<br />
<br />
The value returned represents period of PWM modulation. So to increase PWM modulation frequency, value of the register has to be reduced. For example, to double frequency from the previous listing, execute:<br />
<br />
# intel_reg_write 0xC8254 0x09140914<br />
<br />
You can use online calculator to calculate desired value http://devbraindom.blogspot.com/2013/03/eliminate-led-screen-flicker-with-intel.html<br />
<br />
Refer to dedicated topic for details https://bbs.archlinux.org/viewtopic.php?pid=1245913<br />
<br />
If you are using the Intel GM45 chipset use address 0x61254 instead of 0xC8254.<br />
<br />
=== Inverted Brightness (Intel i915 only) ===<br />
<br />
Symptoms:<br />
* after installing {{ic|xf86-video-intel}} systemd-backlight.service turns off the backlight during boot<br />
** possible solution: mask systemd-backlight.service<br />
* switching from X to another VT turns the backlight off<br />
* the brightness keys are inverted (i.e. turning up the brightness makes the screen darker)<br />
<br />
This problem may be solved by adding {{ic|i915.invert_brightness&#61;1}} to the list of [[Kernel_parameters|kernel parameters]].</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Install_bundled_32-bit_system_in_64-bit_system_(%C4%8Cesky)&diff=344667Install bundled 32-bit system in 64-bit system (Česky)2014-11-14T20:37:01Z<p>Jstjohn: /* Zvuk */ fix 2 capitalization issues</p>
<hr />
<div>[[Category:Arch64 (Česky)]]<br />
[[en:Install bundled 32-bit system in Arch64]]<br />
[[fr:Install environnement 32 sur un systeme 64]]<br />
[[zh-CN:Install bundled 32-bit system in Arch64]]<br />
Instalace Arch64 svázaná s 32bit systémem<br />
<br />
Tento článek je určený především pro ty, kdo opravdu potřebují používat 32bitové aplikace. Protože Arch64 se snaží být čistě 64bitovou distribucí, bývá občas problém sehnat knihovny pro 32bit emulaci. Tento postup vytvoří čistě 32bitovou instalaci ArchLinuxu ve vaší stávající 64bitové.<br />
<br />
== Instalace základních balíčků ==<br />
Nejprve vytvoříme místo, kam stahovat a instalovat balíčky:<br />
mkdir /opt/arch32<br />
<br />
V libovolném editoru (třeba ''nano'') upravte soubor ''/etc/pacman.d/core'', případně (u pacmana>=3.1) ''/etc/pacman.d/mirrorlist'':<br />
<br />
nano /etc/pacman.d/core<br />
nano /etc/pacman.d/mirrorlist<br />
<br />
V těchto souborech nahraďte ''x86_64'' za ''i686'' (raději u více serverů, ale teoreticky stačí i jen jeden)<br />
<br />
'''Nezapomeňte nakonec vrátit tyto soubory do původního stavu!!!'''<br />
<br />
Dále je vhodné vytvořit pro 32bitovou instalaci samostatný log. '''Opět nezapomeňte po skončení tohoto návodu následující změnu zase vrátit zpátky.'''<br />
<br />
nano /etc/pacman.conf<br />
<br />
Upravte položku 'LogFile' podle potřeby (například ''/var/log/pacman_32.log'').<br />
<br />
Aktuální verze pacmana vyžaduje vytvořit adresářovou strukturu pro databázi:<br />
<br />
mkdir -p /opt/arch32/var/lib/pacman<br />
<br />
Nyní proveďte aktualizaci repozitářů:<br />
<br />
pacman --root /opt/arch32 -Sy<br />
<br />
A teď už můžeme nainstalovat základní balíčky (pokud nehodláte v chrootu kompilovat balíčky, můžete skupinu ''base-devel'' vynechat):<br />
<br />
pacman --root /opt/arch32 -S base base-devel<br />
<br />
'''Nyní vraťte zpátky změny v nastavení pacmana - /etc/pacman.d/core resp. /etc/pacman.d/mirrorlist a /etc/pacman.conf'''.<br />
<br />
== /etc/rc.d/arch32 rc skript ==<br />
<br />
Pro spuštění 32bitového prostředí při bootování vytvořte v /etc/rc.d skript a nazvěte ho ''arch32'':<br />
<br />
nano /etc/rc.d/arch32<br />
<br />
#!/bin/bash<br />
<br />
. /etc/rc.conf<br />
. /etc/rc.d/functions<br />
<br />
case $1 in<br />
start)<br />
stat_busy "Starting Arch32 chroot"<br />
mount --bind /proc /opt/arch32/proc<br />
mount --bind /proc/bus/usb /opt/arch32/proc/bus/usb<br />
mount --bind /dev /opt/arch32/dev<br />
mount --bind /dev/pts /opt/arch32/dev/pts<br />
mount --bind /dev/shm /opt/arch32/dev/shm<br />
mount --bind /sys /opt/arch32/sys<br />
mount --bind /tmp /opt/arch32/tmp<br />
mount --bind /home /opt/arch32/home<br />
add_daemon arch32<br />
stat_done<br />
;;<br />
stop)<br />
stat_busy "Stopping Arch32 chroot"<br />
umount /opt/arch32/proc/bus/usb<br />
umount /opt/arch32/proc<br />
umount /opt/arch32/dev/pts<br />
umount /opt/arch32/dev/shm<br />
umount /opt/arch32/dev<br />
umount /opt/arch32/sys<br />
umount /opt/arch32/tmp<br />
umount /opt/arch32/home<br />
rm_daemon arch32<br />
stat_done<br />
;;<br />
restart)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "usage: $0 {start|stop|restart}"<br />
esac<br />
exit 0<br />
<br />
Ještě udělejte soubor spustitelným:<br />
<br />
chmod +x /etc/rc.d/arch32<br />
<br />
A přidejte daemona do ''/etc/rc.conf'':<br />
<br />
DAEMONS=(syslog-ng network netfs crond arch32 gdm)<br />
<br />
== Konfigurace ==<br />
Nejprve je nutné zkopírovat pár souborů s nastavením<br />
<br />
cd /opt/arch32/etc<br />
<br />
cp /etc/passwd* ./<br />
cp /etc/shadow* ./<br />
cp /etc/group* ./<br />
cp /etc/rc.conf ./<br />
ln /etc/resolv.conf ./<br />
cp -a /etc/localtime ./<br />
cp /etc/locale.gen ./<br />
cp /etc/profile.d/locale.sh profile.d<br />
cp /etc/mtab ./<br />
<br />
Abychom zabránili kolizi binárek, je nutné upravit ještě nastavení 32bitového pacmana. Adresářovou strukturu pro pacmana není nutné vytvářet, tu si pacman udělá sám.<br />
<br />
nano /opt/arch32/etc/pacman.conf<br />
[options]<br />
LogFile = /var/log/pacman_32.log<br />
DBPath = /var/lib/pacman_32<br />
CacheDir = /var/cache/pacman_32<br />
<br />
a následně:<br />
<br />
mv /opt/arch32/var/lib/pacman /opt/arch32/var/lib/pacman_32<br />
mv /opt/arch32/var/cache/pacman /opt/arch32/var/cache/pacman_32<br />
<br />
Nyní můžete chrootovat do 32bitového systému (jako root):<br />
<br />
/etc/rc.d/arch32 start<br />
xhost +<br />
chroot /opt/arch32<br />
<br />
Ještě poslední doladění:<br />
<br />
/usr/sbin/locale-gen<br />
pacman -S ttf-bitstream-vera ttf-ms-fonts<br />
<br />
Samozřejmě můžete nainstalovat libovolné jiné fonty, ale je nutné nainstaloval alespoň jedno písmo, jinak nebudou fungovat grafické aplikace.<br />
<br />
Nyní můžete nainstalovat libovolné aplikace podle potřeby:<br />
<br />
pacman -S acroread opera<br />
pacman -S mozilla-firefox<br />
pacman -S libxmu flashplugin<br />
pacman -S mplayer-plugin<br />
<br />
Pokud ještě chcete získat nějaké do místo navíc, můžete smazat stažené balíčky:<br />
<br />
pacman -Scc<br />
<br />
A ještě můžete odstranit pár drobností. '''Nezapomeňte, že /home adresář je provázaný s vaším normálním /home adresářem! Dávejte pozor na to co mažete!!!'''<br />
<br />
rmdir /home/ftp<br />
<br />
pacman -Rd mkinitcpio<br />
<br />
== Spouštění 32bitových aplikací z 64bitového systému ==<br />
<br />
<br />
=== Stáhněte a nainstalujte schroot ===<br />
<br />
Nainstalujte ''schroot'' z repozitáře ''community'':<br />
<br />
pacman -S schroot<br />
<br />
=== Nastavení ===<br />
<br />
Schroot již obsahuje připravené nastavení pro Arch32 chroot. Pouze zkontrolujte, že nastavení v /etc/schroot/schroot.conf v sekci [Arch32] odpovídá vašemu skutečnému nastavení.<br />
<br />
=== Spuštění aplikací ===<br />
<br />
Pro spuštění 32bitové aplikace instalované v chrootu použijte:<br />
<br />
schroot -p opera -notrayicon<br />
<br />
Tento příklad spustí Operu, instalovanou v 32bitovém chrootu bez ikony v tray.<br />
<br />
=== Zvuk ===<br />
Nejpoužívanější aplikací v 32 bitovém systému je flash, například pro YouTube.<br />
Aby flash ve Firefoxu přehrával hudbu, otevřete terminál a chrootujte do 32bitového systému:<br />
<br />
chroot /opt/arch32<br />
<br />
Odtud nainstalujte ''alsa-oss'':<br />
pacman -S alsa-oss<br />
<br />
Potom napište:<br />
export FIREFOX_DSP="aoss"<br />
<br />
A spusťte Firefox</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=ASUS_Eee_PC&diff=344666ASUS Eee PC2014-11-14T20:36:17Z<p>Jstjohn: /* Video */ fix capitalization</p>
<hr />
<div>[[Category:ASUS]]<br />
[[de:Asus Eee PC]]<br />
This should be the page to gather all information on installing and running arch on the Asus Eee. <br />
Why? Because the 'old' page is a bit confusing/outdated, wrongly named (makes finding it in a search hard) and the title limits it to just the install precedure.<br />
<br />
The 'old' page should be cleaned up and merged into this page, and any future information should also go on this page. If no one that actualy owns an Eee want to do it, then I (Mr.Elendig) can do it, but it will take some time.<br />
<br />
Until this page actualy get some contents, go to [[Installing Arch Linux on the Asus EEE PC]].<br />
<br />
= Eee 700 Series and 900=<br />
This should be filled with the majority of the content from [[Installing Arch Linux on the Asus EEE PC]].<br />
<br />
=== Installation ===<br />
Installation can be achieved from an external cdrom drive, or from a usb stick configured as described in [[Install from USB stick]]<br />
<br />
The wireless module (ath5k) is now part of the stock kernel. The stock kernel performs very well on the eeepc. You do not need to install any extra packages from AUR for wireless or install any special kernel.<br />
<br />
During installation make sure you add the following packages in addition to the base packages for wireless to work.<br />
<br />
wireless_tools<br />
netcfg<br />
<br />
Thats all you now need for a working eee.<br />
<br />
=== If you do want an optimized Pentium-M kernel ===<br />
toofishes created a repository for the Eee. You can find some basic packages like a Pentium-M optimized kernel. Add<br />
[eee]<br />
Server = http://code.toofishes.net/packages/eee<br />
to your {{ic|/etc/pacman.conf}} to use the repository.<br />
<br />
Simply use pacman to install the package you need. Install the packages with this command:<br />
# pacman -S kernel-eee<br />
<br />
Then, add the following to {{ic|/boot/grub/menu.lst}}; note that no initrd is needed:<br />
# (2) Arch Linux<br />
title Arch Linux EEE kernel<br />
root (hd0,0)<br />
kernel /boot/vmlinuzeee root=/dev/sda1 ro<br />
<br />
Restart and select Arch Linux EEE kernel from the grub boot menu.<br />
<br />
===Xorg===<br />
Xorg works without an xorg.conf on the eeepc fine with the new hotplugging system. See [[Xorg]].<br />
<br />
===Sound===<br />
If sound does not work in a new installation add the following line to {{ic|/etc/modprobe.d/modprobe.conf}}<br />
options snd-hda-intel model=3stack-dig<br />
<br />
= Eee 900A =<br />
<br />
The 900A is a 900 with a Intel Atom CPU and new hardware (the most is like in 901), you can get help in [[Asus Eee PC 900A]].<br />
<br />
= Eee 901, 904, and 1000(H) =<br />
The 901, 904, and 1000(H) all seem to share much-of, if not all the same hardware. The steps for setting up Arch Linux are as follows.<br />
NB. There is a separate wiki page as well dedicated to the [[ASUS Eee PC 901|901]].<br />
<br />
== Setting up the Network ==<br />
Two PKGBUILD files are available in the AUR to help you get your network interfaces up and running. The first is delcake's "atl1e" drivers for your wired ethernet, and the second is jbooth's "eeert2860" drivers for wireless.<br />
<br />
=== atl1e ===<br />
delcake's PKGBUILD is located [https://aur.archlinux.org/packages.php?ID=18663 here] in the AUR.<br />
Note that in order to build this package, you will need to get the unrar and unzip packages from the mirror of you choice, as well as the LinuxDrivers.zip source code linked on the AUR page unless you did your wireless drivers first.<br />
<br />
#Transfer the PKGBUILD to your Eee PC. Get the source files too if you do not have internet yet.<br />
#Install the unrar and unzip packages if you do not already have them.<br />
#Issue a 'makepkg' command at the location of the PKGBUILD.<br />
<br />
If all goes well, a .pkg.tar.gz file that starts with the name atl1e will have been created in the same folder.<br />
<br />
As root, run 'pacman -U <package name>.pkg.tar.gz' to install your newly created module.<br />
In order to detect it, run both 'depmod -a' and 'modprobe atl1e' as root in that order.<br />
<br />
At this point, you should be able to issue an {{ic|ip a}} command and see your brand new eth0 device staring back at you. Don't forget to add atl1e to your modules list in /etc/rc.conf to automatically load your ethernet module during boot.<br />
<br />
* '''WARNING:''' You will need to recompile this module any time you do a kernel upgrade, so hang on to that PKGBUILD and zip file.<br />
<br />
=== eeert2860 ===<br />
jbooth's PKGBUILD is located [https://aur.archlinux.org/packages.php?ID=18705 here] in the AUR.<br />
Note that in order to build this package, you will need to get the wireless_tools package from the mirror of your choice, as well as Ralink's drivers listed under the sources section unless you did your wired drivers first.<br />
<br />
#Transfer the PKGBUILD to your Eee PC. Get the source files too if you do not have internet yet.<br />
#Install the wireless_tools package if you do not already have it.<br />
#Issue a 'makepkg' command at the location of the PKGBUILD.<br />
<br />
Hopefully, the makepkg command went through without a hitch, and a .pkg.tar.gz file will have been created in the same folder.<br />
<br />
As root, run 'pacman -U <package name>.pkg.tar.gz' to install your newly created module.<br />
In order to detect it, run both 'depmod -a' and 'modprobe rt2860sta' as root in that order.<br />
<br />
Now you should see your ra0 wireless device in the output of {{ic|ip a}}. As root, run {{ic|ip link set dev ra0 up}} to bring up the interface for configuration.<br />
<br />
*'''Still no ra0 device?''' Make sure that the WLAN device is enabled in your BIOS.<br />
<br />
* '''WARNING:''' You will need to recompile this module any time you do a kernel upgrade, so hang on to the PKGBUILD and .tar.bz2 file.<br />
<br />
==Eee 901 20G lsmod and lspci==<br />
'''<br />
Note :''' This section was moved from the 70x/900 page.<br />
<br />
The following are from a stock ASUS EeePC 901 20G Linux version:<br />
<br />
lsmod:<br />
<pre><br />
Module Size Used by<br />
acpi_cpufreq 5004 0 <br />
freq_table 1988 1 acpi_cpufreq<br />
usb_storage 22980 0 <br />
libusual 6352 1 usb_storage<br />
pciehp 31172 0 <br />
pci_hotplug 9672 1 pciehp<br />
ehci_hcd 25420 0 <br />
uhci_hcd 18636 0 <br />
usbhid 13444 0 <br />
usbcore 91992 6 usb_storage,libusual,ehci_hcd,uhci_hcd,usbhid<br />
snd_pcm_oss 33568 0 <br />
snd_mixer_oss 13056 1 snd_pcm_oss<br />
rt2860sta 468248 1 <br />
atl1e 26388 0 <br />
fuse 34516 0 <br />
asus_acpi 6560 0 <br />
button 5648 0 <br />
processor 19820 1 acpi_cpufreq<br />
battery 7940 0 <br />
ac 3524 0 <br />
autofs4 15876 0 <br />
sr_mod 13284 0 <br />
cdrom 30624 1 sr_mod<br />
snd_hda_intel 284112 0 <br />
snd_pcm 50696 2 snd_pcm_oss,snd_hda_intel<br />
snd_timer 15556 1 snd_pcm<br />
snd_page_alloc 6728 2 snd_hda_intel,snd_pcm<br />
snd_hwdep 6084 1 snd_hda_intel<br />
snd 34852 6 snd_pcm_oss,snd_mixer_oss,snd_hda_intel,snd_pcm,snd_timer,snd_hwdep<br />
soundcore 3744 1 snd<br />
genrtc 6028 0<br />
</pre><br />
<br />
lspci:<br />
<pre><br />
00:00.0 Host bridge: Intel Corporation Mobile 945GME Express Memory Controller Hub (rev 03)<br />
00:02.0 VGA compatible controller: Intel Corporation Mobile 945GME Express Integrated Graphics Controller (rev 03)<br />
00:02.1 Display controller: Intel Corporation Mobile 945GM/GMS/GME, 943/940GML Express Integrated Graphics Controller (rev 03)<br />
00:1b.0 Audio device: Intel Corporation 82801G (ICH7 Family) High Definition Audio Controller (rev 02)<br />
00:1c.0 PCI bridge: Intel Corporation 82801G (ICH7 Family) PCI Express Port 1 (rev 02)<br />
00:1c.1 PCI bridge: Intel Corporation 82801G (ICH7 Family) PCI Express Port 2 (rev 02)<br />
00:1c.2 PCI bridge: Intel Corporation 82801G (ICH7 Family) PCI Express Port 3 (rev 02)<br />
00:1c.3 PCI bridge: Intel Corporation 82801G (ICH7 Family) PCI Express Port 4 (rev 02)<br />
00:1d.0 USB Controller: Intel Corporation 82801G (ICH7 Family) USB UHCI Controller #1 (rev 02)<br />
00:1d.1 USB Controller: Intel Corporation 82801G (ICH7 Family) USB UHCI Controller #2 (rev 02)<br />
00:1d.2 USB Controller: Intel Corporation 82801G (ICH7 Family) USB UHCI Controller #3 (rev 02)<br />
00:1d.3 USB Controller: Intel Corporation 82801G (ICH7 Family) USB UHCI Controller #4 (rev 02)<br />
00:1d.7 USB Controller: Intel Corporation 82801G (ICH7 Family) USB2 EHCI Controller (rev 02)<br />
00:1e.0 PCI bridge: Intel Corporation 82801 Mobile PCI Bridge (rev e2)<br />
00:1f.0 ISA bridge: Intel Corporation 82801GBM (ICH7-M) LPC Interface Bridge (rev 02)<br />
00:1f.2 IDE interface: Intel Corporation 82801GBM/GHM (ICH7 Family) SATA IDE Controller (rev 02)<br />
00:1f.3 SMBus: Intel Corporation 82801G (ICH7 Family) SMBus Controller (rev 02)<br />
01:00.0 Network controller: RaLink RT2790 Wireless 802.11n PCIe<br />
03:00.0 Ethernet controller: Atheros Corp. L1e Gigabit Ethernet Adapter (rev b0)<br />
</pre><br />
<br />
= Eee 904HA =<br />
[[ASUS Eee PC 904HA]]<br />
<br />
= Eee T91MT =<br />
[[ASUS Eee PC T91MT]]<br />
<br />
= Eee T101MT =<br />
[[ASUS Eee PC T101MT]]<br />
<br />
= Eee 1000HE =<br />
[[ASUS Eee PC 1000HE]]<br />
<br />
= Eee 1001P =<br />
[[ASUS Eee PC 1001p]]<br />
<br />
= Eee 1001PX =<br />
[[ASUS Eee PC 1001px]]<br />
<br />
= Eee 1005HA =<br />
[[ASUS Eee PC 1005HA]]<br />
<br />
= Eee 1005P(E) =<br />
[[ASUS Eee PC 1005P]]<br />
<br />
= Eee 1011CX =<br />
[[ASUS_Eee_PC_1011cx]]<br />
<br />
= Eee 1015B =<br />
<br />
Things that "just work":<br />
* Wlan (ath9k is part of the kernel; some use brcmsmac)<br />
* Ethernet<br />
* Graphics (with kms and dri2, using the xf86-video-ati driver)<br />
* Webcam (using v4l)<br />
* Suspend-to-RAM (after installing acpid)<br />
* Cardreader (but keucr is in staging, thus '''taints the kernel'''. PyroPeter experienced '''crashes''' while he inserted or removed sd cards)<br />
* Bluetooth (after installing bluez)<br />
* CPU Frequency Scaling (Use acpi_cpufreq since linux 3.7)<br />
* TouchPad (support multi-touch after installing xf86-input-synaptics)<br />
* Video Acceleration (Using [[ATI_Catalyst#Video_acceleration|ATI/AMD's propretary driver(catalyst)]])<br />
<br />
''/etc/modprobe.d/eeepc1015b.conf:''<br />
# supposed to help against following msg in dmesg:<br />
# SP5100 TCO timer: mmio address 0xbafe00 already in use<br />
blacklist sp5100_tco<br />
<br />
# if you don't need the sd-card reader you may want to blacklist<br />
# keucr. it is in staging, thus taints the kernel<br />
blacklist keucr<br />
<br />
# if you find "''ACPI: resource piix4_smbus [io 0x0b00-0x0b07]''<br />
# ''conflicts with ACPI region SMRG [io 0xb00-0xb0f]''" <br />
# in /var/log/messages.log ,try to uncomment the following line<br />
#blacklist i2c_piix4<br />
<br />
lspci:<br />
00:00.0 Host bridge: Advanced Micro Devices [AMD] Family 14h Processor Root Complex<br />
00:01.0 VGA compatible controller: Advanced Micro Devices [AMD] nee ATI Device 9805<br />
00:01.1 Audio device: Advanced Micro Devices [AMD] nee ATI Wrestler HDMI Audio [Radeon HD 6250/6310]<br />
00:04.0 PCI bridge: Advanced Micro Devices [AMD] Family 14h Processor Root Port<br />
00:05.0 PCI bridge: Advanced Micro Devices [AMD] Family 14h Processor Root Port<br />
00:11.0 SATA controller: Advanced Micro Devices [AMD] nee ATI SB7x0/SB8x0/SB9x0 SATA Controller [AHCI mode]<br />
00:12.0 USB controller: Advanced Micro Devices [AMD] nee ATI SB7x0/SB8x0/SB9x0 USB OHCI0 Controller<br />
00:12.2 USB controller: Advanced Micro Devices [AMD] nee ATI SB7x0/SB8x0/SB9x0 USB EHCI Controller<br />
00:13.0 USB controller: Advanced Micro Devices [AMD] nee ATI SB7x0/SB8x0/SB9x0 USB OHCI0 Controller<br />
00:13.2 USB controller: Advanced Micro Devices [AMD] nee ATI SB7x0/SB8x0/SB9x0 USB EHCI Controller<br />
00:14.0 SMBus: Advanced Micro Devices [AMD] nee ATI SBx00 SMBus Controller (rev 42)<br />
00:14.2 Audio device: Advanced Micro Devices [AMD] nee ATI SBx00 Azalia (Intel HDA) (rev 40)<br />
00:14.3 ISA bridge: Advanced Micro Devices [AMD] nee ATI SB7x0/SB8x0/SB9x0 LPC host controller (rev 40)<br />
00:14.4 PCI bridge: Advanced Micro Devices [AMD] nee ATI SBx00 PCI to PCI Bridge (rev 40)<br />
00:15.0 PCI bridge: Advanced Micro Devices [AMD] nee ATI SB700/SB800/SB900 PCI to PCI bridge (PCIE port 0)<br />
00:18.0 Host bridge: Advanced Micro Devices [AMD] Family 12h/14h Processor Function 0 (rev 43)<br />
00:18.1 Host bridge: Advanced Micro Devices [AMD] Family 12h/14h Processor Function 1<br />
00:18.2 Host bridge: Advanced Micro Devices [AMD] Family 12h/14h Processor Function 2<br />
00:18.3 Host bridge: Advanced Micro Devices [AMD] Family 12h/14h Processor Function 3<br />
00:18.4 Host bridge: Advanced Micro Devices [AMD] Family 12h/14h Processor Function 4<br />
00:18.5 Host bridge: Advanced Micro Devices [AMD] Family 12h/14h Processor Function 6<br />
00:18.6 Host bridge: Advanced Micro Devices [AMD] Family 12h/14h Processor Function 5<br />
00:18.7 Host bridge: Advanced Micro Devices [AMD] Family 12h/14h Processor Function 7<br />
01:00.0 Network controller: Atheros Communications Inc. AR9285 Wireless Network Adapter (PCI-Express) (rev 01)<br />
02:00.0 Ethernet controller: Atheros Communications Inc. AR8152 v2.0 Fast Ethernet (rev c1)<br />
On models with ASMedia USB 3.0 chip, replace last 2 line with:<br />
01:00.0 Network controller: Broadcom Corporation BCM4313 802.11b/g/n Wireless LAN Controller (rev 01)<br />
02:00.0 Ethernet controller: Atheros Communications Inc. AR8152 v2.0 Fast Ethernet (rev c1)<br />
03:00.0 USB controller: ASMedia Technology Inc. Device 1040<br />
<br />
lsusb:<br />
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
Bus 003 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 002 Device 002: ID 13d3:5702 IMC Networks UVC VGA Webcam<br />
<br />
== Audio ==<br />
<br />
After running alsaconf the graphics card was the default audio output, so I had to create {{ic|/etc/asound.conf}} with the following contents:<br />
<br />
defaults.ctl.card 1<br />
defaults.pcm.card 1<br />
defaults.timer.card 1<br />
<br />
Volume function key for alsa: <br />
{{hc|/etc/acpi/handler.sh|<br />
......<br />
open)<br />
#echo "LID opend!">/dev/tty5<br />
;;<br />
esac<br />
;;<br />
## volume control key ##<br />
button/mute)<br />
case "$2" in<br />
MUTE) amixer set Master toggle ;;<br />
esac<br />
;;<br />
button/volumedown)<br />
case "$2" in<br />
VOLDN) amixer set Master 2%- ;;<br />
esac<br />
;;<br />
button/volumeup)<br />
case "$2" in<br />
VOLUP) amixer set Master 2%+ ;;<br />
esac<br />
;;<br />
## volume control key end ##<br />
*)<br />
logger "ACPI group/action underfined: $1 /$2"<br />
;;<br />
esac}}<br />
<br />
== Powersaving ==<br />
<br />
When system is idle, [[ATI_Catalyst|ATI/AMD's propretary driver(catalyst)]] saves 2.5W than xf86-video-ati.<br />
<br />
= Eee 1015 BX =<br />
<br />
Most seems to work 'out-of-the-box':<br />
* Wlan<br />
* Ethernet<br />
* Graphics (using the xf86-video-ati driver)<br />
* Webcam<br />
* Suspend-to-RAM (with acpi & acpid)<br />
* Cardreader<br />
* CPU Frequency Scaling (add 'eeepc-wmi ac battery button fan video' to MODULES array in '/etc/rc.conf')<br />
* TouchPad (using the xf86-input-synaptics driver)<br />
<br />
<br />
My blacklist:<br />
# /etc/modprobe.d/blacklist.conf<br />
blacklist sp5100_tco<br />
<br />
For sound at DE add this file to your HOME-directory:<br />
#<br />
# ~/.asoundrc<br />
#<br />
<br />
defaults.ctl.card 1<br />
defaults.pcm.card 1<br />
defaults.timer.card 1<br />
<br />
For volume-control-buttons I use shortcuts with:<br />
amixer -q -c 1 set Master 5+<br />
amixer -q -c 1 set Master 5-<br />
amixer -q -c 1 set Master toggle<br />
<br />
<br />
= Eee 1015 PE/PEM =<br />
<br />
<br />
== Hardware ==<br />
<br />
The Eee 1015 series laptops come with a 1024x600 LED display and a Dual Core Intel Atom processor (N550). They also have a [[Broadcom wireless]] card and an Atheros Ethernet port. <br />
<br />
Here is the output of {{ic|lspci}}:<br />
{{bc|0<nowiki>0:00.0 Host bridge: Intel Corporation N10 Family DMI Bridge (rev 02)<br />
00:02.0 VGA compatible controller: Intel Corporation N10 Family Integrated Graphics Controller (rev 02)<br />
00:02.1 Display controller: Intel Corporation N10 Family Integrated Graphics Controller (rev 02)<br />
00:1b.0 Audio device: Intel Corporation N10/ICH 7 Family High Definition Audio Controller (rev 02)<br />
00:1c.0 PCI bridge: Intel Corporation N10/ICH 7 Family PCI Express Port 1 (rev 02)<br />
00:1c.1 PCI bridge: Intel Corporation N10/ICH 7 Family PCI Express Port 2 (rev 02)<br />
00:1c.3 PCI bridge: Intel Corporation N10/ICH 7 Family PCI Express Port 4 (rev 02)<br />
00:1d.0 USB controller: Intel Corporation N10/ICH 7 Family USB UHCI Controller #1 (rev 02)<br />
00:1d.1 USB controller: Intel Corporation N10/ICH 7 Family USB UHCI Controller #2 (rev 02)<br />
00:1d.2 USB controller: Intel Corporation N10/ICH 7 Family USB UHCI Controller #3 (rev 02)<br />
00:1d.3 USB controller: Intel Corporation N10/ICH 7 Family USB UHCI Controller #4 (rev 02)<br />
00:1d.7 USB controller: Intel Corporation N10/ICH 7 Family USB2 EHCI Controller (rev 02)<br />
00:1e.0 PCI bridge: Intel Corporation 82801 Mobile PCI Bridge (rev e2)<br />
00:1f.0 ISA bridge: Intel Corporation NM10 Family LPC Controller (rev 02)<br />
00:1f.2 SATA controller: Intel Corporation N10/ICH7 Family SATA Controller [AHCI mode] (rev 02)<br />
01:00.0 Ethernet controller: Atheros Communications Inc. AR8132 Fast Ethernet (rev c0)<br />
02:00.0 Network controller: Broadcom Corporation BCM4313 802.11b/g/n Wireless LAN Controller (rev 01)</nowiki>}}<br />
<br />
{{Note|The wireless card uses the '''brcmsmac''' driver. Since linux 3.3.1 the brcmsmac driver depends on the bcma module and blacklisting is no longer required. See [[Broadcom wireless]]}}<br />
<br />
Here is the output of {{ic|lscpu}}:<br />
{{bc|<nowiki>Architecture: x86_64<br />
CPU op-mode(s): 32-bit, 64-bit<br />
Byte Order: Little Endian<br />
CPU(s): 4<br />
On-line CPU(s) list: 0-3<br />
Thread(s) per core: 2<br />
Core(s) per socket: 2<br />
Socket(s): 1<br />
NUMA node(s): 1<br />
Vendor ID: GenuineIntel<br />
CPU family: 6<br />
Model: 28<br />
Stepping: 10<br />
CPU MHz: 1499.813<br />
BogoMIPS: 3000.61<br />
L1d cache: 24K<br />
L1i cache: 32K<br />
L2 cache: 512K<br />
NUMA node0 CPU(s): 0-3<br />
</nowiki>}}<br />
<br />
== Installation ==<br />
<br />
To install Arch on the Asus Eee 1015 series you need to use an external cd-rom drive or [[USB Installation Media]].<br />
<br />
The partition created by Asus on my 1015 PEM is as follows:<br />
<br />
Number Start End Size Type File System Flags<br />
1 1049kb 107Gb 107Gb primary NTFS <br />
2 107Gb 123Gb 16.1Gb primary fat32 hidden<br />
3 123Gb 250Gb 127Gb primary NTFS <br />
4 250Gb 250Gb 21.2Gb primary <br />
<br />
Results may vary. The first partition was the Windows 7 installation. The second is the recovery partition with splashtop. Removing this second partition will cause the fast-start Linux to stop working. The third is Windows D:\ drive and the last one is the boot partition for Windows 7.<br />
<br />
Due to the limitations of having 4 partitions per drive I installed arch on the first 107Gb partition and created a swap file instead of a partition as per [[Swap]]. <br />
<br />
=== ACPI ===<br />
<br />
ACPI works fine following the [[acpid]] guide. The following is for older versions of the kernel.<br />
<br />
To enable acpi you need to edit menu.lst and add acpi_osi=Linux to the kernel line like so:<br />
<br />
kernel /boot/vmlinuz-linux root=/dev/sda1 ro acpi_osi=Linux<br />
<br />
This enabled you to trigger devices in /sys/devices/platform/eeepc/.<br />
<br />
{{Note|As far as I can tell, this is no longer required. If you do add it, the module eeepc-wmi will fail to load - kernel 2.6.39.2-1}}<br />
<br />
=== Modules ===<br />
<br />
In order to get CPU frequency scaling as well as the proper special-purpose Eee PC module loaded, you can use the following MODULES statement in /etc/rc.conf:<br />
<br />
MODULES=( acpi-cpufreq cpufreq_ondemand eeepc-wmi )<br />
<br />
If you get double keypresses for with your function keys (like the mute key, etc.), add the following into {{ic|/etc/modprobe.d/blacklist.conf}} (Create this file if it isn't present)<br />
<pre>blacklist eeepc-laptop</pre><br />
{{Note|As long as you do not add acpi_osi-Linux to menu.lst, the eeepc modules load automagically and are not required in MODULES}}<br />
{{Note|As of [http://kernel.org kernel] 3.3.7-1, no extra modules are '''required''' in order for full usage of Arch Linux on this laptop.}}<br />
<br />
= Eee 1015 PN =<br />
[[ASUS Eee PC 1015pn]]<br />
<br />
= Eee 1025C =<br />
[[ASUS Eee PC 1025c]]<br />
<br />
= Eee 1201T =<br />
[[ASUS Eee PC 1201T]]<br />
<br />
= Eee 1201NL =<br />
[[ASUS Eee PC 1201NL]]<br />
<br />
= Eee 1215n =<br />
[[ASUS Eee PC 1215n]]<br />
<br />
= Eee 1215P =<br />
[[ASUS Eee PC 1215p]]<br />
<br />
= Eee 1215B =<br />
<br />
Things that work out of the box: Wifi, Ethernet, Video (max resolution available with basic Xorg and xfce packages installed), Touchpad, Keyboard (Fn keys not working).<br />
<br />
Things that need work: Audio, Fn keys, Power management.<br />
<br />
== Installation ==<br />
<br />
Arch setup encountered no problems, GRUB installed successfully with no damages to Windows (need to uncomment the windows lines in in /boot/grub/menu.lst) and Express Gate.<br />
<br />
== Audio ==<br />
<br />
With the xfce4 desktop environment audio doesn't work by default (didn't test with other de). <br />
To fix this, add the following lines in your ~/.asoundrc:<br />
{{bc|defaults.pcm.card 1<br />
defaults.ctl.card 1}}<br />
<br />
(Credit to Touko Korpela from the Debian mailing list)<br />
<br />
== Video ==<br />
<br />
YouTube videos with the default ATI driver work flawlessly with a resolution of 720p, while with 1080p playback isn't smooth anymore. Didn't test with the catalyst drivers, maybe a better playback could be achieved.<br />
<br />
== Power Management ==<br />
<br />
ACPI executes correctly and returns remaining battery life. Cpufreq doesn't seem to work, hence making it impossible for Jupiter ([http://sourceforge.net/projects/jupiter/]) to manage the Super Hybrid Engine. However, from the Jupiter tray icon, screen orientation, resolution and touchpad can be toggled and modified.<br />
<br />
By suggestion from the Debian mailing list, I tried loading "powernow-k8" with modprobe to get cpufreq working. This is apparently a bug in the driver detection mechanism of cpufreq, and should be reported upstream, I guess. After loading that module, cpufreq-info seems to work. Have not tried getting Jupiter to manage SHE yet after that.<br />
<br />
'''Suspend''' and '''hibernate''' work '''OK''', with one tiny bug: I can't seem to get the SD-card reader working after resuming from hibernate. After a reboot, it works fine.</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=ELinks&diff=344665ELinks2014-11-14T20:35:09Z<p>Jstjohn: /* Passing Youtube-links through external player */ fix some grammar issues</p>
<hr />
<div>[[Category:Web Browser]]<br />
[[de:Elinks]]<br />
[[fr:ELinks]]<br />
[http://elinks.or.cz/ ELinks] is an advanced and well-established feature-rich text mode web (HTTP/FTP/..) browser. ELinks can render both frames and tables, is highly customizable and can be extended via Lua or Guile scripts. It features tabs and some support for CSS.<br />
<br />
== Installing ==<br />
{{Pkg|elinks}} is available from the official repositories.<br />
== Basic Usage ==<br />
Start elinks with<br />
elinks<br />
or, if you want to start a specific website:<br />
elinks foo.bar.org<br />
<br />
=== Navigation ===<br />
<br />
Navigating the web with a text browser is more or less the same as a graphical browser, just without the 'distractions'.<br />
Once you've started ''elinks'', you can press '''g''' and type in the web page you would like to request. <br />
Then you can navigate the page using arrow keys to navigate by line, the space bar to navigate by page, or the<br />
'''j''', '''k''' keys to navigate by link. <br />
<br />
<br />
{{Expansion|Basic scripting and CSS.}}<br />
{{Expansion|automation and boting.}}<br />
<br />
==Configuration==<br />
Almost everything in ELinks can be configured to suit your fancy. <br />
<br />
ELinks provides to two menus, accessable through ELinks, to customize options and<br />
keybinds respectivly. <br />
<br />
It is recommened to use these tools as opposed to hand-editing the config files (which are placed in ~/.elinks)<br />
It is both much easier and safer this way.<br />
<br />
By default, access to the option manager is through the '''o''' key and access to the keybind-manager is through<br />
the '''k''' key.<br />
<br />
{{Note| The organization of the option-manager is not always obvious and takes a bit of memorization to use <br />
efficiently once you eventually find what you were looking for}}<br />
<br />
== Tips ==<br />
=== Defining URL-handlers ===<br />
<br />
ELinks is capable of using external programs for various tasks,<br />
<br />
Defining URL-handlers through the option menu can be a little confusing at first, but once you get it, its fine. <br />
<br />
To do this, go into the option manager and navigate to '''MIME'''. All the submenus have '''I'''nfo pages to help you.<br />
<br />
This is one of the few cases where it might be easier just to edit the conf file. <br />
<br />
For example, to get ELinks to automatically launch your image-viewer when you click on a jpeg file, you can<br />
add the following to your ~/.elinks/elinks.conf file, <br />
{{hc|~/.elinks/elinks.conf|<nowiki>set mime.extension.jpg="image/jpeg"<br />
set mime.extension.jpeg="image/jpeg"<br />
set mime.extension.png="image/png"<br />
set mime.extension.gif="image/gif"<br />
set mime.extension.bmp="image/bmp"<br />
<br />
set mime.handler.image_viewer.unix.ask = 1<br />
set mime.handler.image_viewer.unix-xwin.ask = 0<br />
<br />
set mime.handler.image_viewer.unix.block = 1<br />
set mime.handler.image_viewer.unix-xwin.block = 0 <br />
<br />
set mime.handler.image_viewer.unix.program = "ADDYOURTERMINALPICTUREVIEWERHERE %"<br />
set mime.handler.image_viewer.unix-xwin.program = "ADDYOURXPICTUREVIEWERHERE %"<br />
<br />
set mime.type.image.jpg = "image_viewer"<br />
set mime.type.image.jpeg = "image_viewer"<br />
set mime.type.image.png = "image_viewer"<br />
set mime.type.image.gif = "image_viewer"<br />
set mime.type.image.bmp = "image_viewer"</nowiki>}}<br />
<br />
=== Using ELinks with [[Tor]] ===<br />
ELinks does not support SOCKS directly, so alternatives are to either invoke ELinks thus {{ic|torify elinks}} or install {{Pkg|privoxy}} from the [[official repositories]] and use it for forwarding to Tor's SOCKS proxy, first by adding the following line to your {{ic|/etc/privoxy/config}}:<br />
forward-socks5 / localhost:9050 .<br />
Restart {{ic|privoxy.service}}<br />
and then entering the following lines to your {{ic|~/.elinks/elinks.conf}}:<br />
set protocol.http.proxy.host = "127.0.0.1:8118"<br />
set protocol.https.proxy.host = "127.0.0.1:8118"<br />
{{Note|The above assumes that ''Tor'' is using port '''9050''' and that ''privoxy'' is listening on port '''8118'''}}<br />
<br />
=== Passing URL's to external commands ===<br />
You can define commands which ELinks will pass the the current URL to.<br />
<br />
To do this, go into the options menu, navigate under '''Document''', then to '''URI-passing'''. <br />
Then press '''A''' to add a new command name. Then navigate to the new command name and press '''E''' to <br />
edit. Type in the name of command, enter and save.<br />
<br />
Assuming the command "tab-external-command" is mapped to '''KEY''', whenever you press '''KEY''', a menu containing your commands<br />
will appear. Select the one you want, and ELinks passes the current URL to that command<br />
{{Note| Elinks allows you to define your own mappings for navigating this menu}}<br />
<br />
Here are some useful commands to get you started...<br />
==== Saving link to the X clipboard ====<br />
echo -n %c | xclip -i <br />
<br />
==== Passing YouTube-links through external player ====<br />
For strictly YouTube-links, {{Pkg|mpv}} has built-in support. Just use the following,<br />
mpv %c <br />
<br />
For a more general approach that can handle many 'tube' sites, you will need {{Pkg|youtube-dl}}. Then add the following command,<br />
youtube-dl -o - %c | mplayer - <br />
I used {{Pkg|mplayer}} because i couldn't get it to work with mpv. Anyway, this is not as nice as mpv's support for YouTube links. <br />
Mpv gives you full control of position in the stream which is wonderful!<br />
<br />
== Troubleshoot ==<br />
=== ELinks froze and i can't start it without it freezing again ===<br />
By default, every time you start ELinks you are connecting to an existing instance. Thus, if that instance<br />
freezes, all current and future instances will freeze as well. <br />
<br />
You can prevent ELinks from connecting to an existing instance by starting it like so<br />
elinks -no-connect<br />
<br />
If this happens a lot, you might consider making this your default startup by making an alias in your shell<br />
alias elinks="elinks -no-connect"<br />
<br />
== See Also ==<br />
<br />
*[http://elinks.or.cz/ Official web site]<br />
*[http://kmandla.wordpress.com/2007/05/06/howto-use-elinks-like-a-pro/ Howto: Use elinks like a pro]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Backlight&diff=344663Backlight2014-11-14T20:33:51Z<p>Jstjohn: /* xcalib */ improve grammar</p>
<hr />
<div>[[Category:Laptops]]<br />
[[Category:Power management]]<br />
[[ru:Backlight]]<br />
[[ja:Backlight]]<br />
Screen brightness might be tricky to control. On some machines physical hardware switches are missing and software solutions may not work well. However, it is generally posssible; be sure to use a method that works for your hardware.<br />
<br />
There are many ways to adjust the screen backlight of a monitor, laptop or integrated panel (such as the iMac) using software, but depending on hardware and model, sometimes only some options are available. This article aims to summarize all possible ways to adjust the backlight.<br />
<br />
== Overview ==<br />
<br />
There are many ways to control brightness. According to this [https://bugs.launchpad.net/ubuntu/+source/xserver-xorg-video-intel/+bug/397617 discussion] and this wiki page [https://wiki.ubuntu.com/Kernel/Debugging/Backlight] the control method could be divided into these categories:<br />
<br />
* brightness is controlled by vendor-specified hotkey and there is no interface for the OS to adjust the brightness.<br />
* brightness is controlled by the either by ACPI or the graphic driver.<br />
* brightness is controlled by HW register through setpci.<br />
<br />
All methods are exposed to the user through {{ic|/sys/class/backlight}} and xrandr/xbacklight can choose one method to control brightness. It is still not very clear which one xbacklight prefers by default.<br />
<br />
{{note|1=See {{Bug|27677}} for xbacklight, if you get "No outputs have backlight property."'' There is a temporary fix if xrandr/xbacklight does not choose the right directory in {{ic|/sys/class/backlight}}: You can specify the one you want in xorg.conf by setting the "Backlight" option of the Device section to the name of that directory (see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=651741 at the bottom of the page for details).}}<br />
<br />
== ACPI ==<br />
<br />
The brightness of the screen backlight is adjusted by setting the power level of the backlight LEDs or cathodes. The power level can often be controlled using the ACPI kernel module for video. An interface to this module is provided via a folder in the sysfs at {{ic|/sys/class/backlight}}.<br />
<br />
The name of the folder depends on the graphics card model.<br />
{{hc|# ls /sys/class/backlight/|<br />
intel_backlight<br />
}}<br />
<br />
A backlight to adjust example: is managed by an Intel graphics card. It is called {{ic|acpi_video0}} on an ATI card. In the following example, acpi_video0 is used.<br />
<br />
The directory contains the following files and folders:<br />
<br />
actual_brightness brightness max_brightness subsystem/ uevent <br />
bl_power device/ power/ type<br />
<br />
The maximum brightness can be found by reading from {{ic|max_brightness}}, which is often 15.<br />
<br />
{{hc|/sys/class/backlight/acpi_video0/max_brightness|<br />
15<br />
}}<br />
<br />
The brightness can be set by writing a number to {{ic|brightness}}. It is not possible to go any higher than the maximum brightness. <br />
<br />
# tee /sys/class/backlight/acpi_video0/brightness <<< 5<br />
<br />
=== Kernel command-line options ===<br />
<br />
Sometimes, ACPI does not work well due to different motherboard implementations and ACPI quirks. This includes some laptops with dual graphics (e.g. Nvidia/Radeon dedicated GPU with Intel/AMD integrated GPU). On Nvidia Optimus laptops, the kernel parameter nomodeset can interfere with the ability to adjust the backlight. Additionally, ACPI sometimes register its own {{ic|acpi_video0}} backlight even if one already exists (such as {{ic|intel_backlight}}), which results in non working backlight keys. You can try adding the following kernel parameters in your [[bootloader]] to stop ACPI from registering its own backlight interface if one already exists:<br />
<br />
video.use_native_backlight=1<br />
<br />
This is the default as of {{pkg|linux}} 3.16. If that does not work, you can try to adjust the list of supported OS interfaces:<br />
<br />
acpi_osi="!Windows 2012"<br />
<br />
{{Tip|1=<br />
On an Asus notebooks you might also need to do:<br />
<br />
{{bc|# modprobe asus-nb-wmi}}<br />
}}<br />
<br />
{{Note|Disabling legacy boot on Dell XPS13 breaks backlight support.}}<br />
<br />
=== Udev rule ===<br />
<br />
If the ACPI interface is available, the backlight level can be set at boot using a udev rule.<br />
<br />
{{hc|/etc/udev/rules.d/81-backlight.rules|<nowiki><br />
# Set backlight level to 8<br />
SUBSYSTEM=="backlight", ACTION=="add", KERNEL=="acpi_video0", ATTR{brightness}="8"</nowiki>}}<br />
<br />
The systemd-backlight service restores the previous backlight brightness level at boot, whereas this rule sets it to a fixed value. If you want to use this rule, it is necessary to mask the system-backlight service, as explained in [[#systemd-backlight service]].<br />
<br />
== Switching off the backlight ==<br />
<br />
Switching off the backlight (for example when one locks the notebook) can be useful to conserve battery energy. Ideally the following command inside of a graphical session should work:<br />
sleep 1 && xset dpms force off<br />
The backlight should switch on again on mouse movement or keyboard input. If the previous command does not work, there is a chance that {{ic|vbetool}} works. Note, however, that in this case the backlight must be manually activated again. The command is as follows:<br />
vbetool dpms off<br />
To activate the backlight again:<br />
vbetool dpms on<br />
<br />
For example, this can be put to use when closing the notebook lid as outlined in the entry for [[Acpid#Laptop_Monitor_Power_Off|Acipd]].<br />
<br />
== systemd-backlight service ==<br />
<br />
The [[systemd]] package includes the service systemd-backlight@.service, which is enabled by default and "static". It saves the backlight brightness level at shutdown and restores it at boot. The service uses the ACPI method described in [[Backlight#ACPI]], generating services for each folder found in {{ic|/sys/class/backlight/}}. For example, if there is a folder named {{ic|acpi_video0}}, it generates a service called {{ic|systemd-backlight@backlight:acpi_video0.service}}. When using other methods of setting the backlight at boot, it is recommended to mask the service systemd-backlight@.service.<br />
<br />
== Backlight utilities ==<br />
<br />
=== xbacklight ===<br />
<br />
You can adjust the backlight through the xorg-server command {{ic|xbacklight}}. The utility is provided by the {{Pkg|xorg-xbacklight}} package in [extra].<br />
<br />
A useful demonstration was posted by [http://www.youtube.com/watch?v=_pi3iKMAJcY gotbletu on YouTube]. He suggests the following commands to adjust the backlight up and down:<br />
<br />
xbacklight -inc 40<br />
xbacklight -dec 40<br />
<br />
{{Tip|These commands can be bound to keyboard keys as described in [[Extra keyboard keys in Xorg]].}}<br />
<br />
=== power-backlight ===<br />
<br />
Set screen backlight brightness dependent on power source type; with udev rule backlight is adjusted on change of power source. Requires graphic driver support for ACPI in {{ic|/sys/class/backlight}}. Install with the AUR package {{aur|power-backlight-git}}.<br />
<br />
=== light ===<br />
<br />
More information can be found on the [[Light]] page.<br />
<br />
=== relight ===<br />
<br />
[http://xyne.archlinux.ca/projects/relight relight] is available in [http://xyne.archlinux.ca/repos Xyne's repos] and as package {{AUR|relight}} in the [[AUR]]. The package provides {{ic|relight.service}}, a [[systemd]] service to automatically restore previous backlight settings during reboot along using the ACPI method explained above, and ''relight-menu'', a dialog-based menu for selecting and configuring backlights for different screens.<br />
<br />
=== setpci (use with great care) ===<br />
<br />
It is possible to set the register of the graphic card to adjust the backlight. It means you adjust the backlight by manipulating the hardware directly, which can be risky and generally is not a good idea. Not all of the graphic cards support this method.<br />
<br />
When using this method, you need to use {{ic|lspci}} first to find out where your graphic card is.<br />
# setpci -s 00:02.0 F4.B=0<br />
<br />
=== Calise ===<br />
<br />
The software [http://calise.sourceforge.net/wordpress/ calise] can be found in AUR.<br />
* Stable version: {{AUR|calise}}<br />
* Development version: {{AUR|calise-git}} <br />
<br />
It basically computes ambient brightness, and set screen's correct backlight, simply making captures from the webcam, for laptop without light sensor.<br />
For more information, calise has its own wiki: [http://calise.sourceforge.net/mediawiki/index.php/Main_Page Calise wiki].<br />
<br />
The main features of this program are that it is very precise, very light on resource usage, and with the daemon version (.service file for systemd users available too), it has practically no impact on battery life.<br />
<br />
=== brightd ===<br />
<br />
Macbook-inspired {{AUR|brightd}} automatically dims (but does not put to standby) the screen when there is no user input for some time. A good companion of [[Display Power Management Signaling]] so that the screen does not blank out in a sudden.<br />
<br />
=== KDE ===<br />
<br />
[[KDE]] users can adjust the backlight via ''System Settings > Power Management > Energy Saving''.<br />
If you want to set backlight before kdm just put in /usr/share/config/kdm/Xsetup :<br />
<br />
xbacklight -inc 10<br />
<br />
== Color correction ==<br />
<br />
=== xcalib ===<br />
<br />
{{Note|''xcalib'' does ''not'' change the backlight power, it just modifies the video LUT table: this means that your battery life will be unaffected by the change. Nevertheless, it could be useful when no backlight control is available (Desktop PCs). Use {{ic|xcalib -clear}} to reset the LUT.}}<br />
<br />
The package {{AUR|xcalib}} ([http://xcalib.sourceforge.net/ upstream URL]) is available in the [[AUR]] and can be used to dim the screen. A demonstration video is available on [https://www.youtube.com/watch?v=A9xsvntT6i4 YouTube]. This program can correct gamma, invert colors, and reduce contrast, the latter of which we use in this case. For example, to dim down:<br />
<br />
$ xcalib -co 40 -a<br />
<br />
This program uses ICC technology to interact with X11 and while the screen is dimmed, you may find that the mouse cursor is just as bright as before.<br />
<br />
=== redshift ===<br />
<br />
The program [[redshift]] in the official repositories uses {{ic|randr}} to adjust the screen brightness depending on the time of day and your geographic position. It can also do RGB gamma corrections and set color temperatures. As with {{ic|xcalib}}, this is very much a software solution and the look of the mouse cursor is unaffected. To execute a single quick adjustment of the brightness, try something like this:<br />
<br />
redshift -o -l 0:0 -b 0.8 -t 6500:6500<br />
<br />
{{Tip|If your longitude is west or your latitude is south, you should input it as negative.<br />
Example for Berkeley, CA: <br />
redshift-gtk -l 37.8717:-122.2728 <br />
}}<br />
<br />
=== NVIDIA settings ===<br />
<br />
Users of [[NVIDIA|NVIDIA's proprietary drivers]] users can change display brightness via the nvidia-settings utility under "X Server Color Correction." However, note that this has absolutely nothing to do with backlight (intensity), it merely adjusts the color output. (Reducing brightness this way is a power-inefficient last resort when all other options fail; increasing brightness spoils your color output completely, in a way similar to overexposed photos.)<br />
<br />
== Specific models ==<br />
<br />
=== Backlight PWM modulation frequency (Intel i915 only) ===<br />
<br />
Laptops with LED backlight are known to have screen flicker sometimes. The reason for this, is that it is hard enough to dim LEDs by limiting direct current flowing through. It is easier to control brightness by switching LEDs on and off fast enough.<br />
<br />
However, frequency of the switching (so-called PWM modulation frequency) is not high enough actually, and some people may notice flicker either explicitly or by feeling headache and eyestrain.<br />
<br />
If you have an Intel i915 GPU, then it may be possible to adjust PWM modulation frequency to eliminate flicker.<br />
<br />
Install {{Pkg|intel-gpu-tools}} from the official repositories. Get value of the register, that determines PWM modulation frequency<br />
<br />
{{hc|# intel_reg_read 0xC8254|<br />
0xC8254 : 0x12281228<br />
}}<br />
<br />
The value returned represents period of PWM modulation. So to increase PWM modulation frequency, value of the register has to be reduced. For example, to double frequency from the previous listing, execute:<br />
<br />
# intel_reg_write 0xC8254 0x09140914<br />
<br />
You can use online calculator to calculate desired value http://devbraindom.blogspot.com/2013/03/eliminate-led-screen-flicker-with-intel.html<br />
<br />
Refer to dedicated topic for details https://bbs.archlinux.org/viewtopic.php?pid=1245913<br />
<br />
If you are using the Intel GM45 chipset use address 0x61254 instead of 0xC8254.<br />
<br />
=== Inverted Brightness (Intel i915 only) ===<br />
<br />
Symptoms:<br />
* after installing {{ic|xf86-video-intel}} systemd-backlight.service turns off the backlight during boot<br />
** possible solution: mask systemd-backlight.service<br />
* switching from X to another VT turns the backlight off<br />
* the brightness keys are inverted (i.e. turning up the brightness makes the screen darker)<br />
<br />
This problem may be solved by adding {{ic|i915.invert_brightness&#61;1}} to the list of [[Kernel_parameters|kernel parameters]].</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=344659Bluetooth headset2014-11-14T20:32:26Z<p>Jstjohn: add two wiki links</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
[[ru:Bluetooth headset]]<br />
{{Related articles start}}<br />
{{Related|Bluetooth}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
<br />
Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation. <br />
<br />
{{Tip|The most recent version of [[Bluez]] does not support the Headset/Handsfree profiles. This means that microphone input will not work, and also no sound output on headsets that do not support the A2DP profile. For using a headset with the Headset/Handsfree profiles, you will need to jump down to the legacy methods which require using [[AUR]] to fetch alternative packages.<br />
}}<br />
<br />
{{Tip| {{AUR|pulseaudio-git}} has added native support for the Headset/Handsfree profiles and Bluez5.}}<br />
<br />
{{Tip|Bluez5 is only supported by [[PulseAudio]] and not by [[ALSA]]. If you do not want to use PulseAudio, you need to install an older Bluez version from the AUR.}}<br />
<br />
== A2DP via Bluez5/PulseAudio ==<br />
<br />
PulseAudio 5.x supports A2DP per default.<br />
Make sure the following packages are installed:<br />
<br />
# pacman -S pulseaudio-alsa bluez bluez-libs bluez-utils<br />
<br />
Start the Bluetooth system:<br />
<br />
# systemctl start bluetooth<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
# bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
# power on<br />
# agent on<br />
# default-agent<br />
# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
shows a device that calls itself "Lasmex LBT10" and has MAC address ''00:1D:43:6D:03:26''. We will now use that MAC address to initiate the pairing:<br />
<br />
# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device:<br />
<br />
# connect 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[PulseAudio]]. You can now redirect any playback to that device using ''pavucontrol''.<br />
<br />
You can now disable scanning again and exit the program:<br />
# scan off<br />
# exit<br />
<br />
=== Troubleshooting ===<br />
<br />
Many users report frustration with getting A2DP to work. <br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, have a look at the log via one of the following commands:<br />
<br />
# systemctl status bluetooth<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
The problem in this case is that PulseAudio is not catching up. A common solution to this problem is to restart PulseAudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while PulseAudio runs as user. After restarting PulseAudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting PulseAudio does not work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
If that still does not work, or you are using PulseAudio's system-wide mode, also load the following PulseAudio modules (again these can be loaded via your default.pa or system.pa):<br />
<br />
module-bluetooth-policy<br />
module-bluez5-device<br />
module-bluez5-discover<br />
<br />
To have your headset auto connect you need to enable PulseAudio's switch-on-connect module. Add the following:<br />
{{hc|/etc/pulse/default.pa|<br />
# automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
You then need to tell ''bluetoothctl'' to trust your Bluetooth headset, or you will see errors like this:<br />
bluetoothd[487]: Authentication attempt without agent<br />
bluetoothd[487]: Access denied: org.bluez.Error.Rejected<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
After a reboot, your Bluetooth adapter will not power on by default. You need to add a udev rule to power it on:<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
# Set bluetooth power up<br />
ACTION=="add", SUBSYSTEM=="bluetooth", KERNEL=="hci[0-9]*", RUN+="/usr/bin/hciconfig %k up"<br />
}}<br />
<br />
==== Connecting works, but I cannot play sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your PulseAudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
== Legacy method: ALSA-BTSCO ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]].}}<br />
<br />
It is much easier to set up your bluetooth headset today, with bluez >= 3.16. You may want to try the out-of-box python script in [http://fosswire.com/2008/01/11/a2dp-stereo-linux/ this blog] (you need edit the script to work with gconftool-2). There is also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
You need your headset's bdaddr. It is of the form ''12:34:56:78:9A:BC''. Either find it in the documentation of your headset, on the headset itself or with the '''hcitool scan''' command.<br />
<br />
Install {{AUR|btsco}}.<br />
<br />
To load the kernel module, type:<br />
# modprobe snd-bt-sco<br />
There will now be an extra audio device. Use {{ic|alsamixer -cN}} (where N is most likely 1) to set the volume. You can access the device with any alsa-capable application by choosing the device ''BT headset'', or with any OSS application by using {{ic|/dev/dspN}} as the audio device.<br />
<br />
But to actually get any sound, you have to connect your headset to the computer first.<br />
<br />
=== Connecting the headset ===<br />
<br />
If you connect your headset for the first time, read the section about pairing first. To connect to your headset to the computer, use the command<br />
$ btsco -f <bdaddr><br />
for example<br />
$ btsco -f 12:34:56:78:9A:BC<br />
<br />
==== Pairing the headset with your computer ====<br />
<br />
The first time you connect the headset, you have to pair it with the computer. To do this, you need your headset's PIN. Depending on your headset you may have to reset the headset and repeat the pairing everytime you used the headset with another bluetooth device.<br />
<br />
There are two ways to pair your headset with the computer:<br />
<br />
===== Using ''bluez-gnome'' =====<br />
<br />
Install the ''bluez-gnome'' package from the community repository. Then start the '''bt-applet''' program. Once you try to connect to the headset, a window will open and ask for the PIN.<br />
<br />
===== Using ''passkey-agent'' =====<br />
<br />
Before connecting to the headset, enter the command<br />
$ passkey-agent --default <pin><br />
where ''<pin>'' is your headset's PIN. Then try to connect to the headset.<br />
<br />
=== Headset and ALSA Devices ===<br />
<br />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<br />
<br />
3. Pair your headset with your device:<br />
$ bluez-simple-agent (optional hci# ***) XX:XX:XX:XX:XX:XX<br />
and put in your pin (0000 or 1234, etc)<br />
<br />
4. Make sure your {{ic|/etc/bluetooth/audio.conf}} allows A2DP Audio Sinks. Place this line just bellow the [General] heading:<br />
Enable=Source,Sink,Media,Socket<br />
<br />
5. Add this to your {{ic|/etc/asound.conf}} file:<br />
#/etc/asound.conf<br />
<br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device XX:XX:XX:XX:XX:XX <br />
profile "auto"<br />
} <br />
} <br />
hint {<br />
show on<br />
description "BT Headset"<br />
} <br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
} <br />
<br />
6. Check to see if it has been added to alsa devices<br />
$ aplay -L<br />
<br />
7. Now play with aplay:<br />
$ aplay -D btheadset /path/to/audio/file<br />
<br />
or Mplayer:<br />
$ mplayer -ao alsa:device=btheadset /path/to/audio/or/video/file<br />
<br />
{{Tip|To find hci# for a usb dongle, type in <br />
$ hcitool dev<br />
}}<br />
<br />
=== Headset's multimedia buttons ===<br />
<br />
In order to get your bluetooth headset's multimedia buttons (play, pause, next, previous) working you need to create {{ic|/etc/modprobe.d/uinput.conf}} containing {{ic|uinput}}.<br />
<br />
== Legacy method: PulseAudio ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]] (references to {{ic|/etc/bluetooth/audio.conf}} and ''bluez-simple-agent'').}}<br />
<br />
This one is much easier and more elegant. PulseAudio will seamlessly switch between output devices when the headset is turned on. If you have ALSA as the sound server, you need the following packages installed:<br />
{{Pkg|pulseaudio}} and {{Pkg|pulseaudio-alsa}}.<br />
<br />
Now, to configure the audio output to use bluetooth, just install {{Pkg|pavucontrol}} and run it to configure the audio output:<br />
$ pavucontrol<br />
Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Audio sink fails ====<br />
<br />
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device. You will get "Audio sink fails".<br />
According to [http://wiki.gentoo.org/wiki/Bluetooth_Headset gentoo wiki], you have to verify than in {{ic|/etc/bluetooth/audio.conf}} there is {{ic|<nowiki>Enable=Socket</nowiki>}} under the {{ic|[General]}} section heading.<br />
<br />
Just do a {{ic|# systemctl restart bluetooth}} to apply it.<br />
<br />
==== Page timeout issue ====<br />
<br />
If you receive this error whilst trying to pair your headset with your system using bluez-simple-agent, then you can try to restart your system and use the graphical bluez applet of your desktop environment.<br />
<br />
== Legacy documentation: ALSA, bluez5 and PulseAudio method ==<br />
<br />
{{Accuracy|Describes two different methods, see the [[Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions|talk page]] for details.|Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions}}<br />
<br />
[[ALSA]], [[bluez|bluez5]], and [[PulseAudio]] work together to allow a wireless [[Bluetooth]] headset to play audio. The following method works with a Lenovo T61p laptop and SoundBot SB220 wireless bluetooth headset. The required software stack is extensive and failure to include all components can produce errors which are difficult to understand. The following list of software packages might not be the minimum required set and needs to be examined more closely.<br />
<br />
Bluez5 has a regression causing HSP/HFP Telephone profile to not be available. This regression is documented in the [http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/5.0/ draft release notes for Pulseaudio 5.0] which say (in "Notes for packagers"): "PulseAudio now supports BlueZ 5, but only the A2DP profile. BlueZ 4 is still the only way to make HSP/HFP work." ([https://fedoraproject.org/wiki/Common_F20_bugs#bluez5-profile from here])<br />
<br />
=== Install Software Packages ===<br />
<br />
The core software components are [[ALSA]], Bluez5, [[PulseAudio]]. However there are additional libraries which are required. As well as a player which can play audio files. The following section lists the software packages installed in order to connect the headset and play audio over the headset.<br />
<br />
==== Install ALSA and associated libraries ====<br />
<br />
[[ALSA]] works with the linux kernel to provide audio services to user mode software. The following packages are used with the [[Bluetooth]] headset: {{Pkg|alsa-utils}}, {{Pkg|alsa-plugins}}, {{Pkg|alsa-tools}}.<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. It is required for [[PulseAudio]] to interface with wireless headsets. Required packages: {{Pkg|bluez}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-libs}}.<br />
<br />
==== Install PulseAudio ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The {{AUR|pulseaudio-git}} package from [[AUR]] has capabilities not provided by the stock {{Pkg|pulseaudio}} package. The additional capabilities are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [https://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
Required packages: {{AUR|pulseaudio-git}}, {{Pkg|pavucontrol}}.<br />
<br />
==== Install Audacious ====<br />
<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Required packages: {{Pkg|audacious}}, {{Pkg|audacious-plugins}}.<br />
<br />
=== Procedure ===<br />
<br />
Once the required packages are installed, use this procedure to play audio with a bluetooth headset. The high level overview of the procedure is to pair the headset, connect the headset, configure the player and pulse audio controller and then play audio.<br />
<br />
Start the bluetooth service as root:<br />
# systemctl start bluetooth<br />
<br />
Verify Bluetooth is started<br />
# systemctl status bluetooth<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: active (running) since Sat 2013-12-07 12:31:14 PST; 12s ago<br />
Docs: man:bluetoothd(8)<br />
Main PID: 3136 (bluetoothd)<br />
Status: "Running"<br />
CGroup: /system.slice/bluetooth.service<br />
└─3136 /usr/lib/bluetooth/bluetoothd<br />
<br />
Dec 07 12:31:14 t61p systemd[1]: Starting Bluetooth service...<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth daemon 5.11<br />
Dec 07 12:31:14 t61p systemd[1]: Started Bluetooth service.<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Starting SDP server<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth management interface 1.3 i...ed<br />
Hint: Some lines were ellipsized, use -l to show in full.<br />
<br />
Start the PulseAudio daemon. This must be done after X windows is started and as a normal user.<br />
$ pulseaudio -D<br />
<br />
Verify the PulseAudio daemon is running.<br />
$ pulseaudio --check -v<br />
I: [pulseaudio] main.c: Daemon running as PID 3186<br />
<br />
Start up bluetoothctl as root and pair and connect your headset. As a regular user, bluetoothctl will pair but not connect. Perhaps this is related to the config file (shown below) which is setup for what appears to be the root user.<br />
Note: the procedure shown below is for an initial pair and connect of the headphone. If the headset is already paired, then the procedure below can be shortened to: power on, agent on, default-agent, connect <mac address>. The mac address can be seen from the devices command output.<br />
<br />
$ bluetoothctl <br />
[NEW] Controller 00:1E:4C:F4:98:5B t61p-0 [default]<br />
[NEW] Device 00:1A:7D:12:36:B9 SoundBot SB220<br />
[bluetooth]# show<br />
Controller 00:1E:4C:F4:98:5B<br />
Name: t61p<br />
Alias: t61p-0<br />
Class: 0x000000<br />
Powered: no<br />
Discoverable: no<br />
Pairable: yes<br />
UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Access Profile (00001800-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
Modalias: usb:v1D6Bp0246d050B<br />
Discovering: no<br />
[bluetooth]# power on<br />
[CHG] Controller 00:1E:4C:F4:98:5B Class: 0x0c010c<br />
Changing power on succeeded<br />
[CHG] Controller 00:1E:4C:F4:98:5B Powered: yes<br />
[bluetooth]# agent on<br />
Agent registered<br />
[bluetooth]# default-agent<br />
Default agent request successful<br />
<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# scan on<br />
Discovery started<br />
[CHG] Controller 00:1E:4C:F4:98:5B Discovering: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 RSSI: -61<br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
Attempting to pair with 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 UUIDs has unsupported type<br />
[CHG] Device 00:1A:7D:12:36:B9 Paired: yes<br />
Pairing successful<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
Connection successful<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
Device 00:1A:7D:12:36:B9<br />
Name: SoundBot SB220<br />
Alias: SoundBot SB220<br />
Class: 0x240404<br />
Icon: audio-card<br />
Paired: yes<br />
Trusted: no<br />
Blocked: no<br />
Connected: yes<br />
LegacyPairing: yes<br />
UUID: Headset (00001108-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
<br />
Start up alsamixer, for simplicity un-mute all your outputs. Oddly enough some can be muted though. The ones I had muted during playback were:<br />
* Headphones<br />
* SPIDF<br />
<br />
Start up audacious. Use the menu to select PulseAudio as your output. Somewhere I read that bluez5 requires pulseaudio-git and this jives with my experience.<br />
<br />
Start up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
[http://netskink.blogspot.com/2013/12/pulseaudio-pavucontrol-and-audacious.html screenshot of application settings]<br />
<br />
==== Miscellaneous configuration files ====<br />
<br />
For reference, these settings were also done.<br />
<br />
===== ALSA /etc/asound.conf =====<br />
<br />
The settings shown at the top of this page was used, but the additional modification for Intel laptop sound cards.<br />
<br />
{{bc|<nowiki><br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device 00:1A:7D:12:36:B9<br />
profile "auto"<br />
}<br />
}<br />
hint {<br />
show on<br />
description "BT Headset"<br />
}<br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
}<br />
options snd-hda-intel model=laptop<br />
</nowiki>}}<br />
<br />
===== /etc/dbus-1/system.d/bluetooth.conf =====<br />
<br />
The settings here seem to be enabled for root only. See the policy user="root" section. However, if a regular user is specified here, the system fails to start. Someone with more knowledge could explain why.<br />
<br />
{{hc|/etc/dbus-1/system.d/bluetooth.conf|<nowiki><br />
<!-- This configuration file specifies the required security policies for Bluetooth core daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<!-- ../system.conf have denied everything, so we just punch some holes --><br />
<br />
<policy user="root"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent1"/><br />
<allow send_interface="org.bluez.MediaEndpoint1"/><br />
<allow send_interface="org.bluez.MediaPlayer1"/><br />
<allow send_interface="org.bluez.ThermometerWatcher1"/><br />
<allow send_interface="org.bluez.AlertAgent1"/><br />
<allow send_interface="org.bluez.Profile1"/><br />
<allow send_interface="org.bluez.HeartRateWatcher1"/><br />
<allow send_interface="org.bluez.CyclingSpeedWatcher1"/><br />
</policy><br />
<br />
<policy at_console="true"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<!-- allow users of lp group (printing subsystem) to communicate with bluetoothd --><br />
<policy group="lp"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<policy context="default"><br />
<deny send_destination="org.bluez"/><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
===== Tested applications =====<br />
<br />
As noted above this will work easily with audacious. YouTube videos with Chromium and Flash Player will work on some videos. If the video has ads it will not work, but if the video does not have ads it will work. Just make sure that after audacious is working with Bluetooth headset, start Chromium, and navigate to YouTube. Find a video without leading ads, and it should play the audio. If the settings icon has the a menu with two drop-down combo boxes for Speed and Quality it will play.<br />
<br />
== Switch between HSV and A2DP setting ==<br />
<br />
This can easily be achieved by the following command where 2 needs to be changed with the correct device number.<br />
<br />
pacmd set-card-profile 2 a2dp<br />
<br />
=== A2DP not working with PulseAudio ===<br />
<br />
If PulseAudio fails when changing the profile to A2DP with bluez 4.1+ and PulseAudio 3.0+, you can try disabling the Socket interface from {{ic|/etc/bluetooth/audio.conf}} by removing the line {{ic|1=Enable=Socket}} and adding line {{ic|1=Disable=Socket}}.<br />
<br />
== Tested headsets ==<br />
<br />
{| class="wikitable"<br />
! Model<br />
! Version<br />
! Comments<br />
! Compatible<br />
|-<br />
| '''Philips SHB9100'''<br />
| <br />
| Pause and resume is flakey. See [https://bbs.archlinux.org/viewtopic.php?pid=1315428#p1315428] for the underlying issue and a temporary solution to improve audio quality.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB7000'''<br />
| <br />
| Pause and resume is flaky.<br />
| {{R|Limited}}<br />
|-<br />
| '''Parrot Zik'''<br />
| <br />
| Firmware 1.04. The microphone is detected, but does not work. Sometimes it lags (but does not stutter); usually this is not noticeable unless playing games, in which case you may switch to a wired connection.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sony DR-BT50'''<br />
| bluez{4,5}<br />
| Works for a2dp, see [http://vlsd.blogspot.com/2013/11/bluetooth-headphones-and-arch-linux.html]). Adapter: D-Link DBT-120 USB dongle.<br />
| {{Yes}}<br />
|-<br />
| '''Sony SBH50'''<br />
| bluez5<br />
| Works for a2dp, Adapter: Broadcom Bluetooth 2.1 Device (Vendor=0a5c ProdID=219b Rev=03.43). Requires the {{ic|btusb}} [[modprobe|module]].<br />
| {{Yes}}<br />
|-<br />
| '''SoundBot SB220'''<br />
| bluez5, {{AUR|pulseaudio-git}}<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Auna Air 300'''<br />
| bluez5, pulseaudio-git<br />
| For some reason, a few restarts were required, and eventually it just started working.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sennheiser MM 400-X'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Audionic BlueBeats (B-777)'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Logitech Wireless Headset'''<br />
| bluez 5.14, pulseaudio-git<br />
| part number PN 981-000381, advertised for use with iPad<br />
| {{Yes}}<br />
|-<br />
| '''HMDX Jam Classic Bluetooth'''<br />
| bluez, pulseaudio-git<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''PT-810'''<br />
| bluez 5.14, pulseaudio-git<br />
| Generic USB-Powered Bluetooth Audio Receiver with 3.5mm headset jack and a2dp profile. Widely available as "USB Bluetooth Receiver." IDs as PT-810.<br />
| {{Yes}}<br />
|-<br />
| '''Philips SHB4000WT'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Philips AEA2000/12'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Nokia BH-104'''<br />
| bluez4<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Creative AirwaveHD'''<br />
| bluez 5.23<br />
| Bluetooth adapter Atheros Communications usb: 0cf3:0036<br />
| {{Yes}}<br />
|-<br />
| '''deleyCON Bluetooth Headset'''<br />
| bluez 5.23<br />
| Adapter: CSL - USB nano Bluetooth-Adapter V4.0. Tested a2dp profile. Untested microphone. Does not auto-connect (even when paired and trusted), must connect manually. Play/pause button mutes/unmutes the headphones, not the playback. Playback fwd/bwd buttons do not work (nothing visible with ''xev'').<br />
| {{R|Limited}}<br />
|-<br />
| '''UE BOOM'''<br />
| bluez5, pulseaudio-git<br />
| Music starts a little stuttered for a few seconds and later gets normal, however, there is a 5-sec lag on video playing.<br />
| {{R|Limited}}<br />
|}<br />
<br />
== See also ==<br />
<br />
Alternative method of connecting a BT headset to Linux:<br />
<br />
* [http://gablog.eu/online/node/80 GaBlog - Connect a Bluetooth headset to Linux]<br />
<br />
Using the same device on Windows and Linux without pairing the device over and over again<br />
<br />
* [http://ubuntuforums.org/showthread.php?p=9363229#post9363229 Dual booting with a Bluetooth keyboard]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=344658Bluetooth headset2014-11-14T20:31:40Z<p>Jstjohn: /* Headset and Alsa Devices */ fix capitalization of ALSA</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
[[ru:Bluetooth headset]]<br />
{{Related articles start}}<br />
{{Related|Bluetooth}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
<br />
Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation. <br />
<br />
{{Tip|The most recent version of [[Bluez]] does not support the Headset/Handsfree profiles. This means that microphone input will not work, and also no sound output on headsets that do not support the A2DP profile. For using a headset with the Headset/Handsfree profiles, you will need to jump down to the legacy methods which require using [[AUR]] to fetch alternative packages.<br />
}}<br />
<br />
{{Tip| {{AUR|pulseaudio-git}} has added native support for the Headset/Handsfree profiles and Bluez5.}}<br />
<br />
{{Tip|Bluez5 is only supported by PulseAudio and not by ALSA. If you do not want to use PulseAudio, you need to install an older Bluez version from AUR.}}<br />
<br />
== A2DP via Bluez5/PulseAudio ==<br />
<br />
PulseAudio 5.x supports A2DP per default.<br />
Make sure the following packages are installed:<br />
<br />
# pacman -S pulseaudio-alsa bluez bluez-libs bluez-utils<br />
<br />
Start the Bluetooth system:<br />
<br />
# systemctl start bluetooth<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
# bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
# power on<br />
# agent on<br />
# default-agent<br />
# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
shows a device that calls itself "Lasmex LBT10" and has MAC address ''00:1D:43:6D:03:26''. We will now use that MAC address to initiate the pairing:<br />
<br />
# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device:<br />
<br />
# connect 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[PulseAudio]]. You can now redirect any playback to that device using ''pavucontrol''.<br />
<br />
You can now disable scanning again and exit the program:<br />
# scan off<br />
# exit<br />
<br />
=== Troubleshooting ===<br />
<br />
Many users report frustration with getting A2DP to work. <br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, have a look at the log via one of the following commands:<br />
<br />
# systemctl status bluetooth<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
The problem in this case is that PulseAudio is not catching up. A common solution to this problem is to restart PulseAudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while PulseAudio runs as user. After restarting PulseAudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting PulseAudio does not work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
If that still does not work, or you are using PulseAudio's system-wide mode, also load the following PulseAudio modules (again these can be loaded via your default.pa or system.pa):<br />
<br />
module-bluetooth-policy<br />
module-bluez5-device<br />
module-bluez5-discover<br />
<br />
To have your headset auto connect you need to enable PulseAudio's switch-on-connect module. Add the following:<br />
{{hc|/etc/pulse/default.pa|<br />
# automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
You then need to tell ''bluetoothctl'' to trust your Bluetooth headset, or you will see errors like this:<br />
bluetoothd[487]: Authentication attempt without agent<br />
bluetoothd[487]: Access denied: org.bluez.Error.Rejected<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
After a reboot, your Bluetooth adapter will not power on by default. You need to add a udev rule to power it on:<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
# Set bluetooth power up<br />
ACTION=="add", SUBSYSTEM=="bluetooth", KERNEL=="hci[0-9]*", RUN+="/usr/bin/hciconfig %k up"<br />
}}<br />
<br />
==== Connecting works, but I cannot play sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your PulseAudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
== Legacy method: ALSA-BTSCO ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]].}}<br />
<br />
It is much easier to set up your bluetooth headset today, with bluez >= 3.16. You may want to try the out-of-box python script in [http://fosswire.com/2008/01/11/a2dp-stereo-linux/ this blog] (you need edit the script to work with gconftool-2). There is also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
You need your headset's bdaddr. It is of the form ''12:34:56:78:9A:BC''. Either find it in the documentation of your headset, on the headset itself or with the '''hcitool scan''' command.<br />
<br />
Install {{AUR|btsco}}.<br />
<br />
To load the kernel module, type:<br />
# modprobe snd-bt-sco<br />
There will now be an extra audio device. Use {{ic|alsamixer -cN}} (where N is most likely 1) to set the volume. You can access the device with any alsa-capable application by choosing the device ''BT headset'', or with any OSS application by using {{ic|/dev/dspN}} as the audio device.<br />
<br />
But to actually get any sound, you have to connect your headset to the computer first.<br />
<br />
=== Connecting the headset ===<br />
<br />
If you connect your headset for the first time, read the section about pairing first. To connect to your headset to the computer, use the command<br />
$ btsco -f <bdaddr><br />
for example<br />
$ btsco -f 12:34:56:78:9A:BC<br />
<br />
==== Pairing the headset with your computer ====<br />
<br />
The first time you connect the headset, you have to pair it with the computer. To do this, you need your headset's PIN. Depending on your headset you may have to reset the headset and repeat the pairing everytime you used the headset with another bluetooth device.<br />
<br />
There are two ways to pair your headset with the computer:<br />
<br />
===== Using ''bluez-gnome'' =====<br />
<br />
Install the ''bluez-gnome'' package from the community repository. Then start the '''bt-applet''' program. Once you try to connect to the headset, a window will open and ask for the PIN.<br />
<br />
===== Using ''passkey-agent'' =====<br />
<br />
Before connecting to the headset, enter the command<br />
$ passkey-agent --default <pin><br />
where ''<pin>'' is your headset's PIN. Then try to connect to the headset.<br />
<br />
=== Headset and ALSA Devices ===<br />
<br />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<br />
<br />
3. Pair your headset with your device:<br />
$ bluez-simple-agent (optional hci# ***) XX:XX:XX:XX:XX:XX<br />
and put in your pin (0000 or 1234, etc)<br />
<br />
4. Make sure your {{ic|/etc/bluetooth/audio.conf}} allows A2DP Audio Sinks. Place this line just bellow the [General] heading:<br />
Enable=Source,Sink,Media,Socket<br />
<br />
5. Add this to your {{ic|/etc/asound.conf}} file:<br />
#/etc/asound.conf<br />
<br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device XX:XX:XX:XX:XX:XX <br />
profile "auto"<br />
} <br />
} <br />
hint {<br />
show on<br />
description "BT Headset"<br />
} <br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
} <br />
<br />
6. Check to see if it has been added to alsa devices<br />
$ aplay -L<br />
<br />
7. Now play with aplay:<br />
$ aplay -D btheadset /path/to/audio/file<br />
<br />
or Mplayer:<br />
$ mplayer -ao alsa:device=btheadset /path/to/audio/or/video/file<br />
<br />
{{Tip|To find hci# for a usb dongle, type in <br />
$ hcitool dev<br />
}}<br />
<br />
=== Headset's multimedia buttons ===<br />
<br />
In order to get your bluetooth headset's multimedia buttons (play, pause, next, previous) working you need to create {{ic|/etc/modprobe.d/uinput.conf}} containing {{ic|uinput}}.<br />
<br />
== Legacy method: PulseAudio ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]] (references to {{ic|/etc/bluetooth/audio.conf}} and ''bluez-simple-agent'').}}<br />
<br />
This one is much easier and more elegant. PulseAudio will seamlessly switch between output devices when the headset is turned on. If you have ALSA as the sound server, you need the following packages installed:<br />
{{Pkg|pulseaudio}} and {{Pkg|pulseaudio-alsa}}.<br />
<br />
Now, to configure the audio output to use bluetooth, just install {{Pkg|pavucontrol}} and run it to configure the audio output:<br />
$ pavucontrol<br />
Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Audio sink fails ====<br />
<br />
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device. You will get "Audio sink fails".<br />
According to [http://wiki.gentoo.org/wiki/Bluetooth_Headset gentoo wiki], you have to verify than in {{ic|/etc/bluetooth/audio.conf}} there is {{ic|<nowiki>Enable=Socket</nowiki>}} under the {{ic|[General]}} section heading.<br />
<br />
Just do a {{ic|# systemctl restart bluetooth}} to apply it.<br />
<br />
==== Page timeout issue ====<br />
<br />
If you receive this error whilst trying to pair your headset with your system using bluez-simple-agent, then you can try to restart your system and use the graphical bluez applet of your desktop environment.<br />
<br />
== Legacy documentation: ALSA, bluez5 and PulseAudio method ==<br />
<br />
{{Accuracy|Describes two different methods, see the [[Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions|talk page]] for details.|Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions}}<br />
<br />
[[ALSA]], [[bluez|bluez5]], and [[PulseAudio]] work together to allow a wireless [[Bluetooth]] headset to play audio. The following method works with a Lenovo T61p laptop and SoundBot SB220 wireless bluetooth headset. The required software stack is extensive and failure to include all components can produce errors which are difficult to understand. The following list of software packages might not be the minimum required set and needs to be examined more closely.<br />
<br />
Bluez5 has a regression causing HSP/HFP Telephone profile to not be available. This regression is documented in the [http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/5.0/ draft release notes for Pulseaudio 5.0] which say (in "Notes for packagers"): "PulseAudio now supports BlueZ 5, but only the A2DP profile. BlueZ 4 is still the only way to make HSP/HFP work." ([https://fedoraproject.org/wiki/Common_F20_bugs#bluez5-profile from here])<br />
<br />
=== Install Software Packages ===<br />
<br />
The core software components are [[ALSA]], Bluez5, [[PulseAudio]]. However there are additional libraries which are required. As well as a player which can play audio files. The following section lists the software packages installed in order to connect the headset and play audio over the headset.<br />
<br />
==== Install ALSA and associated libraries ====<br />
<br />
[[ALSA]] works with the linux kernel to provide audio services to user mode software. The following packages are used with the [[Bluetooth]] headset: {{Pkg|alsa-utils}}, {{Pkg|alsa-plugins}}, {{Pkg|alsa-tools}}.<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. It is required for [[PulseAudio]] to interface with wireless headsets. Required packages: {{Pkg|bluez}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-libs}}.<br />
<br />
==== Install PulseAudio ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The {{AUR|pulseaudio-git}} package from [[AUR]] has capabilities not provided by the stock {{Pkg|pulseaudio}} package. The additional capabilities are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [https://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
Required packages: {{AUR|pulseaudio-git}}, {{Pkg|pavucontrol}}.<br />
<br />
==== Install Audacious ====<br />
<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Required packages: {{Pkg|audacious}}, {{Pkg|audacious-plugins}}.<br />
<br />
=== Procedure ===<br />
<br />
Once the required packages are installed, use this procedure to play audio with a bluetooth headset. The high level overview of the procedure is to pair the headset, connect the headset, configure the player and pulse audio controller and then play audio.<br />
<br />
Start the bluetooth service as root:<br />
# systemctl start bluetooth<br />
<br />
Verify Bluetooth is started<br />
# systemctl status bluetooth<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: active (running) since Sat 2013-12-07 12:31:14 PST; 12s ago<br />
Docs: man:bluetoothd(8)<br />
Main PID: 3136 (bluetoothd)<br />
Status: "Running"<br />
CGroup: /system.slice/bluetooth.service<br />
└─3136 /usr/lib/bluetooth/bluetoothd<br />
<br />
Dec 07 12:31:14 t61p systemd[1]: Starting Bluetooth service...<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth daemon 5.11<br />
Dec 07 12:31:14 t61p systemd[1]: Started Bluetooth service.<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Starting SDP server<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth management interface 1.3 i...ed<br />
Hint: Some lines were ellipsized, use -l to show in full.<br />
<br />
Start the PulseAudio daemon. This must be done after X windows is started and as a normal user.<br />
$ pulseaudio -D<br />
<br />
Verify the PulseAudio daemon is running.<br />
$ pulseaudio --check -v<br />
I: [pulseaudio] main.c: Daemon running as PID 3186<br />
<br />
Start up bluetoothctl as root and pair and connect your headset. As a regular user, bluetoothctl will pair but not connect. Perhaps this is related to the config file (shown below) which is setup for what appears to be the root user.<br />
Note: the procedure shown below is for an initial pair and connect of the headphone. If the headset is already paired, then the procedure below can be shortened to: power on, agent on, default-agent, connect <mac address>. The mac address can be seen from the devices command output.<br />
<br />
$ bluetoothctl <br />
[NEW] Controller 00:1E:4C:F4:98:5B t61p-0 [default]<br />
[NEW] Device 00:1A:7D:12:36:B9 SoundBot SB220<br />
[bluetooth]# show<br />
Controller 00:1E:4C:F4:98:5B<br />
Name: t61p<br />
Alias: t61p-0<br />
Class: 0x000000<br />
Powered: no<br />
Discoverable: no<br />
Pairable: yes<br />
UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Access Profile (00001800-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
Modalias: usb:v1D6Bp0246d050B<br />
Discovering: no<br />
[bluetooth]# power on<br />
[CHG] Controller 00:1E:4C:F4:98:5B Class: 0x0c010c<br />
Changing power on succeeded<br />
[CHG] Controller 00:1E:4C:F4:98:5B Powered: yes<br />
[bluetooth]# agent on<br />
Agent registered<br />
[bluetooth]# default-agent<br />
Default agent request successful<br />
<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# scan on<br />
Discovery started<br />
[CHG] Controller 00:1E:4C:F4:98:5B Discovering: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 RSSI: -61<br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
Attempting to pair with 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 UUIDs has unsupported type<br />
[CHG] Device 00:1A:7D:12:36:B9 Paired: yes<br />
Pairing successful<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
Connection successful<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
Device 00:1A:7D:12:36:B9<br />
Name: SoundBot SB220<br />
Alias: SoundBot SB220<br />
Class: 0x240404<br />
Icon: audio-card<br />
Paired: yes<br />
Trusted: no<br />
Blocked: no<br />
Connected: yes<br />
LegacyPairing: yes<br />
UUID: Headset (00001108-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
<br />
Start up alsamixer, for simplicity un-mute all your outputs. Oddly enough some can be muted though. The ones I had muted during playback were:<br />
* Headphones<br />
* SPIDF<br />
<br />
Start up audacious. Use the menu to select PulseAudio as your output. Somewhere I read that bluez5 requires pulseaudio-git and this jives with my experience.<br />
<br />
Start up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
[http://netskink.blogspot.com/2013/12/pulseaudio-pavucontrol-and-audacious.html screenshot of application settings]<br />
<br />
==== Miscellaneous configuration files ====<br />
<br />
For reference, these settings were also done.<br />
<br />
===== ALSA /etc/asound.conf =====<br />
<br />
The settings shown at the top of this page was used, but the additional modification for Intel laptop sound cards.<br />
<br />
{{bc|<nowiki><br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device 00:1A:7D:12:36:B9<br />
profile "auto"<br />
}<br />
}<br />
hint {<br />
show on<br />
description "BT Headset"<br />
}<br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
}<br />
options snd-hda-intel model=laptop<br />
</nowiki>}}<br />
<br />
===== /etc/dbus-1/system.d/bluetooth.conf =====<br />
<br />
The settings here seem to be enabled for root only. See the policy user="root" section. However, if a regular user is specified here, the system fails to start. Someone with more knowledge could explain why.<br />
<br />
{{hc|/etc/dbus-1/system.d/bluetooth.conf|<nowiki><br />
<!-- This configuration file specifies the required security policies for Bluetooth core daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<!-- ../system.conf have denied everything, so we just punch some holes --><br />
<br />
<policy user="root"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent1"/><br />
<allow send_interface="org.bluez.MediaEndpoint1"/><br />
<allow send_interface="org.bluez.MediaPlayer1"/><br />
<allow send_interface="org.bluez.ThermometerWatcher1"/><br />
<allow send_interface="org.bluez.AlertAgent1"/><br />
<allow send_interface="org.bluez.Profile1"/><br />
<allow send_interface="org.bluez.HeartRateWatcher1"/><br />
<allow send_interface="org.bluez.CyclingSpeedWatcher1"/><br />
</policy><br />
<br />
<policy at_console="true"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<!-- allow users of lp group (printing subsystem) to communicate with bluetoothd --><br />
<policy group="lp"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<policy context="default"><br />
<deny send_destination="org.bluez"/><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
===== Tested applications =====<br />
<br />
As noted above this will work easily with audacious. YouTube videos with Chromium and Flash Player will work on some videos. If the video has ads it will not work, but if the video does not have ads it will work. Just make sure that after audacious is working with Bluetooth headset, start Chromium, and navigate to YouTube. Find a video without leading ads, and it should play the audio. If the settings icon has the a menu with two drop-down combo boxes for Speed and Quality it will play.<br />
<br />
== Switch between HSV and A2DP setting ==<br />
<br />
This can easily be achieved by the following command where 2 needs to be changed with the correct device number.<br />
<br />
pacmd set-card-profile 2 a2dp<br />
<br />
=== A2DP not working with PulseAudio ===<br />
<br />
If PulseAudio fails when changing the profile to A2DP with bluez 4.1+ and PulseAudio 3.0+, you can try disabling the Socket interface from {{ic|/etc/bluetooth/audio.conf}} by removing the line {{ic|1=Enable=Socket}} and adding line {{ic|1=Disable=Socket}}.<br />
<br />
== Tested headsets ==<br />
<br />
{| class="wikitable"<br />
! Model<br />
! Version<br />
! Comments<br />
! Compatible<br />
|-<br />
| '''Philips SHB9100'''<br />
| <br />
| Pause and resume is flakey. See [https://bbs.archlinux.org/viewtopic.php?pid=1315428#p1315428] for the underlying issue and a temporary solution to improve audio quality.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB7000'''<br />
| <br />
| Pause and resume is flaky.<br />
| {{R|Limited}}<br />
|-<br />
| '''Parrot Zik'''<br />
| <br />
| Firmware 1.04. The microphone is detected, but does not work. Sometimes it lags (but does not stutter); usually this is not noticeable unless playing games, in which case you may switch to a wired connection.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sony DR-BT50'''<br />
| bluez{4,5}<br />
| Works for a2dp, see [http://vlsd.blogspot.com/2013/11/bluetooth-headphones-and-arch-linux.html]). Adapter: D-Link DBT-120 USB dongle.<br />
| {{Yes}}<br />
|-<br />
| '''Sony SBH50'''<br />
| bluez5<br />
| Works for a2dp, Adapter: Broadcom Bluetooth 2.1 Device (Vendor=0a5c ProdID=219b Rev=03.43). Requires the {{ic|btusb}} [[modprobe|module]].<br />
| {{Yes}}<br />
|-<br />
| '''SoundBot SB220'''<br />
| bluez5, {{AUR|pulseaudio-git}}<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Auna Air 300'''<br />
| bluez5, pulseaudio-git<br />
| For some reason, a few restarts were required, and eventually it just started working.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sennheiser MM 400-X'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Audionic BlueBeats (B-777)'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Logitech Wireless Headset'''<br />
| bluez 5.14, pulseaudio-git<br />
| part number PN 981-000381, advertised for use with iPad<br />
| {{Yes}}<br />
|-<br />
| '''HMDX Jam Classic Bluetooth'''<br />
| bluez, pulseaudio-git<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''PT-810'''<br />
| bluez 5.14, pulseaudio-git<br />
| Generic USB-Powered Bluetooth Audio Receiver with 3.5mm headset jack and a2dp profile. Widely available as "USB Bluetooth Receiver." IDs as PT-810.<br />
| {{Yes}}<br />
|-<br />
| '''Philips SHB4000WT'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Philips AEA2000/12'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Nokia BH-104'''<br />
| bluez4<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Creative AirwaveHD'''<br />
| bluez 5.23<br />
| Bluetooth adapter Atheros Communications usb: 0cf3:0036<br />
| {{Yes}}<br />
|-<br />
| '''deleyCON Bluetooth Headset'''<br />
| bluez 5.23<br />
| Adapter: CSL - USB nano Bluetooth-Adapter V4.0. Tested a2dp profile. Untested microphone. Does not auto-connect (even when paired and trusted), must connect manually. Play/pause button mutes/unmutes the headphones, not the playback. Playback fwd/bwd buttons do not work (nothing visible with ''xev'').<br />
| {{R|Limited}}<br />
|-<br />
| '''UE BOOM'''<br />
| bluez5, pulseaudio-git<br />
| Music starts a little stuttered for a few seconds and later gets normal, however, there is a 5-sec lag on video playing.<br />
| {{R|Limited}}<br />
|}<br />
<br />
== See also ==<br />
<br />
Alternative method of connecting a BT headset to Linux:<br />
<br />
* [http://gablog.eu/online/node/80 GaBlog - Connect a Bluetooth headset to Linux]<br />
<br />
Using the same device on Windows and Linux without pairing the device over and over again<br />
<br />
* [http://ubuntuforums.org/showthread.php?p=9363229#post9363229 Dual booting with a Bluetooth keyboard]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=344656Bluetooth headset2014-11-14T20:31:05Z<p>Jstjohn: fix capitalization issues</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
[[ru:Bluetooth headset]]<br />
{{Related articles start}}<br />
{{Related|Bluetooth}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
<br />
Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation. <br />
<br />
{{Tip|The most recent version of [[Bluez]] does not support the Headset/Handsfree profiles. This means that microphone input will not work, and also no sound output on headsets that do not support the A2DP profile. For using a headset with the Headset/Handsfree profiles, you will need to jump down to the legacy methods which require using [[AUR]] to fetch alternative packages.<br />
}}<br />
<br />
{{Tip| {{AUR|pulseaudio-git}} has added native support for the Headset/Handsfree profiles and Bluez5.}}<br />
<br />
{{Tip|Bluez5 is only supported by PulseAudio and not by ALSA. If you do not want to use PulseAudio, you need to install an older Bluez version from AUR.}}<br />
<br />
== A2DP via Bluez5/PulseAudio ==<br />
<br />
PulseAudio 5.x supports A2DP per default.<br />
Make sure the following packages are installed:<br />
<br />
# pacman -S pulseaudio-alsa bluez bluez-libs bluez-utils<br />
<br />
Start the Bluetooth system:<br />
<br />
# systemctl start bluetooth<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
# bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
# power on<br />
# agent on<br />
# default-agent<br />
# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
shows a device that calls itself "Lasmex LBT10" and has MAC address ''00:1D:43:6D:03:26''. We will now use that MAC address to initiate the pairing:<br />
<br />
# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device:<br />
<br />
# connect 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[PulseAudio]]. You can now redirect any playback to that device using ''pavucontrol''.<br />
<br />
You can now disable scanning again and exit the program:<br />
# scan off<br />
# exit<br />
<br />
=== Troubleshooting ===<br />
<br />
Many users report frustration with getting A2DP to work. <br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, have a look at the log via one of the following commands:<br />
<br />
# systemctl status bluetooth<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
The problem in this case is that PulseAudio is not catching up. A common solution to this problem is to restart PulseAudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while PulseAudio runs as user. After restarting PulseAudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting PulseAudio does not work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
If that still does not work, or you are using PulseAudio's system-wide mode, also load the following PulseAudio modules (again these can be loaded via your default.pa or system.pa):<br />
<br />
module-bluetooth-policy<br />
module-bluez5-device<br />
module-bluez5-discover<br />
<br />
To have your headset auto connect you need to enable PulseAudio's switch-on-connect module. Add the following:<br />
{{hc|/etc/pulse/default.pa|<br />
# automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
You then need to tell ''bluetoothctl'' to trust your Bluetooth headset, or you will see errors like this:<br />
bluetoothd[487]: Authentication attempt without agent<br />
bluetoothd[487]: Access denied: org.bluez.Error.Rejected<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
After a reboot, your Bluetooth adapter will not power on by default. You need to add a udev rule to power it on:<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
# Set bluetooth power up<br />
ACTION=="add", SUBSYSTEM=="bluetooth", KERNEL=="hci[0-9]*", RUN+="/usr/bin/hciconfig %k up"<br />
}}<br />
<br />
==== Connecting works, but I cannot play sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your PulseAudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
== Legacy method: ALSA-BTSCO ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]].}}<br />
<br />
It is much easier to set up your bluetooth headset today, with bluez >= 3.16. You may want to try the out-of-box python script in [http://fosswire.com/2008/01/11/a2dp-stereo-linux/ this blog] (you need edit the script to work with gconftool-2). There is also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
You need your headset's bdaddr. It is of the form ''12:34:56:78:9A:BC''. Either find it in the documentation of your headset, on the headset itself or with the '''hcitool scan''' command.<br />
<br />
Install {{AUR|btsco}}.<br />
<br />
To load the kernel module, type:<br />
# modprobe snd-bt-sco<br />
There will now be an extra audio device. Use {{ic|alsamixer -cN}} (where N is most likely 1) to set the volume. You can access the device with any alsa-capable application by choosing the device ''BT headset'', or with any OSS application by using {{ic|/dev/dspN}} as the audio device.<br />
<br />
But to actually get any sound, you have to connect your headset to the computer first.<br />
<br />
=== Connecting the headset ===<br />
<br />
If you connect your headset for the first time, read the section about pairing first. To connect to your headset to the computer, use the command<br />
$ btsco -f <bdaddr><br />
for example<br />
$ btsco -f 12:34:56:78:9A:BC<br />
<br />
==== Pairing the headset with your computer ====<br />
<br />
The first time you connect the headset, you have to pair it with the computer. To do this, you need your headset's PIN. Depending on your headset you may have to reset the headset and repeat the pairing everytime you used the headset with another bluetooth device.<br />
<br />
There are two ways to pair your headset with the computer:<br />
<br />
===== Using ''bluez-gnome'' =====<br />
<br />
Install the ''bluez-gnome'' package from the community repository. Then start the '''bt-applet''' program. Once you try to connect to the headset, a window will open and ask for the PIN.<br />
<br />
===== Using ''passkey-agent'' =====<br />
<br />
Before connecting to the headset, enter the command<br />
$ passkey-agent --default <pin><br />
where ''<pin>'' is your headset's PIN. Then try to connect to the headset.<br />
<br />
=== Headset and Alsa Devices ===<br />
<br />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<br />
<br />
3. Pair your headset with your device:<br />
$ bluez-simple-agent (optional hci# ***) XX:XX:XX:XX:XX:XX<br />
and put in your pin (0000 or 1234, etc)<br />
<br />
4. Make sure your {{ic|/etc/bluetooth/audio.conf}} allows A2DP Audio Sinks. Place this line just bellow the [General] heading:<br />
Enable=Source,Sink,Media,Socket<br />
<br />
5. Add this to your {{ic|/etc/asound.conf}} file:<br />
#/etc/asound.conf<br />
<br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device XX:XX:XX:XX:XX:XX <br />
profile "auto"<br />
} <br />
} <br />
hint {<br />
show on<br />
description "BT Headset"<br />
} <br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
} <br />
<br />
6. Check to see if it has been added to alsa devices<br />
$ aplay -L<br />
<br />
7. Now play with aplay:<br />
$ aplay -D btheadset /path/to/audio/file<br />
<br />
or Mplayer:<br />
$ mplayer -ao alsa:device=btheadset /path/to/audio/or/video/file<br />
<br />
{{Tip|To find hci# for a usb dongle, type in <br />
$ hcitool dev<br />
}}<br />
<br />
=== Headset's multimedia buttons ===<br />
<br />
In order to get your bluetooth headset's multimedia buttons (play, pause, next, previous) working you need to create {{ic|/etc/modprobe.d/uinput.conf}} containing {{ic|uinput}}.<br />
<br />
== Legacy method: PulseAudio ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]] (references to {{ic|/etc/bluetooth/audio.conf}} and ''bluez-simple-agent'').}}<br />
<br />
This one is much easier and more elegant. PulseAudio will seamlessly switch between output devices when the headset is turned on. If you have ALSA as the sound server, you need the following packages installed:<br />
{{Pkg|pulseaudio}} and {{Pkg|pulseaudio-alsa}}.<br />
<br />
Now, to configure the audio output to use bluetooth, just install {{Pkg|pavucontrol}} and run it to configure the audio output:<br />
$ pavucontrol<br />
Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Audio sink fails ====<br />
<br />
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device. You will get "Audio sink fails".<br />
According to [http://wiki.gentoo.org/wiki/Bluetooth_Headset gentoo wiki], you have to verify than in {{ic|/etc/bluetooth/audio.conf}} there is {{ic|<nowiki>Enable=Socket</nowiki>}} under the {{ic|[General]}} section heading.<br />
<br />
Just do a {{ic|# systemctl restart bluetooth}} to apply it.<br />
<br />
==== Page timeout issue ====<br />
<br />
If you receive this error whilst trying to pair your headset with your system using bluez-simple-agent, then you can try to restart your system and use the graphical bluez applet of your desktop environment.<br />
<br />
== Legacy documentation: ALSA, bluez5 and PulseAudio method ==<br />
<br />
{{Accuracy|Describes two different methods, see the [[Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions|talk page]] for details.|Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions}}<br />
<br />
[[ALSA]], [[bluez|bluez5]], and [[PulseAudio]] work together to allow a wireless [[Bluetooth]] headset to play audio. The following method works with a Lenovo T61p laptop and SoundBot SB220 wireless bluetooth headset. The required software stack is extensive and failure to include all components can produce errors which are difficult to understand. The following list of software packages might not be the minimum required set and needs to be examined more closely.<br />
<br />
Bluez5 has a regression causing HSP/HFP Telephone profile to not be available. This regression is documented in the [http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/5.0/ draft release notes for Pulseaudio 5.0] which say (in "Notes for packagers"): "PulseAudio now supports BlueZ 5, but only the A2DP profile. BlueZ 4 is still the only way to make HSP/HFP work." ([https://fedoraproject.org/wiki/Common_F20_bugs#bluez5-profile from here])<br />
<br />
=== Install Software Packages ===<br />
<br />
The core software components are [[ALSA]], Bluez5, [[PulseAudio]]. However there are additional libraries which are required. As well as a player which can play audio files. The following section lists the software packages installed in order to connect the headset and play audio over the headset.<br />
<br />
==== Install ALSA and associated libraries ====<br />
<br />
[[ALSA]] works with the linux kernel to provide audio services to user mode software. The following packages are used with the [[Bluetooth]] headset: {{Pkg|alsa-utils}}, {{Pkg|alsa-plugins}}, {{Pkg|alsa-tools}}.<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. It is required for [[PulseAudio]] to interface with wireless headsets. Required packages: {{Pkg|bluez}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-libs}}.<br />
<br />
==== Install PulseAudio ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The {{AUR|pulseaudio-git}} package from [[AUR]] has capabilities not provided by the stock {{Pkg|pulseaudio}} package. The additional capabilities are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [https://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
Required packages: {{AUR|pulseaudio-git}}, {{Pkg|pavucontrol}}.<br />
<br />
==== Install Audacious ====<br />
<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Required packages: {{Pkg|audacious}}, {{Pkg|audacious-plugins}}.<br />
<br />
=== Procedure ===<br />
<br />
Once the required packages are installed, use this procedure to play audio with a bluetooth headset. The high level overview of the procedure is to pair the headset, connect the headset, configure the player and pulse audio controller and then play audio.<br />
<br />
Start the bluetooth service as root:<br />
# systemctl start bluetooth<br />
<br />
Verify Bluetooth is started<br />
# systemctl status bluetooth<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: active (running) since Sat 2013-12-07 12:31:14 PST; 12s ago<br />
Docs: man:bluetoothd(8)<br />
Main PID: 3136 (bluetoothd)<br />
Status: "Running"<br />
CGroup: /system.slice/bluetooth.service<br />
└─3136 /usr/lib/bluetooth/bluetoothd<br />
<br />
Dec 07 12:31:14 t61p systemd[1]: Starting Bluetooth service...<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth daemon 5.11<br />
Dec 07 12:31:14 t61p systemd[1]: Started Bluetooth service.<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Starting SDP server<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth management interface 1.3 i...ed<br />
Hint: Some lines were ellipsized, use -l to show in full.<br />
<br />
Start the PulseAudio daemon. This must be done after X windows is started and as a normal user.<br />
$ pulseaudio -D<br />
<br />
Verify the PulseAudio daemon is running.<br />
$ pulseaudio --check -v<br />
I: [pulseaudio] main.c: Daemon running as PID 3186<br />
<br />
Start up bluetoothctl as root and pair and connect your headset. As a regular user, bluetoothctl will pair but not connect. Perhaps this is related to the config file (shown below) which is setup for what appears to be the root user.<br />
Note: the procedure shown below is for an initial pair and connect of the headphone. If the headset is already paired, then the procedure below can be shortened to: power on, agent on, default-agent, connect <mac address>. The mac address can be seen from the devices command output.<br />
<br />
$ bluetoothctl <br />
[NEW] Controller 00:1E:4C:F4:98:5B t61p-0 [default]<br />
[NEW] Device 00:1A:7D:12:36:B9 SoundBot SB220<br />
[bluetooth]# show<br />
Controller 00:1E:4C:F4:98:5B<br />
Name: t61p<br />
Alias: t61p-0<br />
Class: 0x000000<br />
Powered: no<br />
Discoverable: no<br />
Pairable: yes<br />
UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Access Profile (00001800-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
Modalias: usb:v1D6Bp0246d050B<br />
Discovering: no<br />
[bluetooth]# power on<br />
[CHG] Controller 00:1E:4C:F4:98:5B Class: 0x0c010c<br />
Changing power on succeeded<br />
[CHG] Controller 00:1E:4C:F4:98:5B Powered: yes<br />
[bluetooth]# agent on<br />
Agent registered<br />
[bluetooth]# default-agent<br />
Default agent request successful<br />
<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# scan on<br />
Discovery started<br />
[CHG] Controller 00:1E:4C:F4:98:5B Discovering: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 RSSI: -61<br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
Attempting to pair with 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 UUIDs has unsupported type<br />
[CHG] Device 00:1A:7D:12:36:B9 Paired: yes<br />
Pairing successful<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
Connection successful<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
Device 00:1A:7D:12:36:B9<br />
Name: SoundBot SB220<br />
Alias: SoundBot SB220<br />
Class: 0x240404<br />
Icon: audio-card<br />
Paired: yes<br />
Trusted: no<br />
Blocked: no<br />
Connected: yes<br />
LegacyPairing: yes<br />
UUID: Headset (00001108-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
<br />
Start up alsamixer, for simplicity un-mute all your outputs. Oddly enough some can be muted though. The ones I had muted during playback were:<br />
* Headphones<br />
* SPIDF<br />
<br />
Start up audacious. Use the menu to select PulseAudio as your output. Somewhere I read that bluez5 requires pulseaudio-git and this jives with my experience.<br />
<br />
Start up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
[http://netskink.blogspot.com/2013/12/pulseaudio-pavucontrol-and-audacious.html screenshot of application settings]<br />
<br />
==== Miscellaneous configuration files ====<br />
<br />
For reference, these settings were also done.<br />
<br />
===== ALSA /etc/asound.conf =====<br />
<br />
The settings shown at the top of this page was used, but the additional modification for Intel laptop sound cards.<br />
<br />
{{bc|<nowiki><br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device 00:1A:7D:12:36:B9<br />
profile "auto"<br />
}<br />
}<br />
hint {<br />
show on<br />
description "BT Headset"<br />
}<br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
}<br />
options snd-hda-intel model=laptop<br />
</nowiki>}}<br />
<br />
===== /etc/dbus-1/system.d/bluetooth.conf =====<br />
<br />
The settings here seem to be enabled for root only. See the policy user="root" section. However, if a regular user is specified here, the system fails to start. Someone with more knowledge could explain why.<br />
<br />
{{hc|/etc/dbus-1/system.d/bluetooth.conf|<nowiki><br />
<!-- This configuration file specifies the required security policies for Bluetooth core daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<!-- ../system.conf have denied everything, so we just punch some holes --><br />
<br />
<policy user="root"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent1"/><br />
<allow send_interface="org.bluez.MediaEndpoint1"/><br />
<allow send_interface="org.bluez.MediaPlayer1"/><br />
<allow send_interface="org.bluez.ThermometerWatcher1"/><br />
<allow send_interface="org.bluez.AlertAgent1"/><br />
<allow send_interface="org.bluez.Profile1"/><br />
<allow send_interface="org.bluez.HeartRateWatcher1"/><br />
<allow send_interface="org.bluez.CyclingSpeedWatcher1"/><br />
</policy><br />
<br />
<policy at_console="true"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<!-- allow users of lp group (printing subsystem) to communicate with bluetoothd --><br />
<policy group="lp"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<policy context="default"><br />
<deny send_destination="org.bluez"/><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
===== Tested applications =====<br />
<br />
As noted above this will work easily with audacious. YouTube videos with Chromium and Flash Player will work on some videos. If the video has ads it will not work, but if the video does not have ads it will work. Just make sure that after audacious is working with Bluetooth headset, start Chromium, and navigate to YouTube. Find a video without leading ads, and it should play the audio. If the settings icon has the a menu with two drop-down combo boxes for Speed and Quality it will play.<br />
<br />
== Switch between HSV and A2DP setting ==<br />
<br />
This can easily be achieved by the following command where 2 needs to be changed with the correct device number.<br />
<br />
pacmd set-card-profile 2 a2dp<br />
<br />
=== A2DP not working with PulseAudio ===<br />
<br />
If PulseAudio fails when changing the profile to A2DP with bluez 4.1+ and PulseAudio 3.0+, you can try disabling the Socket interface from {{ic|/etc/bluetooth/audio.conf}} by removing the line {{ic|1=Enable=Socket}} and adding line {{ic|1=Disable=Socket}}.<br />
<br />
== Tested headsets ==<br />
<br />
{| class="wikitable"<br />
! Model<br />
! Version<br />
! Comments<br />
! Compatible<br />
|-<br />
| '''Philips SHB9100'''<br />
| <br />
| Pause and resume is flakey. See [https://bbs.archlinux.org/viewtopic.php?pid=1315428#p1315428] for the underlying issue and a temporary solution to improve audio quality.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB7000'''<br />
| <br />
| Pause and resume is flaky.<br />
| {{R|Limited}}<br />
|-<br />
| '''Parrot Zik'''<br />
| <br />
| Firmware 1.04. The microphone is detected, but does not work. Sometimes it lags (but does not stutter); usually this is not noticeable unless playing games, in which case you may switch to a wired connection.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sony DR-BT50'''<br />
| bluez{4,5}<br />
| Works for a2dp, see [http://vlsd.blogspot.com/2013/11/bluetooth-headphones-and-arch-linux.html]). Adapter: D-Link DBT-120 USB dongle.<br />
| {{Yes}}<br />
|-<br />
| '''Sony SBH50'''<br />
| bluez5<br />
| Works for a2dp, Adapter: Broadcom Bluetooth 2.1 Device (Vendor=0a5c ProdID=219b Rev=03.43). Requires the {{ic|btusb}} [[modprobe|module]].<br />
| {{Yes}}<br />
|-<br />
| '''SoundBot SB220'''<br />
| bluez5, {{AUR|pulseaudio-git}}<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Auna Air 300'''<br />
| bluez5, pulseaudio-git<br />
| For some reason, a few restarts were required, and eventually it just started working.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sennheiser MM 400-X'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Audionic BlueBeats (B-777)'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Logitech Wireless Headset'''<br />
| bluez 5.14, pulseaudio-git<br />
| part number PN 981-000381, advertised for use with iPad<br />
| {{Yes}}<br />
|-<br />
| '''HMDX Jam Classic Bluetooth'''<br />
| bluez, pulseaudio-git<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''PT-810'''<br />
| bluez 5.14, pulseaudio-git<br />
| Generic USB-Powered Bluetooth Audio Receiver with 3.5mm headset jack and a2dp profile. Widely available as "USB Bluetooth Receiver." IDs as PT-810.<br />
| {{Yes}}<br />
|-<br />
| '''Philips SHB4000WT'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Philips AEA2000/12'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Nokia BH-104'''<br />
| bluez4<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Creative AirwaveHD'''<br />
| bluez 5.23<br />
| Bluetooth adapter Atheros Communications usb: 0cf3:0036<br />
| {{Yes}}<br />
|-<br />
| '''deleyCON Bluetooth Headset'''<br />
| bluez 5.23<br />
| Adapter: CSL - USB nano Bluetooth-Adapter V4.0. Tested a2dp profile. Untested microphone. Does not auto-connect (even when paired and trusted), must connect manually. Play/pause button mutes/unmutes the headphones, not the playback. Playback fwd/bwd buttons do not work (nothing visible with ''xev'').<br />
| {{R|Limited}}<br />
|-<br />
| '''UE BOOM'''<br />
| bluez5, pulseaudio-git<br />
| Music starts a little stuttered for a few seconds and later gets normal, however, there is a 5-sec lag on video playing.<br />
| {{R|Limited}}<br />
|}<br />
<br />
== See also ==<br />
<br />
Alternative method of connecting a BT headset to Linux:<br />
<br />
* [http://gablog.eu/online/node/80 GaBlog - Connect a Bluetooth headset to Linux]<br />
<br />
Using the same device on Windows and Linux without pairing the device over and over again<br />
<br />
* [http://ubuntuforums.org/showthread.php?p=9363229#post9363229 Dual booting with a Bluetooth keyboard]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset_(%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9)&diff=344648Bluetooth headset (Русский)2014-11-14T20:24:53Z<p>Jstjohn: /* A2DP not working with pulseaudio */ add templates; fix capitalization</p>
<hr />
<div>[[Category:Sound (Русский)]]<br />
[[Category:Bluetooth (Русский)]]<br />
[[Category:Русский]]<br />
[[en:Bluetooth headset]]<br />
{{Related articles start (Русский)}}<br />
{{Related|Bluetooth (Русский)}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
{{Unmaintained (Русский)|}}<br />
{{Translateme|}}<br />
<br />
<br />
Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation. <br />
<br />
{{Tip|The most recent version of [[Bluez]] does not support the Headset/Handsfree profiles. This means that microphone input will not work, and also no sound output on headsets that do not support the A2DP profile. For using a headset with the Headset/Handsfree profiles, you will need to jump down to the legacy methods which require using [[AUR]] to fetch alternative packages.<br />
}}<br />
<br />
{{Tip|Bluez5 is only supported by Pulseaudio and not by ALSA. If you do not want to use Pulseaudio, you need to install an older Bluez version from AUR.}}<br />
<br />
== A2DP via Bluez5/Pulseaudio ==<br />
<br />
Pulseaudio 5.x supports A2DP per default.<br />
Make sure the following packages are installed:<br />
<br />
# pacman -S pulseaudio-alsa bluez bluez-libs bluez-utils<br />
<br />
Start the bluetooth system:<br />
<br />
# systemctl start bluetooth<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
# bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
# power on<br />
# agent on<br />
# default-agent<br />
# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
shows a device that calls itself "Lasmex LBT10" and has MAC address ''00:1D:43:6D:03:26''. We will now use that MAC address to initiate the pairing:<br />
<br />
# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device:<br />
<br />
# connect 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[Pulseaudio]]. You can now redirect any playback to that device using ''pavucontrol''.<br />
<br />
You can now disable scanning again and exit the program:<br />
# scan off<br />
# exit<br />
<br />
=== Troubleshooting ===<br />
<br />
Many users report frustation with getting A2DP to work. <br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, have a look at the log via one of the following commands:<br />
<br />
# systemctl status bluetooth<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
The problem in this case is that pulseaudio is not catching up. A common solution to this problem is to restart pulseaudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while pulseaudio runs as user. After restarting pulseaudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting pulseaudio doesn't work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
To have your headset auto connect you need to enable PulseAudio's switch-on-connect module. Add the following:<br />
{{hc|/etc/pulse/default.pa|<br />
# automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
You then need to tell ''bluetoothctl'' to trust your bluetooth headset or you will see errors like this:<br />
bluetoothd[487]: Authentication attempt without agent<br />
bluetoothd[487]: Access denied: org.bluez.Error.Rejected<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
After a reboot, your bluetooth adapter will not power on by default. You need to add a udev rule to power it on:<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
# Set bluetooth power up<br />
ACTION=="add", SUBSYSTEM=="bluetooth", KERNEL=="hci[0-9]*", RUN+="/usr/bin/hciconfig %k up"<br />
}}<br />
<br />
==== Connecting works, but I cannot play sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your pulseaudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
== Legacy method: ALSA-BTSCO ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]].}}<br />
<br />
It is much easier to set up your bluetooth headset today, with bluez >= 3.16. You may want to try the out-of-box python script in [http://fosswire.com/2008/01/11/a2dp-stereo-linux/ this blog] (you need edit the script to work with gconftool-2). There is also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
You need your headset's bdaddr. It is of the form ''12:34:56:78:9A:BC''. Either find it in the documentation of your headset, on the headset itself or with the '''hcitool scan''' command.<br />
<br />
Install {{AUR|btsco}}.<br />
<br />
To load the kernel module, type:<br />
# modprobe snd-bt-sco<br />
There will now be an extra audio device. Use {{ic|alsamixer -cN}} (where N is most likely 1) to set the volume. You can access the device with any alsa-capable application by choosing the device ''BT headset'', or with any OSS application by using {{ic|/dev/dspN}} as the audio device.<br />
<br />
But to actually get any sound, you have to connect your headset to the computer first.<br />
<br />
=== Connecting the headset ===<br />
<br />
If you connect your headset for the first time, read the section about pairing first. To connect to your headset to the computer, use the command<br />
$ btsco -f <bdaddr><br />
for example<br />
$ btsco -f 12:34:56:78:9A:BC<br />
<br />
==== Pairing the headset with your computer ====<br />
<br />
The first time you connect the headset, you have to pair it with the computer. To do this, you need your headset's PIN. Depending on your headset you may have to reset the headset and repeat the pairing everytime you used the headset with another bluetooth device.<br />
<br />
There are two ways to pair your headset with the computer:<br />
<br />
===== Using ''bluez-gnome'' =====<br />
<br />
Install the ''bluez-gnome'' package from the community repository. Then start the '''bt-applet''' program. Once you try to connect to the headset, a window will open and ask for the PIN.<br />
<br />
===== Using ''passkey-agent'' =====<br />
<br />
Before connecting to the headset, enter the command<br />
$ passkey-agent --default <pin><br />
where ''<pin>'' is your headset's PIN. Then try to connect to the headset.<br />
<br />
=== Headset and Alsa Devices ===<br />
<br />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<br />
<br />
3. Pair your headset with your device:<br />
$ bluez-simple-agent (optional hci# ***) XX:XX:XX:XX:XX:XX<br />
and put in your pin (0000 or 1234, etc)<br />
<br />
4. Make sure your {{ic|/etc/bluetooth/audio.conf}} allows A2DP Audio Sinks. Place this line just bellow the [Genera] heading:<br />
Enable=Source,Sink,Media,Socket<br />
<br />
5. Add this to your {{ic|/etc/asound.conf}} file:<br />
#/etc/asound.conf<br />
<br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device XX:XX:XX:XX:XX:XX <br />
profile "auto"<br />
} <br />
} <br />
hint {<br />
show on<br />
description "BT Headset"<br />
} <br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
} <br />
<br />
6. Check to see if it has been added to alsa devices<br />
$ aplay -L<br />
<br />
7. Now play with aplay:<br />
$ aplay -D btheadset /path/to/audio/file<br />
<br />
or Mplayer:<br />
$ mplayer -ao alsa:device=btheadset /path/to/audio/or/video/file<br />
<br />
{{Tip|To find hci# for a usb dongle, type in <br />
$ hcitool dev<br />
}}<br />
<br />
=== Headset's multimedia buttons ===<br />
<br />
In order to get your bluetooth headset's multimedia buttons (play, pause, next, previous) working you need to create {{ic|/etc/modprobe.d/uinput.conf}} containing {{ic|uinput}}.<br />
<br />
== Legacy method: PulseAudio ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]] (references to {{ic|/etc/bluetooth/audio.conf}} and ''bluez-simple-agent'').}}<br />
<br />
This one is much easier and more elegant. PulseAudio will seamlessly switch between output devices when the headset is turned on. If you have ALSA as the sound server, you need the following packages installed:<br />
{{Pkg|pulseaudio}} and {{Pkg|pulseaudio-alsa}}.<br />
<br />
Now, to configure the audio output to use bluetooth, just install {{Pkg|pavucontrol}} and run it to configure the audio output:<br />
$ pavucontrol<br />
<br />
See [http://dev.funkynerd.com/knowledgebase/articles/5 this blog] for further explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Audio sink fails ====<br />
<br />
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device. You will get "Audio sink fails".<br />
According to [http://wiki.gentoo.org/wiki/Bluetooth_Headset gentoo wiki], you have to verify than in {{ic|/etc/bluetooth/audio.conf}} there is {{ic|<nowiki>Enable=Socket</nowiki>}} under the {{ic|[General]}} section heading.<br />
<br />
Just do a {{ic|# systemctl restart bluetooth}} to apply it.<br />
<br />
==== Page timeout issue ====<br />
<br />
If you receive this error whilst trying to pair your headset with your system using bluez-simple-agent, then you can try to restart your system and use the graphical bluez applet of your desktop environment.<br />
<br />
== Legacy documentation: ALSA, bluez5 and PulseAudio method ==<br />
<br />
{{Accuracy|Describes two different methods, see the [[Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions|talk page]] for details.|Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions}}<br />
<br />
[[ALSA]], [[bluez|bluez5]], and [[PulseAudio]] work together to allow a wireless [[Bluetooth]] headset to play audio. The following method works with a Lenovo T61p laptop and SoundBot SB220 wireless bluetooth headset. The required software stack is extensive and failure to include all components can produce errors which are difficult to understand. The following list of software packages might not be the minimum required set and needs to be examined more closely.<br />
<br />
Bluez5 has a regression causing HSP/HFP Telephone profile to not be available. This regression is documented in the [http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/5.0/ draft release notes for Pulseaudio 5.0] which say (in "Notes for packagers"): "PulseAudio now supports BlueZ 5, but only the A2DP profile. BlueZ 4 is still the only way to make HSP/HFP work." ([https://fedoraproject.org/wiki/Common_F20_bugs#bluez5-profile from here])<br />
<br />
=== Install Software Packages ===<br />
<br />
The core software components are [[ALSA]], Bluez5, [[Pulseaudio]]. However there are additional libraries which are required. As well as a player which can play audio files. The following section lists the software packages installed in order to connect the headset and play audio over the headset.<br />
<br />
==== Install ALSA and associated libraries ====<br />
<br />
[[ALSA]] works with the linux kernel to provide audio services to user mode software. The following packages are used with the [[Bluetooth]] headset: {{Pkg|alsa-utils}}, {{Pkg|alsa-plugins}}, {{Pkg|alsa-tools}}.<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. It is required for [[PulseAudio]] to interface with wireless headsets. Required packages: {{Pkg|bluez}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-libs}}.<br />
<br />
==== Install PulseAudio ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The {{AUR|pulseaudio-git}} package from [[AUR]] has capabilities not provided by the stock {{Pkg|pulseaudio}} package. The additional capabilities are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [https://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
Required packages: {{AUR|pulseaudio-git}}, {{Pkg|pavucontrol}}.<br />
<br />
==== Install Audacious ====<br />
<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Required packages: {{Pkg|audacious}}, {{Pkg|audacious-plugins}}.<br />
<br />
=== Procedure ===<br />
<br />
Once the required packages are installed, use this procedure to play audio with a bluetooth headset. The high level overview of the procedure is to pair the headset, connect the headset, configure the player and pulse audio controller and then play audio.<br />
<br />
Start the bluetooth service as root or use sudo<br />
# systemctl start bluetooth<br />
<br />
Verify Bluetooth is started<br />
# systemctl status bluetooth<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: active (running) since Sat 2013-12-07 12:31:14 PST; 12s ago<br />
Docs: man:bluetoothd(8)<br />
Main PID: 3136 (bluetoothd)<br />
Status: "Running"<br />
CGroup: /system.slice/bluetooth.service<br />
└─3136 /usr/lib/bluetooth/bluetoothd<br />
<br />
Dec 07 12:31:14 t61p systemd[1]: Starting Bluetooth service...<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth daemon 5.11<br />
Dec 07 12:31:14 t61p systemd[1]: Started Bluetooth service.<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Starting SDP server<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth management interface 1.3 i...ed<br />
Hint: Some lines were ellipsized, use -l to show in full.<br />
<br />
Start the pulseaudio daemon. This must be done after X windows is started and as a normal user.<br />
$ pulseaudio -D<br />
<br />
Verify the pulseaudio daemon is running.<br />
$ pulseaudio --check -v<br />
I: [pulseaudio] main.c: Daemon running as PID 3186<br />
<br />
Start up bluetoothctl as root and pair and connect your headset. As a regular user, bluetoothctl will pair but not connect. Perhaps this is related to the config file (shown below) which is setup for what appears to be the root user.<br />
Note: the procedure shown below is for an initial pair and connect of the headphone. If the headset is already paired, then the procedure below can be shortened to: power on, agent on, default-agent, connect <mac address>. The mac address can be seen from the devices command output.<br />
<br />
$ bluetoothctl <br />
[NEW] Controller 00:1E:4C:F4:98:5B t61p-0 [default]<br />
[NEW] Device 00:1A:7D:12:36:B9 SoundBot SB220<br />
[bluetooth]# show<br />
Controller 00:1E:4C:F4:98:5B<br />
Name: t61p<br />
Alias: t61p-0<br />
Class: 0x000000<br />
Powered: no<br />
Discoverable: no<br />
Pairable: yes<br />
UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Access Profile (00001800-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
Modalias: usb:v1D6Bp0246d050B<br />
Discovering: no<br />
[bluetooth]# power on<br />
[CHG] Controller 00:1E:4C:F4:98:5B Class: 0x0c010c<br />
Changing power on succeeded<br />
[CHG] Controller 00:1E:4C:F4:98:5B Powered: yes<br />
[bluetooth]# agent on<br />
Agent registered<br />
[bluetooth]# default-agent<br />
Default agent request successful<br />
<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# scan on<br />
Discovery started<br />
[CHG] Controller 00:1E:4C:F4:98:5B Discovering: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 RSSI: -61<br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
Attempting to pair with 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 UUIDs has unsupported type<br />
[CHG] Device 00:1A:7D:12:36:B9 Paired: yes<br />
Pairing successful<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
Connection successful<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
Device 00:1A:7D:12:36:B9<br />
Name: SoundBot SB220<br />
Alias: SoundBot SB220<br />
Class: 0x240404<br />
Icon: audio-card<br />
Paired: yes<br />
Trusted: no<br />
Blocked: no<br />
Connected: yes<br />
LegacyPairing: yes<br />
UUID: Headset (00001108-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
<br />
Start up alsamixer, for simplicity un-mute all your outputs. Oddly enough some can be muted though. The ones I had muted during playback were:<br />
* Headphones<br />
* SPIDF<br />
<br />
Start up audacious. Use the menu to select pulseaudio as your output. Somewhere I read that bluez5 requires pulseaudio-git and this jives with my experience.<br />
<br />
Start up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
[http://netskink.blogspot.com/2013/12/pulseaudio-pavucontrol-and-audacious.html screenshot of application settings]<br />
<br />
==== Miscellaneous Configuration Files ====<br />
<br />
For reference these settings were also done.<br />
<br />
===== ALSA /etc/asound.conf =====<br />
<br />
The settings shown at the top of this page was used, but the additional modification for intel laptop soundcards.<br />
<br />
{{bc|<nowiki><br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device 00:1A:7D:12:36:B9<br />
profile "auto"<br />
}<br />
}<br />
hint {<br />
show on<br />
description "BT Headset"<br />
}<br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
}<br />
options snd-hda-intel model=laptop<br />
</nowiki>}}<br />
<br />
===== /etc/dbus-1/system.d/bluetooth.conf =====<br />
<br />
The settings here seem to be enabled for root only. See the policy user="root" section. However, if a regular user is specified here, the system fails to start. Someone with more knowledge could explain why.<br />
<br />
{{hc|/etc/dbus-1/system.d/bluetooth.conf|<nowiki><br />
<!-- This configuration file specifies the required security policies for Bluetooth core daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<!-- ../system.conf have denied everything, so we just punch some holes --><br />
<br />
<policy user="root"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent1"/><br />
<allow send_interface="org.bluez.MediaEndpoint1"/><br />
<allow send_interface="org.bluez.MediaPlayer1"/><br />
<allow send_interface="org.bluez.ThermometerWatcher1"/><br />
<allow send_interface="org.bluez.AlertAgent1"/><br />
<allow send_interface="org.bluez.Profile1"/><br />
<allow send_interface="org.bluez.HeartRateWatcher1"/><br />
<allow send_interface="org.bluez.CyclingSpeedWatcher1"/><br />
</policy><br />
<br />
<policy at_console="true"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<!-- allow users of lp group (printing subsystem) to communicate with bluetoothd --><br />
<policy group="lp"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<policy context="default"><br />
<deny send_destination="org.bluez"/><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
===== Tested applications =====<br />
<br />
As noted above this will work easily with audacious. YouTube videos with Chromium and Flash Player will work on some videos. If the video has ads it will not work, but if the video does not have ads it will work. Just make sure that after audacious is working with Bluetooth headset, start Chromium, and navigate to YouTube. Find a video without leading ads, and it should play the audio. If the settings icon has the a menu with two drop-down combo boxes for Speed and Quality it will play.<br />
<br />
== Switch between HSV and A2DP setting ==<br />
This can easily be achieved by the following command where 2 needs to be changed with the correct device number.<br />
<br />
pacmd set-card-profile 2 a2dp<br />
<br />
=== A2DP not working with PulseAudio ===<br />
<br />
If PulseAudio fails when changing the profile to A2DP with bluez 4.1+ and PulseAudio 3.0+, you can try disabling the Socket interface from {{ic|/etc/bluetooth/audio.conf}} by removing the line {{ic|1=Enable=Socket}} and adding line {{ic|1=Disable=Socket}}.<br />
<br />
== Tested Headsets ==<br />
The following Bluetooth headsets have been tested with Arch Linux<br />
* Philips SHB9100 - Confirmed NOT TO WORK well. Have tried ''everything'' after a while they cut out. Pause and resume too is flakky and basically the whole wireless bluetooth experience is horrible. The following forum post[https://bbs.archlinux.org/viewtopic.php?pid=1315428#p1315428] explains an underlying issue and describes a temporary solution which can be used to improve the audio quality pending a proper fix.<br />
* Parrot Zik - Confirmed to work out of the box with firmware 1.04! The MIC however is detected, but does not work at all. Sometimes it can lag behind (not stutter) but most of the times it is not noticeable unless you playing a game, in which case I would switch to wired which resolves the issue.<br />
* Sony DR-BT50 works for a2dp both with bluez4 and bluez5 (instructions here[http://vlsd.blogspot.com/2013/11/bluetooth-headphones-and-arch-linux.html], subject to change). Adapter: D-Link DBT-120 USB dongle.<br />
* Sony SBH50 works for a2dp with bluez5 and pulseaudio. Adapter: Broadcom Bluetooth 2.1 Device (Vendor=0a5c ProdID=219b Rev=03.43; not sure what the exact model). Does not work until `sudo modprobe btusb`.<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<br />
* Auna Air 300 works well with bluez5, pulseaudio-git, and e.g. also mocp when running the latter through padsp. For some reason, a few restarts and re-tries were required, and eventually it just started working. <br />
* Sennheiser MM 400-X works out of the box with bluez5 and pulseaudio 4.0-6<br />
* Audionic BlueBeats (B-777) works out of the box with bluez5 and pulseaudio 4.0-6<br />
* Logitech Wireless Headset (part number PN 981-000381, advertised for use with iPad) works with bluez 5.14 and pulseaudio-git.<br />
* HMDX Jam Classic Bluetooth works with bluez, pulseaudio-git and pavucontrol<br />
* PT-810 - Generic USB-Powered Bluetooth Audio Receiver with 3.5mm headset jack and a2dp profile. Widely available as "USB Bluetooth Receiver." IDs as PT-810. Works with bluez 5.14 and pulseaudio-git.<br />
* Philips SHB4000WT works out of the box with bluez5 and pulseaudio 5.0<br />
* Philips AEA2000/12 works also out of the box with bluez 5.18-1 (and previous) and pulseaudio 5.0<br />
* Nokia BH-104 - does not work with bluez5. It use to work fine with bluez4, but since Gnome requires bluez5 I can't downgrade.<br />
* Creative AirwaveHD - works with bluez 5.23 and pulseaudio 5.0 with Bluetooth adapter Atheros Communications usb: 0cf3:0036<br />
<br />
== See also ==<br />
<br />
Alternative method of connecting a BT headset to Linux:<br />
<br />
* [http://gablog.eu/online/node/80 GaBlog - Connect a bluetooth headset to linux]<br />
<br />
Using the same device on Windows and Linux without pairing the device over and over again<br />
<br />
* [http://ubuntuforums.org/showthread.php?p=9363229#post9363229 Dual booting with a bluetooth keyboard]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset_(%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9)&diff=344647Bluetooth headset (Русский)2014-11-14T20:23:38Z<p>Jstjohn: /* Tested applications */ minor grammar improvements</p>
<hr />
<div>[[Category:Sound (Русский)]]<br />
[[Category:Bluetooth (Русский)]]<br />
[[Category:Русский]]<br />
[[en:Bluetooth headset]]<br />
{{Related articles start (Русский)}}<br />
{{Related|Bluetooth (Русский)}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
{{Unmaintained (Русский)|}}<br />
{{Translateme|}}<br />
<br />
<br />
Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation. <br />
<br />
{{Tip|The most recent version of [[Bluez]] does not support the Headset/Handsfree profiles. This means that microphone input will not work, and also no sound output on headsets that do not support the A2DP profile. For using a headset with the Headset/Handsfree profiles, you will need to jump down to the legacy methods which require using [[AUR]] to fetch alternative packages.<br />
}}<br />
<br />
{{Tip|Bluez5 is only supported by Pulseaudio and not by ALSA. If you do not want to use Pulseaudio, you need to install an older Bluez version from AUR.}}<br />
<br />
== A2DP via Bluez5/Pulseaudio ==<br />
<br />
Pulseaudio 5.x supports A2DP per default.<br />
Make sure the following packages are installed:<br />
<br />
# pacman -S pulseaudio-alsa bluez bluez-libs bluez-utils<br />
<br />
Start the bluetooth system:<br />
<br />
# systemctl start bluetooth<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
# bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
# power on<br />
# agent on<br />
# default-agent<br />
# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
shows a device that calls itself "Lasmex LBT10" and has MAC address ''00:1D:43:6D:03:26''. We will now use that MAC address to initiate the pairing:<br />
<br />
# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device:<br />
<br />
# connect 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[Pulseaudio]]. You can now redirect any playback to that device using ''pavucontrol''.<br />
<br />
You can now disable scanning again and exit the program:<br />
# scan off<br />
# exit<br />
<br />
=== Troubleshooting ===<br />
<br />
Many users report frustation with getting A2DP to work. <br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, have a look at the log via one of the following commands:<br />
<br />
# systemctl status bluetooth<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
The problem in this case is that pulseaudio is not catching up. A common solution to this problem is to restart pulseaudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while pulseaudio runs as user. After restarting pulseaudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting pulseaudio doesn't work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
To have your headset auto connect you need to enable PulseAudio's switch-on-connect module. Add the following:<br />
{{hc|/etc/pulse/default.pa|<br />
# automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
You then need to tell ''bluetoothctl'' to trust your bluetooth headset or you will see errors like this:<br />
bluetoothd[487]: Authentication attempt without agent<br />
bluetoothd[487]: Access denied: org.bluez.Error.Rejected<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
After a reboot, your bluetooth adapter will not power on by default. You need to add a udev rule to power it on:<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
# Set bluetooth power up<br />
ACTION=="add", SUBSYSTEM=="bluetooth", KERNEL=="hci[0-9]*", RUN+="/usr/bin/hciconfig %k up"<br />
}}<br />
<br />
==== Connecting works, but I cannot play sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your pulseaudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
== Legacy method: ALSA-BTSCO ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]].}}<br />
<br />
It is much easier to set up your bluetooth headset today, with bluez >= 3.16. You may want to try the out-of-box python script in [http://fosswire.com/2008/01/11/a2dp-stereo-linux/ this blog] (you need edit the script to work with gconftool-2). There is also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
You need your headset's bdaddr. It is of the form ''12:34:56:78:9A:BC''. Either find it in the documentation of your headset, on the headset itself or with the '''hcitool scan''' command.<br />
<br />
Install {{AUR|btsco}}.<br />
<br />
To load the kernel module, type:<br />
# modprobe snd-bt-sco<br />
There will now be an extra audio device. Use {{ic|alsamixer -cN}} (where N is most likely 1) to set the volume. You can access the device with any alsa-capable application by choosing the device ''BT headset'', or with any OSS application by using {{ic|/dev/dspN}} as the audio device.<br />
<br />
But to actually get any sound, you have to connect your headset to the computer first.<br />
<br />
=== Connecting the headset ===<br />
<br />
If you connect your headset for the first time, read the section about pairing first. To connect to your headset to the computer, use the command<br />
$ btsco -f <bdaddr><br />
for example<br />
$ btsco -f 12:34:56:78:9A:BC<br />
<br />
==== Pairing the headset with your computer ====<br />
<br />
The first time you connect the headset, you have to pair it with the computer. To do this, you need your headset's PIN. Depending on your headset you may have to reset the headset and repeat the pairing everytime you used the headset with another bluetooth device.<br />
<br />
There are two ways to pair your headset with the computer:<br />
<br />
===== Using ''bluez-gnome'' =====<br />
<br />
Install the ''bluez-gnome'' package from the community repository. Then start the '''bt-applet''' program. Once you try to connect to the headset, a window will open and ask for the PIN.<br />
<br />
===== Using ''passkey-agent'' =====<br />
<br />
Before connecting to the headset, enter the command<br />
$ passkey-agent --default <pin><br />
where ''<pin>'' is your headset's PIN. Then try to connect to the headset.<br />
<br />
=== Headset and Alsa Devices ===<br />
<br />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<br />
<br />
3. Pair your headset with your device:<br />
$ bluez-simple-agent (optional hci# ***) XX:XX:XX:XX:XX:XX<br />
and put in your pin (0000 or 1234, etc)<br />
<br />
4. Make sure your {{ic|/etc/bluetooth/audio.conf}} allows A2DP Audio Sinks. Place this line just bellow the [Genera] heading:<br />
Enable=Source,Sink,Media,Socket<br />
<br />
5. Add this to your {{ic|/etc/asound.conf}} file:<br />
#/etc/asound.conf<br />
<br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device XX:XX:XX:XX:XX:XX <br />
profile "auto"<br />
} <br />
} <br />
hint {<br />
show on<br />
description "BT Headset"<br />
} <br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
} <br />
<br />
6. Check to see if it has been added to alsa devices<br />
$ aplay -L<br />
<br />
7. Now play with aplay:<br />
$ aplay -D btheadset /path/to/audio/file<br />
<br />
or Mplayer:<br />
$ mplayer -ao alsa:device=btheadset /path/to/audio/or/video/file<br />
<br />
{{Tip|To find hci# for a usb dongle, type in <br />
$ hcitool dev<br />
}}<br />
<br />
=== Headset's multimedia buttons ===<br />
<br />
In order to get your bluetooth headset's multimedia buttons (play, pause, next, previous) working you need to create {{ic|/etc/modprobe.d/uinput.conf}} containing {{ic|uinput}}.<br />
<br />
== Legacy method: PulseAudio ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]] (references to {{ic|/etc/bluetooth/audio.conf}} and ''bluez-simple-agent'').}}<br />
<br />
This one is much easier and more elegant. PulseAudio will seamlessly switch between output devices when the headset is turned on. If you have ALSA as the sound server, you need the following packages installed:<br />
{{Pkg|pulseaudio}} and {{Pkg|pulseaudio-alsa}}.<br />
<br />
Now, to configure the audio output to use bluetooth, just install {{Pkg|pavucontrol}} and run it to configure the audio output:<br />
$ pavucontrol<br />
<br />
See [http://dev.funkynerd.com/knowledgebase/articles/5 this blog] for further explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Audio sink fails ====<br />
<br />
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device. You will get "Audio sink fails".<br />
According to [http://wiki.gentoo.org/wiki/Bluetooth_Headset gentoo wiki], you have to verify than in {{ic|/etc/bluetooth/audio.conf}} there is {{ic|<nowiki>Enable=Socket</nowiki>}} under the {{ic|[General]}} section heading.<br />
<br />
Just do a {{ic|# systemctl restart bluetooth}} to apply it.<br />
<br />
==== Page timeout issue ====<br />
<br />
If you receive this error whilst trying to pair your headset with your system using bluez-simple-agent, then you can try to restart your system and use the graphical bluez applet of your desktop environment.<br />
<br />
== Legacy documentation: ALSA, bluez5 and PulseAudio method ==<br />
<br />
{{Accuracy|Describes two different methods, see the [[Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions|talk page]] for details.|Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions}}<br />
<br />
[[ALSA]], [[bluez|bluez5]], and [[PulseAudio]] work together to allow a wireless [[Bluetooth]] headset to play audio. The following method works with a Lenovo T61p laptop and SoundBot SB220 wireless bluetooth headset. The required software stack is extensive and failure to include all components can produce errors which are difficult to understand. The following list of software packages might not be the minimum required set and needs to be examined more closely.<br />
<br />
Bluez5 has a regression causing HSP/HFP Telephone profile to not be available. This regression is documented in the [http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/5.0/ draft release notes for Pulseaudio 5.0] which say (in "Notes for packagers"): "PulseAudio now supports BlueZ 5, but only the A2DP profile. BlueZ 4 is still the only way to make HSP/HFP work." ([https://fedoraproject.org/wiki/Common_F20_bugs#bluez5-profile from here])<br />
<br />
=== Install Software Packages ===<br />
<br />
The core software components are [[ALSA]], Bluez5, [[Pulseaudio]]. However there are additional libraries which are required. As well as a player which can play audio files. The following section lists the software packages installed in order to connect the headset and play audio over the headset.<br />
<br />
==== Install ALSA and associated libraries ====<br />
<br />
[[ALSA]] works with the linux kernel to provide audio services to user mode software. The following packages are used with the [[Bluetooth]] headset: {{Pkg|alsa-utils}}, {{Pkg|alsa-plugins}}, {{Pkg|alsa-tools}}.<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. It is required for [[PulseAudio]] to interface with wireless headsets. Required packages: {{Pkg|bluez}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-libs}}.<br />
<br />
==== Install PulseAudio ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The {{AUR|pulseaudio-git}} package from [[AUR]] has capabilities not provided by the stock {{Pkg|pulseaudio}} package. The additional capabilities are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [https://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
Required packages: {{AUR|pulseaudio-git}}, {{Pkg|pavucontrol}}.<br />
<br />
==== Install Audacious ====<br />
<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Required packages: {{Pkg|audacious}}, {{Pkg|audacious-plugins}}.<br />
<br />
=== Procedure ===<br />
<br />
Once the required packages are installed, use this procedure to play audio with a bluetooth headset. The high level overview of the procedure is to pair the headset, connect the headset, configure the player and pulse audio controller and then play audio.<br />
<br />
Start the bluetooth service as root or use sudo<br />
# systemctl start bluetooth<br />
<br />
Verify Bluetooth is started<br />
# systemctl status bluetooth<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: active (running) since Sat 2013-12-07 12:31:14 PST; 12s ago<br />
Docs: man:bluetoothd(8)<br />
Main PID: 3136 (bluetoothd)<br />
Status: "Running"<br />
CGroup: /system.slice/bluetooth.service<br />
└─3136 /usr/lib/bluetooth/bluetoothd<br />
<br />
Dec 07 12:31:14 t61p systemd[1]: Starting Bluetooth service...<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth daemon 5.11<br />
Dec 07 12:31:14 t61p systemd[1]: Started Bluetooth service.<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Starting SDP server<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth management interface 1.3 i...ed<br />
Hint: Some lines were ellipsized, use -l to show in full.<br />
<br />
Start the pulseaudio daemon. This must be done after X windows is started and as a normal user.<br />
$ pulseaudio -D<br />
<br />
Verify the pulseaudio daemon is running.<br />
$ pulseaudio --check -v<br />
I: [pulseaudio] main.c: Daemon running as PID 3186<br />
<br />
Start up bluetoothctl as root and pair and connect your headset. As a regular user, bluetoothctl will pair but not connect. Perhaps this is related to the config file (shown below) which is setup for what appears to be the root user.<br />
Note: the procedure shown below is for an initial pair and connect of the headphone. If the headset is already paired, then the procedure below can be shortened to: power on, agent on, default-agent, connect <mac address>. The mac address can be seen from the devices command output.<br />
<br />
$ bluetoothctl <br />
[NEW] Controller 00:1E:4C:F4:98:5B t61p-0 [default]<br />
[NEW] Device 00:1A:7D:12:36:B9 SoundBot SB220<br />
[bluetooth]# show<br />
Controller 00:1E:4C:F4:98:5B<br />
Name: t61p<br />
Alias: t61p-0<br />
Class: 0x000000<br />
Powered: no<br />
Discoverable: no<br />
Pairable: yes<br />
UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Access Profile (00001800-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
Modalias: usb:v1D6Bp0246d050B<br />
Discovering: no<br />
[bluetooth]# power on<br />
[CHG] Controller 00:1E:4C:F4:98:5B Class: 0x0c010c<br />
Changing power on succeeded<br />
[CHG] Controller 00:1E:4C:F4:98:5B Powered: yes<br />
[bluetooth]# agent on<br />
Agent registered<br />
[bluetooth]# default-agent<br />
Default agent request successful<br />
<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# scan on<br />
Discovery started<br />
[CHG] Controller 00:1E:4C:F4:98:5B Discovering: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 RSSI: -61<br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
Attempting to pair with 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 UUIDs has unsupported type<br />
[CHG] Device 00:1A:7D:12:36:B9 Paired: yes<br />
Pairing successful<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
Connection successful<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
Device 00:1A:7D:12:36:B9<br />
Name: SoundBot SB220<br />
Alias: SoundBot SB220<br />
Class: 0x240404<br />
Icon: audio-card<br />
Paired: yes<br />
Trusted: no<br />
Blocked: no<br />
Connected: yes<br />
LegacyPairing: yes<br />
UUID: Headset (00001108-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
<br />
Start up alsamixer, for simplicity un-mute all your outputs. Oddly enough some can be muted though. The ones I had muted during playback were:<br />
* Headphones<br />
* SPIDF<br />
<br />
Start up audacious. Use the menu to select pulseaudio as your output. Somewhere I read that bluez5 requires pulseaudio-git and this jives with my experience.<br />
<br />
Start up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
[http://netskink.blogspot.com/2013/12/pulseaudio-pavucontrol-and-audacious.html screenshot of application settings]<br />
<br />
==== Miscellaneous Configuration Files ====<br />
<br />
For reference these settings were also done.<br />
<br />
===== ALSA /etc/asound.conf =====<br />
<br />
The settings shown at the top of this page was used, but the additional modification for intel laptop soundcards.<br />
<br />
{{bc|<nowiki><br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device 00:1A:7D:12:36:B9<br />
profile "auto"<br />
}<br />
}<br />
hint {<br />
show on<br />
description "BT Headset"<br />
}<br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
}<br />
options snd-hda-intel model=laptop<br />
</nowiki>}}<br />
<br />
===== /etc/dbus-1/system.d/bluetooth.conf =====<br />
<br />
The settings here seem to be enabled for root only. See the policy user="root" section. However, if a regular user is specified here, the system fails to start. Someone with more knowledge could explain why.<br />
<br />
{{hc|/etc/dbus-1/system.d/bluetooth.conf|<nowiki><br />
<!-- This configuration file specifies the required security policies for Bluetooth core daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<!-- ../system.conf have denied everything, so we just punch some holes --><br />
<br />
<policy user="root"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent1"/><br />
<allow send_interface="org.bluez.MediaEndpoint1"/><br />
<allow send_interface="org.bluez.MediaPlayer1"/><br />
<allow send_interface="org.bluez.ThermometerWatcher1"/><br />
<allow send_interface="org.bluez.AlertAgent1"/><br />
<allow send_interface="org.bluez.Profile1"/><br />
<allow send_interface="org.bluez.HeartRateWatcher1"/><br />
<allow send_interface="org.bluez.CyclingSpeedWatcher1"/><br />
</policy><br />
<br />
<policy at_console="true"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<!-- allow users of lp group (printing subsystem) to communicate with bluetoothd --><br />
<policy group="lp"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<policy context="default"><br />
<deny send_destination="org.bluez"/><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
===== Tested applications =====<br />
<br />
As noted above this will work easily with audacious. YouTube videos with Chromium and Flash Player will work on some videos. If the video has ads it will not work, but if the video does not have ads it will work. Just make sure that after audacious is working with Bluetooth headset, start Chromium, and navigate to YouTube. Find a video without leading ads, and it should play the audio. If the settings icon has the a menu with two drop-down combo boxes for Speed and Quality it will play.<br />
<br />
== Switch between HSV and A2DP setting ==<br />
This can easily be achieved by the following command where 2 needs to be changed with the correct device number.<br />
<br />
pacmd set-card-profile 2 a2dp<br />
<br />
=== A2DP not working with pulseaudio ===<br />
<br />
If pulseaudio fails when changing the profile to A2DP with bluez 4.1+ and pulseaudio 3.0+, you can try disabling the Socket interface from /etc/bluetooth/audio.conf by removing the line Enable=Socket and adding line Disable=Socket<br />
<br />
Disable=Socket<br />
<br />
== Tested Headsets ==<br />
The following Bluetooth headsets have been tested with Arch Linux<br />
* Philips SHB9100 - Confirmed NOT TO WORK well. Have tried ''everything'' after a while they cut out. Pause and resume too is flakky and basically the whole wireless bluetooth experience is horrible. The following forum post[https://bbs.archlinux.org/viewtopic.php?pid=1315428#p1315428] explains an underlying issue and describes a temporary solution which can be used to improve the audio quality pending a proper fix.<br />
* Parrot Zik - Confirmed to work out of the box with firmware 1.04! The MIC however is detected, but does not work at all. Sometimes it can lag behind (not stutter) but most of the times it is not noticeable unless you playing a game, in which case I would switch to wired which resolves the issue.<br />
* Sony DR-BT50 works for a2dp both with bluez4 and bluez5 (instructions here[http://vlsd.blogspot.com/2013/11/bluetooth-headphones-and-arch-linux.html], subject to change). Adapter: D-Link DBT-120 USB dongle.<br />
* Sony SBH50 works for a2dp with bluez5 and pulseaudio. Adapter: Broadcom Bluetooth 2.1 Device (Vendor=0a5c ProdID=219b Rev=03.43; not sure what the exact model). Does not work until `sudo modprobe btusb`.<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<br />
* Auna Air 300 works well with bluez5, pulseaudio-git, and e.g. also mocp when running the latter through padsp. For some reason, a few restarts and re-tries were required, and eventually it just started working. <br />
* Sennheiser MM 400-X works out of the box with bluez5 and pulseaudio 4.0-6<br />
* Audionic BlueBeats (B-777) works out of the box with bluez5 and pulseaudio 4.0-6<br />
* Logitech Wireless Headset (part number PN 981-000381, advertised for use with iPad) works with bluez 5.14 and pulseaudio-git.<br />
* HMDX Jam Classic Bluetooth works with bluez, pulseaudio-git and pavucontrol<br />
* PT-810 - Generic USB-Powered Bluetooth Audio Receiver with 3.5mm headset jack and a2dp profile. Widely available as "USB Bluetooth Receiver." IDs as PT-810. Works with bluez 5.14 and pulseaudio-git.<br />
* Philips SHB4000WT works out of the box with bluez5 and pulseaudio 5.0<br />
* Philips AEA2000/12 works also out of the box with bluez 5.18-1 (and previous) and pulseaudio 5.0<br />
* Nokia BH-104 - does not work with bluez5. It use to work fine with bluez4, but since Gnome requires bluez5 I can't downgrade.<br />
* Creative AirwaveHD - works with bluez 5.23 and pulseaudio 5.0 with Bluetooth adapter Atheros Communications usb: 0cf3:0036<br />
<br />
== See also ==<br />
<br />
Alternative method of connecting a BT headset to Linux:<br />
<br />
* [http://gablog.eu/online/node/80 GaBlog - Connect a bluetooth headset to linux]<br />
<br />
Using the same device on Windows and Linux without pairing the device over and over again<br />
<br />
* [http://ubuntuforums.org/showthread.php?p=9363229#post9363229 Dual booting with a bluetooth keyboard]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=344646Bluetooth headset2014-11-14T20:22:54Z<p>Jstjohn: /* A2DP not working with pulseaudio */ add templates; fix capitalization</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
[[ru:Bluetooth headset]]<br />
{{Related articles start}}<br />
{{Related|Bluetooth}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
<br />
Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation. <br />
<br />
{{Tip|The most recent version of [[Bluez]] does not support the Headset/Handsfree profiles. This means that microphone input will not work, and also no sound output on headsets that do not support the A2DP profile. For using a headset with the Headset/Handsfree profiles, you will need to jump down to the legacy methods which require using [[AUR]] to fetch alternative packages.<br />
}}<br />
<br />
{{Tip| {{AUR|pulseaudio-git}} has added native support for the Headset/Handsfree profiles and Bluez5.}}<br />
<br />
{{Tip|Bluez5 is only supported by Pulseaudio and not by ALSA. If you do not want to use Pulseaudio, you need to install an older Bluez version from AUR.}}<br />
<br />
== A2DP via Bluez5/Pulseaudio ==<br />
<br />
Pulseaudio 5.x supports A2DP per default.<br />
Make sure the following packages are installed:<br />
<br />
# pacman -S pulseaudio-alsa bluez bluez-libs bluez-utils<br />
<br />
Start the bluetooth system:<br />
<br />
# systemctl start bluetooth<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
# bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
# power on<br />
# agent on<br />
# default-agent<br />
# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
shows a device that calls itself "Lasmex LBT10" and has MAC address ''00:1D:43:6D:03:26''. We will now use that MAC address to initiate the pairing:<br />
<br />
# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device:<br />
<br />
# connect 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[Pulseaudio]]. You can now redirect any playback to that device using ''pavucontrol''.<br />
<br />
You can now disable scanning again and exit the program:<br />
# scan off<br />
# exit<br />
<br />
=== Troubleshooting ===<br />
<br />
Many users report frustation with getting A2DP to work. <br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, have a look at the log via one of the following commands:<br />
<br />
# systemctl status bluetooth<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
The problem in this case is that pulseaudio is not catching up. A common solution to this problem is to restart pulseaudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while pulseaudio runs as user. After restarting pulseaudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting pulseaudio doesn't work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
If that still doesn't work, or you are using pulseaudio's system-wide mode, also load the following pulseaudio modules (again these can be loaded via your default.pa or system.pa):<br />
<br />
module-bluetooth-policy<br />
module-bluez5-device<br />
module-bluez5-discover<br />
<br />
To have your headset auto connect you need to enable PulseAudio's switch-on-connect module. Add the following:<br />
{{hc|/etc/pulse/default.pa|<br />
# automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
You then need to tell ''bluetoothctl'' to trust your bluetooth headset or you will see errors like this:<br />
bluetoothd[487]: Authentication attempt without agent<br />
bluetoothd[487]: Access denied: org.bluez.Error.Rejected<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
After a reboot, your bluetooth adapter will not power on by default. You need to add a udev rule to power it on:<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
# Set bluetooth power up<br />
ACTION=="add", SUBSYSTEM=="bluetooth", KERNEL=="hci[0-9]*", RUN+="/usr/bin/hciconfig %k up"<br />
}}<br />
<br />
==== Connecting works, but I cannot play sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your pulseaudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
== Legacy method: ALSA-BTSCO ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]].}}<br />
<br />
It is much easier to set up your bluetooth headset today, with bluez >= 3.16. You may want to try the out-of-box python script in [http://fosswire.com/2008/01/11/a2dp-stereo-linux/ this blog] (you need edit the script to work with gconftool-2). There is also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
You need your headset's bdaddr. It is of the form ''12:34:56:78:9A:BC''. Either find it in the documentation of your headset, on the headset itself or with the '''hcitool scan''' command.<br />
<br />
Install {{AUR|btsco}}.<br />
<br />
To load the kernel module, type:<br />
# modprobe snd-bt-sco<br />
There will now be an extra audio device. Use {{ic|alsamixer -cN}} (where N is most likely 1) to set the volume. You can access the device with any alsa-capable application by choosing the device ''BT headset'', or with any OSS application by using {{ic|/dev/dspN}} as the audio device.<br />
<br />
But to actually get any sound, you have to connect your headset to the computer first.<br />
<br />
=== Connecting the headset ===<br />
<br />
If you connect your headset for the first time, read the section about pairing first. To connect to your headset to the computer, use the command<br />
$ btsco -f <bdaddr><br />
for example<br />
$ btsco -f 12:34:56:78:9A:BC<br />
<br />
==== Pairing the headset with your computer ====<br />
<br />
The first time you connect the headset, you have to pair it with the computer. To do this, you need your headset's PIN. Depending on your headset you may have to reset the headset and repeat the pairing everytime you used the headset with another bluetooth device.<br />
<br />
There are two ways to pair your headset with the computer:<br />
<br />
===== Using ''bluez-gnome'' =====<br />
<br />
Install the ''bluez-gnome'' package from the community repository. Then start the '''bt-applet''' program. Once you try to connect to the headset, a window will open and ask for the PIN.<br />
<br />
===== Using ''passkey-agent'' =====<br />
<br />
Before connecting to the headset, enter the command<br />
$ passkey-agent --default <pin><br />
where ''<pin>'' is your headset's PIN. Then try to connect to the headset.<br />
<br />
=== Headset and Alsa Devices ===<br />
<br />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<br />
<br />
3. Pair your headset with your device:<br />
$ bluez-simple-agent (optional hci# ***) XX:XX:XX:XX:XX:XX<br />
and put in your pin (0000 or 1234, etc)<br />
<br />
4. Make sure your {{ic|/etc/bluetooth/audio.conf}} allows A2DP Audio Sinks. Place this line just bellow the [General] heading:<br />
Enable=Source,Sink,Media,Socket<br />
<br />
5. Add this to your {{ic|/etc/asound.conf}} file:<br />
#/etc/asound.conf<br />
<br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device XX:XX:XX:XX:XX:XX <br />
profile "auto"<br />
} <br />
} <br />
hint {<br />
show on<br />
description "BT Headset"<br />
} <br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
} <br />
<br />
6. Check to see if it has been added to alsa devices<br />
$ aplay -L<br />
<br />
7. Now play with aplay:<br />
$ aplay -D btheadset /path/to/audio/file<br />
<br />
or Mplayer:<br />
$ mplayer -ao alsa:device=btheadset /path/to/audio/or/video/file<br />
<br />
{{Tip|To find hci# for a usb dongle, type in <br />
$ hcitool dev<br />
}}<br />
<br />
=== Headset's multimedia buttons ===<br />
<br />
In order to get your bluetooth headset's multimedia buttons (play, pause, next, previous) working you need to create {{ic|/etc/modprobe.d/uinput.conf}} containing {{ic|uinput}}.<br />
<br />
== Legacy method: PulseAudio ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]] (references to {{ic|/etc/bluetooth/audio.conf}} and ''bluez-simple-agent'').}}<br />
<br />
This one is much easier and more elegant. PulseAudio will seamlessly switch between output devices when the headset is turned on. If you have ALSA as the sound server, you need the following packages installed:<br />
{{Pkg|pulseaudio}} and {{Pkg|pulseaudio-alsa}}.<br />
<br />
Now, to configure the audio output to use bluetooth, just install {{Pkg|pavucontrol}} and run it to configure the audio output:<br />
$ pavucontrol<br />
Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Audio sink fails ====<br />
<br />
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device. You will get "Audio sink fails".<br />
According to [http://wiki.gentoo.org/wiki/Bluetooth_Headset gentoo wiki], you have to verify than in {{ic|/etc/bluetooth/audio.conf}} there is {{ic|<nowiki>Enable=Socket</nowiki>}} under the {{ic|[General]}} section heading.<br />
<br />
Just do a {{ic|# systemctl restart bluetooth}} to apply it.<br />
<br />
==== Page timeout issue ====<br />
<br />
If you receive this error whilst trying to pair your headset with your system using bluez-simple-agent, then you can try to restart your system and use the graphical bluez applet of your desktop environment.<br />
<br />
== Legacy documentation: ALSA, bluez5 and PulseAudio method ==<br />
<br />
{{Accuracy|Describes two different methods, see the [[Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions|talk page]] for details.|Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions}}<br />
<br />
[[ALSA]], [[bluez|bluez5]], and [[PulseAudio]] work together to allow a wireless [[Bluetooth]] headset to play audio. The following method works with a Lenovo T61p laptop and SoundBot SB220 wireless bluetooth headset. The required software stack is extensive and failure to include all components can produce errors which are difficult to understand. The following list of software packages might not be the minimum required set and needs to be examined more closely.<br />
<br />
Bluez5 has a regression causing HSP/HFP Telephone profile to not be available. This regression is documented in the [http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/5.0/ draft release notes for Pulseaudio 5.0] which say (in "Notes for packagers"): "PulseAudio now supports BlueZ 5, but only the A2DP profile. BlueZ 4 is still the only way to make HSP/HFP work." ([https://fedoraproject.org/wiki/Common_F20_bugs#bluez5-profile from here])<br />
<br />
=== Install Software Packages ===<br />
<br />
The core software components are [[ALSA]], Bluez5, [[Pulseaudio]]. However there are additional libraries which are required. As well as a player which can play audio files. The following section lists the software packages installed in order to connect the headset and play audio over the headset.<br />
<br />
==== Install ALSA and associated libraries ====<br />
<br />
[[ALSA]] works with the linux kernel to provide audio services to user mode software. The following packages are used with the [[Bluetooth]] headset: {{Pkg|alsa-utils}}, {{Pkg|alsa-plugins}}, {{Pkg|alsa-tools}}.<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. It is required for [[PulseAudio]] to interface with wireless headsets. Required packages: {{Pkg|bluez}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-libs}}.<br />
<br />
==== Install PulseAudio ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The {{AUR|pulseaudio-git}} package from [[AUR]] has capabilities not provided by the stock {{Pkg|pulseaudio}} package. The additional capabilities are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [https://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
Required packages: {{AUR|pulseaudio-git}}, {{Pkg|pavucontrol}}.<br />
<br />
==== Install Audacious ====<br />
<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Required packages: {{Pkg|audacious}}, {{Pkg|audacious-plugins}}.<br />
<br />
=== Procedure ===<br />
<br />
Once the required packages are installed, use this procedure to play audio with a bluetooth headset. The high level overview of the procedure is to pair the headset, connect the headset, configure the player and pulse audio controller and then play audio.<br />
<br />
Start the bluetooth service as root or use sudo<br />
# systemctl start bluetooth<br />
<br />
Verify Bluetooth is started<br />
# systemctl status bluetooth<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: active (running) since Sat 2013-12-07 12:31:14 PST; 12s ago<br />
Docs: man:bluetoothd(8)<br />
Main PID: 3136 (bluetoothd)<br />
Status: "Running"<br />
CGroup: /system.slice/bluetooth.service<br />
└─3136 /usr/lib/bluetooth/bluetoothd<br />
<br />
Dec 07 12:31:14 t61p systemd[1]: Starting Bluetooth service...<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth daemon 5.11<br />
Dec 07 12:31:14 t61p systemd[1]: Started Bluetooth service.<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Starting SDP server<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth management interface 1.3 i...ed<br />
Hint: Some lines were ellipsized, use -l to show in full.<br />
<br />
Start the pulseaudio daemon. This must be done after X windows is started and as a normal user.<br />
$ pulseaudio -D<br />
<br />
Verify the pulseaudio daemon is running.<br />
$ pulseaudio --check -v<br />
I: [pulseaudio] main.c: Daemon running as PID 3186<br />
<br />
Start up bluetoothctl as root and pair and connect your headset. As a regular user, bluetoothctl will pair but not connect. Perhaps this is related to the config file (shown below) which is setup for what appears to be the root user.<br />
Note: the procedure shown below is for an initial pair and connect of the headphone. If the headset is already paired, then the procedure below can be shortened to: power on, agent on, default-agent, connect <mac address>. The mac address can be seen from the devices command output.<br />
<br />
$ bluetoothctl <br />
[NEW] Controller 00:1E:4C:F4:98:5B t61p-0 [default]<br />
[NEW] Device 00:1A:7D:12:36:B9 SoundBot SB220<br />
[bluetooth]# show<br />
Controller 00:1E:4C:F4:98:5B<br />
Name: t61p<br />
Alias: t61p-0<br />
Class: 0x000000<br />
Powered: no<br />
Discoverable: no<br />
Pairable: yes<br />
UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Access Profile (00001800-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
Modalias: usb:v1D6Bp0246d050B<br />
Discovering: no<br />
[bluetooth]# power on<br />
[CHG] Controller 00:1E:4C:F4:98:5B Class: 0x0c010c<br />
Changing power on succeeded<br />
[CHG] Controller 00:1E:4C:F4:98:5B Powered: yes<br />
[bluetooth]# agent on<br />
Agent registered<br />
[bluetooth]# default-agent<br />
Default agent request successful<br />
<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# scan on<br />
Discovery started<br />
[CHG] Controller 00:1E:4C:F4:98:5B Discovering: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 RSSI: -61<br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
Attempting to pair with 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 UUIDs has unsupported type<br />
[CHG] Device 00:1A:7D:12:36:B9 Paired: yes<br />
Pairing successful<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
Connection successful<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
Device 00:1A:7D:12:36:B9<br />
Name: SoundBot SB220<br />
Alias: SoundBot SB220<br />
Class: 0x240404<br />
Icon: audio-card<br />
Paired: yes<br />
Trusted: no<br />
Blocked: no<br />
Connected: yes<br />
LegacyPairing: yes<br />
UUID: Headset (00001108-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
<br />
Start up alsamixer, for simplicity un-mute all your outputs. Oddly enough some can be muted though. The ones I had muted during playback were:<br />
* Headphones<br />
* SPIDF<br />
<br />
Start up audacious. Use the menu to select pulseaudio as your output. Somewhere I read that bluez5 requires pulseaudio-git and this jives with my experience.<br />
<br />
Start up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
[http://netskink.blogspot.com/2013/12/pulseaudio-pavucontrol-and-audacious.html screenshot of application settings]<br />
<br />
==== Miscellaneous Configuration Files ====<br />
<br />
For reference these settings were also done.<br />
<br />
===== ALSA /etc/asound.conf =====<br />
<br />
The settings shown at the top of this page was used, but the additional modification for intel laptop soundcards.<br />
<br />
{{bc|<nowiki><br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device 00:1A:7D:12:36:B9<br />
profile "auto"<br />
}<br />
}<br />
hint {<br />
show on<br />
description "BT Headset"<br />
}<br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
}<br />
options snd-hda-intel model=laptop<br />
</nowiki>}}<br />
<br />
===== /etc/dbus-1/system.d/bluetooth.conf =====<br />
<br />
The settings here seem to be enabled for root only. See the policy user="root" section. However, if a regular user is specified here, the system fails to start. Someone with more knowledge could explain why.<br />
<br />
{{hc|/etc/dbus-1/system.d/bluetooth.conf|<nowiki><br />
<!-- This configuration file specifies the required security policies for Bluetooth core daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<!-- ../system.conf have denied everything, so we just punch some holes --><br />
<br />
<policy user="root"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent1"/><br />
<allow send_interface="org.bluez.MediaEndpoint1"/><br />
<allow send_interface="org.bluez.MediaPlayer1"/><br />
<allow send_interface="org.bluez.ThermometerWatcher1"/><br />
<allow send_interface="org.bluez.AlertAgent1"/><br />
<allow send_interface="org.bluez.Profile1"/><br />
<allow send_interface="org.bluez.HeartRateWatcher1"/><br />
<allow send_interface="org.bluez.CyclingSpeedWatcher1"/><br />
</policy><br />
<br />
<policy at_console="true"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<!-- allow users of lp group (printing subsystem) to communicate with bluetoothd --><br />
<policy group="lp"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<policy context="default"><br />
<deny send_destination="org.bluez"/><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
===== Tested applications =====<br />
<br />
As noted above this will work easily with audacious. YouTube videos with Chromium and Flash Player will work on some videos. If the video has ads it will not work, but if the video does not have ads it will work. Just make sure that after audacious is working with Bluetooth headset, start Chromium, and navigate to YouTube. Find a video without leading ads, and it should play the audio. If the settings icon has the a menu with two drop-down combo boxes for Speed and Quality it will play.<br />
<br />
== Switch between HSV and A2DP setting ==<br />
<br />
This can easily be achieved by the following command where 2 needs to be changed with the correct device number.<br />
<br />
pacmd set-card-profile 2 a2dp<br />
<br />
=== A2DP not working with PulseAudio ===<br />
<br />
If PulseAudio fails when changing the profile to A2DP with bluez 4.1+ and PulseAudio 3.0+, you can try disabling the Socket interface from {{ic|/etc/bluetooth/audio.conf}} by removing the line {{ic|1=Enable=Socket}} and adding line {{ic|1=Disable=Socket}}.<br />
<br />
== Tested headsets ==<br />
<br />
{| class="wikitable"<br />
! Model<br />
! Version<br />
! Comments<br />
! Compatible<br />
|-<br />
| '''Philips SHB9100'''<br />
| <br />
| Pause and resume is flakey. See [https://bbs.archlinux.org/viewtopic.php?pid=1315428#p1315428] for the underlying issue and a temporary solution to improve audio quality.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB7000'''<br />
| <br />
| Pause and resume is flakey.<br />
| {{R|Limited}}<br />
|-<br />
| '''Parrot Zik'''<br />
| <br />
| Firmware 1.04. The microphone is detected, but does not work. Sometimes it lags (but does not stutter); usually this is not noticeable unless playing games, in which case you may switch to a wired connection.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sony DR-BT50'''<br />
| bluez{4,5}<br />
| Works for a2dp, see [http://vlsd.blogspot.com/2013/11/bluetooth-headphones-and-arch-linux.html]). Adapter: D-Link DBT-120 USB dongle.<br />
| {{Yes}}<br />
|-<br />
| '''Sony SBH50'''<br />
| bluez5<br />
| Works for a2dp, Adapter: Broadcom Bluetooth 2.1 Device (Vendor=0a5c ProdID=219b Rev=03.43). Requires the {{ic|btusb}} [[modprobe|module]].<br />
| {{Yes}}<br />
|-<br />
| '''SoundBot SB220'''<br />
| bluez5, {{AUR|pulseaudio-git}}<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Auna Air 300'''<br />
| bluez5, pulseaudio-git<br />
| For some reason, a few restarts were required, and eventually it just started working.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sennheiser MM 400-X'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Audionic BlueBeats (B-777)'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Logitech Wireless Headset'''<br />
| bluez 5.14, pulseaudio-git<br />
| part number PN 981-000381, advertised for use with iPad<br />
| {{Yes}}<br />
|-<br />
| '''HMDX Jam Classic Bluetooth'''<br />
| bluez, pulseaudio-git<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''PT-810'''<br />
| bluez 5.14, pulseaudio-git<br />
| Generic USB-Powered Bluetooth Audio Receiver with 3.5mm headset jack and a2dp profile. Widely available as "USB Bluetooth Receiver." IDs as PT-810.<br />
| {{Yes}}<br />
|-<br />
| '''Philips SHB4000WT'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Philips AEA2000/12'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Nokia BH-104'''<br />
| bluez4<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Creative AirwaveHD'''<br />
| bluez 5.23<br />
| Bluetooth adapter Atheros Communications usb: 0cf3:0036<br />
| {{Yes}}<br />
|-<br />
| '''deleyCON Bluetooth Headset'''<br />
| bluez 5.23<br />
| Adapter: CSL - USB nano Bluetooth-Adapter V4.0. Tested a2dp profile. Untested microphone. Doesn't auto-connect (even when paired and trusted), must connect manually. Play/pause button mutes/unmutes the headphones, not the playback. Playback fwd/bwd buttons do not work (nothing visible with ''xev'').<br />
| {{R|Limited}}<br />
|-<br />
| '''UE BOOM'''<br />
| bluez5, pulseaudio-git<br />
| Music starts a little stuttered for a few seconds and later gets normal, however, there is a 5-sec lag on video playing.<br />
| {{R|Limited}}<br />
|}<br />
<br />
== See also ==<br />
<br />
Alternative method of connecting a BT headset to Linux:<br />
<br />
* [http://gablog.eu/online/node/80 GaBlog - Connect a bluetooth headset to linux]<br />
<br />
Using the same device on Windows and Linux without pairing the device over and over again<br />
<br />
* [http://ubuntuforums.org/showthread.php?p=9363229#post9363229 Dual booting with a bluetooth keyboard]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=344644Bluetooth headset2014-11-14T20:21:41Z<p>Jstjohn: /* Tested applications */ minor grammar improvements</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
[[ru:Bluetooth headset]]<br />
{{Related articles start}}<br />
{{Related|Bluetooth}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
<br />
Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation. <br />
<br />
{{Tip|The most recent version of [[Bluez]] does not support the Headset/Handsfree profiles. This means that microphone input will not work, and also no sound output on headsets that do not support the A2DP profile. For using a headset with the Headset/Handsfree profiles, you will need to jump down to the legacy methods which require using [[AUR]] to fetch alternative packages.<br />
}}<br />
<br />
{{Tip| {{AUR|pulseaudio-git}} has added native support for the Headset/Handsfree profiles and Bluez5.}}<br />
<br />
{{Tip|Bluez5 is only supported by Pulseaudio and not by ALSA. If you do not want to use Pulseaudio, you need to install an older Bluez version from AUR.}}<br />
<br />
== A2DP via Bluez5/Pulseaudio ==<br />
<br />
Pulseaudio 5.x supports A2DP per default.<br />
Make sure the following packages are installed:<br />
<br />
# pacman -S pulseaudio-alsa bluez bluez-libs bluez-utils<br />
<br />
Start the bluetooth system:<br />
<br />
# systemctl start bluetooth<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
# bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
# power on<br />
# agent on<br />
# default-agent<br />
# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
shows a device that calls itself "Lasmex LBT10" and has MAC address ''00:1D:43:6D:03:26''. We will now use that MAC address to initiate the pairing:<br />
<br />
# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device:<br />
<br />
# connect 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[Pulseaudio]]. You can now redirect any playback to that device using ''pavucontrol''.<br />
<br />
You can now disable scanning again and exit the program:<br />
# scan off<br />
# exit<br />
<br />
=== Troubleshooting ===<br />
<br />
Many users report frustation with getting A2DP to work. <br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, have a look at the log via one of the following commands:<br />
<br />
# systemctl status bluetooth<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
The problem in this case is that pulseaudio is not catching up. A common solution to this problem is to restart pulseaudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while pulseaudio runs as user. After restarting pulseaudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting pulseaudio doesn't work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
If that still doesn't work, or you are using pulseaudio's system-wide mode, also load the following pulseaudio modules (again these can be loaded via your default.pa or system.pa):<br />
<br />
module-bluetooth-policy<br />
module-bluez5-device<br />
module-bluez5-discover<br />
<br />
To have your headset auto connect you need to enable PulseAudio's switch-on-connect module. Add the following:<br />
{{hc|/etc/pulse/default.pa|<br />
# automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
You then need to tell ''bluetoothctl'' to trust your bluetooth headset or you will see errors like this:<br />
bluetoothd[487]: Authentication attempt without agent<br />
bluetoothd[487]: Access denied: org.bluez.Error.Rejected<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
After a reboot, your bluetooth adapter will not power on by default. You need to add a udev rule to power it on:<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
# Set bluetooth power up<br />
ACTION=="add", SUBSYSTEM=="bluetooth", KERNEL=="hci[0-9]*", RUN+="/usr/bin/hciconfig %k up"<br />
}}<br />
<br />
==== Connecting works, but I cannot play sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your pulseaudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
== Legacy method: ALSA-BTSCO ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]].}}<br />
<br />
It is much easier to set up your bluetooth headset today, with bluez >= 3.16. You may want to try the out-of-box python script in [http://fosswire.com/2008/01/11/a2dp-stereo-linux/ this blog] (you need edit the script to work with gconftool-2). There is also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
You need your headset's bdaddr. It is of the form ''12:34:56:78:9A:BC''. Either find it in the documentation of your headset, on the headset itself or with the '''hcitool scan''' command.<br />
<br />
Install {{AUR|btsco}}.<br />
<br />
To load the kernel module, type:<br />
# modprobe snd-bt-sco<br />
There will now be an extra audio device. Use {{ic|alsamixer -cN}} (where N is most likely 1) to set the volume. You can access the device with any alsa-capable application by choosing the device ''BT headset'', or with any OSS application by using {{ic|/dev/dspN}} as the audio device.<br />
<br />
But to actually get any sound, you have to connect your headset to the computer first.<br />
<br />
=== Connecting the headset ===<br />
<br />
If you connect your headset for the first time, read the section about pairing first. To connect to your headset to the computer, use the command<br />
$ btsco -f <bdaddr><br />
for example<br />
$ btsco -f 12:34:56:78:9A:BC<br />
<br />
==== Pairing the headset with your computer ====<br />
<br />
The first time you connect the headset, you have to pair it with the computer. To do this, you need your headset's PIN. Depending on your headset you may have to reset the headset and repeat the pairing everytime you used the headset with another bluetooth device.<br />
<br />
There are two ways to pair your headset with the computer:<br />
<br />
===== Using ''bluez-gnome'' =====<br />
<br />
Install the ''bluez-gnome'' package from the community repository. Then start the '''bt-applet''' program. Once you try to connect to the headset, a window will open and ask for the PIN.<br />
<br />
===== Using ''passkey-agent'' =====<br />
<br />
Before connecting to the headset, enter the command<br />
$ passkey-agent --default <pin><br />
where ''<pin>'' is your headset's PIN. Then try to connect to the headset.<br />
<br />
=== Headset and Alsa Devices ===<br />
<br />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<br />
<br />
3. Pair your headset with your device:<br />
$ bluez-simple-agent (optional hci# ***) XX:XX:XX:XX:XX:XX<br />
and put in your pin (0000 or 1234, etc)<br />
<br />
4. Make sure your {{ic|/etc/bluetooth/audio.conf}} allows A2DP Audio Sinks. Place this line just bellow the [General] heading:<br />
Enable=Source,Sink,Media,Socket<br />
<br />
5. Add this to your {{ic|/etc/asound.conf}} file:<br />
#/etc/asound.conf<br />
<br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device XX:XX:XX:XX:XX:XX <br />
profile "auto"<br />
} <br />
} <br />
hint {<br />
show on<br />
description "BT Headset"<br />
} <br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
} <br />
<br />
6. Check to see if it has been added to alsa devices<br />
$ aplay -L<br />
<br />
7. Now play with aplay:<br />
$ aplay -D btheadset /path/to/audio/file<br />
<br />
or Mplayer:<br />
$ mplayer -ao alsa:device=btheadset /path/to/audio/or/video/file<br />
<br />
{{Tip|To find hci# for a usb dongle, type in <br />
$ hcitool dev<br />
}}<br />
<br />
=== Headset's multimedia buttons ===<br />
<br />
In order to get your bluetooth headset's multimedia buttons (play, pause, next, previous) working you need to create {{ic|/etc/modprobe.d/uinput.conf}} containing {{ic|uinput}}.<br />
<br />
== Legacy method: PulseAudio ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]] (references to {{ic|/etc/bluetooth/audio.conf}} and ''bluez-simple-agent'').}}<br />
<br />
This one is much easier and more elegant. PulseAudio will seamlessly switch between output devices when the headset is turned on. If you have ALSA as the sound server, you need the following packages installed:<br />
{{Pkg|pulseaudio}} and {{Pkg|pulseaudio-alsa}}.<br />
<br />
Now, to configure the audio output to use bluetooth, just install {{Pkg|pavucontrol}} and run it to configure the audio output:<br />
$ pavucontrol<br />
Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Audio sink fails ====<br />
<br />
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device. You will get "Audio sink fails".<br />
According to [http://wiki.gentoo.org/wiki/Bluetooth_Headset gentoo wiki], you have to verify than in {{ic|/etc/bluetooth/audio.conf}} there is {{ic|<nowiki>Enable=Socket</nowiki>}} under the {{ic|[General]}} section heading.<br />
<br />
Just do a {{ic|# systemctl restart bluetooth}} to apply it.<br />
<br />
==== Page timeout issue ====<br />
<br />
If you receive this error whilst trying to pair your headset with your system using bluez-simple-agent, then you can try to restart your system and use the graphical bluez applet of your desktop environment.<br />
<br />
== Legacy documentation: ALSA, bluez5 and PulseAudio method ==<br />
<br />
{{Accuracy|Describes two different methods, see the [[Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions|talk page]] for details.|Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions}}<br />
<br />
[[ALSA]], [[bluez|bluez5]], and [[PulseAudio]] work together to allow a wireless [[Bluetooth]] headset to play audio. The following method works with a Lenovo T61p laptop and SoundBot SB220 wireless bluetooth headset. The required software stack is extensive and failure to include all components can produce errors which are difficult to understand. The following list of software packages might not be the minimum required set and needs to be examined more closely.<br />
<br />
Bluez5 has a regression causing HSP/HFP Telephone profile to not be available. This regression is documented in the [http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/5.0/ draft release notes for Pulseaudio 5.0] which say (in "Notes for packagers"): "PulseAudio now supports BlueZ 5, but only the A2DP profile. BlueZ 4 is still the only way to make HSP/HFP work." ([https://fedoraproject.org/wiki/Common_F20_bugs#bluez5-profile from here])<br />
<br />
=== Install Software Packages ===<br />
<br />
The core software components are [[ALSA]], Bluez5, [[Pulseaudio]]. However there are additional libraries which are required. As well as a player which can play audio files. The following section lists the software packages installed in order to connect the headset and play audio over the headset.<br />
<br />
==== Install ALSA and associated libraries ====<br />
<br />
[[ALSA]] works with the linux kernel to provide audio services to user mode software. The following packages are used with the [[Bluetooth]] headset: {{Pkg|alsa-utils}}, {{Pkg|alsa-plugins}}, {{Pkg|alsa-tools}}.<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. It is required for [[PulseAudio]] to interface with wireless headsets. Required packages: {{Pkg|bluez}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-libs}}.<br />
<br />
==== Install PulseAudio ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The {{AUR|pulseaudio-git}} package from [[AUR]] has capabilities not provided by the stock {{Pkg|pulseaudio}} package. The additional capabilities are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [https://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
Required packages: {{AUR|pulseaudio-git}}, {{Pkg|pavucontrol}}.<br />
<br />
==== Install Audacious ====<br />
<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Required packages: {{Pkg|audacious}}, {{Pkg|audacious-plugins}}.<br />
<br />
=== Procedure ===<br />
<br />
Once the required packages are installed, use this procedure to play audio with a bluetooth headset. The high level overview of the procedure is to pair the headset, connect the headset, configure the player and pulse audio controller and then play audio.<br />
<br />
Start the bluetooth service as root or use sudo<br />
# systemctl start bluetooth<br />
<br />
Verify Bluetooth is started<br />
# systemctl status bluetooth<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: active (running) since Sat 2013-12-07 12:31:14 PST; 12s ago<br />
Docs: man:bluetoothd(8)<br />
Main PID: 3136 (bluetoothd)<br />
Status: "Running"<br />
CGroup: /system.slice/bluetooth.service<br />
└─3136 /usr/lib/bluetooth/bluetoothd<br />
<br />
Dec 07 12:31:14 t61p systemd[1]: Starting Bluetooth service...<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth daemon 5.11<br />
Dec 07 12:31:14 t61p systemd[1]: Started Bluetooth service.<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Starting SDP server<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth management interface 1.3 i...ed<br />
Hint: Some lines were ellipsized, use -l to show in full.<br />
<br />
Start the pulseaudio daemon. This must be done after X windows is started and as a normal user.<br />
$ pulseaudio -D<br />
<br />
Verify the pulseaudio daemon is running.<br />
$ pulseaudio --check -v<br />
I: [pulseaudio] main.c: Daemon running as PID 3186<br />
<br />
Start up bluetoothctl as root and pair and connect your headset. As a regular user, bluetoothctl will pair but not connect. Perhaps this is related to the config file (shown below) which is setup for what appears to be the root user.<br />
Note: the procedure shown below is for an initial pair and connect of the headphone. If the headset is already paired, then the procedure below can be shortened to: power on, agent on, default-agent, connect <mac address>. The mac address can be seen from the devices command output.<br />
<br />
$ bluetoothctl <br />
[NEW] Controller 00:1E:4C:F4:98:5B t61p-0 [default]<br />
[NEW] Device 00:1A:7D:12:36:B9 SoundBot SB220<br />
[bluetooth]# show<br />
Controller 00:1E:4C:F4:98:5B<br />
Name: t61p<br />
Alias: t61p-0<br />
Class: 0x000000<br />
Powered: no<br />
Discoverable: no<br />
Pairable: yes<br />
UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Access Profile (00001800-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
Modalias: usb:v1D6Bp0246d050B<br />
Discovering: no<br />
[bluetooth]# power on<br />
[CHG] Controller 00:1E:4C:F4:98:5B Class: 0x0c010c<br />
Changing power on succeeded<br />
[CHG] Controller 00:1E:4C:F4:98:5B Powered: yes<br />
[bluetooth]# agent on<br />
Agent registered<br />
[bluetooth]# default-agent<br />
Default agent request successful<br />
<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# scan on<br />
Discovery started<br />
[CHG] Controller 00:1E:4C:F4:98:5B Discovering: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 RSSI: -61<br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
Attempting to pair with 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 UUIDs has unsupported type<br />
[CHG] Device 00:1A:7D:12:36:B9 Paired: yes<br />
Pairing successful<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
Connection successful<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
Device 00:1A:7D:12:36:B9<br />
Name: SoundBot SB220<br />
Alias: SoundBot SB220<br />
Class: 0x240404<br />
Icon: audio-card<br />
Paired: yes<br />
Trusted: no<br />
Blocked: no<br />
Connected: yes<br />
LegacyPairing: yes<br />
UUID: Headset (00001108-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
<br />
Start up alsamixer, for simplicity un-mute all your outputs. Oddly enough some can be muted though. The ones I had muted during playback were:<br />
* Headphones<br />
* SPIDF<br />
<br />
Start up audacious. Use the menu to select pulseaudio as your output. Somewhere I read that bluez5 requires pulseaudio-git and this jives with my experience.<br />
<br />
Start up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
[http://netskink.blogspot.com/2013/12/pulseaudio-pavucontrol-and-audacious.html screenshot of application settings]<br />
<br />
==== Miscellaneous Configuration Files ====<br />
<br />
For reference these settings were also done.<br />
<br />
===== ALSA /etc/asound.conf =====<br />
<br />
The settings shown at the top of this page was used, but the additional modification for intel laptop soundcards.<br />
<br />
{{bc|<nowiki><br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device 00:1A:7D:12:36:B9<br />
profile "auto"<br />
}<br />
}<br />
hint {<br />
show on<br />
description "BT Headset"<br />
}<br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
}<br />
options snd-hda-intel model=laptop<br />
</nowiki>}}<br />
<br />
===== /etc/dbus-1/system.d/bluetooth.conf =====<br />
<br />
The settings here seem to be enabled for root only. See the policy user="root" section. However, if a regular user is specified here, the system fails to start. Someone with more knowledge could explain why.<br />
<br />
{{hc|/etc/dbus-1/system.d/bluetooth.conf|<nowiki><br />
<!-- This configuration file specifies the required security policies for Bluetooth core daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<!-- ../system.conf have denied everything, so we just punch some holes --><br />
<br />
<policy user="root"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent1"/><br />
<allow send_interface="org.bluez.MediaEndpoint1"/><br />
<allow send_interface="org.bluez.MediaPlayer1"/><br />
<allow send_interface="org.bluez.ThermometerWatcher1"/><br />
<allow send_interface="org.bluez.AlertAgent1"/><br />
<allow send_interface="org.bluez.Profile1"/><br />
<allow send_interface="org.bluez.HeartRateWatcher1"/><br />
<allow send_interface="org.bluez.CyclingSpeedWatcher1"/><br />
</policy><br />
<br />
<policy at_console="true"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<!-- allow users of lp group (printing subsystem) to communicate with bluetoothd --><br />
<policy group="lp"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<policy context="default"><br />
<deny send_destination="org.bluez"/><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
===== Tested applications =====<br />
<br />
As noted above this will work easily with audacious. YouTube videos with Chromium and Flash Player will work on some videos. If the video has ads it will not work, but if the video does not have ads it will work. Just make sure that after audacious is working with Bluetooth headset, start Chromium, and navigate to YouTube. Find a video without leading ads, and it should play the audio. If the settings icon has the a menu with two drop-down combo boxes for Speed and Quality it will play.<br />
<br />
== Switch between HSV and A2DP setting ==<br />
<br />
This can easily be achieved by the following command where 2 needs to be changed with the correct device number.<br />
<br />
pacmd set-card-profile 2 a2dp<br />
<br />
=== A2DP not working with pulseaudio ===<br />
<br />
If pulseaudio fails when changing the profile to A2DP with bluez 4.1+ and pulseaudio 3.0+, you can try disabling the Socket interface from /etc/bluetooth/audio.conf by removing the line Enable=Socket and adding line Disable=Socket<br />
<br />
Disable=Socket<br />
<br />
== Tested headsets ==<br />
<br />
{| class="wikitable"<br />
! Model<br />
! Version<br />
! Comments<br />
! Compatible<br />
|-<br />
| '''Philips SHB9100'''<br />
| <br />
| Pause and resume is flakey. See [https://bbs.archlinux.org/viewtopic.php?pid=1315428#p1315428] for the underlying issue and a temporary solution to improve audio quality.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB7000'''<br />
| <br />
| Pause and resume is flakey.<br />
| {{R|Limited}}<br />
|-<br />
| '''Parrot Zik'''<br />
| <br />
| Firmware 1.04. The microphone is detected, but does not work. Sometimes it lags (but does not stutter); usually this is not noticeable unless playing games, in which case you may switch to a wired connection.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sony DR-BT50'''<br />
| bluez{4,5}<br />
| Works for a2dp, see [http://vlsd.blogspot.com/2013/11/bluetooth-headphones-and-arch-linux.html]). Adapter: D-Link DBT-120 USB dongle.<br />
| {{Yes}}<br />
|-<br />
| '''Sony SBH50'''<br />
| bluez5<br />
| Works for a2dp, Adapter: Broadcom Bluetooth 2.1 Device (Vendor=0a5c ProdID=219b Rev=03.43). Requires the {{ic|btusb}} [[modprobe|module]].<br />
| {{Yes}}<br />
|-<br />
| '''SoundBot SB220'''<br />
| bluez5, {{AUR|pulseaudio-git}}<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Auna Air 300'''<br />
| bluez5, pulseaudio-git<br />
| For some reason, a few restarts were required, and eventually it just started working.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sennheiser MM 400-X'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Audionic BlueBeats (B-777)'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Logitech Wireless Headset'''<br />
| bluez 5.14, pulseaudio-git<br />
| part number PN 981-000381, advertised for use with iPad<br />
| {{Yes}}<br />
|-<br />
| '''HMDX Jam Classic Bluetooth'''<br />
| bluez, pulseaudio-git<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''PT-810'''<br />
| bluez 5.14, pulseaudio-git<br />
| Generic USB-Powered Bluetooth Audio Receiver with 3.5mm headset jack and a2dp profile. Widely available as "USB Bluetooth Receiver." IDs as PT-810.<br />
| {{Yes}}<br />
|-<br />
| '''Philips SHB4000WT'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Philips AEA2000/12'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Nokia BH-104'''<br />
| bluez4<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Creative AirwaveHD'''<br />
| bluez 5.23<br />
| Bluetooth adapter Atheros Communications usb: 0cf3:0036<br />
| {{Yes}}<br />
|-<br />
| '''deleyCON Bluetooth Headset'''<br />
| bluez 5.23<br />
| Adapter: CSL - USB nano Bluetooth-Adapter V4.0. Tested a2dp profile. Untested microphone. Doesn't auto-connect (even when paired and trusted), must connect manually. Play/pause button mutes/unmutes the headphones, not the playback. Playback fwd/bwd buttons do not work (nothing visible with ''xev'').<br />
| {{R|Limited}}<br />
|-<br />
| '''UE BOOM'''<br />
| bluez5, pulseaudio-git<br />
| Music starts a little stuttered for a few seconds and later gets normal, however, there is a 5-sec lag on video playing.<br />
| {{R|Limited}}<br />
|}<br />
<br />
== See also ==<br />
<br />
Alternative method of connecting a BT headset to Linux:<br />
<br />
* [http://gablog.eu/online/node/80 GaBlog - Connect a bluetooth headset to linux]<br />
<br />
Using the same device on Windows and Linux without pairing the device over and over again<br />
<br />
* [http://ubuntuforums.org/showthread.php?p=9363229#post9363229 Dual booting with a bluetooth keyboard]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Firefox&diff=344641Firefox2014-11-14T20:19:01Z<p>Jstjohn: /* Firefox variants */ fix typo; use HTTPS in links</p>
<hr />
<div>[[Category:Web Browser]]<br />
[[ar:Firefox]]<br />
[[cs:Firefox]]<br />
[[de:Firefox]]<br />
[[es:Firefox]]<br />
[[fr:Firefox]]<br />
[[it:Firefox]]<br />
[[ja:Firefox]]<br />
[[ko:Firefox]]<br />
[[ru:Firefox]]<br />
[[tr:Firefox]]<br />
[[zh-CN:Firefox]]<br />
{{Related articles start}}<br />
{{Related|Browser plugins}}<br />
{{Related|Firefox tweaks}}<br />
{{Related|Chromium}}<br />
{{Related|Opera}}<br />
{{Related articles end}}<br />
[http://www.firefox.com Firefox] is a popular open-source graphical web browser from [http://www.mozilla.com Mozilla].<br />
<br />
== Installing ==<br />
<br />
Firefox can be [[pacman|installed]] with the {{Pkg|firefox}} package, available in the [[official repositories]].<br />
<br />
Other alternatives from the [[AUR]] include:<br />
<br />
*{{AUR|firefox-esr-bin}} (a [https://www.mozilla.org/en-US/firefox/organizations/ long-term] supported version)<br />
*{{AUR|firefox-beta-bin}} (the official [https://www.mozilla.org/en-US/firefox/channel/ cutting-edge] version by Mozilla)<br />
*{{AUR|firefox-developer}} ([http://www.mozilla.org/en-US/firefox/developer/ Firefox Developer Edition])<br />
*{{AUR|firefox-aurora}} ([http://www.mozilla.org/en-US/firefox/aurora/ alpha version] superceded by Firefox Developer Edition)<br />
*{{AUR|firefox-nightly}} (a [https://nightly.mozilla.org/ nightly] version)<br />
<br />
Here you can find an overview of Mozilla's [https://wiki.mozilla.org/Releases releases].<br />
<br />
There are a number of language packs available for Firefox, other than the standard English. Language packs are usually named as {{ic|firefox-i18n-languagecode}} (where {{ic|languagecode}} can be any language code, such as '''de''', '''ja''', '''fr''', etc.). For a list of available language packs see [https://www.archlinux.org/packages/?sort=&q=firefox-i18n&maintainer=&last_update=&flagged=&limit=100 this].<br />
<br />
If Firefox does not anti-alias and/or hint your fonts, try to install {{AUR|ttf-win7-fonts}} (preferred) or {{AUR|ttf-ms-fonts}} and take a look at [[Font configuration]].<br />
<br />
=== Firefox variants ===<br />
<br />
* {{App|[[Wikipedia:Mozilla Corporation software rebranded by the Debian project#IceWeasel|Iceweasel]]|Fork of Firefox that is being developed by Debian. The main difference is that it does not include any trademarked Mozilla artwork.|https://wiki.debian.org/Iceweasel|{{AUR|iceweasel}}}}<br />
{{Note|For some more information about Iceweasel's existence, see [http://web.glandium.org/blog/?p&#61;97 this blog post].}}<br />
* {{App|[[Wikipedia:GNU IceCat|GNU IceCat]]|Web browser distributed by the GNU Project. It is made entirely of free software and is compatible with the GNU/Linux operating system and almost all of Firefox's addons. |https://www.gnu.org/software/gnuzilla/|{{AUR|icecat}}}}<br />
* {{App|Firefox KDE|Version of Firefox that incorporates an OpenSUSE patch for better KDE integration than is possible through simple Firefox plugins.|https://gitorious.org/firefox-kde-opensuse|{{AUR|firefox-kde-opensuse}}}}<br />
* {{App|Firefox GTK3|Firefox with GTK3 integration.||{{AUR|firefox-gtk3-bin}}}}<br />
* {{App|[[Wikipedia:Pale Moon (web browser)|Pale Moon]]|Firefox fork based on Firefox ESR, keeping a classic (pre-Australis) interface through selective use of add-ons. Compiled for SSE2 support and with disabled optional code.| http://www.palemoon.org/|{{AUR|palemoon-bin}}}}<br />
<br />
== Add-ons ==<br />
<br />
Firefox is well known for its large library of add-ons which can be used to add new features or modify the behavior of existing features of Firefox. You can find new add-ons or manage installed add-ons with Firefox's "Add-ons Manager."<br />
<br />
For a list of popular add-ons, see [https://addons.mozilla.org/en-US/firefox/extensions/?sort=popular Mozilla's add-on list sorted by popularity]. See also [[Wikipedia:List of Firefox extensions|List of Firefox extensions]] on Wikipedia.<br />
<br />
== Plugins ==<br />
<br />
See the main article: [[Browser plugins]]<br />
<br />
To find out what plugins are installed/enabled, enter:<br />
about:plugins<br />
in the Firefox address bar or go to the ''Add-ons'' entry in the Firefox Menu and select the ''Plugins'' tab.<br />
<br />
=== GNOME Keyring integration ===<br />
<br />
Install {{AUR|firefox-gnome-keyring}} from the [[AUR]] to integrate Firefox with [[GNOME Keyring]]. To make firefox-gnome-keyring use your login keychain, set extensions.gnome-keyring.keyringName to "login" (without the double quotes) in about:config. Note the lowercase 'l' despite the the keychain name having an uppercase 'L' in Seahorse.<br />
<br />
=== KDE integration ===<br />
<br />
* To bring the KDE look to GTK apps (including Firefox), install {{Pkg|oxygen-gtk2}} and {{Pkg|kde-gtk-config}}. After that, go to System Settings -> Application Appearance -> GTK. Be sure to choose 'oxygen-gtk' in 'Select a GTK2 Theme' and check 'Show icons in GTK buttons' and 'Show icons in GTK menus'.<br />
<br />
* To use KDE's KPart technology with Firefox, by embedding different KDE file viewers into the browser, you can install {{Pkg|kpartsplugin}}.<br />
<br />
* For integration with KDE’s mime type system and file dialogs, one can use {{AUR|firefox-kde-opensuse}} variant from AUR with OpenSUSE’s patches applied, or {{AUR|firefox-kde-global-menu}} for that ''and'' appmenu integration.<br />
<br />
* Add-ons may provide some integration, such as [https://addons.mozilla.org/en-US/firefox/addon/kde-wallet-password-integratio/ KWallet integration] and [https://addons.mozilla.org/en-US/firefox/addon/plasmanotify/ Plasma notifications].<br />
<br />
=== Dictionaries for spell checking ===<br />
<br />
To enable spell checking for a specific language right click on any text field and check the ''Check Spelling'' box. To select a language for spell checking to you have right click again and select your language from the ''Languages'' sub-menu.<br />
<br />
To get more languages just click ''Add Dictionaries...'' and select the dictionary you want to install from the list.<br />
<br />
Alternatively, you can install the {{Pkg|hunspell}} package, available in the [[official repositories]]. You also need to install dictionaries for your language, such as {{Pkg|hunspell-fr}} (for the French language) or {{Pkg|hunspell-he}} (for Hebrew).<br />
<br />
By default, Firefox will try to symlink all your hunspell dictionaries in {{ic|/usr/lib/firefox/dictionaries}}. If you want to have less dictionaries offered to you in Firefox, you can remove some of those links. Be aware that it may not stand an upgrade of Firefox.<br />
<br />
=== Adding search engines ===<br />
<br />
Search engines can be added to Firefox through normal add-ons, see [https://addons.mozilla.org/en-US/firefox/search-tools/ this page] for a list of available search engines.<br />
<br />
A very extensive list of search engines can be found [http://mycroft.mozdev.org/ here].<br />
<br />
Also, you can use the [https://firefox.maltekraus.de/extensions/add-to-search-bar add-to-searchbar] extension to add a search to your search bar from any web site, by simply right clicking on the site's search field and selecting ''Add to Search Bar...''<br />
<br />
If you want a manual solution, take a look at {{ic|~/.mozilla/firefox/''xxxxxxxx''.default/searchplugins/}} (where ''xxxxxxxx'' is your profile ID).<br />
<br />
==== arch-firefox-search ====<br />
<br />
Install the {{Pkg|arch-firefox-search}} package, available in the [[official repositories]], to add Arch-specific searches (AUR, wiki, forum, etc, as specified by user) to the Firefox search toolbar.<br />
<br />
=== Multimedia playback ===<br />
<br />
If {{ic|media.gstreamer.enabled}} is enabled in {{ic|about:config}}, Firefox will try to use [[GStreamer]] for playing multimedia inside HTML5 {{ic|<audio>}} and {{ic|<video>}} elements. For this to work, the optional dependencies of the {{Pkg|firefox}} package need to be installed (see [[Browser plugins#Multimedia playback]] for details).<br />
<br />
Restart Firefox, and go to [https://www.youtube.com/html5 YouTube's HTML5 page] or [http://www.quirksmode.org/html5/tests/video.html this page] to verify that it is correctly installed and is in use.<br />
<br />
Alternatively, to force Firefox to rely on the Adobe Flash Player to play HTML5 audio, set {{ic|media.gstreamer.enabled}} to {{ic|false}} in your {{ic|about:config}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Setting your e-mail client ===<br />
<br />
Firefox is usually set to open {{ic|mailto}} links with a web application such as Gmail or Yahoo Mail. To set your e-mail client in Firefox to use with {{ic|mailto}} links, go to ''Preferences > Applications'' and modify the ''action'' column corresponding to the {{ic|mailto}} content type. You have to set this to the exact location of your e-mail client (e.g. {{ic|/usr/bin/kmail}} for Kmail).<br />
<br />
=== File association ===<br />
<br />
See [[Default applications]].<br />
<br />
==== File association problems ====<br />
<br />
{{Expansion|Mention {{ic|xdg-open}} trick in {{ic|Preferences > Applications}}, and possible mistakes with {{ic|octet/binary-stream}} [https://bugs.launchpad.net/ubuntu/+source/firefox/+bug/918019/comments/12]}}<br />
<br />
{{Accuracy|1={{Pkg|firefox}} does not seem to use {{Pkg|libgnome}} at all, though [https://bugzilla.mozilla.org/show_bug.cgi?id=694570 this bug] is still open.}}<br />
<br />
For non-[[GNOME]] users, Firefox may not associate file types properly or at all (in the "Open With" part of the download dialog). Installing {{Pkg|libgnome}} from the [[official repositories]] amends the problem.<br />
<br />
If you are using [[KDE]] you can also do the following:<br />
<br />
ln -s ~/.local/share/applications/mimeapps.list ~/.local/share/applications/mimeinfo.cache<br />
<br />
From now on Firefox should use the applications which are explicitly set in KDE.<br />
<br />
=== Firefox keeps creating ~/Desktop even when this is not desired ===<br />
<br />
Firefox uses {{ic|~/Desktop}} as the default place for download and upload files. To set it to another folder, create {{ic|~/.config/user-dirs.dirs}} and add:<br />
XDG_DESKTOP_DIR="/home/''user''/"<br />
XDG_DOWNLOAD_DIR="/home/''user''/''dir''"<br />
XDG_TEMPLATES_DIR="/home/''user''/''dir''"<br />
XDG_PUBLICSHARE_DIR="/home/''user''/''dir''"<br />
XDG_DOCUMENTS_DIR="/home/''user''/''dir''"<br />
XDG_MUSIC_DIR="/home/''user''/''dir''"<br />
XDG_PICTURES_DIR="/home/''user''/''dir''"<br />
XDG_VIDEOS_DIR="/home/''user''/''dir''"<br />
Change ''user'' and ''dir'' to the actual directory.<br />
<br />
=== Make plugins respect blocked pop-ups ===<br />
<br />
Some plugins can misbehave and bypass the default settings, such as the Flash plugin. You can prevent this by doing the following:<br />
<br />
# Type {{ic|about:config}} into the address bar.<br />
# Right-click on the page and select {{ic|New}} and then {{ic|Integer}}.<br />
# Name it {{ic|privacy.popups.disable_from_plugins}}.<br />
# Set the value to 2.<br />
<br />
The possible values are:<br />
* '''0''': Allow all popups from plugins.<br />
* '''1''': Allow popups, but limit them to dom.popup_maximum.<br />
* '''2''': Block popups from plugins.<br />
* '''3''': Block popups from plugins, even on whitelisted sites.<br />
<br />
=== Middle-click errors ===<br />
<br />
A common error message you can get while using the middle mouse button in Firefox is:<br />
The URL is not valid and cannot be loaded.<br />
<br />
Another symptom is that middle-clicking results in unexpected behavior, like accessing a random web page.<br />
<br />
The reason stems from the use of the middle mouse buttons in UNIX-like operating systems. The middle mouse button is used to paste whatever text has been highlighted/added to the clipboard. Then there is the possibly conflicting feature in Firefox, which defaults to loading the URL of the corresponding text when the button is depressed. This can be easily disabled by going to {{ic|about:config}} and setting the {{ic|middlemouse.contentLoadURL}} option to '''false'''.<br />
<br />
Alternatively, having the traditional scroll cursor on middle-click (default behavior on Windows browsers) can be achieved by searching for {{ic|general.autoScroll}} and setting it to '''true'''.<br />
<br />
=== Backspace does not work as the 'Back' button ===<br />
<br />
As per [http://ubuntu.wordpress.com/2006/12/21/fix-firefox-backspace-to-take-you-to-the-previous-page/ this article], the feature has been removed in order to fix a bug. To re-introduce the original behavior go to {{ic|about:config}} and set the {{ic|browser.backspace_action}} option to '''0''' (zero).<br />
<br />
=== Firefox does not remember login information ===<br />
<br />
It may be due to a corrupted {{ic|cookies.sqlite}} file in [http://support.mozilla.com/en-US/kb/Profiles#How_to_find_your_profile Firefox's profile] folder. In order to fix this, just rename or remove {{ic|cookie.sqlite}} while Firefox is not running.<br />
<br />
Open a terminal of choice and type the following:<br />
$ cd ~/.mozilla/firefox/xxxxxxxx.default/<br />
$ rm -f cookies.sqlite<br />
{{Note|xxxxxxxx represents a random string of 8 characters.}}<br />
<br />
Restart Firefox and see if it solved the problem.<br />
<br />
=== Unreadable input fields with dark GTK+ themes ===<br />
<br />
{{Merge|Firefox tweaks#Appearance|Anything on that page might be in troubleshooting section as well, so let's keep the info in one place.}}<br />
<br />
When using a dark [[GTK+]] theme, one might encounter Internet pages with unreadable input and text fields (e.g. Amazon can have white text on white background). This can happen because the site only sets either background or text color, and Firefox takes the other one from the theme.<br />
<br />
A work around is to explicitly setting standard colors for all web pages in {{ic|~/.mozilla/firefox/xxxxxxxx.default/chrome/userContent.css}} or using [https://addons.mozilla.org/en-US/firefox/addon/stylish/ stylish add-on].<br />
<br />
The following sets input fields to standard black text / white background; both can be overridden by the displayed site, so that colors are seen as intended:<br />
{{bc|<br />
input {<br />
-moz-appearance: none !important;<br />
background-color: white;<br />
color: black;<br />
}<br />
<br />
textarea {<br />
-moz-appearance: none !important;<br />
background-color: white;<br />
color: black;<br />
}<br />
<br />
select {<br />
-moz-appearance: none !important;<br />
background-color: white;<br />
color: black;<br />
}<br />
}}<br />
<br />
This will force the colors ("Allow pages to choose their own colors..." checkbox in the ''Preferences > Content > Color'' dialog):<br />
{{bc|<br />
input {<br />
-moz-appearance: none !important;<br />
background-color: pink !important;<br />
color: green !important;<br />
}<br />
<br />
textarea {<br />
-moz-appearance: none !important;<br />
background-color: pink !important;<br />
color: green !important;<br />
}<br />
<br />
select {<br />
-moz-appearance: none !important;<br />
background-color: pink !important;<br />
color: green !important;<br />
}<br />
}}<br />
<br />
For Firefox 30 (Currently in Nightly Channel) there's this.<br />
{{Note|If you want {{ic|urlbar}} and {{ic|searchbar}} to be {{ic|white}} remove both {{ic|:not}} css selectors.}}<br />
{{bc|<br />
input:not(.urlbar-input):not(.textbox-input) {<br />
-moz-appearance: none !important;<br />
background-color: white;<br />
color: black;<br />
}<br />
<br />
#downloads-indicator-counter {<br />
color: white;<br />
}<br />
<br />
textarea {<br />
-moz-appearance: none !important;<br />
background-color: white;<br />
color: black;<br />
}<br />
<br />
select {<br />
-moz-appearance: none !important;<br />
background-color: white;<br />
color: black;<br />
}<br />
}}<br />
<br />
Change color values to suit, or use an add-on like [https://addons.mozilla.org/en-US/firefox/addon/2108 Stylish].<br />
<br />
=== "Do you want Firefox to save your tabs for the next time it starts?" dialog does not appear ===<br />
<br />
From the [http://support.mozilla.com/en-US/questions/767751 Mozilla support] site:<br />
<br />
# Type {{ic|about:config}} in the address bar.<br />
# Set {{ic|browser.warnOnQuit}} to '''true'''.<br />
# Set {{ic|browser.showQuitWarning}} to '''true'''.<br />
<br />
=== The menu cannot pop-up after updating to Firefox 13 ===<br />
<br />
This problem is most probably related to this [https://bugzilla.mozilla.org/show_bug.cgi?id=787943 bug] and it may affect any user that sets<br />
GTK_IM_MODULE=xim<br />
<br />
while configuring their input method.<br />
<br />
It appears to happen especially to those who are using [[Fcitx]] 4.0.x (at that time Fcitx only supported XIM). With newer version of Fcitx, XIM is discouraged and you should set:<br />
GTK_IM_MODULE=fcitx<br />
<br />
For more information see the [[Fcitx]] page.<br />
<br />
=== Silently fails when installing desktop apps from marketplace ===<br />
<br />
Installation of apps from firefox os marketplace will silently fail if there's no {{ic|~/.local/share/applications}} folder.<br />
<br />
== See also ==<br />
<br />
* [http://www.mozilla.org/firefox/ Official website]<br />
* [http://www.mozilla.org/ Mozilla Foundation]<br />
* [https://wiki.mozilla.org/Firefox Firefox wiki]<br />
* [https://addons.mozilla.org/ Firefox Add-ons]<br />
* [https://addons.mozilla.org/en-US/firefox/themes/ Firefox themes]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Browser_plugins&diff=344631Browser plugins2014-11-14T20:07:50Z<p>Jstjohn: /* Installation */ use HTTPS link; fix run-on sentence; use active voice instead of passive voice for one sentence</p>
<hr />
<div>[[Category:Web Browser]]<br />
[[de:Browser Plugins]]<br />
[[es:Browser Plugins]]<br />
[[fr:Plugins navigateur]]<br />
[[ja:Browser Plugins]]<br />
[[tr:Web tarayıcı eklentileri]]<br />
[[zh-CN:Browser Plugins]]<br />
{{Related articles start}}<br />
{{Related|Opera}}<br />
{{Related|Firefox}}<br />
{{Related|Chromium}}<br />
{{Related articles end}}<br />
<br />
There are two types of browser plugins, based on the plugin API they <br />
use:<br />
*Netscape plugin API (NPAPI): these plugins work in [[Firefox]], [[Opera]] and most other browsers ('''not''' in [[Chromium]]).<br />
*Pepper plugin API (PPAPI): these plugins work only in [[Chromium]] and Chrome.<br />
<br />
Most plugins on this page are NPAPI-only, unless noted otherwise.<br />
<br />
== Flash Player ==<br />
<br />
=== Shumway ===<br />
<br />
[http://mozilla.github.io/shumway/ Shumway] is an HTML5 technology experiment that explores building a faithful and efficient renderer for the SWF file format without native code assistance. As of 2013-01-01, the plugin may be installed directly from [http://mozilla.github.io/shumway/ Mozilla's github.io site]. According to the [https://github.com/mozilla/shumway/wiki Shumway wiki], "Integration with Firefox is a possibility if the experiment proves successful." <br />
<br />
Shumway is also embedded in Firefox Nightly/Aurora builds.<br />
<br />
=== Gnash ===<br />
<br />
See also [[Wikipedia:Gnash]].<br />
<br />
[http://www.gnu.org/software/gnash/ GNU Gnash] is a free (libre) alternative to Adobe Flash Player. It is available both as a standalone player for desktop computers and embedded devices, as well as a browser plugin, and supports the SWF format up to version 7 (with versions 8 and 9 under development) and about 80% of ActionScript 2.0.<br />
<br />
There are multiple packages available in the [[AUR]]: {{AUR|gnash}}, {{AUR|gnash-kde4}}, {{AUR|gnash-trunk-git}}.<br />
<br />
{{Note|If you find that Gnash does not work properly right out of the box, then you may also need to [[pacman|install]] {{Pkg|gstreamer0.10-ffmpeg}} from the [[official repositories]].}}<br />
<br />
=== Lightspark ===<br />
<br />
[http://lightspark.github.com/ Lightspark] is another attempt to provide a free alternative to Adobe Flash aimed at supporting newer Flash formats. Lightspark has the ability to fall back on Gnash for old content, which enables users to install both and enjoy wider coverage. Although it is still very much in development, it supports some [https://github.com/lightspark/lightspark/wiki/Site-Support popular sites]. <br />
<br />
Lightspark can be [[pacman|installed]] with the package {{AUR|lightspark}} or {{AUR|lightspark-git}}, available in the [[AUR]].<br />
<br />
=== Adobe Flash Player ===<br />
<br />
==== Installation ====<br />
<br />
The package you will need to install depends on the browser you use.<br />
<br />
* The NPAPI version can be [[pacman|installed]] with the {{Pkg|flashplugin}} package from the official repositories. This plugin was [https://blogs.adobe.com/flashplayer/2012/02/adobe-and-google-partnering-for-flash-player-on-linux.html discontinued by Adobe] and is stuck at version 11.2; although, Adobe will provide security updates for another 5 years (i.e. 2017).<br />
<br />
* The PPAPI version is shipped with Google Chrome. If you are using Chromium or any other browser using the PPAPI interface, see [[Chromium#Flash Player plugin]] for more information.<br />
<br />
{{Note|Some Flash apps may require {{AUR|ttf-ms-fonts}} from the [[AUR]] in order to properly render text.}}<br />
<br />
==== Configuration ====<br />
<br />
To change the preferences (privacy settings, resource usage, etc.) of Flash Player, right click on any embedded Flash content and choose ''Settings'' from the menu, or go to the [http://helpx.adobe.com/flash-player/kb/find-version-flash-player.html Adobe website]. There, a Flash animation will give you access to your local settings.<br />
<br />
You can also use the Flash settings file {{ic|/etc/adobe/mms.cfg}}.<br />
<br />
{{Warning|Flash hardware acceleration can be unstable. See [https://forums.adobe.com/thread/911321]}}<br />
<br />
To enable [[VDPAU]], uncomment the following line:<br />
<br />
EnableLinuxHWVideoDecode=1<br />
<br />
A more detailed example configuration:<br />
<br />
{{hc|/etc/adobe/mms.cfg|2=<br />
AVHardwareDisable = 0<br />
FullScreenDisable = 0<br />
LocalFileReadDisable = 1<br />
FileDownloadDisable = 1<br />
FileUploadDisable = 1<br />
LocalStorageLimit = 1<br />
ThirdPartyStorage = 1<br />
AssetCacheSize = 10<br />
AutoUpdateDisable = 1<br />
LegacyDomainMatching = 0<br />
LocalFileLegacyAction = 0<br />
AllowUserLocalTrust = 0<br />
# DisableSockets = 1 <br />
OverrideGPUValidation = 1<br />
DisableDeviceFontEnumeration = 1 #Prevent sites to identify you by snooping the installed fonts<br />
}}<br />
<br />
You can also refer to the [http://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo-x86/www-plugins/adobe-flash/files/mms.cfg mms.cfg from Gentoo], which is extensively commented.<br />
<br />
==== Disable the "Press ESC to exit full screen mode" message ====<br />
{{Note|This only works for the NPAPI plugin.}}<br />
For a way to disable this message see [http://ubuntuforums.org/showthread.php?t=1839293 this ubuntuforums.org post].<br />
<br />
Backup {{ic|libflashplayer.so}}:<br />
# cp /usr/lib/mozilla/plugins/libflashplayer.so /usr/lib/mozilla/plugins/libflashplayer.so.backup <br />
<br />
Make a copy of it in your home directory:<br />
# cp /usr/lib/mozilla/plugins/libflashplayer.so ~/<br />
<br />
Install {{Pkg|wine}} from the official repositories.<br />
<br />
Download {{ic|Flash Fullscreen Patcher.zip}} from [http://forum.videohelp.com/threads/304807-How-to-remove-annoying-Press-Esc-to-message-in-Flash-Video this page], extract and execute with {{ic|wine}}:<br />
<br />
$ wget http://forum.videohelp.com/attachments/16250-1360745667/Flash%20Fullscreen%20Patcher.zip<br />
$ unzip Flash\ Fullscreen\ Patcher\ 2.0.zip<br />
$ wine Flash\ Fullscreen\ Patcher\ 2.0.exe<br />
<br />
Patch {{ic|libflashplayer.so}} (the one from your home directory) using the GUI.<br />
Copy the patched Flash Player back to the plugins directory:<br />
# cp ~/libflashplayer.so /usr/lib/mozilla/plugins/<br />
<br />
==== Multiple monitor full-screen fix ====<br />
<br />
{{Note|<br />
* This only works for the NPAPI plugin.<br />
* There is also a package {{AUR|flashplugin-focusfix}} in the [[AUR]] that includes this fix.<br />
}}<br />
<br />
: ''sourced from this post on [http://www.webupd8.org/2012/10/ubuntu-multi-monitor-tweaks-full-screen.html webupd8]''<br />
<br />
When using a multiple monitor setup, or swapping between virtual desktops, it is possible to lose focus on a fullscreen flash window. In such a case, the adobe flash-plugin will automatically exit full-screen mode. This may not be to your liking.<br />
<br />
Unfortunately, this behavior is hard coded into the binary. In order to change this behavior it is necessary to alter the binary.<br />
<br />
First you will need a hex editor, such as {{Pkg|ghex}}.<br />
<br />
Then, you will need to alter the adobe flash-plugin binary, which is commonly located at {{ic|/lib/mozilla/plugins/libflashplayer.so}}. It is prudent of course to first backup the file, in case you want to revert the behavior or make a mistake while editing.<br />
<br />
# cp /usr/lib/mozilla/plugins/libflashplayer.so /usr/lib/mozilla/plugins/libflashplayer.so.backup <br />
<br />
Then open the binary in the hex editor with '''root privileges''':<br />
<br />
# ghex /usr/lib/mozilla/plugins/libflashplayer.so<br />
<br />
Using the hex editor find the string {{ic|_NET_ACTIVE_WINDOW}}. In ghex the readable string is on the right hand side of the window, and the hex is on the left, you are trying to locate the readable string. It should be easy to find using a search function.<br />
<br />
Upon finding {{ic|_NET_ACTIVE_WINDOW}} rewrite the line, but '''do not''' change the length of the line, for example {{ic|_NET_ACTIVE_WINDOW}} becomes {{ic|_XET_ACTIVE_WINDOW}}.<br />
<br />
Save the binary, and restart any processes using the plugin (as this will crash any instance of the plugin in use.)<br />
<br />
==== Fullscreen fix for GNOME 3 ====<br />
<br />
If you have problems with Flash's fullscreen-mode (video freezes but audio keeps playing), then it is probably because the fullscreen flash window is displayed ''behind'' the browser window. This is a [https://bugzilla.gnome.org/show_bug.cgi?id=722743 known upstream bug in mutter]. You can easily fix this by using [[Wikipedia:Devil's Pie (software)|devilspie]]:<br />
<br />
Install {{Pkg|devilspie}} from the official repositories.<br />
<br />
Create the {{ic|~/.devilspie}} directory:<br />
<br />
# mkdir ~/.devilspie<br />
<br />
Now you have to create a config file for each browser you use (see below)<br />
<br />
Finally, add devilspie to your list of startup items by adding the following file to {{ic|~/.config/autostart}}<br />
{{hc|~/.config/autostart/devilspie.desktop|2=<br />
[Desktop Entry]<br />
Name=devilspie<br />
Exec=devilspie<br />
Hidden=false<br />
NoDisplay=false<br />
X-GNOME-Autostart-enabled=true<br />
}}<br />
<br />
===== Firefox =====<br />
<br />
{{hc|~/.devilspie/flash-fullscreen-firefox.ds|2=<br />
(if<br />
(is (application_name) "plugin-container")<br />
(begin<br />
(focus)<br />
)<br />
)<br />
}}<br />
<br />
===== Chrome / Chromium =====<br />
<br />
{{hc|~/.devilspie/flash-fullscreen-chrome.ds|2=<br />
(if<br />
(is (application_name) "exe")<br />
(begin<br />
(focus)<br />
)<br />
)<br />
}}<br />
<br />
===== Epiphany / GNOME Web =====<br />
<br />
{{hc|~/.devilspie/flash-fullscreen-epiphany.ds|2=<br />
(if<br />
(is (application_name) "WebKitPluginProcess")<br />
(begin<br />
(focus)<br />
)<br />
)<br />
}}<br />
<br />
== PDF viewer ==<br />
<br />
=== PDF.js ===<br />
<br />
[https://mozillalabs.com/en-US/pdfjs/ PDF.js] is a PDF renderer created by Mozilla and built using HTML5 technologies.<br />
<br />
For [[Firefox]] it is available as a [https://addons.mozilla.org/en-US/firefox/addon/pdfjs/ plugin], which is included in [[Firefox]] since version 19.<br />
<br />
For [[Chromium]] and Google Chrome there is an experimental extension in the [https://chrome.google.com/webstore/detail/pdf-viewer/oemmndcbldboiebfnladdacbdfmadadm Chrome web store] or alternatively it can be built from the source of [https://github.com/mozilla/pdf.js Pdf.js].<br />
<br />
=== External PDF viewers ===<br />
<br />
To use an external PDF viewer you need [[#MozPlugger]] or [[#kpartsplugin]].<br />
<br />
If you want to use MozPlugger with Evince, for example, you have to find the lines containing {{ic|pdf}} in the {{ic|/etc/mozpluggerrc}} file and modify the corresponding line after {{ic|GV()}} as below:<br />
repeat noisy swallow(evince) fill: evince "$file"<br />
(replace {{ic|evince}} with something else if it is not your viewer of choice).<br />
<br />
If this is not enough, you may need to change 2 values in {{ic|about:config}}:<br />
* Change {{ic|pdfjs.disabled}}'s value to ''true'';<br />
* Change {{ic|plugin.disable_full_page_plugin_for_types}}'s value to an empty value.<br />
<br />
Restart and it should work like a charm!<br />
<br />
=== Adobe Reader ===<br />
<br />
Due to licensing restrictions, Adobe Reader cannot be distributed from any of the official Arch Linux repositories. There are versions available in the [[AUR]]. Please note that no matter how many votes it receives, Adobe Reader will never be included in the [[official repositories]].<br />
<br />
Also, there are [https://aur.archlinux.org/packages.php?O=0&K=acroread-&do_Search=Go localizations] available in many languages.<br />
<br />
==== 32-bit ====<br />
<br />
Adobe Acrobat Reader is only available as a 32-bit binary. It can be installed with the {{AUR|acroread}} package, available in the [[AUR]].<br />
<br />
This package installs the Acrobat Reader application as well as the Firefox plugin. Note that hardware-assisted rendering is unavailable under Linux (at least using a Geforce 8600GTS with driver version 185.18.14).<br />
<br />
==== 64-bit ====<br />
<br />
There is yet to be an official 64-bit version of Adobe Reader.<br />
<br />
To use it in a 64-bit environment, you can:<br />
* Follow [[Install bundled 32-bit system in Arch64|this guide]] originally posted in the forums. It involves creating a chrooted environment that could be reused for other 32-bit only applications.<br />
<br />
* Install {{AUR|acroread}} (with all its 32-bit dependencies) from [[AUR]]. Be advised that the [[Firefox]] plugin cannot be used ''directly'' with this binary -- it will not load in the 64-bit browser. To load it install the {{Pkg|nspluginwrapper}} package from the official [[Multilib|[multilib]]] repository and run:<br />
$ nspluginwrapper -v -a -i<br />
as a normal user. This checks the plugin directory and links the plugins as needed.<br />
<br />
== Citrix ==<br />
<br />
See [[Citrix]].<br />
<br />
== Java (IcedTea) ==<br />
<br />
{{Note|Java [https://www.java.com/en/download/faq/chrome.xml does not work on Chromium], since they've disabled all NPAPI pluggins. Install another browser to use any Java plugin.}}<br />
<br />
To enable [[Java]] support in your browser, you have two options: the open-source [[Wikipedia:OpenJDK|OpenJDK]] (recommended) or Oracle's proprietary version. For details about why OpenJDK is recommended see [https://mailman.archlinux.org/pipermail/arch-general/2011-August/021671.html this].<br />
<br />
To use OpenJDK, you have to install the [http://icedtea.classpath.org/wiki/Main_Page IcedTea] browser plugin, {{Pkg|icedtea-web}}.<br />
<br />
If you want to use Oracle's JRE, install the {{AUR|jre}} (or {{AUR|jre6}}) package, available in the [[AUR]].<br />
<br />
See [[Java#OpenJDK]] for additional details and references.<br />
<br />
{{Note|If you experience any problems with the Java plugin (e.g. it is not recognized by the browser), you can try this [[Flash#Plugins_are_installed_but_not_working|solution]].}}<br />
<br />
== Pipelight ==<br />
<br />
See [[Pipelight]].<br />
<br />
== Multimedia playback ==<br />
<br />
Many browsers support the [[GStreamer]] framework to play multimedia inside HTML5 {{ic|<audio>}} and {{ic|<video>}} elements. Check the optional dependencies of the browser package (or {{Pkg|webkitgtk}}/{{Pkg|webkitgtk2}} if using a webkit-based browser) to see which version of GStreamer is supported: this can be either {{ic|gst-*}} for the current version, or {{ic|gstreamer0.10-*}} for the legacy version. See [[GStreamer#Installation]] for the description of each plugin.<br />
<br />
=== Other plugins ===<br />
<br />
* {{App|Gecko Media Player|Mozilla browser plugin to handle media on websites, using MPlayer.|https://sites.google.com/site/kdekorte2/gecko-mediaplayer|{{Pkg|gecko-mediaplayer}}}}<br />
* {{App|Totem Plugin|Browser plugin based on the [[Wikipedia:Totem (software)|Totem]] media player for [[Gnome]] which uses [[Gstreamer]].|http://projects.gnome.org/totem/|{{Pkg|totem}}}}<br />
* {{App|Rosa Media Player Plugin|Qt-based browser plugin also based on MPlayer.|https://abf.rosalinux.ru/uxteam/ROSA_Media_Player|{{AUR|rosa-media-player-plugin}}}}<br />
* {{App|VLC Plugin|NPAPI-based plugin that uses VLC technologies.|http://git.videolan.org/?p&#61;npapi-vlc.git;a&#61;summary|{{AUR|npapi-vlc-git}}}}<br />
<br />
== Other ==<br />
<br />
=== MozPlugger ===<br />
<br />
MozPlugger can be installed with the {{AUR|mozplugger}} package.<br />
<br />
[http://mozplugger.mozdev.org/ MozPlugger] is a Mozilla plugin which can show many types of multimedia inside your browser. To accomplish this, it uses external programs such as MPlayer, xine, Evince, OpenOffice, TiMidity, etc. To modify or add applications to be used by MozPlugger just modify the {{ic|/etc/mozpluggerrc}} file.<br />
<br />
For example, MozPlugger uses OpenOffice by default to open {{ic|doc}} files. To change it to use LibreOffice instead, look for the OpenOffice section:<br />
{{hc|/etc/mozpluggerrc|<br />
...<br />
### OpenOffice<br />
define([OO],[swallow(VCLSalFrame) fill: ooffice2.0 -nologo -norestore -view $1 "$file"<br />
swallow(VCLSalFrame) fill: ooffice -nologo -norestore -view $1 "$file"<br />
swallow(VCLSalFrame) fill: soffice -nologo $1 "$file"])<br />
...<br />
}}<br />
and add LibreOffice at the beginning of the list:<br />
{{hc|/etc/mozpluggerrc|<br />
...<br />
### LibreOffice/OpenOffice<br />
define([OO],[swallow(VCLSalFrame) fill: libreoffice --nologo --norestore --view $1 "$file"<br />
swallow(VCLSalFrame) fill: ooffice2.0 -nologo -norestore -view $1 "$file"<br />
swallow(VCLSalFrame) fill: ooffice -nologo -norestore -view $1 "$file"<br />
swallow(VCLSalFrame) fill: soffice -nologo $1 "$file"])<br />
...<br />
}}<br />
{{Note|Be sure to also choose LibreOffice as your preferred application to open {{ic|doc}} files.}}<br />
<br />
As another simple example, if you want to open {{ic|cpp}} files with your favorite text editor (we will use Kate) to get syntax highlighting, just add a new section to your {{ic|mozpluggerrc}} file:<br />
{{hc|/etc/mozpluggerrc|<br />
text/x-c++:cpp:C++ Source File<br />
text/x-c++:hpp:C++ Header File<br />
repeat noisy swallow(kate) fill: kate -b "$file"<br />
}}<br />
<br />
To change the default of MPlayer so that [[mpv]] is used instead, change the appropriate lines such that:<br />
{{hc|1=/etc/mozpluggerrc|2=<br />
...<br />
### MPlayer<br />
<br />
#define(MP_CMD,[mplayer -really-quiet -nojoystick -nofs -zoom -vo xv,x11 -ao esd,alsa,oss,arts,null -osdlevel 0 $1 </dev/null])<br />
define(MP_CMD,[mpv -really-quiet $1 </dev/null])<br />
<br />
#define(MP_EMBED,[embed noisy ignore_errors: MP_CMD(-xy $width -wid $window $1)])<br />
define(MP_EMBED,[embed noisy ignore_errors: MP_CMD(--autofit=$width -wid $window $1)])<br />
<br />
#define(MP_NOEMBED,[noembed noisy ignore_errors maxaspect swallow(MPlayer): MP_CMD($1)])<br />
define(MP_NOEMBED,[noembed noisy ignore_errors maxaspect swallow(mpv): MP_CMD($1)])<br />
<br />
...<br />
<br />
#define(MP_AUDIO,[mplayer -quiet -nojoystick $1 </dev/null])<br />
define(MP_AUDIO,[mpv -really-quiet $1 </dev/null])<br />
<br />
#define(MP_AUDIO_STREAM,[controls stream noisy ignore_errors: mplayer -quiet -nojoystick $1 "$file" </dev/null])<br />
define(MP_AUDIO_STREAM,[controls stream noisy ignore_errors: mpv -really-quiet $1 "$file" </dev/null])<br />
...<br />
}}<br />
<br />
For a more complete list of MozPlugger options see [http://www.linuxmanpages.com/man7/mozplugger.7.php this page].<br />
<br />
=== kpartsplugin ===<br />
<br />
[http://www.unix-ag.uni-kl.de/~fischer/kpartsplugin/ The KParts plugin] is a plugin that uses KDE's KPart technology to embed different file viewers in the browser, such as Okular (for PDF), Ark (for different archives), Calligra Words (for ODF), etc. It cannot use applications that are not based on the KPart technology.<br />
<br />
The KParts plugin can be installed with the package {{Pkg|kpartsplugin}}, available in the official repositories.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Flash Player: no sound ===<br />
<br />
Flash Player outputs its sound only through the default [[Advanced Linux Sound Architecture|ALSA]] device, which is number '''0'''. If you have multiple sound devices (a very common example is having a sound card and HDMI output in the video card), then your preferred device may have a different number.<br />
<br />
For a list of available devices with their respective numbers, run:<br />
{{hc|$ aplay -l|<br />
**** List of PLAYBACK Hardware Devices ****<br />
card 0: Generic [HD-Audio Generic], device 3: HDMI 0 [HDMI 0]<br />
Subdevices: 1/1<br />
Subdevice #0: subdevice #0<br />
card 1: DX [Xonar DX], device 0: Multichannel [Multichannel]<br />
Subdevices: 0/1<br />
Subdevice #0: subdevice #0<br />
card 1: DX [Xonar DX], device 1: Digital [Digital]<br />
Subdevices: 1/1<br />
Subdevice #0: subdevice #0<br />
}}<br />
In this case, the HDMI output is {{ic|card 0}} and the sound card is {{ic|card 1}}. To make your sound card the default for ALSA, create the file {{ic|.asoundrc}} in your home directory, with the following content:<br />
{{hc|~/.asoundrc|<br />
pcm.!default {<br />
type hw<br />
card 1<br />
}<br />
<br />
ctl.!default {<br />
type hw<br />
card 1<br />
}<br />
}}<br />
<br />
=== Flash Player: blocking sound for other applications or delayed playback ===<br />
<br />
If sound is delayed within Flash videos or Flash stops sound from any other application, then make sure you do not have {{ic|snd_pcm_oss}} module loaded:<br />
$ lsmod | grep snd_pcm_oss<br />
You can unload it:<br />
# rmmod snd_pcm_oss<br />
and restart the browser to see if it helps.<br />
<br />
=== Flash Player: performance ===<br />
<br />
Adobe's Flash plugin has some serious performance issues, especially when CPU frequency scaling is used. There seems to be a policy not to use the whole CPU workload, so the frequency scaling governor does not clock the CPU any higher. To work around this issue, see [[CPU frequency scaling#Switching threshold]]<br />
<br />
=== Flash Player: low webcam resolution ===<br />
<br />
If your webcam has low resolution in Flash (the image looks very pixelated) you can try starting your browser with this:<br />
$ LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so [broswer]<br />
<br />
=== Flash Player: black bars in full screen playback on multi-headed setups ===<br />
<br />
The Flash plugin has a known bug where the full screen mode does not really work when you have a multi-monitor setup. Apparently, it incorrectly determines the full screen resolution, so the full screen Flash Player fills the correct monitor but gets scaled as if the monitor had the resolution of the total display area.<br />
<br />
To fix this, you can use the "hack" described [http://al.robotfuzz.com/content/workaround-fullscreen-flash-linux-multiheaded-desktops here]. Simply download the source from the link given on the page, and follow the instructions in the README.<br />
<br />
{{Tip|The hack is available in the [[AUR]] and can be installed with the {{AUR|fullscreenhack}} package.}}<br />
<br />
{{Note|While the author mentions using NVDIA's TwinView, the hack should work for any multi-monitor setup.}}<br />
<br />
=== Flash Player: blue tint on videos with NVIDIA ===<br />
<br />
An issue with {{Pkg|flashplugin}} versions 11.2.202.228-1 and 11.2.202.233-1 causes it to send the U/V panes in the incorrect order resulting in a blue tint on certain videos. Version 0.5 of {{Pkg|libvdpau}} includes a workaround to fix this, see the [http://lists.x.org/archives/xorg-announce/2012-September/002066.html official announcement].<br />
<br />
=== Flash Player: leaking overlay with NVIDIA ===<br />
<br />
This bug is due to the incorrect color key being used by the {{Pkg|flashplugin}} version 11.2.202.228-1 (see [http://www.nvnews.net/vbulletin/showpost.php?p=2514210&postcount=102 this post] on the NVIDIA forums) and causes the Flash content to "leak" into other pages or solid black backgrounds. To avoid this issue simply export {{ic|1=VDPAU_NVIDIA_NO_OVERLAY=1}} within either your shell profile (e.g. {{ic|~/.bash_profile}} or {{ic|~/.zprofile}}) or {{ic|~/.xinitrc}}<br />
<br />
=== Flash Player: videos not working on older systems ===<br />
<br />
If you have Adobe Flash installed on an older system and you start playing a video which simply turns black with nothing happening, it is most likely that your CPU does not support SSE2. You can simply check this by looking at your CPU flags with this command:<br />
$ grep sse2 /proc/cpuinfo<br />
<br />
If no results are returned, then you need to install an older version of Flash (for example 10.3, or 11.1). Older versions possibly will have vulnerabilities. You should then consider sandboxing Firefox using {{AUR|sandfox}}, available in the [[AUR]]. See the [https://igurublog.wordpress.com/downloads/script-sandfox/ sandfox homepage] for usage information.<br />
<br />
Older versions of Flash are available here:<br />
https://www.adobe.com/products/flashplayer/distribution3.html<br />
You need to copy {{ic|libflashplayer.so}} to the folder {{ic|/usr/lib/mozilla/plugins/}}<br />
<br />
Older {{Pkg|flashplugin}} packages can be downloaded from the [[AUR]] e.g. {{AUR|flashplugin-10}}.<br />
<br />
The most recent package without SSE2 is {{ic|flashplugin-11.1.102.63-1-i686.pkg.tar.xz}}. If you use the packaged version, you have to add {{ic|IgnorePkg &#61; flashplugin}} to {{ic|/etc/pacman.conf}}.<br />
<br />
=== Plugins are installed but not working ===<br />
<br />
A common problem is that the plugin path is unset. This typically occurs on a new install, when the user has not re-logged in before running Firefox after the installation. Test if the path is unset:<br />
echo $MOZ_PLUGIN_PATH<br />
If unset, then either re-login, or source {{ic|/etc/profile.d/mozilla-common.sh}} and start Firefox from the same shell:<br />
source /etc/profile.d/mozilla-common.sh && firefox<br />
<br />
=== Gecko Media Player will not play Apple trailers ===<br />
<br />
If Apple Trailers appear to start to play and then fail, try setting the user agent for your browser to:<br />
QuickTime/7.6.2 (qtver=7.6.2;os=Windows NT 5.1Service Pack 3)</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Libvirt&diff=344429Libvirt2014-11-12T17:22:20Z<p>Jstjohn: /* using virt-install */ fix typos; improve grammar</p>
<hr />
<div>{{DISPLAYTITLE:libvirt}}<br />
[[Category:Virtualization]]<br />
[[ja:libvirt]]<br />
[[zh-CN:libvirt]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related articles end}}<br />
<br />
libvirt is a [https://fedoraproject.org/wiki/Virtualization?rd=Tools/Virtualization#Full_Virtualization virtualization] API and daemon for managing virtual machines. It provides an abstraction layer between the virtualization technology and the user interface with the purpose to help administer numerous users and virtual machines; it can record settings, pool local and remote VM images, monitor VM performance, etc.<br />
<br />
== Purpose ==<br />
<br />
libvirt is primarily designed to be able to test numerous operating systems or software. It additionally can provide these virtual machines to a number of people and it allows virtual machines can be easily created and destroyed. Generally these virtual machines are Linux-based and server-based, relying on the [[KVM]] hypervisor. KVM generally focuses on server virtualization while others (e.g. [[VirtualBox]]) focuses on desktop virtualization. Desktop virtualization is possible and does well in disk throughput and networking (with the VirtIO drivers), but compares less in 2D/3D graphic acceleration.<br />
<br />
== Installation ==<br />
<br />
Install {{pkg|libvirt}} from the [[official repositories]]. Afterwards, ''back-end'' end support and a ''front-end'' user interface will need to be chosen.<br />
<br />
The ''back-end'' is the virtualization technology itself, a.k.a. hypervisor, whether it be hardware, software, firmware, etc.<br />
<br />
* [[KVM]] (kernel-based virtual machine) is the standard back-end; it is supported by the machine emulator [[QEMU]].<br />
* Other supported back-ends are listed on the [[wikipedia:Libvirt#Supported_Hypervisors|Wikipedia page]].<br />
<br />
The ''front-end'' is the user interface to configure and start the virtual machine.<br />
<br />
* {{ic|virsh}} (short for virtual shell) is a thorough, command line program used for configuring virtual machines; it is included in the libvirt package.<br />
* {{pkg|virt-viewer}} is often the program used to view virtual machines started with {{ic|virsh}}.<br />
* {{pkg|virt-manager}} is a graphical user interface that can create, configure, and view virtual machines.<br />
* Other supported front-ends are listed on the [[wikipedia:Libvirt#User_Interfaces|Wikipedia page]].<br />
<br />
For ''system'' network connectivity, install either: <br />
<br />
* {{Pkg|ebtables}} and {{Pkg|dnsmasq}} for the default NAT/DHCP networking.<br />
* {{Pkg|bridge-utils}} for bridged networking.<br />
* {{Pkg|openbsd-netcat}} for remote management over [[SSH]].<br />
<br />
{{note|For libvirt [[Xen]] support, libvirt will need to be recompiled. Currently, the package {{pkg|libvirt}}, and the AUR package {{aur|libvirt-git}}, disable the Xen back-end. To do so, grab the package build source from the [[Arch Build System|ABS]], and build following removal of the {{ic|--without-xen}} compile flag.}}<br />
<br />
== Configuration ==<br />
<br />
For ''system'' administration (i.e. global image location and administration), libvirt requires [[#Setting up authorization]] and starting the [[#daemon]].<br />
<br />
For user-''session'' administration, authorization is limited to local abilities and the front-end will launch a local instance of libvirt.<br />
<br />
=== Setting up authorization ===<br />
<br />
The ''libvirt'' [[Users and groups|group]] will need to be created and any users wanting to be able to manage virtual machines added to this group:<br />
<br />
# groupadd libvirt<br />
# gpasswd --add ''username'' libvirt<br />
<br />
'''Re-login''' any user that is added to the group (one must log into a group to be included in it). Then choose an authentication method, either: [[#Authenticating with polkit|polkit]], ''or'' [[#Authenticating with file-based permissions|file-based permissions]].<br />
<br />
==== Authenticating with polkit ====<br />
<br />
To use a polkit rule for users in the ''libvirt'' group to manage virtual machines, create:<br />
<br />
{{hc|/etc/polkit-1/rules.d/50-org.libvirt.unix.manage.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.libvirt.unix.manage" &&<br />
subject.isInGroup("libvirt")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
</nowiki>}}<br />
<br />
''To grant only '''monitoring''' privileges use {{ic|org.libvirt.unix.monitor}} (for more information, see [http://wiki.libvirt.org/page/SSHPolicyKitSetup#Configuring_management_access_via_PolicyKit this]).''<br />
<br />
==== Authenticating with file-based permissions ====<br />
<br />
To define file-based permissions for users in the ''libvirt'' group to manage virtual machines, uncomment and define:<br />
<br />
{{hc|/etc/libvirt/libvirtd.conf|<nowiki><br />
#unix_sock_group = "libvirt"<br />
#unix_sock_ro_perms = "0777" # set to 0770 to deny non-group libvirt users<br />
#unix_sock_rw_perms = "0770"<br />
#auth_unix_ro = "none"<br />
#auth_unix_rw = "none"<br />
</nowiki>}}<br />
<br />
{{note|Some guides mention changed permissions of certain libvirt directories. While this may make management easier, know such permissions are lost on package update. To edit these system directories, root user is expected.}}<br />
<br />
== Daemon ==<br />
<br />
To use libvirt, start and enable the {{ic|libvirtd}} [[Systemd#Using units|systemd service]].<br />
<br />
== Test ==<br />
<br />
To test if the daemon is working properly on a ''system'' level:<br />
<br />
virsh -c qemu:///system<br />
<br />
To test if libvirt is working properly for a user-''session'':<br />
<br />
virsh -c qemu:///session<br />
<br />
==Usage: creation of a new VM==<br />
Libvirt management is mostly done with three tools : one GUI, '''virt-manager''', and two CLI commands: '''virsh''' (part of libvirt) and '''guestfish''' (part of {{AUR|libguestfs}}). Both tools let you create and then manage your VM.<br />
{{tip|basic virsh usages<br />
* {{ic|$ virsh [options]...<command> [args...]}} run a virsch command from your shell <br />
{{hc|$ virsh #launch an interactive virsh session|# virsh }} <br />
* {{ic|$ virsh list}} show ''running'' domains (pool-list lists ''active'' pools)<br />
* {{ic|$ virsh list --all}} list ''all'' domains ((pool-list --all lists ''all'' pools)<br />
}}<br />
{{Note|the virsh command is run as a regular user. This user shall belongs to the ''libvirt'' group.}}<br />
===Creating a storage pool===<br />
A ''storage pool'' is a quantity of storage for use by virtual machines. Storage pools are often divided into storage volumes and the volumes are assigned to guest virtual machines as block devices. The pool can be:<br />
* a directory pool<br />
* a filesystem pool<br />
* a network filesystem pool<br />
* a logical volume pool<br />
<br />
====using virt-manager====<br />
<br />
First, connect to an existing server. Once you are there, right click and choose '''Details'''. Go to '''Storage''' and press the '''+''' icon at the lower left. Then just follow the wizard.<br />
<br />
====using virsh====<br />
Add a [[lvm|logical volume]] pool when assuming there is already a '''vg0/''myStoragePool''''' LVM volume with some free space on it, as shown by the command output below.<br />
{{hc|# vgs|<br />
VG #PV #LV #SN Attr VSize VFree<br />
vg0 1 6 0 wz--n- 1.5t 150G<br />
}}<br />
We want now use the free space as a storage pool on a virsh interactive session.<br />
{{bc|# virsh<br />
<br />
virsh # pool-define-as ''myPoolName'' fs - - /dev/vg0/''myStoragePool'' - "''myMntPoint''"<br />
Pool ''myPoolName'' defined<br />
<br />
virsh# pool-build ''myPoolName''<br />
Pool ''myPoolName'' built<br />
<br />
virsh # pool-start ''myPoolName''<br />
Pool ''myPoolName'' started<br />
<br />
virsh # pool-list --all<br />
Name State Autostart<br />
<br />
default active yes<br />
''myPoolName'' active no<br />
<br />
virsh # pool-autostart ''myPoolName''<br />
Pool ''myPoolName'' marked as autostarted<br />
<br />
virsh # pool-info ''myPoolName''<br />
Name: ''myPoolName''<br />
UUID: 71dcb73a-6af9-4595-8208-a1c83e1ec6c7<br />
State: running<br />
Persistent: yes<br />
Autostart: yes<br />
Capacity: 1.5 t<br />
Allocation: 1 t<br />
Available: 150G<br />
<br />
virsh # quit<br />
}}<br />
<br />
{{Note|<br />
* libvirt will in fact change the ''myPoolName'' to ''myMntPoint''. When lisitng pools, the name will thus be ''myMntPoint''<br />
* a new ''myPoolName''.xml file has been created in {{ic|/etc/libvirt/storage}}<br />
* a new mountpoint ''myMntPoint'' directory is created<br />
* you can remove the default pool with the command {{ic|$ virsh pool-undefine default}}<br />
* the LVM volume vg0/''myStoragePool'' will be automatically mounted on the defined ''myMntPoint'' when VM is starting. No need to deal with it in your {{ic|/etc/fstab}}<br />
}}<br />
{{Tip|<br />
* Best practice is to dedicate a volume group to your storage pool only. Storage pool will be auto-started and could either contains volume you do not want to mount<br />
* Do not use your LVM volume group as your pool name, otherwise when deleting the pool storage you will delete your LVM group too<br />
}}<br />
<br />
===Creating a storage volume===<br />
Once the pool has been created, volumes for each VM can be created inside the pool.<br />
<br />
====Using virsh====<br />
{{bc|# virsh<br />
<br />
virsh # vol-create-as ''myPoolName'' volume1 120G<br />
Vol volume1 created<br />
<br />
# virsh vol-list ''myPoolName''<br />
Name Path<br />
<br />
volume1 ''myMntPoint''/volume1<br />
<br />
# virsh vol-dumpxml --pool ''myPoolName'' volume1<br />
<--------><br />
info on volume1 in xml format <br />
<---------><br />
<br />
}}<br />
<br />
{{Note|<br />
* the {{ic|vol-create}} command will take a while<br />
* a new file volume1 for installing the VM on has been created in ''myMntPoint''<br />
* to ''delete'' a volume, use this command {{ic| virsh # vol-delete volume1 --pool ''myPoolName''}}<br />
}}<br />
<br />
===Installing a new VM===<br />
To create a new VM, you need some sort of installation media, which is usually a standard {{ic|.iso}} file. Copy it to the {{ic|/var/lib/libvirt/images/}} directory (alternatively, you can create a new ''storage pool'' directory in virt-manager and copy it there).<br />
<br />
{{Note|[[SELinux]] requires that virtual machines be stored in {{ic|/var/lib/libvirt/images/}} by default. If you use SELinux and are having issues with virtual machines, ensure that your VMs are in that directory or ensure that you have added the correct labeling to the non-default directory that you used.}}<br />
<br />
====using virt-manager====<br />
<br />
Then run {{ic|virt-manager}}, connect to the server, right click on the connection and choose '''New'''. Choose a name, and select '''Local install media'''. Just continue with the wizard.<br />
<br />
On the '''4th step''', you may want to uncheck ''Allocate entire disk now'' -- this way you will save space when your VM is not using all of its disk. However, this can cause increased fragmentation of the disk, and you ''must'' pay attention to the total available disk space on the VM host because it is much easier to over-allocate disk space to VMs.<br />
<br />
On the '''5th step''', open '''Advanced options''' and make sure that ''Virt Type'' is set to '''kvm'''.<br />
<br />
====using virt-install====<br />
The {{ic|$ virt-install}} command let you create the new VM with many arguments and sub options. For a complete list of arguments, please see [[http://linux.die.net/man/1/virt-install man virt-install]].<br />
<br />
The command will take this pattern:<br />
{{ic|$ virt-install --connect ''hypervisor'':///system [list of arguments and options]}}. <br />
{{Note| <br />
* {{ic|///session}} let you create/manage guests as a regular '''user'''. {{ic|///system}} create guests run by the system libvirtd instance.<br />
* ''hypervisor'' can of course be [[QEMU]], [[Xen]], [[Linux_Containers|lxc]].<br />
}}.<br />
<br />
Below is a basic command with most useful arguments. For clarification, the '''qemu''' hypervisor is used, the installed OS is '''windows8'''. <br />
{{bc|<nowiki> $ virt-install --connect qemu:///system \<br />
--name=myVMname \ # name of your VM<br />
--memory=2048 \ # RAM you want to allocate<br />
--os-variant=win7 \ # type of os for the VM- win7 OR later<br />
--disk /path/to/myMntPoint/volume1 \ # point to the VM image<br />
--virt-type kvm \ # virtualization type<br />
--cdrom /dev/cdrom \ # use your guest CD-ROM<br />
--disk /path/to/iso/file,cdrom \ # path to guest .iso file. It will be on a CD-ROM device in the w8 guest and will be added as a storage pool.<br />
--controller scsi,model=virtio-scsi # use virtio<br />
</nowiki>}}<br />
<br />
{{Note|<br />
* the above command will create a {{ic|'''$XDG_CONFIG_HOME'''/libvirt/qemu/myVMname.xml}} file. This file can be edited later to more precised options.<br />
* the new VM is listed in ''virt-manager''<br />
* As of 2014-08-20, the [http://www.spice-space.org/ spice protocol] does not provide windows binaries for w8. In case you really want this graphic protocol, you have to stick to w7 and add this line {{ic|--graphics spice}} to the {{ic|virt-install}} command.<br />
}}<br />
{{Tip| <br />
* It is possible to create a VM using an existing ''configuration_file.xml'' with the following command {{ic|virsh create ''configuration_file.xml''}}<br />
* Most drivers and fine-tuning sub options can be modified/added later when managing the VM. Best is to start with a basic install. For example, the above command will make the VM use the NAT network. If a more sophisticated network is wanted (like a bridge), do it later.}}<br />
<br />
====Using VirtualBox with virt-manager====<br />
{{Merge|virtualbox|this section would fit better in virtualbox wiki}}<br />
{{Note|[[VirtualBox]] support in libvirt is not quite stable yet and may cause your libvirtd to crash. Usually this is harmless and everything will be back once you restart the daemon.}}<br />
<br />
virt-manager does not let you to add any VirtualBox connections from the GUI. However, you can launch it from the command line:<br />
virt-manager -c vbox:///system<br />
<br />
Or if you want to manage a remote system over SSH:<br />
<nowiki>virt-manager -c vbox+ssh://username@host/system</nowiki><br />
<br />
==Usage: management of a VM==<br />
=== Using virt-manager ===<br />
The usage is pretty straightforward. Start the '''Virtual Machine Manager''', then click on the desired listed machine. It will then open the VM windows. Under the ''View'' menu, select ''Details''. You will see a new window with everything needed to list/view/add/modify ''Hardware''.<br />
<br />
=== Using virsh ===<br />
==== Starting KVM virtual machines on boot up ====<br />
<br />
At the command line, to set a VM to automatically start at boot-up, run:<br />
<br />
$ virsh autostart <domain><br />
<br />
To disable automatic starting:<br />
<br />
$ virsh autostart --disable <domain><br />
<br />
''virt-manager'' is equally easy having an autostart check box in the boot options of the VM.<br />
<br />
{{Note|VMs started by QEMU or KVM from the command line are not then manageable by ''virt-manager''.}}<br />
====Stopping / resuming guest at host shutdown / startup ====<br />
Running guests may be suspended (or shutdown) at host shutdown automatically using the {{ic|libvirt-guests.service}} systemd service. This same daemon will resume (startup) the suspended (shutdown) guests automatically at host startup.<br />
Check {{ic|/etc/conf.d/libvirtd-guests}} for libvirt-guests options.<br />
<br />
==== Live snapshots ====<br />
A feature called external snapshotting allows one to take a live snapshot of a virtual machine without turning it off. Currently it only works with qcow2 and raw file based images.<br />
<br />
Once a snapshot is created, KVM attaches that new snapshotted image to virtual machine that is used as its new block device, storing any new data directly to it while the original disk image is taken offline which you can easily copy or backup. After that you can merge the snapshotted image to the original image, again without shutting down your virtual machine.<br />
<br />
Here is how it works.<br />
<br />
Currently running virtual machines:<br />
{{hc|# virsh list|<nowiki><br />
Id Name State<br />
----------------------------------------------------<br />
3 archey running<br />
</nowiki>}}<br />
<br />
List all its current images:<br />
{{hc|# virsh domblklist archey|<nowiki><br />
Target Source<br />
------------------------------------------------<br />
vda /vms/archey.img<br />
</nowiki>}}<br />
<br />
Notice the image file properties<br />
{{hc|# qemu-img info /vms/archey.img|<nowiki><br />
image: /vms/archey.img<br />
file format: qcow2<br />
virtual size: 50G (53687091200 bytes)<br />
disk size: 2.1G<br />
cluster_size: 65536<br />
</nowiki>}}<br />
<br />
Create a disk-only snapshot. The switch {{ic|--atomic}} makes sure that the VM is not modified if snapshot creation fails.<br />
# virsh snapshot-create-as archey snapshot1 --disk-only --atomic<br />
<br />
List if you want to see the snapshots:<br />
{{hc|# virsh snapshot-list archey|<nowiki><br />
Name Creation Time State<br />
------------------------------------------------------------<br />
snapshot1 2012-10-21 17:12:57 -0700 disk-snapshot<br />
</nowiki>}}<br />
<br />
Notice the new snapshot image created by virsh and its image properties. It weighs just a few MiBs and is linked to its original "backing image/chain".<br />
{{hc|# qemu-img info /vms/archey.snapshot1|<nowiki><br />
image: /vms/archey.snapshot1<br />
file format: qcow2<br />
virtual size: 50G (53687091200 bytes)<br />
disk size: 18M<br />
cluster_size: 65536<br />
backing file: /vms/archey.img<br />
</nowiki>}}<br />
<br />
At this point, you can go ahead and copy the original image with {{ic|1=cp -sparse=true}} or {{ic|rsync -S}}. <br />
Then you can merge the original image back into the snapshot.<br />
# virsh blockpull --domain archey --path /vms/archey.snapshot1<br />
<br />
Now that you have pulled the blocks out of original image, the file {{ic|/vms/archey.snapshot1}} becomes the new disk image. Check its disk size to see what it means. After that is done, the original image {{ic|/vms/archey.img}} and the snapshot metadata can be deleted safely. The {{ic|virsh blockcommit}} would work opposite to {{ic|blockpull}} but it seems to be currently under development in qemu-kvm 1.3 (including snapshot-revert feature), scheduled to be released sometime next year.<br />
<br />
This new feature of KVM will certainly come handy to the people who like to take frequent live backups without risking corruption of the file system.<br />
<br />
==Remote access to libvirt==<br />
<br />
===Using unencrypted TCP/IP socket (most simple, least secure)===<br />
{{Warning|This should ''only'' be used for testing or use over a secure, private, and trusted network.}}<br />
<br />
Edit {{ic|/etc/libvirt/libvirtd.conf}}:<br />
{{hc|/etc/libvirt/libvirtd.conf|<nowiki><br />
listen_tls = 0<br />
listen_tcp = 1<br />
auth_tcp=none<br />
</nowiki>}}<br />
<br />
{{Warning|We do not enable SASL here, so all TCP traffic is cleartext! For real world use, ''always'' enable SASL.}}<br />
<br />
It is also necessary to start the server in listening mode by editing {{ic|/etc/conf.d/libvirtd}} <br />
{{hc|/etc/conf.d/libvirtd|2=LIBVIRTD_ARGS="--listen"}}<br />
<br />
===Using SSH===<br />
The {{Pkg|openbsd-netcat}} package is needed for remote management over [[SSH]].<br />
<br />
To connect to the remote system using {{ic|virsh}}:<br />
$ virsh -c qemu+ssh://''username''@''host''/system<br />
<br />
If something goes wrong, you can get some logs using:<br />
$ LIBVIRT_DEBUG=1 virsh -c qemu+ssh://''username''@''host''/system<br />
<br />
To display the graphical console for a virtual machine:<br />
$ virt-viewer --connect qemu+ssh://''username''@''host''/system myvirtualmachine<br />
<br />
To display the virtual machine desktop management tool:<br />
$ virt-manager -c qemu+ssh://''username''@''host''/system<br />
<br />
{{Note|If you are having problems connecting to a remote RHEL server (or anything other than Arch, really), try the two workarounds mentioned in {{bug|30748}} and {{bug|22068}}.}}<br />
<br />
=== Using Python ===<br />
The {{Pkg|libvirt-python}} package provides a {{Pkg|python2}} API in {{ic|/usr/lib/python2.7/site-packages/libvirt.py}}.<br />
<br />
General examples are given in {{ic|/usr/share/doc/libvirt-python-''your_libvirt_version''/examples/}}<br />
<br />
Unofficial example using {{Pkg|qemu}} and {{Pkg|openssh}}:<br />
<br />
#! /usr/bin/env python2<br />
# -*- coding: utf-8 -*-<br />
import socket<br />
import sys<br />
import libvirt<br />
if (__name__ == "__main__"):<br />
<nowiki>conn = libvirt.open("qemu+ssh://xxx/system")</nowiki><br />
print "Trying to find node on xxx"<br />
domains = conn.listDomainsID()<br />
for domainID in domains:<br />
domConnect = conn.lookupByID(domainID)<br />
if domConnect.name() == 'xxx-node':<br />
print "Found shared node on xxx with ID " + str(domainID)<br />
domServ = domConnect<br />
break<br />
<br />
== Bridged networking ==<br />
To use ''physical Ethernet'' from your virtual machines, you have to create a ''bridge'' between your physical Ethernet device (here ''eth0'') and the virtual Ethernet device the VM is using.<br />
<br />
=== Host configuration ===<br />
<br />
libvirt creates the bridge ''virbr0'' for NAT networking, so use another name such as ''br0'' or ''virbr1''.<br />
You have to create a new [[Netctl]] or [[Systemd-networkd]] profile to configure the bridge, for example (with DHCP configuration):<br />
<br />
{{hc|/etc/netctl/br0|<nowiki><br />
Description="Bridge connection for kvm"<br />
Interface=br0<br />
Connection=bridge<br />
BindsToInterfaces=(eno1)<br />
IP=dhcp<br />
</nowiki>}}<br />
<br />
{{out of date|The tip below needs to be updated for [[netctl]].}}<br />
{{Tip|It is recommended that you enable [[Wikipedia:Spanning_Tree_Protocol|Spanning Tree Protocol]] (STP) on the virtual bridge (e.g. ''br0'') that you create to avoid any potential bridging loops. You can automatically enable STP by appending {{ic|1=POST_UP="brctl stp $INTERFACE on"}} to the netcfg profile.}}<br />
<br />
=== Guest configuration ===<br />
<br />
Now we have to activate the ''bridge interface'' in our ''VMs''.<br />
If have a recent Linux machine, you can use this code in the ''.xml'' file:<br />
<br />
[...]<br />
<interface type='bridge'><br />
<source bridge='br0'/><br />
<mac address='24:42:53:21:52:49'/><br />
<model type='virtio' /><br />
</interface><br />
[...]<br />
<br />
This code activates a ''virtio'' device on the machine so, in Windows you will have to install an additional driver (you can find it in the AUR package {{aur|virtio-win}} or with [http://www.spice-space.org/download/binaries/ Spice Guest Tools] that includes desktop enhancements like video driver and display resize support) or remove the line {{ic|<model type<nowiki>=</nowiki>'virtio' />}}:<br />
<br />
[...]<br />
<interface type='bridge'><br />
<source bridge='br0'/><br />
<mac address='24:42:53:21:52:49'/><br />
</interface><br />
[...]<br />
<br />
== See also ==<br />
<br />
* [http://libvirt.org/drvqemu.html libvirt web site]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Tuning_and_Optimization_Guide/index.html Virtualization Tuning and Optimization Guide]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Deployment_and_Administration_Guide/sect-KVM_Para_virtualized_virtio_Drivers-Installing_the_drivers_on_an_installed_Windows_guest_virtual_machine.html Installing the drivers on an installed Windows guest virtual machine]<br />
* [http://www-01.ibm.com/support/knowledgecenter/linuxonibm/liaat/liaatkvm.htm IBM KVM]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Deployment_and_Administration_Guide/index.html Red Hat Enterprise Linux 7 Virtualization Deployment and Administration Guide]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Libvirt&diff=344428Libvirt2014-11-12T17:19:26Z<p>Jstjohn: /* See also */ update RHEL 6 links to RHEL 7 versions</p>
<hr />
<div>{{DISPLAYTITLE:libvirt}}<br />
[[Category:Virtualization]]<br />
[[ja:libvirt]]<br />
[[zh-CN:libvirt]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related articles end}}<br />
<br />
libvirt is a [https://fedoraproject.org/wiki/Virtualization?rd=Tools/Virtualization#Full_Virtualization virtualization] API and daemon for managing virtual machines. It provides an abstraction layer between the virtualization technology and the user interface with the purpose to help administer numerous users and virtual machines; it can record settings, pool local and remote VM images, monitor VM performance, etc.<br />
<br />
== Purpose ==<br />
<br />
libvirt is primarily designed to be able to test numerous operating systems or software. It additionally can provide these virtual machines to a number of people and it allows virtual machines can be easily created and destroyed. Generally these virtual machines are Linux-based and server-based, relying on the [[KVM]] hypervisor. KVM generally focuses on server virtualization while others (e.g. [[VirtualBox]]) focuses on desktop virtualization. Desktop virtualization is possible and does well in disk throughput and networking (with the VirtIO drivers), but compares less in 2D/3D graphic acceleration.<br />
<br />
== Installation ==<br />
<br />
Install {{pkg|libvirt}} from the [[official repositories]]. Afterwards, ''back-end'' end support and a ''front-end'' user interface will need to be chosen.<br />
<br />
The ''back-end'' is the virtualization technology itself, a.k.a. hypervisor, whether it be hardware, software, firmware, etc.<br />
<br />
* [[KVM]] (kernel-based virtual machine) is the standard back-end; it is supported by the machine emulator [[QEMU]].<br />
* Other supported back-ends are listed on the [[wikipedia:Libvirt#Supported_Hypervisors|Wikipedia page]].<br />
<br />
The ''front-end'' is the user interface to configure and start the virtual machine.<br />
<br />
* {{ic|virsh}} (short for virtual shell) is a thorough, command line program used for configuring virtual machines; it is included in the libvirt package.<br />
* {{pkg|virt-viewer}} is often the program used to view virtual machines started with {{ic|virsh}}.<br />
* {{pkg|virt-manager}} is a graphical user interface that can create, configure, and view virtual machines.<br />
* Other supported front-ends are listed on the [[wikipedia:Libvirt#User_Interfaces|Wikipedia page]].<br />
<br />
For ''system'' network connectivity, install either: <br />
<br />
* {{Pkg|ebtables}} and {{Pkg|dnsmasq}} for the default NAT/DHCP networking.<br />
* {{Pkg|bridge-utils}} for bridged networking.<br />
* {{Pkg|openbsd-netcat}} for remote management over [[SSH]].<br />
<br />
{{note|For libvirt [[Xen]] support, libvirt will need to be recompiled. Currently, the package {{pkg|libvirt}}, and the AUR package {{aur|libvirt-git}}, disable the Xen back-end. To do so, grab the package build source from the [[Arch Build System|ABS]], and build following removal of the {{ic|--without-xen}} compile flag.}}<br />
<br />
== Configuration ==<br />
<br />
For ''system'' administration (i.e. global image location and administration), libvirt requires [[#Setting up authorization]] and starting the [[#daemon]].<br />
<br />
For user-''session'' administration, authorization is limited to local abilities and the front-end will launch a local instance of libvirt.<br />
<br />
=== Setting up authorization ===<br />
<br />
The ''libvirt'' [[Users and groups|group]] will need to be created and any users wanting to be able to manage virtual machines added to this group:<br />
<br />
# groupadd libvirt<br />
# gpasswd --add ''username'' libvirt<br />
<br />
'''Re-login''' any user that is added to the group (one must log into a group to be included in it). Then choose an authentication method, either: [[#Authenticating with polkit|polkit]], ''or'' [[#Authenticating with file-based permissions|file-based permissions]].<br />
<br />
==== Authenticating with polkit ====<br />
<br />
To use a polkit rule for users in the ''libvirt'' group to manage virtual machines, create:<br />
<br />
{{hc|/etc/polkit-1/rules.d/50-org.libvirt.unix.manage.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.libvirt.unix.manage" &&<br />
subject.isInGroup("libvirt")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
</nowiki>}}<br />
<br />
''To grant only '''monitoring''' privileges use {{ic|org.libvirt.unix.monitor}} (for more information, see [http://wiki.libvirt.org/page/SSHPolicyKitSetup#Configuring_management_access_via_PolicyKit this]).''<br />
<br />
==== Authenticating with file-based permissions ====<br />
<br />
To define file-based permissions for users in the ''libvirt'' group to manage virtual machines, uncomment and define:<br />
<br />
{{hc|/etc/libvirt/libvirtd.conf|<nowiki><br />
#unix_sock_group = "libvirt"<br />
#unix_sock_ro_perms = "0777" # set to 0770 to deny non-group libvirt users<br />
#unix_sock_rw_perms = "0770"<br />
#auth_unix_ro = "none"<br />
#auth_unix_rw = "none"<br />
</nowiki>}}<br />
<br />
{{note|Some guides mention changed permissions of certain libvirt directories. While this may make management easier, know such permissions are lost on package update. To edit these system directories, root user is expected.}}<br />
<br />
== Daemon ==<br />
<br />
To use libvirt, start and enable the {{ic|libvirtd}} [[Systemd#Using units|systemd service]].<br />
<br />
== Test ==<br />
<br />
To test if the daemon is working properly on a ''system'' level:<br />
<br />
virsh -c qemu:///system<br />
<br />
To test if libvirt is working properly for a user-''session'':<br />
<br />
virsh -c qemu:///session<br />
<br />
==Usage: creation of a new VM==<br />
Libvirt management is mostly done with three tools : one GUI, '''virt-manager''', and two CLI commands: '''virsh''' (part of libvirt) and '''guestfish''' (part of {{AUR|libguestfs}}). Both tools let you create and then manage your VM.<br />
{{tip|basic virsh usages<br />
* {{ic|$ virsh [options]...<command> [args...]}} run a virsch command from your shell <br />
{{hc|$ virsh #launch an interactive virsh session|# virsh }} <br />
* {{ic|$ virsh list}} show ''running'' domains (pool-list lists ''active'' pools)<br />
* {{ic|$ virsh list --all}} list ''all'' domains ((pool-list --all lists ''all'' pools)<br />
}}<br />
{{Note|the virsh command is run as a regular user. This user shall belongs to the ''libvirt'' group.}}<br />
===Creating a storage pool===<br />
A ''storage pool'' is a quantity of storage for use by virtual machines. Storage pools are often divided into storage volumes and the volumes are assigned to guest virtual machines as block devices. The pool can be:<br />
* a directory pool<br />
* a filesystem pool<br />
* a network filesystem pool<br />
* a logical volume pool<br />
<br />
====using virt-manager====<br />
<br />
First, connect to an existing server. Once you are there, right click and choose '''Details'''. Go to '''Storage''' and press the '''+''' icon at the lower left. Then just follow the wizard.<br />
<br />
====using virsh====<br />
Add a [[lvm|logical volume]] pool when assuming there is already a '''vg0/''myStoragePool''''' LVM volume with some free space on it, as shown by the command output below.<br />
{{hc|# vgs|<br />
VG #PV #LV #SN Attr VSize VFree<br />
vg0 1 6 0 wz--n- 1.5t 150G<br />
}}<br />
We want now use the free space as a storage pool on a virsh interactive session.<br />
{{bc|# virsh<br />
<br />
virsh # pool-define-as ''myPoolName'' fs - - /dev/vg0/''myStoragePool'' - "''myMntPoint''"<br />
Pool ''myPoolName'' defined<br />
<br />
virsh# pool-build ''myPoolName''<br />
Pool ''myPoolName'' built<br />
<br />
virsh # pool-start ''myPoolName''<br />
Pool ''myPoolName'' started<br />
<br />
virsh # pool-list --all<br />
Name State Autostart<br />
<br />
default active yes<br />
''myPoolName'' active no<br />
<br />
virsh # pool-autostart ''myPoolName''<br />
Pool ''myPoolName'' marked as autostarted<br />
<br />
virsh # pool-info ''myPoolName''<br />
Name: ''myPoolName''<br />
UUID: 71dcb73a-6af9-4595-8208-a1c83e1ec6c7<br />
State: running<br />
Persistent: yes<br />
Autostart: yes<br />
Capacity: 1.5 t<br />
Allocation: 1 t<br />
Available: 150G<br />
<br />
virsh # quit<br />
}}<br />
<br />
{{Note|<br />
* libvirt will in fact change the ''myPoolName'' to ''myMntPoint''. When lisitng pools, the name will thus be ''myMntPoint''<br />
* a new ''myPoolName''.xml file has been created in {{ic|/etc/libvirt/storage}}<br />
* a new mountpoint ''myMntPoint'' directory is created<br />
* you can remove the default pool with the command {{ic|$ virsh pool-undefine default}}<br />
* the LVM volume vg0/''myStoragePool'' will be automatically mounted on the defined ''myMntPoint'' when VM is starting. No need to deal with it in your {{ic|/etc/fstab}}<br />
}}<br />
{{Tip|<br />
* Best practice is to dedicate a volume group to your storage pool only. Storage pool will be auto-started and could either contains volume you do not want to mount<br />
* Do not use your LVM volume group as your pool name, otherwise when deleting the pool storage you will delete your LVM group too<br />
}}<br />
<br />
===Creating a storage volume===<br />
Once the pool has been created, volumes for each VM can be created inside the pool.<br />
<br />
====Using virsh====<br />
{{bc|# virsh<br />
<br />
virsh # vol-create-as ''myPoolName'' volume1 120G<br />
Vol volume1 created<br />
<br />
# virsh vol-list ''myPoolName''<br />
Name Path<br />
<br />
volume1 ''myMntPoint''/volume1<br />
<br />
# virsh vol-dumpxml --pool ''myPoolName'' volume1<br />
<--------><br />
info on volume1 in xml format <br />
<---------><br />
<br />
}}<br />
<br />
{{Note|<br />
* the {{ic|vol-create}} command will take a while<br />
* a new file volume1 for installing the VM on has been created in ''myMntPoint''<br />
* to ''delete'' a volume, use this command {{ic| virsh # vol-delete volume1 --pool ''myPoolName''}}<br />
}}<br />
<br />
===Installing a new VM===<br />
To create a new VM, you need some sort of installation media, which is usually a standard {{ic|.iso}} file. Copy it to the {{ic|/var/lib/libvirt/images/}} directory (alternatively, you can create a new ''storage pool'' directory in virt-manager and copy it there).<br />
<br />
{{Note|[[SELinux]] requires that virtual machines be stored in {{ic|/var/lib/libvirt/images/}} by default. If you use SELinux and are having issues with virtual machines, ensure that your VMs are in that directory or ensure that you have added the correct labeling to the non-default directory that you used.}}<br />
<br />
====using virt-manager====<br />
<br />
Then run {{ic|virt-manager}}, connect to the server, right click on the connection and choose '''New'''. Choose a name, and select '''Local install media'''. Just continue with the wizard.<br />
<br />
On the '''4th step''', you may want to uncheck ''Allocate entire disk now'' -- this way you will save space when your VM is not using all of its disk. However, this can cause increased fragmentation of the disk, and you ''must'' pay attention to the total available disk space on the VM host because it is much easier to over-allocate disk space to VMs.<br />
<br />
On the '''5th step''', open '''Advanced options''' and make sure that ''Virt Type'' is set to '''kvm'''.<br />
<br />
====using virt-install====<br />
The {{ic|$ virt-install}} command let you create the new VM with many arguments and sub options. For a complete list of arguments, please see [[http://linux.die.net/man/1/virt-install man virt-install]].<br />
<br />
The command will take this pattern:<br />
{{ic|$ virt-install --connect ''hypervisor'':///system [list of arguments and options]}}. <br />
{{Note| <br />
* {{ic|///session}} let you create/manage guests as a regular '''user'''. {{ic|///system}} create guests run by the system libvirtd instance.<br />
* ''hypervisor'' can of course be [[Qemu]], [[Xen]], [[Linux_Containers|lxc]].<br />
}}.<br />
<br />
Below is a basic command with most useful arguments. For clarification, the '''qemu''' hypervisor is used, the installed OS is '''windows8'''. <br />
{{bc|<nowiki> $ virt-install --connect qemu:///system \<br />
--name=myVMname \ # name of your VM<br />
--memory=2048 \ # ram you want to allocate<br />
--os-variant=win7 \ # type of os for the VM- win7 OR later<br />
--disk /path/to/myMntPoint/volume1 \ # point to the VM image<br />
--virt-type kvm \ # virtualization type<br />
--cdrom /dev/cdrom \ # use your guest cdrom <br />
--disk /path/to/iso/file,cdrom \ # path to guest .iso file. It will be on a cdrom device in the w8 guest and will be added as a storage pool.<br />
--controller scsi,model=virtio-scsi # use virtio<br />
</nowiki>}}<br />
<br />
{{Note|<br />
* the above command will create a {{ic|'''$XDG_CONFIG_HOME'''/libvirt/qemu/myVMname.xml}} file. This file can be edited later to more precised options.<br />
* the new VM is listed in '''virt-manager'''<br />
* As of 2014-08-20, the [http://www.spice-space.org/ spice protocol] does not provide windows binaries for w8. In case you really want this graphic protocol, you have to stick to w7 and add this line {{ic|--graphics spice}} to the {{ic|virt-install}} command.<br />
}}<br />
{{Tip| <br />
* it is possible to create a VM using an existing ''configuration_file.xml'' with the following command {{ic| $ visrh create ''configuration_file.xml''}}<br />
* most drivers and fine tuning sub options can be modified/added later when managing the VM. Best is to start with a basic install. For example, the above command will make the VM use the NAT network. If a more sophisticated network is wanted (like a bridge), do it later.}}<br />
<br />
====Using VirtualBox with virt-manager====<br />
{{Merge|virtualbox|this section would fit better in virtualbox wiki}}<br />
{{Note|[[VirtualBox]] support in libvirt is not quite stable yet and may cause your libvirtd to crash. Usually this is harmless and everything will be back once you restart the daemon.}}<br />
<br />
virt-manager does not let you to add any VirtualBox connections from the GUI. However, you can launch it from the command line:<br />
virt-manager -c vbox:///system<br />
<br />
Or if you want to manage a remote system over SSH:<br />
<nowiki>virt-manager -c vbox+ssh://username@host/system</nowiki><br />
<br />
==Usage: management of a VM==<br />
=== Using virt-manager ===<br />
The usage is pretty straightforward. Start the '''Virtual Machine Manager''', then click on the desired listed machine. It will then open the VM windows. Under the ''View'' menu, select ''Details''. You will see a new window with everything needed to list/view/add/modify ''Hardware''.<br />
<br />
=== Using virsh ===<br />
==== Starting KVM virtual machines on boot up ====<br />
<br />
At the command line, to set a VM to automatically start at boot-up, run:<br />
<br />
$ virsh autostart <domain><br />
<br />
To disable automatic starting:<br />
<br />
$ virsh autostart --disable <domain><br />
<br />
''virt-manager'' is equally easy having an autostart check box in the boot options of the VM.<br />
<br />
{{Note|VMs started by QEMU or KVM from the command line are not then manageable by ''virt-manager''.}}<br />
====Stopping / resuming guest at host shutdown / startup ====<br />
Running guests may be suspended (or shutdown) at host shutdown automatically using the {{ic|libvirt-guests.service}} systemd service. This same daemon will resume (startup) the suspended (shutdown) guests automatically at host startup.<br />
Check {{ic|/etc/conf.d/libvirtd-guests}} for libvirt-guests options.<br />
<br />
==== Live snapshots ====<br />
A feature called external snapshotting allows one to take a live snapshot of a virtual machine without turning it off. Currently it only works with qcow2 and raw file based images.<br />
<br />
Once a snapshot is created, KVM attaches that new snapshotted image to virtual machine that is used as its new block device, storing any new data directly to it while the original disk image is taken offline which you can easily copy or backup. After that you can merge the snapshotted image to the original image, again without shutting down your virtual machine.<br />
<br />
Here is how it works.<br />
<br />
Currently running virtual machines:<br />
{{hc|# virsh list|<nowiki><br />
Id Name State<br />
----------------------------------------------------<br />
3 archey running<br />
</nowiki>}}<br />
<br />
List all its current images:<br />
{{hc|# virsh domblklist archey|<nowiki><br />
Target Source<br />
------------------------------------------------<br />
vda /vms/archey.img<br />
</nowiki>}}<br />
<br />
Notice the image file properties<br />
{{hc|# qemu-img info /vms/archey.img|<nowiki><br />
image: /vms/archey.img<br />
file format: qcow2<br />
virtual size: 50G (53687091200 bytes)<br />
disk size: 2.1G<br />
cluster_size: 65536<br />
</nowiki>}}<br />
<br />
Create a disk-only snapshot. The switch {{ic|--atomic}} makes sure that the VM is not modified if snapshot creation fails.<br />
# virsh snapshot-create-as archey snapshot1 --disk-only --atomic<br />
<br />
List if you want to see the snapshots:<br />
{{hc|# virsh snapshot-list archey|<nowiki><br />
Name Creation Time State<br />
------------------------------------------------------------<br />
snapshot1 2012-10-21 17:12:57 -0700 disk-snapshot<br />
</nowiki>}}<br />
<br />
Notice the new snapshot image created by virsh and its image properties. It weighs just a few MiBs and is linked to its original "backing image/chain".<br />
{{hc|# qemu-img info /vms/archey.snapshot1|<nowiki><br />
image: /vms/archey.snapshot1<br />
file format: qcow2<br />
virtual size: 50G (53687091200 bytes)<br />
disk size: 18M<br />
cluster_size: 65536<br />
backing file: /vms/archey.img<br />
</nowiki>}}<br />
<br />
At this point, you can go ahead and copy the original image with {{ic|1=cp -sparse=true}} or {{ic|rsync -S}}. <br />
Then you can merge the original image back into the snapshot.<br />
# virsh blockpull --domain archey --path /vms/archey.snapshot1<br />
<br />
Now that you have pulled the blocks out of original image, the file {{ic|/vms/archey.snapshot1}} becomes the new disk image. Check its disk size to see what it means. After that is done, the original image {{ic|/vms/archey.img}} and the snapshot metadata can be deleted safely. The {{ic|virsh blockcommit}} would work opposite to {{ic|blockpull}} but it seems to be currently under development in qemu-kvm 1.3 (including snapshot-revert feature), scheduled to be released sometime next year.<br />
<br />
This new feature of KVM will certainly come handy to the people who like to take frequent live backups without risking corruption of the file system.<br />
<br />
==Remote access to libvirt==<br />
<br />
===Using unencrypted TCP/IP socket (most simple, least secure)===<br />
{{Warning|This should ''only'' be used for testing or use over a secure, private, and trusted network.}}<br />
<br />
Edit {{ic|/etc/libvirt/libvirtd.conf}}:<br />
{{hc|/etc/libvirt/libvirtd.conf|<nowiki><br />
listen_tls = 0<br />
listen_tcp = 1<br />
auth_tcp=none<br />
</nowiki>}}<br />
<br />
{{Warning|We do not enable SASL here, so all TCP traffic is cleartext! For real world use, ''always'' enable SASL.}}<br />
<br />
It is also necessary to start the server in listening mode by editing {{ic|/etc/conf.d/libvirtd}} <br />
{{hc|/etc/conf.d/libvirtd|2=LIBVIRTD_ARGS="--listen"}}<br />
<br />
===Using SSH===<br />
The {{Pkg|openbsd-netcat}} package is needed for remote management over [[SSH]].<br />
<br />
To connect to the remote system using {{ic|virsh}}:<br />
$ virsh -c qemu+ssh://''username''@''host''/system<br />
<br />
If something goes wrong, you can get some logs using:<br />
$ LIBVIRT_DEBUG=1 virsh -c qemu+ssh://''username''@''host''/system<br />
<br />
To display the graphical console for a virtual machine:<br />
$ virt-viewer --connect qemu+ssh://''username''@''host''/system myvirtualmachine<br />
<br />
To display the virtual machine desktop management tool:<br />
$ virt-manager -c qemu+ssh://''username''@''host''/system<br />
<br />
{{Note|If you are having problems connecting to a remote RHEL server (or anything other than Arch, really), try the two workarounds mentioned in {{bug|30748}} and {{bug|22068}}.}}<br />
<br />
=== Using Python ===<br />
The {{Pkg|libvirt-python}} package provides a {{Pkg|python2}} API in {{ic|/usr/lib/python2.7/site-packages/libvirt.py}}.<br />
<br />
General examples are given in {{ic|/usr/share/doc/libvirt-python-''your_libvirt_version''/examples/}}<br />
<br />
Unofficial example using {{Pkg|qemu}} and {{Pkg|openssh}}:<br />
<br />
#! /usr/bin/env python2<br />
# -*- coding: utf-8 -*-<br />
import socket<br />
import sys<br />
import libvirt<br />
if (__name__ == "__main__"):<br />
<nowiki>conn = libvirt.open("qemu+ssh://xxx/system")</nowiki><br />
print "Trying to find node on xxx"<br />
domains = conn.listDomainsID()<br />
for domainID in domains:<br />
domConnect = conn.lookupByID(domainID)<br />
if domConnect.name() == 'xxx-node':<br />
print "Found shared node on xxx with ID " + str(domainID)<br />
domServ = domConnect<br />
break<br />
<br />
== Bridged networking ==<br />
To use ''physical Ethernet'' from your virtual machines, you have to create a ''bridge'' between your physical Ethernet device (here ''eth0'') and the virtual Ethernet device the VM is using.<br />
<br />
=== Host configuration ===<br />
<br />
libvirt creates the bridge ''virbr0'' for NAT networking, so use another name such as ''br0'' or ''virbr1''.<br />
You have to create a new [[Netctl]] or [[Systemd-networkd]] profile to configure the bridge, for example (with DHCP configuration):<br />
<br />
{{hc|/etc/netctl/br0|<nowiki><br />
Description="Bridge connection for kvm"<br />
Interface=br0<br />
Connection=bridge<br />
BindsToInterfaces=(eno1)<br />
IP=dhcp<br />
</nowiki>}}<br />
<br />
{{out of date|The tip below needs to be updated for [[netctl]].}}<br />
{{Tip|It is recommended that you enable [[Wikipedia:Spanning_Tree_Protocol|Spanning Tree Protocol]] (STP) on the virtual bridge (e.g. ''br0'') that you create to avoid any potential bridging loops. You can automatically enable STP by appending {{ic|1=POST_UP="brctl stp $INTERFACE on"}} to the netcfg profile.}}<br />
<br />
=== Guest configuration ===<br />
<br />
Now we have to activate the ''bridge interface'' in our ''VMs''.<br />
If have a recent Linux machine, you can use this code in the ''.xml'' file:<br />
<br />
[...]<br />
<interface type='bridge'><br />
<source bridge='br0'/><br />
<mac address='24:42:53:21:52:49'/><br />
<model type='virtio' /><br />
</interface><br />
[...]<br />
<br />
This code activates a ''virtio'' device on the machine so, in Windows you will have to install an additional driver (you can find it in the AUR package {{aur|virtio-win}} or with [http://www.spice-space.org/download/binaries/ Spice Guest Tools] that includes desktop enhancements like video driver and display resize support) or remove the line {{ic|<model type<nowiki>=</nowiki>'virtio' />}}:<br />
<br />
[...]<br />
<interface type='bridge'><br />
<source bridge='br0'/><br />
<mac address='24:42:53:21:52:49'/><br />
</interface><br />
[...]<br />
<br />
== See also ==<br />
<br />
* [http://libvirt.org/drvqemu.html libvirt web site]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Tuning_and_Optimization_Guide/index.html Virtualization Tuning and Optimization Guide]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Deployment_and_Administration_Guide/sect-KVM_Para_virtualized_virtio_Drivers-Installing_the_drivers_on_an_installed_Windows_guest_virtual_machine.html Installing the drivers on an installed Windows guest virtual machine]<br />
* [http://www-01.ibm.com/support/knowledgecenter/linuxonibm/liaat/liaatkvm.htm IBM KVM]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Deployment_and_Administration_Guide/index.html Red Hat Enterprise Linux 7 Virtualization Deployment and Administration Guide]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Media_Transfer_Protocol&diff=344209Media Transfer Protocol2014-11-10T20:23:41Z<p>Jstjohn: /* Installation */ Nautilus is now GNOME Files</p>
<hr />
<div>[[Category:Sound]]<br />
[[ja:MTP]]<br />
[[zh-CN:MTP]]<br />
MTP is the "Media Transfer Protocol" and is used by many mp3 players (e.g. Creative Zen) and mobile phones (e.g. Android 3+ devices). It is part of the "Windows Media" Framework and has close relationship with Windows Media Player.<br />
<br />
== Installation ==<br />
<br />
MTP support is provided by [http://libmtp.sourceforge.net/ libmtp], [[pacman|installable]] with the {{Pkg|libmtp}} package from the [[official repositories]].<br />
<br />
To view the contents of your Android device's storage via MTP on your file manager, install corresponding plugin:<br />
<br />
* For file managers that use [[GVFS]] ([[GNOME Files]], Xfce's [[Thunar]]), install {{Pkg|gvfs-mtp}} for MTP or {{Pkg|gvfs-gphoto2}} for PTP support.<br />
* For file managers that use KIO (KDE's Dolphin), install {{Pkg|kio-mtp}} (PTP support is included by default).<br />
<br />
{{Note|If you have an Android device that does not support UMS and you find {{Pkg|mtpfs}} extremely slow or not working properly, you can install {{AUR|jmtpfs}} from the AUR.}}<br />
<br />
== Usage ==<br />
<br />
{{Note|Don't forget to unlock your phone (screen unlock) before connecting, otherwise you will get error messages.}}<br />
After installation, you have several MTP tools available.<br />
Upon connecting your MTP device, you use:<br />
# mtp-detect<br />
to see if your MTP device is detected. If you get errors about permission, remember that you need to be in the uucp group to access the USB system in general.<br />
<br />
To connect to your MTP device, you use:<br />
# mtp-connect<br />
<br />
If connection is successful, there are several switch options to use in conjunction with {{ic|mtp-connect}} to access data on the device.<br />
<br />
There are also several stand alone commands you can use to access your MTP device such as,<br />
{{Warning | Some commands may be harmful to your MTP device!!! }}<br />
<br />
mtp-albumart mtp-emptyfolders mtp-getplaylist mtp-reset mtp-trexist<br />
mtp-albums mtp-files mtp-hotplug mtp-sendfile<br />
mtp-connect mtp-folders mtp-newfolder mtp-sendtr<br />
mtp-delfile mtp-format mtp-newplaylist mtp-thumb<br />
mtp-detect mtp-getfile mtp-playlists mtp-tracks<br />
<br />
If you see a message like:<br />
<br />
Device 0 (VID=XXXX and PID=XXXX) is UNKNOWN.<br />
Please report this VID/PID and the device model to the libmtp development team<br />
<br />
You should check whether your device has been already in this list: [Supported devices list[http://sourceforge.net/p/libmtp/code/ci/HEAD/tree/src/music-players.h]]<br />
If it is not, you should report it to the development team. If it already is, your libmtp might be slightly outdated. To allow it to be properly used by libmtp, you can add your device to:<br />
/usr/lib/udev/rules.d/69-libmtp.rules<br />
<br />
== Using media players ==<br />
<br />
You can also use your MTP device in music players such as Amarok. To do this you may have to edit {{ic|/usr/lib/udev/rules.d/51-android.rules}} (the MTP device used in the following example is a Galaxy Nexus):<br />
To do this run:<br />
$ lsusb<br />
and look for your device, it will be something like:<br />
Bus 003 Device 011: ID 04e8:6860 Samsung Electronics Co., Ltd GT-I9100 Phone [Galaxy S II], GT-P7500 [Galaxy Tab 10.1]<br />
in which case the entry would be:<br />
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0666", OWNER="[username]"<br />
Then, reload udev rules:<br />
# udevadm control --reload<br />
<br />
{{Note|After installing MTP you may have to reboot for your device to be recognised}}<br />
<br />
== mtpfs ==<br />
<br />
{{Warning | The following is likely to not work and you might have to resort to [[Digital_Cameras#libgphoto2|gphoto2]] or a file manager with gvfs support like [[PCManFM]]. }}<br />
<br />
Mtpfs is FUSE filesystem that supports reading and writing from any MTP device. Basically it allows you to mount your device as an external drive.<br />
<br />
Mtpfs can be installed with the packge {{Pkg|mtpfs}}, available from the [[official repositories]].<br />
* First edit your {{ic|/etc/fuse.conf}} and uncomment the following line:<br />
user_allow_other<br />
<br />
* To mount your device <br />
$ mtpfs -o allow_other /media/YOURMOUNTPOINT<br />
* To unmount your device<br />
$ fusermount -u /media/YOURMOUNTPOINT<br />
* To unmount your device as root<br />
# umount /media/YOURMOUNTPOINT<br />
<br />
Also, you can put them into your ~/.bashrc:<br />
alias android-connect="mtpfs -o allow_other /media/YOURMOUNTPOINT"<br />
alias android-disconnect="fusermount -u /media/YOURMOUNTPOINT"<br />
Or, with sudo <br />
alias android-disconnect="sudo umount -u /media/YOURMOUNTPOINT"<br />
{{Note|if you want not be asked for password when using sudo, please refer to [[USB storage devices]]}}<br />
<br />
== jmtpfs ==<br />
<br />
[http://research.jacquette.com/jmtpfs-exchanging-files-between-android-devices-and-linux/ jmtpfs] is a FUSE and libmtp based filesystem for accessing MTP (Media Transfer Protocol) devices. It was specifically designed for exchanging files between Linux systems and newer Android devices that support MTP but not USB Mass Storage.<br />
jmtpfs is available as {{AUR|jmtpfs}} in the [[AUR]].<br />
<br />
Use this commands to mount your device:<br />
$ jmtpfs ~/mtp<br />
<br />
And this command to unmount it:<br />
$ fusermount -u ~/mtp<br />
<br />
== go-mtpfs ==<br />
<br />
{{Note|Go-mtpfs gives a better performance while writing files to some devices than mtpfs/jmtpfs. Try it if you have slow speeds.}}<br />
{{Note|Mounting with Go-mtpfs fails if external SD Card is present. If you have also external SD Card please remove it and then try mounting again.}}<br />
<br />
If the above instructions do not show any positive results one should try {{AUR|go-mtpfs-git}} from the [[AUR]].<br />
The following has been tested on a Samsung Galaxy Nexus GSM, Asus/Google Nexus 7 (2012 1st gen model), Samsung Galaxy S 3 mini and Google Nexus 4. (This is the only mtp software which worked for me on Nexus 4. Settings are usb debugging enabled, connected as media device.)<br />
<br />
If you want do it simpler, install {{Pkg|go}}, {{Pkg|libmtp}} and {{Pkg|git}} from the [[official repositories]]. After that install {{AUR|go-mtpfs-git}} from the [[AUR]].<br />
<br />
As in the section above install {{Pkg|android-udev}} which will provide you with "/usr/lib/udev/rules.d/51-android.rules" edit it to apply to <br />
your vendorID and productID, which you can see after running mtp-detect. To the end of the line add with a comma OWNER="yourusername". Save the file.<br />
<br />
* Add yourself to the "fuse" group:<br />
gpasswd -a [user] fuse<br />
<br />
* If the group "fuse" does not exist create it with:<br />
groupadd fuse<br />
<br />
Logout or reboot to apply these changes. <br />
<br />
* To create a mount point called "Android" issue the following commands:<br />
mkdir Android<br />
<br />
* To mount your phone use:<br />
go-mtpfs Android<br />
<br />
* To unmount your phone:<br />
fusermount -u Android<br />
<br />
You can create a .bashrc alias as in the example above for easier use.<br />
<br />
== gvfs-mtp ==<br />
<br />
Philip Langdale implemented native MTP support for gvfs. The weaknesses of gphoto2 and mtpfs are listed in his [http://intr.overt.org/blog/?p=153 blog post]. The native mtp implementation for gvfs [https://bugzilla.gnome.org/show_bug.cgi?id=666195 has been merged upstream] and has been released in gvfs [http://git.gnome.org/browse/gvfs/commit/?id=d6c8e3a4910ee2c5968886328ebe9456b445796b 1.15.2]. <br />
<br />
You can grab the stable {{Pkg|gvfs-mtp}} package from extra. You may want to reboot your PC to make it actually working. Devices will have gvfs paths like this<br />
<br />
gvfs-ls mtp://[usb:002,013]/<br />
<br />
{{Merge|udev}}<br />
<br />
{{Note| If only installing gvfs-mtp doesn't work, you need to write a udev rule in order to auto-mount the device.}}<br />
<br />
Plug your device and get the vendor-id and product-id,respectively:<br />
<br />
$ lsusb<br />
Bus 001 Device 007: ID 0421:0661 Nokia Mobile Phones Lumia 920<br />
(...)<br />
<br />
The two numbers after ID are ''vendorId'' : ''productID''<br />
<br />
Then make a udev rule, e.g.<br />
<br />
# nano /usr/lib/udev/rules.d/51-android.rules<br />
<br />
and type this rule:<br />
<br />
ATTR{idVendor}=="YOUR VENDOR ID HERE", ATTR{idProduct}=="YOUR PRODUCT ID HERE", SYMLINK+="libmtp", MODE="660", ENV{ID_MTP_DEVICE}="1"<br />
<br />
Reload the udev rules.<br />
<br />
# udevadm control --reload<br />
<br />
And reboot the system. Now File Managers(like Thunar) should be able to automount the MTP Device. [https://bbs.archlinux.org/viewtopic.php?id=180719].<br />
<br />
== simple-mtpfs ==<br />
<br />
This is another FUSE filesystem for MTP devices. You may find this to be more reliable than {{Pkg|mtpfs}}. {{AUR|simple-mtpfs}} is available in the AUR or can be built from source. Do not run the following commands as root.<br />
<br />
To list MTP devices run<br />
<br />
$ simple-mtpfs --list-devices<br />
<br />
To mount a MTP devices (in this example device 0) run<br />
<br />
$ simple-mtpfs /path/to/your/mount/point<br />
<br />
To un mount run<br />
<br />
$ fusermount -u /path/to/your/mount/point<br />
<br />
== KDE MTP KIO Slave ==<br />
<br />
There is a MTP KIO Slave built upon libmtp availiable as package {{Pkg|kio-mtp}}. <br />
<br />
Using KIO makes file access in KDE seamless, in principle any KDE application would be able read/write files on the device.<br />
<br />
=== Usage ===<br />
<br />
The device will be available under the path mtp:/<br />
<br />
=== Workaround if the KDE device actions does not work ===<br />
<br />
If you are not able to use the action "Open with File Manager", you may work around this problem by editing the file /usr/share/apps/solid/actions/solid_mtp.desktop<br />
<br />
Change the line<br />
Exec=kioclient exec mtp:udi=%i/<br />
To<br />
Exec=dolphin "mtp:/"<br />
<br />
== GNOME gMTP ==<br />
<br />
gMTP is a native Gnome application used for MTP access.<br />
<br />
{{AUR|gmtp}} is currently located in the [[AUR]] .<br />
<br />
== Workarounds for Android ==<br />
<br />
=== AirDroid ===<br />
<br />
AirDroid is an Android app to access files from your web browser.<br />
<br />
=== FTP ===<br />
<br />
You run a local FTP server on Arch and connect to it from your phone. There are many FTP clients available for Android.<br />
<br />
Alternatively you can run FTP Server on your phone and connect to it from Arch.<br />
<br />
See [[List of applications/Internet#FTP]].<br />
<br />
=== SSH Server ===<br />
<br />
There are many SSH servers available for Android, it allows you to transfer files using {{ic|scp}} command. See also [[SSH]].<br />
<br />
=== Samba ===<br />
<br />
See [[Samba]]. Might require ROOT access on your phone.<br />
<br />
=== ADB ===<br />
<br />
ADB (Android Debug Bridge) is a part of the Android SDK. Install {{Aur|android-sdk-platform-tools}} from [[AUR]]. It can be used to push and pull files from your device. See [[Android#Connecting to a real device - Android Debug Bridge (ADB)]].<br />
<br />
* To push a file to the device use<br />
$ adb push ''<what-to-copy>'' ''<where-to-place>''<br />
<br />
* To pull a file<br />
$ adb pull ''<what-to-pull>'' ''<where-to-place>''<br />
<br />
=== Microsoft Windows on VirtualBox ===<br />
<br />
For this you need to [[Pacman|install]] {{Pkg|virtualbox}} from official repositories and {{Aur|virtualbox-ext-oracle}} from [[AUR]] on your host. Then install VirtualBox Guest Additions on your guest OS. After that go to your ''VM Settings -> USB'' and turn on ''Enable USB Controller''.<br />
<br />
Now you are able to pass your MTP device to Windows on your virtual machine through ''Devices -> USB Devices''. Don't forget to set a shared directory for VM too.<br />
<br />
See [[VirtualBox]].</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=AUR_Metadata&diff=341117AUR Metadata2014-10-22T07:34:15Z<p>Jstjohn: /* Working with makepkg --source */ remove bad information about including .AURINFO in the "source" array. just use "mkaurball" instead... that's why it is there.</p>
<hr />
<div>[[Category:Package development]]<br />
[[ja:AUR Metadata]]<br />
{{Related articles start}}<br />
{{Related|Arch User Repository}}<br />
{{Related|PKGBUILD}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related articles end}}<br />
{{Stub}}<br />
In order to display information in the [[AUR]] web interface, the AUR's back-end code attempts to parse [[PKGBUILD]] files and salvage package name, version, and other information from it. {{ic|PKGBUILD}}s are [[Bash]] scripts, and correctly parsing Bash scripts without executing them is a huge challenge, which is why [[makepkg]] is a Bash script itself: it includes the PKGBUILD of the package being built via the {{ic|source}} directive. AUR metadata files were created to get rid of some hacks, used by AUR package maintainers to work around incorrect parsing in the web interface. See also {{Bug|25210}}, {{Bug|15043}}, and {{Bug|16394}}.<br />
<br />
== How it works ==<br />
By adding a metadata file called ".AURINFO" to source tarballs to overwrite specific PKGBUILD fields. The format of this file is described in the [https://mailman.archlinux.org/pipermail/aur-dev/2013-March/002428.html AUR 2.1.0 release announcement]. {{ic|.AURINFO}} files are parsed line-by-line. The syntax for each line is {{ic|1=key = value}} (yes, spaces around = are important, and do not include quotes around the values), where {{ic|key}} is any of the following field names:<br />
<br />
* pkgbase: This is required by AUR 3, otherwise the infamous “only lowercase letters are allowed” error is reported. (Pacman uses the first ''pkgname'' if ''pkgbase'' is omitted.) Repeat pkgname if unsure.<br />
* pkgname<br />
* pkgver: package version, formatted as [''epoch'':]''pkgver''<br />
* pkgrel: release number of the package specific to Arch Linux<br />
* pkgdesc<br />
* url<br />
* license: in case of multiple licenses separate them by a space<br />
* depends: dependencies, one per line<br />
<br />
Fields with other names are ignored. Multiple {{ic|depends}} lines can be specified to add multiple dependencies. This format closely matches the {{ic|.PKGINFO}} format that is used for binary packages in [[pacman|pacman/libalpm]]. It can be extended by field name prefixes or sections to support split packages later.<br />
<br />
== Working with makepkg --source ==<br />
Note that {{ic|makepkg --source}} will not automatically include an .AURINFO file in the source tarball. To include the .AURINFO file in the source tarball, use {{ic|mkaurball}} from the package {{Pkg|pkgbuild-introspection}} instead of {{ic|makepkg --source}}.<br />
<br />
== What does not work ==<br />
* Multiple architectures ({{ic|x86_64}} dependencies tend to be more numerous, so just put them)<br />
<br />
== pkgbuild-introspection and mkaurball ==<br />
[https://github.com/falconindy/pkgbuild-introspection pkgbuild-introspection] is a set of tools for generating {{ic|.AURINFO}} files. One of the provided tools is {{ic|mkaurball}}, which is a script that runs {{ic|makepkg --source}}, generates an {{ic|.AURINFO}} file, and inserts it into the resulting source package.<br />
<br />
{{Tip|{{ic|mkaurball}} is a wrapper for {{ic|makepkg --source}}. When creating source packages for inclusion in the [[AUR]], use {{ic|mkaurball}} instead of running {{ic|makepkg --source}} directly.}}<br />
<br />
[[pacman|Install]] the package {{Pkg|pkgbuild-introspection}} from the [[official repositories]].<br />
<br />
== See also ==<br />
* https://mailman.archlinux.org/pipermail/aur-general/2014-January/026720.html<br />
* https://projects.archlinux.org/aur.git/tree/web/html/pkgsubmit.php, the code that reads the “.AURINFO” file.</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Libvirt&diff=340970Libvirt2014-10-21T04:24:41Z<p>Jstjohn: /* See also */ update link for RHEL 6 VM admin guide to the RHEL 7 version</p>
<hr />
<div>{{DISPLAYTITLE:libvirt}}<br />
[[Category:Virtualization]]<br />
[[ja:libvirt]]<br />
[[zh-CN:libvirt]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related articles end}}<br />
libvirt is a virtualization API and a daemon for managing virtual machines (VMs) -- remote or locally, using multiple virtualization back-ends ([[QEMU]]/[[KVM]], [[VirtualBox]], [[Xen]], etc), communally called ''hypervisors'' . <br />
== Installing ==<br />
<br />
On the server, [[pacman|install]] at least {{Pkg|libvirt}} '''and''' a virtualization back-end such as [[QEMU]]. Then depending on the use case:<br />
* If network connectivity within the virtual machine is desired (which is most likely to be the case), install either both {{Pkg|ebtables}} and {{Pkg|dnsmasq}} for the default NAT/DHCP networking, {{Pkg|bridge-utils}} for bridged networking or the three of them to cover every method.<br />
* If remote management over [[SSH]] is desired, install {{Pkg|openbsd-netcat}}.<br />
<br />
On the client:<br />
* If planning on using only the command line, install the {{Pkg|libvirt}} package which provides the [http://wiki.libvirt.org/page/FAQ#What_is_the_.27virsh_edit.27_command_and_how_do_I_use_it.3F recommended] {{ic|virsh}} utility.<br />
* If wishing to use a graphical application, install {{Pkg|virt-manager}} and {{Pkg|virtviewer}}.<br />
<br />
{{Note|The server and client can be the same physical machine. Many more applications using ''libvirt'''s API may be found on [http://libvirt.org/apps.html libvirt's official website].}}<br />
<br />
===Building libvirt for Xen===<br />
The [[PKGBUILD]] for both {{AUR|libvirt-git}} in the [[Arch User Repository|AUR]] and {{Pkg|libvirt}} in the [[official repositories]] currently disables [[Xen]] support with the {{ic|--without-xen}} flag during the make process. If you want to use libvirt for managing Xen, you will need to [https://projects.archlinux.org/svntogit/community.git/tree/libvirt/repos/community-x86_64/ grab the whole file set] to enable Xen support and build your own libvirt package using the [[Arch Build System]]. The {{AUR|xen}} package from the [[AUR]] is required to build libvirt with Xen support.<br />
<br />
The alternative XenAPI driver is lacking a package at the moment? (2010-05-23, friesoft)<br />
<br />
==Server configuration==<br />
<br />
Libvirt is not usable "out of the box". At a minimum, you must [[#Run daemon|run the daemon]] and [[#Authorization|configure authorization]]. It is also advisable to [[#Enable KVM acceleration for QEMU]].<br />
Main configuration folders are found in {{ic|/etc/libvirt}}. Lots of files are in a '''.xml''' format.<br />
<br />
===Run daemon===<br />
<br />
{{Accuracy|The following section contains contradictory information concerning which group should be set in {{ic|/etc/libvirt/qemu.conf}}: {{ic|kvm}} is listed in the [[Users_and_groups#Deprecated_or_unused_groups|deprecated or unused groups]] section of the wiki, and why should one create a {{ic|qemu}} group when immediately after it is asked to create a {{ic|libvirt}} group?}}<br />
<br />
Change default user and group in {{ic|/etc/libvirt/qemu.conf}} to {{ic|qemu:qemu}}, as QEMU defaults to {{ic|nobody:kvm}}. You will need to [[Users_and_groups|change]] to the {{ic|qemu}} user and {{ic|kvm}} group. Omitting to change to the KVM group will leave you when running {{ic|virt-install --connect qemu:///system }} with this error: <br />
{{bc|Starting install...<br />
ERROR internal error: process exited while connecting to monitor:<br />
Could not access KVM kernel module: Permission denied<br />
failed to initialize KVM: Permission denied}}<br />
<br />
<br />
Then, [[File_Permissions_and_Attributes#Changing ownership using the chown command|set ownership]] of the following directories {{ic|/var/run/libvirt/qemu/}}, {{ic|/var/lib/libvirt/qemu/}}, {{ic|/var/lib/libvirt/images/}} and {{ic|/var/cache/libvirt/qemu/}} to match the user:group ID that QEMU guests will be run as.<br />
<br />
Start/enable {{ic|libvirtd.service}} [[Systemd#Using units|using systemd]].<br />
<br />
{{Note|The Avahi daemon is used for local discovery of libvirt hosts via multicast-DNS. To disable this functionality, set {{ic|1=mdns_adv = 0}} in {{ic|/etc/libvirt/libvirtd.conf}}.}}<br />
<br />
===Authorization===<br />
<br />
First, you will need to create the ''libvirt'' [[Users and groups|group]] and add any users you want to have access to libvirt to that group.<br />
# groupadd libvirt<br />
# gpasswd -a ''user'' libvirt<br />
<br />
Any users that are currently logged in will need to log out and log back in to update their groups. Alternatively, the user can use the following command in the shell they will be launching libvirt from to update the group:<br />
$ newgrp libvirt<br />
<br />
Then you have to follow either [[#polkit authorization]] '''or''' [[#file-based permissions]]:<br />
<br />
====polkit authorization====<br />
To allow users that are in the ''libvirt'' group to manage virtual machines, you need to create the following file:<br />
<br />
{{hc|/etc/polkit-1/rules.d/50-org.libvirt.unix.manage.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.libvirt.unix.manage" &&<br />
subject.isInGroup("libvirt")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
</nowiki>}}<br />
<br />
Alternatively, you can grant only monitoring privileges with {{ic|org.libvirt.unix.monitor}}.<br />
<br />
For more information, see [http://wiki.libvirt.org/page/SSHPolicyKitSetup#Configuring_management_access_via_PolicyKit the libvirt wiki].<br />
<br />
====file-based permissions====<br />
To allow users that are in the ''libvirt'' group to manage virtual machines, you can uncomment the following lines (they are not all in the same location in the file):<br />
<br />
{{hc|/etc/libvirt/libvirtd.conf|<nowiki><br />
#unix_sock_group = "libvirt"<br />
#unix_sock_ro_perms = "0777"<br />
#unix_sock_rw_perms = "0770"<br />
#auth_unix_ro = "none"<br />
#auth_unix_rw = "none"<br />
</nowiki>}}<br />
<br />
{{Note|You may also wish to change {{ic|unix_sock_ro_perms}} from {{ic|0777}} to {{ic|0770}} to disallow read-only access to people who are not members of the ''libvirt'' group.}}<br />
<br />
===Enable KVM acceleration for QEMU===<br />
{{Merge|kvm|this section would fit better in the [[Qemu]] or [[kvm]] wiki. It has nothing to do with libvirt}}<br />
{{Note|[[KVM]] will conflict with [[VirtualBox]]. You cannot use KVM and VirtualBox at the same time.}}<br />
<br />
Running virtual machines with the usual [[QEMU]] emulation (i.e. without KVM), will be '''painfully slow'''. You definitely want to enable KVM support if your CPU supports it. To find out, run the following command:<br />
$ egrep --color "vmx|svm" /proc/cpuinfo<br />
<br />
If that command generates output, then your CPU supports hardware acceleration via KVM; if that command does ''not'' generate output, then you ''cannot use KVM''.<br />
<br />
If KVM is ''not'' working, you will find the following message in your {{ic|/var/log/libvirt/qemu/VIRTNAME.log}}:<br />
{{hc|/var/log/libvirt/qemu/VIRTNAME.log|<br />
Could not initialize KVM, will disable KVM support<br />
}}<br />
<br />
More info is available from the [http://www.linux-kvm.org/page/FAQ official KVM FAQ]<br />
<br />
==Usage: creation of a new VM==<br />
Libvirt management is mostly done with three tools : one GUI, '''virt-manager''', and two CLI commands: '''virsh''' (part of libvirt) and '''guestfish''' (part of [https://aur.archlinux.org/packages/libguestfs/libguestfs libguestfs]) . Both tools let you create and then manage your VM.<br />
{{tip|basic virsh usages<br />
* {{ic|$ virsh [options]...<command> [args...]}} run a virsch command from your shell <br />
{{hc|$ virsh #launch an interactive virsh session|# virsh }} <br />
* {{ic|$ virsh list}} show ''running'' domains (pool-list lists ''active'' pools)<br />
* {{ic|$ virsh list --all}} list ''all'' domains ((pool-list --all lists ''all'' pools)<br />
}}<br />
{{Note|the virsh command is run as a regular user. This user shall belongs to the ''libvirt'' group.}}<br />
===Creating a storage pool===<br />
A ''storage pool'' is a quantity of storage for use by virtual machines. Storage pools are often divided into storage volumes and the volumes are assigned to guest virtual machines as block devices. The pool can be:<br />
* a directory pool<br />
* a filesystem pool<br />
* a network filesystem pool<br />
* a logical volume pool<br />
<br />
====using virt-manager====<br />
<br />
First, connect to an existing server. Once you are there, right click and choose '''Details'''. Go to '''Storage''' and press the '''+''' icon at the lower left. Then just follow the wizard.<br />
<br />
====using virsh====<br />
Add a [[lvm|logical volume]] pool when assuming there is already a '''vg0/''myStoragePool''''' LVM volume with some free space on it, as shown by the command output below.<br />
{{hc|# vgs|<br />
VG #PV #LV #SN Attr VSize VFree<br />
vg0 1 6 0 wz--n- 1.5t 150G<br />
}}<br />
We want now use the free space as a storage pool on a virsh interactive session.<br />
{{bc|# virsh<br />
<br />
virsh # pool-define-as ''myPoolName'' fs - - /dev/vg0/''myStoragePool'' - "''myMntPoint''"<br />
Pool ''myPoolName'' defined<br />
<br />
virsh# pool-build ''myPoolName''<br />
Pool ''myPoolName'' built<br />
<br />
virsh # pool-start ''myPoolName''<br />
Pool ''myPoolName'' started<br />
<br />
virsh # pool-list --all<br />
Name State Autostart<br />
<br />
default active yes<br />
''myPoolName'' active no<br />
<br />
virsh # pool-autostart ''myPoolName''<br />
Pool ''myPoolName'' marked as autostarted<br />
<br />
virsh # pool-info ''myPoolName''<br />
Name: ''myPoolName''<br />
UUID: 71dcb73a-6af9-4595-8208-a1c83e1ec6c7<br />
State: running<br />
Persistent: yes<br />
Autostart: yes<br />
Capacity: 1.5 t<br />
Allocation: 1 t<br />
Available: 150G<br />
<br />
virsh # quit<br />
}}<br />
<br />
{{Note|<br />
* libvirt will in fact change the ''myPoolName'' to ''myMntPoint''. When lisitng pools, the name will thus be ''myMntPoint''<br />
* a new ''myPoolName''.xml file has been created in {{ic|/etc/libvirt/storage}}<br />
* a new mountpoint ''myMntPoint'' directory is created<br />
* you can remove the default pool with the command {{ic|$ virsh pool-undefine default}}<br />
* the LVM volume vg0/''myStoragePool'' will be automatically mounted on the defined ''myMntPoint'' when VM is starting. No need to deal with it in your {{ic|/etc/fstab}}<br />
}}<br />
{{Tip|<br />
* Best practice is to dedicate a volume group to your storage pool only. Storage pool will be auto-started and could either contains volume you do not want to mount<br />
* Do not use your LVM volume group as your pool name, otherwise when deleting the pool storage you will delete your LVM group too<br />
}}<br />
<br />
===Creating a storage volume===<br />
Once the pool has been created, volumes for each VM can be created inside the pool.<br />
<br />
====Using virsh====<br />
{{bc|# virsh<br />
<br />
virsh # vol-create-as ''myPoolName'' volume1 120G<br />
Vol volume1 created<br />
<br />
# virsh vol-list ''myPoolName''<br />
Name Path<br />
<br />
volume1 ''myMntPoint''/volume1<br />
<br />
# virsh vol-dumpxml --pool ''myPoolName'' volume1<br />
<--------><br />
info on volume1 in xml format <br />
<---------><br />
<br />
}}<br />
<br />
{{Note|<br />
* the {{ic|vol-create}} command will take a while<br />
* a new file volume1 for installing the VM on has been created in ''myMntPoint''<br />
* to ''delete'' a volume, use this command {{ic| virsh # vol-delete volume1 --pool ''myPoolName''}}<br />
}}<br />
<br />
===Installing a new VM===<br />
To create a new VM, you need some sort of installation media, which is usually a standard {{ic|.iso}} file. Copy it to the {{ic|/var/lib/libvirt/images/}} directory (alternatively, you can create a new ''storage pool'' directory in virt-manager and copy it there).<br />
<br />
{{Note|[[SELinux]] requires that virtual machines be stored in {{ic|/var/lib/libvirt/images/}} by default. If you use SELinux and are having issues with virtual machines, ensure that your VMs are in that directory or ensure that you have added the correct labeling to the non-default directory that you used.}}<br />
<br />
====using virt-manager====<br />
<br />
Then run {{ic|virt-manager}}, connect to the server, right click on the connection and choose '''New'''. Choose a name, and select '''Local install media'''. Just continue with the wizard.<br />
<br />
On the '''4th step''', you may want to uncheck ''Allocate entire disk now'' -- this way you will save space when your VM is not using all of its disk. However, this can cause increased fragmentation of the disk, and you ''must'' pay attention to the total available disk space on the VM host because it is much easier to over-allocate disk space to VMs.<br />
<br />
On the '''5th step''', open '''Advanced options''' and make sure that ''Virt Type'' is set to '''kvm'''. If the kvm choice is not available, see section [[#Enable KVM acceleration for QEMU|Enable KVM acceleration for QEMU]] above.<br />
<br />
====using virt-install====<br />
The {{ic|$ virt-install}} command let you create the new VM with many arguments and sub options. For a complete list of arguments, please see [[http://linux.die.net/man/1/virt-install man virt-install]].<br />
<br />
The command will take this pattern:<br />
{{ic|$ virt-install --connect ''hypervisor'':///system [list of arguments and options]}}. <br />
{{Note| <br />
* {{ic|///session}} let you create/manage guests as a regular '''user'''. {{ic|///system}} create guests run by the system libvirtd instance.<br />
* ''hypervisor'' can of course be [[Qemu]], [[Xen]], [[Linux_Containers|lxc]].<br />
}}.<br />
<br />
Below is a basic command with most useful arguments. For clarification, the '''qemu''' hypervisor is used, the installed OS is '''windows8'''. <br />
{{bc|<nowiki> $ virt-install --connect qemu:///system \<br />
--name=myVMname \ # name of your VM<br />
--memory=2048 \ # ram you want to allocate<br />
--os-variant=win7 \ # type of os for the VM- win7 OR later<br />
--disk /path/to/myMntPoint/volume1 \ # point to the VM image<br />
--virt-type kvm \ # virtualization type<br />
--cdrom /dev/cdrom \ # use your guest cdrom <br />
--disk /path/to/iso/file,cdrom \ # path to guest .iso file. It will be on a cdrom device in the w8 guest and will be added as a storage pool.<br />
--controller scsi,model=virtio-scsi # use virtio<br />
</nowiki>}}<br />
<br />
{{Note|<br />
* the above command will create a {{ic|'''$XDG_CONFIG_HOME'''/libvirt/qemu/myVMname.xml}} file. This file can be edited later to more precised options.<br />
* the new VM is listed in '''virt-manager'''<br />
* As of 2014-08-20, the [http://www.spice-space.org/ spice protocol] does not provide windows binaries for w8. In case you really want this graphic protocol, you have to stick to w7 and add this line {{ic|--graphics spice}} to the {{ic|virt-install}} command.<br />
}}<br />
{{Tip| <br />
* it is possible to create a VM using an existing ''configuration_file.xml'' with the following command {{ic| $ visrh create ''configuration_file.xml''}}<br />
* most drivers and fine tuning sub options can be modified/added later when managing the VM. Best is to start with a basic install. For example, the above command will make the VM use the NAT network. If a more sophisticated network is wanted (like a bridge), do it later.}}<br />
<br />
====Using VirtualBox with virt-manager====<br />
{{Merge|virtualbox|this section would fit better in virtualbox wiki}}<br />
{{Note|[[VirtualBox]] support in libvirt is not quite stable yet and may cause your libvirtd to crash. Usually this is harmless and everything will be back once you restart the daemon.}}<br />
<br />
virt-manager does not let you to add any VirtualBox connections from the GUI. However, you can launch it from the command line:<br />
virt-manager -c vbox:///system<br />
<br />
Or if you want to manage a remote system over SSH:<br />
<nowiki>virt-manager -c vbox+ssh://username@host/system</nowiki><br />
<br />
==Usage: management of a VM==<br />
=== Using virt-manager ===<br />
The usage is pretty straightforward. Start the '''Virtual Machine Manager''', then click on the desired listed machine. It will then open the VM windows. Under the ''View'' menu, select ''Details''. You will see a new window with everything needed to list/view/add/modify ''Hardware''.<br />
<br />
=== Using virsh ===<br />
==== Starting KVM virtual machines on boot up ====<br />
<br />
At the command line, to set a VM to automatically start at boot-up, run:<br />
<br />
$ virsh autostart <domain><br />
<br />
To disable automatic starting:<br />
<br />
$ virsh autostart --disable <domain><br />
<br />
''virt-manager'' is equally easy having an autostart check box in the boot options of the VM.<br />
<br />
{{Note|VMs started by QEMU or KVM from the command line are not then manageable by ''virt-manager''.}}<br />
====Stopping / resuming guest at host shutdown / startup ====<br />
Running guests may be suspended (or shutdown) at host shutdown automatically using the {{ic|libvirt-guests.service}} systemd service. This same daemon will resume (startup) the suspended (shutdown) guests automatically at host startup.<br />
Check {{ic|/etc/conf.d/libvirtd-guests}} for libvirt-guests options.<br />
<br />
==== Live snapshots ====<br />
A feature called external snapshotting allows one to take a live snapshot of a virtual machine without turning it off. Currently it only works with qcow2 and raw file based images.<br />
<br />
Once a snapshot is created, KVM attaches that new snapshotted image to virtual machine that is used as its new block device, storing any new data directly to it while the original disk image is taken offline which you can easily copy or backup. After that you can merge the snapshotted image to the original image, again without shutting down your virtual machine.<br />
<br />
Here's how it works.<br />
<br />
Currently running virtual machines:<br />
{{hc|# virsh list|<nowiki><br />
Id Name State<br />
----------------------------------------------------<br />
3 archey running<br />
</nowiki>}}<br />
<br />
List all its current images:<br />
{{hc|# virsh domblklist archey|<nowiki><br />
Target Source<br />
------------------------------------------------<br />
vda /vms/archey.img<br />
</nowiki>}}<br />
<br />
Notice the image file properties<br />
{{hc|# qemu-img info /vms/archey.img|<nowiki><br />
image: /vms/archey.img<br />
file format: qcow2<br />
virtual size: 50G (53687091200 bytes)<br />
disk size: 2.1G<br />
cluster_size: 65536<br />
</nowiki>}}<br />
<br />
Create a disk-only snapshot. The switch {{ic|--atomic}} makes sure that the VM is not modified if snapshot creation fails.<br />
# virsh snapshot-create-as archey snapshot1 --disk-only --atomic<br />
<br />
List if you want to see the snapshots:<br />
{{hc|# virsh snapshot-list archey|<nowiki><br />
Name Creation Time State<br />
------------------------------------------------------------<br />
snapshot1 2012-10-21 17:12:57 -0700 disk-snapshot<br />
</nowiki>}}<br />
<br />
Notice the new snapshot image created by virsh and its image properties. It weighs just a few MiBs and is linked to its original "backing image/chain".<br />
{{hc|# qemu-img info /vms/archey.snapshot1|<nowiki><br />
image: /vms/archey.snapshot1<br />
file format: qcow2<br />
virtual size: 50G (53687091200 bytes)<br />
disk size: 18M<br />
cluster_size: 65536<br />
backing file: /vms/archey.img<br />
</nowiki>}}<br />
<br />
At this point, you can go ahead and copy the original image with {{ic|1=cp -sparse=true}} or {{ic|rsync -S}}. <br />
Then you can merge the original image back into the snapshot.<br />
# virsh blockpull --domain archey --path /vms/archey.snapshot1<br />
<br />
Now that you have pulled the blocks out of original image, the file {{ic|/vms/archey.snapshot1}} becomes the new disk image. Check its disk size to see what it means. After that is done, the original image {{ic|/vms/archey.img}} and the snapshot metadata can be deleted safely. The {{ic|virsh blockcommit}} would work opposite to {{ic|blockpull}} but it seems to be currently under development in qemu-kvm 1.3 (including snapshot-revert feature), scheduled to be released sometime next year.<br />
<br />
This new feature of KVM will certainly come handy to the people who like to take frequent live backups without risking corruption of the file system.<br />
<br />
==Remote access to libvirt==<br />
<br />
===Using unencrypted TCP/IP socket (most simple, least secure)===<br />
{{Warning|This should ''only'' be used for testing or use over a secure, private, and trusted network.}}<br />
<br />
Edit {{ic|/etc/libvirt/libvirtd.conf}}:<br />
{{hc|/etc/libvirt/libvirtd.conf|<nowiki><br />
listen_tls = 0<br />
listen_tcp = 1<br />
auth_tcp=none<br />
</nowiki>}}<br />
<br />
{{Warning|We do not enable SASL here, so all TCP traffic is cleartext! For real world use, ''always'' enable SASL.}}<br />
<br />
It is also necessary to start the server in listening mode by editing {{ic|/etc/conf.d/libvirtd}} <br />
{{hc|/etc/conf.d/libvirtd|2=LIBVIRTD_ARGS="--listen"}}<br />
<br />
===Using SSH===<br />
The {{Pkg|openbsd-netcat}} package is needed for remote management over [[SSH]].<br />
<br />
To connect to the remote system using {{ic|virsh}}:<br />
$ virsh -c qemu+ssh://''username''@''host''/system<br />
<br />
If something goes wrong, you can get some logs using:<br />
$ LIBVIRT_DEBUG=1 virsh -c qemu+ssh://''username''@''host''/system<br />
<br />
To display the graphical console for a virtual machine:<br />
$ virt-viewer --connect qemu+ssh://''username''@''host''/system myvirtualmachine<br />
<br />
To display the virtual machine desktop management tool:<br />
$ virt-manager -c qemu+ssh://''username''@''host''/system<br />
<br />
{{Note|If you are having problems connecting to a remote RHEL server (or anything other than Arch, really), try the two workarounds mentioned in {{bug|30748}} and {{bug|22068}}.}}<br />
<br />
=== Using Python ===<br />
The {{Pkg|libvirt-python}} package provides a {{Pkg|python2}} API in {{ic|/usr/lib/python2.7/site-packages/libvirt.py}}.<br />
<br />
General examples are given in {{ic|/usr/share/doc/libvirt-python-''your_libvirt_version''/examples/}}<br />
<br />
Unofficial example using {{Pkg|qemu}} and {{Pkg|openssh}}:<br />
<br />
#! /usr/bin/env python2<br />
# -*- coding: utf-8 -*-<br />
import socket<br />
import sys<br />
import libvirt<br />
if (__name__ == "__main__"):<br />
<nowiki>conn = libvirt.open("qemu+ssh://xxx/system")</nowiki><br />
print "Trying to find node on xxx"<br />
domains = conn.listDomainsID()<br />
for domainID in domains:<br />
domConnect = conn.lookupByID(domainID)<br />
if domConnect.name() == 'xxx-node':<br />
print "Found shared node on xxx with ID " + str(domainID)<br />
domServ = domConnect<br />
break<br />
<br />
== Bridged networking ==<br />
To use ''physical Ethernet'' from your virtual machines, you have to create a ''bridge'' between your physical Ethernet device (here ''eth0'') and the virtual Ethernet device the VM is using.<br />
<br />
=== Host configuration ===<br />
<br />
libvirt creates the bridge ''virbr0'' for NAT networking, so use another name such as ''br0'' or ''virbr1''.<br />
You have to create a new [[Netctl]] or [[Systemd-networkd]] profile to configure the bridge, for example (with DHCP configuration):<br />
<br />
{{hc|/etc/netctl/br0|<nowiki><br />
Description="Bridge connection for kvm"<br />
Interface=br0<br />
Connection=bridge<br />
BindsToInterfaces=(eno1)<br />
IP=dhcp<br />
</nowiki>}}<br />
<br />
{{out of date|The tip below needs to be updated for [[netctl]].}}<br />
{{Tip|It is recommended that you enable [[Wikipedia:Spanning_Tree_Protocol|Spanning Tree Protocol]] (STP) on the virtual bridge (e.g. ''br0'') that you create to avoid any potential bridging loops. You can automatically enable STP by appending {{ic|1=POST_UP="brctl stp $INTERFACE on"}} to the netcfg profile.}}<br />
<br />
=== Guest configuration ===<br />
Now we have to activate the ''bridge interface'' in our ''VMs''.<br />
If have a recent Linux machine, you can use this code in the ''.xml'' file:<br />
<br />
[...]<br />
<interface type='bridge'><br />
<source bridge='br0'/><br />
<mac address='24:42:53:21:52:49'/><br />
<model type='virtio' /><br />
</interface><br />
[...]<br />
<br />
This code activates a ''virtio'' device on the machine so, in Windows you will have to install an additional driver (you can find it here [http://www.linux-kvm.org/page/WindowsGuestDrivers/Download_Drivers Windows KVM VirtIO drivers]) or remove the line {{ic|<model type<nowiki>=</nowiki>'virtio' />}}:<br />
<br />
[...]<br />
<interface type='bridge'><br />
<source bridge='br0'/><br />
<mac address='24:42:53:21:52:49'/><br />
</interface><br />
[...]<br />
<br />
== See also ==<br />
* [http://libvirt.org/drvqemu.html libvirt web site]<br />
* [http://www-01.ibm.com/support/knowledgecenter/linuxonibm/liaat/liaatkvm.htm IBM KVM]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Deployment_and_Administration_Guide/index.html Red Hat Enterprise Linux 7 Virtualization Deployment and Administration Guide]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Chromium&diff=339988Chromium2014-10-14T17:46:17Z<p>Jstjohn: /* mailto links opened in new tab */ improve grammar</p>
<hr />
<div>[[de:Chromium]]<br />
[[es:Chromium]]<br />
[[fr:chromium]]<br />
[[it:Chromium]]<br />
[[ja:Chromium]]<br />
[[ru:Chromium]]<br />
[[zh-CN:Chromium]]<br />
[[Category:Web Browser]]<br />
{{Related articles start}}<br />
{{Related|Chromium tweaks}}<br />
{{Related|Browser plugins}}<br />
{{Related|Firefox}}<br />
{{Related|Opera}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Chromium (web browser)|Chromium]] is an open-source graphical web browser from Google, based on the [[Wikipedia:Blink (layout engine)|Blink]] rendering engine.<br />
<br />
== Installation ==<br />
<br />
The open source project, '''Chromium''', can be [[Pacman|installed]] with the package {{Pkg|chromium}}, available in the [[official repositories]]. <br />
In the [[AUR]] you can also find:<br />
* {{AUR|chromium-dev}} - the development version (binary version: {{AUR|chromium-browser-bin}})<br />
<br />
The modified browser, '''Google Chrome''', bundled with Flash Player, can be installed with the package {{AUR|google-chrome}}, available in the [[AUR]]. <br />
In the [[AUR]] you can also find:<br />
* {{AUR|google-chrome-beta}} - the beta version<br />
* {{AUR|google-chrome-dev}} - the development version<br />
<br />
{{Tip|See these [https://code.google.com/p/chromium/wiki/ChromiumBrowserVsGoogleChrome two] [http://news.softpedia.com/news/Google-Chrome-vs-Chromium-Understanding-Stable-Beta-Dev-Releases-and-Version-No-140060.shtml articles] for an explanation of the differences between Stable/Beta/Dev, as well as Chromium vs. Chrome and an explanation of the version numbering.}}<br />
<br />
===32-bit systems predating SSE2===<br />
<br />
As of version 35 of ''chromium'', [https://code.google.com/p/chromium/issues/detail?id=348761#c15 support for older hardware without an SSE2 instruction set has been removed upstream]. Users of old hardware still wishing to use ''chromium'' may build the {{AUR|chromium-no-sse2}} package or download a pre-compiled package from [[Repo-ck#Other packages|Repo-ck]]. Keep in mind that requiring SSE2 fixed several bugs, and you should not report issues encountered with this patched version upstream.<br />
<br />
== Configuration ==<br />
<br />
=== Set Chromium as default browser ===<br />
<br />
This behaviour is related to [[xdg-open]]: see [[xdg-open#Set the default browser]]. For more information about the topic in general, see [[Default applications]].<br />
<br />
=== File associations ===<br />
<br />
This behaviour is related to [[xdg-open]]: see [[xdg-open#Configuration]]. For more information about the topic in general, see [[Default applications]].<br />
<br />
=== Flash Player plugin ===<br />
<br />
{{Note|Chromium no longer supports the Netscape plugin API (NPAPI), so {{pkg|flashplugin}} from the repositories cannot be used.}}<br />
<br />
'''pepper-flash''' is the Flash Player plugin, using the new Pepper plugin API. It is developed by Adobe, and distributed bundled with Google Chrome.<br />
<br />
To install pepper-flash for Chromium, install {{AUR|chromium-pepper-flash}} from the [[AUR]]. If you want the development version, install {{AUR|chromium-pepper-flash-dev}}.<br />
<br />
Enable the plugin in {{ic|chrome://plugins}}.<br />
<br />
=== PDF viewer plugin ===<br />
<br />
There are multiple ways of enabling PDF support in Chromium that are detailed below.<br />
<br />
==== libpdf ====<br />
<br />
'''libpdf''' is Google's own implementation of a PDF viewer included with Chromium (since v37) and Google Chrome. <br />
<br />
When updating from v36 to 37, it is necessary to [[pacman#Removing packages|uninstall]] {{AUR|chromium-libpdf}} and {{AUR|chromium-libpdf-dev}}. If the plugin is disabled then enable it in {{ic|chrome://plugins}}.<br />
<br />
==== PDF.js ====<br />
<br />
See the main article: [[Browser plugins#PDF.js]]<br />
<br />
=== Certificates ===<br />
<br />
Chromium uses [[Network Security Services|NSS]] for certificate management. Certificates can be managed in {{ic|Settings}} → {{ic|Show advanced settings...}} → {{ic|Manage Certificates...}}.<br />
<br />
== Tips and tricks ==<br />
<br />
See the main article: [[Chromium tweaks]]<br />
<br />
== Troubleshooting ==<br />
<br />
=== Constant freezes under KDE ===<br />
<br />
[[Pacman#Removing packages|Uninstall]] {{pkg|libcanberra-pulse}}. See: [https://bbs.archlinux.org/viewtopic.php?pid=1228558 BBS#1228558].<br />
<br />
=== Cracking sound ===<br />
<br />
There have been reports of cracking sound with Chromium over HDMI audio. Start Chromium with a different audio buffer size to fix the issue:<br />
$ chromium --audio-buffer-size=2048<br />
<br />
=== Font rendering issues in PDF plugin ===<br />
<br />
To fix the font rendering in some PDFs one has to install the {{Pkg|ttf-liberation}} package, otherwise the substituted font causes text to run into other text. This was [https://code.google.com/p/chromium/issues/detail?id=369991 reported on the chromium bug tracker] by an Arch user.<br />
<br />
=== Force 3D acceleration in Flash Player and the browser ===<br />
<br />
{{Warning|Disabling the rendering list may cause unstable behaviour, including crashes of the host. See the bug reports in {{ic|chrome://gpu}}.}}<br />
<br />
First, make sure you have all the required packages as explained in [[VDPAU]]. Then, to force 3D rendering ''enable'' the flag "Override software rendering list" in {{ic|chrome://flags}}. Check if it is working in {{ic|chrome://gpu}}. This may also alleviate tearing issues with the [[radeon]] driver.<br />
<br />
=== mailto links opened in new tab ===<br />
<br />
If you do not use any desktop environment, you might encounter the issue that all ''mailto'' links are opened in a new browser instance instead of your default email client. In this case, you might need to use the following workaround by modifying {{ic|/usr/bin/xdg-email}} which is called by Chromium:<br />
<br />
# sed 's/open_generic "${mailto}"/open_gnome "${mailto}"/' -i /usr/bin/xdg-email<br />
<br />
This patch needs to be applied on every update of {{Pkg|xdg-utils}}. If you want a persistent solution, you can install {{AUR|xdg-utils-xdg-email-gnome}} or {{AUR|xdg-utils-mimeo}} from the [[AUR]].<br />
<br />
=== Proxy settings ===<br />
<br />
As of June 2012, there are many situations in which proxy settings do not work properly, especially if set through the KDE interface. A working alternative is to use Chromium's command-line options, like {{ic|--proxy-auto-detect}}, {{ic|--proxy-pac-url}} and {{ic|--proxy-server}}, to set your proxy.<br />
<br />
=== speech-dispatcher dumps core ===<br />
<br />
{{Note|This was reported as bug {{Bug|38456}}.}}<br />
<br />
Chromium installs {{Pkg|speech-dispatcher}} as a dependency. The latter is an independent layer for speech synthesis interface and by default uses {{Pkg|festival}} as its back end. If you are frequently receiving core dumps, it is likely caused by not having installed festival. To resolve the error message, either install festival or change the back end used by speech-dispatcher.<br />
<br />
=== WebGL ===<br />
<br />
Chromium will sometimes disable WebGL with certain graphics card configurations. To remedy this, enter {{ic|chrome://flags}} into the URL bar and ''disable'' the ''Disable WebGL'' flag. Alternatively, pass the command-line flag {{ic|--enable-webgl}} to Chromium in the terminal.<br />
<br />
There is also the possibility that your graphics card has been blacklisted by Chromium. To override this, go to {{ic|chrome://flags}} and ''enable'' the ''Override software rendering list'' flag. Alternatively, pass the command-line flag {{ic|--ignore-gpu-blacklist}} to Chromium in the terminal.<br />
<br />
If you are using Chromium with [[Bumblebee]], WebGL might crash due to GPU sandboxing. In this case, you can disable GPU sandboxing with {{ic|optirun chromium --disable-gpu-sandbox}}.<br />
<br />
== See also ==<br />
<br />
* [http://www.chromium.org/Home Chromium homepage]<br />
* [http://googlechromereleases.blogspot.com Google Chrome release notes]<br />
* [https://chrome.google.com/webstore/category/home Chrome web store]<br />
* [[Wikipedia: Chromium_(web_browser)#Differences_from_Google_Chrome|Differences between Chromium and Google Chrome]]<br />
* [http://peter.sh/experiments/chromium-command-line-switches/ List of Chromium command-line switches]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Java&diff=339987Java2014-10-14T17:40:45Z<p>Jstjohn: /* Flagging packages as out-of-date */ improve grammar</p>
<hr />
<div>[[Category:Programming language]]<br />
[[cs:Java]]<br />
[[de:Java]]<br />
[[es:Java]]<br />
[[fr:Java]]<br />
[[it:Java]]<br />
[[ja:Java]]<br />
[[pt:Java]]<br />
[[ru:Java]]<br />
[[tr:Java]]<br />
{{Related articles start}}<br />
{{Related|Java Package Guidelines}}<br />
{{Related articles end}}<br />
<br />
"''Java is a programming language originally developed by Sun Microsystems and released in 1995 as a core component of Sun Microsystems' Java platform. The language derives much of its syntax from C and C++ but has a simpler object model and fewer low-level facilities. Java applications are typically compiled to bytecode that can run on any Java virtual machine (JVM) regardless of computer architecture.''" — [[Wikipedia:Java (programming language)|Wikipedia article]]<br />
<br />
Arch Linux officially supports the open source [http://openjdk.java.net/ OpenJDK] versions 7 and 8. All these JVM can be installed without conflict and switched between using helper script {{Ic|archlinux-java}}. Several other Java environments are available in [[AUR]] but are not officially supported.<br />
<br />
== Installation ==<br />
The following packages are available in the [[official repositories]]:<br />
<br />
OpenJDK 7:<br />
<br />
{| class="wikitable"<br />
! Package name !! Use<br />
|-<br />
|{{Pkg|jre7-openjdk-headless}} || Java runtime environment (''JRE'') without any graphical tool - version 7<br />
|-<br />
|{{Pkg|jre7-openjdk}} || Complete Java Runtime Environment (''JRE'') - version 7<br />
|-<br />
|{{Pkg|jdk7-openjdk}} || Java Development Kit (''JDK'') - version 7<br />
|-<br />
|{{Pkg|openjdk7-doc}} || OpenJDK javadoc - version 7<br />
|-<br />
|{{Pkg|openjdk7-src}} || OpenJDK sources - version 7<br />
|}<br />
<br />
OpenJDK 8:<br />
<br />
{| class="wikitable"<br />
! Package name !! Use<br />
|-<br />
|{{Pkg|jre8-openjdk-headless}} || Java runtime environment (''JRE'') without any graphical tool - version 8<br />
|-<br />
|{{Pkg|jre8-openjdk}} || Complete Java Runtime Environment (''JRE'') - version 8<br />
|-<br />
|{{Pkg|jdk8-openjdk}} || Java Development Kit (''JDK'') - version 8<br />
|-<br />
|{{Pkg|openjdk8-doc}} || OpenJDK javadoc - version 8<br />
|-<br />
|{{Pkg|openjdk8-src}} || OpenJDK sources - version 8<br />
|-<br />
|}<br />
<br />
{{Note|Installing a JDK will automatically pull its JRE dependency.}}<br />
<br />
{{Note|After installation, the Java environment will need to be recognized by the shell ({{Ic|$PATH}} variable). This can be done by sourcing {{Ic|/etc/profile}} from the command line or by logging out/in again of a Desktop Environment.}}<br />
<br />
Two ''common'' packages named {{Pkg|java-runtime-common}} and {{Pkg|java-environment-common}} are automatically pulled as dependency and provide environment file {{Ic|/etc/profile.d/jre.sh}}. This file contains all JVM common environment variables. Package {{Pkg|java-runtime-common}} also provides a utility script {{Ic|archlinux-java}} that can display and change the default Java environment. This script sets links {{Ic|/usr/lib/jvm/default}} and {{Ic|/usr/lib/jvm/default-runtime}} to point at a valid non-conflicting Java environment installed and Java runtime in {{Ic|/var/lib/jvm/java-${JAVA_MAJOR_VERSION}-${VENDOR_NAME}}}. Most executable provided by the Java environment set have direct links from {{Ic|/usr/bin}}, others are available in {{Ic|$PATH}}.<br />
<br />
{{Warning|File {{Ic|/etc/profile.d/jdk.sh}} is not provided anymore by any package.}}<br />
<br />
== Flagging packages as out-of-date ==<br />
<br />
Although the Arch Linux package releases may contain a reference to the proprietary versions the packages are based on, the open-source project has its own versioning scheme: <br />
<br />
* {{Pkg|jre7-openjdk}}, {{Pkg|jdk7-openjdk}}, and {{Pkg|jre7-openjdk-headless}} and their OpenJDK 8 couterparts should be flagged as out-of-date based on the [http://icedtea.wildebeest.org/download/source ''IcedTea'' version] (e.g. {{ic|2.4.3}}), rather than on the Oracle reference version (e.g. {{ic|u45}} in the release {{ic|7.u45_2.4.3-1}}).<br />
* {{Pkg|icedtea-web}} should be flagged as out-of-date based on the [http://icedtea.wildebeest.org/download/source ''IcedTea Web'' version] (e.g. {{ic|1.4.1}}). This is independent of the ''IcedTea'' version.<br />
<br />
== Switching between JVM ==<br />
<br />
Helper script {{Ic|archlinux-java}} provides such functionalities:<br />
<br />
archlinux-java <COMMAND><br />
<br />
COMMAND:<br />
status List installed Java environments and enabled one<br />
get Return the short name of the Java environment set as default<br />
set <JAVA_ENV> Force <JAVA_ENV> as default<br />
unset Unset current default Java environment<br />
fix Fix an invalid/broken default Java environment configuration<br />
<br />
=== List compatible Java environments installed ===<br />
<br />
% archlinux-java status<br />
<br />
Example:<br />
<br />
% archlinux-java status<br />
Available Java environments:<br />
java-7-openjdk (default)<br />
java-8-openjdk/jre<br />
<br />
Note the ''(default)'' denoting that {{Ic|java-7-openjdk}} is currently set as default. Invocation of {{Ic|java}} and other binaries will rely on this Java install. Also note on the previous output that only the ''JRE'' part of OpenJDK 8 is installed here.<br />
<br />
=== Change default Java environment ===<br />
<br />
# archlinux-java set <JAVA_ENV_NAME><br />
<br />
Example:<br />
<br />
# archlinux-java set java-8-openjdk/jre<br />
<br />
Note that {{Ic|archlinux-java}} will not let you set an invalid Java environment. In the previous example, {{pkg|jre8-openjdk}} is installed but {{pkg|jdk8-openjdk}} is '''not''' so trying to set {{Ic|java-8-openjdk}} will fail:<br />
<br />
# archlinux-java set java-8-openjdk<br />
'/usr/lib/jvm/java-8-openjdk' is not a valid Java environment path<br />
<br />
=== Unsetting the default Java environment ===<br />
<br />
There should be no need to unset a Java environment as packages providing them should take care of this. Still should you want to do so, just use command {{Ic|unset}}:<br />
<br />
# archlinux-java unset<br />
<br />
=== Fixing the default Java environment ===<br />
<br />
If {{Ic|/usr/bin}} links are incorrect or if an invalid Java environment link is set, calling the {{Ic|archlinux-java fix}} command tries to fix these. Also note that if no default Java environment is set, this will look for valid ones and try to set it for you. Officially supported packages "OpenJDK 7" and "OpenJDK 8" will be considered first in this order, then un-official packages from [[AUR]].<br />
<br />
# archlinux-java fix<br />
<br />
=== Former "One time setup" trick ===<br />
<br />
Formerly, package {{Pkg|java-common}} could be forced into using a Java installation by setting environment variable {{Ic|JAVA_HOME}}. This cannot be done anymore with latest version of {{Pkg|java-runtime-common}}.<br />
<br />
== Package pre-requisites to support {{Ic|archlinux-java}} ==<br />
This section is targeted at packager willing to provide packages in [[AUR]] for an alternate JVM and be able to integrate with Arch Linux JVM scheme to use {{Ic|archlinux-java}}. To do so, packages should:<br />
<br />
* Place all files under {{Ic|/usr/lib/jvm/java-${JAVA_MAJOR_VERSION}-${VENDOR_NAME} }}<br />
* Ensure all executables for which [https://www.archlinux.org/packages/extra/any/java-runtime-common/files/ java-runtime-common] and [https://www.archlinux.org/packages/extra/any/java-environment-common/files/ java-environment-common] provide links are available in the corresponding package <br />
* Ship links from {{Ic|/usr/bin}} to executables, only if these links do not already belong to [https://www.archlinux.org/packages/extra/any/java-runtime-common/files/ java-runtime-common] and [https://www.archlinux.org/packages/extra/any/java-environment-common/files/ java-environment-common]<br />
* Suffix man pages with {{Ic|-${VENDOR_NAME}${JAVA_MAJOR_VERSION} }} to prevent conflicts (see [https://www.archlinux.org/packages/extra/x86_64/jre8-openjdk/files/ jre8-openjdk file list] where man pages are suffixed with {{Ic|-openjdk8}})<br />
* Do not declare any [[PKGBUILD#conflicts|conflicts]] nor [[PKGBUILD#replaces|replaces]] with other JDKs, {{Ic|java-runtime}}, {{Ic|java-runtime-headless}} nor {{Ic|java-environment}}<br />
* Use script {{Ic|archlinux-java}} in ''install functions'' to set the Java environment as default '''if no other valid Java environment is already set''' (ie: package should not '''force''' install as default). See [https://projects.archlinux.org/svntogit/packages.git/tree/trunk?h=packages/java7-openjdk officially supported Java environment package sources] for examples<br />
<br />
Also please note that:<br />
* Packages that need '''any''' Java environment should declare dependency on {{Ic|java-runtime}}, {{Ic|java-runtime-headless}} or {{Ic|java-environment}} as usual<br />
* Packages that need a '''specific Java vendor''' should declare dependency on the corresponding package<br />
* OpenJDK packages now declare {{Ic|1=provides="java-runtime-openjdk=${pkgver}"}} etc. This enables a third-party package to declare dependency on an OpenJDK without specifying a version<br />
<br />
== Unsupported JVM from AUR ==<br />
<br />
{{Warning|Packages in [[AUR]] may or may not support {{Ic|archlinux-java}}}}<br />
<br />
=== Java SE ===<br />
Several packages from [[AUR]] provide Oracle's implementations of JRE and JDK, but the main ones are {{AUR|jre}} and {{AUR|jdk}}.<br />
<br />
==== Java SE 6/7 ====<br />
Older versions include {{AUR|jre6}}/{{AUR|jre6-compat}}/{{AUR|jre7}}/{{AUR|jre7-oracle}} and {{AUR|jdk6}}/{{AUR|jdk6-compat}}/{{AUR|jdk7}}/{{AUR|jdk7-oracle}}.<br />
<br />
=== Oracle JRockit ===<br />
[http://www.oracle.com/technetwork/middleware/jrockit/overview/index.html JRockit] is Oracle's JIT version of Java, available as {{AUR|jrockit}}.<br />
<br />
=== VMkit ===<br />
[http://vmkit.llvm.org/index.html VMkit] is an LLVM-based framework for JIT virtual machines. J3 is a JVM running on VMkit. The webpage can be found here: [http://vmkit.llvm.org/get_started.html vmkit]. J3 depends on the GNU classpath libraries, but may also work with the Apache class path libraries.<br />
<br />
=== Parrot VM ===<br />
[http://www.parrot.org/ Parrot] is a VM that offers experimental [http://trac.parrot.org/parrot/wiki/Languages support for Java] through two different methods: Either as a [http://code.google.com/p/parrot-jvm/ Java VM bytecode translator] or as a [https://github.com/chrisdolan/perk Java compiler targeting the Parrot VM]. {{Pkg|parrot}} is available in the [[official repositories]] and {{AUR|parrot-git}} in the AUR.<br />
<br />
== Troubleshooting ==<br />
=== MySQL ===<br />
Due to the fact that the JDBC-drivers often use the port in the URL to establish a connection to the database, it is considered "remote" (i.e., MySQL does not listen to the port as per its default settings) despite the fact that they are possibly running on the same host, Thus, to use JDBC and MySQL you should enable remote access to MySQL, following the instructions in [[MySQL#Grant Remote Access]].<br />
<br />
=== Impersonate another window manager ===<br />
You may use the {{pkg|wmname}} from [http://tools.suckless.org/wmname suckless.org] to make the JVM believe you are running a different window manager. This may solve a rendering issue of Java GUIs occurring in window managers like [[Awesome]] or [[Dwm]].<br />
$ wmname LG3D<br />
<br />
You must restart the application in question after issuing the wmname command.<br />
<br />
This works because the JVM contains a hard-coded list of known, non-re-parenting window managers. For maximum irony, some users prefer to impersonate {{ic|LG3D}}, the non-re-parenting window manager [[wikipedia:Project_Looking_Glass|written by Sun, in Java]].<br />
<br />
=== Illegible fonts ===<br />
In addition to the suggestions mentioned below in [[#Better font rendering]], some fonts may still not be legible afterwards. If this is the case, there is a good chance Microsoft fonts are being used. Install {{AUR|ttf-ms-fonts}} from the [[AUR]].<br />
<br />
=== Missing text in some applications ===<br />
If some applications are completely missing texts it may help to use the options under [[#Tips and tricks]] as suggested in {{Bug|40871}}.<br />
<br />
=== Too many levels of symbolic links ===<br />
<br />
If you get an error like:<br />
<br />
/usr/bin/java: line 2: /usr/lib/jvm/default/bin/java: Too many levels of symbolic links<br />
/usr/bin/java: line 2: exec: /usr/lib/jvm/default/bin/java: cannot execute: Too many levels of symbolic links<br />
<br />
[[#Fixing the default Java environment]] should solve the problem. See also [https://bbs.archlinux.org/viewtopic.php?pid=1453803].<br />
<br />
== Tips and tricks ==<br />
{{Note|Suggestions in this section are applicable to all applications, using explicitly installed (external) Java runtime. Some applications are bundled with own (private) runtime or use own mechanics for GUI, font rendering, etc., so none of written below is guaranteed to work.}}<br />
<br />
Behavior of most Java applications can be controlled by supplying predefined variables to Java runtime. From [https://bbs.archlinux.org/viewtopic.php?id=72892 this forum post], a way to do it consists of adding the following line in your {{Ic|~/.bashrc}} (or {{Ic|/etc/profile.d/jre.sh}} to affect programs that are not run by sourcing {{Ic|~/.bashrc}}, e.g., launching a program from Gnome's Applications view):<br />
<br />
export _JAVA_OPTIONS="-D'''<option 1>''' -D'''<option 2>'''..."<br />
<br />
For example, to use system anti-aliased fonts and make swing use the GTK look and feel:<br />
<br />
export _JAVA_OPTIONS='-Dawt.useSystemAAFontSettings=on -Dswing.aatext=true -Dswing.defaultlaf=com.sun.java.swing.plaf.gtk.GTKLookAndFeel'<br />
<br />
=== Better font rendering ===<br />
Both closed source and open source implementations of Java are known to have improperly implemented anti-aliasing of fonts. This can be fixed with the following options: {{Ic|1=awt.useSystemAAFontSettings=on}}, {{Ic|1=swing.aatext=true}}<br />
<br />
See [[Java Runtime Environment Fonts]] for more detailed information.<br />
<br />
=== GTK LookAndFeel ===<br />
If your Java programs look ugly, you may want to set up the default look and feel for the swing components: {{Ic|1=swing.defaultlaf=com.sun.java.swing.plaf.gtk.GTKLookAndFeel}}.<br />
<br />
Some stubborn Java programs insist on using the cross platform Metal look and feel. In some of these cases you can force these apps to use the GTK look and feel by setting the following property:<br />
<br />
{{Ic|1=swing.crossplatformlaf=com.sun.java.swing.plaf.gtk.GTKLookAndFeel}}.</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Optical_disc_drive&diff=339470Optical disc drive2014-10-10T00:45:08Z<p>Jstjohn: /* Burning an audio CD */ improve spelling and grammar; use italics for "cdrecord" when used in prose</p>
<hr />
<div>[[Category:Optical]]<br />
[[Category:Audio/Video]]<br />
[[es:Optical Disc Drive]]<br />
[[it:Optical Disc Drive]]<br />
[[ja:Optical Disc Drive]]<br />
[[zh-CN:Optical Disc Drive]]<br />
{{Related articles start}}<br />
{{Related|Codecs}}<br />
{{Related|MPlayer}}<br />
{{Related|dvdbackup}}<br />
{{Related|MEncoder}}<br />
{{Related|BluRay}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Optical disc drive|Wikipedia]]<br />
<br />
:''In computing, an optical disc drive (ODD) is a disk drive that uses laser light or electromagnetic waves within or near the visible light spectrum as part of the process of reading or writing data to or from optical discs. Some drives can only read from discs, but recent drives are commonly both readers and recorders, also called burners or writers. Compact discs, DVDs, and Blu-ray discs are common types of optical media which can be read and recorded by such drives. Optical drive is the generic name; drives are usually described as "CD" "DVD", or "Blu-ray", followed by "drive", "writer", etc.''<br />
<br />
== Burning ==<br />
<br />
The burning process of optical disc drives consists of creating or obtaining an image and writing it to an optical medium. The image may in principle be any data file. If you want to mount the resulting medium, then it is usually an ISO 9660 file system image file. Audio and multi-media CDs are often burned from a BIN file, under control of a TOC file or a CUE file which tell the desired track layout.<br />
<br />
=== Install burning utilities ===<br />
<br />
If you want to use programs with graphical user interface, then follow [[#Burning CD/DVD/BD with a GUI|this link to the list of GUI programs]].<br />
<br />
The programs listed here are the back ends which are used by most free GUI programs for CD, DVD, and BD. They are command line oriented. GUI users might get to them when it comes to troubleshooting or to scripting of burn activities.<br />
<br />
You need at least one program for creation of file system images and one program that is able to burn data onto your desired media type.<br />
<br />
Available programs for ISO 9660 image creation are:<br />
<br />
* {{ic|genisoimage}} from package {{Pkg|cdrkit}}<br />
* {{ic|mkisofs}} from package {{Pkg|cdrtools}}<br />
* {{ic|xorriso}} and {{ic|xorrisofs}} from package {{Pkg|libisoburn}}<br />
<br />
The traditional choice is {{ic|genisoimage}}.<br />
<br />
Available programs for burning to media are:<br />
<br />
* {{ic|cdrdao}} from package {{Pkg|cdrdao}} (CD only, TOC/CUE/BIN only)<br />
* {{ic|cdrecord}} from package {{Pkg|cdrtools}}<br />
* {{ic|cdrskin}} from package {{Pkg|libburn}}<br />
* {{ic|growisofs}} from package {{Pkg|dvd+rw-tools}} (DVD and BD only)<br />
* {{ic|wodim}} from package {{Pkg|cdrkit}} (CD only, DVD deprecated)<br />
* {{ic|xorriso}} and {{ic|xorrecord}} from package {{Pkg|libisoburn}}<br />
<br />
The traditional choices are {{ic|wodim}} for CD and {{ic|growisofs}} for DVD and Blu-ray Disk. For growisofs and BD-R see the bug workaround below.<br />
For writing TOC/CUE/BIN files to CD, install {{ic|cdrdao}}.<br />
<br />
The free GUI programs for CD, DVD, and BD burning depend on at least one of the above packages.<br />
<br />
The programs {{ic|genisoimage}}, {{ic|mkisofs}}, and {{ic|xorrisofs}} all three support the genisoimage options which are shown in this document.<br />
<br />
The programs {{ic|cdrecord}}, {{ic|cdrskin}}, and {{ic|wodim}} all three support the shown wodim options. Program {{ic|xorrecord}} supports those which do not deal with audio CD.<br />
<br />
{{Note|<br />
* The installed files of packages {{Pkg|cdrkit}} and {{Pkg|cdrtools}} are in conflict. Install only one of them.<br />
* If you want to install [[wikipedia:Cdrtools|cdrtools]], make sure that you build a package using [[makepkg]] and install with [[pacman]]. Pacman wrappers may resolve to cdrkit instead.<br />
}}<br />
<br />
=== Making an ISO image from existing files on hard disk ===<br />
<br />
The simplest way to create an ISO image is to first copy the needed files to one folder, for example: {{ic|./for_iso}}.<br />
<br />
Then use {{ic|genisoimage}} in the manner of the following example:<br />
<br />
$ genisoimage -V "ARCHIVE_2013_07_27" -J -r -o isoimage.iso ./for_iso<br />
<br />
Each of those flags/switches are explained in the following sections.<br />
<br />
==== Basic switches ====<br />
;-V: Specifies the name (that is assigned to) of the file system. The ISO 9660 standard specs impose the limitations of 32-character string length, as well as limiting the characters allowed to sets of: "A" to "Z", "0" to "9", and "_". This volume label will probably show up as mount point if the medium is mounted automatically.<br />
;-J: Prepares names of up to 64 UTF-16 characters for MS-Windows readers. Also known as "Joliet".<br />
;-joliet-long: Would allow 103 UTF-16 characters for MS-Windows readers. Non-compliant to Joliet specs.<br />
;-r: Prepares names of up to 255 characters for Unix readers and gives read permission for everybody. Also known as "Rock Ridge".<br />
;-o: Sets the file path for the resulting ISO image.<br />
<br />
==== graft-points ====<br />
<br />
It is also possible to let genisoimage collect files and directories from various paths<br />
<br />
$ genisoimage -V "BACKUP_2013_07_27" -J -r -o backup_2013_07_27.iso \<br />
-graft-points \<br />
/photos=/home/user/photos \<br />
/mail=/home/user/mail \<br />
/photos/holidays=/home/user/holidays/photos<br />
<br />
;-graft-points: Enables the recognition of ''pathspecs'' which consist of a target address in the ISO file system (e.g. {{ic|/photos}}) and a source address on hard disk (e.g. {{ic|/home/user/photos}}). Both are separated by a "=" character.<br />
<br />
So this example puts the disk directory {{ic|/home/user/photos}}, {{ic|/home/user/mail}} and {{ic|/home/user/holidays/photos}}, respectively in the ISO image as {{ic|/photos}}, {{ic|/mail}} and {{ic|/photos/holidays}}.<br />
<br />
Programs ''mkisofs'' and ''xorrisofs'' accept the same options. For secure backups, consider using ''xorrisofs'' with option {{ic|--for_backup}}, which records eventual ACLs and stores an MD5 checksum for each data file.<br />
<br />
See the manuals of the ISO 9660 programs for more info about their options:<br />
*[http://linux.die.net/man/1/genisoimage genisoimage]<br />
*[http://cdrtools.sourceforge.net/private/man/cdrecord/index.html mkisofs]<br />
*[https://www.gnu.org/software/xorriso/man_1_xorrisofs.html xorrisofs]<br />
<br />
{{Tip|This process can be thought of alternately as:<br />
* creating an archive (which is not that different, on one level, from creating a ZIP archive or tarball (e.g. ''.tar.gz''))<br />
* creating and ''populating'' a file system volume, manifested in the form of a "disk" image (file), which preserves as much as possible (content, name, relative directory structure/hierarchy/placement, and possibly other file system overhead metadata / properties (aspects)) such as timestamp(s), ownership, permissions.}}<br />
<br />
=== Mounting an ISO image ===<br />
<br />
To test if the ISO image is proper, you can mount it (as root):<br />
<br />
# mount -t iso9660 -o ro,loop=/dev/loop0 cd_image /cdrom<br />
<br />
You have to first load the loop module:<br />
<br />
# modprobe loop<br />
<br />
Do not forget to unmount the image when your inspection of the image is done:<br />
<br />
# umount /cdrom<br />
<br />
See also [[Mounting images as user]] for mounting without root privileges.<br />
<br />
=== Converting img/ccd to an ISO image ===<br />
<br />
To convert an {{ic|img}}/{{ic|ccd}} image, you can use {{Pkg|ccd2iso}}:<br />
<br />
$ ccd2iso ~/image.img ~/image.iso<br />
<br />
=== Learning the name of your optical drive ===<br />
<br />
For the remainder of this section the name of your recording device is assumed to be {{ic|/dev/sr0}}.<br />
<br />
Check this by<br />
<br />
$ wodim dev=/dev/sr0 -checkdrive<br />
<br />
which should report "Vendor_info" and "Identification" of the drive.<br />
<br />
If no drive is found, check whether any {{ic|/dev/sr*}} exist and whether they offer read/write permission ({{ic|wr-}}) to you or your group.<br />
If no {{ic|/dev/sr*}} exists then try<br />
<br />
# modprobe sr_mod<br />
<br />
=== Reading the volume label of a CD or DVD ===<br />
<br />
If you want to get the name/label of the media, use dd:<br />
<br />
$ dd if=/dev/sr0 bs=1 skip=32808 count=32<br />
<br />
=== Reading an ISO image from a CD, DVD, or BD ===<br />
<br />
You should determine the size of the ISO file system before copying it to hard disk. Most media types deliver more data than was written to them with the most recent burn run.<br />
<br />
Use program {{ic|isosize}} out of package {{Pkg|util-linux}} to obtain the image size<br />
<br />
$ blocks=$(expr $(isosize /dev/sr0) / 2048)<br />
<br />
Have a look whether the obtained number of blocks is plausible<br />
<br />
{{hc|$ echo "That would be $(expr $blocks / 512) MB"|<br />
That would be 589 MB<br />
}}<br />
<br />
Then copy the determined amount of data from medium to hard disk :<br />
<br />
$ dd if=/dev/sr0 of=isoimage.iso bs=2048 count=$blocks<br />
<br />
Omit {{ic|1= count=$blocks}} if you did not determine the size. You will probably get more data than needed. The resulting file will nevertheless be mountable. It should still fit onto a medium of the same type as the medium from which the image was copied.<br />
<br />
If the original medium was bootable, then the copy will be a bootable image. You may use it as pseudo CD for a virtual machine or burn it onto optical media which should then become bootable.<br />
<br />
=== Erasing CD-RW and DVD-RW ===<br />
<br />
Used CD-RW media need to be erased before you can write over the previously recorded data. This is done by<br />
<br />
$ wodim -v dev=/dev/sr0 blank=fast<br />
<br />
Unformatted DVD-RW media need the same treatment before re-use. But fast blanking deprives them of the capability for multi-session and recording of streams of unpredicted length. So one should apply<br />
<br />
$ dvd+rw-format -blank=full /dev/sr0<br />
<br />
{{ic|1= dvd+rw-format}} is part of package {{Pkg|dvd+rw-tools}}. Alternative commands are<br />
$ cdrecord -v dev=/dev/sr0 blank=all<br />
$ cdrskin -v dev=/dev/sr0 blank=all<br />
$ xorriso -outdev /dev/sr0 -blank as_needed<br />
<br />
Formatted DVD-RW media can be overwritten without such erasure. So consider to apply once in their life time<br />
<br />
$ dvd+rw-format -force /dev/sr0<br />
<br />
Alternative commands are <br />
$ cdrskin -v dev=/dev/sr0 blank=format_overwrite<br />
$ xorriso -outdev /dev/sr0 -format as_needed<br />
<br />
All other media are either write-once (CD-R, DVD-R, DVD+R, BD-R) or are overwritable without the need for erasing (DVD-RAM, DVD+RW, BD-RE).<br />
<br />
=== Burning an ISO image to CD, DVD, or BD ===<br />
<br />
To burn a readily prepared ISO image file {{ic|isoimage.iso}} onto an optical medium, run for CD:<br />
<br />
$ wodim -v -sao dev=/dev/sr0 isoimage.iso<br />
<br />
and for DVD or BD:<br />
<br />
$ growisofs -dvd-compat -Z /dev/sr0=isoimage.iso<br />
<br />
The programs {{ic|cdrecord}}, {{ic|cdrskin}}, and {{ic|xorrecord}} may be used on all kinds of media with the options shown with {{ic|wodim}}.<br />
<br />
{{Note|<br />
* Make sure that the medium is not mounted when you begin to write to it. Mounting may happen automatically if the medium contains a readable file system. In the best case, it will prevent the burn programs from using the burner device. In the worst case, there will be misburns because read operations disturbed the drive.<br />
So if in doubt, do:<br />
# umount /dev/sr0<br />
* {{ic|growisofs}} has a small bug with blank BD-R media. It issues an error message after the burning is complete. Programs like {{ic|k3b}} then believe the whole burn run failed.<br />
To prevent this, either<br />
** format the blank BD-R by {{ic|dvd+rw-format /dev/sr0}} before submitting it to ''growisofs''<br />
** or use ''growisofs'' option {{ic|1= -use-the-force-luke=spare:none}}<br />
}}<br />
<br />
=== Verifying the burnt ISO image ===<br />
<br />
You can verify the integrity of the burnt medium to make sure it contains no errors. Always eject the medium and reinsert it before verifying. The kernel will learn about the new content only by that reinsertion.<br />
<br />
First calculate the MD5 checksum of the original ISO image:<br />
<br />
{{hc|$ md5sum isoimage.iso|<br />
e5643e18e05f5646046bb2e4236986d8 isoimage.iso<br />
}}<br />
<br />
Next calculate the MD5 checksum of the ISO file system on the medium.<br />
Although some media types deliver exactly the same amount of data as have been submitted to the burn program, many others append trailing garbage when being read. So you should restrict reading to the size of the ISO image file.<br />
<br />
$ blocks=$(expr $(du -b isoimage.iso | awk '{print $1}') / 2048)<br />
<br />
{{hc|<nowiki>$ dd if=/dev/sr0 bs=2048 count=$blocks | md5sum</nowiki>|<br />
43992+0 records in<br />
43992+0 records out<br />
90095616 bytes (90 MB) copied, 0.359539 s, 251 MB/s<br />
e5643e18e05f5646046bb2e4236986d8 -<br />
}}<br />
<br />
Both runs should yield the same MD5 checksum (here: {{ic|e5643e18e05f5646046bb2e4236986d8}}). If they do not, you will probably also get an I/O error message from the {{ic|dd}} run. {{ic|dmesg}} might then tell about SCSI errors and block numbers, if you are interested.<br />
<br />
=== ISO 9660 and Burning On-The-Fly ===<br />
<br />
It is not necessary to store an emerging ISO file system on hard disk before writing it to optical media. Only very old CD drives at very old computers could suffer failed burns due to empty drive buffer.<br />
<br />
If you omit option {{ic|-o}} from {{ic|genisoimage}} then it writes the ISO image to standard output. This can be piped into the standard input of burn programs.<br />
<br />
$ genisoimage -V "ARCHIVE_2013_07_27" -J -r ./for_iso | \<br />
wodim -v dev=/dev/sr0 -waiti -<br />
<br />
Option {{ic|-waiti}} is not really needed here. It prevents {{ic|wodim}} from writing to the medium before {{ic|genisoimage}} starts its output. This would allow {{ic|genisoimage}} to read the medium without disturbing an already started burn run. See next section about multi-session.<br />
<br />
On DVD and BD, you may let{{ic|growisofs}} operate {{ic|genisoimage}} for you and burn its output on-the-fly<br />
<br />
$ export MKISOFS="genisoimage"<br />
$ growisofs -Z /dev/sr0 -V "ARCHIVE_2013_07_27" -r -J ./for_iso<br />
<br />
=== Multi-session ===<br />
<br />
ISO 9660 multi-session means that a medium with readable file system is still writable at its first unused block address, and that a new ISO directory tree gets written to this unused part.<br />
The new tree is accompanied by the content blocks of newly added or overwritten data files. The blocks of data files, which shall stay as in the old ISO tree, will not be written again.<br />
<br />
Linux and many other operating systems will mount the directory tree in the last session on the medium. This youngest tree will normally show the files of the older sessions, too.<br />
<br />
==== Multi-session by wodim ====<br />
<br />
CD-R and CD-RW stay writable (aka "appendable") if wodim option {{ic|-multi}} was used<br />
<br />
$ wodim -v -multi dev=/dev/sr0 isoimage.iso<br />
<br />
Then the medium can be inquired for the parameters of the next session<br />
<br />
$ m=$(wodim dev=/dev/sr0 -msinfo)<br />
<br />
By help of these parameters and of the readable medium in the drive you can produce the add-on ISO session<br />
<br />
$ genisoimage -M /dev/sr0 -C "$m" \<br />
-V "ARCHIVE_2013_07_28" -J -r -o session2.iso ./more_for_iso<br />
<br />
Finally append the session to the medium and keep it appendable again<br />
<br />
$ wodim -v -multi dev=/dev/sr0 session2.iso<br />
<br />
Programs {{ic|cdrskin}} and {{ic|xorrecord}} do this too with DVD-R, DVD+R, BD-R and unformatted DVD-RW. Program {{ic|cdrecord}} does multi-session with at least DVD-R and DVD-RW. They all do with CD-R and CD-RW, of course.<br />
<br />
Most re-usable media types do not record a session history that would be recognizable for a mounting kernel. But with ISO 9660 it is possible to achieve the multi-session effect even on those media.<br />
<br />
{{ic|growisofs}} and {{ic|xorriso}} can do this and hide most of the complexity.<br />
<br />
==== Multi-session by growisofs ====<br />
<br />
{{ic|growisofs}} forwards most of its program arguments to a program that is compatible to {{ic|mkisofs}}. See above examples of {{ic|genisoimage}}.<br />
It bans option {{ic|-o}} and deprecates option {{ic|-C}}.<br />
By default it uses the installed program named "mkisofs". You may let it choose one of the others by setting environment variable {{ic|MKISOFS}}<br />
<br />
$ export MKISOFS="genisoimage"<br />
$ export MKISOFS="xorrisofs"<br />
<br />
The wish to begin with a new ISO file system on the optical medium is expressed by option {{ic|-Z}}<br />
<br />
$ growisofs -Z /dev/sr0 -V "ARCHIVE_2013_07_27" -r -J ./for_iso<br />
<br />
The wish to append more files as new session to an existing ISO file system is expressed by option {{ic|-M}}<br />
<br />
$ growisofs -M /dev/sr0 -V "ARCHIVE_2013_07_28" -r -J ./more_for_iso<br />
<br />
For details see the [http://linux.die.net/man/1/growisofs growisofs manual] and the manuals of {{ic|genisoimage}}, {{ic|mkisofs}}, {{ic|xorrisofs}}.<br />
<br />
==== Multi-session by xorriso ====<br />
<br />
{{ic|xorriso}} learns the wish to begin with a new ISO file system from the blank state of the medium. So it is appropriate to blank it if it contains data. The command {{ic|-blank as_needed}} applies to all kinds of re-usable media and even to ISO images in data files on hard disk. It does not cause error if applied to a blank write-once medium.<br />
<br />
$ xorriso -outdev /dev/sr0 -blank as_needed \<br />
-volid "ARCHIVE_2013_07_27" -joliet on -add ./for_iso --<br />
<br />
On non-blank writable media xorriso appends the newly given disk files if command {{ic|-dev}} is used rather than {{ic|-outdev}}. Of course, no command {{ic|-blank}} should be given here<br />
<br />
$ xorriso -dev /dev/sr0 \<br />
-volid "ARCHIVE_2013_07_28" -joliet on -add ./more_for_iso --<br />
<br />
For details see the [https://www.gnu.org/software/xorriso/man_1_xorriso.html manual page] and especially its [https://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES examples]<br />
<br />
=== BD Defect Management ===<br />
<br />
BD-RE and formatted BD-R media are normally written with enabled Defect Management. This feature reads the written blocks while they are still stored in the drive buffer. In case of poor read quality the blocks get written again or redirected to the ''Spare Area'' where the data get stored in replacement blocks.<br />
<br />
This checkreading reduces write speed to at most half of the nominal speed of drive and BD medium. Sometimes it is even worse. Heavy use of the Spare Area causes long delays during read operations. So Defect Management is not always desirable.<br />
<br />
{{ic|cdrecord}} does not format BD-R. It has no means to prevent Defect Management on BD-RE media, though.<br />
<br />
{{ic|growisofs}} formats BD-R by default. This can be prevented by option {{ic|1= -use-the-force-luke=spare:none}}. It has no means to prevent Defect Management on BD-RE media, though.<br />
<br />
{{ic|cdrskin}}, {{ic|xorriso}}, and {{ic|xorrecord}} do not format BD-R by default. They do with {{ic|1= cdrskin blank=format_if_needed}}, resp. {{ic|1= xorriso -format as_needed}}, resp. {{ic|1= xorrecord blank=format_overwrite}}.<br />
These three programs can disable Defect Management with BD-RE and already formatted BD-R by {{ic|1= cdrskin stream_recording=on}}, resp. {{ic|1= xorriso -stream_recording on}}, resp. {{ic|1= xorrecord stream_recording=on}}.<br />
<br />
=== Burning an audio CD ===<br />
<br />
Create your audio tracks and store them as uncompressed, 16-bit, stereo WAV files. To convert MP3 to WAV, ensure {{Pkg|lame}} is installed, {{ic|cd}} to the directory with your MP3 files, and run:<br />
<br />
$ for i in *.mp3; do lame --decode "$i" "$(basename "$i" .mp3)".wav; done<br />
<br />
In case you get an error when trying to burn WAV files converted with LAME, try decoding with {{Pkg|mpg123}}:<br />
<br />
$ for i in *.mp3; do mpg123 --rate 44100 --stereo --buffer 3072 --resync -w $(basename $i .mp3).wav $i; done<br />
<br />
Name the audio files in a manner that will cause them to be listed in the desired track order when listed alphabetically, such as {{ic|01.wav}}, {{ic|02.wav}}, {{ic|03.wav}}, etc.<br />
Use the following command to simulate burning the WAV files as an audio CD:<br />
<br />
$ wodim -dummy -v -pad speed=1 dev=/dev/sr0 -dao -swab *.wav<br />
<br />
In case you detect errors or empty tracks like:<br />
<br />
Track 01: audio 0 MB (00:00.00) no preemp pad<br />
<br />
try another decoder (e.g. mpg123) or try using ''cdrecord'' from the {{Pkg|cdrtools}} package.<br />
<br />
Note that {{Pkg|cdrkit}} also contains a ''cdrecord'' command, but it is just a softlink to ''wodim''.<br />
If anything worked, you can remove the dummy flag to actually burn the CD.<br />
<br />
To test the new audio CD, use [[MPlayer]]:<br />
<br />
$ mplayer cdda://<br />
<br />
=== Burning a bin/cue ===<br />
<br />
To burn a bin/cue image run:<br />
<br />
$ cdrdao write --device /dev/sr0 image.cue<br />
<br />
==== TOC/CUE/BIN for mixed-mode disks ====<br />
<br />
ISO images only store a single data track. If you want to create an image of a mixed-mode disk (data track with multiple audio tracks) then you need to make a TOC/BIN pair:<br />
<br />
$ cdrdao read-cd --read-raw --datafile IMAGE.bin --driver generic-mmc:0x20000 --device /dev/cdrom IMAGE.toc<br />
<br />
Some software only likes CUE/BIN pair, you can make a CUE sheet with {{ic|toc2cue}} (part of {{ic|cdrdao}}):<br />
<br />
$ toc2cue IMAGE.toc IMAGE.cue<br />
<br />
=== Burn backend problems ===<br />
<br />
If you experience problems, you may ask for advise at mailing list [mailto:cdwrite@other.debian.org cdwrite@other.debian.org] . Or ask for advise at the support mail addresses if some are listed near the end of the program's man page.<br />
<br />
Tell the command lines you tried, the medium type (e.g. CD-R, DVD+RW, ...), and the symptoms of failure (program messages, disappointed user expectation, ...).<br />
You will possibly get asked to obtain the newest release or development version of the affected program and to make test runs. But the answer might as well be, that your drive dislikes the particular medium.<br />
<br />
=== Burning CD/DVD/BD with a GUI ===<br />
<br />
{{Wikipedia|Comparison of disc authoring software|Wikipedia - Comparison of disc authoring software}}<br />
There are several applications available to burn CDs in a graphical environment.<br />
<br />
==== Free GUI Programs ====<br />
<br />
* {{App|[[Wikipedia:AcetoneISO|AcetoneISO]]|All-in-one ISO tool (supports BIN, MDF, NRG, IMG, DAA, DMG, CDI, B5I, BWI, PDI and ISO).|http://sourceforge.net/projects/acetoneiso|{{Pkg|acetoneiso2}}}}<br />
* {{App|BashBurn|Lightweight terminal based menu frontend for CD/DVD burning tools.|http://bashburn.dose.se/|{{Pkg|bashburn}}}}<br />
* {{App|[[Wikipedia:Brasero (software)|Brasero]]|Disc burning application for the GNOME desktop that is designed to be as simple as possible. Part of {{Grp|gnome-extra}}.|https://wiki.gnome.org/Apps/Brasero|{{Pkg|brasero}}}}<br />
* {{App|cdw|Ncurses frontend to cdrecord, mkisofs, growisofs, dvd+rw-mediainfo, dvd+rw-format, xorriso.|http://cdw.sourceforge.net/|{{AUR|cdw}}}}<br />
* {{App|[[Wikipedia:GnomeBaker|GnomeBaker]]|Full featured CD/DVD burning application for the GNOME desktop.|http://gnomebaker.sourceforge.net/|{{AUR|gnomebaker}}}}<br />
* {{App|Graveman|GTK-based CD/DVD burning application. It requires configuration to point to correct devices.|http://graveman.tuxfamily.org/|{{AUR|graveman}}}}<br />
* {{App|[[Wikipedia:ISO_Master|isomaster]]|ISO image editor.|http://littlesvr.ca/isomaster|{{AUR|isomaster}}}}<br />
* {{App|[[Wikipedia:K3b|K3b]]|Feature-rich and easy to handle CD burning application based on KDElibs.|http://www.k3b.org/|{{Pkg|k3b}}}}<br />
* {{App|Silicon empire|Qt-based set of tools to manage and organize your optical discs like CDs, DVDs and Blu-rays.|http://getsilicon.org/|{{AUR|silicon-empire}}}}<br />
* {{App|[[Wikipedia:X-CD-Roast|X-CD-Roast]]|Lightweight cdrtools front-end for CD and DVD writing.|http://www.xcdroast.org/|{{AUR|xcdroast}}}}<br />
* {{App|Xfburn|Simple front-end to the libburnia libraries with support for CD/DVD(-RW), ISO images, and BurnFree.|http://goodies.xfce.org/projects/applications/xfburn|{{Pkg|xfburn}}}}<br />
* {{App|xorriso-tcltk|Graphical front-end to ISO and CD/DVD/BD burn tool xorriso|https://www.gnu.org/software/xorriso/xorriso-tcltk-screen.gif|{{Pkg|libisoburn}}}}<br />
<br />
==== Nero Linux ====<br />
<br />
Nero Linux is a commercial burning suite from makers of Nero for Windows - Nero AG. The biggest advantage of Nero Linux is its interface which similar to window version. Hence, users migrating from windows might find it easy to operate. The Linux version now includes Nero Express, a wizard which takes users through the process of burning CDs and DVDs step-by-step, which users will be familiar with from the Windows version. Also new in version 4 is Blu-ray Disc defect management, integration of Isolinux for creating bootable media and support for Musepack and AIFF audio formats...<br />
<br />
Nero Linux 4 retails at $19.99 with a free trial version also available.<br />
<br />
* [http://www.nero.com/enu/promo-linux.html Nero Linux 4]<br />
* {{AUR|nerolinux}} [[AUR]] package.<br />
<br />
Nero Linux offers some features, like:<br />
<br />
* Easy, wizard-style user interface for guided burning with Nero Linux Express 4.<br />
* Full Blu-ray burning support.<br />
* Supports burning of audio CD (CD-DA), ISO 9660 (Joliet support), CD-text, ISOLINUX bootable, Multi-session discs, DVD-Video and miniDVD, DVD double layer support.<br />
* Advanced burning with Nero Burning ROM and command line client.<br />
<br />
{{Note|The necessary {{ic|sg}} module should be loaded automatically, otherwise see [[Kernel modules#Configuration]] for information about manual configuration.}}<br />
<br />
== DVD playing ==<br />
<br />
[[Wikipedia:DVD|DVD]], also known as Digital Versatile Disc or Digital Video Disc, is an optical disc storage media format used for video and data storage.<br />
<br />
If you wish to play encrypted DVDs, you must install the libdvd* packages:<br />
* {{Pkg|libdvdread}}<br />
* {{Pkg|libdvdcss}}<br />
* {{Pkg|libdvdnav}}<br />
<br />
Additionally, you must install player software. Popular DVD players are [[MPlayer]], [[Wikipedia:Xine|xine]] and [[VLC]]. See the [[List_of_Applications/Multimedia#Video_players|video players]] list and the specific instructions for [[MPlayer#DVD playing|MPlayer]].<br />
<br />
== Ripping ==<br />
<br />
[[Wikipedia:Ripping|Ripping]] is the process of copying audio or video content to a hard disk, typically from removable media or media streams.<br />
<br />
=== CD ===<br />
<br />
* {{App|[[Wikipedia:ABCDE|Abcde]]|Comprehensive command-line tool for ripping audio CDs.|http://code.google.com/p/abcde/|{{Pkg|abcde}}}}<br />
* {{App|[[Wikipedia:Asunder|Asunder]]|GTK+-based CD ripping program.|http://littlesvr.ca/asunder/|{{Pkg|asunder}}}}<br />
* {{App|[[Wikipedia:cdparanoia|cdparanoia]]|Compact Disc Digital Audio (CDDA) Digital Audio Extraction (DAE) tool.|http://xiph.org/paranoia/index.html|{{Pkg|cdparanoia}}}}<br />
* {{App|Gnac|Audio converter for GNOME.|http://gnac.sourceforge.net/|{{Pkg|gnac}}}}<br />
* {{App|Goobox|CD player and ripper for GNOME.|https://people.gnome.org/~paobac/goobox/|{{Pkg|goobox}}}}<br />
* {{App|[[Wikipedia:Grip (software)|Grip]]|Fast and light CD ripper within the GNOME project that resembles [[Wikipedia:Audiograbber|Audiograbber]].|http://sourceforge.net/projects/grip/|{{Pkg|grip}}}}<br />
* {{App|KAudioCreator|Program for ripping and encoding Audio CDs and encoding files from disk.|http://kde-apps.org/content/show.php/KAudioCreator?content&#61;107645|{{Pkg|kaudiocreator}}}}<br />
* {{App|morituri|CD ripper aiming for accuracy over speed.|http://thomas.apestaart.org/morituri/trac/|{{Pkg|morituri}}}}<br />
* {{App|ripperX|GTK+ program to rip and encode MP3 files.|http://sourceforge.net/projects/ripperx/|{{Pkg|ripperx}}}}<br />
* {{App|rubyripper|Audiodisk ripper that tries to deliver a secure rip through multiple rippings of the same track and corrections of any differences.|http://code.google.com/p/rubyripper/|{{Pkg|rubyripper}}}}<br />
* {{App|[[Wikipedia:Sound Juicer|Sound Juicer]]|CD ripper for GNOME.|http://burtonini.com/blog/computers/sound-juicer|{{Pkg|sound-juicer}}}}<br />
* {{App|soundKonverter|Front-end to various audio converters.|http://www.kde-apps.org/content/show.php?content&#61;29024|{{Pkg|soundkonverter}}}}<br />
<br />
=== DVD ===<br />
<br />
Often, the process of ripping a DVD can be broken down into two subtasks:<br />
# '''Data extraction''' - Copying the audio and/or video data to a hard disk,<br />
# [[Wikipedia:Transcode|Transcoding]] - Converting the extracted data into a suitable format.<br />
<br />
Some utilities perform both tasks, whilst others focus on one aspect or the other:<br />
<br />
* {{App|dvd-vr|Tool which easily converts VRO files extracted from a [[Wikipedia:DVD-VR|DVD-VR]] and splits them in regular VOB files.|http://www.pixelbeat.org/programs/dvd-vr/|{{AUR|dvd-vr}}}}<br />
* {{App|[[dvdbackup]]|Tool for pure data extraction which does not transcode. It is useful for creating ''exact'' copies of encrypted DVDs in conjunction with '''libdvdcss''' or for decrypting video for other utilities unable to read encrypted DVDs.|http://dvdbackup.sourceforge.net/|{{Pkg|dvdbackup}}}}<br />
* {{App|[[FFmpeg]]|Complete and free Internet live audio and video broadcasting solution for Linux/Unix, capable to do a direct rip in any format (audio/video) from a DVD-Video ISO image, just select the input as the ISO image and proceed with the desired options. It also allows to downmixing, shrinking, spliting, selecting streams among other features.|http://ffmpeg.org/|See [[FFmpeg#Package_installation|article]]}}<br />
* {{App|HandBrake|Multithreaded video transcoder, which offers both a graphical and command-line interface with many preset configurations.|http://handbrake.fr/|{{Pkg|handbrake}}}}<br />
* {{App|Hybrid|Multi platform Qt based frontend for a bunch of other tools which can convert nearly every input to x264/Xvid/VP8 + ac3/ogg/mp3/aac/flac inside an mp4/m2ts/mkv/webm/mov/avi container, a Blu-ray or an AVCHD structure.|http://www.selur.de/|{{AUR|hybrid-encoder}}}}<br />
* {{App|[[MEncoder]]|Free command line video decoding, encoding and filtering tool released under the GNU General Public License. It is a close sibling to MPlayer and can convert all the formats that MPlayer understands into a variety of compressed and uncompressed formats using different codecs. Wrapper programs like {{AUR|h264enc}} and {{AUR|undvd}} can provide an assistive interface. Many [[MEncoder#GUI frontends|front-ends]] are available.|http://www.mplayerhq.hu/|{{Pkg|mencoder}}}}<br />
* {{App|Transcode|Video/DVD ripper and encoder for the terminal/console.|http://tcforge.berlios.de/|{{Pkg|transcode}}}}<br />
<br />
==== dvd::rip ====<br />
<br />
dvd::rip is a front-end to {{Pkg|transcode}}, used to extract and transcode on-the-fly.<br />
<br />
The following packages should be installed:<br />
* {{Pkg|dvdrip}}: GTK front-end for {{Pkg|transcode}}, which performs the ripping and encoding<br />
* {{Pkg|libdv}}: Software codec for DV video<br />
* {{Pkg|xvidcore}}: If you want to encode your ripped files as XviD, an open source MPEG-4 video codec (free alternative to DivX)<br />
* {{AUR|divx4linux}}: If you want to encode your ripped files as DivX (available in the [[AUR]])<br />
<br />
The dvd::rip preferences are mostly well-documented/self-explanatory. If you need help with something, see http://www.exit1.org/dvdrip/doc/gui-gui_pref.cipp.<br />
<br />
Ripping a DVD is often a simple matter of selecting the preferred codec(s), selecting the desired titles, then clicking the "Rip" button.<br />
<br />
== Troubleshooting ==<br />
<br />
=== K3b locale error ===<br />
<br />
When running K3B, if the following message appears:<br />
<br />
System locale charset is ANSI_X3.4-1968<br />
Your system's locale charset (i.e. the charset used to encode file names) is <br />
set to ANSI_X3.4-1968. It is highly unlikely that this has been done intentionally.<br />
Most likely the locale is not set at all. An invalid setting will result in<br />
problems when creating data projects.Solution: To properly set the locale <br />
charset make sure the LC_* environment variables are set. Normally the distribution <br />
setup tools take care of this.<br />
<br />
It means that your locale is not set well.<br />
<br />
To fix it,<br />
<br />
* Remove {{ic|/etc/locale.gen}}<br />
* Re-install {{Pkg|glibc}}<br />
* Edit {{ic|/etc/locale.gen}}, uncommenting all lines lines that corresponds to your language AND the {{ic|en_US}} options, for compatibility:<br />
<br />
{{bc|<br />
en_US.UTF-8 UTF-8<br />
en_US ISO-8859-1<br />
}}<br />
* Re-generate the profiles with {{ic|locale-gen}}:<br />
{{hc|# locale-gen|<br />
Generating locales...<br />
en_US.UTF-8... done<br />
en_US.ISO-8859-1... done<br />
pt_BR.UTF-8... done<br />
pt_BR.ISO-8859-1... done<br />
Generation complete.<br />
}}<br />
<br />
More info [https://bbs.archlinux.org/viewtopic.php?pid=251512%29; here].<br />
<br />
=== Brasero fails to find blank discs ===<br />
<br />
Brasero uses {{Pkg|gvfs}} to manage CD/DVD burning devices. Also make sure that your session [[General troubleshooting#Session permissions|is not broken]].<br />
<br />
=== Brasero fails to normalize audio CD ===<br />
<br />
If you try to burn it may stop at the first step called Normalization.<br />
<br />
As a workaround you can disable the normalization plugin using the ''Edit > Plugins'' menu<br />
<br />
=== VLC: Error "... could not open the disc /dev/dvd" ===<br />
<br />
If you get the error, "vlc dvdread could not open the disc "/dev/dvd"" it may be because there is no device node {{ic|/dev/dvd}} on your system. Udev no longer creates {{ic|/dev/dvd}} and instead uses {{ic|/dev/sr0}}. To fix this, edit the VLC configuration file ({{ic|~/.config/vlc/vlcrc}}):<br />
<br />
# DVD device (string) <br />
dvd=/dev/sr0<br />
<br />
=== DVD drive is noisy ===<br />
<br />
If playing DVD videos causes the system to be very loud, it may be because the disk is spinning faster than it needs to. To temporarily change the speed of the drive, as root, run:<br />
<br />
# eject -x 12 /dev/dvd<br />
<br />
Sometimes:<br />
<br />
# hdparm -E12 /dev/dvd<br />
<br />
Any speed that is supported by the drive can be used, or 0 for the maximum speed.<br />
<br />
[http://hektor.umcs.lublin.pl/~mikosmul/computing/tips/cd-rom-speed.html Setting CD-ROM and DVD-ROM drive speed]<br />
<br />
=== Playback does not work with new computer (new DVD-Drive) ===<br />
<br />
If playback does not work and you have a new computer (new DVD-Drive) the reason might be that the [[Wikipedia:DVD region code|region code]] is not set. You can read and set the region code with {{AUR|regionset}} from the [[AUR]].<br />
<br />
=== None of the above programs are able to rip/encode a DVD to my hard disk! ===<br />
<br />
Make sure the region of your DVD reader is set correctly; otherwise, you will get loads of inexplicable CSS-related errors. Use {{AUR|regionset}} to do so.<br />
<br />
=== GUI program log indicates problems with backend program ===<br />
<br />
If you use a GUI program and experience problems which the program's log blames on some backend program, then try to reproduce the problem by the logged backend program arguments.<br />
Whether you succeed with reproducing or not, you may report the logged lines and your own findings to the places mentioned in [[#Burn backend problems|section Burn Backend Problems]].<br />
<br />
==== Special case: medium error / write error ====<br />
<br />
Here are some typical messages about the drive disliking the medium. This can only be solved by using a different drive or a different medium. A different program will hardly help.<br />
<br />
K3b with backend wodim:<br />
Sense Bytes: 70 00 03 00 00 00 00 12 00 00 00 00 0C 00 00 00<br />
Sense Key: 0x3 Medium Error, Segment 0<br />
Sense Code: 0x0C Qual 0x00 (write error) Fru 0x0<br />
<br />
Brasero with backend growisofs:<br />
BraseroGrowisofs stderr: :-[ WRITE@LBA=0h failed with SK=3h/ASC=0Ch/ACQ=00h]: Input/output error<br />
<br />
Brasero with backend libburn:<br />
BraseroLibburn Libburn reported an error SCSI error on write(16976,16): [3 0C 00] Write error<br />
<br />
=== AHCI ===<br />
<br />
If your new DVD-Drive is detected but will not mount, check wether your BIOS uses [[AHCI]] and add the module to the kernel image.<br />
<br />
Edit {{ic|/etc/mkinitcpio.conf}} and add {{ic|ahci}} to the {{ic|MODULES}} variable (see [[mkinitcpio]] for details):<br />
MODULES="ahci"<br />
<br />
Rebuild the kernel image so that it includes the newly added module:<br />
# mkinitcpio -p linux<br />
<br />
== See also ==<br />
<br />
* RIAA and actual laws allow backup of physically obtained media under these conditions [https://www.riaa.com/physicalpiracy.php?content_selector=piracy_online_the_law RIAA - the law].<br />
* [[Convert any Movie to DVD Video]]<br />
* [http://libburnia-project.org/ Main page of the project Libburnia]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=Optical_disc_drive&diff=339469Optical disc drive2014-10-10T00:41:47Z<p>Jstjohn: /* Burning an ISO image to CD, DVD, or BD */ improve grammar; add italics around "growisofs" in prose</p>
<hr />
<div>[[Category:Optical]]<br />
[[Category:Audio/Video]]<br />
[[es:Optical Disc Drive]]<br />
[[it:Optical Disc Drive]]<br />
[[ja:Optical Disc Drive]]<br />
[[zh-CN:Optical Disc Drive]]<br />
{{Related articles start}}<br />
{{Related|Codecs}}<br />
{{Related|MPlayer}}<br />
{{Related|dvdbackup}}<br />
{{Related|MEncoder}}<br />
{{Related|BluRay}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Optical disc drive|Wikipedia]]<br />
<br />
:''In computing, an optical disc drive (ODD) is a disk drive that uses laser light or electromagnetic waves within or near the visible light spectrum as part of the process of reading or writing data to or from optical discs. Some drives can only read from discs, but recent drives are commonly both readers and recorders, also called burners or writers. Compact discs, DVDs, and Blu-ray discs are common types of optical media which can be read and recorded by such drives. Optical drive is the generic name; drives are usually described as "CD" "DVD", or "Blu-ray", followed by "drive", "writer", etc.''<br />
<br />
== Burning ==<br />
<br />
The burning process of optical disc drives consists of creating or obtaining an image and writing it to an optical medium. The image may in principle be any data file. If you want to mount the resulting medium, then it is usually an ISO 9660 file system image file. Audio and multi-media CDs are often burned from a BIN file, under control of a TOC file or a CUE file which tell the desired track layout.<br />
<br />
=== Install burning utilities ===<br />
<br />
If you want to use programs with graphical user interface, then follow [[#Burning CD/DVD/BD with a GUI|this link to the list of GUI programs]].<br />
<br />
The programs listed here are the back ends which are used by most free GUI programs for CD, DVD, and BD. They are command line oriented. GUI users might get to them when it comes to troubleshooting or to scripting of burn activities.<br />
<br />
You need at least one program for creation of file system images and one program that is able to burn data onto your desired media type.<br />
<br />
Available programs for ISO 9660 image creation are:<br />
<br />
* {{ic|genisoimage}} from package {{Pkg|cdrkit}}<br />
* {{ic|mkisofs}} from package {{Pkg|cdrtools}}<br />
* {{ic|xorriso}} and {{ic|xorrisofs}} from package {{Pkg|libisoburn}}<br />
<br />
The traditional choice is {{ic|genisoimage}}.<br />
<br />
Available programs for burning to media are:<br />
<br />
* {{ic|cdrdao}} from package {{Pkg|cdrdao}} (CD only, TOC/CUE/BIN only)<br />
* {{ic|cdrecord}} from package {{Pkg|cdrtools}}<br />
* {{ic|cdrskin}} from package {{Pkg|libburn}}<br />
* {{ic|growisofs}} from package {{Pkg|dvd+rw-tools}} (DVD and BD only)<br />
* {{ic|wodim}} from package {{Pkg|cdrkit}} (CD only, DVD deprecated)<br />
* {{ic|xorriso}} and {{ic|xorrecord}} from package {{Pkg|libisoburn}}<br />
<br />
The traditional choices are {{ic|wodim}} for CD and {{ic|growisofs}} for DVD and Blu-ray Disk. For growisofs and BD-R see the bug workaround below.<br />
For writing TOC/CUE/BIN files to CD, install {{ic|cdrdao}}.<br />
<br />
The free GUI programs for CD, DVD, and BD burning depend on at least one of the above packages.<br />
<br />
The programs {{ic|genisoimage}}, {{ic|mkisofs}}, and {{ic|xorrisofs}} all three support the genisoimage options which are shown in this document.<br />
<br />
The programs {{ic|cdrecord}}, {{ic|cdrskin}}, and {{ic|wodim}} all three support the shown wodim options. Program {{ic|xorrecord}} supports those which do not deal with audio CD.<br />
<br />
{{Note|<br />
* The installed files of packages {{Pkg|cdrkit}} and {{Pkg|cdrtools}} are in conflict. Install only one of them.<br />
* If you want to install [[wikipedia:Cdrtools|cdrtools]], make sure that you build a package using [[makepkg]] and install with [[pacman]]. Pacman wrappers may resolve to cdrkit instead.<br />
}}<br />
<br />
=== Making an ISO image from existing files on hard disk ===<br />
<br />
The simplest way to create an ISO image is to first copy the needed files to one folder, for example: {{ic|./for_iso}}.<br />
<br />
Then use {{ic|genisoimage}} in the manner of the following example:<br />
<br />
$ genisoimage -V "ARCHIVE_2013_07_27" -J -r -o isoimage.iso ./for_iso<br />
<br />
Each of those flags/switches are explained in the following sections.<br />
<br />
==== Basic switches ====<br />
;-V: Specifies the name (that is assigned to) of the file system. The ISO 9660 standard specs impose the limitations of 32-character string length, as well as limiting the characters allowed to sets of: "A" to "Z", "0" to "9", and "_". This volume label will probably show up as mount point if the medium is mounted automatically.<br />
;-J: Prepares names of up to 64 UTF-16 characters for MS-Windows readers. Also known as "Joliet".<br />
;-joliet-long: Would allow 103 UTF-16 characters for MS-Windows readers. Non-compliant to Joliet specs.<br />
;-r: Prepares names of up to 255 characters for Unix readers and gives read permission for everybody. Also known as "Rock Ridge".<br />
;-o: Sets the file path for the resulting ISO image.<br />
<br />
==== graft-points ====<br />
<br />
It is also possible to let genisoimage collect files and directories from various paths<br />
<br />
$ genisoimage -V "BACKUP_2013_07_27" -J -r -o backup_2013_07_27.iso \<br />
-graft-points \<br />
/photos=/home/user/photos \<br />
/mail=/home/user/mail \<br />
/photos/holidays=/home/user/holidays/photos<br />
<br />
;-graft-points: Enables the recognition of ''pathspecs'' which consist of a target address in the ISO file system (e.g. {{ic|/photos}}) and a source address on hard disk (e.g. {{ic|/home/user/photos}}). Both are separated by a "=" character.<br />
<br />
So this example puts the disk directory {{ic|/home/user/photos}}, {{ic|/home/user/mail}} and {{ic|/home/user/holidays/photos}}, respectively in the ISO image as {{ic|/photos}}, {{ic|/mail}} and {{ic|/photos/holidays}}.<br />
<br />
Programs ''mkisofs'' and ''xorrisofs'' accept the same options. For secure backups, consider using ''xorrisofs'' with option {{ic|--for_backup}}, which records eventual ACLs and stores an MD5 checksum for each data file.<br />
<br />
See the manuals of the ISO 9660 programs for more info about their options:<br />
*[http://linux.die.net/man/1/genisoimage genisoimage]<br />
*[http://cdrtools.sourceforge.net/private/man/cdrecord/index.html mkisofs]<br />
*[https://www.gnu.org/software/xorriso/man_1_xorrisofs.html xorrisofs]<br />
<br />
{{Tip|This process can be thought of alternately as:<br />
* creating an archive (which is not that different, on one level, from creating a ZIP archive or tarball (e.g. ''.tar.gz''))<br />
* creating and ''populating'' a file system volume, manifested in the form of a "disk" image (file), which preserves as much as possible (content, name, relative directory structure/hierarchy/placement, and possibly other file system overhead metadata / properties (aspects)) such as timestamp(s), ownership, permissions.}}<br />
<br />
=== Mounting an ISO image ===<br />
<br />
To test if the ISO image is proper, you can mount it (as root):<br />
<br />
# mount -t iso9660 -o ro,loop=/dev/loop0 cd_image /cdrom<br />
<br />
You have to first load the loop module:<br />
<br />
# modprobe loop<br />
<br />
Do not forget to unmount the image when your inspection of the image is done:<br />
<br />
# umount /cdrom<br />
<br />
See also [[Mounting images as user]] for mounting without root privileges.<br />
<br />
=== Converting img/ccd to an ISO image ===<br />
<br />
To convert an {{ic|img}}/{{ic|ccd}} image, you can use {{Pkg|ccd2iso}}:<br />
<br />
$ ccd2iso ~/image.img ~/image.iso<br />
<br />
=== Learning the name of your optical drive ===<br />
<br />
For the remainder of this section the name of your recording device is assumed to be {{ic|/dev/sr0}}.<br />
<br />
Check this by<br />
<br />
$ wodim dev=/dev/sr0 -checkdrive<br />
<br />
which should report "Vendor_info" and "Identification" of the drive.<br />
<br />
If no drive is found, check whether any {{ic|/dev/sr*}} exist and whether they offer read/write permission ({{ic|wr-}}) to you or your group.<br />
If no {{ic|/dev/sr*}} exists then try<br />
<br />
# modprobe sr_mod<br />
<br />
=== Reading the volume label of a CD or DVD ===<br />
<br />
If you want to get the name/label of the media, use dd:<br />
<br />
$ dd if=/dev/sr0 bs=1 skip=32808 count=32<br />
<br />
=== Reading an ISO image from a CD, DVD, or BD ===<br />
<br />
You should determine the size of the ISO file system before copying it to hard disk. Most media types deliver more data than was written to them with the most recent burn run.<br />
<br />
Use program {{ic|isosize}} out of package {{Pkg|util-linux}} to obtain the image size<br />
<br />
$ blocks=$(expr $(isosize /dev/sr0) / 2048)<br />
<br />
Have a look whether the obtained number of blocks is plausible<br />
<br />
{{hc|$ echo "That would be $(expr $blocks / 512) MB"|<br />
That would be 589 MB<br />
}}<br />
<br />
Then copy the determined amount of data from medium to hard disk :<br />
<br />
$ dd if=/dev/sr0 of=isoimage.iso bs=2048 count=$blocks<br />
<br />
Omit {{ic|1= count=$blocks}} if you did not determine the size. You will probably get more data than needed. The resulting file will nevertheless be mountable. It should still fit onto a medium of the same type as the medium from which the image was copied.<br />
<br />
If the original medium was bootable, then the copy will be a bootable image. You may use it as pseudo CD for a virtual machine or burn it onto optical media which should then become bootable.<br />
<br />
=== Erasing CD-RW and DVD-RW ===<br />
<br />
Used CD-RW media need to be erased before you can write over the previously recorded data. This is done by<br />
<br />
$ wodim -v dev=/dev/sr0 blank=fast<br />
<br />
Unformatted DVD-RW media need the same treatment before re-use. But fast blanking deprives them of the capability for multi-session and recording of streams of unpredicted length. So one should apply<br />
<br />
$ dvd+rw-format -blank=full /dev/sr0<br />
<br />
{{ic|1= dvd+rw-format}} is part of package {{Pkg|dvd+rw-tools}}. Alternative commands are<br />
$ cdrecord -v dev=/dev/sr0 blank=all<br />
$ cdrskin -v dev=/dev/sr0 blank=all<br />
$ xorriso -outdev /dev/sr0 -blank as_needed<br />
<br />
Formatted DVD-RW media can be overwritten without such erasure. So consider to apply once in their life time<br />
<br />
$ dvd+rw-format -force /dev/sr0<br />
<br />
Alternative commands are <br />
$ cdrskin -v dev=/dev/sr0 blank=format_overwrite<br />
$ xorriso -outdev /dev/sr0 -format as_needed<br />
<br />
All other media are either write-once (CD-R, DVD-R, DVD+R, BD-R) or are overwritable without the need for erasing (DVD-RAM, DVD+RW, BD-RE).<br />
<br />
=== Burning an ISO image to CD, DVD, or BD ===<br />
<br />
To burn a readily prepared ISO image file {{ic|isoimage.iso}} onto an optical medium, run for CD:<br />
<br />
$ wodim -v -sao dev=/dev/sr0 isoimage.iso<br />
<br />
and for DVD or BD:<br />
<br />
$ growisofs -dvd-compat -Z /dev/sr0=isoimage.iso<br />
<br />
The programs {{ic|cdrecord}}, {{ic|cdrskin}}, and {{ic|xorrecord}} may be used on all kinds of media with the options shown with {{ic|wodim}}.<br />
<br />
{{Note|<br />
* Make sure that the medium is not mounted when you begin to write to it. Mounting may happen automatically if the medium contains a readable file system. In the best case, it will prevent the burn programs from using the burner device. In the worst case, there will be misburns because read operations disturbed the drive.<br />
So if in doubt, do:<br />
# umount /dev/sr0<br />
* {{ic|growisofs}} has a small bug with blank BD-R media. It issues an error message after the burning is complete. Programs like {{ic|k3b}} then believe the whole burn run failed.<br />
To prevent this, either<br />
** format the blank BD-R by {{ic|dvd+rw-format /dev/sr0}} before submitting it to ''growisofs''<br />
** or use ''growisofs'' option {{ic|1= -use-the-force-luke=spare:none}}<br />
}}<br />
<br />
=== Verifying the burnt ISO image ===<br />
<br />
You can verify the integrity of the burnt medium to make sure it contains no errors. Always eject the medium and reinsert it before verifying. The kernel will learn about the new content only by that reinsertion.<br />
<br />
First calculate the MD5 checksum of the original ISO image:<br />
<br />
{{hc|$ md5sum isoimage.iso|<br />
e5643e18e05f5646046bb2e4236986d8 isoimage.iso<br />
}}<br />
<br />
Next calculate the MD5 checksum of the ISO file system on the medium.<br />
Although some media types deliver exactly the same amount of data as have been submitted to the burn program, many others append trailing garbage when being read. So you should restrict reading to the size of the ISO image file.<br />
<br />
$ blocks=$(expr $(du -b isoimage.iso | awk '{print $1}') / 2048)<br />
<br />
{{hc|<nowiki>$ dd if=/dev/sr0 bs=2048 count=$blocks | md5sum</nowiki>|<br />
43992+0 records in<br />
43992+0 records out<br />
90095616 bytes (90 MB) copied, 0.359539 s, 251 MB/s<br />
e5643e18e05f5646046bb2e4236986d8 -<br />
}}<br />
<br />
Both runs should yield the same MD5 checksum (here: {{ic|e5643e18e05f5646046bb2e4236986d8}}). If they do not, you will probably also get an I/O error message from the {{ic|dd}} run. {{ic|dmesg}} might then tell about SCSI errors and block numbers, if you are interested.<br />
<br />
=== ISO 9660 and Burning On-The-Fly ===<br />
<br />
It is not necessary to store an emerging ISO file system on hard disk before writing it to optical media. Only very old CD drives at very old computers could suffer failed burns due to empty drive buffer.<br />
<br />
If you omit option {{ic|-o}} from {{ic|genisoimage}} then it writes the ISO image to standard output. This can be piped into the standard input of burn programs.<br />
<br />
$ genisoimage -V "ARCHIVE_2013_07_27" -J -r ./for_iso | \<br />
wodim -v dev=/dev/sr0 -waiti -<br />
<br />
Option {{ic|-waiti}} is not really needed here. It prevents {{ic|wodim}} from writing to the medium before {{ic|genisoimage}} starts its output. This would allow {{ic|genisoimage}} to read the medium without disturbing an already started burn run. See next section about multi-session.<br />
<br />
On DVD and BD, you may let{{ic|growisofs}} operate {{ic|genisoimage}} for you and burn its output on-the-fly<br />
<br />
$ export MKISOFS="genisoimage"<br />
$ growisofs -Z /dev/sr0 -V "ARCHIVE_2013_07_27" -r -J ./for_iso<br />
<br />
=== Multi-session ===<br />
<br />
ISO 9660 multi-session means that a medium with readable file system is still writable at its first unused block address, and that a new ISO directory tree gets written to this unused part.<br />
The new tree is accompanied by the content blocks of newly added or overwritten data files. The blocks of data files, which shall stay as in the old ISO tree, will not be written again.<br />
<br />
Linux and many other operating systems will mount the directory tree in the last session on the medium. This youngest tree will normally show the files of the older sessions, too.<br />
<br />
==== Multi-session by wodim ====<br />
<br />
CD-R and CD-RW stay writable (aka "appendable") if wodim option {{ic|-multi}} was used<br />
<br />
$ wodim -v -multi dev=/dev/sr0 isoimage.iso<br />
<br />
Then the medium can be inquired for the parameters of the next session<br />
<br />
$ m=$(wodim dev=/dev/sr0 -msinfo)<br />
<br />
By help of these parameters and of the readable medium in the drive you can produce the add-on ISO session<br />
<br />
$ genisoimage -M /dev/sr0 -C "$m" \<br />
-V "ARCHIVE_2013_07_28" -J -r -o session2.iso ./more_for_iso<br />
<br />
Finally append the session to the medium and keep it appendable again<br />
<br />
$ wodim -v -multi dev=/dev/sr0 session2.iso<br />
<br />
Programs {{ic|cdrskin}} and {{ic|xorrecord}} do this too with DVD-R, DVD+R, BD-R and unformatted DVD-RW. Program {{ic|cdrecord}} does multi-session with at least DVD-R and DVD-RW. They all do with CD-R and CD-RW, of course.<br />
<br />
Most re-usable media types do not record a session history that would be recognizable for a mounting kernel. But with ISO 9660 it is possible to achieve the multi-session effect even on those media.<br />
<br />
{{ic|growisofs}} and {{ic|xorriso}} can do this and hide most of the complexity.<br />
<br />
==== Multi-session by growisofs ====<br />
<br />
{{ic|growisofs}} forwards most of its program arguments to a program that is compatible to {{ic|mkisofs}}. See above examples of {{ic|genisoimage}}.<br />
It bans option {{ic|-o}} and deprecates option {{ic|-C}}.<br />
By default it uses the installed program named "mkisofs". You may let it choose one of the others by setting environment variable {{ic|MKISOFS}}<br />
<br />
$ export MKISOFS="genisoimage"<br />
$ export MKISOFS="xorrisofs"<br />
<br />
The wish to begin with a new ISO file system on the optical medium is expressed by option {{ic|-Z}}<br />
<br />
$ growisofs -Z /dev/sr0 -V "ARCHIVE_2013_07_27" -r -J ./for_iso<br />
<br />
The wish to append more files as new session to an existing ISO file system is expressed by option {{ic|-M}}<br />
<br />
$ growisofs -M /dev/sr0 -V "ARCHIVE_2013_07_28" -r -J ./more_for_iso<br />
<br />
For details see the [http://linux.die.net/man/1/growisofs growisofs manual] and the manuals of {{ic|genisoimage}}, {{ic|mkisofs}}, {{ic|xorrisofs}}.<br />
<br />
==== Multi-session by xorriso ====<br />
<br />
{{ic|xorriso}} learns the wish to begin with a new ISO file system from the blank state of the medium. So it is appropriate to blank it if it contains data. The command {{ic|-blank as_needed}} applies to all kinds of re-usable media and even to ISO images in data files on hard disk. It does not cause error if applied to a blank write-once medium.<br />
<br />
$ xorriso -outdev /dev/sr0 -blank as_needed \<br />
-volid "ARCHIVE_2013_07_27" -joliet on -add ./for_iso --<br />
<br />
On non-blank writable media xorriso appends the newly given disk files if command {{ic|-dev}} is used rather than {{ic|-outdev}}. Of course, no command {{ic|-blank}} should be given here<br />
<br />
$ xorriso -dev /dev/sr0 \<br />
-volid "ARCHIVE_2013_07_28" -joliet on -add ./more_for_iso --<br />
<br />
For details see the [https://www.gnu.org/software/xorriso/man_1_xorriso.html manual page] and especially its [https://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES examples]<br />
<br />
=== BD Defect Management ===<br />
<br />
BD-RE and formatted BD-R media are normally written with enabled Defect Management. This feature reads the written blocks while they are still stored in the drive buffer. In case of poor read quality the blocks get written again or redirected to the ''Spare Area'' where the data get stored in replacement blocks.<br />
<br />
This checkreading reduces write speed to at most half of the nominal speed of drive and BD medium. Sometimes it is even worse. Heavy use of the Spare Area causes long delays during read operations. So Defect Management is not always desirable.<br />
<br />
{{ic|cdrecord}} does not format BD-R. It has no means to prevent Defect Management on BD-RE media, though.<br />
<br />
{{ic|growisofs}} formats BD-R by default. This can be prevented by option {{ic|1= -use-the-force-luke=spare:none}}. It has no means to prevent Defect Management on BD-RE media, though.<br />
<br />
{{ic|cdrskin}}, {{ic|xorriso}}, and {{ic|xorrecord}} do not format BD-R by default. They do with {{ic|1= cdrskin blank=format_if_needed}}, resp. {{ic|1= xorriso -format as_needed}}, resp. {{ic|1= xorrecord blank=format_overwrite}}.<br />
These three programs can disable Defect Management with BD-RE and already formatted BD-R by {{ic|1= cdrskin stream_recording=on}}, resp. {{ic|1= xorriso -stream_recording on}}, resp. {{ic|1= xorrecord stream_recording=on}}.<br />
<br />
=== Burning an audio CD ===<br />
<br />
Create your audio tracks and store them as uncompressed, 16-bit stereo WAV files. To convert MP3 to WAV, ensure {{Pkg|lame}} is installed, {{ic|cd}} to the directoy with your MP3 files, and run:<br />
<br />
$ for i in *.mp3; do lame --decode "$i" "$(basename "$i" .mp3)".wav; done<br />
<br />
In case you get an error when trying to burn WAV files converted with lame try decoding with {{Pkg|mpg123}}:<br />
<br />
$ for i in *.mp3; do mpg123 --rate 44100 --stereo --buffer 3072 --resync -w $(basename $i .mp3).wav $i; done<br />
<br />
Name the audio files in a manner that will cause them to be listed in the desired track order when listed alphabetically, such as {{ic|01.wav}}, {{ic|02.wav}}, {{ic|03.wav}}, etc.<br />
Use the following command to simulate burning the wav files as an audio CD:<br />
<br />
$ wodim -dummy -v -pad speed=1 dev=/dev/sr0 -dao -swab *.wav<br />
<br />
In case you detect errors or empty tracks like:<br />
<br />
Track 01: audio 0 MB (00:00.00) no preemp pad<br />
<br />
try another decoder (e.g. mpg123) or try using cdrecord from the {{Pkg|cdrtools}} package.<br />
<br />
Note that {{Pkg|cdrkit}} also contains a cdrecord command but it is just a softlink to ''wodim''.<br />
If anything worked you can remove the dummy flag to really burn the CD<br />
<br />
To test the new audio CD, use [[MPlayer]]:<br />
<br />
$ mplayer cdda://<br />
<br />
=== Burning a bin/cue ===<br />
<br />
To burn a bin/cue image run:<br />
<br />
$ cdrdao write --device /dev/sr0 image.cue<br />
<br />
==== TOC/CUE/BIN for mixed-mode disks ====<br />
<br />
ISO images only store a single data track. If you want to create an image of a mixed-mode disk (data track with multiple audio tracks) then you need to make a TOC/BIN pair:<br />
<br />
$ cdrdao read-cd --read-raw --datafile IMAGE.bin --driver generic-mmc:0x20000 --device /dev/cdrom IMAGE.toc<br />
<br />
Some software only likes CUE/BIN pair, you can make a CUE sheet with {{ic|toc2cue}} (part of {{ic|cdrdao}}):<br />
<br />
$ toc2cue IMAGE.toc IMAGE.cue<br />
<br />
=== Burn backend problems ===<br />
<br />
If you experience problems, you may ask for advise at mailing list [mailto:cdwrite@other.debian.org cdwrite@other.debian.org] . Or ask for advise at the support mail addresses if some are listed near the end of the program's man page.<br />
<br />
Tell the command lines you tried, the medium type (e.g. CD-R, DVD+RW, ...), and the symptoms of failure (program messages, disappointed user expectation, ...).<br />
You will possibly get asked to obtain the newest release or development version of the affected program and to make test runs. But the answer might as well be, that your drive dislikes the particular medium.<br />
<br />
=== Burning CD/DVD/BD with a GUI ===<br />
<br />
{{Wikipedia|Comparison of disc authoring software|Wikipedia - Comparison of disc authoring software}}<br />
There are several applications available to burn CDs in a graphical environment.<br />
<br />
==== Free GUI Programs ====<br />
<br />
* {{App|[[Wikipedia:AcetoneISO|AcetoneISO]]|All-in-one ISO tool (supports BIN, MDF, NRG, IMG, DAA, DMG, CDI, B5I, BWI, PDI and ISO).|http://sourceforge.net/projects/acetoneiso|{{Pkg|acetoneiso2}}}}<br />
* {{App|BashBurn|Lightweight terminal based menu frontend for CD/DVD burning tools.|http://bashburn.dose.se/|{{Pkg|bashburn}}}}<br />
* {{App|[[Wikipedia:Brasero (software)|Brasero]]|Disc burning application for the GNOME desktop that is designed to be as simple as possible. Part of {{Grp|gnome-extra}}.|https://wiki.gnome.org/Apps/Brasero|{{Pkg|brasero}}}}<br />
* {{App|cdw|Ncurses frontend to cdrecord, mkisofs, growisofs, dvd+rw-mediainfo, dvd+rw-format, xorriso.|http://cdw.sourceforge.net/|{{AUR|cdw}}}}<br />
* {{App|[[Wikipedia:GnomeBaker|GnomeBaker]]|Full featured CD/DVD burning application for the GNOME desktop.|http://gnomebaker.sourceforge.net/|{{AUR|gnomebaker}}}}<br />
* {{App|Graveman|GTK-based CD/DVD burning application. It requires configuration to point to correct devices.|http://graveman.tuxfamily.org/|{{AUR|graveman}}}}<br />
* {{App|[[Wikipedia:ISO_Master|isomaster]]|ISO image editor.|http://littlesvr.ca/isomaster|{{AUR|isomaster}}}}<br />
* {{App|[[Wikipedia:K3b|K3b]]|Feature-rich and easy to handle CD burning application based on KDElibs.|http://www.k3b.org/|{{Pkg|k3b}}}}<br />
* {{App|Silicon empire|Qt-based set of tools to manage and organize your optical discs like CDs, DVDs and Blu-rays.|http://getsilicon.org/|{{AUR|silicon-empire}}}}<br />
* {{App|[[Wikipedia:X-CD-Roast|X-CD-Roast]]|Lightweight cdrtools front-end for CD and DVD writing.|http://www.xcdroast.org/|{{AUR|xcdroast}}}}<br />
* {{App|Xfburn|Simple front-end to the libburnia libraries with support for CD/DVD(-RW), ISO images, and BurnFree.|http://goodies.xfce.org/projects/applications/xfburn|{{Pkg|xfburn}}}}<br />
* {{App|xorriso-tcltk|Graphical front-end to ISO and CD/DVD/BD burn tool xorriso|https://www.gnu.org/software/xorriso/xorriso-tcltk-screen.gif|{{Pkg|libisoburn}}}}<br />
<br />
==== Nero Linux ====<br />
<br />
Nero Linux is a commercial burning suite from makers of Nero for Windows - Nero AG. The biggest advantage of Nero Linux is its interface which similar to window version. Hence, users migrating from windows might find it easy to operate. The Linux version now includes Nero Express, a wizard which takes users through the process of burning CDs and DVDs step-by-step, which users will be familiar with from the Windows version. Also new in version 4 is Blu-ray Disc defect management, integration of Isolinux for creating bootable media and support for Musepack and AIFF audio formats...<br />
<br />
Nero Linux 4 retails at $19.99 with a free trial version also available.<br />
<br />
* [http://www.nero.com/enu/promo-linux.html Nero Linux 4]<br />
* {{AUR|nerolinux}} [[AUR]] package.<br />
<br />
Nero Linux offers some features, like:<br />
<br />
* Easy, wizard-style user interface for guided burning with Nero Linux Express 4.<br />
* Full Blu-ray burning support.<br />
* Supports burning of audio CD (CD-DA), ISO 9660 (Joliet support), CD-text, ISOLINUX bootable, Multi-session discs, DVD-Video and miniDVD, DVD double layer support.<br />
* Advanced burning with Nero Burning ROM and command line client.<br />
<br />
{{Note|The necessary {{ic|sg}} module should be loaded automatically, otherwise see [[Kernel modules#Configuration]] for information about manual configuration.}}<br />
<br />
== DVD playing ==<br />
<br />
[[Wikipedia:DVD|DVD]], also known as Digital Versatile Disc or Digital Video Disc, is an optical disc storage media format used for video and data storage.<br />
<br />
If you wish to play encrypted DVDs, you must install the libdvd* packages:<br />
* {{Pkg|libdvdread}}<br />
* {{Pkg|libdvdcss}}<br />
* {{Pkg|libdvdnav}}<br />
<br />
Additionally, you must install player software. Popular DVD players are [[MPlayer]], [[Wikipedia:Xine|xine]] and [[VLC]]. See the [[List_of_Applications/Multimedia#Video_players|video players]] list and the specific instructions for [[MPlayer#DVD playing|MPlayer]].<br />
<br />
== Ripping ==<br />
<br />
[[Wikipedia:Ripping|Ripping]] is the process of copying audio or video content to a hard disk, typically from removable media or media streams.<br />
<br />
=== CD ===<br />
<br />
* {{App|[[Wikipedia:ABCDE|Abcde]]|Comprehensive command-line tool for ripping audio CDs.|http://code.google.com/p/abcde/|{{Pkg|abcde}}}}<br />
* {{App|[[Wikipedia:Asunder|Asunder]]|GTK+-based CD ripping program.|http://littlesvr.ca/asunder/|{{Pkg|asunder}}}}<br />
* {{App|[[Wikipedia:cdparanoia|cdparanoia]]|Compact Disc Digital Audio (CDDA) Digital Audio Extraction (DAE) tool.|http://xiph.org/paranoia/index.html|{{Pkg|cdparanoia}}}}<br />
* {{App|Gnac|Audio converter for GNOME.|http://gnac.sourceforge.net/|{{Pkg|gnac}}}}<br />
* {{App|Goobox|CD player and ripper for GNOME.|https://people.gnome.org/~paobac/goobox/|{{Pkg|goobox}}}}<br />
* {{App|[[Wikipedia:Grip (software)|Grip]]|Fast and light CD ripper within the GNOME project that resembles [[Wikipedia:Audiograbber|Audiograbber]].|http://sourceforge.net/projects/grip/|{{Pkg|grip}}}}<br />
* {{App|KAudioCreator|Program for ripping and encoding Audio CDs and encoding files from disk.|http://kde-apps.org/content/show.php/KAudioCreator?content&#61;107645|{{Pkg|kaudiocreator}}}}<br />
* {{App|morituri|CD ripper aiming for accuracy over speed.|http://thomas.apestaart.org/morituri/trac/|{{Pkg|morituri}}}}<br />
* {{App|ripperX|GTK+ program to rip and encode MP3 files.|http://sourceforge.net/projects/ripperx/|{{Pkg|ripperx}}}}<br />
* {{App|rubyripper|Audiodisk ripper that tries to deliver a secure rip through multiple rippings of the same track and corrections of any differences.|http://code.google.com/p/rubyripper/|{{Pkg|rubyripper}}}}<br />
* {{App|[[Wikipedia:Sound Juicer|Sound Juicer]]|CD ripper for GNOME.|http://burtonini.com/blog/computers/sound-juicer|{{Pkg|sound-juicer}}}}<br />
* {{App|soundKonverter|Front-end to various audio converters.|http://www.kde-apps.org/content/show.php?content&#61;29024|{{Pkg|soundkonverter}}}}<br />
<br />
=== DVD ===<br />
<br />
Often, the process of ripping a DVD can be broken down into two subtasks:<br />
# '''Data extraction''' - Copying the audio and/or video data to a hard disk,<br />
# [[Wikipedia:Transcode|Transcoding]] - Converting the extracted data into a suitable format.<br />
<br />
Some utilities perform both tasks, whilst others focus on one aspect or the other:<br />
<br />
* {{App|dvd-vr|Tool which easily converts VRO files extracted from a [[Wikipedia:DVD-VR|DVD-VR]] and splits them in regular VOB files.|http://www.pixelbeat.org/programs/dvd-vr/|{{AUR|dvd-vr}}}}<br />
* {{App|[[dvdbackup]]|Tool for pure data extraction which does not transcode. It is useful for creating ''exact'' copies of encrypted DVDs in conjunction with '''libdvdcss''' or for decrypting video for other utilities unable to read encrypted DVDs.|http://dvdbackup.sourceforge.net/|{{Pkg|dvdbackup}}}}<br />
* {{App|[[FFmpeg]]|Complete and free Internet live audio and video broadcasting solution for Linux/Unix, capable to do a direct rip in any format (audio/video) from a DVD-Video ISO image, just select the input as the ISO image and proceed with the desired options. It also allows to downmixing, shrinking, spliting, selecting streams among other features.|http://ffmpeg.org/|See [[FFmpeg#Package_installation|article]]}}<br />
* {{App|HandBrake|Multithreaded video transcoder, which offers both a graphical and command-line interface with many preset configurations.|http://handbrake.fr/|{{Pkg|handbrake}}}}<br />
* {{App|Hybrid|Multi platform Qt based frontend for a bunch of other tools which can convert nearly every input to x264/Xvid/VP8 + ac3/ogg/mp3/aac/flac inside an mp4/m2ts/mkv/webm/mov/avi container, a Blu-ray or an AVCHD structure.|http://www.selur.de/|{{AUR|hybrid-encoder}}}}<br />
* {{App|[[MEncoder]]|Free command line video decoding, encoding and filtering tool released under the GNU General Public License. It is a close sibling to MPlayer and can convert all the formats that MPlayer understands into a variety of compressed and uncompressed formats using different codecs. Wrapper programs like {{AUR|h264enc}} and {{AUR|undvd}} can provide an assistive interface. Many [[MEncoder#GUI frontends|front-ends]] are available.|http://www.mplayerhq.hu/|{{Pkg|mencoder}}}}<br />
* {{App|Transcode|Video/DVD ripper and encoder for the terminal/console.|http://tcforge.berlios.de/|{{Pkg|transcode}}}}<br />
<br />
==== dvd::rip ====<br />
<br />
dvd::rip is a front-end to {{Pkg|transcode}}, used to extract and transcode on-the-fly.<br />
<br />
The following packages should be installed:<br />
* {{Pkg|dvdrip}}: GTK front-end for {{Pkg|transcode}}, which performs the ripping and encoding<br />
* {{Pkg|libdv}}: Software codec for DV video<br />
* {{Pkg|xvidcore}}: If you want to encode your ripped files as XviD, an open source MPEG-4 video codec (free alternative to DivX)<br />
* {{AUR|divx4linux}}: If you want to encode your ripped files as DivX (available in the [[AUR]])<br />
<br />
The dvd::rip preferences are mostly well-documented/self-explanatory. If you need help with something, see http://www.exit1.org/dvdrip/doc/gui-gui_pref.cipp.<br />
<br />
Ripping a DVD is often a simple matter of selecting the preferred codec(s), selecting the desired titles, then clicking the "Rip" button.<br />
<br />
== Troubleshooting ==<br />
<br />
=== K3b locale error ===<br />
<br />
When running K3B, if the following message appears:<br />
<br />
System locale charset is ANSI_X3.4-1968<br />
Your system's locale charset (i.e. the charset used to encode file names) is <br />
set to ANSI_X3.4-1968. It is highly unlikely that this has been done intentionally.<br />
Most likely the locale is not set at all. An invalid setting will result in<br />
problems when creating data projects.Solution: To properly set the locale <br />
charset make sure the LC_* environment variables are set. Normally the distribution <br />
setup tools take care of this.<br />
<br />
It means that your locale is not set well.<br />
<br />
To fix it,<br />
<br />
* Remove {{ic|/etc/locale.gen}}<br />
* Re-install {{Pkg|glibc}}<br />
* Edit {{ic|/etc/locale.gen}}, uncommenting all lines lines that corresponds to your language AND the {{ic|en_US}} options, for compatibility:<br />
<br />
{{bc|<br />
en_US.UTF-8 UTF-8<br />
en_US ISO-8859-1<br />
}}<br />
* Re-generate the profiles with {{ic|locale-gen}}:<br />
{{hc|# locale-gen|<br />
Generating locales...<br />
en_US.UTF-8... done<br />
en_US.ISO-8859-1... done<br />
pt_BR.UTF-8... done<br />
pt_BR.ISO-8859-1... done<br />
Generation complete.<br />
}}<br />
<br />
More info [https://bbs.archlinux.org/viewtopic.php?pid=251512%29; here].<br />
<br />
=== Brasero fails to find blank discs ===<br />
<br />
Brasero uses {{Pkg|gvfs}} to manage CD/DVD burning devices. Also make sure that your session [[General troubleshooting#Session permissions|is not broken]].<br />
<br />
=== Brasero fails to normalize audio CD ===<br />
<br />
If you try to burn it may stop at the first step called Normalization.<br />
<br />
As a workaround you can disable the normalization plugin using the ''Edit > Plugins'' menu<br />
<br />
=== VLC: Error "... could not open the disc /dev/dvd" ===<br />
<br />
If you get the error, "vlc dvdread could not open the disc "/dev/dvd"" it may be because there is no device node {{ic|/dev/dvd}} on your system. Udev no longer creates {{ic|/dev/dvd}} and instead uses {{ic|/dev/sr0}}. To fix this, edit the VLC configuration file ({{ic|~/.config/vlc/vlcrc}}):<br />
<br />
# DVD device (string) <br />
dvd=/dev/sr0<br />
<br />
=== DVD drive is noisy ===<br />
<br />
If playing DVD videos causes the system to be very loud, it may be because the disk is spinning faster than it needs to. To temporarily change the speed of the drive, as root, run:<br />
<br />
# eject -x 12 /dev/dvd<br />
<br />
Sometimes:<br />
<br />
# hdparm -E12 /dev/dvd<br />
<br />
Any speed that is supported by the drive can be used, or 0 for the maximum speed.<br />
<br />
[http://hektor.umcs.lublin.pl/~mikosmul/computing/tips/cd-rom-speed.html Setting CD-ROM and DVD-ROM drive speed]<br />
<br />
=== Playback does not work with new computer (new DVD-Drive) ===<br />
<br />
If playback does not work and you have a new computer (new DVD-Drive) the reason might be that the [[Wikipedia:DVD region code|region code]] is not set. You can read and set the region code with {{AUR|regionset}} from the [[AUR]].<br />
<br />
=== None of the above programs are able to rip/encode a DVD to my hard disk! ===<br />
<br />
Make sure the region of your DVD reader is set correctly; otherwise, you will get loads of inexplicable CSS-related errors. Use {{AUR|regionset}} to do so.<br />
<br />
=== GUI program log indicates problems with backend program ===<br />
<br />
If you use a GUI program and experience problems which the program's log blames on some backend program, then try to reproduce the problem by the logged backend program arguments.<br />
Whether you succeed with reproducing or not, you may report the logged lines and your own findings to the places mentioned in [[#Burn backend problems|section Burn Backend Problems]].<br />
<br />
==== Special case: medium error / write error ====<br />
<br />
Here are some typical messages about the drive disliking the medium. This can only be solved by using a different drive or a different medium. A different program will hardly help.<br />
<br />
K3b with backend wodim:<br />
Sense Bytes: 70 00 03 00 00 00 00 12 00 00 00 00 0C 00 00 00<br />
Sense Key: 0x3 Medium Error, Segment 0<br />
Sense Code: 0x0C Qual 0x00 (write error) Fru 0x0<br />
<br />
Brasero with backend growisofs:<br />
BraseroGrowisofs stderr: :-[ WRITE@LBA=0h failed with SK=3h/ASC=0Ch/ACQ=00h]: Input/output error<br />
<br />
Brasero with backend libburn:<br />
BraseroLibburn Libburn reported an error SCSI error on write(16976,16): [3 0C 00] Write error<br />
<br />
=== AHCI ===<br />
<br />
If your new DVD-Drive is detected but will not mount, check wether your BIOS uses [[AHCI]] and add the module to the kernel image.<br />
<br />
Edit {{ic|/etc/mkinitcpio.conf}} and add {{ic|ahci}} to the {{ic|MODULES}} variable (see [[mkinitcpio]] for details):<br />
MODULES="ahci"<br />
<br />
Rebuild the kernel image so that it includes the newly added module:<br />
# mkinitcpio -p linux<br />
<br />
== See also ==<br />
<br />
* RIAA and actual laws allow backup of physically obtained media under these conditions [https://www.riaa.com/physicalpiracy.php?content_selector=piracy_online_the_law RIAA - the law].<br />
* [[Convert any Movie to DVD Video]]<br />
* [http://libburnia-project.org/ Main page of the project Libburnia]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=CUPS&diff=339238CUPS2014-10-08T00:36:10Z<p>Jstjohn: /* Printer "Paused" or "Stopped" with Status "Rendering completed" */ add missing templates; move the "groupadd" command to separate line; state that world writable files are insecure; change the Warning template to a Note; create subsection for GID info</p>
<hr />
<div>[[Category:Printers]]<br />
[[cs:CUPS]]<br />
[[de:CUPS]]<br />
[[es:CUPS]]<br />
[[fr:CUPS]]<br />
[[it:CUPS]]<br />
[[ja:CUPS]]<br />
[[pl:CUPS]]<br />
[[ru:CUPS]]<br />
[[th:CUPS]]<br />
[[tr:CUPS]]<br />
[[zh-CN:CUPS]]<br />
[[zh-TW:CUPS]]<br />
{{Related articles start}}<br />
{{Related|CUPS printer sharing}}<br />
{{Related|CUPS printer-specific problems}}<br />
{{Related|Samba}}<br />
{{Related articles end}}<br />
<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''[[Wikipedia:CUPS|CUPS]] is the standards-based, open source printing system developed by Apple Inc. for OS® X and other UNIX®-like operating systems''".<br />
<br />
Although there are other printing packages such as LPRNG, the Common Unix Printing System is the most popular choice because of its relative ease of use.<br />
<br />
== CUPS Linux printing workflow ==<br />
As of {{Pkg|cups}} version 1.5.3-3, Arch Linux makes use of the new full pdf-based printing workflow. For<br />
further reading check [http://www.linuxfoundation.org/collaborate/workgroups/openprinting/pdfasstandardprintjobformat PDF standard printing job format] and an old [https://wiki.linuxfoundation.org/en/OpenPrinting/Database/CUPS-Filter-Chart CUPS filtering chart] for history and fun.<br />
A good starting point for general Linux printing questions is [http://www.linuxfoundation.org/collaborate/workgroups/openprinting here].<br />
<br />
There are two ways to setup a printer.<br />
* If there's a CUPS server running in your network and sharing a printer you only need to install the client package.<br />
* If the printer is connected directly to your system or you have access to an IPP network printer then setup a local CUPS server.<br />
<br />
== Installing the client package ==<br />
<br />
The package {{Pkg|libcups}} is the only required package. [[pacman|Install]] it from the [[official repositories]].<br />
<br />
Then add your CUPS server's IP address or hostname into {{ic|/etc/cups/client.conf}}, after {{ic|ServerName}}. That is all you need. Every application should quickly find the printer(s) shared by that CUPS server.<br />
<br />
=== Optional advanced network setup ===<br />
<br />
It is also possible to run a entire cupsd+cups-browsed instance on your client with Avahi browsing enabled to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown.<br />
{{Note|This behavior did not change with cups 1.6.x - the difference is that until 1.5.x cupsd was able to do printer browsing alone and now it can only browse its own shared printers.<br />
To get the local cupsd recognise other shared printers offered by a remote cupsd server you need a running local cups-browsed (supported since cups-filters 1.0.26) instance using Avahi to discover unknown printers.}}<br />
<br />
=== Installing CUPS in a 32-bit chroot environment ===<br />
<br />
If you have a 64-bit base installation with a [[Install_bundled_32-bit_system_in_Arch64|32-bit chroot environment]], explicit installation of CUPS is not necessary in the 32-bit environment. To access installed CUPS printers from the chroot environment, one needs to bind the {{ic|/var/run/cups}} directory to the same relative location in the chroot environment. Simply create the directory in the chroot (it probably does not exist), mount (with {{ic|-o bind}} passed to the command}}, and printers should be available from 32-bit chroot applications immediately.<br />
<br />
{{bc|# mkdir /path/to/chroot/var/run/cups<br />
# Example: # mkdir /opt/arch32/var/run/cups<br />
<br />
# mount -o bind /var/run/cups /path/to/chroot/var/run/cups}}<br />
<br />
== Installing the server packages ==<br />
<br />
{{Poor writing|Add Template:App}}<br />
<br />
The following packages and some printer drivers are needed. [[pacman|Install]] them from the [[official repositories]].<br />
<br />
* {{Pkg|cups}} - the actual CUPS daemon<br />
* {{Pkg|ghostscript}} - (optional) PostScript interpreter<br />
* {{Pkg|gsfonts}} - GhostScript standard Type1 fonts<br />
<br />
If you want to enable printer browsing through your network, also install {{Pkg|avahi}} and enable {{ic|avahi-daemon.service}} [[systemd#Using units|using systemd]].<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install {{Pkg|samba}}.<br />
<br />
=== Printer driver ===<br />
<br />
Choosing the right driver depends on the printer. Package names may be misleading because printers of other makes can rely on them. Additional printer drivers are available from the [[AUR]].<br />
<br />
* {{AUR|cndrvcups-lb}} - Canon UFR2 driver with support for LBP, iR and MF series printers.<br />
* {{AUR|cnijfilter-mg4200}} - Printer drivers for Canon MG4200<br />
* {{Pkg|cups-pdf}} - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
* {{AUR|foo2zjs}} - Drivers for ZjStream protocol printers such as the HP Laserjet 1018. More info [http://foo2zjs.rkkda.com here]. It also includes drivers for HBPL protocol such as the Dell C1765 MFP. More info [http://foo2hbpl.rkkda.com here]<br />
* {{Pkg|foomatic-db}}, {{Pkg|foomatic-db-engine}} and {{Pkg|foomatic-db-nonfree}} - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix.<br />
* {{Pkg|gutenprint}} - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostScript, CUPS, Foomatic, and the [[GIMP]]<br />
* {{Pkg|hplip}} - HP drivers for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models, as well as a number of Brother printers.<br />
* {{AUR|hpoj}} - If you are using an HP Officejet, you should also install this package and follow the instructions to avoid problems as in [https://answers.launchpad.net/hplip/+question/133425 this thread].<br />
* {{AUR|samsung-unified-driver}} - Unified Linux Driver for Samsung printers and scanners. Required for new printers such as the ML-2160.<br />
* {{Pkg|splix}} - Samsung drivers for SPL (Samsung Printer Language) printers.<br />
<br />
==== Download printer PPD ====<br />
<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.openprinting.org/printers OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{ic|/usr/share/cups/model/}}}}<br />
<br />
==== Another source for printer drivers ====<br />
<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
== Hardware support and configuration ==<br />
<br />
=== USB printers ===<br />
<br />
{{Tip|Most USB printers should work out of the box, you can skip this section and come back if you can not get your printer to work.}}<br />
<br />
USB printers can get accessed with two methods: The usblp kernel module and libusb. The former is the classic way. It is simple: data is sent to the printer by writing it to a device file as a simple serial data stream. Reading the same device file allows bi-di access, at least for things like reading out ink levels, status, or printer capability information (PJL). It works very well for simple printers, but for multi-function devices (printer/scanner) it is not suitable and manufacturers like HP supply their own backends. Source: [http://lists.linuxfoundation.org/pipermail/printing-architecture/2012/002412.html here].<br />
<br />
==== Blacklisting usblp ====<br />
<br />
{{Warning|As of {{Pkg|cups}} version 1.6.0, you no longer need to [[Kernel modules#Blacklisting|blacklist]] the {{ic|usblp}} kernel module.<br />
<br />
If you find out this is the only way to fix a remaining issue please report this upstream to the CUPS bug tracker and maybe also get in contact with Till Kamppeter (Debian CUPS maintainer). See [http://cups.org/str.php?L4128 upstream bug] for more.}}<br />
<br />
If you have problems getting your USB printer to work, you can try blacklisting the {{ic|usblp}} [[kernel module]]:<br />
<br />
{{hc|/etc/modprobe.d/blacklistusblp.conf|<br />
blacklist usblp<br />
}}<br />
<br />
Custom kernel users may need to manually load the {{ic|usbcore}} [[kernel module]] before proceeding.<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
If you're using {{ic|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{ic|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
=== Parallel port printers ===<br />
<br />
To use a parallel port printer, you will need to load the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]].<br />
<br />
Check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
If you are using a USB to parallel port adapter, CUPS will not be able to detect the printer. As a workaround, add the printer using a different connection type and then change DeviceID in {{ic|/etc/cups/printers.conf}}:<br />
DeviceID = parallel:/dev/usb/lp0<br />
<br />
=== HP Printer ===<br />
HP printers can also be installed via HP's Linux setup tool. Install it by installing {{Pkg|hplip}} from the [[official repositories]].<br />
<br />
To run with qt frontend:<br />
# hp-setup -u<br />
<br />
To run with command line:<br />
# hp-setup -i<br />
<br />
To run systray spool manager:<br />
$ hp-systray<br />
<br />
PPD files are in {{ic|/usr/share/ppd/HP/}}.<br />
<br />
{{Note| If you get errors complaining about missing gobject/dbus dependencies, install {{Pkg|python2-gobject2}} and {{Pkg|python2-dbus}}. For details see this [https://bugs.archlinux.org/task/26666 bug report].}}<br />
<br />
For printers that require the proprietary HP plugin (like the Laserjet Pro P1102w or 1020), install the {{AUR|hplip-plugin}} package from [[AUR]].<br />
<br />
{{Warning| Due to a bug in hplip-setup, you might get error in sys tray or CUPS logs {{ic|Print job failed - required plug-in not found. Please run hp-plugin}} even after you install the aforementioned {{AUR|hplip-plugin}} package from [[AUR]]. To fix, simply modify the printer in CUPS web interface and select the driver manually (preferably the en,en version). After that restart CUPS service.}}<br />
<br />
{{Note|<br />
{{Pkg|hplip}} depends on {{Pkg|foomatic-db-engine}} which prevents the drivers list from appearing when a printer is added to CUPS via the web user interface (following error : "Unable to get list of printer drivers"). The workaround consists of installing {{Pkg|hplip}} first, retrieving the corresponding PPD file from {{ic|/usr/share/ppd/HP/}}, then, removing {{Pkg|hplip}} entirely and the unnecessary dependencies. Finally, install the printer manually using the CUPS web ui, select the PPD file you retrieved then re-install {{Pkg|hplip}}. After a reboot, you should have a fully working printer.}}<br />
<br />
== Configuring ==<br />
<br />
Now that CUPS is installed, there are a variety of options on how to set up printing solutions. As always, the tried and true command line method is at your disposal. CUPS also embeds a full-featured web interface. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. Depending on your needs, you may choose one method or the other.<br />
<br />
If you are planning on connecting to a network printer, rather than one that is directly connected to the computer, you might want to read the [[CUPS printer sharing]] page first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
=== CUPS daemon ===<br />
<br />
With CUPS installed, you can now start {{ic|cups.service}} and optionally, {{ic|cups-browsed.service}} [[systemd#Using units|using systemd]]. Enable them as required.<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{ic|/etc/hostname}}).<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a username and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label (e.g., next to ''USB Printer #1'' for USB printers). Finally, choose the appropriate drivers and the configuration is complete.<br />
<br />
Now test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
{{Tip|See: [[#Alternative CUPS interfaces]] for other front-ends.}}<br />
{{Note|<br />
* When setting up a USB printer, you should see your printer listed on ''Add Printer'' page. If you can only see a "SCSI printer" option, it probably means that CUPS has failed to recognize your printer.<br />
* To enable wireless scanning on certain HP multi-function devices using the {{pkg|hplip}} package, you may need to add the printer as a Network Printer using the HTTP protocol. To determine the proper URI to use, run the {{ic|hp-makeuri}} command.}}<br />
<br />
==== CUPS administration ====<br />
<br />
A username and password will be required when administering the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default username is the one assigned in the ''sys'' group, or root. Other admin groups (e.g. ''printadmin'') may be added to the {{ic|SystemGroup}} line in {{ic|/etc/cups/cups-files.conf}} (you might have to add this line). <br />
<br />
Create the group[s] ({{ic|man groupadd}}) <br />
<br />
# groupadd printadmin <br />
# groupadd lp<br />
<br />
and add the users to the group(s) ({{ic|man gpasswd}}). <br />
<br />
# gpasswd -a username printadmin # for printer administration<br />
# gpasswd -a username lp # for printing priviledges<br />
<br />
# Administrator user group, used to match @SYSTEM in cupsd.conf policy rules...<br />
SystemGroup sys root '''printadmin'''<br />
<br />
Restart {{ic|cups.service}} using systemd. The user must re-login for these changes to take affect.<br />
<br />
Refer to the full cups [http://www.cups.org/documentation.php documentation] for further details.<br />
<br />
==== Remote access to web interface ====<br />
<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{ic|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
Port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
Three levels of access can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{ic|Allow}} statement to that level's section. An {{ic|Allow}} statement can take one or more of the forms listed below:<br />
Allow from all<br />
Allow from host.domain.com<br />
Allow from *.domain.com<br />
Allow from ip-address<br />
Allow from ip-address/netmask<br />
Allow from @LOCAL<br />
<br />
Deny statements can also be used. For example, if wanting to give full access to all hosts on your local network interfaces, file {{ic|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
'''Allow From @LOCAL'''<br />
</Location><br />
<br />
You might also need to add:<br />
<br />
DefaultEncryption Never<br />
<br />
This should avoid the error: 426 - Upgrade Required when using the CUPS web interface from a remote machine.<br />
<br />
=== Command-line configuration ===<br />
<br />
CUPS can be fully controlled from command-line with nice tools, ''i.e.'' the lp* and the cups* command families.<br />
<br />
On Arch Linux, most commands support auto-completion with common shells.<br />
Also note that command-line switches cannot be grouped.<br />
<br />
;List the devices<br />
# lpinfo -v<br />
<br />
;List the drivers<br />
# lpinfo -m<br />
<br />
;Add a new printer<br />
# lpadmin -p ''printer'' -E -v ''device'' -P ''ppd''<br />
<br />
The ''printer'' is up to you. The device can be retrieved from the 'lpinfo -v' command.<br />
Example:<br />
# lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH" -P /usr/share/ppd/HP/hp-deskjet_940c.ppd.gz<br />
<br />
In the following, the ''printer'' references the name you have used here to set up the printer.<br />
<br />
;Set the default printer<br />
$ lpoptions -d ''printer''<br />
<br />
;Check the status<br />
$ lpstat -s<br />
$ lpstat -p ''printer''<br />
<br />
;Deactivate a printer<br />
# cupsdisable ''printer''<br />
<br />
;Activate a printer<br />
# cupsenable ''printer''<br />
<br />
;Remove a printer<br />
First set it to reject all incoming entries:<br />
# cupsreject ''printer''<br />
Then disable it.<br />
# cupsdisable ''printer''<br />
Finally remove it.<br />
# lpadmin -x ''printer''<br />
<br />
;Print a file<br />
$ lpr ''file''<br />
$ lpr -# 17 ''file'' # print the file 17 times<br />
$ echo "Hello, world!" | lpr -p # print the result of a command. The -p switch adds a header.<br />
<br />
;Check the printing queue<br />
$ lpq<br />
$ lpq -a # on all printers<br />
<br />
;Clear the printing queue<br />
# lprm # remove last entry only<br />
# lprm - # remove all entries<br />
<br />
=== Alternative CUPS interfaces ===<br />
<br />
==== GNOME ====<br />
<br />
You can configure and manage printers by [[pacman|installing]] {{Pkg|system-config-printer}}. This program does pull in some gnome dependencies.<br />
<br />
If your user does not have sufficient priviliges to administer the cups scheduler, system-config-printer will request the root password when it starts. You can avoid this by performing the following instructions.<br />
<br />
1. Create a group for administering the cups scheduler:<br />
<br />
# groupadd lpadmin<br />
<br />
2. Add yourself to the newly created group:<br />
<br />
# usermod -aG lpadmin ''username''<br />
<br />
3. Tell cups to respect the newly created group:<br />
<br />
{{hc|/etc/cups/cups-files.conf|<br />
...<br />
SystemGroup sys root '''lpadmin'''<br />
...}}<br />
<br />
4. Restart cups:<br />
<br />
# systemctl restart cups<br />
<br />
5. Log out and log in again or restart your computer.<br />
<br />
==== KDE ====<br />
<br />
[[KDE]] users can modify their printers from the Control Center. The {{Pkg|kdeutils-print-manager}} package may need be installed if the Printers interface isn't found in the Hardware group. KDE users should refer to the desktop environments' documentation for more information on how to use the interface.<br />
<br />
==== Other ====<br />
<br />
There is also {{AUR|gtklp}} in the [[AUR]].<br />
<br />
== PDF virtual printer ==<br />
{{Note| With GNOME, it is now possible to directly print into a PDF or Postscript file, therefore CUPS-PDF is no longer required on such system. }}<br />
<br />
{{Pkg|cups-pdf}} is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. This package is not necessary, but it can be quite useful.<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Add Printer<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Find generated PDF documents in a sub-directory located at {{ic|/var/spool/cups-pdf}}. Normally, the subdirectory is named after the user who performed the job. A little tweak helps you to find your printed PDF documents more easily. Edit {{ic|/etc/cups/cups-pdf.conf}} by changing the line<br />
#Out /var/spool/cups-pdf/${USER}<br />
<br />
to<br />
<br />
Out ${HOME}<br />
<br />
=== Print to PostScript ===<br />
<br />
The CUPS-PDF (Virtual PDF Printer) actually creates a PostScript file and then creates the PDF using the ps2pdf utility. To print to PostScript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
== Troubleshooting ==<br />
<br />
The best way to get printing working is to set 'LogLevel' in {{ic|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{ic|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{ic|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{ic|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{ic|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
=== Problems resulting from upgrades ===<br />
<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
==== CUPS stops working ====<br />
<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" may result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy {{ic|/etc/cups/cupsd.conf.default}} to {{ic|/etc/cups/cupsd.conf}} (backup the old configuration if needed) and restart CUPS to employ the new settings.<br />
<br />
==== All jobs are "stopped" ====<br />
<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
==== All jobs are "The printer is not responding" ====<br />
<br />
On networked printers, you should check that the name that CUPS uses as its connection URI resolves to the printer's IP via DNS, e.g.<br />
If your printer's connection looks like this:<br />
lpd://BRN_020554/BINARY_P1<br />
<br />
then the hostname 'BRN_020554' needs to resolve to the printer's IP from the server running CUPS<br />
<br />
==== The PPD version is not compatible with gutenprint ====<br />
<br />
Run:<br />
# /usr/bin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
=== Other ===<br />
<br />
==== Printer "Paused" or "Stopped" with Status "Rendering completed" ====<br />
<br />
When low on ink, some printers will get stuck in "Rendering completed" status and, if it is a network printer, the printer may even become unreachable from CUPS' perspective despite being properly connected to the network. Replacing the low/depleted ink cartridge(s) in this setting will return the printer to "Ready" status and, if it is a network printer, will make the printer available to CUPS again.<br />
<br />
{{Note|If you use third-party ink cartridges, the ink levels reported by the printer may be inaccurate. If you use third-party ink and your printer used to work fine but is now getting stuck on "Rendering completed" status, replace the ink cartridges regardless of the reported ink levels before trying other fixes.}}<br />
<br />
If low ink is not the issue, check the "Group ID" of files in {{ic|/etc/cups}}, {{ic|/var/log/cups}}, and, if you have "root" permission, {{ic|/var/spool/cups}}. The files should have GID {{ic|lp}}. If some files have GID {{ic|nobody}}, then check the named groups in the "Group" and "SystemGroup" directives in the file {{ic|/etc/cups/cups-files.conf}}. Typically there will be {{ic|Group lp}} and {{ic|SystemGroup lpadmin sys root}}. Make sure that the group in "Group" is NOT also in "SystemGroup". In particular, make sure that the name {{ic|lp}} is NOT listed in the "SystemGroup" directive, when it is used in the "Group" directive. This is counter to recommendations made in the CUPS and KDE wiki pages in the past. If you had added {{ic|lp}} to the "SystemGroup" directive, as had been suggested, remove {{ic|lp}} from the "SystemGroup", or run the following command and change {{ic|lp}} to {{ic|lpadmin}} in the "SystemGroup" directive.<br />
# groupadd -g107 lpadmin<br />
<br />
===== Explanation of GID issue =====<br />
For security reasons, cupsd does not allow external CUPS helper programs, which use the "Group" GID, to run in the Administration groups, which are those GIDs listed in "SystemGroup". If the named group in the Group directive is also in the SystemGroup directive, then cupsd changes the Group GID to "nobody" instead, without warning. However, the printer devices in {{ic|/dev/}}, for instance {{ic|/dev/parport0}}, are created with user "root" and group "lp". When cupsd then tries to print, it "pauses" or "stops" because it does not have permission to write the printer device file, and does not provide any useful error message. Making the printer device files "world writable" can bypass the problem, but that is insecure and is not the proper solution.<br />
<br />
==== CUPS permission errors ====<br />
<br />
* Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
* Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
==== HPLIP printer sends "/usr/lib/cups/backend/hp failed" error ====<br />
<br />
Make sure dbus is installed and running. If the error persists, try starting avahi-daemon.<br />
<br />
Try adding the printer as a Network Printer using the http:// protocol. Generate the printer URI with {{ic|hp-makeuri}}.<br />
<br />
{{Note|There might need to set permissions issues right. Follow indications here: [[CUPS#Device node permissions]].}}<br />
<br />
==== HPLIP printer claims job is complete but printer does nothing ====<br />
<br />
This happens on HP printers when you select the (old) hpijs driver (e.g. the Deskjet D1600 series). Instead, use the hpcups driver when adding the printer.<br />
<br />
Some HP printers (e.g HP LaserJet) require their firmware to be downloaded from the computer every time the printer is switched on. If there is an issue with udev (or equivalent) and the firmware download rule is never fired, you may experience this issue.<br />
As a workaround, you can manually download the firmware to the printer. Ensure the printer is plugged in and switched on, then enter<br />
hp-firmware -n<br />
<br />
==== hp-setup asks to specify the PPD file for the discovered printer ====<br />
<br />
Install CUPS before running hp-setup.<br />
<br />
==== I have installed Qt, but hp-setup reports "Qt/PyQt 4 initialization failed" ====<br />
<br />
"hp-check -t" won't give you useful information to find the required package. You have to install all the "Dependent Packages" prefixed with "python2" in https://www.archlinux.org/packages/extra/x86_64/hplip/<br />
<br />
==== hp-setup finds the printer automatically but reports "Unable to communicate with device" when printing test page immediately afterwards ====<br />
<br />
This at least happens to hplip 3.13.5-2 for HP Officejet 6500A through local network connection. To solve the problem, specify the IP address of the HP printer for hp-setup to locate the printer.<br />
<br />
==== hp-toolbox sends an error, "Unable to communicate with device" ====<br />
<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/''printer id''<br />
or, "{{ic|Unable to communicate with device"}}", then it may be needed to [[Groups#Group management|add the user to the lp and sys groups]].<br />
<br />
This can also be caused by printers such as the P1102 that provide a virtual CD-ROM drive for MS Windows drivers. The lp dev appears and then disappears. In that case, try the '''usb-modeswitch''' and '''usb-modeswitch-data''' packages, that lets one switch off the "Smart Drive" (udev rules included in said packages).<br />
<br />
This can also occur with network attached printers if the [[Avahi|avahi-daemon]] is not running. Another possibility is the specification of the printer's IP address in ''hp-setup'' fails to locate the printer because the IP address of the the printer changed due to DHCP. If this is the case, consider adding a DHCP reservation for the printer in the DHCP server's configuration.<br />
<br />
==== CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer ====<br />
<br />
If receiving any of the following error messages in {{ic|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer ''printer_name'' not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure {{pkg|hplip}} has been [[pacman|installed]], in addition to [[#Packages|the packages mentioned above]]. See [https://bbs.archlinux.org/viewtopic.php?id=65615 this forum post] for more information.<br />
<br />
==== Printing fails with unauthorised error ====<br />
<br />
If the user has been added to the lp group, and allowed to print (set in {{ic|cupsd.conf}}), then the problem lies in {{ic|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
==== Unknown supported format: application/postscript ====<br />
<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{ic|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{ic|/etc/cups/mime.types}}.<br />
<br />
==== Finding URIs for Windows print servers ====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
{{bc| WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series}}<br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
If it won't work try '%20' instead of spaces.<br />
<br />
==== Print-Job client-error-document-format-not-supported ====<br />
<br />
Try installing the foomatic packages and use a foomatic driver.<br />
<br />
==== Unable to get list of printer drivers ====<br />
<br />
* Check the {{ic|ServerName}} in {{ic|/etc/cups/client.conf}} is written without http://<br />
ServerName localhost:631<br />
* Try to remove Foomatic drivers or refer to [[#HP_Printer]] for a workaround.<br />
<br />
==== lp: Error - Scheduler Not Responding ====<br />
<br />
If you get this error when printing a document using:<br />
<br />
$ lp document-to-print<br />
<br />
Try setting the {{ic|CUPS_SERVER}} environment variable:<br />
<br />
$ export CUPS_SERVER=localhost<br />
<br />
If this solves your problem, make the solution permanent by adding the export line above to {{ic|~/.bash_profile}}.<br />
<br />
==== CUPS prints only an empty and an error-message page on HP LaserJet ====<br />
<br />
There is a bug that causes CUPS to fail when printing images on HP LaserJet (in my case 3380). The bug has been reported and fixed by [https://bugs.launchpad.net/ubuntu/+source/cups-filters/+bug/998087 Ubuntu].<br />
The first page is empty, the second page contains the following error message:<br />
ERROR:<br />
invalidaccess<br />
OFFENDING COMMAND:<br />
filter<br />
STACK:<br />
/SubFileDecode<br />
endstream<br />
...<br />
<br />
In order to fix the issue, run the following command as root:<br />
# lpadmin -p ''printer'' -o pdftops-renderer-default=pdftops<br />
<br />
==== "Using invalid Host" error message ====<br />
<br />
Try adding {{ic|ServerAlias *}} into {{ic|/etc/cups/cupsd.conf}}.<br />
<br />
==== Printer doesn't print with an "Filter failed" message on CUPS web interface (HP printer) ====<br />
<br />
Change the permissions of the printer USB port. Get the bus and device number from {{ic|lsusb}}, then set the permission using:<br />
<br />
{{hc| lsusb |<br />
Bus <BUSID> Device <DEVID>: ID <PRINTERID>:<VENDOR> Hewlett-Packard DeskJet D1360}}<br />
<br />
Then substitute the provided device information to the <br />
<br />
# chmod 0666 /dev/bus/usb/<BUSID>/<DEVID><br />
<br />
To make the persistent permission change that will be triggered automatically each time the computer is rebooted, add the following line.<br />
<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="<VENDOR>", ATTRS{idProduct}=="<PRINTERID>", GROUP="lp", MODE:="666"<br />
}}<br />
<br />
Each system may vary, so consult [[udev#List_attributes_of_a_device]] wiki page.<br />
<br />
==== Printer does not print with a "Filter failed" message on CUPS web interface (HP printer connected over network) ====<br />
<br />
Start, enable, and restart the {{ic|avahi-daemon}} service.<br />
<br />
==== HPLIP 3.13: Plugin is installed, but HP Device Manager complains it is not ====<br />
<br />
The issue might have to do with the file permission change that had been made to {{ic|/var/lib/hp/hplip.state}}. To correct the issue, a simple {{ic|chmod 644 /var/lib/hp/hplip.state}} and {{ic|chmod 755 /var/lib/hp}} should be sufficient. For further information, please read this [https://bugs.launchpad.net/hplip/+bug/1131596 link].<br />
<br />
==== Printer is not recognized by CUPS ====<br />
<br />
If your printer is not listed in the "Add Printers" page of the CUPS web interface, nor by {{ic|lpinfo -v}}, try the following (suggested in [https://bbs.archlinux.org/viewtopic.php?pid=1037279#p1037279 this thread]):<br />
<br />
* Remove {{ic|usblp}} from blacklist<br />
* Load {{ic|usblp}} module<br />
# modprobe usblp<br />
* Stop CUPS<br />
* Add the following udev rule in a new rule file:<br />
{{hc|/etc/udev/rules.d/10-cups_device_link.rules|2=<br />
KERNEL=="lp[0-9]", SYMLINK+="%k", GROUP="lp"<br />
}}<br />
* Reload udev rules:<br />
# udevadm control --reload-rules<br />
* Unplug the printer, and plug it in again.<br />
* Wait a few seconds, and then start the CUPS service.<br />
<br />
==== Cannot load /etc/samba/smb.conf ====<br />
<br />
If you are printing to a remote printer over SMB and get this error message: "Can't load /etc/samba/smb.conf - run testparm to debug it", then create an empty {{ic|/etc/samba/smb.conf}} file:<br />
<br />
# mkdir /etc/samba<br />
# touch /etc/samba/smb.conf<br />
<br />
and restart the CUPS service.<br />
<br />
==== CUPS' systemd service does not start even though it is enabled ====<br />
<br />
The systemd service file provided by CUPS uses socket activation, meaning the service is only started when an application connects to CUPS' socket. However, the systemd socket file provided by CUPS only works for the local <br />
{{ic|/var/run/cups/cups.sock}} socket. <br />
<br />
In order to have the CUPS service start when initiating a print job over the network, create the following file:<br />
<br />
{{hc|1=/etc/systemd/system/cups.socket|2=<br />
.include /usr/lib/systemd/system/cups.socket<br />
<br />
[Socket]<br />
ListenDatagram=0.0.0.0:631<br />
}}<br />
<br />
Then reload systemd:<br />
<br />
# systemctl --system daemon-reload<br />
<br />
Confirm that everything is working correctly:<br />
<br />
{{bc|<br />
# systemctl is-enabled cups.service &#124;&#124; systemctl enable cups.service<br />
# systemctl status cups.socket<br />
cups.socket - CUPS Printing Service Sockets<br />
Loaded: loaded (/etc/systemd/system/cups.socket; enabled)<br />
Active: inactive (dead)<br />
Listen: /var/run/cups/cups.sock (Stream)<br />
0.0.0.0:631 (Stream)<br />
0.0.0.0:631 (Datagram)<br />
}}<br />
<br />
CUPS should now start automatically when printing locally or over the network.<br />
<br />
==== "Forbidden" error when adding a printer ====<br />
<br />
If adding a printer through the web interface returns an error: ''Forbidden'', the most likely reason is that the privileges are not set correctly. One way to fix it is to add the administering user to the group {{ic|sys}}. For example,<br />
# usermod -a -G sys ''username''<br />
<br />
== See also ==<br />
<br />
* [http://localhost:631/help Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's printing guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation resources]''<br />
* [http://wiki.gotux.net/tutorials/software/hp-printer Install HP printers easy way]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=CUPS&diff=339237CUPS2014-10-08T00:29:22Z<p>Jstjohn: /* hp-toolbox sends an error, "Unable to communicate with device" */ add suggestion to configure a DHCP reservation</p>
<hr />
<div>[[Category:Printers]]<br />
[[cs:CUPS]]<br />
[[de:CUPS]]<br />
[[es:CUPS]]<br />
[[fr:CUPS]]<br />
[[it:CUPS]]<br />
[[ja:CUPS]]<br />
[[pl:CUPS]]<br />
[[ru:CUPS]]<br />
[[th:CUPS]]<br />
[[tr:CUPS]]<br />
[[zh-CN:CUPS]]<br />
[[zh-TW:CUPS]]<br />
{{Related articles start}}<br />
{{Related|CUPS printer sharing}}<br />
{{Related|CUPS printer-specific problems}}<br />
{{Related|Samba}}<br />
{{Related articles end}}<br />
<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''[[Wikipedia:CUPS|CUPS]] is the standards-based, open source printing system developed by Apple Inc. for OS® X and other UNIX®-like operating systems''".<br />
<br />
Although there are other printing packages such as LPRNG, the Common Unix Printing System is the most popular choice because of its relative ease of use.<br />
<br />
== CUPS Linux printing workflow ==<br />
As of {{Pkg|cups}} version 1.5.3-3, Arch Linux makes use of the new full pdf-based printing workflow. For<br />
further reading check [http://www.linuxfoundation.org/collaborate/workgroups/openprinting/pdfasstandardprintjobformat PDF standard printing job format] and an old [https://wiki.linuxfoundation.org/en/OpenPrinting/Database/CUPS-Filter-Chart CUPS filtering chart] for history and fun.<br />
A good starting point for general Linux printing questions is [http://www.linuxfoundation.org/collaborate/workgroups/openprinting here].<br />
<br />
There are two ways to setup a printer.<br />
* If there's a CUPS server running in your network and sharing a printer you only need to install the client package.<br />
* If the printer is connected directly to your system or you have access to an IPP network printer then setup a local CUPS server.<br />
<br />
== Installing the client package ==<br />
<br />
The package {{Pkg|libcups}} is the only required package. [[pacman|Install]] it from the [[official repositories]].<br />
<br />
Then add your CUPS server's IP address or hostname into {{ic|/etc/cups/client.conf}}, after {{ic|ServerName}}. That is all you need. Every application should quickly find the printer(s) shared by that CUPS server.<br />
<br />
=== Optional advanced network setup ===<br />
<br />
It is also possible to run a entire cupsd+cups-browsed instance on your client with Avahi browsing enabled to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown.<br />
{{Note|This behavior did not change with cups 1.6.x - the difference is that until 1.5.x cupsd was able to do printer browsing alone and now it can only browse its own shared printers.<br />
To get the local cupsd recognise other shared printers offered by a remote cupsd server you need a running local cups-browsed (supported since cups-filters 1.0.26) instance using Avahi to discover unknown printers.}}<br />
<br />
=== Installing CUPS in a 32-bit chroot environment ===<br />
<br />
If you have a 64-bit base installation with a [[Install_bundled_32-bit_system_in_Arch64|32-bit chroot environment]], explicit installation of CUPS is not necessary in the 32-bit environment. To access installed CUPS printers from the chroot environment, one needs to bind the {{ic|/var/run/cups}} directory to the same relative location in the chroot environment. Simply create the directory in the chroot (it probably does not exist), mount (with {{ic|-o bind}} passed to the command}}, and printers should be available from 32-bit chroot applications immediately.<br />
<br />
{{bc|# mkdir /path/to/chroot/var/run/cups<br />
# Example: # mkdir /opt/arch32/var/run/cups<br />
<br />
# mount -o bind /var/run/cups /path/to/chroot/var/run/cups}}<br />
<br />
== Installing the server packages ==<br />
<br />
{{Poor writing|Add Template:App}}<br />
<br />
The following packages and some printer drivers are needed. [[pacman|Install]] them from the [[official repositories]].<br />
<br />
* {{Pkg|cups}} - the actual CUPS daemon<br />
* {{Pkg|ghostscript}} - (optional) PostScript interpreter<br />
* {{Pkg|gsfonts}} - GhostScript standard Type1 fonts<br />
<br />
If you want to enable printer browsing through your network, also install {{Pkg|avahi}} and enable {{ic|avahi-daemon.service}} [[systemd#Using units|using systemd]].<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install {{Pkg|samba}}.<br />
<br />
=== Printer driver ===<br />
<br />
Choosing the right driver depends on the printer. Package names may be misleading because printers of other makes can rely on them. Additional printer drivers are available from the [[AUR]].<br />
<br />
* {{AUR|cndrvcups-lb}} - Canon UFR2 driver with support for LBP, iR and MF series printers.<br />
* {{AUR|cnijfilter-mg4200}} - Printer drivers for Canon MG4200<br />
* {{Pkg|cups-pdf}} - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
* {{AUR|foo2zjs}} - Drivers for ZjStream protocol printers such as the HP Laserjet 1018. More info [http://foo2zjs.rkkda.com here]. It also includes drivers for HBPL protocol such as the Dell C1765 MFP. More info [http://foo2hbpl.rkkda.com here]<br />
* {{Pkg|foomatic-db}}, {{Pkg|foomatic-db-engine}} and {{Pkg|foomatic-db-nonfree}} - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix.<br />
* {{Pkg|gutenprint}} - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostScript, CUPS, Foomatic, and the [[GIMP]]<br />
* {{Pkg|hplip}} - HP drivers for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models, as well as a number of Brother printers.<br />
* {{AUR|hpoj}} - If you are using an HP Officejet, you should also install this package and follow the instructions to avoid problems as in [https://answers.launchpad.net/hplip/+question/133425 this thread].<br />
* {{AUR|samsung-unified-driver}} - Unified Linux Driver for Samsung printers and scanners. Required for new printers such as the ML-2160.<br />
* {{Pkg|splix}} - Samsung drivers for SPL (Samsung Printer Language) printers.<br />
<br />
==== Download printer PPD ====<br />
<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.openprinting.org/printers OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{ic|/usr/share/cups/model/}}}}<br />
<br />
==== Another source for printer drivers ====<br />
<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
== Hardware support and configuration ==<br />
<br />
=== USB printers ===<br />
<br />
{{Tip|Most USB printers should work out of the box, you can skip this section and come back if you can not get your printer to work.}}<br />
<br />
USB printers can get accessed with two methods: The usblp kernel module and libusb. The former is the classic way. It is simple: data is sent to the printer by writing it to a device file as a simple serial data stream. Reading the same device file allows bi-di access, at least for things like reading out ink levels, status, or printer capability information (PJL). It works very well for simple printers, but for multi-function devices (printer/scanner) it is not suitable and manufacturers like HP supply their own backends. Source: [http://lists.linuxfoundation.org/pipermail/printing-architecture/2012/002412.html here].<br />
<br />
==== Blacklisting usblp ====<br />
<br />
{{Warning|As of {{Pkg|cups}} version 1.6.0, you no longer need to [[Kernel modules#Blacklisting|blacklist]] the {{ic|usblp}} kernel module.<br />
<br />
If you find out this is the only way to fix a remaining issue please report this upstream to the CUPS bug tracker and maybe also get in contact with Till Kamppeter (Debian CUPS maintainer). See [http://cups.org/str.php?L4128 upstream bug] for more.}}<br />
<br />
If you have problems getting your USB printer to work, you can try blacklisting the {{ic|usblp}} [[kernel module]]:<br />
<br />
{{hc|/etc/modprobe.d/blacklistusblp.conf|<br />
blacklist usblp<br />
}}<br />
<br />
Custom kernel users may need to manually load the {{ic|usbcore}} [[kernel module]] before proceeding.<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
If you're using {{ic|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{ic|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
=== Parallel port printers ===<br />
<br />
To use a parallel port printer, you will need to load the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]].<br />
<br />
Check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
If you are using a USB to parallel port adapter, CUPS will not be able to detect the printer. As a workaround, add the printer using a different connection type and then change DeviceID in {{ic|/etc/cups/printers.conf}}:<br />
DeviceID = parallel:/dev/usb/lp0<br />
<br />
=== HP Printer ===<br />
HP printers can also be installed via HP's Linux setup tool. Install it by installing {{Pkg|hplip}} from the [[official repositories]].<br />
<br />
To run with qt frontend:<br />
# hp-setup -u<br />
<br />
To run with command line:<br />
# hp-setup -i<br />
<br />
To run systray spool manager:<br />
$ hp-systray<br />
<br />
PPD files are in {{ic|/usr/share/ppd/HP/}}.<br />
<br />
{{Note| If you get errors complaining about missing gobject/dbus dependencies, install {{Pkg|python2-gobject2}} and {{Pkg|python2-dbus}}. For details see this [https://bugs.archlinux.org/task/26666 bug report].}}<br />
<br />
For printers that require the proprietary HP plugin (like the Laserjet Pro P1102w or 1020), install the {{AUR|hplip-plugin}} package from [[AUR]].<br />
<br />
{{Warning| Due to a bug in hplip-setup, you might get error in sys tray or CUPS logs {{ic|Print job failed - required plug-in not found. Please run hp-plugin}} even after you install the aforementioned {{AUR|hplip-plugin}} package from [[AUR]]. To fix, simply modify the printer in CUPS web interface and select the driver manually (preferably the en,en version). After that restart CUPS service.}}<br />
<br />
{{Note|<br />
{{Pkg|hplip}} depends on {{Pkg|foomatic-db-engine}} which prevents the drivers list from appearing when a printer is added to CUPS via the web user interface (following error : "Unable to get list of printer drivers"). The workaround consists of installing {{Pkg|hplip}} first, retrieving the corresponding PPD file from {{ic|/usr/share/ppd/HP/}}, then, removing {{Pkg|hplip}} entirely and the unnecessary dependencies. Finally, install the printer manually using the CUPS web ui, select the PPD file you retrieved then re-install {{Pkg|hplip}}. After a reboot, you should have a fully working printer.}}<br />
<br />
== Configuring ==<br />
<br />
Now that CUPS is installed, there are a variety of options on how to set up printing solutions. As always, the tried and true command line method is at your disposal. CUPS also embeds a full-featured web interface. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. Depending on your needs, you may choose one method or the other.<br />
<br />
If you are planning on connecting to a network printer, rather than one that is directly connected to the computer, you might want to read the [[CUPS printer sharing]] page first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
=== CUPS daemon ===<br />
<br />
With CUPS installed, you can now start {{ic|cups.service}} and optionally, {{ic|cups-browsed.service}} [[systemd#Using units|using systemd]]. Enable them as required.<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{ic|/etc/hostname}}).<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a username and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label (e.g., next to ''USB Printer #1'' for USB printers). Finally, choose the appropriate drivers and the configuration is complete.<br />
<br />
Now test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
{{Tip|See: [[#Alternative CUPS interfaces]] for other front-ends.}}<br />
{{Note|<br />
* When setting up a USB printer, you should see your printer listed on ''Add Printer'' page. If you can only see a "SCSI printer" option, it probably means that CUPS has failed to recognize your printer.<br />
* To enable wireless scanning on certain HP multi-function devices using the {{pkg|hplip}} package, you may need to add the printer as a Network Printer using the HTTP protocol. To determine the proper URI to use, run the {{ic|hp-makeuri}} command.}}<br />
<br />
==== CUPS administration ====<br />
<br />
A username and password will be required when administering the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default username is the one assigned in the ''sys'' group, or root. Other admin groups (e.g. ''printadmin'') may be added to the {{ic|SystemGroup}} line in {{ic|/etc/cups/cups-files.conf}} (you might have to add this line). <br />
<br />
Create the group[s] ({{ic|man groupadd}}) <br />
<br />
# groupadd printadmin <br />
# groupadd lp<br />
<br />
and add the users to the group(s) ({{ic|man gpasswd}}). <br />
<br />
# gpasswd -a username printadmin # for printer administration<br />
# gpasswd -a username lp # for printing priviledges<br />
<br />
# Administrator user group, used to match @SYSTEM in cupsd.conf policy rules...<br />
SystemGroup sys root '''printadmin'''<br />
<br />
Restart {{ic|cups.service}} using systemd. The user must re-login for these changes to take affect.<br />
<br />
Refer to the full cups [http://www.cups.org/documentation.php documentation] for further details.<br />
<br />
==== Remote access to web interface ====<br />
<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{ic|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
Port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
Three levels of access can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{ic|Allow}} statement to that level's section. An {{ic|Allow}} statement can take one or more of the forms listed below:<br />
Allow from all<br />
Allow from host.domain.com<br />
Allow from *.domain.com<br />
Allow from ip-address<br />
Allow from ip-address/netmask<br />
Allow from @LOCAL<br />
<br />
Deny statements can also be used. For example, if wanting to give full access to all hosts on your local network interfaces, file {{ic|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
'''Allow From @LOCAL'''<br />
</Location><br />
<br />
You might also need to add:<br />
<br />
DefaultEncryption Never<br />
<br />
This should avoid the error: 426 - Upgrade Required when using the CUPS web interface from a remote machine.<br />
<br />
=== Command-line configuration ===<br />
<br />
CUPS can be fully controlled from command-line with nice tools, ''i.e.'' the lp* and the cups* command families.<br />
<br />
On Arch Linux, most commands support auto-completion with common shells.<br />
Also note that command-line switches cannot be grouped.<br />
<br />
;List the devices<br />
# lpinfo -v<br />
<br />
;List the drivers<br />
# lpinfo -m<br />
<br />
;Add a new printer<br />
# lpadmin -p ''printer'' -E -v ''device'' -P ''ppd''<br />
<br />
The ''printer'' is up to you. The device can be retrieved from the 'lpinfo -v' command.<br />
Example:<br />
# lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH" -P /usr/share/ppd/HP/hp-deskjet_940c.ppd.gz<br />
<br />
In the following, the ''printer'' references the name you have used here to set up the printer.<br />
<br />
;Set the default printer<br />
$ lpoptions -d ''printer''<br />
<br />
;Check the status<br />
$ lpstat -s<br />
$ lpstat -p ''printer''<br />
<br />
;Deactivate a printer<br />
# cupsdisable ''printer''<br />
<br />
;Activate a printer<br />
# cupsenable ''printer''<br />
<br />
;Remove a printer<br />
First set it to reject all incoming entries:<br />
# cupsreject ''printer''<br />
Then disable it.<br />
# cupsdisable ''printer''<br />
Finally remove it.<br />
# lpadmin -x ''printer''<br />
<br />
;Print a file<br />
$ lpr ''file''<br />
$ lpr -# 17 ''file'' # print the file 17 times<br />
$ echo "Hello, world!" | lpr -p # print the result of a command. The -p switch adds a header.<br />
<br />
;Check the printing queue<br />
$ lpq<br />
$ lpq -a # on all printers<br />
<br />
;Clear the printing queue<br />
# lprm # remove last entry only<br />
# lprm - # remove all entries<br />
<br />
=== Alternative CUPS interfaces ===<br />
<br />
==== GNOME ====<br />
<br />
You can configure and manage printers by [[pacman|installing]] {{Pkg|system-config-printer}}. This program does pull in some gnome dependencies.<br />
<br />
If your user does not have sufficient priviliges to administer the cups scheduler, system-config-printer will request the root password when it starts. You can avoid this by performing the following instructions.<br />
<br />
1. Create a group for administering the cups scheduler:<br />
<br />
# groupadd lpadmin<br />
<br />
2. Add yourself to the newly created group:<br />
<br />
# usermod -aG lpadmin ''username''<br />
<br />
3. Tell cups to respect the newly created group:<br />
<br />
{{hc|/etc/cups/cups-files.conf|<br />
...<br />
SystemGroup sys root '''lpadmin'''<br />
...}}<br />
<br />
4. Restart cups:<br />
<br />
# systemctl restart cups<br />
<br />
5. Log out and log in again or restart your computer.<br />
<br />
==== KDE ====<br />
<br />
[[KDE]] users can modify their printers from the Control Center. The {{Pkg|kdeutils-print-manager}} package may need be installed if the Printers interface isn't found in the Hardware group. KDE users should refer to the desktop environments' documentation for more information on how to use the interface.<br />
<br />
==== Other ====<br />
<br />
There is also {{AUR|gtklp}} in the [[AUR]].<br />
<br />
== PDF virtual printer ==<br />
{{Note| With GNOME, it is now possible to directly print into a PDF or Postscript file, therefore CUPS-PDF is no longer required on such system. }}<br />
<br />
{{Pkg|cups-pdf}} is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. This package is not necessary, but it can be quite useful.<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Add Printer<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Find generated PDF documents in a sub-directory located at {{ic|/var/spool/cups-pdf}}. Normally, the subdirectory is named after the user who performed the job. A little tweak helps you to find your printed PDF documents more easily. Edit {{ic|/etc/cups/cups-pdf.conf}} by changing the line<br />
#Out /var/spool/cups-pdf/${USER}<br />
<br />
to<br />
<br />
Out ${HOME}<br />
<br />
=== Print to PostScript ===<br />
<br />
The CUPS-PDF (Virtual PDF Printer) actually creates a PostScript file and then creates the PDF using the ps2pdf utility. To print to PostScript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
== Troubleshooting ==<br />
<br />
The best way to get printing working is to set 'LogLevel' in {{ic|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{ic|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{ic|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{ic|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{ic|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
=== Problems resulting from upgrades ===<br />
<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
==== CUPS stops working ====<br />
<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" may result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy {{ic|/etc/cups/cupsd.conf.default}} to {{ic|/etc/cups/cupsd.conf}} (backup the old configuration if needed) and restart CUPS to employ the new settings.<br />
<br />
==== All jobs are "stopped" ====<br />
<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
==== All jobs are "The printer is not responding" ====<br />
<br />
On networked printers, you should check that the name that CUPS uses as its connection URI resolves to the printer's IP via DNS, e.g.<br />
If your printer's connection looks like this:<br />
lpd://BRN_020554/BINARY_P1<br />
<br />
then the hostname 'BRN_020554' needs to resolve to the printer's IP from the server running CUPS<br />
<br />
==== The PPD version is not compatible with gutenprint ====<br />
<br />
Run:<br />
# /usr/bin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
=== Other ===<br />
<br />
==== Printer "Paused" or "Stopped" with Status "Rendering completed" ====<br />
<br />
When low on ink, some printers will get stuck in "Rendering completed" status and, if it is a network printer, the printer may even become unreachable from CUPS' perspective despite being properly connected to the network. Replacing the low/depleted ink cartridge(s) in this setting will return the printer to "Ready" status and, if it is a network printer, will make the printer available to CUPS again.<br />
<br />
{{Warning|If you use third-party ink cartridges, the ink levels reported by the printer may be inaccurate. If you use third-party ink and your printer used to work fine but is now getting stuck on "Rendering completed" status, replace the ink cartridges regardless of the reported ink levels before trying other fixes.}}<br />
<br />
If low ink is not the issue, check the "Group ID" of files in /etc/cups, /var/log/cups, and, if you have "root" permission, /var/spool/cups. The files should have GID "lp". If some files have GID "nobody", then check the named groups in the "Group" and "SystemGroup" directives in the file /etc/cups/cups-files.conf. Typically there will be "Group lp" and "SystemGroup lpadmin sys root". Make sure that the group in "Group" is NOT also in "SystemGroup". In particular, make sure that the name "lp" is NOT listed in the "SystemGroup" directive, when it is used in the "Group" directive. This is counter to recommendations made in the CUPS and KDE wiki pages in the past. If you had added "lp" to the "SystemGroup" directive, as had been suggested, remove "lp" from the "SystemGroup", or run "sudo groupadd -g107 lpadmin" and change "lp" to "lpadmin" in the "SystemGroup" directive.<br />
<br />
Explanation of GID issue: For security reasons, cupsd does not allow external cups helper programs, which use the "Group" GID, to run in the Administration groups, which are those GIDs listed in "SystemGroup". If the named group in the Group directive is also in the SystemGroup directive, then cupsd changes the Group GID to "nobody" instead, without warning. However, the printer devices in "/dev/", for instance "/dev/parport0", are created with user "root" and group "lp". When cupsd then tries to print, it "pauses" or "stops" because it does not have permission to write the printer device file, and does not provide any useful error message. Making the printer device files "world writable" can bypass the problem, but is not the proper solution.<br />
<br />
==== CUPS permission errors ====<br />
<br />
* Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
* Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
==== HPLIP printer sends "/usr/lib/cups/backend/hp failed" error ====<br />
<br />
Make sure dbus is installed and running. If the error persists, try starting avahi-daemon.<br />
<br />
Try adding the printer as a Network Printer using the http:// protocol. Generate the printer URI with {{ic|hp-makeuri}}.<br />
<br />
{{Note|There might need to set permissions issues right. Follow indications here: [[CUPS#Device node permissions]].}}<br />
<br />
==== HPLIP printer claims job is complete but printer does nothing ====<br />
<br />
This happens on HP printers when you select the (old) hpijs driver (e.g. the Deskjet D1600 series). Instead, use the hpcups driver when adding the printer.<br />
<br />
Some HP printers (e.g HP LaserJet) require their firmware to be downloaded from the computer every time the printer is switched on. If there is an issue with udev (or equivalent) and the firmware download rule is never fired, you may experience this issue.<br />
As a workaround, you can manually download the firmware to the printer. Ensure the printer is plugged in and switched on, then enter<br />
hp-firmware -n<br />
<br />
==== hp-setup asks to specify the PPD file for the discovered printer ====<br />
<br />
Install CUPS before running hp-setup.<br />
<br />
==== I have installed Qt, but hp-setup reports "Qt/PyQt 4 initialization failed" ====<br />
<br />
"hp-check -t" won't give you useful information to find the required package. You have to install all the "Dependent Packages" prefixed with "python2" in https://www.archlinux.org/packages/extra/x86_64/hplip/<br />
<br />
==== hp-setup finds the printer automatically but reports "Unable to communicate with device" when printing test page immediately afterwards ====<br />
<br />
This at least happens to hplip 3.13.5-2 for HP Officejet 6500A through local network connection. To solve the problem, specify the IP address of the HP printer for hp-setup to locate the printer.<br />
<br />
==== hp-toolbox sends an error, "Unable to communicate with device" ====<br />
<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/''printer id''<br />
or, "{{ic|Unable to communicate with device"}}", then it may be needed to [[Groups#Group management|add the user to the lp and sys groups]].<br />
<br />
This can also be caused by printers such as the P1102 that provide a virtual CD-ROM drive for MS Windows drivers. The lp dev appears and then disappears. In that case, try the '''usb-modeswitch''' and '''usb-modeswitch-data''' packages, that lets one switch off the "Smart Drive" (udev rules included in said packages).<br />
<br />
This can also occur with network attached printers if the [[Avahi|avahi-daemon]] is not running. Another possibility is the specification of the printer's IP address in ''hp-setup'' fails to locate the printer because the IP address of the the printer changed due to DHCP. If this is the case, consider adding a DHCP reservation for the printer in the DHCP server's configuration.<br />
<br />
==== CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer ====<br />
<br />
If receiving any of the following error messages in {{ic|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer ''printer_name'' not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure {{pkg|hplip}} has been [[pacman|installed]], in addition to [[#Packages|the packages mentioned above]]. See [https://bbs.archlinux.org/viewtopic.php?id=65615 this forum post] for more information.<br />
<br />
==== Printing fails with unauthorised error ====<br />
<br />
If the user has been added to the lp group, and allowed to print (set in {{ic|cupsd.conf}}), then the problem lies in {{ic|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
==== Unknown supported format: application/postscript ====<br />
<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{ic|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{ic|/etc/cups/mime.types}}.<br />
<br />
==== Finding URIs for Windows print servers ====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
{{bc| WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series}}<br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
If it won't work try '%20' instead of spaces.<br />
<br />
==== Print-Job client-error-document-format-not-supported ====<br />
<br />
Try installing the foomatic packages and use a foomatic driver.<br />
<br />
==== Unable to get list of printer drivers ====<br />
<br />
* Check the {{ic|ServerName}} in {{ic|/etc/cups/client.conf}} is written without http://<br />
ServerName localhost:631<br />
* Try to remove Foomatic drivers or refer to [[#HP_Printer]] for a workaround.<br />
<br />
==== lp: Error - Scheduler Not Responding ====<br />
<br />
If you get this error when printing a document using:<br />
<br />
$ lp document-to-print<br />
<br />
Try setting the {{ic|CUPS_SERVER}} environment variable:<br />
<br />
$ export CUPS_SERVER=localhost<br />
<br />
If this solves your problem, make the solution permanent by adding the export line above to {{ic|~/.bash_profile}}.<br />
<br />
==== CUPS prints only an empty and an error-message page on HP LaserJet ====<br />
<br />
There is a bug that causes CUPS to fail when printing images on HP LaserJet (in my case 3380). The bug has been reported and fixed by [https://bugs.launchpad.net/ubuntu/+source/cups-filters/+bug/998087 Ubuntu].<br />
The first page is empty, the second page contains the following error message:<br />
ERROR:<br />
invalidaccess<br />
OFFENDING COMMAND:<br />
filter<br />
STACK:<br />
/SubFileDecode<br />
endstream<br />
...<br />
<br />
In order to fix the issue, run the following command as root:<br />
# lpadmin -p ''printer'' -o pdftops-renderer-default=pdftops<br />
<br />
==== "Using invalid Host" error message ====<br />
<br />
Try adding {{ic|ServerAlias *}} into {{ic|/etc/cups/cupsd.conf}}.<br />
<br />
==== Printer doesn't print with an "Filter failed" message on CUPS web interface (HP printer) ====<br />
<br />
Change the permissions of the printer USB port. Get the bus and device number from {{ic|lsusb}}, then set the permission using:<br />
<br />
{{hc| lsusb |<br />
Bus <BUSID> Device <DEVID>: ID <PRINTERID>:<VENDOR> Hewlett-Packard DeskJet D1360}}<br />
<br />
Then substitute the provided device information to the <br />
<br />
# chmod 0666 /dev/bus/usb/<BUSID>/<DEVID><br />
<br />
To make the persistent permission change that will be triggered automatically each time the computer is rebooted, add the following line.<br />
<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="<VENDOR>", ATTRS{idProduct}=="<PRINTERID>", GROUP="lp", MODE:="666"<br />
}}<br />
<br />
Each system may vary, so consult [[udev#List_attributes_of_a_device]] wiki page.<br />
<br />
==== Printer does not print with a "Filter failed" message on CUPS web interface (HP printer connected over network) ====<br />
<br />
Start, enable, and restart the {{ic|avahi-daemon}} service.<br />
<br />
==== HPLIP 3.13: Plugin is installed, but HP Device Manager complains it is not ====<br />
<br />
The issue might have to do with the file permission change that had been made to {{ic|/var/lib/hp/hplip.state}}. To correct the issue, a simple {{ic|chmod 644 /var/lib/hp/hplip.state}} and {{ic|chmod 755 /var/lib/hp}} should be sufficient. For further information, please read this [https://bugs.launchpad.net/hplip/+bug/1131596 link].<br />
<br />
==== Printer is not recognized by CUPS ====<br />
<br />
If your printer is not listed in the "Add Printers" page of the CUPS web interface, nor by {{ic|lpinfo -v}}, try the following (suggested in [https://bbs.archlinux.org/viewtopic.php?pid=1037279#p1037279 this thread]):<br />
<br />
* Remove {{ic|usblp}} from blacklist<br />
* Load {{ic|usblp}} module<br />
# modprobe usblp<br />
* Stop CUPS<br />
* Add the following udev rule in a new rule file:<br />
{{hc|/etc/udev/rules.d/10-cups_device_link.rules|2=<br />
KERNEL=="lp[0-9]", SYMLINK+="%k", GROUP="lp"<br />
}}<br />
* Reload udev rules:<br />
# udevadm control --reload-rules<br />
* Unplug the printer, and plug it in again.<br />
* Wait a few seconds, and then start the CUPS service.<br />
<br />
==== Cannot load /etc/samba/smb.conf ====<br />
<br />
If you are printing to a remote printer over SMB and get this error message: "Can't load /etc/samba/smb.conf - run testparm to debug it", then create an empty {{ic|/etc/samba/smb.conf}} file:<br />
<br />
# mkdir /etc/samba<br />
# touch /etc/samba/smb.conf<br />
<br />
and restart the CUPS service.<br />
<br />
==== CUPS' systemd service does not start even though it is enabled ====<br />
<br />
The systemd service file provided by CUPS uses socket activation, meaning the service is only started when an application connects to CUPS' socket. However, the systemd socket file provided by CUPS only works for the local <br />
{{ic|/var/run/cups/cups.sock}} socket. <br />
<br />
In order to have the CUPS service start when initiating a print job over the network, create the following file:<br />
<br />
{{hc|1=/etc/systemd/system/cups.socket|2=<br />
.include /usr/lib/systemd/system/cups.socket<br />
<br />
[Socket]<br />
ListenDatagram=0.0.0.0:631<br />
}}<br />
<br />
Then reload systemd:<br />
<br />
# systemctl --system daemon-reload<br />
<br />
Confirm that everything is working correctly:<br />
<br />
{{bc|<br />
# systemctl is-enabled cups.service &#124;&#124; systemctl enable cups.service<br />
# systemctl status cups.socket<br />
cups.socket - CUPS Printing Service Sockets<br />
Loaded: loaded (/etc/systemd/system/cups.socket; enabled)<br />
Active: inactive (dead)<br />
Listen: /var/run/cups/cups.sock (Stream)<br />
0.0.0.0:631 (Stream)<br />
0.0.0.0:631 (Datagram)<br />
}}<br />
<br />
CUPS should now start automatically when printing locally or over the network.<br />
<br />
==== "Forbidden" error when adding a printer ====<br />
<br />
If adding a printer through the web interface returns an error: ''Forbidden'', the most likely reason is that the privileges are not set correctly. One way to fix it is to add the administering user to the group {{ic|sys}}. For example,<br />
# usermod -a -G sys ''username''<br />
<br />
== See also ==<br />
<br />
* [http://localhost:631/help Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's printing guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation resources]''<br />
* [http://wiki.gotux.net/tutorials/software/hp-printer Install HP printers easy way]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=CUPS&diff=339236CUPS2014-10-08T00:26:38Z<p>Jstjohn: /* hp-toolbox sends an error, "Unable to communicate with device" */ improve grammar</p>
<hr />
<div>[[Category:Printers]]<br />
[[cs:CUPS]]<br />
[[de:CUPS]]<br />
[[es:CUPS]]<br />
[[fr:CUPS]]<br />
[[it:CUPS]]<br />
[[ja:CUPS]]<br />
[[pl:CUPS]]<br />
[[ru:CUPS]]<br />
[[th:CUPS]]<br />
[[tr:CUPS]]<br />
[[zh-CN:CUPS]]<br />
[[zh-TW:CUPS]]<br />
{{Related articles start}}<br />
{{Related|CUPS printer sharing}}<br />
{{Related|CUPS printer-specific problems}}<br />
{{Related|Samba}}<br />
{{Related articles end}}<br />
<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''[[Wikipedia:CUPS|CUPS]] is the standards-based, open source printing system developed by Apple Inc. for OS® X and other UNIX®-like operating systems''".<br />
<br />
Although there are other printing packages such as LPRNG, the Common Unix Printing System is the most popular choice because of its relative ease of use.<br />
<br />
== CUPS Linux printing workflow ==<br />
As of {{Pkg|cups}} version 1.5.3-3, Arch Linux makes use of the new full pdf-based printing workflow. For<br />
further reading check [http://www.linuxfoundation.org/collaborate/workgroups/openprinting/pdfasstandardprintjobformat PDF standard printing job format] and an old [https://wiki.linuxfoundation.org/en/OpenPrinting/Database/CUPS-Filter-Chart CUPS filtering chart] for history and fun.<br />
A good starting point for general Linux printing questions is [http://www.linuxfoundation.org/collaborate/workgroups/openprinting here].<br />
<br />
There are two ways to setup a printer.<br />
* If there's a CUPS server running in your network and sharing a printer you only need to install the client package.<br />
* If the printer is connected directly to your system or you have access to an IPP network printer then setup a local CUPS server.<br />
<br />
== Installing the client package ==<br />
<br />
The package {{Pkg|libcups}} is the only required package. [[pacman|Install]] it from the [[official repositories]].<br />
<br />
Then add your CUPS server's IP address or hostname into {{ic|/etc/cups/client.conf}}, after {{ic|ServerName}}. That is all you need. Every application should quickly find the printer(s) shared by that CUPS server.<br />
<br />
=== Optional advanced network setup ===<br />
<br />
It is also possible to run a entire cupsd+cups-browsed instance on your client with Avahi browsing enabled to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown.<br />
{{Note|This behavior did not change with cups 1.6.x - the difference is that until 1.5.x cupsd was able to do printer browsing alone and now it can only browse its own shared printers.<br />
To get the local cupsd recognise other shared printers offered by a remote cupsd server you need a running local cups-browsed (supported since cups-filters 1.0.26) instance using Avahi to discover unknown printers.}}<br />
<br />
=== Installing CUPS in a 32-bit chroot environment ===<br />
<br />
If you have a 64-bit base installation with a [[Install_bundled_32-bit_system_in_Arch64|32-bit chroot environment]], explicit installation of CUPS is not necessary in the 32-bit environment. To access installed CUPS printers from the chroot environment, one needs to bind the {{ic|/var/run/cups}} directory to the same relative location in the chroot environment. Simply create the directory in the chroot (it probably does not exist), mount (with {{ic|-o bind}} passed to the command}}, and printers should be available from 32-bit chroot applications immediately.<br />
<br />
{{bc|# mkdir /path/to/chroot/var/run/cups<br />
# Example: # mkdir /opt/arch32/var/run/cups<br />
<br />
# mount -o bind /var/run/cups /path/to/chroot/var/run/cups}}<br />
<br />
== Installing the server packages ==<br />
<br />
{{Poor writing|Add Template:App}}<br />
<br />
The following packages and some printer drivers are needed. [[pacman|Install]] them from the [[official repositories]].<br />
<br />
* {{Pkg|cups}} - the actual CUPS daemon<br />
* {{Pkg|ghostscript}} - (optional) PostScript interpreter<br />
* {{Pkg|gsfonts}} - GhostScript standard Type1 fonts<br />
<br />
If you want to enable printer browsing through your network, also install {{Pkg|avahi}} and enable {{ic|avahi-daemon.service}} [[systemd#Using units|using systemd]].<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install {{Pkg|samba}}.<br />
<br />
=== Printer driver ===<br />
<br />
Choosing the right driver depends on the printer. Package names may be misleading because printers of other makes can rely on them. Additional printer drivers are available from the [[AUR]].<br />
<br />
* {{AUR|cndrvcups-lb}} - Canon UFR2 driver with support for LBP, iR and MF series printers.<br />
* {{AUR|cnijfilter-mg4200}} - Printer drivers for Canon MG4200<br />
* {{Pkg|cups-pdf}} - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
* {{AUR|foo2zjs}} - Drivers for ZjStream protocol printers such as the HP Laserjet 1018. More info [http://foo2zjs.rkkda.com here]. It also includes drivers for HBPL protocol such as the Dell C1765 MFP. More info [http://foo2hbpl.rkkda.com here]<br />
* {{Pkg|foomatic-db}}, {{Pkg|foomatic-db-engine}} and {{Pkg|foomatic-db-nonfree}} - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix.<br />
* {{Pkg|gutenprint}} - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostScript, CUPS, Foomatic, and the [[GIMP]]<br />
* {{Pkg|hplip}} - HP drivers for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models, as well as a number of Brother printers.<br />
* {{AUR|hpoj}} - If you are using an HP Officejet, you should also install this package and follow the instructions to avoid problems as in [https://answers.launchpad.net/hplip/+question/133425 this thread].<br />
* {{AUR|samsung-unified-driver}} - Unified Linux Driver for Samsung printers and scanners. Required for new printers such as the ML-2160.<br />
* {{Pkg|splix}} - Samsung drivers for SPL (Samsung Printer Language) printers.<br />
<br />
==== Download printer PPD ====<br />
<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.openprinting.org/printers OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{ic|/usr/share/cups/model/}}}}<br />
<br />
==== Another source for printer drivers ====<br />
<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
== Hardware support and configuration ==<br />
<br />
=== USB printers ===<br />
<br />
{{Tip|Most USB printers should work out of the box, you can skip this section and come back if you can not get your printer to work.}}<br />
<br />
USB printers can get accessed with two methods: The usblp kernel module and libusb. The former is the classic way. It is simple: data is sent to the printer by writing it to a device file as a simple serial data stream. Reading the same device file allows bi-di access, at least for things like reading out ink levels, status, or printer capability information (PJL). It works very well for simple printers, but for multi-function devices (printer/scanner) it is not suitable and manufacturers like HP supply their own backends. Source: [http://lists.linuxfoundation.org/pipermail/printing-architecture/2012/002412.html here].<br />
<br />
==== Blacklisting usblp ====<br />
<br />
{{Warning|As of {{Pkg|cups}} version 1.6.0, you no longer need to [[Kernel modules#Blacklisting|blacklist]] the {{ic|usblp}} kernel module.<br />
<br />
If you find out this is the only way to fix a remaining issue please report this upstream to the CUPS bug tracker and maybe also get in contact with Till Kamppeter (Debian CUPS maintainer). See [http://cups.org/str.php?L4128 upstream bug] for more.}}<br />
<br />
If you have problems getting your USB printer to work, you can try blacklisting the {{ic|usblp}} [[kernel module]]:<br />
<br />
{{hc|/etc/modprobe.d/blacklistusblp.conf|<br />
blacklist usblp<br />
}}<br />
<br />
Custom kernel users may need to manually load the {{ic|usbcore}} [[kernel module]] before proceeding.<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
If you're using {{ic|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{ic|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
=== Parallel port printers ===<br />
<br />
To use a parallel port printer, you will need to load the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]].<br />
<br />
Check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
If you are using a USB to parallel port adapter, CUPS will not be able to detect the printer. As a workaround, add the printer using a different connection type and then change DeviceID in {{ic|/etc/cups/printers.conf}}:<br />
DeviceID = parallel:/dev/usb/lp0<br />
<br />
=== HP Printer ===<br />
HP printers can also be installed via HP's Linux setup tool. Install it by installing {{Pkg|hplip}} from the [[official repositories]].<br />
<br />
To run with qt frontend:<br />
# hp-setup -u<br />
<br />
To run with command line:<br />
# hp-setup -i<br />
<br />
To run systray spool manager:<br />
$ hp-systray<br />
<br />
PPD files are in {{ic|/usr/share/ppd/HP/}}.<br />
<br />
{{Note| If you get errors complaining about missing gobject/dbus dependencies, install {{Pkg|python2-gobject2}} and {{Pkg|python2-dbus}}. For details see this [https://bugs.archlinux.org/task/26666 bug report].}}<br />
<br />
For printers that require the proprietary HP plugin (like the Laserjet Pro P1102w or 1020), install the {{AUR|hplip-plugin}} package from [[AUR]].<br />
<br />
{{Warning| Due to a bug in hplip-setup, you might get error in sys tray or CUPS logs {{ic|Print job failed - required plug-in not found. Please run hp-plugin}} even after you install the aforementioned {{AUR|hplip-plugin}} package from [[AUR]]. To fix, simply modify the printer in CUPS web interface and select the driver manually (preferably the en,en version). After that restart CUPS service.}}<br />
<br />
{{Note|<br />
{{Pkg|hplip}} depends on {{Pkg|foomatic-db-engine}} which prevents the drivers list from appearing when a printer is added to CUPS via the web user interface (following error : "Unable to get list of printer drivers"). The workaround consists of installing {{Pkg|hplip}} first, retrieving the corresponding PPD file from {{ic|/usr/share/ppd/HP/}}, then, removing {{Pkg|hplip}} entirely and the unnecessary dependencies. Finally, install the printer manually using the CUPS web ui, select the PPD file you retrieved then re-install {{Pkg|hplip}}. After a reboot, you should have a fully working printer.}}<br />
<br />
== Configuring ==<br />
<br />
Now that CUPS is installed, there are a variety of options on how to set up printing solutions. As always, the tried and true command line method is at your disposal. CUPS also embeds a full-featured web interface. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. Depending on your needs, you may choose one method or the other.<br />
<br />
If you are planning on connecting to a network printer, rather than one that is directly connected to the computer, you might want to read the [[CUPS printer sharing]] page first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
=== CUPS daemon ===<br />
<br />
With CUPS installed, you can now start {{ic|cups.service}} and optionally, {{ic|cups-browsed.service}} [[systemd#Using units|using systemd]]. Enable them as required.<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{ic|/etc/hostname}}).<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a username and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label (e.g., next to ''USB Printer #1'' for USB printers). Finally, choose the appropriate drivers and the configuration is complete.<br />
<br />
Now test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
{{Tip|See: [[#Alternative CUPS interfaces]] for other front-ends.}}<br />
{{Note|<br />
* When setting up a USB printer, you should see your printer listed on ''Add Printer'' page. If you can only see a "SCSI printer" option, it probably means that CUPS has failed to recognize your printer.<br />
* To enable wireless scanning on certain HP multi-function devices using the {{pkg|hplip}} package, you may need to add the printer as a Network Printer using the HTTP protocol. To determine the proper URI to use, run the {{ic|hp-makeuri}} command.}}<br />
<br />
==== CUPS administration ====<br />
<br />
A username and password will be required when administering the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default username is the one assigned in the ''sys'' group, or root. Other admin groups (e.g. ''printadmin'') may be added to the {{ic|SystemGroup}} line in {{ic|/etc/cups/cups-files.conf}} (you might have to add this line). <br />
<br />
Create the group[s] ({{ic|man groupadd}}) <br />
<br />
# groupadd printadmin <br />
# groupadd lp<br />
<br />
and add the users to the group(s) ({{ic|man gpasswd}}). <br />
<br />
# gpasswd -a username printadmin # for printer administration<br />
# gpasswd -a username lp # for printing priviledges<br />
<br />
# Administrator user group, used to match @SYSTEM in cupsd.conf policy rules...<br />
SystemGroup sys root '''printadmin'''<br />
<br />
Restart {{ic|cups.service}} using systemd. The user must re-login for these changes to take affect.<br />
<br />
Refer to the full cups [http://www.cups.org/documentation.php documentation] for further details.<br />
<br />
==== Remote access to web interface ====<br />
<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{ic|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
Port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
Three levels of access can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{ic|Allow}} statement to that level's section. An {{ic|Allow}} statement can take one or more of the forms listed below:<br />
Allow from all<br />
Allow from host.domain.com<br />
Allow from *.domain.com<br />
Allow from ip-address<br />
Allow from ip-address/netmask<br />
Allow from @LOCAL<br />
<br />
Deny statements can also be used. For example, if wanting to give full access to all hosts on your local network interfaces, file {{ic|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
'''Allow From @LOCAL'''<br />
</Location><br />
<br />
You might also need to add:<br />
<br />
DefaultEncryption Never<br />
<br />
This should avoid the error: 426 - Upgrade Required when using the CUPS web interface from a remote machine.<br />
<br />
=== Command-line configuration ===<br />
<br />
CUPS can be fully controlled from command-line with nice tools, ''i.e.'' the lp* and the cups* command families.<br />
<br />
On Arch Linux, most commands support auto-completion with common shells.<br />
Also note that command-line switches cannot be grouped.<br />
<br />
;List the devices<br />
# lpinfo -v<br />
<br />
;List the drivers<br />
# lpinfo -m<br />
<br />
;Add a new printer<br />
# lpadmin -p ''printer'' -E -v ''device'' -P ''ppd''<br />
<br />
The ''printer'' is up to you. The device can be retrieved from the 'lpinfo -v' command.<br />
Example:<br />
# lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH" -P /usr/share/ppd/HP/hp-deskjet_940c.ppd.gz<br />
<br />
In the following, the ''printer'' references the name you have used here to set up the printer.<br />
<br />
;Set the default printer<br />
$ lpoptions -d ''printer''<br />
<br />
;Check the status<br />
$ lpstat -s<br />
$ lpstat -p ''printer''<br />
<br />
;Deactivate a printer<br />
# cupsdisable ''printer''<br />
<br />
;Activate a printer<br />
# cupsenable ''printer''<br />
<br />
;Remove a printer<br />
First set it to reject all incoming entries:<br />
# cupsreject ''printer''<br />
Then disable it.<br />
# cupsdisable ''printer''<br />
Finally remove it.<br />
# lpadmin -x ''printer''<br />
<br />
;Print a file<br />
$ lpr ''file''<br />
$ lpr -# 17 ''file'' # print the file 17 times<br />
$ echo "Hello, world!" | lpr -p # print the result of a command. The -p switch adds a header.<br />
<br />
;Check the printing queue<br />
$ lpq<br />
$ lpq -a # on all printers<br />
<br />
;Clear the printing queue<br />
# lprm # remove last entry only<br />
# lprm - # remove all entries<br />
<br />
=== Alternative CUPS interfaces ===<br />
<br />
==== GNOME ====<br />
<br />
You can configure and manage printers by [[pacman|installing]] {{Pkg|system-config-printer}}. This program does pull in some gnome dependencies.<br />
<br />
If your user does not have sufficient priviliges to administer the cups scheduler, system-config-printer will request the root password when it starts. You can avoid this by performing the following instructions.<br />
<br />
1. Create a group for administering the cups scheduler:<br />
<br />
# groupadd lpadmin<br />
<br />
2. Add yourself to the newly created group:<br />
<br />
# usermod -aG lpadmin ''username''<br />
<br />
3. Tell cups to respect the newly created group:<br />
<br />
{{hc|/etc/cups/cups-files.conf|<br />
...<br />
SystemGroup sys root '''lpadmin'''<br />
...}}<br />
<br />
4. Restart cups:<br />
<br />
# systemctl restart cups<br />
<br />
5. Log out and log in again or restart your computer.<br />
<br />
==== KDE ====<br />
<br />
[[KDE]] users can modify their printers from the Control Center. The {{Pkg|kdeutils-print-manager}} package may need be installed if the Printers interface isn't found in the Hardware group. KDE users should refer to the desktop environments' documentation for more information on how to use the interface.<br />
<br />
==== Other ====<br />
<br />
There is also {{AUR|gtklp}} in the [[AUR]].<br />
<br />
== PDF virtual printer ==<br />
{{Note| With GNOME, it is now possible to directly print into a PDF or Postscript file, therefore CUPS-PDF is no longer required on such system. }}<br />
<br />
{{Pkg|cups-pdf}} is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. This package is not necessary, but it can be quite useful.<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Add Printer<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Find generated PDF documents in a sub-directory located at {{ic|/var/spool/cups-pdf}}. Normally, the subdirectory is named after the user who performed the job. A little tweak helps you to find your printed PDF documents more easily. Edit {{ic|/etc/cups/cups-pdf.conf}} by changing the line<br />
#Out /var/spool/cups-pdf/${USER}<br />
<br />
to<br />
<br />
Out ${HOME}<br />
<br />
=== Print to PostScript ===<br />
<br />
The CUPS-PDF (Virtual PDF Printer) actually creates a PostScript file and then creates the PDF using the ps2pdf utility. To print to PostScript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
== Troubleshooting ==<br />
<br />
The best way to get printing working is to set 'LogLevel' in {{ic|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{ic|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{ic|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{ic|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{ic|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
=== Problems resulting from upgrades ===<br />
<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
==== CUPS stops working ====<br />
<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" may result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy {{ic|/etc/cups/cupsd.conf.default}} to {{ic|/etc/cups/cupsd.conf}} (backup the old configuration if needed) and restart CUPS to employ the new settings.<br />
<br />
==== All jobs are "stopped" ====<br />
<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
==== All jobs are "The printer is not responding" ====<br />
<br />
On networked printers, you should check that the name that CUPS uses as its connection URI resolves to the printer's IP via DNS, e.g.<br />
If your printer's connection looks like this:<br />
lpd://BRN_020554/BINARY_P1<br />
<br />
then the hostname 'BRN_020554' needs to resolve to the printer's IP from the server running CUPS<br />
<br />
==== The PPD version is not compatible with gutenprint ====<br />
<br />
Run:<br />
# /usr/bin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
=== Other ===<br />
<br />
==== Printer "Paused" or "Stopped" with Status "Rendering completed" ====<br />
<br />
When low on ink, some printers will get stuck in "Rendering completed" status and, if it is a network printer, the printer may even become unreachable from CUPS' perspective despite being properly connected to the network. Replacing the low/depleted ink cartridge(s) in this setting will return the printer to "Ready" status and, if it is a network printer, will make the printer available to CUPS again.<br />
<br />
{{Warning|If you use third-party ink cartridges, the ink levels reported by the printer may be inaccurate. If you use third-party ink and your printer used to work fine but is now getting stuck on "Rendering completed" status, replace the ink cartridges regardless of the reported ink levels before trying other fixes.}}<br />
<br />
If low ink is not the issue, check the "Group ID" of files in /etc/cups, /var/log/cups, and, if you have "root" permission, /var/spool/cups. The files should have GID "lp". If some files have GID "nobody", then check the named groups in the "Group" and "SystemGroup" directives in the file /etc/cups/cups-files.conf. Typically there will be "Group lp" and "SystemGroup lpadmin sys root". Make sure that the group in "Group" is NOT also in "SystemGroup". In particular, make sure that the name "lp" is NOT listed in the "SystemGroup" directive, when it is used in the "Group" directive. This is counter to recommendations made in the CUPS and KDE wiki pages in the past. If you had added "lp" to the "SystemGroup" directive, as had been suggested, remove "lp" from the "SystemGroup", or run "sudo groupadd -g107 lpadmin" and change "lp" to "lpadmin" in the "SystemGroup" directive.<br />
<br />
Explanation of GID issue: For security reasons, cupsd does not allow external cups helper programs, which use the "Group" GID, to run in the Administration groups, which are those GIDs listed in "SystemGroup". If the named group in the Group directive is also in the SystemGroup directive, then cupsd changes the Group GID to "nobody" instead, without warning. However, the printer devices in "/dev/", for instance "/dev/parport0", are created with user "root" and group "lp". When cupsd then tries to print, it "pauses" or "stops" because it does not have permission to write the printer device file, and does not provide any useful error message. Making the printer device files "world writable" can bypass the problem, but is not the proper solution.<br />
<br />
==== CUPS permission errors ====<br />
<br />
* Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
* Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
==== HPLIP printer sends "/usr/lib/cups/backend/hp failed" error ====<br />
<br />
Make sure dbus is installed and running. If the error persists, try starting avahi-daemon.<br />
<br />
Try adding the printer as a Network Printer using the http:// protocol. Generate the printer URI with {{ic|hp-makeuri}}.<br />
<br />
{{Note|There might need to set permissions issues right. Follow indications here: [[CUPS#Device node permissions]].}}<br />
<br />
==== HPLIP printer claims job is complete but printer does nothing ====<br />
<br />
This happens on HP printers when you select the (old) hpijs driver (e.g. the Deskjet D1600 series). Instead, use the hpcups driver when adding the printer.<br />
<br />
Some HP printers (e.g HP LaserJet) require their firmware to be downloaded from the computer every time the printer is switched on. If there is an issue with udev (or equivalent) and the firmware download rule is never fired, you may experience this issue.<br />
As a workaround, you can manually download the firmware to the printer. Ensure the printer is plugged in and switched on, then enter<br />
hp-firmware -n<br />
<br />
==== hp-setup asks to specify the PPD file for the discovered printer ====<br />
<br />
Install CUPS before running hp-setup.<br />
<br />
==== I have installed Qt, but hp-setup reports "Qt/PyQt 4 initialization failed" ====<br />
<br />
"hp-check -t" won't give you useful information to find the required package. You have to install all the "Dependent Packages" prefixed with "python2" in https://www.archlinux.org/packages/extra/x86_64/hplip/<br />
<br />
==== hp-setup finds the printer automatically but reports "Unable to communicate with device" when printing test page immediately afterwards ====<br />
<br />
This at least happens to hplip 3.13.5-2 for HP Officejet 6500A through local network connection. To solve the problem, specify the IP address of the HP printer for hp-setup to locate the printer.<br />
<br />
==== hp-toolbox sends an error, "Unable to communicate with device" ====<br />
<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/''printer id''<br />
or, "{{ic|Unable to communicate with device"}}", then it may be needed to [[Groups#Group management|add the user to the lp and sys groups]].<br />
<br />
This can also be caused by printers such as the P1102 that provide a virtual CD-ROM drive for MS Windows drivers. The lp dev appears and then disappears. In that case, try the '''usb-modeswitch''' and '''usb-modeswitch-data''' packages, that lets one switch off the "Smart Drive" (udev rules included in said packages).<br />
<br />
This can also occur with network attached printers if the [[Avahi|avahi-daemon]] is not running. Another possibility is the specification of the printer's IP address in ''hp-setup'' fails to locate the printer because the IP address of the the printer changed due to DHCP.<br />
<br />
==== CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer ====<br />
<br />
If receiving any of the following error messages in {{ic|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer ''printer_name'' not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure {{pkg|hplip}} has been [[pacman|installed]], in addition to [[#Packages|the packages mentioned above]]. See [https://bbs.archlinux.org/viewtopic.php?id=65615 this forum post] for more information.<br />
<br />
==== Printing fails with unauthorised error ====<br />
<br />
If the user has been added to the lp group, and allowed to print (set in {{ic|cupsd.conf}}), then the problem lies in {{ic|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
==== Unknown supported format: application/postscript ====<br />
<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{ic|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{ic|/etc/cups/mime.types}}.<br />
<br />
==== Finding URIs for Windows print servers ====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
{{bc| WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series}}<br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
If it won't work try '%20' instead of spaces.<br />
<br />
==== Print-Job client-error-document-format-not-supported ====<br />
<br />
Try installing the foomatic packages and use a foomatic driver.<br />
<br />
==== Unable to get list of printer drivers ====<br />
<br />
* Check the {{ic|ServerName}} in {{ic|/etc/cups/client.conf}} is written without http://<br />
ServerName localhost:631<br />
* Try to remove Foomatic drivers or refer to [[#HP_Printer]] for a workaround.<br />
<br />
==== lp: Error - Scheduler Not Responding ====<br />
<br />
If you get this error when printing a document using:<br />
<br />
$ lp document-to-print<br />
<br />
Try setting the {{ic|CUPS_SERVER}} environment variable:<br />
<br />
$ export CUPS_SERVER=localhost<br />
<br />
If this solves your problem, make the solution permanent by adding the export line above to {{ic|~/.bash_profile}}.<br />
<br />
==== CUPS prints only an empty and an error-message page on HP LaserJet ====<br />
<br />
There is a bug that causes CUPS to fail when printing images on HP LaserJet (in my case 3380). The bug has been reported and fixed by [https://bugs.launchpad.net/ubuntu/+source/cups-filters/+bug/998087 Ubuntu].<br />
The first page is empty, the second page contains the following error message:<br />
ERROR:<br />
invalidaccess<br />
OFFENDING COMMAND:<br />
filter<br />
STACK:<br />
/SubFileDecode<br />
endstream<br />
...<br />
<br />
In order to fix the issue, run the following command as root:<br />
# lpadmin -p ''printer'' -o pdftops-renderer-default=pdftops<br />
<br />
==== "Using invalid Host" error message ====<br />
<br />
Try adding {{ic|ServerAlias *}} into {{ic|/etc/cups/cupsd.conf}}.<br />
<br />
==== Printer doesn't print with an "Filter failed" message on CUPS web interface (HP printer) ====<br />
<br />
Change the permissions of the printer USB port. Get the bus and device number from {{ic|lsusb}}, then set the permission using:<br />
<br />
{{hc| lsusb |<br />
Bus <BUSID> Device <DEVID>: ID <PRINTERID>:<VENDOR> Hewlett-Packard DeskJet D1360}}<br />
<br />
Then substitute the provided device information to the <br />
<br />
# chmod 0666 /dev/bus/usb/<BUSID>/<DEVID><br />
<br />
To make the persistent permission change that will be triggered automatically each time the computer is rebooted, add the following line.<br />
<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="<VENDOR>", ATTRS{idProduct}=="<PRINTERID>", GROUP="lp", MODE:="666"<br />
}}<br />
<br />
Each system may vary, so consult [[udev#List_attributes_of_a_device]] wiki page.<br />
<br />
==== Printer does not print with a "Filter failed" message on CUPS web interface (HP printer connected over network) ====<br />
<br />
Start, enable, and restart the {{ic|avahi-daemon}} service.<br />
<br />
==== HPLIP 3.13: Plugin is installed, but HP Device Manager complains it is not ====<br />
<br />
The issue might have to do with the file permission change that had been made to {{ic|/var/lib/hp/hplip.state}}. To correct the issue, a simple {{ic|chmod 644 /var/lib/hp/hplip.state}} and {{ic|chmod 755 /var/lib/hp}} should be sufficient. For further information, please read this [https://bugs.launchpad.net/hplip/+bug/1131596 link].<br />
<br />
==== Printer is not recognized by CUPS ====<br />
<br />
If your printer is not listed in the "Add Printers" page of the CUPS web interface, nor by {{ic|lpinfo -v}}, try the following (suggested in [https://bbs.archlinux.org/viewtopic.php?pid=1037279#p1037279 this thread]):<br />
<br />
* Remove {{ic|usblp}} from blacklist<br />
* Load {{ic|usblp}} module<br />
# modprobe usblp<br />
* Stop CUPS<br />
* Add the following udev rule in a new rule file:<br />
{{hc|/etc/udev/rules.d/10-cups_device_link.rules|2=<br />
KERNEL=="lp[0-9]", SYMLINK+="%k", GROUP="lp"<br />
}}<br />
* Reload udev rules:<br />
# udevadm control --reload-rules<br />
* Unplug the printer, and plug it in again.<br />
* Wait a few seconds, and then start the CUPS service.<br />
<br />
==== Cannot load /etc/samba/smb.conf ====<br />
<br />
If you are printing to a remote printer over SMB and get this error message: "Can't load /etc/samba/smb.conf - run testparm to debug it", then create an empty {{ic|/etc/samba/smb.conf}} file:<br />
<br />
# mkdir /etc/samba<br />
# touch /etc/samba/smb.conf<br />
<br />
and restart the CUPS service.<br />
<br />
==== CUPS' systemd service does not start even though it is enabled ====<br />
<br />
The systemd service file provided by CUPS uses socket activation, meaning the service is only started when an application connects to CUPS' socket. However, the systemd socket file provided by CUPS only works for the local <br />
{{ic|/var/run/cups/cups.sock}} socket. <br />
<br />
In order to have the CUPS service start when initiating a print job over the network, create the following file:<br />
<br />
{{hc|1=/etc/systemd/system/cups.socket|2=<br />
.include /usr/lib/systemd/system/cups.socket<br />
<br />
[Socket]<br />
ListenDatagram=0.0.0.0:631<br />
}}<br />
<br />
Then reload systemd:<br />
<br />
# systemctl --system daemon-reload<br />
<br />
Confirm that everything is working correctly:<br />
<br />
{{bc|<br />
# systemctl is-enabled cups.service &#124;&#124; systemctl enable cups.service<br />
# systemctl status cups.socket<br />
cups.socket - CUPS Printing Service Sockets<br />
Loaded: loaded (/etc/systemd/system/cups.socket; enabled)<br />
Active: inactive (dead)<br />
Listen: /var/run/cups/cups.sock (Stream)<br />
0.0.0.0:631 (Stream)<br />
0.0.0.0:631 (Datagram)<br />
}}<br />
<br />
CUPS should now start automatically when printing locally or over the network.<br />
<br />
==== "Forbidden" error when adding a printer ====<br />
<br />
If adding a printer through the web interface returns an error: ''Forbidden'', the most likely reason is that the privileges are not set correctly. One way to fix it is to add the administering user to the group {{ic|sys}}. For example,<br />
# usermod -a -G sys ''username''<br />
<br />
== See also ==<br />
<br />
* [http://localhost:631/help Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's printing guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation resources]''<br />
* [http://wiki.gotux.net/tutorials/software/hp-printer Install HP printers easy way]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=CUPS&diff=339235CUPS2014-10-08T00:24:05Z<p>Jstjohn: /* Unable to get list of printer drivers */ add missing templates</p>
<hr />
<div>[[Category:Printers]]<br />
[[cs:CUPS]]<br />
[[de:CUPS]]<br />
[[es:CUPS]]<br />
[[fr:CUPS]]<br />
[[it:CUPS]]<br />
[[ja:CUPS]]<br />
[[pl:CUPS]]<br />
[[ru:CUPS]]<br />
[[th:CUPS]]<br />
[[tr:CUPS]]<br />
[[zh-CN:CUPS]]<br />
[[zh-TW:CUPS]]<br />
{{Related articles start}}<br />
{{Related|CUPS printer sharing}}<br />
{{Related|CUPS printer-specific problems}}<br />
{{Related|Samba}}<br />
{{Related articles end}}<br />
<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''[[Wikipedia:CUPS|CUPS]] is the standards-based, open source printing system developed by Apple Inc. for OS® X and other UNIX®-like operating systems''".<br />
<br />
Although there are other printing packages such as LPRNG, the Common Unix Printing System is the most popular choice because of its relative ease of use.<br />
<br />
== CUPS Linux printing workflow ==<br />
As of {{Pkg|cups}} version 1.5.3-3, Arch Linux makes use of the new full pdf-based printing workflow. For<br />
further reading check [http://www.linuxfoundation.org/collaborate/workgroups/openprinting/pdfasstandardprintjobformat PDF standard printing job format] and an old [https://wiki.linuxfoundation.org/en/OpenPrinting/Database/CUPS-Filter-Chart CUPS filtering chart] for history and fun.<br />
A good starting point for general Linux printing questions is [http://www.linuxfoundation.org/collaborate/workgroups/openprinting here].<br />
<br />
There are two ways to setup a printer.<br />
* If there's a CUPS server running in your network and sharing a printer you only need to install the client package.<br />
* If the printer is connected directly to your system or you have access to an IPP network printer then setup a local CUPS server.<br />
<br />
== Installing the client package ==<br />
<br />
The package {{Pkg|libcups}} is the only required package. [[pacman|Install]] it from the [[official repositories]].<br />
<br />
Then add your CUPS server's IP address or hostname into {{ic|/etc/cups/client.conf}}, after {{ic|ServerName}}. That is all you need. Every application should quickly find the printer(s) shared by that CUPS server.<br />
<br />
=== Optional advanced network setup ===<br />
<br />
It is also possible to run a entire cupsd+cups-browsed instance on your client with Avahi browsing enabled to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown.<br />
{{Note|This behavior did not change with cups 1.6.x - the difference is that until 1.5.x cupsd was able to do printer browsing alone and now it can only browse its own shared printers.<br />
To get the local cupsd recognise other shared printers offered by a remote cupsd server you need a running local cups-browsed (supported since cups-filters 1.0.26) instance using Avahi to discover unknown printers.}}<br />
<br />
=== Installing CUPS in a 32-bit chroot environment ===<br />
<br />
If you have a 64-bit base installation with a [[Install_bundled_32-bit_system_in_Arch64|32-bit chroot environment]], explicit installation of CUPS is not necessary in the 32-bit environment. To access installed CUPS printers from the chroot environment, one needs to bind the {{ic|/var/run/cups}} directory to the same relative location in the chroot environment. Simply create the directory in the chroot (it probably does not exist), mount (with {{ic|-o bind}} passed to the command}}, and printers should be available from 32-bit chroot applications immediately.<br />
<br />
{{bc|# mkdir /path/to/chroot/var/run/cups<br />
# Example: # mkdir /opt/arch32/var/run/cups<br />
<br />
# mount -o bind /var/run/cups /path/to/chroot/var/run/cups}}<br />
<br />
== Installing the server packages ==<br />
<br />
{{Poor writing|Add Template:App}}<br />
<br />
The following packages and some printer drivers are needed. [[pacman|Install]] them from the [[official repositories]].<br />
<br />
* {{Pkg|cups}} - the actual CUPS daemon<br />
* {{Pkg|ghostscript}} - (optional) PostScript interpreter<br />
* {{Pkg|gsfonts}} - GhostScript standard Type1 fonts<br />
<br />
If you want to enable printer browsing through your network, also install {{Pkg|avahi}} and enable {{ic|avahi-daemon.service}} [[systemd#Using units|using systemd]].<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install {{Pkg|samba}}.<br />
<br />
=== Printer driver ===<br />
<br />
Choosing the right driver depends on the printer. Package names may be misleading because printers of other makes can rely on them. Additional printer drivers are available from the [[AUR]].<br />
<br />
* {{AUR|cndrvcups-lb}} - Canon UFR2 driver with support for LBP, iR and MF series printers.<br />
* {{AUR|cnijfilter-mg4200}} - Printer drivers for Canon MG4200<br />
* {{Pkg|cups-pdf}} - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
* {{AUR|foo2zjs}} - Drivers for ZjStream protocol printers such as the HP Laserjet 1018. More info [http://foo2zjs.rkkda.com here]. It also includes drivers for HBPL protocol such as the Dell C1765 MFP. More info [http://foo2hbpl.rkkda.com here]<br />
* {{Pkg|foomatic-db}}, {{Pkg|foomatic-db-engine}} and {{Pkg|foomatic-db-nonfree}} - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix.<br />
* {{Pkg|gutenprint}} - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostScript, CUPS, Foomatic, and the [[GIMP]]<br />
* {{Pkg|hplip}} - HP drivers for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models, as well as a number of Brother printers.<br />
* {{AUR|hpoj}} - If you are using an HP Officejet, you should also install this package and follow the instructions to avoid problems as in [https://answers.launchpad.net/hplip/+question/133425 this thread].<br />
* {{AUR|samsung-unified-driver}} - Unified Linux Driver for Samsung printers and scanners. Required for new printers such as the ML-2160.<br />
* {{Pkg|splix}} - Samsung drivers for SPL (Samsung Printer Language) printers.<br />
<br />
==== Download printer PPD ====<br />
<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.openprinting.org/printers OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{ic|/usr/share/cups/model/}}}}<br />
<br />
==== Another source for printer drivers ====<br />
<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
== Hardware support and configuration ==<br />
<br />
=== USB printers ===<br />
<br />
{{Tip|Most USB printers should work out of the box, you can skip this section and come back if you can not get your printer to work.}}<br />
<br />
USB printers can get accessed with two methods: The usblp kernel module and libusb. The former is the classic way. It is simple: data is sent to the printer by writing it to a device file as a simple serial data stream. Reading the same device file allows bi-di access, at least for things like reading out ink levels, status, or printer capability information (PJL). It works very well for simple printers, but for multi-function devices (printer/scanner) it is not suitable and manufacturers like HP supply their own backends. Source: [http://lists.linuxfoundation.org/pipermail/printing-architecture/2012/002412.html here].<br />
<br />
==== Blacklisting usblp ====<br />
<br />
{{Warning|As of {{Pkg|cups}} version 1.6.0, you no longer need to [[Kernel modules#Blacklisting|blacklist]] the {{ic|usblp}} kernel module.<br />
<br />
If you find out this is the only way to fix a remaining issue please report this upstream to the CUPS bug tracker and maybe also get in contact with Till Kamppeter (Debian CUPS maintainer). See [http://cups.org/str.php?L4128 upstream bug] for more.}}<br />
<br />
If you have problems getting your USB printer to work, you can try blacklisting the {{ic|usblp}} [[kernel module]]:<br />
<br />
{{hc|/etc/modprobe.d/blacklistusblp.conf|<br />
blacklist usblp<br />
}}<br />
<br />
Custom kernel users may need to manually load the {{ic|usbcore}} [[kernel module]] before proceeding.<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
If you're using {{ic|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{ic|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
=== Parallel port printers ===<br />
<br />
To use a parallel port printer, you will need to load the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]].<br />
<br />
Check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
If you are using a USB to parallel port adapter, CUPS will not be able to detect the printer. As a workaround, add the printer using a different connection type and then change DeviceID in {{ic|/etc/cups/printers.conf}}:<br />
DeviceID = parallel:/dev/usb/lp0<br />
<br />
=== HP Printer ===<br />
HP printers can also be installed via HP's Linux setup tool. Install it by installing {{Pkg|hplip}} from the [[official repositories]].<br />
<br />
To run with qt frontend:<br />
# hp-setup -u<br />
<br />
To run with command line:<br />
# hp-setup -i<br />
<br />
To run systray spool manager:<br />
$ hp-systray<br />
<br />
PPD files are in {{ic|/usr/share/ppd/HP/}}.<br />
<br />
{{Note| If you get errors complaining about missing gobject/dbus dependencies, install {{Pkg|python2-gobject2}} and {{Pkg|python2-dbus}}. For details see this [https://bugs.archlinux.org/task/26666 bug report].}}<br />
<br />
For printers that require the proprietary HP plugin (like the Laserjet Pro P1102w or 1020), install the {{AUR|hplip-plugin}} package from [[AUR]].<br />
<br />
{{Warning| Due to a bug in hplip-setup, you might get error in sys tray or CUPS logs {{ic|Print job failed - required plug-in not found. Please run hp-plugin}} even after you install the aforementioned {{AUR|hplip-plugin}} package from [[AUR]]. To fix, simply modify the printer in CUPS web interface and select the driver manually (preferably the en,en version). After that restart CUPS service.}}<br />
<br />
{{Note|<br />
{{Pkg|hplip}} depends on {{Pkg|foomatic-db-engine}} which prevents the drivers list from appearing when a printer is added to CUPS via the web user interface (following error : "Unable to get list of printer drivers"). The workaround consists of installing {{Pkg|hplip}} first, retrieving the corresponding PPD file from {{ic|/usr/share/ppd/HP/}}, then, removing {{Pkg|hplip}} entirely and the unnecessary dependencies. Finally, install the printer manually using the CUPS web ui, select the PPD file you retrieved then re-install {{Pkg|hplip}}. After a reboot, you should have a fully working printer.}}<br />
<br />
== Configuring ==<br />
<br />
Now that CUPS is installed, there are a variety of options on how to set up printing solutions. As always, the tried and true command line method is at your disposal. CUPS also embeds a full-featured web interface. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. Depending on your needs, you may choose one method or the other.<br />
<br />
If you are planning on connecting to a network printer, rather than one that is directly connected to the computer, you might want to read the [[CUPS printer sharing]] page first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
=== CUPS daemon ===<br />
<br />
With CUPS installed, you can now start {{ic|cups.service}} and optionally, {{ic|cups-browsed.service}} [[systemd#Using units|using systemd]]. Enable them as required.<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{ic|/etc/hostname}}).<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a username and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label (e.g., next to ''USB Printer #1'' for USB printers). Finally, choose the appropriate drivers and the configuration is complete.<br />
<br />
Now test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
{{Tip|See: [[#Alternative CUPS interfaces]] for other front-ends.}}<br />
{{Note|<br />
* When setting up a USB printer, you should see your printer listed on ''Add Printer'' page. If you can only see a "SCSI printer" option, it probably means that CUPS has failed to recognize your printer.<br />
* To enable wireless scanning on certain HP multi-function devices using the {{pkg|hplip}} package, you may need to add the printer as a Network Printer using the HTTP protocol. To determine the proper URI to use, run the {{ic|hp-makeuri}} command.}}<br />
<br />
==== CUPS administration ====<br />
<br />
A username and password will be required when administering the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default username is the one assigned in the ''sys'' group, or root. Other admin groups (e.g. ''printadmin'') may be added to the {{ic|SystemGroup}} line in {{ic|/etc/cups/cups-files.conf}} (you might have to add this line). <br />
<br />
Create the group[s] ({{ic|man groupadd}}) <br />
<br />
# groupadd printadmin <br />
# groupadd lp<br />
<br />
and add the users to the group(s) ({{ic|man gpasswd}}). <br />
<br />
# gpasswd -a username printadmin # for printer administration<br />
# gpasswd -a username lp # for printing priviledges<br />
<br />
# Administrator user group, used to match @SYSTEM in cupsd.conf policy rules...<br />
SystemGroup sys root '''printadmin'''<br />
<br />
Restart {{ic|cups.service}} using systemd. The user must re-login for these changes to take affect.<br />
<br />
Refer to the full cups [http://www.cups.org/documentation.php documentation] for further details.<br />
<br />
==== Remote access to web interface ====<br />
<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{ic|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
Port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
Three levels of access can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{ic|Allow}} statement to that level's section. An {{ic|Allow}} statement can take one or more of the forms listed below:<br />
Allow from all<br />
Allow from host.domain.com<br />
Allow from *.domain.com<br />
Allow from ip-address<br />
Allow from ip-address/netmask<br />
Allow from @LOCAL<br />
<br />
Deny statements can also be used. For example, if wanting to give full access to all hosts on your local network interfaces, file {{ic|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
'''Allow From @LOCAL'''<br />
</Location><br />
<br />
You might also need to add:<br />
<br />
DefaultEncryption Never<br />
<br />
This should avoid the error: 426 - Upgrade Required when using the CUPS web interface from a remote machine.<br />
<br />
=== Command-line configuration ===<br />
<br />
CUPS can be fully controlled from command-line with nice tools, ''i.e.'' the lp* and the cups* command families.<br />
<br />
On Arch Linux, most commands support auto-completion with common shells.<br />
Also note that command-line switches cannot be grouped.<br />
<br />
;List the devices<br />
# lpinfo -v<br />
<br />
;List the drivers<br />
# lpinfo -m<br />
<br />
;Add a new printer<br />
# lpadmin -p ''printer'' -E -v ''device'' -P ''ppd''<br />
<br />
The ''printer'' is up to you. The device can be retrieved from the 'lpinfo -v' command.<br />
Example:<br />
# lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH" -P /usr/share/ppd/HP/hp-deskjet_940c.ppd.gz<br />
<br />
In the following, the ''printer'' references the name you have used here to set up the printer.<br />
<br />
;Set the default printer<br />
$ lpoptions -d ''printer''<br />
<br />
;Check the status<br />
$ lpstat -s<br />
$ lpstat -p ''printer''<br />
<br />
;Deactivate a printer<br />
# cupsdisable ''printer''<br />
<br />
;Activate a printer<br />
# cupsenable ''printer''<br />
<br />
;Remove a printer<br />
First set it to reject all incoming entries:<br />
# cupsreject ''printer''<br />
Then disable it.<br />
# cupsdisable ''printer''<br />
Finally remove it.<br />
# lpadmin -x ''printer''<br />
<br />
;Print a file<br />
$ lpr ''file''<br />
$ lpr -# 17 ''file'' # print the file 17 times<br />
$ echo "Hello, world!" | lpr -p # print the result of a command. The -p switch adds a header.<br />
<br />
;Check the printing queue<br />
$ lpq<br />
$ lpq -a # on all printers<br />
<br />
;Clear the printing queue<br />
# lprm # remove last entry only<br />
# lprm - # remove all entries<br />
<br />
=== Alternative CUPS interfaces ===<br />
<br />
==== GNOME ====<br />
<br />
You can configure and manage printers by [[pacman|installing]] {{Pkg|system-config-printer}}. This program does pull in some gnome dependencies.<br />
<br />
If your user does not have sufficient priviliges to administer the cups scheduler, system-config-printer will request the root password when it starts. You can avoid this by performing the following instructions.<br />
<br />
1. Create a group for administering the cups scheduler:<br />
<br />
# groupadd lpadmin<br />
<br />
2. Add yourself to the newly created group:<br />
<br />
# usermod -aG lpadmin ''username''<br />
<br />
3. Tell cups to respect the newly created group:<br />
<br />
{{hc|/etc/cups/cups-files.conf|<br />
...<br />
SystemGroup sys root '''lpadmin'''<br />
...}}<br />
<br />
4. Restart cups:<br />
<br />
# systemctl restart cups<br />
<br />
5. Log out and log in again or restart your computer.<br />
<br />
==== KDE ====<br />
<br />
[[KDE]] users can modify their printers from the Control Center. The {{Pkg|kdeutils-print-manager}} package may need be installed if the Printers interface isn't found in the Hardware group. KDE users should refer to the desktop environments' documentation for more information on how to use the interface.<br />
<br />
==== Other ====<br />
<br />
There is also {{AUR|gtklp}} in the [[AUR]].<br />
<br />
== PDF virtual printer ==<br />
{{Note| With GNOME, it is now possible to directly print into a PDF or Postscript file, therefore CUPS-PDF is no longer required on such system. }}<br />
<br />
{{Pkg|cups-pdf}} is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. This package is not necessary, but it can be quite useful.<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Add Printer<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Find generated PDF documents in a sub-directory located at {{ic|/var/spool/cups-pdf}}. Normally, the subdirectory is named after the user who performed the job. A little tweak helps you to find your printed PDF documents more easily. Edit {{ic|/etc/cups/cups-pdf.conf}} by changing the line<br />
#Out /var/spool/cups-pdf/${USER}<br />
<br />
to<br />
<br />
Out ${HOME}<br />
<br />
=== Print to PostScript ===<br />
<br />
The CUPS-PDF (Virtual PDF Printer) actually creates a PostScript file and then creates the PDF using the ps2pdf utility. To print to PostScript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
== Troubleshooting ==<br />
<br />
The best way to get printing working is to set 'LogLevel' in {{ic|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{ic|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{ic|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{ic|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{ic|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
=== Problems resulting from upgrades ===<br />
<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
==== CUPS stops working ====<br />
<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" may result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy {{ic|/etc/cups/cupsd.conf.default}} to {{ic|/etc/cups/cupsd.conf}} (backup the old configuration if needed) and restart CUPS to employ the new settings.<br />
<br />
==== All jobs are "stopped" ====<br />
<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
==== All jobs are "The printer is not responding" ====<br />
<br />
On networked printers, you should check that the name that CUPS uses as its connection URI resolves to the printer's IP via DNS, e.g.<br />
If your printer's connection looks like this:<br />
lpd://BRN_020554/BINARY_P1<br />
<br />
then the hostname 'BRN_020554' needs to resolve to the printer's IP from the server running CUPS<br />
<br />
==== The PPD version is not compatible with gutenprint ====<br />
<br />
Run:<br />
# /usr/bin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
=== Other ===<br />
<br />
==== Printer "Paused" or "Stopped" with Status "Rendering completed" ====<br />
<br />
When low on ink, some printers will get stuck in "Rendering completed" status and, if it is a network printer, the printer may even become unreachable from CUPS' perspective despite being properly connected to the network. Replacing the low/depleted ink cartridge(s) in this setting will return the printer to "Ready" status and, if it is a network printer, will make the printer available to CUPS again.<br />
<br />
{{Warning|If you use third-party ink cartridges, the ink levels reported by the printer may be inaccurate. If you use third-party ink and your printer used to work fine but is now getting stuck on "Rendering completed" status, replace the ink cartridges regardless of the reported ink levels before trying other fixes.}}<br />
<br />
If low ink is not the issue, check the "Group ID" of files in /etc/cups, /var/log/cups, and, if you have "root" permission, /var/spool/cups. The files should have GID "lp". If some files have GID "nobody", then check the named groups in the "Group" and "SystemGroup" directives in the file /etc/cups/cups-files.conf. Typically there will be "Group lp" and "SystemGroup lpadmin sys root". Make sure that the group in "Group" is NOT also in "SystemGroup". In particular, make sure that the name "lp" is NOT listed in the "SystemGroup" directive, when it is used in the "Group" directive. This is counter to recommendations made in the CUPS and KDE wiki pages in the past. If you had added "lp" to the "SystemGroup" directive, as had been suggested, remove "lp" from the "SystemGroup", or run "sudo groupadd -g107 lpadmin" and change "lp" to "lpadmin" in the "SystemGroup" directive.<br />
<br />
Explanation of GID issue: For security reasons, cupsd does not allow external cups helper programs, which use the "Group" GID, to run in the Administration groups, which are those GIDs listed in "SystemGroup". If the named group in the Group directive is also in the SystemGroup directive, then cupsd changes the Group GID to "nobody" instead, without warning. However, the printer devices in "/dev/", for instance "/dev/parport0", are created with user "root" and group "lp". When cupsd then tries to print, it "pauses" or "stops" because it does not have permission to write the printer device file, and does not provide any useful error message. Making the printer device files "world writable" can bypass the problem, but is not the proper solution.<br />
<br />
==== CUPS permission errors ====<br />
<br />
* Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
* Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
==== HPLIP printer sends "/usr/lib/cups/backend/hp failed" error ====<br />
<br />
Make sure dbus is installed and running. If the error persists, try starting avahi-daemon.<br />
<br />
Try adding the printer as a Network Printer using the http:// protocol. Generate the printer URI with {{ic|hp-makeuri}}.<br />
<br />
{{Note|There might need to set permissions issues right. Follow indications here: [[CUPS#Device node permissions]].}}<br />
<br />
==== HPLIP printer claims job is complete but printer does nothing ====<br />
<br />
This happens on HP printers when you select the (old) hpijs driver (e.g. the Deskjet D1600 series). Instead, use the hpcups driver when adding the printer.<br />
<br />
Some HP printers (e.g HP LaserJet) require their firmware to be downloaded from the computer every time the printer is switched on. If there is an issue with udev (or equivalent) and the firmware download rule is never fired, you may experience this issue.<br />
As a workaround, you can manually download the firmware to the printer. Ensure the printer is plugged in and switched on, then enter<br />
hp-firmware -n<br />
<br />
==== hp-setup asks to specify the PPD file for the discovered printer ====<br />
<br />
Install CUPS before running hp-setup.<br />
<br />
==== I have installed Qt, but hp-setup reports "Qt/PyQt 4 initialization failed" ====<br />
<br />
"hp-check -t" won't give you useful information to find the required package. You have to install all the "Dependent Packages" prefixed with "python2" in https://www.archlinux.org/packages/extra/x86_64/hplip/<br />
<br />
==== hp-setup finds the printer automatically but reports "Unable to communicate with device" when printing test page immediately afterwards ====<br />
<br />
This at least happens to hplip 3.13.5-2 for HP Officejet 6500A through local network connection. To solve the problem, specify the IP address of the HP printer for hp-setup to locate the printer.<br />
<br />
==== hp-toolbox sends an error, "Unable to communicate with device" ====<br />
<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/''printer id''<br />
or, "{{ic|Unable to communicate with device"}}", then it may be needed to [[Groups#Group management|add the user to the lp and sys groups]].<br />
<br />
This can also be caused by printers such as the P1102 that provide a virtual cd-rom drive for MS-Windows drivers. The lp dev appears and then disappears. In that case try the '''usb-modeswitch''' and '''usb-modeswitch-data''' packages, that lets one switch off the "Smart Drive" (udev rules included in said packages).<br />
<br />
This can also occur with network attached printers if the [[Avahi|avahi-daemon]] is not running. Another possiblility is the specification of the printer's IP address in hp-setup fails to locate the printer because the IP address of the the printer changed due to DHCP.<br />
<br />
==== CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer ====<br />
<br />
If receiving any of the following error messages in {{ic|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer ''printer_name'' not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure {{pkg|hplip}} has been [[pacman|installed]], in addition to [[#Packages|the packages mentioned above]]. See [https://bbs.archlinux.org/viewtopic.php?id=65615 this forum post] for more information.<br />
<br />
==== Printing fails with unauthorised error ====<br />
<br />
If the user has been added to the lp group, and allowed to print (set in {{ic|cupsd.conf}}), then the problem lies in {{ic|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
==== Unknown supported format: application/postscript ====<br />
<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{ic|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{ic|/etc/cups/mime.types}}.<br />
<br />
==== Finding URIs for Windows print servers ====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
{{bc| WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series}}<br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
If it won't work try '%20' instead of spaces.<br />
<br />
==== Print-Job client-error-document-format-not-supported ====<br />
<br />
Try installing the foomatic packages and use a foomatic driver.<br />
<br />
==== Unable to get list of printer drivers ====<br />
<br />
* Check the {{ic|ServerName}} in {{ic|/etc/cups/client.conf}} is written without http://<br />
ServerName localhost:631<br />
* Try to remove Foomatic drivers or refer to [[#HP_Printer]] for a workaround.<br />
<br />
==== lp: Error - Scheduler Not Responding ====<br />
<br />
If you get this error when printing a document using:<br />
<br />
$ lp document-to-print<br />
<br />
Try setting the {{ic|CUPS_SERVER}} environment variable:<br />
<br />
$ export CUPS_SERVER=localhost<br />
<br />
If this solves your problem, make the solution permanent by adding the export line above to {{ic|~/.bash_profile}}.<br />
<br />
==== CUPS prints only an empty and an error-message page on HP LaserJet ====<br />
<br />
There is a bug that causes CUPS to fail when printing images on HP LaserJet (in my case 3380). The bug has been reported and fixed by [https://bugs.launchpad.net/ubuntu/+source/cups-filters/+bug/998087 Ubuntu].<br />
The first page is empty, the second page contains the following error message:<br />
ERROR:<br />
invalidaccess<br />
OFFENDING COMMAND:<br />
filter<br />
STACK:<br />
/SubFileDecode<br />
endstream<br />
...<br />
<br />
In order to fix the issue, run the following command as root:<br />
# lpadmin -p ''printer'' -o pdftops-renderer-default=pdftops<br />
<br />
==== "Using invalid Host" error message ====<br />
<br />
Try adding {{ic|ServerAlias *}} into {{ic|/etc/cups/cupsd.conf}}.<br />
<br />
==== Printer doesn't print with an "Filter failed" message on CUPS web interface (HP printer) ====<br />
<br />
Change the permissions of the printer USB port. Get the bus and device number from {{ic|lsusb}}, then set the permission using:<br />
<br />
{{hc| lsusb |<br />
Bus <BUSID> Device <DEVID>: ID <PRINTERID>:<VENDOR> Hewlett-Packard DeskJet D1360}}<br />
<br />
Then substitute the provided device information to the <br />
<br />
# chmod 0666 /dev/bus/usb/<BUSID>/<DEVID><br />
<br />
To make the persistent permission change that will be triggered automatically each time the computer is rebooted, add the following line.<br />
<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="<VENDOR>", ATTRS{idProduct}=="<PRINTERID>", GROUP="lp", MODE:="666"<br />
}}<br />
<br />
Each system may vary, so consult [[udev#List_attributes_of_a_device]] wiki page.<br />
<br />
==== Printer does not print with a "Filter failed" message on CUPS web interface (HP printer connected over network) ====<br />
<br />
Start, enable, and restart the {{ic|avahi-daemon}} service.<br />
<br />
==== HPLIP 3.13: Plugin is installed, but HP Device Manager complains it is not ====<br />
<br />
The issue might have to do with the file permission change that had been made to {{ic|/var/lib/hp/hplip.state}}. To correct the issue, a simple {{ic|chmod 644 /var/lib/hp/hplip.state}} and {{ic|chmod 755 /var/lib/hp}} should be sufficient. For further information, please read this [https://bugs.launchpad.net/hplip/+bug/1131596 link].<br />
<br />
==== Printer is not recognized by CUPS ====<br />
<br />
If your printer is not listed in the "Add Printers" page of the CUPS web interface, nor by {{ic|lpinfo -v}}, try the following (suggested in [https://bbs.archlinux.org/viewtopic.php?pid=1037279#p1037279 this thread]):<br />
<br />
* Remove {{ic|usblp}} from blacklist<br />
* Load {{ic|usblp}} module<br />
# modprobe usblp<br />
* Stop CUPS<br />
* Add the following udev rule in a new rule file:<br />
{{hc|/etc/udev/rules.d/10-cups_device_link.rules|2=<br />
KERNEL=="lp[0-9]", SYMLINK+="%k", GROUP="lp"<br />
}}<br />
* Reload udev rules:<br />
# udevadm control --reload-rules<br />
* Unplug the printer, and plug it in again.<br />
* Wait a few seconds, and then start the CUPS service.<br />
<br />
==== Cannot load /etc/samba/smb.conf ====<br />
<br />
If you are printing to a remote printer over SMB and get this error message: "Can't load /etc/samba/smb.conf - run testparm to debug it", then create an empty {{ic|/etc/samba/smb.conf}} file:<br />
<br />
# mkdir /etc/samba<br />
# touch /etc/samba/smb.conf<br />
<br />
and restart the CUPS service.<br />
<br />
==== CUPS' systemd service does not start even though it is enabled ====<br />
<br />
The systemd service file provided by CUPS uses socket activation, meaning the service is only started when an application connects to CUPS' socket. However, the systemd socket file provided by CUPS only works for the local <br />
{{ic|/var/run/cups/cups.sock}} socket. <br />
<br />
In order to have the CUPS service start when initiating a print job over the network, create the following file:<br />
<br />
{{hc|1=/etc/systemd/system/cups.socket|2=<br />
.include /usr/lib/systemd/system/cups.socket<br />
<br />
[Socket]<br />
ListenDatagram=0.0.0.0:631<br />
}}<br />
<br />
Then reload systemd:<br />
<br />
# systemctl --system daemon-reload<br />
<br />
Confirm that everything is working correctly:<br />
<br />
{{bc|<br />
# systemctl is-enabled cups.service &#124;&#124; systemctl enable cups.service<br />
# systemctl status cups.socket<br />
cups.socket - CUPS Printing Service Sockets<br />
Loaded: loaded (/etc/systemd/system/cups.socket; enabled)<br />
Active: inactive (dead)<br />
Listen: /var/run/cups/cups.sock (Stream)<br />
0.0.0.0:631 (Stream)<br />
0.0.0.0:631 (Datagram)<br />
}}<br />
<br />
CUPS should now start automatically when printing locally or over the network.<br />
<br />
==== "Forbidden" error when adding a printer ====<br />
<br />
If adding a printer through the web interface returns an error: ''Forbidden'', the most likely reason is that the privileges are not set correctly. One way to fix it is to add the administering user to the group {{ic|sys}}. For example,<br />
# usermod -a -G sys ''username''<br />
<br />
== See also ==<br />
<br />
* [http://localhost:631/help Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's printing guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation resources]''<br />
* [http://wiki.gotux.net/tutorials/software/hp-printer Install HP printers easy way]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=CUPS&diff=339234CUPS2014-10-08T00:22:47Z<p>Jstjohn: /* CUPS prints only an empty and an error-message page on HP LaserJet */ add missing "#"; use "root" instead of "superuser"</p>
<hr />
<div>[[Category:Printers]]<br />
[[cs:CUPS]]<br />
[[de:CUPS]]<br />
[[es:CUPS]]<br />
[[fr:CUPS]]<br />
[[it:CUPS]]<br />
[[ja:CUPS]]<br />
[[pl:CUPS]]<br />
[[ru:CUPS]]<br />
[[th:CUPS]]<br />
[[tr:CUPS]]<br />
[[zh-CN:CUPS]]<br />
[[zh-TW:CUPS]]<br />
{{Related articles start}}<br />
{{Related|CUPS printer sharing}}<br />
{{Related|CUPS printer-specific problems}}<br />
{{Related|Samba}}<br />
{{Related articles end}}<br />
<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''[[Wikipedia:CUPS|CUPS]] is the standards-based, open source printing system developed by Apple Inc. for OS® X and other UNIX®-like operating systems''".<br />
<br />
Although there are other printing packages such as LPRNG, the Common Unix Printing System is the most popular choice because of its relative ease of use.<br />
<br />
== CUPS Linux printing workflow ==<br />
As of {{Pkg|cups}} version 1.5.3-3, Arch Linux makes use of the new full pdf-based printing workflow. For<br />
further reading check [http://www.linuxfoundation.org/collaborate/workgroups/openprinting/pdfasstandardprintjobformat PDF standard printing job format] and an old [https://wiki.linuxfoundation.org/en/OpenPrinting/Database/CUPS-Filter-Chart CUPS filtering chart] for history and fun.<br />
A good starting point for general Linux printing questions is [http://www.linuxfoundation.org/collaborate/workgroups/openprinting here].<br />
<br />
There are two ways to setup a printer.<br />
* If there's a CUPS server running in your network and sharing a printer you only need to install the client package.<br />
* If the printer is connected directly to your system or you have access to an IPP network printer then setup a local CUPS server.<br />
<br />
== Installing the client package ==<br />
<br />
The package {{Pkg|libcups}} is the only required package. [[pacman|Install]] it from the [[official repositories]].<br />
<br />
Then add your CUPS server's IP address or hostname into {{ic|/etc/cups/client.conf}}, after {{ic|ServerName}}. That is all you need. Every application should quickly find the printer(s) shared by that CUPS server.<br />
<br />
=== Optional advanced network setup ===<br />
<br />
It is also possible to run a entire cupsd+cups-browsed instance on your client with Avahi browsing enabled to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown.<br />
{{Note|This behavior did not change with cups 1.6.x - the difference is that until 1.5.x cupsd was able to do printer browsing alone and now it can only browse its own shared printers.<br />
To get the local cupsd recognise other shared printers offered by a remote cupsd server you need a running local cups-browsed (supported since cups-filters 1.0.26) instance using Avahi to discover unknown printers.}}<br />
<br />
=== Installing CUPS in a 32-bit chroot environment ===<br />
<br />
If you have a 64-bit base installation with a [[Install_bundled_32-bit_system_in_Arch64|32-bit chroot environment]], explicit installation of CUPS is not necessary in the 32-bit environment. To access installed CUPS printers from the chroot environment, one needs to bind the {{ic|/var/run/cups}} directory to the same relative location in the chroot environment. Simply create the directory in the chroot (it probably does not exist), mount (with {{ic|-o bind}} passed to the command}}, and printers should be available from 32-bit chroot applications immediately.<br />
<br />
{{bc|# mkdir /path/to/chroot/var/run/cups<br />
# Example: # mkdir /opt/arch32/var/run/cups<br />
<br />
# mount -o bind /var/run/cups /path/to/chroot/var/run/cups}}<br />
<br />
== Installing the server packages ==<br />
<br />
{{Poor writing|Add Template:App}}<br />
<br />
The following packages and some printer drivers are needed. [[pacman|Install]] them from the [[official repositories]].<br />
<br />
* {{Pkg|cups}} - the actual CUPS daemon<br />
* {{Pkg|ghostscript}} - (optional) PostScript interpreter<br />
* {{Pkg|gsfonts}} - GhostScript standard Type1 fonts<br />
<br />
If you want to enable printer browsing through your network, also install {{Pkg|avahi}} and enable {{ic|avahi-daemon.service}} [[systemd#Using units|using systemd]].<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install {{Pkg|samba}}.<br />
<br />
=== Printer driver ===<br />
<br />
Choosing the right driver depends on the printer. Package names may be misleading because printers of other makes can rely on them. Additional printer drivers are available from the [[AUR]].<br />
<br />
* {{AUR|cndrvcups-lb}} - Canon UFR2 driver with support for LBP, iR and MF series printers.<br />
* {{AUR|cnijfilter-mg4200}} - Printer drivers for Canon MG4200<br />
* {{Pkg|cups-pdf}} - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
* {{AUR|foo2zjs}} - Drivers for ZjStream protocol printers such as the HP Laserjet 1018. More info [http://foo2zjs.rkkda.com here]. It also includes drivers for HBPL protocol such as the Dell C1765 MFP. More info [http://foo2hbpl.rkkda.com here]<br />
* {{Pkg|foomatic-db}}, {{Pkg|foomatic-db-engine}} and {{Pkg|foomatic-db-nonfree}} - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix.<br />
* {{Pkg|gutenprint}} - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostScript, CUPS, Foomatic, and the [[GIMP]]<br />
* {{Pkg|hplip}} - HP drivers for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models, as well as a number of Brother printers.<br />
* {{AUR|hpoj}} - If you are using an HP Officejet, you should also install this package and follow the instructions to avoid problems as in [https://answers.launchpad.net/hplip/+question/133425 this thread].<br />
* {{AUR|samsung-unified-driver}} - Unified Linux Driver for Samsung printers and scanners. Required for new printers such as the ML-2160.<br />
* {{Pkg|splix}} - Samsung drivers for SPL (Samsung Printer Language) printers.<br />
<br />
==== Download printer PPD ====<br />
<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.openprinting.org/printers OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{ic|/usr/share/cups/model/}}}}<br />
<br />
==== Another source for printer drivers ====<br />
<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
== Hardware support and configuration ==<br />
<br />
=== USB printers ===<br />
<br />
{{Tip|Most USB printers should work out of the box, you can skip this section and come back if you can not get your printer to work.}}<br />
<br />
USB printers can get accessed with two methods: The usblp kernel module and libusb. The former is the classic way. It is simple: data is sent to the printer by writing it to a device file as a simple serial data stream. Reading the same device file allows bi-di access, at least for things like reading out ink levels, status, or printer capability information (PJL). It works very well for simple printers, but for multi-function devices (printer/scanner) it is not suitable and manufacturers like HP supply their own backends. Source: [http://lists.linuxfoundation.org/pipermail/printing-architecture/2012/002412.html here].<br />
<br />
==== Blacklisting usblp ====<br />
<br />
{{Warning|As of {{Pkg|cups}} version 1.6.0, you no longer need to [[Kernel modules#Blacklisting|blacklist]] the {{ic|usblp}} kernel module.<br />
<br />
If you find out this is the only way to fix a remaining issue please report this upstream to the CUPS bug tracker and maybe also get in contact with Till Kamppeter (Debian CUPS maintainer). See [http://cups.org/str.php?L4128 upstream bug] for more.}}<br />
<br />
If you have problems getting your USB printer to work, you can try blacklisting the {{ic|usblp}} [[kernel module]]:<br />
<br />
{{hc|/etc/modprobe.d/blacklistusblp.conf|<br />
blacklist usblp<br />
}}<br />
<br />
Custom kernel users may need to manually load the {{ic|usbcore}} [[kernel module]] before proceeding.<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
If you're using {{ic|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{ic|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
=== Parallel port printers ===<br />
<br />
To use a parallel port printer, you will need to load the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]].<br />
<br />
Check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
If you are using a USB to parallel port adapter, CUPS will not be able to detect the printer. As a workaround, add the printer using a different connection type and then change DeviceID in {{ic|/etc/cups/printers.conf}}:<br />
DeviceID = parallel:/dev/usb/lp0<br />
<br />
=== HP Printer ===<br />
HP printers can also be installed via HP's Linux setup tool. Install it by installing {{Pkg|hplip}} from the [[official repositories]].<br />
<br />
To run with qt frontend:<br />
# hp-setup -u<br />
<br />
To run with command line:<br />
# hp-setup -i<br />
<br />
To run systray spool manager:<br />
$ hp-systray<br />
<br />
PPD files are in {{ic|/usr/share/ppd/HP/}}.<br />
<br />
{{Note| If you get errors complaining about missing gobject/dbus dependencies, install {{Pkg|python2-gobject2}} and {{Pkg|python2-dbus}}. For details see this [https://bugs.archlinux.org/task/26666 bug report].}}<br />
<br />
For printers that require the proprietary HP plugin (like the Laserjet Pro P1102w or 1020), install the {{AUR|hplip-plugin}} package from [[AUR]].<br />
<br />
{{Warning| Due to a bug in hplip-setup, you might get error in sys tray or CUPS logs {{ic|Print job failed - required plug-in not found. Please run hp-plugin}} even after you install the aforementioned {{AUR|hplip-plugin}} package from [[AUR]]. To fix, simply modify the printer in CUPS web interface and select the driver manually (preferably the en,en version). After that restart CUPS service.}}<br />
<br />
{{Note|<br />
{{Pkg|hplip}} depends on {{Pkg|foomatic-db-engine}} which prevents the drivers list from appearing when a printer is added to CUPS via the web user interface (following error : "Unable to get list of printer drivers"). The workaround consists of installing {{Pkg|hplip}} first, retrieving the corresponding PPD file from {{ic|/usr/share/ppd/HP/}}, then, removing {{Pkg|hplip}} entirely and the unnecessary dependencies. Finally, install the printer manually using the CUPS web ui, select the PPD file you retrieved then re-install {{Pkg|hplip}}. After a reboot, you should have a fully working printer.}}<br />
<br />
== Configuring ==<br />
<br />
Now that CUPS is installed, there are a variety of options on how to set up printing solutions. As always, the tried and true command line method is at your disposal. CUPS also embeds a full-featured web interface. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. Depending on your needs, you may choose one method or the other.<br />
<br />
If you are planning on connecting to a network printer, rather than one that is directly connected to the computer, you might want to read the [[CUPS printer sharing]] page first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
=== CUPS daemon ===<br />
<br />
With CUPS installed, you can now start {{ic|cups.service}} and optionally, {{ic|cups-browsed.service}} [[systemd#Using units|using systemd]]. Enable them as required.<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{ic|/etc/hostname}}).<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a username and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label (e.g., next to ''USB Printer #1'' for USB printers). Finally, choose the appropriate drivers and the configuration is complete.<br />
<br />
Now test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
{{Tip|See: [[#Alternative CUPS interfaces]] for other front-ends.}}<br />
{{Note|<br />
* When setting up a USB printer, you should see your printer listed on ''Add Printer'' page. If you can only see a "SCSI printer" option, it probably means that CUPS has failed to recognize your printer.<br />
* To enable wireless scanning on certain HP multi-function devices using the {{pkg|hplip}} package, you may need to add the printer as a Network Printer using the HTTP protocol. To determine the proper URI to use, run the {{ic|hp-makeuri}} command.}}<br />
<br />
==== CUPS administration ====<br />
<br />
A username and password will be required when administering the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default username is the one assigned in the ''sys'' group, or root. Other admin groups (e.g. ''printadmin'') may be added to the {{ic|SystemGroup}} line in {{ic|/etc/cups/cups-files.conf}} (you might have to add this line). <br />
<br />
Create the group[s] ({{ic|man groupadd}}) <br />
<br />
# groupadd printadmin <br />
# groupadd lp<br />
<br />
and add the users to the group(s) ({{ic|man gpasswd}}). <br />
<br />
# gpasswd -a username printadmin # for printer administration<br />
# gpasswd -a username lp # for printing priviledges<br />
<br />
# Administrator user group, used to match @SYSTEM in cupsd.conf policy rules...<br />
SystemGroup sys root '''printadmin'''<br />
<br />
Restart {{ic|cups.service}} using systemd. The user must re-login for these changes to take affect.<br />
<br />
Refer to the full cups [http://www.cups.org/documentation.php documentation] for further details.<br />
<br />
==== Remote access to web interface ====<br />
<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{ic|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
Port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
Three levels of access can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{ic|Allow}} statement to that level's section. An {{ic|Allow}} statement can take one or more of the forms listed below:<br />
Allow from all<br />
Allow from host.domain.com<br />
Allow from *.domain.com<br />
Allow from ip-address<br />
Allow from ip-address/netmask<br />
Allow from @LOCAL<br />
<br />
Deny statements can also be used. For example, if wanting to give full access to all hosts on your local network interfaces, file {{ic|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
'''Allow From @LOCAL'''<br />
</Location><br />
<br />
You might also need to add:<br />
<br />
DefaultEncryption Never<br />
<br />
This should avoid the error: 426 - Upgrade Required when using the CUPS web interface from a remote machine.<br />
<br />
=== Command-line configuration ===<br />
<br />
CUPS can be fully controlled from command-line with nice tools, ''i.e.'' the lp* and the cups* command families.<br />
<br />
On Arch Linux, most commands support auto-completion with common shells.<br />
Also note that command-line switches cannot be grouped.<br />
<br />
;List the devices<br />
# lpinfo -v<br />
<br />
;List the drivers<br />
# lpinfo -m<br />
<br />
;Add a new printer<br />
# lpadmin -p ''printer'' -E -v ''device'' -P ''ppd''<br />
<br />
The ''printer'' is up to you. The device can be retrieved from the 'lpinfo -v' command.<br />
Example:<br />
# lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH" -P /usr/share/ppd/HP/hp-deskjet_940c.ppd.gz<br />
<br />
In the following, the ''printer'' references the name you have used here to set up the printer.<br />
<br />
;Set the default printer<br />
$ lpoptions -d ''printer''<br />
<br />
;Check the status<br />
$ lpstat -s<br />
$ lpstat -p ''printer''<br />
<br />
;Deactivate a printer<br />
# cupsdisable ''printer''<br />
<br />
;Activate a printer<br />
# cupsenable ''printer''<br />
<br />
;Remove a printer<br />
First set it to reject all incoming entries:<br />
# cupsreject ''printer''<br />
Then disable it.<br />
# cupsdisable ''printer''<br />
Finally remove it.<br />
# lpadmin -x ''printer''<br />
<br />
;Print a file<br />
$ lpr ''file''<br />
$ lpr -# 17 ''file'' # print the file 17 times<br />
$ echo "Hello, world!" | lpr -p # print the result of a command. The -p switch adds a header.<br />
<br />
;Check the printing queue<br />
$ lpq<br />
$ lpq -a # on all printers<br />
<br />
;Clear the printing queue<br />
# lprm # remove last entry only<br />
# lprm - # remove all entries<br />
<br />
=== Alternative CUPS interfaces ===<br />
<br />
==== GNOME ====<br />
<br />
You can configure and manage printers by [[pacman|installing]] {{Pkg|system-config-printer}}. This program does pull in some gnome dependencies.<br />
<br />
If your user does not have sufficient priviliges to administer the cups scheduler, system-config-printer will request the root password when it starts. You can avoid this by performing the following instructions.<br />
<br />
1. Create a group for administering the cups scheduler:<br />
<br />
# groupadd lpadmin<br />
<br />
2. Add yourself to the newly created group:<br />
<br />
# usermod -aG lpadmin ''username''<br />
<br />
3. Tell cups to respect the newly created group:<br />
<br />
{{hc|/etc/cups/cups-files.conf|<br />
...<br />
SystemGroup sys root '''lpadmin'''<br />
...}}<br />
<br />
4. Restart cups:<br />
<br />
# systemctl restart cups<br />
<br />
5. Log out and log in again or restart your computer.<br />
<br />
==== KDE ====<br />
<br />
[[KDE]] users can modify their printers from the Control Center. The {{Pkg|kdeutils-print-manager}} package may need be installed if the Printers interface isn't found in the Hardware group. KDE users should refer to the desktop environments' documentation for more information on how to use the interface.<br />
<br />
==== Other ====<br />
<br />
There is also {{AUR|gtklp}} in the [[AUR]].<br />
<br />
== PDF virtual printer ==<br />
{{Note| With GNOME, it is now possible to directly print into a PDF or Postscript file, therefore CUPS-PDF is no longer required on such system. }}<br />
<br />
{{Pkg|cups-pdf}} is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. This package is not necessary, but it can be quite useful.<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Add Printer<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Find generated PDF documents in a sub-directory located at {{ic|/var/spool/cups-pdf}}. Normally, the subdirectory is named after the user who performed the job. A little tweak helps you to find your printed PDF documents more easily. Edit {{ic|/etc/cups/cups-pdf.conf}} by changing the line<br />
#Out /var/spool/cups-pdf/${USER}<br />
<br />
to<br />
<br />
Out ${HOME}<br />
<br />
=== Print to PostScript ===<br />
<br />
The CUPS-PDF (Virtual PDF Printer) actually creates a PostScript file and then creates the PDF using the ps2pdf utility. To print to PostScript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
== Troubleshooting ==<br />
<br />
The best way to get printing working is to set 'LogLevel' in {{ic|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{ic|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{ic|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{ic|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{ic|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
=== Problems resulting from upgrades ===<br />
<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
==== CUPS stops working ====<br />
<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" may result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy {{ic|/etc/cups/cupsd.conf.default}} to {{ic|/etc/cups/cupsd.conf}} (backup the old configuration if needed) and restart CUPS to employ the new settings.<br />
<br />
==== All jobs are "stopped" ====<br />
<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
==== All jobs are "The printer is not responding" ====<br />
<br />
On networked printers, you should check that the name that CUPS uses as its connection URI resolves to the printer's IP via DNS, e.g.<br />
If your printer's connection looks like this:<br />
lpd://BRN_020554/BINARY_P1<br />
<br />
then the hostname 'BRN_020554' needs to resolve to the printer's IP from the server running CUPS<br />
<br />
==== The PPD version is not compatible with gutenprint ====<br />
<br />
Run:<br />
# /usr/bin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
=== Other ===<br />
<br />
==== Printer "Paused" or "Stopped" with Status "Rendering completed" ====<br />
<br />
When low on ink, some printers will get stuck in "Rendering completed" status and, if it is a network printer, the printer may even become unreachable from CUPS' perspective despite being properly connected to the network. Replacing the low/depleted ink cartridge(s) in this setting will return the printer to "Ready" status and, if it is a network printer, will make the printer available to CUPS again.<br />
<br />
{{Warning|If you use third-party ink cartridges, the ink levels reported by the printer may be inaccurate. If you use third-party ink and your printer used to work fine but is now getting stuck on "Rendering completed" status, replace the ink cartridges regardless of the reported ink levels before trying other fixes.}}<br />
<br />
If low ink is not the issue, check the "Group ID" of files in /etc/cups, /var/log/cups, and, if you have "root" permission, /var/spool/cups. The files should have GID "lp". If some files have GID "nobody", then check the named groups in the "Group" and "SystemGroup" directives in the file /etc/cups/cups-files.conf. Typically there will be "Group lp" and "SystemGroup lpadmin sys root". Make sure that the group in "Group" is NOT also in "SystemGroup". In particular, make sure that the name "lp" is NOT listed in the "SystemGroup" directive, when it is used in the "Group" directive. This is counter to recommendations made in the CUPS and KDE wiki pages in the past. If you had added "lp" to the "SystemGroup" directive, as had been suggested, remove "lp" from the "SystemGroup", or run "sudo groupadd -g107 lpadmin" and change "lp" to "lpadmin" in the "SystemGroup" directive.<br />
<br />
Explanation of GID issue: For security reasons, cupsd does not allow external cups helper programs, which use the "Group" GID, to run in the Administration groups, which are those GIDs listed in "SystemGroup". If the named group in the Group directive is also in the SystemGroup directive, then cupsd changes the Group GID to "nobody" instead, without warning. However, the printer devices in "/dev/", for instance "/dev/parport0", are created with user "root" and group "lp". When cupsd then tries to print, it "pauses" or "stops" because it does not have permission to write the printer device file, and does not provide any useful error message. Making the printer device files "world writable" can bypass the problem, but is not the proper solution.<br />
<br />
==== CUPS permission errors ====<br />
<br />
* Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
* Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
==== HPLIP printer sends "/usr/lib/cups/backend/hp failed" error ====<br />
<br />
Make sure dbus is installed and running. If the error persists, try starting avahi-daemon.<br />
<br />
Try adding the printer as a Network Printer using the http:// protocol. Generate the printer URI with {{ic|hp-makeuri}}.<br />
<br />
{{Note|There might need to set permissions issues right. Follow indications here: [[CUPS#Device node permissions]].}}<br />
<br />
==== HPLIP printer claims job is complete but printer does nothing ====<br />
<br />
This happens on HP printers when you select the (old) hpijs driver (e.g. the Deskjet D1600 series). Instead, use the hpcups driver when adding the printer.<br />
<br />
Some HP printers (e.g HP LaserJet) require their firmware to be downloaded from the computer every time the printer is switched on. If there is an issue with udev (or equivalent) and the firmware download rule is never fired, you may experience this issue.<br />
As a workaround, you can manually download the firmware to the printer. Ensure the printer is plugged in and switched on, then enter<br />
hp-firmware -n<br />
<br />
==== hp-setup asks to specify the PPD file for the discovered printer ====<br />
<br />
Install CUPS before running hp-setup.<br />
<br />
==== I have installed Qt, but hp-setup reports "Qt/PyQt 4 initialization failed" ====<br />
<br />
"hp-check -t" won't give you useful information to find the required package. You have to install all the "Dependent Packages" prefixed with "python2" in https://www.archlinux.org/packages/extra/x86_64/hplip/<br />
<br />
==== hp-setup finds the printer automatically but reports "Unable to communicate with device" when printing test page immediately afterwards ====<br />
<br />
This at least happens to hplip 3.13.5-2 for HP Officejet 6500A through local network connection. To solve the problem, specify the IP address of the HP printer for hp-setup to locate the printer.<br />
<br />
==== hp-toolbox sends an error, "Unable to communicate with device" ====<br />
<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/''printer id''<br />
or, "{{ic|Unable to communicate with device"}}", then it may be needed to [[Groups#Group management|add the user to the lp and sys groups]].<br />
<br />
This can also be caused by printers such as the P1102 that provide a virtual cd-rom drive for MS-Windows drivers. The lp dev appears and then disappears. In that case try the '''usb-modeswitch''' and '''usb-modeswitch-data''' packages, that lets one switch off the "Smart Drive" (udev rules included in said packages).<br />
<br />
This can also occur with network attached printers if the [[Avahi|avahi-daemon]] is not running. Another possiblility is the specification of the printer's IP address in hp-setup fails to locate the printer because the IP address of the the printer changed due to DHCP.<br />
<br />
==== CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer ====<br />
<br />
If receiving any of the following error messages in {{ic|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer ''printer_name'' not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure {{pkg|hplip}} has been [[pacman|installed]], in addition to [[#Packages|the packages mentioned above]]. See [https://bbs.archlinux.org/viewtopic.php?id=65615 this forum post] for more information.<br />
<br />
==== Printing fails with unauthorised error ====<br />
<br />
If the user has been added to the lp group, and allowed to print (set in {{ic|cupsd.conf}}), then the problem lies in {{ic|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
==== Unknown supported format: application/postscript ====<br />
<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{ic|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{ic|/etc/cups/mime.types}}.<br />
<br />
==== Finding URIs for Windows print servers ====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
{{bc| WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series}}<br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
If it won't work try '%20' instead of spaces.<br />
<br />
==== Print-Job client-error-document-format-not-supported ====<br />
<br />
Try installing the foomatic packages and use a foomatic driver.<br />
<br />
==== Unable to get list of printer drivers ====<br />
<br />
* Check your ServerName in /etc/cups/client.conf is written without http://<br />
ServerName localhost:631<br />
* Try to remove Foomatic drivers or refer to [[#HP_Printer]] for a workaround.<br />
<br />
==== lp: Error - Scheduler Not Responding ====<br />
<br />
If you get this error when printing a document using:<br />
<br />
$ lp document-to-print<br />
<br />
Try setting the {{ic|CUPS_SERVER}} environment variable:<br />
<br />
$ export CUPS_SERVER=localhost<br />
<br />
If this solves your problem, make the solution permanent by adding the export line above to {{ic|~/.bash_profile}}.<br />
<br />
==== CUPS prints only an empty and an error-message page on HP LaserJet ====<br />
<br />
There is a bug that causes CUPS to fail when printing images on HP LaserJet (in my case 3380). The bug has been reported and fixed by [https://bugs.launchpad.net/ubuntu/+source/cups-filters/+bug/998087 Ubuntu].<br />
The first page is empty, the second page contains the following error message:<br />
ERROR:<br />
invalidaccess<br />
OFFENDING COMMAND:<br />
filter<br />
STACK:<br />
/SubFileDecode<br />
endstream<br />
...<br />
<br />
In order to fix the issue, run the following command as root:<br />
# lpadmin -p ''printer'' -o pdftops-renderer-default=pdftops<br />
<br />
==== "Using invalid Host" error message ====<br />
<br />
Try adding {{ic|ServerAlias *}} into {{ic|/etc/cups/cupsd.conf}}.<br />
<br />
==== Printer doesn't print with an "Filter failed" message on CUPS web interface (HP printer) ====<br />
<br />
Change the permissions of the printer USB port. Get the bus and device number from {{ic|lsusb}}, then set the permission using:<br />
<br />
{{hc| lsusb |<br />
Bus <BUSID> Device <DEVID>: ID <PRINTERID>:<VENDOR> Hewlett-Packard DeskJet D1360}}<br />
<br />
Then substitute the provided device information to the <br />
<br />
# chmod 0666 /dev/bus/usb/<BUSID>/<DEVID><br />
<br />
To make the persistent permission change that will be triggered automatically each time the computer is rebooted, add the following line.<br />
<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="<VENDOR>", ATTRS{idProduct}=="<PRINTERID>", GROUP="lp", MODE:="666"<br />
}}<br />
<br />
Each system may vary, so consult [[udev#List_attributes_of_a_device]] wiki page.<br />
<br />
==== Printer does not print with a "Filter failed" message on CUPS web interface (HP printer connected over network) ====<br />
<br />
Start, enable, and restart the {{ic|avahi-daemon}} service.<br />
<br />
==== HPLIP 3.13: Plugin is installed, but HP Device Manager complains it is not ====<br />
<br />
The issue might have to do with the file permission change that had been made to {{ic|/var/lib/hp/hplip.state}}. To correct the issue, a simple {{ic|chmod 644 /var/lib/hp/hplip.state}} and {{ic|chmod 755 /var/lib/hp}} should be sufficient. For further information, please read this [https://bugs.launchpad.net/hplip/+bug/1131596 link].<br />
<br />
==== Printer is not recognized by CUPS ====<br />
<br />
If your printer is not listed in the "Add Printers" page of the CUPS web interface, nor by {{ic|lpinfo -v}}, try the following (suggested in [https://bbs.archlinux.org/viewtopic.php?pid=1037279#p1037279 this thread]):<br />
<br />
* Remove {{ic|usblp}} from blacklist<br />
* Load {{ic|usblp}} module<br />
# modprobe usblp<br />
* Stop CUPS<br />
* Add the following udev rule in a new rule file:<br />
{{hc|/etc/udev/rules.d/10-cups_device_link.rules|2=<br />
KERNEL=="lp[0-9]", SYMLINK+="%k", GROUP="lp"<br />
}}<br />
* Reload udev rules:<br />
# udevadm control --reload-rules<br />
* Unplug the printer, and plug it in again.<br />
* Wait a few seconds, and then start the CUPS service.<br />
<br />
==== Cannot load /etc/samba/smb.conf ====<br />
<br />
If you are printing to a remote printer over SMB and get this error message: "Can't load /etc/samba/smb.conf - run testparm to debug it", then create an empty {{ic|/etc/samba/smb.conf}} file:<br />
<br />
# mkdir /etc/samba<br />
# touch /etc/samba/smb.conf<br />
<br />
and restart the CUPS service.<br />
<br />
==== CUPS' systemd service does not start even though it is enabled ====<br />
<br />
The systemd service file provided by CUPS uses socket activation, meaning the service is only started when an application connects to CUPS' socket. However, the systemd socket file provided by CUPS only works for the local <br />
{{ic|/var/run/cups/cups.sock}} socket. <br />
<br />
In order to have the CUPS service start when initiating a print job over the network, create the following file:<br />
<br />
{{hc|1=/etc/systemd/system/cups.socket|2=<br />
.include /usr/lib/systemd/system/cups.socket<br />
<br />
[Socket]<br />
ListenDatagram=0.0.0.0:631<br />
}}<br />
<br />
Then reload systemd:<br />
<br />
# systemctl --system daemon-reload<br />
<br />
Confirm that everything is working correctly:<br />
<br />
{{bc|<br />
# systemctl is-enabled cups.service &#124;&#124; systemctl enable cups.service<br />
# systemctl status cups.socket<br />
cups.socket - CUPS Printing Service Sockets<br />
Loaded: loaded (/etc/systemd/system/cups.socket; enabled)<br />
Active: inactive (dead)<br />
Listen: /var/run/cups/cups.sock (Stream)<br />
0.0.0.0:631 (Stream)<br />
0.0.0.0:631 (Datagram)<br />
}}<br />
<br />
CUPS should now start automatically when printing locally or over the network.<br />
<br />
==== "Forbidden" error when adding a printer ====<br />
<br />
If adding a printer through the web interface returns an error: ''Forbidden'', the most likely reason is that the privileges are not set correctly. One way to fix it is to add the administering user to the group {{ic|sys}}. For example,<br />
# usermod -a -G sys ''username''<br />
<br />
== See also ==<br />
<br />
* [http://localhost:631/help Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's printing guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation resources]''<br />
* [http://wiki.gotux.net/tutorials/software/hp-printer Install HP printers easy way]</div>Jstjohnhttps://wiki.archlinux.org/index.php?title=CUPS&diff=339233CUPS2014-10-08T00:21:31Z<p>Jstjohn: /* lp: Error - Scheduler Not Responding */ add missing templates</p>
<hr />
<div>[[Category:Printers]]<br />
[[cs:CUPS]]<br />
[[de:CUPS]]<br />
[[es:CUPS]]<br />
[[fr:CUPS]]<br />
[[it:CUPS]]<br />
[[ja:CUPS]]<br />
[[pl:CUPS]]<br />
[[ru:CUPS]]<br />
[[th:CUPS]]<br />
[[tr:CUPS]]<br />
[[zh-CN:CUPS]]<br />
[[zh-TW:CUPS]]<br />
{{Related articles start}}<br />
{{Related|CUPS printer sharing}}<br />
{{Related|CUPS printer-specific problems}}<br />
{{Related|Samba}}<br />
{{Related articles end}}<br />
<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''[[Wikipedia:CUPS|CUPS]] is the standards-based, open source printing system developed by Apple Inc. for OS® X and other UNIX®-like operating systems''".<br />
<br />
Although there are other printing packages such as LPRNG, the Common Unix Printing System is the most popular choice because of its relative ease of use.<br />
<br />
== CUPS Linux printing workflow ==<br />
As of {{Pkg|cups}} version 1.5.3-3, Arch Linux makes use of the new full pdf-based printing workflow. For<br />
further reading check [http://www.linuxfoundation.org/collaborate/workgroups/openprinting/pdfasstandardprintjobformat PDF standard printing job format] and an old [https://wiki.linuxfoundation.org/en/OpenPrinting/Database/CUPS-Filter-Chart CUPS filtering chart] for history and fun.<br />
A good starting point for general Linux printing questions is [http://www.linuxfoundation.org/collaborate/workgroups/openprinting here].<br />
<br />
There are two ways to setup a printer.<br />
* If there's a CUPS server running in your network and sharing a printer you only need to install the client package.<br />
* If the printer is connected directly to your system or you have access to an IPP network printer then setup a local CUPS server.<br />
<br />
== Installing the client package ==<br />
<br />
The package {{Pkg|libcups}} is the only required package. [[pacman|Install]] it from the [[official repositories]].<br />
<br />
Then add your CUPS server's IP address or hostname into {{ic|/etc/cups/client.conf}}, after {{ic|ServerName}}. That is all you need. Every application should quickly find the printer(s) shared by that CUPS server.<br />
<br />
=== Optional advanced network setup ===<br />
<br />
It is also possible to run a entire cupsd+cups-browsed instance on your client with Avahi browsing enabled to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown.<br />
{{Note|This behavior did not change with cups 1.6.x - the difference is that until 1.5.x cupsd was able to do printer browsing alone and now it can only browse its own shared printers.<br />
To get the local cupsd recognise other shared printers offered by a remote cupsd server you need a running local cups-browsed (supported since cups-filters 1.0.26) instance using Avahi to discover unknown printers.}}<br />
<br />
=== Installing CUPS in a 32-bit chroot environment ===<br />
<br />
If you have a 64-bit base installation with a [[Install_bundled_32-bit_system_in_Arch64|32-bit chroot environment]], explicit installation of CUPS is not necessary in the 32-bit environment. To access installed CUPS printers from the chroot environment, one needs to bind the {{ic|/var/run/cups}} directory to the same relative location in the chroot environment. Simply create the directory in the chroot (it probably does not exist), mount (with {{ic|-o bind}} passed to the command}}, and printers should be available from 32-bit chroot applications immediately.<br />
<br />
{{bc|# mkdir /path/to/chroot/var/run/cups<br />
# Example: # mkdir /opt/arch32/var/run/cups<br />
<br />
# mount -o bind /var/run/cups /path/to/chroot/var/run/cups}}<br />
<br />
== Installing the server packages ==<br />
<br />
{{Poor writing|Add Template:App}}<br />
<br />
The following packages and some printer drivers are needed. [[pacman|Install]] them from the [[official repositories]].<br />
<br />
* {{Pkg|cups}} - the actual CUPS daemon<br />
* {{Pkg|ghostscript}} - (optional) PostScript interpreter<br />
* {{Pkg|gsfonts}} - GhostScript standard Type1 fonts<br />
<br />
If you want to enable printer browsing through your network, also install {{Pkg|avahi}} and enable {{ic|avahi-daemon.service}} [[systemd#Using units|using systemd]].<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install {{Pkg|samba}}.<br />
<br />
=== Printer driver ===<br />
<br />
Choosing the right driver depends on the printer. Package names may be misleading because printers of other makes can rely on them. Additional printer drivers are available from the [[AUR]].<br />
<br />
* {{AUR|cndrvcups-lb}} - Canon UFR2 driver with support for LBP, iR and MF series printers.<br />
* {{AUR|cnijfilter-mg4200}} - Printer drivers for Canon MG4200<br />
* {{Pkg|cups-pdf}} - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
* {{AUR|foo2zjs}} - Drivers for ZjStream protocol printers such as the HP Laserjet 1018. More info [http://foo2zjs.rkkda.com here]. It also includes drivers for HBPL protocol such as the Dell C1765 MFP. More info [http://foo2hbpl.rkkda.com here]<br />
* {{Pkg|foomatic-db}}, {{Pkg|foomatic-db-engine}} and {{Pkg|foomatic-db-nonfree}} - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix.<br />
* {{Pkg|gutenprint}} - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostScript, CUPS, Foomatic, and the [[GIMP]]<br />
* {{Pkg|hplip}} - HP drivers for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models, as well as a number of Brother printers.<br />
* {{AUR|hpoj}} - If you are using an HP Officejet, you should also install this package and follow the instructions to avoid problems as in [https://answers.launchpad.net/hplip/+question/133425 this thread].<br />
* {{AUR|samsung-unified-driver}} - Unified Linux Driver for Samsung printers and scanners. Required for new printers such as the ML-2160.<br />
* {{Pkg|splix}} - Samsung drivers for SPL (Samsung Printer Language) printers.<br />
<br />
==== Download printer PPD ====<br />
<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.openprinting.org/printers OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{ic|/usr/share/cups/model/}}}}<br />
<br />
==== Another source for printer drivers ====<br />
<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
== Hardware support and configuration ==<br />
<br />
=== USB printers ===<br />
<br />
{{Tip|Most USB printers should work out of the box, you can skip this section and come back if you can not get your printer to work.}}<br />
<br />
USB printers can get accessed with two methods: The usblp kernel module and libusb. The former is the classic way. It is simple: data is sent to the printer by writing it to a device file as a simple serial data stream. Reading the same device file allows bi-di access, at least for things like reading out ink levels, status, or printer capability information (PJL). It works very well for simple printers, but for multi-function devices (printer/scanner) it is not suitable and manufacturers like HP supply their own backends. Source: [http://lists.linuxfoundation.org/pipermail/printing-architecture/2012/002412.html here].<br />
<br />
==== Blacklisting usblp ====<br />
<br />
{{Warning|As of {{Pkg|cups}} version 1.6.0, you no longer need to [[Kernel modules#Blacklisting|blacklist]] the {{ic|usblp}} kernel module.<br />
<br />
If you find out this is the only way to fix a remaining issue please report this upstream to the CUPS bug tracker and maybe also get in contact with Till Kamppeter (Debian CUPS maintainer). See [http://cups.org/str.php?L4128 upstream bug] for more.}}<br />
<br />
If you have problems getting your USB printer to work, you can try blacklisting the {{ic|usblp}} [[kernel module]]:<br />
<br />
{{hc|/etc/modprobe.d/blacklistusblp.conf|<br />
blacklist usblp<br />
}}<br />
<br />
Custom kernel users may need to manually load the {{ic|usbcore}} [[kernel module]] before proceeding.<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
If you're using {{ic|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{ic|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
=== Parallel port printers ===<br />
<br />
To use a parallel port printer, you will need to load the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]].<br />
<br />
Check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
If you are using a USB to parallel port adapter, CUPS will not be able to detect the printer. As a workaround, add the printer using a different connection type and then change DeviceID in {{ic|/etc/cups/printers.conf}}:<br />
DeviceID = parallel:/dev/usb/lp0<br />
<br />
=== HP Printer ===<br />
HP printers can also be installed via HP's Linux setup tool. Install it by installing {{Pkg|hplip}} from the [[official repositories]].<br />
<br />
To run with qt frontend:<br />
# hp-setup -u<br />
<br />
To run with command line:<br />
# hp-setup -i<br />
<br />
To run systray spool manager:<br />
$ hp-systray<br />
<br />
PPD files are in {{ic|/usr/share/ppd/HP/}}.<br />
<br />
{{Note| If you get errors complaining about missing gobject/dbus dependencies, install {{Pkg|python2-gobject2}} and {{Pkg|python2-dbus}}. For details see this [https://bugs.archlinux.org/task/26666 bug report].}}<br />
<br />
For printers that require the proprietary HP plugin (like the Laserjet Pro P1102w or 1020), install the {{AUR|hplip-plugin}} package from [[AUR]].<br />
<br />
{{Warning| Due to a bug in hplip-setup, you might get error in sys tray or CUPS logs {{ic|Print job failed - required plug-in not found. Please run hp-plugin}} even after you install the aforementioned {{AUR|hplip-plugin}} package from [[AUR]]. To fix, simply modify the printer in CUPS web interface and select the driver manually (preferably the en,en version). After that restart CUPS service.}}<br />
<br />
{{Note|<br />
{{Pkg|hplip}} depends on {{Pkg|foomatic-db-engine}} which prevents the drivers list from appearing when a printer is added to CUPS via the web user interface (following error : "Unable to get list of printer drivers"). The workaround consists of installing {{Pkg|hplip}} first, retrieving the corresponding PPD file from {{ic|/usr/share/ppd/HP/}}, then, removing {{Pkg|hplip}} entirely and the unnecessary dependencies. Finally, install the printer manually using the CUPS web ui, select the PPD file you retrieved then re-install {{Pkg|hplip}}. After a reboot, you should have a fully working printer.}}<br />
<br />
== Configuring ==<br />
<br />
Now that CUPS is installed, there are a variety of options on how to set up printing solutions. As always, the tried and true command line method is at your disposal. CUPS also embeds a full-featured web interface. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. Depending on your needs, you may choose one method or the other.<br />
<br />
If you are planning on connecting to a network printer, rather than one that is directly connected to the computer, you might want to read the [[CUPS printer sharing]] page first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
=== CUPS daemon ===<br />
<br />
With CUPS installed, you can now start {{ic|cups.service}} and optionally, {{ic|cups-browsed.service}} [[systemd#Using units|using systemd]]. Enable them as required.<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{ic|/etc/hostname}}).<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a username and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label (e.g., next to ''USB Printer #1'' for USB printers). Finally, choose the appropriate drivers and the configuration is complete.<br />
<br />
Now test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
{{Tip|See: [[#Alternative CUPS interfaces]] for other front-ends.}}<br />
{{Note|<br />
* When setting up a USB printer, you should see your printer listed on ''Add Printer'' page. If you can only see a "SCSI printer" option, it probably means that CUPS has failed to recognize your printer.<br />
* To enable wireless scanning on certain HP multi-function devices using the {{pkg|hplip}} package, you may need to add the printer as a Network Printer using the HTTP protocol. To determine the proper URI to use, run the {{ic|hp-makeuri}} command.}}<br />
<br />
==== CUPS administration ====<br />
<br />
A username and password will be required when administering the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default username is the one assigned in the ''sys'' group, or root. Other admin groups (e.g. ''printadmin'') may be added to the {{ic|SystemGroup}} line in {{ic|/etc/cups/cups-files.conf}} (you might have to add this line). <br />
<br />
Create the group[s] ({{ic|man groupadd}}) <br />
<br />
# groupadd printadmin <br />
# groupadd lp<br />
<br />
and add the users to the group(s) ({{ic|man gpasswd}}). <br />
<br />
# gpasswd -a username printadmin # for printer administration<br />
# gpasswd -a username lp # for printing priviledges<br />
<br />
# Administrator user group, used to match @SYSTEM in cupsd.conf policy rules...<br />
SystemGroup sys root '''printadmin'''<br />
<br />
Restart {{ic|cups.service}} using systemd. The user must re-login for these changes to take affect.<br />
<br />
Refer to the full cups [http://www.cups.org/documentation.php documentation] for further details.<br />
<br />
==== Remote access to web interface ====<br />
<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{ic|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
Port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
Three levels of access can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{ic|Allow}} statement to that level's section. An {{ic|Allow}} statement can take one or more of the forms listed below:<br />
Allow from all<br />
Allow from host.domain.com<br />
Allow from *.domain.com<br />
Allow from ip-address<br />
Allow from ip-address/netmask<br />
Allow from @LOCAL<br />
<br />
Deny statements can also be used. For example, if wanting to give full access to all hosts on your local network interfaces, file {{ic|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
Order allow,deny<br />
'''Allow from @LOCAL'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
'''Allow From @LOCAL'''<br />
</Location><br />
<br />
You might also need to add:<br />
<br />
DefaultEncryption Never<br />
<br />
This should avoid the error: 426 - Upgrade Required when using the CUPS web interface from a remote machine.<br />
<br />
=== Command-line configuration ===<br />
<br />
CUPS can be fully controlled from command-line with nice tools, ''i.e.'' the lp* and the cups* command families.<br />
<br />
On Arch Linux, most commands support auto-completion with common shells.<br />
Also note that command-line switches cannot be grouped.<br />
<br />
;List the devices<br />
# lpinfo -v<br />
<br />
;List the drivers<br />
# lpinfo -m<br />
<br />
;Add a new printer<br />
# lpadmin -p ''printer'' -E -v ''device'' -P ''ppd''<br />
<br />
The ''printer'' is up to you. The device can be retrieved from the 'lpinfo -v' command.<br />
Example:<br />
# lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH" -P /usr/share/ppd/HP/hp-deskjet_940c.ppd.gz<br />
<br />
In the following, the ''printer'' references the name you have used here to set up the printer.<br />
<br />
;Set the default printer<br />
$ lpoptions -d ''printer''<br />
<br />
;Check the status<br />
$ lpstat -s<br />
$ lpstat -p ''printer''<br />
<br />
;Deactivate a printer<br />
# cupsdisable ''printer''<br />
<br />
;Activate a printer<br />
# cupsenable ''printer''<br />
<br />
;Remove a printer<br />
First set it to reject all incoming entries:<br />
# cupsreject ''printer''<br />
Then disable it.<br />
# cupsdisable ''printer''<br />
Finally remove it.<br />
# lpadmin -x ''printer''<br />
<br />
;Print a file<br />
$ lpr ''file''<br />
$ lpr -# 17 ''file'' # print the file 17 times<br />
$ echo "Hello, world!" | lpr -p # print the result of a command. The -p switch adds a header.<br />
<br />
;Check the printing queue<br />
$ lpq<br />
$ lpq -a # on all printers<br />
<br />
;Clear the printing queue<br />
# lprm # remove last entry only<br />
# lprm - # remove all entries<br />
<br />
=== Alternative CUPS interfaces ===<br />
<br />
==== GNOME ====<br />
<br />
You can configure and manage printers by [[pacman|installing]] {{Pkg|system-config-printer}}. This program does pull in some gnome dependencies.<br />
<br />
If your user does not have sufficient priviliges to administer the cups scheduler, system-config-printer will request the root password when it starts. You can avoid this by performing the following instructions.<br />
<br />
1. Create a group for administering the cups scheduler:<br />
<br />
# groupadd lpadmin<br />
<br />
2. Add yourself to the newly created group:<br />
<br />
# usermod -aG lpadmin ''username''<br />
<br />
3. Tell cups to respect the newly created group:<br />
<br />
{{hc|/etc/cups/cups-files.conf|<br />
...<br />
SystemGroup sys root '''lpadmin'''<br />
...}}<br />
<br />
4. Restart cups:<br />
<br />
# systemctl restart cups<br />
<br />
5. Log out and log in again or restart your computer.<br />
<br />
==== KDE ====<br />
<br />
[[KDE]] users can modify their printers from the Control Center. The {{Pkg|kdeutils-print-manager}} package may need be installed if the Printers interface isn't found in the Hardware group. KDE users should refer to the desktop environments' documentation for more information on how to use the interface.<br />
<br />
==== Other ====<br />
<br />
There is also {{AUR|gtklp}} in the [[AUR]].<br />
<br />
== PDF virtual printer ==<br />
{{Note| With GNOME, it is now possible to directly print into a PDF or Postscript file, therefore CUPS-PDF is no longer required on such system. }}<br />
<br />
{{Pkg|cups-pdf}} is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. This package is not necessary, but it can be quite useful.<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Add Printer<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Find generated PDF documents in a sub-directory located at {{ic|/var/spool/cups-pdf}}. Normally, the subdirectory is named after the user who performed the job. A little tweak helps you to find your printed PDF documents more easily. Edit {{ic|/etc/cups/cups-pdf.conf}} by changing the line<br />
#Out /var/spool/cups-pdf/${USER}<br />
<br />
to<br />
<br />
Out ${HOME}<br />
<br />
=== Print to PostScript ===<br />
<br />
The CUPS-PDF (Virtual PDF Printer) actually creates a PostScript file and then creates the PDF using the ps2pdf utility. To print to PostScript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
== Troubleshooting ==<br />
<br />
The best way to get printing working is to set 'LogLevel' in {{ic|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{ic|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{ic|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{ic|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{ic|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
=== Problems resulting from upgrades ===<br />
<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
==== CUPS stops working ====<br />
<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" may result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy {{ic|/etc/cups/cupsd.conf.default}} to {{ic|/etc/cups/cupsd.conf}} (backup the old configuration if needed) and restart CUPS to employ the new settings.<br />
<br />
==== All jobs are "stopped" ====<br />
<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
==== All jobs are "The printer is not responding" ====<br />
<br />
On networked printers, you should check that the name that CUPS uses as its connection URI resolves to the printer's IP via DNS, e.g.<br />
If your printer's connection looks like this:<br />
lpd://BRN_020554/BINARY_P1<br />
<br />
then the hostname 'BRN_020554' needs to resolve to the printer's IP from the server running CUPS<br />
<br />
==== The PPD version is not compatible with gutenprint ====<br />
<br />
Run:<br />
# /usr/bin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
=== Other ===<br />
<br />
==== Printer "Paused" or "Stopped" with Status "Rendering completed" ====<br />
<br />
When low on ink, some printers will get stuck in "Rendering completed" status and, if it is a network printer, the printer may even become unreachable from CUPS' perspective despite being properly connected to the network. Replacing the low/depleted ink cartridge(s) in this setting will return the printer to "Ready" status and, if it is a network printer, will make the printer available to CUPS again.<br />
<br />
{{Warning|If you use third-party ink cartridges, the ink levels reported by the printer may be inaccurate. If you use third-party ink and your printer used to work fine but is now getting stuck on "Rendering completed" status, replace the ink cartridges regardless of the reported ink levels before trying other fixes.}}<br />
<br />
If low ink is not the issue, check the "Group ID" of files in /etc/cups, /var/log/cups, and, if you have "root" permission, /var/spool/cups. The files should have GID "lp". If some files have GID "nobody", then check the named groups in the "Group" and "SystemGroup" directives in the file /etc/cups/cups-files.conf. Typically there will be "Group lp" and "SystemGroup lpadmin sys root". Make sure that the group in "Group" is NOT also in "SystemGroup". In particular, make sure that the name "lp" is NOT listed in the "SystemGroup" directive, when it is used in the "Group" directive. This is counter to recommendations made in the CUPS and KDE wiki pages in the past. If you had added "lp" to the "SystemGroup" directive, as had been suggested, remove "lp" from the "SystemGroup", or run "sudo groupadd -g107 lpadmin" and change "lp" to "lpadmin" in the "SystemGroup" directive.<br />
<br />
Explanation of GID issue: For security reasons, cupsd does not allow external cups helper programs, which use the "Group" GID, to run in the Administration groups, which are those GIDs listed in "SystemGroup". If the named group in the Group directive is also in the SystemGroup directive, then cupsd changes the Group GID to "nobody" instead, without warning. However, the printer devices in "/dev/", for instance "/dev/parport0", are created with user "root" and group "lp". When cupsd then tries to print, it "pauses" or "stops" because it does not have permission to write the printer device file, and does not provide any useful error message. Making the printer device files "world writable" can bypass the problem, but is not the proper solution.<br />
<br />
==== CUPS permission errors ====<br />
<br />
* Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
* Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
==== HPLIP printer sends "/usr/lib/cups/backend/hp failed" error ====<br />
<br />
Make sure dbus is installed and running. If the error persists, try starting avahi-daemon.<br />
<br />
Try adding the printer as a Network Printer using the http:// protocol. Generate the printer URI with {{ic|hp-makeuri}}.<br />
<br />
{{Note|There might need to set permissions issues right. Follow indications here: [[CUPS#Device node permissions]].}}<br />
<br />
==== HPLIP printer claims job is complete but printer does nothing ====<br />
<br />
This happens on HP printers when you select the (old) hpijs driver (e.g. the Deskjet D1600 series). Instead, use the hpcups driver when adding the printer.<br />
<br />
Some HP printers (e.g HP LaserJet) require their firmware to be downloaded from the computer every time the printer is switched on. If there is an issue with udev (or equivalent) and the firmware download rule is never fired, you may experience this issue.<br />
As a workaround, you can manually download the firmware to the printer. Ensure the printer is plugged in and switched on, then enter<br />
hp-firmware -n<br />
<br />
==== hp-setup asks to specify the PPD file for the discovered printer ====<br />
<br />
Install CUPS before running hp-setup.<br />
<br />
==== I have installed Qt, but hp-setup reports "Qt/PyQt 4 initialization failed" ====<br />
<br />
"hp-check -t" won't give you useful information to find the required package. You have to install all the "Dependent Packages" prefixed with "python2" in https://www.archlinux.org/packages/extra/x86_64/hplip/<br />
<br />
==== hp-setup finds the printer automatically but reports "Unable to communicate with device" when printing test page immediately afterwards ====<br />
<br />
This at least happens to hplip 3.13.5-2 for HP Officejet 6500A through local network connection. To solve the problem, specify the IP address of the HP printer for hp-setup to locate the printer.<br />
<br />
==== hp-toolbox sends an error, "Unable to communicate with device" ====<br />
<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/''printer id''<br />
or, "{{ic|Unable to communicate with device"}}", then it may be needed to [[Groups#Group management|add the user to the lp and sys groups]].<br />
<br />
This can also be caused by printers such as the P1102 that provide a virtual cd-rom drive for MS-Windows drivers. The lp dev appears and then disappears. In that case try the '''usb-modeswitch''' and '''usb-modeswitch-data''' packages, that lets one switch off the "Smart Drive" (udev rules included in said packages).<br />
<br />
This can also occur with network attached printers if the [[Avahi|avahi-daemon]] is not running. Another possiblility is the specification of the printer's IP address in hp-setup fails to locate the printer because the IP address of the the printer changed due to DHCP.<br />
<br />
==== CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer ====<br />
<br />
If receiving any of the following error messages in {{ic|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer ''printer_name'' not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure {{pkg|hplip}} has been [[pacman|installed]], in addition to [[#Packages|the packages mentioned above]]. See [https://bbs.archlinux.org/viewtopic.php?id=65615 this forum post] for more information.<br />
<br />
==== Printing fails with unauthorised error ====<br />
<br />
If the user has been added to the lp group, and allowed to print (set in {{ic|cupsd.conf}}), then the problem lies in {{ic|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
==== Unknown supported format: application/postscript ====<br />
<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{ic|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{ic|/etc/cups/mime.types}}.<br />
<br />
==== Finding URIs for Windows print servers ====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
{{bc| WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series}}<br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
If it won't work try '%20' instead of spaces.<br />
<br />
==== Print-Job client-error-document-format-not-supported ====<br />
<br />
Try installing the foomatic packages and use a foomatic driver.<br />
<br />
==== Unable to get list of printer drivers ====<br />
<br />
* Check your ServerName in /etc/cups/client.conf is written without http://<br />
ServerName localhost:631<br />
* Try to remove Foomatic drivers or refer to [[#HP_Printer]] for a workaround.<br />
<br />
==== lp: Error - Scheduler Not Responding ====<br />
<br />
If you get this error when printing a document using:<br />
<br />
$ lp document-to-print<br />
<br />
Try setting the {{ic|CUPS_SERVER}} environment variable:<br />
<br />
$ export CUPS_SERVER=localhost<br />
<br />
If this solves your problem, make the solution permanent by adding the export line above to {{ic|~/.bash_profile}}.<br />
<br />
==== CUPS prints only an empty and an error-message page on HP LaserJet ====<br />
<br />
There is a bug that causes CUPS to fail when printing images on HP LaserJet (in my case 3380). The bug has been reported and fixed by [https://bugs.launchpad.net/ubuntu/+source/cups-filters/+bug/998087 Ubuntu].<br />
The first page is empty, the second page contains the following error message:<br />
ERROR:<br />
invalidaccess<br />
OFFENDING COMMAND:<br />
filter<br />
STACK:<br />
/SubFileDecode<br />
endstream<br />
...<br />
<br />
In order to fix the issue, use the following command (as superuser):<br />
lpadmin -p ''printer'' -o pdftops-renderer-default=pdftops<br />
<br />
==== "Using invalid Host" error message ====<br />
<br />
Try adding {{ic|ServerAlias *}} into {{ic|/etc/cups/cupsd.conf}}.<br />
<br />
==== Printer doesn't print with an "Filter failed" message on CUPS web interface (HP printer) ====<br />
<br />
Change the permissions of the printer USB port. Get the bus and device number from {{ic|lsusb}}, then set the permission using:<br />
<br />
{{hc| lsusb |<br />
Bus <BUSID> Device <DEVID>: ID <PRINTERID>:<VENDOR> Hewlett-Packard DeskJet D1360}}<br />
<br />
Then substitute the provided device information to the <br />
<br />
# chmod 0666 /dev/bus/usb/<BUSID>/<DEVID><br />
<br />
To make the persistent permission change that will be triggered automatically each time the computer is rebooted, add the following line.<br />
<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="<VENDOR>", ATTRS{idProduct}=="<PRINTERID>", GROUP="lp", MODE:="666"<br />
}}<br />
<br />
Each system may vary, so consult [[udev#List_attributes_of_a_device]] wiki page.<br />
<br />
==== Printer does not print with a "Filter failed" message on CUPS web interface (HP printer connected over network) ====<br />
<br />
Start, enable, and restart the {{ic|avahi-daemon}} service.<br />
<br />
==== HPLIP 3.13: Plugin is installed, but HP Device Manager complains it is not ====<br />
<br />
The issue might have to do with the file permission change that had been made to {{ic|/var/lib/hp/hplip.state}}. To correct the issue, a simple {{ic|chmod 644 /var/lib/hp/hplip.state}} and {{ic|chmod 755 /var/lib/hp}} should be sufficient. For further information, please read this [https://bugs.launchpad.net/hplip/+bug/1131596 link].<br />
<br />
==== Printer is not recognized by CUPS ====<br />
<br />
If your printer is not listed in the "Add Printers" page of the CUPS web interface, nor by {{ic|lpinfo -v}}, try the following (suggested in [https://bbs.archlinux.org/viewtopic.php?pid=1037279#p1037279 this thread]):<br />
<br />
* Remove {{ic|usblp}} from blacklist<br />
* Load {{ic|usblp}} module<br />
# modprobe usblp<br />
* Stop CUPS<br />
* Add the following udev rule in a new rule file:<br />
{{hc|/etc/udev/rules.d/10-cups_device_link.rules|2=<br />
KERNEL=="lp[0-9]", SYMLINK+="%k", GROUP="lp"<br />
}}<br />
* Reload udev rules:<br />
# udevadm control --reload-rules<br />
* Unplug the printer, and plug it in again.<br />
* Wait a few seconds, and then start the CUPS service.<br />
<br />
==== Cannot load /etc/samba/smb.conf ====<br />
<br />
If you are printing to a remote printer over SMB and get this error message: "Can't load /etc/samba/smb.conf - run testparm to debug it", then create an empty {{ic|/etc/samba/smb.conf}} file:<br />
<br />
# mkdir /etc/samba<br />
# touch /etc/samba/smb.conf<br />
<br />
and restart the CUPS service.<br />
<br />
==== CUPS' systemd service does not start even though it is enabled ====<br />
<br />
The systemd service file provided by CUPS uses socket activation, meaning the service is only started when an application connects to CUPS' socket. However, the systemd socket file provided by CUPS only works for the local <br />
{{ic|/var/run/cups/cups.sock}} socket. <br />
<br />
In order to have the CUPS service start when initiating a print job over the network, create the following file:<br />
<br />
{{hc|1=/etc/systemd/system/cups.socket|2=<br />
.include /usr/lib/systemd/system/cups.socket<br />
<br />
[Socket]<br />
ListenDatagram=0.0.0.0:631<br />
}}<br />
<br />
Then reload systemd:<br />
<br />
# systemctl --system daemon-reload<br />
<br />
Confirm that everything is working correctly:<br />
<br />
{{bc|<br />
# systemctl is-enabled cups.service &#124;&#124; systemctl enable cups.service<br />
# systemctl status cups.socket<br />
cups.socket - CUPS Printing Service Sockets<br />
Loaded: loaded (/etc/systemd/system/cups.socket; enabled)<br />
Active: inactive (dead)<br />
Listen: /var/run/cups/cups.sock (Stream)<br />
0.0.0.0:631 (Stream)<br />
0.0.0.0:631 (Datagram)<br />
}}<br />
<br />
CUPS should now start automatically when printing locally or over the network.<br />
<br />
==== "Forbidden" error when adding a printer ====<br />
<br />
If adding a printer through the web interface returns an error: ''Forbidden'', the most likely reason is that the privileges are not set correctly. One way to fix it is to add the administering user to the group {{ic|sys}}. For example,<br />
# usermod -a -G sys ''username''<br />
<br />
== See also ==<br />
<br />
* [http://localhost:631/help Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's printing guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation resources]''<br />
* [http://wiki.gotux.net/tutorials/software/hp-printer Install HP printers easy way]</div>Jstjohn