https://wiki.archlinux.org/api.php?action=feedcontributions&user=Netskink&feedformat=atomArchWiki - User contributions [en]2024-03-28T12:40:35ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Talk:QEMU&diff=414384Talk:QEMU2016-01-04T16:39:53Z<p>Netskink: /* host only networking */ new section</p>
<hr />
<div>== Linear RAID ==<br />
<br />
When I was updating the article yesterday, I had tried to fit the section about linear raid (boot a VM from a partition by prepending a MBR to it) into the article better. But I'm not sure the technique described is the right one at all. It looks like it works, but wouldn't it be easier to install a bootloader directly to the partition (e.g. syslinux)? Then the VM could be booted directly from the partition simply by using it as its virtual disk.<br />
--[[User:Synchronicity|Synchronicity]] ([[User talk:Synchronicity|talk]]) 19:23, 9 May 2012 (UTC)<br />
<br />
== Creating bridge manually ==<br />
<br />
I really don't know what to do with this section. I'd say it has been superseded by [[QEMU#Creating bridge using qemu-bridge-helper]] (available since qemu-1.1, we now have qemu-1.5) - or is someone still using this method? Perhaps link to https://en.wikibooks.org/wiki/QEMU/Networking#TAP_interfaces or http://wiki.qemu.org/Documentation/Networking/NAT is sufficient. What do you think? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:42, 22 July 2013 (UTC)<br />
<br />
:Actually, I've become a happy user of this method. I've written some scripts to easily create bridge interface, TAP interface, and combined with Xyne's [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html excellent scripts] to set up NAT and launch DHCP server, I have complete solution to easily manage multiple VMs on one (or even more) bridge.<br />
:My scripts are available on github: [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-launcher.sh], [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-tap-helper.sh], [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-mac-hasher.py] but I won't probably integrate them into the wiki, I'l just leave a note when I do some more testing.<br />
:The thing is, what to do with the current content? Personally I think that links to [https://en.wikibooks.org/wiki/QEMU/Networking#TAP_interfaces], [http://wiki.qemu.org/Documentation/Networking/NAT] and my scripts are sufficient (of course others are welcome). I'd also leave the note at the end to ''disable the firewall on the bridge'', I find it extremely useful.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:24, 5 September 2013 (UTC)<br />
<br />
== Starting QEMU virtual machines with systemd ==<br />
The custom systemd service script does not work. It always fails with {{ic|Failed at step EXEC spawning /usr/bin/qemu-{type}: No such file or directory}}. To Fix this modify the ExecStart command {{bc|1=ExecStart=/usr/bin/sh -c "/usr/bin/qemu-${type} -name %i -nographic ${args}"}}<br />
Also {{ic|echo 'system_powerdown' &#124; nc localhost 7101}} kills the VM immediatly. To fix this change the stop script. It simply checks each second if the main process is still running. {{bc|1=ExecStop=/usr/bin/sh -c "${haltcmd} && while [[ $(pidof qemu-${type} | grep $MAINPID) ]]; do sleep 1; done"}}<br />
{{ic|gnu-netcat}} does not work to connect to the monitor. You need to use {{ic|openbsd-netcat}}. -- [[User:Ant32|Ant32]] ([[User talk:Ant32|talk]]) 17:48, 5 September 2013 (UTC)<br />
<br />
:The first problem related to starting the service seems rather strange - didn't you have typo error in your local {{ic|qemu@.service}} file (missing the dollar sign {{ic|$}} in {{ic|${type} }})?<br />
:The second problem is valid, systemd kills the main process when the ExecStop command exits (see {{ic|systemd.service(5)}}). If your workaround really works, it could be added to the wiki with a proper description.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:17, 7 September 2013 (UTC)<br />
<br />
::Relevant thread on systemd-devel mailing list: [http://lists.freedesktop.org/archives/systemd-devel/2013-September/012982.html] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 00:00, 15 September 2013 (UTC)<br />
<br />
== Kexec Hackery When Using a Real Partition ==<br />
<br />
After banging my head against a wall long enough and figuring out what {{ic|-kernel}} and {{ic|-initrd}} were really calling, I put a note above the appropriate section and mentioned two ways to use the guest's images. (Otherwise, you'll have to worry if the host and guest images match.) The first -- mount the partition(s) -- is more appropriate for "low-volume-handling" of VMs. The second -- using kexec -- becomes more useful when you're juggling more than a few VMs.<br />
<br />
I'm only mentioning this hack because (as of now) [[Kexec]] only mentions use for rebooting into another kernel, not switching out the kernel before the system is even up. This hack comes from from https://digitalocean.uservoice.com/forums/136585-digitalocean/suggestions/2814988-give-option-to-use-the-droplet-s-own-bootloader- which has two suggestions. The most recent, using systemd units by jkuan, doesn't work because jkuan tried to copy a {{ic|.target}} file into a {{ic|.service}} file and systemd wants {{ic|ExecStart}} in a {{ic|.service}} file. The second one, replacing {{ic|/usr/bin/init}} by andrew_sparks, works for me on my Arch instance at DigitalOcean.<br />
<br />
Adaptation from said post:<br />
<br />
# pacman -S kexec-tools<br />
# pacman -R systemd-sysvcompat<br />
<br />
{{hc|1=/tmp/init|2=<br />
#!/bin/sh<br />
<br />
kexec --load /boot/vmlinuz-linux --initrd=/boot/initramfs-linux.img --append="root=/dev/sda init=/usr/lib/systemd/systemd" &&<br />
mount -o ro,remount / && kexec -e<br />
exec /usr/lib/systemd/systemd<br />
}}<br />
<br />
# cd [/path/to/vm]/usr/bin<br />
# mv init init.dist<br />
# cp /tmp/init ./<br />
# chmod 755 init<br />
<br />
I'm leaving this on the Talk page as I haven't even tried it out in QEMU myself. Also, my eyes are about ready to pop out of my head, so I'm barring myself from figuring out the appropriate way to edit this in for the time being. [[User:BrainwreckedTech|BrainwreckedTech]] ([[User talk:BrainwreckedTech|talk]]) 21:23, 14 January 2014 (UTC)<br />
<br />
== Replace -net with -netdev ==<br />
<br />
The {{ic|-net}} option is deprecated and replaced by {{ic|-netdev}}. I think this article should be modified to reflect that.<br />
http://en.wikibooks.org/wiki/QEMU/Networking#cite_ref-1<br />
[[User:Axper|axper]] ([[User talk:Axper|talk]]) 18:12, 1 July 2014 (UTC)<br />
<br />
== I'm rewriting the network section ==<br />
<br />
https://wiki.archlinux.org/index.php/User:Axper/sandbox/qemu_network<br />
[[User:Axper|axper]] ([[User talk:Axper|talk]]) 20:07, 2 July 2014 (UTC)<br />
<br />
::I think a lot of networking topics could be moved outside of the QEMU page. Many virtualization applications share the same basic principles with regards to networking, such as tun/tap creating, bridges, VDE, etc. There are a few networking schemes that are QEMU-specific, for example multicast sockets and {{ic|-net socket,...}}, and these could be mentioned on the QEMU page, although these are less reliable and rarely used in comparison to tap devices. We should also of course note the QEMU-specific command line options in the QEMU page, but for general concepts and commands independent of the virtualization applications, they could go on pages dedicated to the task. The best example is VDE, which is in no way limited to QEMU, yet it still doesn't have its own page on the Arch wiki.<br />
<br />
::Incidentally, I'm planning on rewriting [[User Mode Linux]] (yes, I promise I will get around to it), which happens to share the "tap with bridge" and VDE concepts with QEMU. It would be nice if I could link to pages dedicated to those topics and only write UML-specific commands in the page, instead of duplicating a bunch of general information. I'm not familiar very familiar with Xen or LXC or Docker or the like, but I would suspect that they also share some networking infrastructure. We could possibly even create a category just for these types of pages, for example "Virtual Networking" or "Advanced Networking". [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 13:32, 19 February 2015 (UTC)<br />
<br />
== -enable-kvm vs -machine type=pc,accel=kvm ==<br />
<br />
The section [[QEMU#Enabling_KVM]] recommends {{ic|-enable-kvm}}, while [[QEMU#Virtual_machine_runs_too_slowly]] recommends {{ic|1=-machine type=pc,accel=kvm}}. Is there any difference between the two? Is one preferred over the other? Should we just link to the former section from the latter (and possibly move both command line switches to the same section)? [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 17:23, 18 January 2015 (UTC)<br />
<br />
== virtio-gpu ==<br />
<br />
Any tutorial on using the new virtio-gpu which is introduced in qemu-2.4 and kernel 4.2? [[User:Adam900710|Adam900710]] ([[User talk:Adam900710|talk]]) 02:44, 19 August 2015 (UTC)<br />
<br />
== host only networking ==<br />
<br />
I added a quick and easy method but it was deleted. I found errors in what is here. Is it worth my time to correct them or will they be deleted?</div>Netskinkhttps://wiki.archlinux.org/index.php?title=QEMU&diff=413888QEMU2015-12-30T23:06:19Z<p>Netskink: /* Host-only Networking with ARM virtual machines (VM/Guests) */</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Hypervisors]]<br />
[[de:Qemu]]<br />
[[es:QEMU]]<br />
[[fr:Qemu]]<br />
[[ja:QEMU]]<br />
[[zh-CN:QEMU]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
<br />
From the [http://wiki.qemu.org/Main_Page QEMU about page]:<br />
:''QEMU is a generic and open source machine emulator and virtualizer.''<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installing QEMU ==<br />
<br />
{{Expansion|See {{Bug|45977}}.}}<br />
<br />
[[Install]] the {{Pkg|qemu}} package.<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s). However, there are several GUI front-ends for QEMU:<br />
<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
* {{AUR|aqemu}}<br />
<br />
Additional front-ends with QEMU support are available for [[libvirt]].<br />
<br />
== Creating new virtualized system ==<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Tip|See the [https://en.wikibooks.org/wiki/QEMU/Images QEMU Wikibook] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk.<br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. Using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GB image in the ''raw'' format:<br />
<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''qcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
{{Warning|If you store the hard disk images on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the directory before creating any images.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
<br />
$ qemu-img create -o backing_file=''img1.raw'',backing_fmt=''raw'' -f ''qcow2'' ''img1.cow''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
<br />
$ qemu-system-i386 ''img1.cow''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required.<br />
<br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like:<br />
<br />
$ qemu-img rebase -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked:<br />
<br />
$ qemu-img rebase -u -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the operating system installed on it unbootable. For full explanation and workaround see [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages].}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example, to increase image space by 10 GB, run:<br />
<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
After enlarging the disk image, you must use file system and partitioning tools inside the virtual machine to actually begin using the new space. When shrinking a disk image, you must '''first reduce the allocated file systems and partition sizes''' using the file system and partitioning tools inside the virtual machine and then shrink the disk image accordingly, otherwise shrinking the disk image will result in data loss!<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly.<br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso''}}}}<br />
<br />
=== Installing the operating system===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 guests, to install from a bootable ISO file as CD-ROM:<br />
<br />
$ qemu-system-i386 -cdrom ''iso_image'' -boot order=d ''qemu_image''<br />
<br />
See {{ic|qemu(1)}} for information about loading other media types, such as floppy or disk images, or physical drives.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Tip|<br />
* By default only 128 MB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512M}} or {{ic|-m 2G}}.<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on guest's architecture) are used to run the virtualized guest. The usage is:<br />
<br />
$ qemu-system-i386 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{ic|qemu(1)}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM must be supported by your processor and kernel, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-enable-kvm}} to the additional start options. To check if KVM is enabled for a running VM, enter the QEMU [https://en.wikibooks.org/wiki/QEMU/Monitor Monitor] using {{ic|Ctrl+Alt+Shift+2}}, and type {{ic|info kvm}}.<br />
<br />
{{Note|<br />
* If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.<br />
* KVM needs to be enabled in order to start Windows 7 and Windows 8 properly without a ''blue screen''.<br />
}}<br />
<br />
== Moving data between host and guest OS ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[SMB]] or [[NFS]], or you can access the host's HTTP server, etc.<br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] with an automatically generated {{ic|smb.conf}} file located at {{ic|/tmp/qemu-smb.''pid''-0/smb.conf}} and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and this is not necessarily very useful since the guest can also access the normal [[Samba]] service on the host if you have set up shares on it.<br />
<br />
To enable this feature, start QEMU with a command like:<br />
<br />
$ qemu-system-i386 ''disk_image'' -net nic -net user,smb=''shared_dir_path''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
{{Note|<br />
* If you are using sharing options multiple times like {{ic|1=-net user,smb=''shared_dir_path1'' -net user,smb=''shared_dir_path2''}} or {{ic|1=-net user,smb=''shared_dir_path1'',smb=''shared_dir_path2''}} then it will share only the last defined one.<br />
* If you cannot access the shared folder and the guest system is Windows, check that the [http://ecross.mvps.org/howto/enable-netbios-over-tcp-ip-with-windows.htm NetBIOS protocol is enabled] and that a firewall does not block [http://technet.microsoft.com/en-us/library/cc940063.aspx ports] used by the NetBIOS protocol.<br />
}}<br />
<br />
=== Mounting a partition inside a raw disk image ===<br />
<br />
When the virtual machine is not running, it is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices. This does not work with disk images in special formats, such as qcow2, although those can be mounted using {{ic|qemu-nbd}}.<br />
<br />
{{Warning|You must make sure to unmount the partitions before running the virtual machine again. Otherwise, data corruption is very likely to occur.}}<br />
<br />
==== With manually specifying byte offset ====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
==== With loop module autodetecting partitions ====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* [[Kernel_modules#Manual_module_handling|Unload]] the {{ic|loop}} kernel module, and load it with the {{ic|1=max_part=15}} parameter set. Additionally, the maximum number of loop devices can be controlled with the {{ic|max_loop}} parameter.<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
<br />
# losetup -f -P ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
==== With kpartx ====<br />
<br />
'''kpartx''' from the {{AUR|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a ''disk_image''<br />
<br />
This will setup the loopback device and create the necessary partition(s) device(s) in {{ic|/dev/mapper/}}.<br />
<br />
=== Mounting a partition inside a qcow2 image ===<br />
<br />
You may mount a partition inside a qcow2 image using {{ic|qemu-nbd}}. See [http://en.wikibooks.org/wiki/QEMU/Images#Mounting_an_image_on_the_host Wikibooks].<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you need to change the owner of the partition's device file to that user.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[kernel]] and [[initramfs|initrd]] manually, or by simulating a disk with a MBR by using linear [[RAID]].<br />
<br />
==== By specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
<br />
{{Note|In this example, it is the '''host's''' images that are being used, not the guest's. If you wish to use the guest's images, either mount {{ic|/dev/sda3}} read-only (to protect the file system from the host) and specify the {{ic|/full/path/to/images}} or use some kexec hackery in the guest to reload the guest's kernel (extends boot time). }}<br />
<br />
$ qemu-system-i386 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
When there are multiple [[kernel parameters]] to be passed to the {{ic|-append}} option, they need to be quoted using single or double quotes. For example:<br />
<br />
... -append 'root=/dev/sda1 console=ttyS0'<br />
<br />
==== Simulate virtual disk with MBR using linear RAID ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate a MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
You can do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: the trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image.<br />
<br />
Suppose you have a plain, unmounted {{ic|/dev/hdaN}} partition with some file system on it you wish to make part of a QEMU disk image. First, you create some small file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hdaN}} disk image using software RAID:<br />
<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kilobyte-roundable offsets (such as 31.5 KB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu.<br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image:<br />
<br />
$ qemu-system-i386 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
== Networking ==<br />
<br />
{{Poor writing|Network topologies (sections [[#Host-only networking]], [[#Internal networking]] and info spread out across other sections) should not be described alongside the various virtual interfaces implementations, such as [[#User-mode networking]], [[#Tap networking with QEMU]], [[#Networking with VDE2]].}}<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [http://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
<ol><br />
<li>Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
</li><br />
<li>Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
{{bc|1=<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-i386 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
}}<br />
<br />
</li><br />
<li>Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|<nowiki><br />
#!/usr/bin/env python<br />
<br />
import sys<br />
import zlib<br />
<br />
if len(sys.argv) != 2:<br />
print("usage: %s <VM Name>" % sys.argv[0])<br />
sys.exit(1)<br />
<br />
crc = zlib.crc32(sys.argv[1].encode("utf-8")) & 0xffffffff<br />
crc = str(hex(crc))[2:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))<br />
</nowiki>}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-i386 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
</li><br />
</ol><br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU.<br />
<br />
{{warning|This only works with the TCP and UDP protocols, so ICMP, including {{ic|ping}}, will not work. Do not use {{ic|ping}} to test network connectivity.}}<br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, redirecting host ports to the guest (for example to allow SSH connections to the guest) or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the [[Firewalls|precautions]] you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, a better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
As indicated in the user-mode networking section, tap devices offer higher networking performance than user-mode. If the guest OS supports virtio network driver, then the networking performance will be increased considerably as well. Supposing the use of the tap0 device, that the virtio driver is used on the guest, and that no scripts are used to help start/stop networking, next is part of the qemu command one should see:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no<br />
<br />
But if already using a tap device with virtio networking driver, one can even boost the networking performance by enabling vhost, like:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no,vhost=on<br />
<br />
See http://www.linux-kvm.com/content/how-maximize-virtio-net-performance-vhost-net for more information.<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet sharing#Enable NAT]] page.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface&#61;br0 --bind-interfaces --dhcp-range&#61;172.20.0.2,172.20.255.254<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
By default iptables would drop packets in the bridge network. You may need to use such iptables rule to allow packets in a bridged network:<br />
<br />
# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
{{Note|This method is available since QEMU 1.1, see http://wiki.qemu.org/Features/HelperNetworking.}}<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|See [[Network bridge]] for information on creating bridge.}}<br />
<br />
First, copy {{ic|/etc/qemu/bridge.conf.sample}} to {{ic|/etc/qemu/bridge.conf}}. Now modify {{ic|/etc/qemu/bridge.conf}} to contain the names of all bridges to be used by QEMU:<br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''bridge0''<br />
allow ''bridge1''<br />
...}}<br />
<br />
Now start the VM. The most basic usage would be:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' ''[...]''<br />
<br />
With multiple taps, the most basic usage requires specifying the VLAN for all additional NICs:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' -net nic,vlan=1 -net bridge,vlan=1,br=''bridge1'' ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [http://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it. See http://en.gentoo-wiki.com/wiki/KVM#Networking_2{{Dead link|2013|07|23}}.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
# sysctl net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Now create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=$(whoami)<br />
<br />
# Get name of newly created TAP device; see https://bbs.archlinux.org/viewtopic.php?pid=1285079#p1285079<br />
precreationg=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
sudo /usr/bin/ip tuntap add user $USERID mode tap<br />
postcreation=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
IFACE=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
<br />
# This line creates a random MAC address. The downside is the DHCP server will assign a different IP address each time<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
# Instead, uncomment and edit this line to set a static MAC address. The benefit is that the DHCP server will assign the same IP address.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu-system-i386 -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo ip link set dev $IFACE down &> /dev/null<br />
sudo ip tuntap del $IFACE mode tap &> /dev/null<br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
$ run-qemu -hda ''myvm.img'' -m 512 -vga std<br />
<br />
* It is recommended for performance and security reasons to disable the [http://ebtables.netfilter.org/documentation/bridge-nf.html firewall on the bridge]:<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [http://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Loading]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Network sharing between physical device and a Tap device through iptables ====<br />
<br />
{{Merge|Internet_sharing|Duplication, not specific to QEMU.}}<br />
<br />
Bridged networking works fine between a wired interface (Eg. eth0), and it's easy to setup. However if the host gets connected to the network through a wireless device, then bridging is not possible.<br />
<br />
See https://wiki.archlinux.org/index.php/Network_bridge#Wireless_interface_on_a_bridge as a reference.<br />
<br />
One way to overcome that is to setup a tap device with a static IP, making linux automatically handle the routing for it, and then forward traffic between the tap interface and the device connected to the network through iptables rules.<br />
<br />
See https://wiki.archlinux.org/index.php/Internet_sharing as a reference.<br />
<br />
There you can find what's needed to share the network between devices, included tap and tun ones. The following just hints further on some of the host configurations required. As indicated in the reference above, the client needs to be configured for a static IP, using the IP assigned to the tap interface as the gateway. The caveat is that the DNS servers on the client might need to be manually edited if they change when changing from one host device connected to the network to another.<br />
<br />
To allow IP forwarding on every boot, one need to add the following lines to sysctl configuration file inside /etc/sysctl.d:<br />
<br />
net.ipv4.ip_forward = 1<br />
net.ipv6.conf.default.forwarding = 1<br />
net.ipv6.conf.all.forwarding = 1<br />
<br />
The iptables rules can look like:<br />
<br />
# Forwarding from/to outside<br />
iptables -A FORWARD -i ${INT} -o ${EXT_0} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_1} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_2} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_0} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_1} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_2} -o ${INT} -j ACCEPT<br />
# NAT/Masquerade (network address translation)<br />
iptables -t nat -A POSTROUTING -o ${EXT_0} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_1} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_2} -j MASQUERADE<br />
<br />
The prior supposes there are 3 devices connected to the network sharing traffic with one internal device, where for example:<br />
<br />
INT=tap0<br />
EXT_0=eth0<br />
EXT_1=wlan0<br />
EXT_2=tun0<br />
<br />
The prior shows a forwarding that would allow sharing wired and wireless connections with the tap device.<br />
<br />
The forwarding rules shown are stateless, and for pure forwarding. One could think of restricting specific traffic, putting a firewall in place to protect the guest and others. However those would decrease the networking performance, while a simple bridge doesn't include any of that.<br />
<br />
Bonus: Whether the connection is wired or wireless, if one gets connected through VPN to a remote site with a tun device, supposing the tun device opened for that connection is tun0, and the prior iptables rules are applied, then the remote connection gets also shared with the guest. This avoids the need for the guest to also open a VPN connection. Again, as the guest networking needs to be static, then if connecting the host remotely this way, one most probably will need to edit the DNS servers on the guest.<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [http://wiki.virtualsquare.org/wiki/index.php/Main_Page the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-i386 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep -f vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be executable<br />
<br />
# chmod u+x /etc/systemd/scripts/qemu-network-env<br />
<br />
You can [[start]] {{ic|qemu-network-env.service}} as usual.<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
<br />
=== Host-only Networking with ARM virtual machines (VM/Guests) ===<br />
<br />
This is a concise method for setting up host only networking for ARM guests. ie. the vm and host can ssh, ping each other. Interactions between<br />
multiple guests will not work since only one bridge/tap is specified. The method is slightly different for i386 guests and that method is not described here but in the attached notes.<br />
<br />
==== Components Needed ====<br />
<br />
These are the components used for this method:<br />
<br />
* qemu<br />
* qemu-arch-extra <br />
* dnsmasq<br />
* bridge-utils<br />
<br />
==== Procedure ====<br />
<br />
Start the bridge/tap and dhcp server for the host only network. Afterwards the interfaces will be down. When the vm is started these interfaces will be started. Possibly netctl's bridge example interface could do this but it was simpler to just write a script. This script will need to be run using sudo. Lastly, the ip address chosen 172.16.0.1 was chosen since it did not conflict with any network currently in use.<br />
<br />
{{hc|do_network.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Do this to setup host only networking<br />
brctl addbr br0<br />
ip addr add 172.16.0.1/24 broadcast 172.16.0.255 dev br0<br />
ip link set br0 up<br />
ip tuntap add dev tap0 mode tap<br />
ip link set tap0 up promisc on<br />
brctl addif br0 tap0<br />
ip link set tap0 up<br />
dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.16.0.10,172.16.0.20<br />
</nowiki>}}<br />
<br />
Once the tap/bridge is setup start the arm vm like so:<br />
<br />
{{hc|doit.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Do this to setup host only networking<br />
brctl addbr br0<br />
ip addr add 172.16.0.1/24 broadcast 172.16.0.255 dev br0<br />
ip link set br0 up<br />
ip tuntap add dev tap0 mode tap<br />
ip link set tap0 up promisc on<br />
brctl addif br0 tap0<br />
ip link set tap0 up<br />
dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.16.0.10,172.16.0.20<br />
</nowiki>}}<br />
<br />
{{hc|do_network.sh|<nowiki><br />
#!/bin/bash<br />
<br />
sudo qemu-system-arm -M vexpress-a9 -kernel vmlinuz-3.2.0-4-vexpress \<br />
-initrd initrd.img-3.2.0-4-vexpress -append "root=/dev/mmcblk0p2" \<br />
-drive if=sd,cache=unsafe,file=hda.img \<br />
-net nic,vlan=0 -net tap,vlan=0,ifname=tap0,script=no<br />
</nowiki>}}<br />
<br />
==== More Details ====<br />
<br />
More details on how to setup a virtual machine, building qemu, using a similar method for i386, credits to the work this is based on and more are found here <br />
http://github.com/netskink/carolinacon12<br />
<br />
== Graphics ==<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|cirrus}}, {{ic|vmware}}, {{ic|qxl}}, and {{ic|none}}.<br />
<br />
=== cirrus ===<br />
<br />
The cirrus graphical adapter was the default [http://wiki.qemu.org/ChangeLog/2.2#VGA before 2.2]. It [https://www.kraxel.org/blog/2014/10/qemu-using-cirrus-considered-harmful/ should not] be used on modern systems.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels. This is the default since QEMU 2.2.<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. On the guest, install the VMware drivers ({{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests).<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, pass the {{ic|-vga qxl}} option and install drivers in the guest.<br />
<br />
For basic support (similar to {{ic|-vga std}}) in Linux guests, the qxl and bochs_drm kernel modules must be loaded. The xorg modesetting driver (part of {{Pkg|xorg-server}}) can be combined with these drivers. Drivers for other operating systems can be found on the [http://www.spice-space.org/download.html SPICE download page]. Advanced functionality such as multi-monitor support requires [[#Spice support|SPICE]].<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
=== vnc ===<br />
<br />
Given that you used the {{ic|-nographic}} option, you can add the {{ic|-vnc display}} option to have QEMU listen on {{ic|display}} and redirect the VGA display to the VNC session. There is an example of this in the [[#Starting QEMU virtual machines on boot]] section's example configs.<br />
<br />
$ qemu-system-i386 -vga std -nographic -vnc :0<br />
$ gvncviewer :0<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [http://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [http://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} instead of the simple {{Ic|-hd*}} plus {{Ic|1=if=virtio}}:<br />
$ qemu-system-i386 -boot order=c -drive file=''disk_image'',if=virtio<br />
<br />
{{Note|{{Ic|1=-boot order=c}} is absolutely necessary when you want to boot from it. There is no auto-detection as with {{Ic|-hd*}}.}}<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-i386 -net nic,model=virtio<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an (Arch) Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must contain the necessary modules. By default, this is handled by [[mkinitcpio]]'s {{ic|autodetect}} hook. Otherwise use the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}} to include the necessary modules and rebuild the initial ramdisk.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES="virtio virtio_blk virtio_pci virtio_net"}}<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing to disks by [[UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [http://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
{{Note|1=The only (reliable) way to upgrade a Windows 8.1 guest to Windows 10 seems to be to temporarily choose cpu core2duo,nx for the install [http://ubuntuforums.org/showthread.php?t=2289210]. After the install, you may revert to other cpu settings (8/8/2015).}}<br />
<br />
==== Block device drivers ====<br />
<br />
===== New Install of Windows =====<br />
<br />
Windows does not come with the virtio drivers. Therefore, you will need to load them during installation. There are basically two ways to do this: via Floppy Disk or via ISO files. Both images can be downloaded from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
The floppy disk option is difficult because you will need to press F6 (Shift-F6 on newer Windows) at the very beginning of powering on the QEMU. This is difficult since you need time to connect your VNC console window. You can attempt to add a delay to the boot sequence. See {{ic|man qemu-system}} for more details about applying a delay at boot.<br />
<br />
The ISO option to load drivers is the preferred way, but it is available only on Windows Vista and Windows Server 2008 and later. The procedure is to load the image with virtio drivers in an additional cdrom device along with the primary disk device and Windows installer:<br />
<br />
$ qemu-system-i386 ... \<br />
-drive file=''/path/to/primary/disk.img'',index=0,media=disk,if=virtio \<br />
-drive file=''/path/to/installer.iso'',index=2,media=cdrom \<br />
-drive file=''/path/to/virtio.iso'',index=3,media=cdrom \<br />
...<br />
<br />
During the installation, the Windows installer will ask you for your Product key and perform some additional checks. When it gets to the "Where do you want to install Windows?" screen, it will give a warning that no disks are found. Follow the example instructions below (based on Windows Server 2012 R2 with Update).<br />
<br />
* Select the option {{ic|Load Drivers}}.<br />
* Uncheck the box for "Hide drivers that aren't compatible with this computer's hardware".<br />
* Click the Browse button and open the CDROM for the virtio iso, usually named "virtio-win-XX".<br />
* Now browse to {{ic|E:\viostor\[your-os]\amd64}}, select it, and press OK.<br />
* Click Next<br />
<br />
You should now see your virtio disk(s) listed here, ready to be selected, formatted and installed to.<br />
<br />
===== Change Existing Windows VM to use virtio =====<br />
Modifying an existing Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
Now you need to create a new disk image, which fill force Windows to search for the driver. For example:<br />
<br />
$ qemu-img create -f qcow2 ''fake.qcow2'' 1G<br />
<br />
Run the original Windows guest (with the boot disk still in IDE mode) with the fake disk (in virtio mode) and a CD-ROM with the driver.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=ide -drive file=''fake.qcow2'',if=virtio -cdrom virtio-win-0.1-81.iso<br />
<br />
Windows will detect the fake disk and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
When the installation is successful, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio<br />
<br />
{{Note|If you encounter the Blue Screen of Death, make sure you did not forget the {{ic|-m}} parameter, and that you do not boot with virtio instead of ide for the system drive before drivers are installed.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-net}} argument as explained above.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio -net nic,model=virtio -cdrom virtio-win-0.1-74.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|<nowiki><br />
virtio_loader="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
</nowiki>}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
{{bc|<nowiki><br />
sed -i bak "s/ada/vtbd/g" /etc/fstab<br />
</nowiki>}}<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured through the virt-manager GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== Custom script ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|<nowiki><br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="type=system-x86_64" "haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/env qemu-${type} -name %i -nographic $args<br />
ExecStop=/bin/sh -c ${haltcmd}<br />
TimeoutStopSec=30<br />
KillMode=none<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|According to {{ic|systemd.service(5)}} and {{ic|systemd.kill(5)}} man pages it is necessary to use the {{ic|1=KillMode=none}} option. Otherwise the main qemu process will be killed immediately after the {{ic|ExecStop}} command quits (it simply echoes one string) and your quest system will not be able to shutdown correctly.}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the following variables set:<br />
<br />
; type<br />
: QEMU binary to call. If specified, will be prepended with {{ic|/usr/bin/qemu-}} and that binary will be used to start the VM. I.e. you can boot e.g. {{ic|qemu-system-arm}} images with {{ic|1=type="system-arm"}}.<br />
; args<br />
: QEMU command line to start with. Will always be prepended with {{ic|-name ${vm} -nographic}}.<br />
; haltcmd<br />
: Command to shut down a VM safely. I am using {{ic|-monitor telnet:..}} and power off my VMs via ACPI by sending {{ic|system_powerdown}} to monitor. You can use SSH or some other ways.<br />
<br />
Example configs:<br />
<br />
{{hc|/etc/conf.d/qemu.d/one|<nowiki><br />
type="system-x86_64"<br />
<br />
args="-enable-kvm -m 512 -hda /dev/mapper/vg0-vm1 -net nic,macaddr=DE:AD:BE:EF:E0:00 \<br />
-net tap,ifname=tap0 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7100" # or netcat/ncat<br />
<br />
# You can use other ways to shut down your VM correctly<br />
#haltcmd="ssh powermanager@vm1 sudo poweroff"<br />
</nowiki>}}<br />
<br />
{{hc|/etc/conf.d/qemu.d/two|<nowiki><br />
args="-enable-kvm -m 512 -hda /srv/kvm/vm2.img -net nic,macaddr=DE:AD:BE:EF:E0:01 \<br />
-net tap,ifname=tap1 -serial telnet:localhost:7001,server,nowait,nodelay \<br />
-monitor telnet:localhost:7101,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7101"<br />
</nowiki>}}<br />
<br />
To set which virtual machines will start on boot-up, use<br />
<br />
# systemctl enable qemu@''vm_name''<br />
# systemctl disable qemu@''vm_name''<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the option {{ic|-usbdevice tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
<br />
$ qemu-system-i386 -hda ''disk_image'' -m 512 -vga std -usbdevice tablet<br />
<br />
If that doesn't work, try the tip at [[#Mouse cursor is jittery or erratic]].<br />
<br />
=== Pass-through host USB device ===<br />
<br />
To access physical USB device connected to host from VM, you can start QEMU with following option:<br />
<br />
$ qemu-system-i386 -usbdevice host:''vendor_id'':''product_id'' ''disk_image''<br />
<br />
You can find {{ic|vendor_id}} and {{ic|product_id}} of your device with {{ic|lsusb}} command.<br />
<br />
{{Note|If you encounter permission errors when running QEMU, see [[Udev#Writing udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
To enable KSM, simply run<br />
<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, you can use [[systemd#Temporary files|systemd's temporary files]]:<br />
<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://www.kernel.org/doc/Documentation/vm/ksm.txt for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory: {{bc|$ grep . /sys/kernel/mm/ksm/*}}}}<br />
<br />
=== Spice support ===<br />
<br />
{{Poor writing|This section needs much more information and shall be placed under the [[#Graphics]] section .}}<br />
<br />
The [http://spice-space.org/ SPICE project] aims to provide a complete, open-source solution for interaction with virtualized desktop devices. Its main focus is to provide high-quality remote access to QEMU virtual machines.<br />
<br />
The official {{Pkg|qemu}} package is built with SPICE support.<br />
<br />
You can start your VM:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing,addr=::1<br />
<br />
{{Out of date|1=''spicec'' has been removed in {{Pkg|spice}}-0.12.6 [http://cgit.freedesktop.org/spice/spice/tree/NEWS?id=f0aeb9db000a34a46b51c5d95229171ff1eee307#n3].}}<br />
<br />
Then connect with a spice client<br />
<br />
$ spicec -h 127.0.0.1 -p 5930<br />
<br />
{{Tip|<br />
* The key combination to escape mouse and keyboard grab can be configured for {{ic|spicec}}, the default is {{ic|Shift+F12}}: {{bc|1=$ spicec --hotkeys release-cursor=ctrl+alt}}<br />
* To disable mouse and keyboard grabbing for {{ic|spicec}} (useful to allow your window manager shortcuts to work), set {{ic|1=SPICE_NOGRAB=1}}.<br />
* {{Pkg|virt-manager}} has a SPICE client built in.<br />
* {{Pkg|spice-gtk3}} provides another client for demoing purposes. Example usage: {{ic|spicy -h 127.0.0.1 -p 5930}}.<br />
}}<br />
<br />
==== SPICE Guest Additions ====<br />
For improved support for multiple monitors, clipboard sharing and more, you have to install additional packages in your ''guest'':<br />
* {{AUR|spice-vdagent}}: for [http://people.freedesktop.org/~teuf/spice-doc/html/ch02s05.html Agent] support. Do not forget to enable the {{ic|spice-vdagentd}} service.<br />
* {{AUR|xf86-video-qxl}}: for the QXL display driver.<br />
* For other operating systems, see http://people.freedesktop.org/~teuf/spice-doc/html/ch04.html<br />
<br />
In addition to the {{ic|-spice}} option, these options are also needed:<br />
<br />
-device virtio-serial \<br />
-chardev spicevmc,id=vdagent,name=vdagent \<br />
-device virtserialport,chardev=vdagent,name=com.redhat.spice.0<br />
<br />
The spicec and spicy program are intended for testing purposes, to enable additional monitors you have to install the {{Pkg|virtviewer}} package. Then connect with the VM using:<br />
<br />
remote-viewer spice://localhost:5930<br />
<br />
==== Multi-monitor support ====<br />
The Linux QXL driver supports four heads (virtual screens) by default. This can be changed via the {{ic|1=qxl.heads=N}} kernel parameter.<br />
<br />
The default VGA memory size for QXL devices is 16M (VRAM size is 64M). This is not sufficient if you would like to enable two 1920x1200 monitors since that requires 2 × 1920 × 4 (color depth) × 1200 = 17.6 MiB VGA memory. This can be changed by replacing {{ic|-vga qxl}} by {{ic|<nowiki>-vga none -device qxl-vga,vgamem_mb=32</nowiki>}}. If you ever increase vgamem_mb beyond 64M, then you also have to increase the {{ic|vram_size_mb}} option.<br />
<br />
=== Copy and paste ===<br />
<br />
To have copy and paste between the host and the guest you need to enable the spice agent communication channel. It requires to add a virtio-serial device to the guest, and open a port for the spice vdagent. It is also required to install the spice vdagent in guest ({{AUR|spice-vdagent}} for Arch guests, [http://www.spice-space.org/download.html Windows guest tools] for Windows guests). Make sure the agent is running (and for future, started automatically).<br />
<br />
Start QEMU with the following options:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The {{ic|-device virtio-serial-pci}} option adds the virtio-serial device, {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in that device and {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port.<br />
<br />
It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 10.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-i386 -nographic -net user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either rdesktop or freerdp to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|~/.bashrc}} file.<br />
<br />
=== No visible Cursor ===<br />
<br />
Add {{ic|-show-cursor}} to QEMU's options to see a mouse cursor.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps}}.<br />
<br />
$ qemu-system-i386 -k ''keymap'' ''disk_image''<br />
<br />
=== Virtual machine runs too slowly ===<br />
<br />
There are a number of techniques that you can use to improve the performance if your virtual machine. For example:<br />
<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU. If you do not do this, it may be trying to emulate a more generic CPU.<br />
* If the host machine has multiple CPUs, assign the guest more CPUs using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* Use KVM if possible: add {{ic|1=-machine type=pc,accel=kvm}} to the QEMU start command you use.<br />
* If supported by drivers in the guest operating system, use [http://wiki.libvirt.org/page/Virtio virtio] for network and/or block devices. For example:<br />
$ qemu-system-i386 -net nic,model=virtio -net tap,if=tap0,script=no -drive file=''disk_image'',media=disk,if=virtio<br />
* Use TAP devices instead of user-mode networking. See [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, disable the cache:<br />
$ qemu-system-i386 -drive file=''disk_image'',if=virtio,cache=none<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]:<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU with the {{ic|-balloon virtio}} option.<br />
<br />
See http://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
=== Guest display stretches on window resize ===<br />
<br />
To restore default window size, press {{ic|Ctrl+Alt+u}}.<br />
<br />
=== ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy ===<br />
<br />
If an error message like this is printed when starting QEMU with {{ic|-enable-kvm}} option:<br />
<br />
ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy<br />
failed to initialize KVM: Device or resource busy<br />
<br />
that means another [[hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<br />
<br />
=== libgfapi error message ===<br />
<br />
The error message displayed at startup:<br />
<br />
Failed to open module: libgfapi.so.0: cannot open shared object file: No such file or directory<br />
<br />
is not a problem, it just means that you are lacking the optional GlusterFS dependency.<br />
<br />
=== Kernel panic on LIVE-environments===<br />
<br />
If you start a live-environment (or better: booting a system) you may encounter this:<br />
<br />
[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)<br />
<br />
or some other boot hindering process (e.g. can't unpack initramfs, cant start service foo).<br />
Try starting the VM with the {{ic|-m VALUE}} switch and an appropriate amount of RAM, if the ram is to low you will probably encounter similar issues as above/without the memory-switch.<br />
<br />
<br />
== See also ==<br />
<br />
* [http://qemu.org Official QEMU website]<br />
* [http://www.linux-kvm.org Official KVM website]<br />
* [http://qemu.weilnetz.de/qemu-doc.html QEMU Emulator User Documentation]<br />
* [https://en.wikibooks.org/wiki/QEMU QEMU Wikibook]<br />
* [http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU] by AlienBOB (last updated in 2008)<br />
* [http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army] by Falconindy<br />
* [http://git.qemu.org/?p=qemu.git;a=tree;f=docs Lastest docs]<br />
* [http://qemu.weilnetz.de/ QEMU on Windows]<br />
* [http://en.wikipedia.org/wiki/Qemu Wikipedia]<br />
* [https://wiki.debian.org/QEMU QEMU - Debian Wiki]<br />
* [https://people.gnome.org/~markmc/qemu-networking.html QEMU Networking on gnome.org]<br />
* [http://bsdwiki.reedmedia.net/wiki/networking_qemu_virtual_bsd_systems.html Networking QEMU Virtual BSD Systems]<br />
* [https://www.gnu.org/software/hurd/hurd/running/qemu.html QEMU on gnu.org]<br />
* [https://wiki.freebsd.org/qemu QEMU on FreeBSD as host]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=QEMU&diff=413845QEMU2015-12-30T13:58:09Z<p>Netskink: /* Components Needed */</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Hypervisors]]<br />
[[de:Qemu]]<br />
[[es:QEMU]]<br />
[[fr:Qemu]]<br />
[[ja:QEMU]]<br />
[[zh-CN:QEMU]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
<br />
From the [http://wiki.qemu.org/Main_Page QEMU about page]:<br />
:''QEMU is a generic and open source machine emulator and virtualizer.''<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installing QEMU ==<br />
<br />
{{Expansion|See {{Bug|45977}}.}}<br />
<br />
[[Install]] the {{Pkg|qemu}} package.<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s). However, there are several GUI front-ends for QEMU:<br />
<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
* {{AUR|aqemu}}<br />
<br />
Additional front-ends with QEMU support are available for [[libvirt]].<br />
<br />
== Creating new virtualized system ==<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Tip|See the [https://en.wikibooks.org/wiki/QEMU/Images QEMU Wikibook] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk.<br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. Using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GB image in the ''raw'' format:<br />
<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''qcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
{{Warning|If you store the hard disk images on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the directory before creating any images.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
<br />
$ qemu-img create -o backing_file=''img1.raw'',backing_fmt=''raw'' -f ''qcow2'' ''img1.cow''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
<br />
$ qemu-system-i386 ''img1.cow''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required.<br />
<br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like:<br />
<br />
$ qemu-img rebase -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked:<br />
<br />
$ qemu-img rebase -u -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the operating system installed on it unbootable. For full explanation and workaround see [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages].}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example, to increase image space by 10 GB, run:<br />
<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
After enlarging the disk image, you must use file system and partitioning tools inside the virtual machine to actually begin using the new space. When shrinking a disk image, you must '''first reduce the allocated file systems and partition sizes''' using the file system and partitioning tools inside the virtual machine and then shrink the disk image accordingly, otherwise shrinking the disk image will result in data loss!<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly.<br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso''}}}}<br />
<br />
=== Installing the operating system===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 guests, to install from a bootable ISO file as CD-ROM:<br />
<br />
$ qemu-system-i386 -cdrom ''iso_image'' -boot order=d ''qemu_image''<br />
<br />
See {{ic|qemu(1)}} for information about loading other media types, such as floppy or disk images, or physical drives.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Tip|<br />
* By default only 128 MB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512M}} or {{ic|-m 2G}}.<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on guest's architecture) are used to run the virtualized guest. The usage is:<br />
<br />
$ qemu-system-i386 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{ic|qemu(1)}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM must be supported by your processor and kernel, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-enable-kvm}} to the additional start options. To check if KVM is enabled for a running VM, enter the QEMU [https://en.wikibooks.org/wiki/QEMU/Monitor Monitor] using {{ic|Ctrl+Alt+Shift+2}}, and type {{ic|info kvm}}.<br />
<br />
{{Note|<br />
* If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.<br />
* KVM needs to be enabled in order to start Windows 7 and Windows 8 properly without a ''blue screen''.<br />
}}<br />
<br />
== Moving data between host and guest OS ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[SMB]] or [[NFS]], or you can access the host's HTTP server, etc.<br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] with an automatically generated {{ic|smb.conf}} file located at {{ic|/tmp/qemu-smb.''pid''-0/smb.conf}} and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and this is not necessarily very useful since the guest can also access the normal [[Samba]] service on the host if you have set up shares on it.<br />
<br />
To enable this feature, start QEMU with a command like:<br />
<br />
$ qemu-system-i386 ''disk_image'' -net nic -net user,smb=''shared_dir_path''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
{{Note|<br />
* If you are using sharing options multiple times like {{ic|1=-net user,smb=''shared_dir_path1'' -net user,smb=''shared_dir_path2''}} or {{ic|1=-net user,smb=''shared_dir_path1'',smb=''shared_dir_path2''}} then it will share only the last defined one.<br />
* If you cannot access the shared folder and the guest system is Windows, check that the [http://ecross.mvps.org/howto/enable-netbios-over-tcp-ip-with-windows.htm NetBIOS protocol is enabled] and that a firewall does not block [http://technet.microsoft.com/en-us/library/cc940063.aspx ports] used by the NetBIOS protocol.<br />
}}<br />
<br />
=== Mounting a partition inside a raw disk image ===<br />
<br />
When the virtual machine is not running, it is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices. This does not work with disk images in special formats, such as qcow2, although those can be mounted using {{ic|qemu-nbd}}.<br />
<br />
{{Warning|You must make sure to unmount the partitions before running the virtual machine again. Otherwise, data corruption is very likely to occur.}}<br />
<br />
==== With manually specifying byte offset ====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
==== With loop module autodetecting partitions ====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* [[Kernel_modules#Manual_module_handling|Unload]] the {{ic|loop}} kernel module, and load it with the {{ic|1=max_part=15}} parameter set. Additionally, the maximum number of loop devices can be controlled with the {{ic|max_loop}} parameter.<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
<br />
# losetup -f -P ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
==== With kpartx ====<br />
<br />
'''kpartx''' from the {{AUR|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a ''disk_image''<br />
<br />
This will setup the loopback device and create the necessary partition(s) device(s) in {{ic|/dev/mapper/}}.<br />
<br />
=== Mounting a partition inside a qcow2 image ===<br />
<br />
You may mount a partition inside a qcow2 image using {{ic|qemu-nbd}}. See [http://en.wikibooks.org/wiki/QEMU/Images#Mounting_an_image_on_the_host Wikibooks].<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you need to change the owner of the partition's device file to that user.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[kernel]] and [[initramfs|initrd]] manually, or by simulating a disk with a MBR by using linear [[RAID]].<br />
<br />
==== By specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
<br />
{{Note|In this example, it is the '''host's''' images that are being used, not the guest's. If you wish to use the guest's images, either mount {{ic|/dev/sda3}} read-only (to protect the file system from the host) and specify the {{ic|/full/path/to/images}} or use some kexec hackery in the guest to reload the guest's kernel (extends boot time). }}<br />
<br />
$ qemu-system-i386 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
When there are multiple [[kernel parameters]] to be passed to the {{ic|-append}} option, they need to be quoted using single or double quotes. For example:<br />
<br />
... -append 'root=/dev/sda1 console=ttyS0'<br />
<br />
==== Simulate virtual disk with MBR using linear RAID ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate a MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
You can do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: the trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image.<br />
<br />
Suppose you have a plain, unmounted {{ic|/dev/hdaN}} partition with some file system on it you wish to make part of a QEMU disk image. First, you create some small file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hdaN}} disk image using software RAID:<br />
<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kilobyte-roundable offsets (such as 31.5 KB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu.<br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image:<br />
<br />
$ qemu-system-i386 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
== Networking ==<br />
<br />
{{Poor writing|Network topologies (sections [[#Host-only networking]], [[#Internal networking]] and info spread out across other sections) should not be described alongside the various virtual interfaces implementations, such as [[#User-mode networking]], [[#Tap networking with QEMU]], [[#Networking with VDE2]].}}<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [http://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
<ol><br />
<li>Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
</li><br />
<li>Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
{{bc|1=<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-i386 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
}}<br />
<br />
</li><br />
<li>Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|<nowiki><br />
#!/usr/bin/env python<br />
<br />
import sys<br />
import zlib<br />
<br />
if len(sys.argv) != 2:<br />
print("usage: %s <VM Name>" % sys.argv[0])<br />
sys.exit(1)<br />
<br />
crc = zlib.crc32(sys.argv[1].encode("utf-8")) & 0xffffffff<br />
crc = str(hex(crc))[2:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))<br />
</nowiki>}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-i386 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
</li><br />
</ol><br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU.<br />
<br />
{{warning|This only works with the TCP and UDP protocols, so ICMP, including {{ic|ping}}, will not work. Do not use {{ic|ping}} to test network connectivity.}}<br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, redirecting host ports to the guest (for example to allow SSH connections to the guest) or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the [[Firewalls|precautions]] you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, a better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
As indicated in the user-mode networking section, tap devices offer higher networking performance than user-mode. If the guest OS supports virtio network driver, then the networking performance will be increased considerably as well. Supposing the use of the tap0 device, that the virtio driver is used on the guest, and that no scripts are used to help start/stop networking, next is part of the qemu command one should see:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no<br />
<br />
But if already using a tap device with virtio networking driver, one can even boost the networking performance by enabling vhost, like:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no,vhost=on<br />
<br />
See http://www.linux-kvm.com/content/how-maximize-virtio-net-performance-vhost-net for more information.<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet sharing#Enable NAT]] page.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface&#61;br0 --bind-interfaces --dhcp-range&#61;172.20.0.2,172.20.255.254<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
By default iptables would drop packets in the bridge network. You may need to use such iptables rule to allow packets in a bridged network:<br />
<br />
# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
{{Note|This method is available since QEMU 1.1, see http://wiki.qemu.org/Features/HelperNetworking.}}<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|See [[Network bridge]] for information on creating bridge.}}<br />
<br />
First, copy {{ic|/etc/qemu/bridge.conf.sample}} to {{ic|/etc/qemu/bridge.conf}}. Now modify {{ic|/etc/qemu/bridge.conf}} to contain the names of all bridges to be used by QEMU:<br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''bridge0''<br />
allow ''bridge1''<br />
...}}<br />
<br />
Now start the VM. The most basic usage would be:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' ''[...]''<br />
<br />
With multiple taps, the most basic usage requires specifying the VLAN for all additional NICs:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' -net nic,vlan=1 -net bridge,vlan=1,br=''bridge1'' ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [http://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it. See http://en.gentoo-wiki.com/wiki/KVM#Networking_2{{Dead link|2013|07|23}}.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
# sysctl net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Now create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=$(whoami)<br />
<br />
# Get name of newly created TAP device; see https://bbs.archlinux.org/viewtopic.php?pid=1285079#p1285079<br />
precreationg=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
sudo /usr/bin/ip tuntap add user $USERID mode tap<br />
postcreation=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
IFACE=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
<br />
# This line creates a random MAC address. The downside is the DHCP server will assign a different IP address each time<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
# Instead, uncomment and edit this line to set a static MAC address. The benefit is that the DHCP server will assign the same IP address.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu-system-i386 -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo ip link set dev $IFACE down &> /dev/null<br />
sudo ip tuntap del $IFACE mode tap &> /dev/null<br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
$ run-qemu -hda ''myvm.img'' -m 512 -vga std<br />
<br />
* It is recommended for performance and security reasons to disable the [http://ebtables.netfilter.org/documentation/bridge-nf.html firewall on the bridge]:<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [http://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Loading]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Network sharing between physical device and a Tap device through iptables ====<br />
<br />
{{Merge|Internet_sharing|Duplication, not specific to QEMU.}}<br />
<br />
Bridged networking works fine between a wired interface (Eg. eth0), and it's easy to setup. However if the host gets connected to the network through a wireless device, then bridging is not possible.<br />
<br />
See https://wiki.archlinux.org/index.php/Network_bridge#Wireless_interface_on_a_bridge as a reference.<br />
<br />
One way to overcome that is to setup a tap device with a static IP, making linux automatically handle the routing for it, and then forward traffic between the tap interface and the device connected to the network through iptables rules.<br />
<br />
See https://wiki.archlinux.org/index.php/Internet_sharing as a reference.<br />
<br />
There you can find what's needed to share the network between devices, included tap and tun ones. The following just hints further on some of the host configurations required. As indicated in the reference above, the client needs to be configured for a static IP, using the IP assigned to the tap interface as the gateway. The caveat is that the DNS servers on the client might need to be manually edited if they change when changing from one host device connected to the network to another.<br />
<br />
To allow IP forwarding on every boot, one need to add the following lines to sysctl configuration file inside /etc/sysctl.d:<br />
<br />
net.ipv4.ip_forward = 1<br />
net.ipv6.conf.default.forwarding = 1<br />
net.ipv6.conf.all.forwarding = 1<br />
<br />
The iptables rules can look like:<br />
<br />
# Forwarding from/to outside<br />
iptables -A FORWARD -i ${INT} -o ${EXT_0} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_1} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_2} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_0} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_1} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_2} -o ${INT} -j ACCEPT<br />
# NAT/Masquerade (network address translation)<br />
iptables -t nat -A POSTROUTING -o ${EXT_0} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_1} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_2} -j MASQUERADE<br />
<br />
The prior supposes there are 3 devices connected to the network sharing traffic with one internal device, where for example:<br />
<br />
INT=tap0<br />
EXT_0=eth0<br />
EXT_1=wlan0<br />
EXT_2=tun0<br />
<br />
The prior shows a forwarding that would allow sharing wired and wireless connections with the tap device.<br />
<br />
The forwarding rules shown are stateless, and for pure forwarding. One could think of restricting specific traffic, putting a firewall in place to protect the guest and others. However those would decrease the networking performance, while a simple bridge doesn't include any of that.<br />
<br />
Bonus: Whether the connection is wired or wireless, if one gets connected through VPN to a remote site with a tun device, supposing the tun device opened for that connection is tun0, and the prior iptables rules are applied, then the remote connection gets also shared with the guest. This avoids the need for the guest to also open a VPN connection. Again, as the guest networking needs to be static, then if connecting the host remotely this way, one most probably will need to edit the DNS servers on the guest.<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [http://wiki.virtualsquare.org/wiki/index.php/Main_Page the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-i386 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep -f vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be executable<br />
<br />
# chmod u+x /etc/systemd/scripts/qemu-network-env<br />
<br />
You can [[start]] {{ic|qemu-network-env.service}} as usual.<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
<br />
=== Host-only Networking with ARM virtual machines (VM/Guests) ===<br />
<br />
{{Deletion|The only part specific to ARM is running {{ic|qemu-system-arm}} instead of {{ic|qemu-system-x86_64}}. On Arch, this is provided by {{Pkg|qemu-arch-extra}}, but this was not tested on Arch (refers to ''dpkg''). In general, written like a blog post with no explanation of the steps, duplicates previous sections.}}<br />
<br />
This is a concise method for setting up host only networking for ARM guests. ie. the vm and host can ssh, ping each other. Interactions between<br />
multiple guests was not tested. The method is slightly different for i386 guests and that method is not described here but in the attached<br />
notes here.<br />
<br />
==== Components Needed ====<br />
<br />
These are the components used for this method:<br />
<br />
* qemu - I used the regular git version of qemu instead of the one provided by pacman since it did not have arm support prebuilt. The build method is detailed in the github link.<br />
* dnsmasq<br />
* bridge-utils<br />
<br />
==== Procedure ====<br />
<br />
Start the bridge/tap and dhcp server for the host only network. Afterwards the interfaces will be down. When the vm is started these interfaces will be started. Possibly netctl's bridge example interface could do this but it was simpler to just write a script. This script will need to be run using sudo. Lastly, the ip address chosen 172.16.0.1 was chosen since it did not conflict with any network currently in use.<br />
<br />
{{hc|do_network.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Do this to setup host only networking<br />
brctl addbr br0<br />
ip addr add 172.16.0.1/24 broadcast 172.16.0.255 dev br0<br />
ip link set br0 up<br />
ip tuntap add dev tap0 mode tap<br />
ip link set tap0 up promisc on<br />
brctl addif br0 tap0<br />
ip link set tap0 up<br />
dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.16.0.10,172.16.0.20<br />
</nowiki>}}<br />
<br />
Once the tap/bridge is setup start the arm vm like so:<br />
<br />
{{hc|doit.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Do this to setup host only networking<br />
brctl addbr br0<br />
ip addr add 172.16.0.1/24 broadcast 172.16.0.255 dev br0<br />
ip link set br0 up<br />
ip tuntap add dev tap0 mode tap<br />
ip link set tap0 up promisc on<br />
brctl addif br0 tap0<br />
ip link set tap0 up<br />
dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.16.0.10,172.16.0.20<br />
</nowiki>}}<br />
<br />
{{hc|do_network.sh|<nowiki><br />
#!/bin/bash<br />
<br />
sudo qemu-system-arm -M vexpress-a9 -kernel vmlinuz-3.2.0-4-vexpress \<br />
-initrd initrd.img-3.2.0-4-vexpress -append "root=/dev/mmcblk0p2" \<br />
-drive if=sd,cache=unsafe,file=hda.img \<br />
-net nic,vlan=0 -net tap,vlan=0,ifname=tap0,script=no<br />
</nowiki>}}<br />
<br />
==== More Details ====<br />
<br />
More details on how to setup a virtual machine, building qemu, using a similar method for i386, credits to the work this is based on and more are found here <br />
http://github.com/netskink/carolinacon12<br />
<br />
== Graphics ==<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|cirrus}}, {{ic|vmware}}, {{ic|qxl}}, and {{ic|none}}.<br />
<br />
=== cirrus ===<br />
<br />
The cirrus graphical adapter was the default [http://wiki.qemu.org/ChangeLog/2.2#VGA before 2.2]. It [https://www.kraxel.org/blog/2014/10/qemu-using-cirrus-considered-harmful/ should not] be used on modern systems.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels. This is the default since QEMU 2.2.<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. On the guest, install the VMware drivers ({{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests).<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, pass the {{ic|-vga qxl}} option and install drivers in the guest.<br />
<br />
For basic support (similar to {{ic|-vga std}}) in Linux guests, the qxl and bochs_drm kernel modules must be loaded. The xorg modesetting driver (part of {{Pkg|xorg-server}}) can be combined with these drivers. Drivers for other operating systems can be found on the [http://www.spice-space.org/download.html SPICE download page]. Advanced functionality such as multi-monitor support requires [[#Spice support|SPICE]].<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
=== vnc ===<br />
<br />
Given that you used the {{ic|-nographic}} option, you can add the {{ic|-vnc display}} option to have QEMU listen on {{ic|display}} and redirect the VGA display to the VNC session. There is an example of this in the [[#Starting QEMU virtual machines on boot]] section's example configs.<br />
<br />
$ qemu-system-i386 -vga std -nographic -vnc :0<br />
$ gvncviewer :0<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [http://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [http://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} instead of the simple {{Ic|-hd*}} plus {{Ic|1=if=virtio}}:<br />
$ qemu-system-i386 -boot order=c -drive file=''disk_image'',if=virtio<br />
<br />
{{Note|{{Ic|1=-boot order=c}} is absolutely necessary when you want to boot from it. There is no auto-detection as with {{Ic|-hd*}}.}}<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-i386 -net nic,model=virtio<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an (Arch) Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must contain the necessary modules. By default, this is handled by [[mkinitcpio]]'s {{ic|autodetect}} hook. Otherwise use the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}} to include the necessary modules and rebuild the initial ramdisk.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES="virtio virtio_blk virtio_pci virtio_net"}}<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing to disks by [[UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [http://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
{{Note|1=The only (reliable) way to upgrade a Windows 8.1 guest to Windows 10 seems to be to temporarily choose cpu core2duo,nx for the install [http://ubuntuforums.org/showthread.php?t=2289210]. After the install, you may revert to other cpu settings (8/8/2015).}}<br />
<br />
==== Block device drivers ====<br />
<br />
===== New Install of Windows =====<br />
<br />
Windows does not come with the virtio drivers. Therefore, you will need to load them during installation. There are basically two ways to do this: via Floppy Disk or via ISO files. Both images can be downloaded from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
The floppy disk option is difficult because you will need to press F6 (Shift-F6 on newer Windows) at the very beginning of powering on the QEMU. This is difficult since you need time to connect your VNC console window. You can attempt to add a delay to the boot sequence. See {{ic|man qemu-system}} for more details about applying a delay at boot.<br />
<br />
The ISO option to load drivers is the preferred way, but it is available only on Windows Vista and Windows Server 2008 and later. The procedure is to load the image with virtio drivers in an additional cdrom device along with the primary disk device and Windows installer:<br />
<br />
$ qemu-system-i386 ... \<br />
-drive file=''/path/to/primary/disk.img'',index=0,media=disk,if=virtio \<br />
-drive file=''/path/to/installer.iso'',index=2,media=cdrom \<br />
-drive file=''/path/to/virtio.iso'',index=3,media=cdrom \<br />
...<br />
<br />
During the installation, the Windows installer will ask you for your Product key and perform some additional checks. When it gets to the "Where do you want to install Windows?" screen, it will give a warning that no disks are found. Follow the example instructions below (based on Windows Server 2012 R2 with Update).<br />
<br />
* Select the option {{ic|Load Drivers}}.<br />
* Uncheck the box for "Hide drivers that aren't compatible with this computer's hardware".<br />
* Click the Browse button and open the CDROM for the virtio iso, usually named "virtio-win-XX".<br />
* Now browse to {{ic|E:\viostor\[your-os]\amd64}}, select it, and press OK.<br />
* Click Next<br />
<br />
You should now see your virtio disk(s) listed here, ready to be selected, formatted and installed to.<br />
<br />
===== Change Existing Windows VM to use virtio =====<br />
Modifying an existing Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
Now you need to create a new disk image, which fill force Windows to search for the driver. For example:<br />
<br />
$ qemu-img create -f qcow2 ''fake.qcow2'' 1G<br />
<br />
Run the original Windows guest (with the boot disk still in IDE mode) with the fake disk (in virtio mode) and a CD-ROM with the driver.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=ide -drive file=''fake.qcow2'',if=virtio -cdrom virtio-win-0.1-81.iso<br />
<br />
Windows will detect the fake disk and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
When the installation is successful, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio<br />
<br />
{{Note|If you encounter the Blue Screen of Death, make sure you did not forget the {{ic|-m}} parameter, and that you do not boot with virtio instead of ide for the system drive before drivers are installed.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-net}} argument as explained above.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio -net nic,model=virtio -cdrom virtio-win-0.1-74.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|<nowiki><br />
virtio_loader="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
</nowiki>}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
{{bc|<nowiki><br />
sed -i bak "s/ada/vtbd/g" /etc/fstab<br />
</nowiki>}}<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured through the virt-manager GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== Custom script ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|<nowiki><br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="type=system-x86_64" "haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/env qemu-${type} -name %i -nographic $args<br />
ExecStop=/bin/sh -c ${haltcmd}<br />
TimeoutStopSec=30<br />
KillMode=none<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|According to {{ic|systemd.service(5)}} and {{ic|systemd.kill(5)}} man pages it is necessary to use the {{ic|1=KillMode=none}} option. Otherwise the main qemu process will be killed immediately after the {{ic|ExecStop}} command quits (it simply echoes one string) and your quest system will not be able to shutdown correctly.}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the following variables set:<br />
<br />
; type<br />
: QEMU binary to call. If specified, will be prepended with {{ic|/usr/bin/qemu-}} and that binary will be used to start the VM. I.e. you can boot e.g. {{ic|qemu-system-arm}} images with {{ic|1=type="system-arm"}}.<br />
; args<br />
: QEMU command line to start with. Will always be prepended with {{ic|-name ${vm} -nographic}}.<br />
; haltcmd<br />
: Command to shut down a VM safely. I am using {{ic|-monitor telnet:..}} and power off my VMs via ACPI by sending {{ic|system_powerdown}} to monitor. You can use SSH or some other ways.<br />
<br />
Example configs:<br />
<br />
{{hc|/etc/conf.d/qemu.d/one|<nowiki><br />
type="system-x86_64"<br />
<br />
args="-enable-kvm -m 512 -hda /dev/mapper/vg0-vm1 -net nic,macaddr=DE:AD:BE:EF:E0:00 \<br />
-net tap,ifname=tap0 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7100" # or netcat/ncat<br />
<br />
# You can use other ways to shut down your VM correctly<br />
#haltcmd="ssh powermanager@vm1 sudo poweroff"<br />
</nowiki>}}<br />
<br />
{{hc|/etc/conf.d/qemu.d/two|<nowiki><br />
args="-enable-kvm -m 512 -hda /srv/kvm/vm2.img -net nic,macaddr=DE:AD:BE:EF:E0:01 \<br />
-net tap,ifname=tap1 -serial telnet:localhost:7001,server,nowait,nodelay \<br />
-monitor telnet:localhost:7101,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7101"<br />
</nowiki>}}<br />
<br />
To set which virtual machines will start on boot-up, use<br />
<br />
# systemctl enable qemu@''vm_name''<br />
# systemctl disable qemu@''vm_name''<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the option {{ic|-usbdevice tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
<br />
$ qemu-system-i386 -hda ''disk_image'' -m 512 -vga std -usbdevice tablet<br />
<br />
If that doesn't work, try the tip at [[#Mouse cursor is jittery or erratic]].<br />
<br />
=== Pass-through host USB device ===<br />
<br />
To access physical USB device connected to host from VM, you can start QEMU with following option:<br />
<br />
$ qemu-system-i386 -usbdevice host:''vendor_id'':''product_id'' ''disk_image''<br />
<br />
You can find {{ic|vendor_id}} and {{ic|product_id}} of your device with {{ic|lsusb}} command.<br />
<br />
{{Note|If you encounter permission errors when running QEMU, see [[Udev#Writing udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
To enable KSM, simply run<br />
<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, you can use [[systemd#Temporary files|systemd's temporary files]]:<br />
<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://www.kernel.org/doc/Documentation/vm/ksm.txt for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory: {{bc|$ grep . /sys/kernel/mm/ksm/*}}}}<br />
<br />
=== Spice support ===<br />
<br />
{{Poor writing|This section needs much more information and shall be placed under the [[#Graphics]] section .}}<br />
<br />
The [http://spice-space.org/ SPICE project] aims to provide a complete, open-source solution for interaction with virtualized desktop devices. Its main focus is to provide high-quality remote access to QEMU virtual machines.<br />
<br />
The official {{Pkg|qemu}} package is built with SPICE support.<br />
<br />
You can start your VM:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing,addr=::1<br />
<br />
{{Out of date|1=''spicec'' has been removed in {{Pkg|spice}}-0.12.6 [http://cgit.freedesktop.org/spice/spice/tree/NEWS?id=f0aeb9db000a34a46b51c5d95229171ff1eee307#n3].}}<br />
<br />
Then connect with a spice client<br />
<br />
$ spicec -h 127.0.0.1 -p 5930<br />
<br />
{{Tip|<br />
* The key combination to escape mouse and keyboard grab can be configured for {{ic|spicec}}, the default is {{ic|Shift+F12}}: {{bc|1=$ spicec --hotkeys release-cursor=ctrl+alt}}<br />
* To disable mouse and keyboard grabbing for {{ic|spicec}} (useful to allow your window manager shortcuts to work), set {{ic|1=SPICE_NOGRAB=1}}.<br />
* {{Pkg|virt-manager}} has a SPICE client built in.<br />
* {{Pkg|spice-gtk3}} provides another client for demoing purposes. Example usage: {{ic|spicy -h 127.0.0.1 -p 5930}}.<br />
}}<br />
<br />
==== SPICE Guest Additions ====<br />
For improved support for multiple monitors, clipboard sharing and more, you have to install additional packages in your ''guest'':<br />
* {{AUR|spice-vdagent}}: for [http://people.freedesktop.org/~teuf/spice-doc/html/ch02s05.html Agent] support. Do not forget to enable the {{ic|spice-vdagentd}} service.<br />
* {{AUR|xf86-video-qxl}}: for the QXL display driver.<br />
* For other operating systems, see http://people.freedesktop.org/~teuf/spice-doc/html/ch04.html<br />
<br />
In addition to the {{ic|-spice}} option, these options are also needed:<br />
<br />
-device virtio-serial \<br />
-chardev spicevmc,id=vdagent,name=vdagent \<br />
-device virtserialport,chardev=vdagent,name=com.redhat.spice.0<br />
<br />
The spicec and spicy program are intended for testing purposes, to enable additional monitors you have to install the {{Pkg|virtviewer}} package. Then connect with the VM using:<br />
<br />
remote-viewer spice://localhost:5930<br />
<br />
==== Multi-monitor support ====<br />
The Linux QXL driver supports four heads (virtual screens) by default. This can be changed via the {{ic|1=qxl.heads=N}} kernel parameter.<br />
<br />
The default VGA memory size for QXL devices is 16M (VRAM size is 64M). This is not sufficient if you would like to enable two 1920x1200 monitors since that requires 2 × 1920 × 4 (color depth) × 1200 = 17.6 MiB VGA memory. This can be changed by replacing {{ic|-vga qxl}} by {{ic|<nowiki>-vga none -device qxl-vga,vgamem_mb=32</nowiki>}}. If you ever increase vgamem_mb beyond 64M, then you also have to increase the {{ic|vram_size_mb}} option.<br />
<br />
=== Copy and paste ===<br />
<br />
To have copy and paste between the host and the guest you need to enable the spice agent communication channel. It requires to add a virtio-serial device to the guest, and open a port for the spice vdagent. It is also required to install the spice vdagent in guest ({{AUR|spice-vdagent}} for Arch guests, [http://www.spice-space.org/download.html Windows guest tools] for Windows guests). Make sure the agent is running (and for future, started automatically).<br />
<br />
Start QEMU with the following options:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The {{ic|-device virtio-serial-pci}} option adds the virtio-serial device, {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in that device and {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port.<br />
<br />
It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 10.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-i386 -nographic -net user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either rdesktop or freerdp to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|~/.bashrc}} file.<br />
<br />
=== No visible Cursor ===<br />
<br />
Add {{ic|-show-cursor}} to QEMU's options to see a mouse cursor.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps}}.<br />
<br />
$ qemu-system-i386 -k ''keymap'' ''disk_image''<br />
<br />
=== Virtual machine runs too slowly ===<br />
<br />
There are a number of techniques that you can use to improve the performance if your virtual machine. For example:<br />
<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU. If you do not do this, it may be trying to emulate a more generic CPU.<br />
* If the host machine has multiple CPUs, assign the guest more CPUs using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* Use KVM if possible: add {{ic|1=-machine type=pc,accel=kvm}} to the QEMU start command you use.<br />
* If supported by drivers in the guest operating system, use [http://wiki.libvirt.org/page/Virtio virtio] for network and/or block devices. For example:<br />
$ qemu-system-i386 -net nic,model=virtio -net tap,if=tap0,script=no -drive file=''disk_image'',media=disk,if=virtio<br />
* Use TAP devices instead of user-mode networking. See [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, disable the cache:<br />
$ qemu-system-i386 -drive file=''disk_image'',if=virtio,cache=none<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]:<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU with the {{ic|-balloon virtio}} option.<br />
<br />
See http://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
=== Guest display stretches on window resize ===<br />
<br />
To restore default window size, press {{ic|Ctrl+Alt+u}}.<br />
<br />
=== ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy ===<br />
<br />
If an error message like this is printed when starting QEMU with {{ic|-enable-kvm}} option:<br />
<br />
ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy<br />
failed to initialize KVM: Device or resource busy<br />
<br />
that means another [[hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<br />
<br />
=== libgfapi error message ===<br />
<br />
The error message displayed at startup:<br />
<br />
Failed to open module: libgfapi.so.0: cannot open shared object file: No such file or directory<br />
<br />
is not a problem, it just means that you are lacking the optional GlusterFS dependency.<br />
<br />
=== Kernel panic on LIVE-environments===<br />
<br />
If you start a live-environment (or better: booting a system) you may encounter this:<br />
<br />
[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)<br />
<br />
or some other boot hindering process (e.g. can't unpack initramfs, cant start service foo).<br />
Try starting the VM with the {{ic|-m VALUE}} switch and an appropriate amount of RAM, if the ram is to low you will probably encounter similar issues as above/without the memory-switch.<br />
<br />
<br />
== See also ==<br />
<br />
* [http://qemu.org Official QEMU website]<br />
* [http://www.linux-kvm.org Official KVM website]<br />
* [http://qemu.weilnetz.de/qemu-doc.html QEMU Emulator User Documentation]<br />
* [https://en.wikibooks.org/wiki/QEMU QEMU Wikibook]<br />
* [http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU] by AlienBOB (last updated in 2008)<br />
* [http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army] by Falconindy<br />
* [http://git.qemu.org/?p=qemu.git;a=tree;f=docs Lastest docs]<br />
* [http://qemu.weilnetz.de/ QEMU on Windows]<br />
* [http://en.wikipedia.org/wiki/Qemu Wikipedia]<br />
* [https://wiki.debian.org/QEMU QEMU - Debian Wiki]<br />
* [https://people.gnome.org/~markmc/qemu-networking.html QEMU Networking on gnome.org]<br />
* [http://bsdwiki.reedmedia.net/wiki/networking_qemu_virtual_bsd_systems.html Networking QEMU Virtual BSD Systems]<br />
* [https://www.gnu.org/software/hurd/hurd/running/qemu.html QEMU on gnu.org]<br />
* [https://wiki.freebsd.org/qemu QEMU on FreeBSD as host]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=QEMU&diff=413842QEMU2015-12-30T13:03:00Z<p>Netskink: /* Procedure */</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Hypervisors]]<br />
[[de:Qemu]]<br />
[[es:QEMU]]<br />
[[fr:Qemu]]<br />
[[ja:QEMU]]<br />
[[zh-CN:QEMU]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
<br />
From the [http://wiki.qemu.org/Main_Page QEMU about page]:<br />
:''QEMU is a generic and open source machine emulator and virtualizer.''<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installing QEMU ==<br />
<br />
{{Expansion|See {{Bug|45977}}.}}<br />
<br />
[[Install]] the {{Pkg|qemu}} package.<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s). However, there are several GUI front-ends for QEMU:<br />
<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
* {{AUR|aqemu}}<br />
<br />
Additional front-ends with QEMU support are available for [[libvirt]].<br />
<br />
== Creating new virtualized system ==<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Tip|See the [https://en.wikibooks.org/wiki/QEMU/Images QEMU Wikibook] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk.<br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. Using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GB image in the ''raw'' format:<br />
<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''qcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
{{Warning|If you store the hard disk images on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the directory before creating any images.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
<br />
$ qemu-img create -o backing_file=''img1.raw'',backing_fmt=''raw'' -f ''qcow2'' ''img1.cow''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
<br />
$ qemu-system-i386 ''img1.cow''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required.<br />
<br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like:<br />
<br />
$ qemu-img rebase -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked:<br />
<br />
$ qemu-img rebase -u -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the operating system installed on it unbootable. For full explanation and workaround see [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages].}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example, to increase image space by 10 GB, run:<br />
<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
After enlarging the disk image, you must use file system and partitioning tools inside the virtual machine to actually begin using the new space. When shrinking a disk image, you must '''first reduce the allocated file systems and partition sizes''' using the file system and partitioning tools inside the virtual machine and then shrink the disk image accordingly, otherwise shrinking the disk image will result in data loss!<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly.<br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso''}}}}<br />
<br />
=== Installing the operating system===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 guests, to install from a bootable ISO file as CD-ROM:<br />
<br />
$ qemu-system-i386 -cdrom ''iso_image'' -boot order=d ''qemu_image''<br />
<br />
See {{ic|qemu(1)}} for information about loading other media types, such as floppy or disk images, or physical drives.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Tip|<br />
* By default only 128 MB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512M}} or {{ic|-m 2G}}.<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on guest's architecture) are used to run the virtualized guest. The usage is:<br />
<br />
$ qemu-system-i386 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{ic|qemu(1)}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM must be supported by your processor and kernel, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-enable-kvm}} to the additional start options. To check if KVM is enabled for a running VM, enter the QEMU [https://en.wikibooks.org/wiki/QEMU/Monitor Monitor] using {{ic|Ctrl+Alt+Shift+2}}, and type {{ic|info kvm}}.<br />
<br />
{{Note|<br />
* If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.<br />
* KVM needs to be enabled in order to start Windows 7 and Windows 8 properly without a ''blue screen''.<br />
}}<br />
<br />
== Moving data between host and guest OS ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[SMB]] or [[NFS]], or you can access the host's HTTP server, etc.<br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] with an automatically generated {{ic|smb.conf}} file located at {{ic|/tmp/qemu-smb.''pid''-0/smb.conf}} and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and this is not necessarily very useful since the guest can also access the normal [[Samba]] service on the host if you have set up shares on it.<br />
<br />
To enable this feature, start QEMU with a command like:<br />
<br />
$ qemu-system-i386 ''disk_image'' -net nic -net user,smb=''shared_dir_path''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
{{Note|<br />
* If you are using sharing options multiple times like {{ic|1=-net user,smb=''shared_dir_path1'' -net user,smb=''shared_dir_path2''}} or {{ic|1=-net user,smb=''shared_dir_path1'',smb=''shared_dir_path2''}} then it will share only the last defined one.<br />
* If you cannot access the shared folder and the guest system is Windows, check that the [http://ecross.mvps.org/howto/enable-netbios-over-tcp-ip-with-windows.htm NetBIOS protocol is enabled] and that a firewall does not block [http://technet.microsoft.com/en-us/library/cc940063.aspx ports] used by the NetBIOS protocol.<br />
}}<br />
<br />
=== Mounting a partition inside a raw disk image ===<br />
<br />
When the virtual machine is not running, it is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices. This does not work with disk images in special formats, such as qcow2, although those can be mounted using {{ic|qemu-nbd}}.<br />
<br />
{{Warning|You must make sure to unmount the partitions before running the virtual machine again. Otherwise, data corruption is very likely to occur.}}<br />
<br />
==== With manually specifying byte offset ====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
==== With loop module autodetecting partitions ====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* [[Kernel_modules#Manual_module_handling|Unload]] the {{ic|loop}} kernel module, and load it with the {{ic|1=max_part=15}} parameter set. Additionally, the maximum number of loop devices can be controlled with the {{ic|max_loop}} parameter.<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
<br />
# losetup -f -P ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
==== With kpartx ====<br />
<br />
'''kpartx''' from the {{AUR|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a ''disk_image''<br />
<br />
This will setup the loopback device and create the necessary partition(s) device(s) in {{ic|/dev/mapper/}}.<br />
<br />
=== Mounting a partition inside a qcow2 image ===<br />
<br />
You may mount a partition inside a qcow2 image using {{ic|qemu-nbd}}. See [http://en.wikibooks.org/wiki/QEMU/Images#Mounting_an_image_on_the_host Wikibooks].<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you need to change the owner of the partition's device file to that user.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[kernel]] and [[initramfs|initrd]] manually, or by simulating a disk with a MBR by using linear [[RAID]].<br />
<br />
==== By specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
<br />
{{Note|In this example, it is the '''host's''' images that are being used, not the guest's. If you wish to use the guest's images, either mount {{ic|/dev/sda3}} read-only (to protect the file system from the host) and specify the {{ic|/full/path/to/images}} or use some kexec hackery in the guest to reload the guest's kernel (extends boot time). }}<br />
<br />
$ qemu-system-i386 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
When there are multiple [[kernel parameters]] to be passed to the {{ic|-append}} option, they need to be quoted using single or double quotes. For example:<br />
<br />
... -append 'root=/dev/sda1 console=ttyS0'<br />
<br />
==== Simulate virtual disk with MBR using linear RAID ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate a MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
You can do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: the trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image.<br />
<br />
Suppose you have a plain, unmounted {{ic|/dev/hdaN}} partition with some file system on it you wish to make part of a QEMU disk image. First, you create some small file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hdaN}} disk image using software RAID:<br />
<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kilobyte-roundable offsets (such as 31.5 KB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu.<br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image:<br />
<br />
$ qemu-system-i386 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
== Networking ==<br />
<br />
{{Poor writing|Network topologies (sections [[#Host-only networking]], [[#Internal networking]] and info spread out across other sections) should not be described alongside the various virtual interfaces implementations, such as [[#User-mode networking]], [[#Tap networking with QEMU]], [[#Networking with VDE2]].}}<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [http://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
<ol><br />
<li>Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
</li><br />
<li>Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
{{bc|1=<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-i386 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
}}<br />
<br />
</li><br />
<li>Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|<nowiki><br />
#!/usr/bin/env python<br />
<br />
import sys<br />
import zlib<br />
<br />
if len(sys.argv) != 2:<br />
print("usage: %s <VM Name>" % sys.argv[0])<br />
sys.exit(1)<br />
<br />
crc = zlib.crc32(sys.argv[1].encode("utf-8")) & 0xffffffff<br />
crc = str(hex(crc))[2:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))<br />
</nowiki>}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-i386 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
</li><br />
</ol><br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU.<br />
<br />
{{warning|This only works with the TCP and UDP protocols, so ICMP, including {{ic|ping}}, will not work. Do not use {{ic|ping}} to test network connectivity.}}<br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, redirecting host ports to the guest (for example to allow SSH connections to the guest) or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the [[Firewalls|precautions]] you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, a better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
As indicated in the user-mode networking section, tap devices offer higher networking performance than user-mode. If the guest OS supports virtio network driver, then the networking performance will be increased considerably as well. Supposing the use of the tap0 device, that the virtio driver is used on the guest, and that no scripts are used to help start/stop networking, next is part of the qemu command one should see:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no<br />
<br />
But if already using a tap device with virtio networking driver, one can even boost the networking performance by enabling vhost, like:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no,vhost=on<br />
<br />
See http://www.linux-kvm.com/content/how-maximize-virtio-net-performance-vhost-net for more information.<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet sharing#Enable NAT]] page.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface&#61;br0 --bind-interfaces --dhcp-range&#61;172.20.0.2,172.20.255.254<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
By default iptables would drop packets in the bridge network. You may need to use such iptables rule to allow packets in a bridged network:<br />
<br />
# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
{{Note|This method is available since QEMU 1.1, see http://wiki.qemu.org/Features/HelperNetworking.}}<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|See [[Network bridge]] for information on creating bridge.}}<br />
<br />
First, copy {{ic|/etc/qemu/bridge.conf.sample}} to {{ic|/etc/qemu/bridge.conf}}. Now modify {{ic|/etc/qemu/bridge.conf}} to contain the names of all bridges to be used by QEMU:<br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''bridge0''<br />
allow ''bridge1''<br />
...}}<br />
<br />
Now start the VM. The most basic usage would be:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' ''[...]''<br />
<br />
With multiple taps, the most basic usage requires specifying the VLAN for all additional NICs:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' -net nic,vlan=1 -net bridge,vlan=1,br=''bridge1'' ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [http://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it. See http://en.gentoo-wiki.com/wiki/KVM#Networking_2{{Dead link|2013|07|23}}.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
# sysctl net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Now create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=$(whoami)<br />
<br />
# Get name of newly created TAP device; see https://bbs.archlinux.org/viewtopic.php?pid=1285079#p1285079<br />
precreationg=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
sudo /usr/bin/ip tuntap add user $USERID mode tap<br />
postcreation=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
IFACE=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
<br />
# This line creates a random MAC address. The downside is the DHCP server will assign a different IP address each time<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
# Instead, uncomment and edit this line to set a static MAC address. The benefit is that the DHCP server will assign the same IP address.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu-system-i386 -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo ip link set dev $IFACE down &> /dev/null<br />
sudo ip tuntap del $IFACE mode tap &> /dev/null<br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
$ run-qemu -hda ''myvm.img'' -m 512 -vga std<br />
<br />
* It is recommended for performance and security reasons to disable the [http://ebtables.netfilter.org/documentation/bridge-nf.html firewall on the bridge]:<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [http://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Loading]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Network sharing between physical device and a Tap device through iptables ====<br />
<br />
{{Merge|Internet_sharing|Duplication, not specific to QEMU.}}<br />
<br />
Bridged networking works fine between a wired interface (Eg. eth0), and it's easy to setup. However if the host gets connected to the network through a wireless device, then bridging is not possible.<br />
<br />
See https://wiki.archlinux.org/index.php/Network_bridge#Wireless_interface_on_a_bridge as a reference.<br />
<br />
One way to overcome that is to setup a tap device with a static IP, making linux automatically handle the routing for it, and then forward traffic between the tap interface and the device connected to the network through iptables rules.<br />
<br />
See https://wiki.archlinux.org/index.php/Internet_sharing as a reference.<br />
<br />
There you can find what's needed to share the network between devices, included tap and tun ones. The following just hints further on some of the host configurations required. As indicated in the reference above, the client needs to be configured for a static IP, using the IP assigned to the tap interface as the gateway. The caveat is that the DNS servers on the client might need to be manually edited if they change when changing from one host device connected to the network to another.<br />
<br />
To allow IP forwarding on every boot, one need to add the following lines to sysctl configuration file inside /etc/sysctl.d:<br />
<br />
net.ipv4.ip_forward = 1<br />
net.ipv6.conf.default.forwarding = 1<br />
net.ipv6.conf.all.forwarding = 1<br />
<br />
The iptables rules can look like:<br />
<br />
# Forwarding from/to outside<br />
iptables -A FORWARD -i ${INT} -o ${EXT_0} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_1} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_2} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_0} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_1} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_2} -o ${INT} -j ACCEPT<br />
# NAT/Masquerade (network address translation)<br />
iptables -t nat -A POSTROUTING -o ${EXT_0} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_1} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_2} -j MASQUERADE<br />
<br />
The prior supposes there are 3 devices connected to the network sharing traffic with one internal device, where for example:<br />
<br />
INT=tap0<br />
EXT_0=eth0<br />
EXT_1=wlan0<br />
EXT_2=tun0<br />
<br />
The prior shows a forwarding that would allow sharing wired and wireless connections with the tap device.<br />
<br />
The forwarding rules shown are stateless, and for pure forwarding. One could think of restricting specific traffic, putting a firewall in place to protect the guest and others. However those would decrease the networking performance, while a simple bridge doesn't include any of that.<br />
<br />
Bonus: Whether the connection is wired or wireless, if one gets connected through VPN to a remote site with a tun device, supposing the tun device opened for that connection is tun0, and the prior iptables rules are applied, then the remote connection gets also shared with the guest. This avoids the need for the guest to also open a VPN connection. Again, as the guest networking needs to be static, then if connecting the host remotely this way, one most probably will need to edit the DNS servers on the guest.<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [http://wiki.virtualsquare.org/wiki/index.php/Main_Page the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-i386 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep -f vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be executable<br />
<br />
# chmod u+x /etc/systemd/scripts/qemu-network-env<br />
<br />
You can [[start]] {{ic|qemu-network-env.service}} as usual.<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
<br />
=== Host-only Networking with ARM virtual machines (VM/Guests) ===<br />
<br />
This is a concise method for setting up host only networking for ARM guests. ie. the vm and host can ssh, ping each other. Interactions between<br />
multiple guests was not tested. The method is slightly different for i386 guests and that method is not described here but in the attached<br />
notes here.<br />
<br />
==== Components Needed ====<br />
<br />
These are the components used for this method:<br />
<br />
* qemu - I used the regular git version of qemu instead of the one provided by dpkg since it did not have arm support prebuilt. The build method is detailed in the github link.<br />
* dnsmasq<br />
* bridge-utils<br />
<br />
==== Procedure ====<br />
<br />
Start the bridge/tap and dhcp server for the host only network. Afterwards the interfaces will be down. When the vm is started these interfaces will be started. Possibly netctl's bridge example interface could do this but it was simpler to just write a script. This script will need to be run using sudo. Lastly, the ip address chosen 172.16.0.1 was chosen since it did not conflict with any network currently in use.<br />
<br />
{{hc|do_network.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Do this to setup host only networking<br />
brctl addbr br0<br />
ip addr add 172.16.0.1/24 broadcast 172.16.0.255 dev br0<br />
ip link set br0 up<br />
ip tuntap add dev tap0 mode tap<br />
ip link set tap0 up promisc on<br />
brctl addif br0 tap0<br />
ip link set tap0 up<br />
dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.16.0.10,172.16.0.20<br />
</nowiki>}}<br />
<br />
Once the tap/bridge is setup start the arm vm like so:<br />
<br />
{{hc|doit.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Do this to setup host only networking<br />
brctl addbr br0<br />
ip addr add 172.16.0.1/24 broadcast 172.16.0.255 dev br0<br />
ip link set br0 up<br />
ip tuntap add dev tap0 mode tap<br />
ip link set tap0 up promisc on<br />
brctl addif br0 tap0<br />
ip link set tap0 up<br />
dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.16.0.10,172.16.0.20<br />
</nowiki>}}<br />
<br />
{{hc|do_network.sh|<nowiki><br />
#!/bin/bash<br />
<br />
sudo qemu-system-arm -M vexpress-a9 -kernel vmlinuz-3.2.0-4-vexpress \<br />
-initrd initrd.img-3.2.0-4-vexpress -append "root=/dev/mmcblk0p2" \<br />
-drive if=sd,cache=unsafe,file=hda.img \<br />
-net nic,vlan=0 -net tap,vlan=0,ifname=tap0,script=no<br />
</nowiki>}}<br />
<br />
==== More Details ====<br />
<br />
More details on how to setup a virtual machine, building qemu, using a similar method for i386, credits to the work this is based on and more are found here <br />
http://github.com/netskink/carolinacon12<br />
<br />
== Graphics ==<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|cirrus}}, {{ic|vmware}}, {{ic|qxl}}, and {{ic|none}}.<br />
<br />
=== cirrus ===<br />
<br />
The cirrus graphical adapter was the default [http://wiki.qemu.org/ChangeLog/2.2#VGA before 2.2]. It [https://www.kraxel.org/blog/2014/10/qemu-using-cirrus-considered-harmful/ should not] be used on modern systems.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels. This is the default since QEMU 2.2.<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. On the guest, install the VMware drivers ({{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests).<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, pass the {{ic|-vga qxl}} option and install drivers in the guest.<br />
<br />
For basic support (similar to {{ic|-vga std}}) in Linux guests, the qxl and bochs_drm kernel modules must be loaded. The xorg modesetting driver (part of {{Pkg|xorg-server}}) can be combined with these drivers. Drivers for other operating systems can be found on the [http://www.spice-space.org/download.html SPICE download page]. Advanced functionality such as multi-monitor support requires [[#Spice support|SPICE]].<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
=== vnc ===<br />
<br />
Given that you used the {{ic|-nographic}} option, you can add the {{ic|-vnc display}} option to have QEMU listen on {{ic|display}} and redirect the VGA display to the VNC session. There is an example of this in the [[#Starting QEMU virtual machines on boot]] section's example configs.<br />
<br />
$ qemu-system-i386 -vga std -nographic -vnc :0<br />
$ gvncviewer :0<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [http://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [http://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} instead of the simple {{Ic|-hd*}} plus {{Ic|1=if=virtio}}:<br />
$ qemu-system-i386 -boot order=c -drive file=''disk_image'',if=virtio<br />
<br />
{{Note|{{Ic|1=-boot order=c}} is absolutely necessary when you want to boot from it. There is no auto-detection as with {{Ic|-hd*}}.}}<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-i386 -net nic,model=virtio<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an (Arch) Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must contain the necessary modules. By default, this is handled by [[mkinitcpio]]'s {{ic|autodetect}} hook. Otherwise use the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}} to include the necessary modules and rebuild the initial ramdisk.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES="virtio virtio_blk virtio_pci virtio_net"}}<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing to disks by [[UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [http://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
{{Note|1=The only (reliable) way to upgrade a Windows 8.1 guest to Windows 10 seems to be to temporarily choose cpu core2duo,nx for the install [http://ubuntuforums.org/showthread.php?t=2289210]. After the install, you may revert to other cpu settings (8/8/2015).}}<br />
<br />
==== Block device drivers ====<br />
<br />
===== New Install of Windows =====<br />
<br />
Windows does not come with the virtio drivers. Therefore, you will need to load them during installation. There are basically two ways to do this: via Floppy Disk or via ISO files. Both images can be downloaded from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
The floppy disk option is difficult because you will need to press F6 (Shift-F6 on newer Windows) at the very beginning of powering on the QEMU. This is difficult since you need time to connect your VNC console window. You can attempt to add a delay to the boot sequence. See {{ic|man qemu-system}} for more details about applying a delay at boot.<br />
<br />
The ISO option to load drivers is the preferred way, but it is available only on Windows Vista and Windows Server 2008 and later. The procedure is to load the image with virtio drivers in an additional cdrom device along with the primary disk device and Windows installer:<br />
<br />
$ qemu-system-i386 ... \<br />
-drive file=''/path/to/primary/disk.img'',index=0,media=disk,if=virtio \<br />
-drive file=''/path/to/installer.iso'',index=2,media=cdrom \<br />
-drive file=''/path/to/virtio.iso'',index=3,media=cdrom \<br />
...<br />
<br />
During the installation, the Windows installer will ask you for your Product key and perform some additional checks. When it gets to the "Where do you want to install Windows?" screen, it will give a warning that no disks are found. Follow the example instructions below (based on Windows Server 2012 R2 with Update).<br />
<br />
* Select the option {{ic|Load Drivers}}.<br />
* Uncheck the box for "Hide drivers that aren't compatible with this computer's hardware".<br />
* Click the Browse button and open the CDROM for the virtio iso, usually named "virtio-win-XX".<br />
* Now browse to {{ic|E:\viostor\[your-os]\amd64}}, select it, and press OK.<br />
* Click Next<br />
<br />
You should now see your virtio disk(s) listed here, ready to be selected, formatted and installed to.<br />
<br />
===== Change Existing Windows VM to use virtio =====<br />
Modifying an existing Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
Now you need to create a new disk image, which fill force Windows to search for the driver. For example:<br />
<br />
$ qemu-img create -f qcow2 ''fake.qcow2'' 1G<br />
<br />
Run the original Windows guest (with the boot disk still in IDE mode) with the fake disk (in virtio mode) and a CD-ROM with the driver.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=ide -drive file=''fake.qcow2'',if=virtio -cdrom virtio-win-0.1-81.iso<br />
<br />
Windows will detect the fake disk and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
When the installation is successful, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio<br />
<br />
{{Note|If you encounter the Blue Screen of Death, make sure you did not forget the {{ic|-m}} parameter, and that you do not boot with virtio instead of ide for the system drive before drivers are installed.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-net}} argument as explained above.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio -net nic,model=virtio -cdrom virtio-win-0.1-74.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|<nowiki><br />
virtio_loader="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
</nowiki>}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
{{bc|<nowiki><br />
sed -i bak "s/ada/vtbd/g" /etc/fstab<br />
</nowiki>}}<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured through the virt-manager GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== Custom script ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|<nowiki><br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="type=system-x86_64" "haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/env qemu-${type} -name %i -nographic $args<br />
ExecStop=/bin/sh -c ${haltcmd}<br />
TimeoutStopSec=30<br />
KillMode=none<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|According to {{ic|systemd.service(5)}} and {{ic|systemd.kill(5)}} man pages it is necessary to use the {{ic|1=KillMode=none}} option. Otherwise the main qemu process will be killed immediately after the {{ic|ExecStop}} command quits (it simply echoes one string) and your quest system will not be able to shutdown correctly.}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the following variables set:<br />
<br />
; type<br />
: QEMU binary to call. If specified, will be prepended with {{ic|/usr/bin/qemu-}} and that binary will be used to start the VM. I.e. you can boot e.g. {{ic|qemu-system-arm}} images with {{ic|1=type="system-arm"}}.<br />
; args<br />
: QEMU command line to start with. Will always be prepended with {{ic|-name ${vm} -nographic}}.<br />
; haltcmd<br />
: Command to shut down a VM safely. I am using {{ic|-monitor telnet:..}} and power off my VMs via ACPI by sending {{ic|system_powerdown}} to monitor. You can use SSH or some other ways.<br />
<br />
Example configs:<br />
<br />
{{hc|/etc/conf.d/qemu.d/one|<nowiki><br />
type="system-x86_64"<br />
<br />
args="-enable-kvm -m 512 -hda /dev/mapper/vg0-vm1 -net nic,macaddr=DE:AD:BE:EF:E0:00 \<br />
-net tap,ifname=tap0 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7100" # or netcat/ncat<br />
<br />
# You can use other ways to shut down your VM correctly<br />
#haltcmd="ssh powermanager@vm1 sudo poweroff"<br />
</nowiki>}}<br />
<br />
{{hc|/etc/conf.d/qemu.d/two|<nowiki><br />
args="-enable-kvm -m 512 -hda /srv/kvm/vm2.img -net nic,macaddr=DE:AD:BE:EF:E0:01 \<br />
-net tap,ifname=tap1 -serial telnet:localhost:7001,server,nowait,nodelay \<br />
-monitor telnet:localhost:7101,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7101"<br />
</nowiki>}}<br />
<br />
To set which virtual machines will start on boot-up, use<br />
<br />
# systemctl enable qemu@''vm_name''<br />
# systemctl disable qemu@''vm_name''<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the option {{ic|-usbdevice tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
<br />
$ qemu-system-i386 -hda ''disk_image'' -m 512 -vga std -usbdevice tablet<br />
<br />
If that doesn't work, try the tip at [[#Mouse cursor is jittery or erratic]].<br />
<br />
=== Pass-through host USB device ===<br />
<br />
To access physical USB device connected to host from VM, you can start QEMU with following option:<br />
<br />
$ qemu-system-i386 -usbdevice host:''vendor_id'':''product_id'' ''disk_image''<br />
<br />
You can find {{ic|vendor_id}} and {{ic|product_id}} of your device with {{ic|lsusb}} command.<br />
<br />
{{Note|If you encounter permission errors when running QEMU, see [[Udev#Writing udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
To enable KSM, simply run<br />
<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, you can use [[systemd#Temporary files|systemd's temporary files]]:<br />
<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://www.kernel.org/doc/Documentation/vm/ksm.txt for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory: {{bc|$ grep . /sys/kernel/mm/ksm/*}}}}<br />
<br />
=== Spice support ===<br />
<br />
{{Poor writing|This section needs much more information and shall be placed under the [[#Graphics]] section .}}<br />
<br />
The [http://spice-space.org/ SPICE project] aims to provide a complete, open-source solution for interaction with virtualized desktop devices. Its main focus is to provide high-quality remote access to QEMU virtual machines.<br />
<br />
The official {{Pkg|qemu}} package is built with SPICE support.<br />
<br />
You can start your VM:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing,addr=::1<br />
<br />
{{Out of date|1=''spicec'' has been removed in {{Pkg|spice}}-0.12.6 [http://cgit.freedesktop.org/spice/spice/tree/NEWS?id=f0aeb9db000a34a46b51c5d95229171ff1eee307#n3].}}<br />
<br />
Then connect with a spice client<br />
<br />
$ spicec -h 127.0.0.1 -p 5930<br />
<br />
{{Tip|<br />
* The key combination to escape mouse and keyboard grab can be configured for {{ic|spicec}}, the default is {{ic|Shift+F12}}: {{bc|1=$ spicec --hotkeys release-cursor=ctrl+alt}}<br />
* To disable mouse and keyboard grabbing for {{ic|spicec}} (useful to allow your window manager shortcuts to work), set {{ic|1=SPICE_NOGRAB=1}}.<br />
* {{Pkg|virt-manager}} has a SPICE client built in.<br />
* {{Pkg|spice-gtk3}} provides another client for demoing purposes. Example usage: {{ic|spicy -h 127.0.0.1 -p 5930}}.<br />
}}<br />
<br />
==== SPICE Guest Additions ====<br />
For improved support for multiple monitors, clipboard sharing and more, you have to install additional packages in your ''guest'':<br />
* {{AUR|spice-vdagent}}: for [http://people.freedesktop.org/~teuf/spice-doc/html/ch02s05.html Agent] support. Do not forget to enable the {{ic|spice-vdagentd}} service.<br />
* {{AUR|xf86-video-qxl}}: for the QXL display driver.<br />
* For other operating systems, see http://people.freedesktop.org/~teuf/spice-doc/html/ch04.html<br />
<br />
In addition to the {{ic|-spice}} option, these options are also needed:<br />
<br />
-device virtio-serial \<br />
-chardev spicevmc,id=vdagent,name=vdagent \<br />
-device virtserialport,chardev=vdagent,name=com.redhat.spice.0<br />
<br />
The spicec and spicy program are intended for testing purposes, to enable additional monitors you have to install the {{Pkg|virtviewer}} package. Then connect with the VM using:<br />
<br />
remote-viewer spice://localhost:5930<br />
<br />
==== Multi-monitor support ====<br />
The Linux QXL driver supports four heads (virtual screens) by default. This can be changed via the {{ic|1=qxl.heads=N}} kernel parameter.<br />
<br />
The default VGA memory size for QXL devices is 16M (VRAM size is 64M). This is not sufficient if you would like to enable two 1920x1200 monitors since that requires 2 × 1920 × 4 (color depth) × 1200 = 17.6 MiB VGA memory. This can be changed by replacing {{ic|-vga qxl}} by {{ic|<nowiki>-vga none -device qxl-vga,vgamem_mb=32</nowiki>}}. If you ever increase vgamem_mb beyond 64M, then you also have to increase the {{ic|vram_size_mb}} option.<br />
<br />
=== Copy and paste ===<br />
<br />
To have copy and paste between the host and the guest you need to enable the spice agent communication channel. It requires to add a virtio-serial device to the guest, and open a port for the spice vdagent. It is also required to install the spice vdagent in guest ({{AUR|spice-vdagent}} for Arch guests, [http://www.spice-space.org/download.html Windows guest tools] for Windows guests). Make sure the agent is running (and for future, started automatically).<br />
<br />
Start QEMU with the following options:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The {{ic|-device virtio-serial-pci}} option adds the virtio-serial device, {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in that device and {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port.<br />
<br />
It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 10.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-i386 -nographic -net user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either rdesktop or freerdp to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|~/.bashrc}} file.<br />
<br />
=== No visible Cursor ===<br />
<br />
Add {{ic|-show-cursor}} to QEMU's options to see a mouse cursor.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps}}.<br />
<br />
$ qemu-system-i386 -k ''keymap'' ''disk_image''<br />
<br />
=== Virtual machine runs too slowly ===<br />
<br />
There are a number of techniques that you can use to improve the performance if your virtual machine. For example:<br />
<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU. If you do not do this, it may be trying to emulate a more generic CPU.<br />
* If the host machine has multiple CPUs, assign the guest more CPUs using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* Use KVM if possible: add {{ic|1=-machine type=pc,accel=kvm}} to the QEMU start command you use.<br />
* If supported by drivers in the guest operating system, use [http://wiki.libvirt.org/page/Virtio virtio] for network and/or block devices. For example:<br />
$ qemu-system-i386 -net nic,model=virtio -net tap,if=tap0,script=no -drive file=''disk_image'',media=disk,if=virtio<br />
* Use TAP devices instead of user-mode networking. See [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, disable the cache:<br />
$ qemu-system-i386 -drive file=''disk_image'',if=virtio,cache=none<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]:<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU with the {{ic|-balloon virtio}} option.<br />
<br />
See http://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
=== Guest display stretches on window resize ===<br />
<br />
To restore default window size, press {{ic|Ctrl+Alt+u}}.<br />
<br />
=== ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy ===<br />
<br />
If an error message like this is printed when starting QEMU with {{ic|-enable-kvm}} option:<br />
<br />
ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy<br />
failed to initialize KVM: Device or resource busy<br />
<br />
that means another [[hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<br />
<br />
=== libgfapi error message ===<br />
<br />
The error message displayed at startup:<br />
<br />
Failed to open module: libgfapi.so.0: cannot open shared object file: No such file or directory<br />
<br />
is not a problem, it just means that you are lacking the optional GlusterFS dependency.<br />
<br />
=== Kernel panic on LIVE-environments===<br />
<br />
If you start a live-environment (or better: booting a system) you may encounter this:<br />
<br />
[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)<br />
<br />
or some other boot hindering process (e.g. can't unpack initramfs, cant start service foo).<br />
Try starting the VM with the {{ic|-m VALUE}} switch and an appropriate amount of RAM, if the ram is to low you will probably encounter similar issues as above/without the memory-switch.<br />
<br />
<br />
== See also ==<br />
<br />
* [http://qemu.org Official QEMU website]<br />
* [http://www.linux-kvm.org Official KVM website]<br />
* [http://qemu.weilnetz.de/qemu-doc.html QEMU Emulator User Documentation]<br />
* [https://en.wikibooks.org/wiki/QEMU QEMU Wikibook]<br />
* [http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU] by AlienBOB (last updated in 2008)<br />
* [http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army] by Falconindy<br />
* [http://git.qemu.org/?p=qemu.git;a=tree;f=docs Lastest docs]<br />
* [http://qemu.weilnetz.de/ QEMU on Windows]<br />
* [http://en.wikipedia.org/wiki/Qemu Wikipedia]<br />
* [https://wiki.debian.org/QEMU QEMU - Debian Wiki]<br />
* [https://people.gnome.org/~markmc/qemu-networking.html QEMU Networking on gnome.org]<br />
* [http://bsdwiki.reedmedia.net/wiki/networking_qemu_virtual_bsd_systems.html Networking QEMU Virtual BSD Systems]<br />
* [https://www.gnu.org/software/hurd/hurd/running/qemu.html QEMU on gnu.org]<br />
* [https://wiki.freebsd.org/qemu QEMU on FreeBSD as host]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=QEMU&diff=413841QEMU2015-12-30T13:01:31Z<p>Netskink: /* Networking */</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Hypervisors]]<br />
[[de:Qemu]]<br />
[[es:QEMU]]<br />
[[fr:Qemu]]<br />
[[ja:QEMU]]<br />
[[zh-CN:QEMU]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
<br />
From the [http://wiki.qemu.org/Main_Page QEMU about page]:<br />
:''QEMU is a generic and open source machine emulator and virtualizer.''<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installing QEMU ==<br />
<br />
{{Expansion|See {{Bug|45977}}.}}<br />
<br />
[[Install]] the {{Pkg|qemu}} package.<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s). However, there are several GUI front-ends for QEMU:<br />
<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
* {{AUR|aqemu}}<br />
<br />
Additional front-ends with QEMU support are available for [[libvirt]].<br />
<br />
== Creating new virtualized system ==<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Tip|See the [https://en.wikibooks.org/wiki/QEMU/Images QEMU Wikibook] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk.<br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. Using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GB image in the ''raw'' format:<br />
<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''qcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
{{Warning|If you store the hard disk images on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the directory before creating any images.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
<br />
$ qemu-img create -o backing_file=''img1.raw'',backing_fmt=''raw'' -f ''qcow2'' ''img1.cow''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
<br />
$ qemu-system-i386 ''img1.cow''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required.<br />
<br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like:<br />
<br />
$ qemu-img rebase -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked:<br />
<br />
$ qemu-img rebase -u -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the operating system installed on it unbootable. For full explanation and workaround see [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages].}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example, to increase image space by 10 GB, run:<br />
<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
After enlarging the disk image, you must use file system and partitioning tools inside the virtual machine to actually begin using the new space. When shrinking a disk image, you must '''first reduce the allocated file systems and partition sizes''' using the file system and partitioning tools inside the virtual machine and then shrink the disk image accordingly, otherwise shrinking the disk image will result in data loss!<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly.<br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso''}}}}<br />
<br />
=== Installing the operating system===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 guests, to install from a bootable ISO file as CD-ROM:<br />
<br />
$ qemu-system-i386 -cdrom ''iso_image'' -boot order=d ''qemu_image''<br />
<br />
See {{ic|qemu(1)}} for information about loading other media types, such as floppy or disk images, or physical drives.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Tip|<br />
* By default only 128 MB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512M}} or {{ic|-m 2G}}.<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on guest's architecture) are used to run the virtualized guest. The usage is:<br />
<br />
$ qemu-system-i386 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{ic|qemu(1)}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM must be supported by your processor and kernel, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-enable-kvm}} to the additional start options. To check if KVM is enabled for a running VM, enter the QEMU [https://en.wikibooks.org/wiki/QEMU/Monitor Monitor] using {{ic|Ctrl+Alt+Shift+2}}, and type {{ic|info kvm}}.<br />
<br />
{{Note|<br />
* If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.<br />
* KVM needs to be enabled in order to start Windows 7 and Windows 8 properly without a ''blue screen''.<br />
}}<br />
<br />
== Moving data between host and guest OS ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[SMB]] or [[NFS]], or you can access the host's HTTP server, etc.<br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] with an automatically generated {{ic|smb.conf}} file located at {{ic|/tmp/qemu-smb.''pid''-0/smb.conf}} and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and this is not necessarily very useful since the guest can also access the normal [[Samba]] service on the host if you have set up shares on it.<br />
<br />
To enable this feature, start QEMU with a command like:<br />
<br />
$ qemu-system-i386 ''disk_image'' -net nic -net user,smb=''shared_dir_path''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
{{Note|<br />
* If you are using sharing options multiple times like {{ic|1=-net user,smb=''shared_dir_path1'' -net user,smb=''shared_dir_path2''}} or {{ic|1=-net user,smb=''shared_dir_path1'',smb=''shared_dir_path2''}} then it will share only the last defined one.<br />
* If you cannot access the shared folder and the guest system is Windows, check that the [http://ecross.mvps.org/howto/enable-netbios-over-tcp-ip-with-windows.htm NetBIOS protocol is enabled] and that a firewall does not block [http://technet.microsoft.com/en-us/library/cc940063.aspx ports] used by the NetBIOS protocol.<br />
}}<br />
<br />
=== Mounting a partition inside a raw disk image ===<br />
<br />
When the virtual machine is not running, it is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices. This does not work with disk images in special formats, such as qcow2, although those can be mounted using {{ic|qemu-nbd}}.<br />
<br />
{{Warning|You must make sure to unmount the partitions before running the virtual machine again. Otherwise, data corruption is very likely to occur.}}<br />
<br />
==== With manually specifying byte offset ====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
==== With loop module autodetecting partitions ====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* [[Kernel_modules#Manual_module_handling|Unload]] the {{ic|loop}} kernel module, and load it with the {{ic|1=max_part=15}} parameter set. Additionally, the maximum number of loop devices can be controlled with the {{ic|max_loop}} parameter.<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
<br />
# losetup -f -P ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
==== With kpartx ====<br />
<br />
'''kpartx''' from the {{AUR|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a ''disk_image''<br />
<br />
This will setup the loopback device and create the necessary partition(s) device(s) in {{ic|/dev/mapper/}}.<br />
<br />
=== Mounting a partition inside a qcow2 image ===<br />
<br />
You may mount a partition inside a qcow2 image using {{ic|qemu-nbd}}. See [http://en.wikibooks.org/wiki/QEMU/Images#Mounting_an_image_on_the_host Wikibooks].<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you need to change the owner of the partition's device file to that user.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[kernel]] and [[initramfs|initrd]] manually, or by simulating a disk with a MBR by using linear [[RAID]].<br />
<br />
==== By specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
<br />
{{Note|In this example, it is the '''host's''' images that are being used, not the guest's. If you wish to use the guest's images, either mount {{ic|/dev/sda3}} read-only (to protect the file system from the host) and specify the {{ic|/full/path/to/images}} or use some kexec hackery in the guest to reload the guest's kernel (extends boot time). }}<br />
<br />
$ qemu-system-i386 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
When there are multiple [[kernel parameters]] to be passed to the {{ic|-append}} option, they need to be quoted using single or double quotes. For example:<br />
<br />
... -append 'root=/dev/sda1 console=ttyS0'<br />
<br />
==== Simulate virtual disk with MBR using linear RAID ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate a MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
You can do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: the trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image.<br />
<br />
Suppose you have a plain, unmounted {{ic|/dev/hdaN}} partition with some file system on it you wish to make part of a QEMU disk image. First, you create some small file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hdaN}} disk image using software RAID:<br />
<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kilobyte-roundable offsets (such as 31.5 KB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu.<br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image:<br />
<br />
$ qemu-system-i386 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
== Networking ==<br />
<br />
{{Poor writing|Network topologies (sections [[#Host-only networking]], [[#Internal networking]] and info spread out across other sections) should not be described alongside the various virtual interfaces implementations, such as [[#User-mode networking]], [[#Tap networking with QEMU]], [[#Networking with VDE2]].}}<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [http://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
<ol><br />
<li>Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
</li><br />
<li>Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
{{bc|1=<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-i386 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
}}<br />
<br />
</li><br />
<li>Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|<nowiki><br />
#!/usr/bin/env python<br />
<br />
import sys<br />
import zlib<br />
<br />
if len(sys.argv) != 2:<br />
print("usage: %s <VM Name>" % sys.argv[0])<br />
sys.exit(1)<br />
<br />
crc = zlib.crc32(sys.argv[1].encode("utf-8")) & 0xffffffff<br />
crc = str(hex(crc))[2:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))<br />
</nowiki>}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-i386 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
</li><br />
</ol><br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU.<br />
<br />
{{warning|This only works with the TCP and UDP protocols, so ICMP, including {{ic|ping}}, will not work. Do not use {{ic|ping}} to test network connectivity.}}<br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, redirecting host ports to the guest (for example to allow SSH connections to the guest) or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the [[Firewalls|precautions]] you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, a better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
As indicated in the user-mode networking section, tap devices offer higher networking performance than user-mode. If the guest OS supports virtio network driver, then the networking performance will be increased considerably as well. Supposing the use of the tap0 device, that the virtio driver is used on the guest, and that no scripts are used to help start/stop networking, next is part of the qemu command one should see:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no<br />
<br />
But if already using a tap device with virtio networking driver, one can even boost the networking performance by enabling vhost, like:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no,vhost=on<br />
<br />
See http://www.linux-kvm.com/content/how-maximize-virtio-net-performance-vhost-net for more information.<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet sharing#Enable NAT]] page.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface&#61;br0 --bind-interfaces --dhcp-range&#61;172.20.0.2,172.20.255.254<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
By default iptables would drop packets in the bridge network. You may need to use such iptables rule to allow packets in a bridged network:<br />
<br />
# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
{{Note|This method is available since QEMU 1.1, see http://wiki.qemu.org/Features/HelperNetworking.}}<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|See [[Network bridge]] for information on creating bridge.}}<br />
<br />
First, copy {{ic|/etc/qemu/bridge.conf.sample}} to {{ic|/etc/qemu/bridge.conf}}. Now modify {{ic|/etc/qemu/bridge.conf}} to contain the names of all bridges to be used by QEMU:<br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''bridge0''<br />
allow ''bridge1''<br />
...}}<br />
<br />
Now start the VM. The most basic usage would be:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' ''[...]''<br />
<br />
With multiple taps, the most basic usage requires specifying the VLAN for all additional NICs:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' -net nic,vlan=1 -net bridge,vlan=1,br=''bridge1'' ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [http://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it. See http://en.gentoo-wiki.com/wiki/KVM#Networking_2{{Dead link|2013|07|23}}.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
# sysctl net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Now create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=$(whoami)<br />
<br />
# Get name of newly created TAP device; see https://bbs.archlinux.org/viewtopic.php?pid=1285079#p1285079<br />
precreationg=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
sudo /usr/bin/ip tuntap add user $USERID mode tap<br />
postcreation=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
IFACE=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
<br />
# This line creates a random MAC address. The downside is the DHCP server will assign a different IP address each time<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
# Instead, uncomment and edit this line to set a static MAC address. The benefit is that the DHCP server will assign the same IP address.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu-system-i386 -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo ip link set dev $IFACE down &> /dev/null<br />
sudo ip tuntap del $IFACE mode tap &> /dev/null<br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
$ run-qemu -hda ''myvm.img'' -m 512 -vga std<br />
<br />
* It is recommended for performance and security reasons to disable the [http://ebtables.netfilter.org/documentation/bridge-nf.html firewall on the bridge]:<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [http://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Loading]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Network sharing between physical device and a Tap device through iptables ====<br />
<br />
{{Merge|Internet_sharing|Duplication, not specific to QEMU.}}<br />
<br />
Bridged networking works fine between a wired interface (Eg. eth0), and it's easy to setup. However if the host gets connected to the network through a wireless device, then bridging is not possible.<br />
<br />
See https://wiki.archlinux.org/index.php/Network_bridge#Wireless_interface_on_a_bridge as a reference.<br />
<br />
One way to overcome that is to setup a tap device with a static IP, making linux automatically handle the routing for it, and then forward traffic between the tap interface and the device connected to the network through iptables rules.<br />
<br />
See https://wiki.archlinux.org/index.php/Internet_sharing as a reference.<br />
<br />
There you can find what's needed to share the network between devices, included tap and tun ones. The following just hints further on some of the host configurations required. As indicated in the reference above, the client needs to be configured for a static IP, using the IP assigned to the tap interface as the gateway. The caveat is that the DNS servers on the client might need to be manually edited if they change when changing from one host device connected to the network to another.<br />
<br />
To allow IP forwarding on every boot, one need to add the following lines to sysctl configuration file inside /etc/sysctl.d:<br />
<br />
net.ipv4.ip_forward = 1<br />
net.ipv6.conf.default.forwarding = 1<br />
net.ipv6.conf.all.forwarding = 1<br />
<br />
The iptables rules can look like:<br />
<br />
# Forwarding from/to outside<br />
iptables -A FORWARD -i ${INT} -o ${EXT_0} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_1} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_2} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_0} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_1} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_2} -o ${INT} -j ACCEPT<br />
# NAT/Masquerade (network address translation)<br />
iptables -t nat -A POSTROUTING -o ${EXT_0} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_1} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_2} -j MASQUERADE<br />
<br />
The prior supposes there are 3 devices connected to the network sharing traffic with one internal device, where for example:<br />
<br />
INT=tap0<br />
EXT_0=eth0<br />
EXT_1=wlan0<br />
EXT_2=tun0<br />
<br />
The prior shows a forwarding that would allow sharing wired and wireless connections with the tap device.<br />
<br />
The forwarding rules shown are stateless, and for pure forwarding. One could think of restricting specific traffic, putting a firewall in place to protect the guest and others. However those would decrease the networking performance, while a simple bridge doesn't include any of that.<br />
<br />
Bonus: Whether the connection is wired or wireless, if one gets connected through VPN to a remote site with a tun device, supposing the tun device opened for that connection is tun0, and the prior iptables rules are applied, then the remote connection gets also shared with the guest. This avoids the need for the guest to also open a VPN connection. Again, as the guest networking needs to be static, then if connecting the host remotely this way, one most probably will need to edit the DNS servers on the guest.<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [http://wiki.virtualsquare.org/wiki/index.php/Main_Page the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-i386 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep -f vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be executable<br />
<br />
# chmod u+x /etc/systemd/scripts/qemu-network-env<br />
<br />
You can [[start]] {{ic|qemu-network-env.service}} as usual.<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
<br />
=== Host-only Networking with ARM virtual machines (VM/Guests) ===<br />
<br />
This is a concise method for setting up host only networking for ARM guests. ie. the vm and host can ssh, ping each other. Interactions between<br />
multiple guests was not tested. The method is slightly different for i386 guests and that method is not described here but in the attached<br />
notes here.<br />
<br />
==== Components Needed ====<br />
<br />
These are the components used for this method:<br />
<br />
* qemu - I used the regular git version of qemu instead of the one provided by dpkg since it did not have arm support prebuilt. The build method is detailed in the github link.<br />
* dnsmasq<br />
* bridge-utils<br />
<br />
==== Procedure ====<br />
<br />
Start the bridge/tap and dhcp server for the host only network. Afterwards the interfaces will be down. When the vm is started these interfaces will be started. Possibly netctl's bridge example interface could do this but it was simpler to just write a script. This script will need to be run using sudo. Lastly, the ip address chosen 172.16.0.1 was chosen since it did not conflict with any network currently in use.<br />
<br />
{{hc|do_network.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Do this to setup host only networking<br />
brctl addbr br0<br />
ip addr add 172.16.0.1/24 broadcast 172.16.0.255 dev br0<br />
ip link set br0 up<br />
ip tuntap add dev tap0 mode tap<br />
ip link set tap0 up promisc on<br />
brctl addif br0 tap0<br />
ip link set tap0 up<br />
dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.16.0.10,172.16.0.20<br />
</nowiki>}}<br />
<br />
Once the tap/bridge is setup start the arm vm like so:<br />
<br />
{{hc|do_network.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Do this to setup host only networking<br />
brctl addbr br0<br />
ip addr add 172.16.0.1/24 broadcast 172.16.0.255 dev br0<br />
ip link set br0 up<br />
ip tuntap add dev tap0 mode tap<br />
ip link set tap0 up promisc on<br />
brctl addif br0 tap0<br />
ip link set tap0 up<br />
dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.16.0.10,172.16.0.20<br />
</nowiki>}}<br />
<br />
{{hc|do_network.sh|<nowiki><br />
#!/bin/bash<br />
<br />
sudo qemu-system-arm -M vexpress-a9 -kernel vmlinuz-3.2.0-4-vexpress \<br />
-initrd initrd.img-3.2.0-4-vexpress -append "root=/dev/mmcblk0p2" \<br />
-drive if=sd,cache=unsafe,file=hda.img \<br />
-net nic,vlan=0 -net tap,vlan=0,ifname=tap0,script=no<br />
</nowiki>}}<br />
<br />
==== More Details ====<br />
<br />
More details on how to setup a virtual machine, building qemu, using a similar method for i386, credits to the work this is based on and more are found here <br />
http://github.com/netskink/carolinacon12<br />
<br />
== Graphics ==<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|cirrus}}, {{ic|vmware}}, {{ic|qxl}}, and {{ic|none}}.<br />
<br />
=== cirrus ===<br />
<br />
The cirrus graphical adapter was the default [http://wiki.qemu.org/ChangeLog/2.2#VGA before 2.2]. It [https://www.kraxel.org/blog/2014/10/qemu-using-cirrus-considered-harmful/ should not] be used on modern systems.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels. This is the default since QEMU 2.2.<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. On the guest, install the VMware drivers ({{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests).<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, pass the {{ic|-vga qxl}} option and install drivers in the guest.<br />
<br />
For basic support (similar to {{ic|-vga std}}) in Linux guests, the qxl and bochs_drm kernel modules must be loaded. The xorg modesetting driver (part of {{Pkg|xorg-server}}) can be combined with these drivers. Drivers for other operating systems can be found on the [http://www.spice-space.org/download.html SPICE download page]. Advanced functionality such as multi-monitor support requires [[#Spice support|SPICE]].<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
=== vnc ===<br />
<br />
Given that you used the {{ic|-nographic}} option, you can add the {{ic|-vnc display}} option to have QEMU listen on {{ic|display}} and redirect the VGA display to the VNC session. There is an example of this in the [[#Starting QEMU virtual machines on boot]] section's example configs.<br />
<br />
$ qemu-system-i386 -vga std -nographic -vnc :0<br />
$ gvncviewer :0<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [http://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [http://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} instead of the simple {{Ic|-hd*}} plus {{Ic|1=if=virtio}}:<br />
$ qemu-system-i386 -boot order=c -drive file=''disk_image'',if=virtio<br />
<br />
{{Note|{{Ic|1=-boot order=c}} is absolutely necessary when you want to boot from it. There is no auto-detection as with {{Ic|-hd*}}.}}<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-i386 -net nic,model=virtio<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an (Arch) Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must contain the necessary modules. By default, this is handled by [[mkinitcpio]]'s {{ic|autodetect}} hook. Otherwise use the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}} to include the necessary modules and rebuild the initial ramdisk.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES="virtio virtio_blk virtio_pci virtio_net"}}<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing to disks by [[UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [http://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
{{Note|1=The only (reliable) way to upgrade a Windows 8.1 guest to Windows 10 seems to be to temporarily choose cpu core2duo,nx for the install [http://ubuntuforums.org/showthread.php?t=2289210]. After the install, you may revert to other cpu settings (8/8/2015).}}<br />
<br />
==== Block device drivers ====<br />
<br />
===== New Install of Windows =====<br />
<br />
Windows does not come with the virtio drivers. Therefore, you will need to load them during installation. There are basically two ways to do this: via Floppy Disk or via ISO files. Both images can be downloaded from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
The floppy disk option is difficult because you will need to press F6 (Shift-F6 on newer Windows) at the very beginning of powering on the QEMU. This is difficult since you need time to connect your VNC console window. You can attempt to add a delay to the boot sequence. See {{ic|man qemu-system}} for more details about applying a delay at boot.<br />
<br />
The ISO option to load drivers is the preferred way, but it is available only on Windows Vista and Windows Server 2008 and later. The procedure is to load the image with virtio drivers in an additional cdrom device along with the primary disk device and Windows installer:<br />
<br />
$ qemu-system-i386 ... \<br />
-drive file=''/path/to/primary/disk.img'',index=0,media=disk,if=virtio \<br />
-drive file=''/path/to/installer.iso'',index=2,media=cdrom \<br />
-drive file=''/path/to/virtio.iso'',index=3,media=cdrom \<br />
...<br />
<br />
During the installation, the Windows installer will ask you for your Product key and perform some additional checks. When it gets to the "Where do you want to install Windows?" screen, it will give a warning that no disks are found. Follow the example instructions below (based on Windows Server 2012 R2 with Update).<br />
<br />
* Select the option {{ic|Load Drivers}}.<br />
* Uncheck the box for "Hide drivers that aren't compatible with this computer's hardware".<br />
* Click the Browse button and open the CDROM for the virtio iso, usually named "virtio-win-XX".<br />
* Now browse to {{ic|E:\viostor\[your-os]\amd64}}, select it, and press OK.<br />
* Click Next<br />
<br />
You should now see your virtio disk(s) listed here, ready to be selected, formatted and installed to.<br />
<br />
===== Change Existing Windows VM to use virtio =====<br />
Modifying an existing Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
Now you need to create a new disk image, which fill force Windows to search for the driver. For example:<br />
<br />
$ qemu-img create -f qcow2 ''fake.qcow2'' 1G<br />
<br />
Run the original Windows guest (with the boot disk still in IDE mode) with the fake disk (in virtio mode) and a CD-ROM with the driver.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=ide -drive file=''fake.qcow2'',if=virtio -cdrom virtio-win-0.1-81.iso<br />
<br />
Windows will detect the fake disk and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
When the installation is successful, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio<br />
<br />
{{Note|If you encounter the Blue Screen of Death, make sure you did not forget the {{ic|-m}} parameter, and that you do not boot with virtio instead of ide for the system drive before drivers are installed.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-net}} argument as explained above.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio -net nic,model=virtio -cdrom virtio-win-0.1-74.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|<nowiki><br />
virtio_loader="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
</nowiki>}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
{{bc|<nowiki><br />
sed -i bak "s/ada/vtbd/g" /etc/fstab<br />
</nowiki>}}<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured through the virt-manager GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== Custom script ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|<nowiki><br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="type=system-x86_64" "haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/env qemu-${type} -name %i -nographic $args<br />
ExecStop=/bin/sh -c ${haltcmd}<br />
TimeoutStopSec=30<br />
KillMode=none<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|According to {{ic|systemd.service(5)}} and {{ic|systemd.kill(5)}} man pages it is necessary to use the {{ic|1=KillMode=none}} option. Otherwise the main qemu process will be killed immediately after the {{ic|ExecStop}} command quits (it simply echoes one string) and your quest system will not be able to shutdown correctly.}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the following variables set:<br />
<br />
; type<br />
: QEMU binary to call. If specified, will be prepended with {{ic|/usr/bin/qemu-}} and that binary will be used to start the VM. I.e. you can boot e.g. {{ic|qemu-system-arm}} images with {{ic|1=type="system-arm"}}.<br />
; args<br />
: QEMU command line to start with. Will always be prepended with {{ic|-name ${vm} -nographic}}.<br />
; haltcmd<br />
: Command to shut down a VM safely. I am using {{ic|-monitor telnet:..}} and power off my VMs via ACPI by sending {{ic|system_powerdown}} to monitor. You can use SSH or some other ways.<br />
<br />
Example configs:<br />
<br />
{{hc|/etc/conf.d/qemu.d/one|<nowiki><br />
type="system-x86_64"<br />
<br />
args="-enable-kvm -m 512 -hda /dev/mapper/vg0-vm1 -net nic,macaddr=DE:AD:BE:EF:E0:00 \<br />
-net tap,ifname=tap0 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7100" # or netcat/ncat<br />
<br />
# You can use other ways to shut down your VM correctly<br />
#haltcmd="ssh powermanager@vm1 sudo poweroff"<br />
</nowiki>}}<br />
<br />
{{hc|/etc/conf.d/qemu.d/two|<nowiki><br />
args="-enable-kvm -m 512 -hda /srv/kvm/vm2.img -net nic,macaddr=DE:AD:BE:EF:E0:01 \<br />
-net tap,ifname=tap1 -serial telnet:localhost:7001,server,nowait,nodelay \<br />
-monitor telnet:localhost:7101,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7101"<br />
</nowiki>}}<br />
<br />
To set which virtual machines will start on boot-up, use<br />
<br />
# systemctl enable qemu@''vm_name''<br />
# systemctl disable qemu@''vm_name''<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the option {{ic|-usbdevice tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
<br />
$ qemu-system-i386 -hda ''disk_image'' -m 512 -vga std -usbdevice tablet<br />
<br />
If that doesn't work, try the tip at [[#Mouse cursor is jittery or erratic]].<br />
<br />
=== Pass-through host USB device ===<br />
<br />
To access physical USB device connected to host from VM, you can start QEMU with following option:<br />
<br />
$ qemu-system-i386 -usbdevice host:''vendor_id'':''product_id'' ''disk_image''<br />
<br />
You can find {{ic|vendor_id}} and {{ic|product_id}} of your device with {{ic|lsusb}} command.<br />
<br />
{{Note|If you encounter permission errors when running QEMU, see [[Udev#Writing udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
To enable KSM, simply run<br />
<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, you can use [[systemd#Temporary files|systemd's temporary files]]:<br />
<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://www.kernel.org/doc/Documentation/vm/ksm.txt for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory: {{bc|$ grep . /sys/kernel/mm/ksm/*}}}}<br />
<br />
=== Spice support ===<br />
<br />
{{Poor writing|This section needs much more information and shall be placed under the [[#Graphics]] section .}}<br />
<br />
The [http://spice-space.org/ SPICE project] aims to provide a complete, open-source solution for interaction with virtualized desktop devices. Its main focus is to provide high-quality remote access to QEMU virtual machines.<br />
<br />
The official {{Pkg|qemu}} package is built with SPICE support.<br />
<br />
You can start your VM:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing,addr=::1<br />
<br />
{{Out of date|1=''spicec'' has been removed in {{Pkg|spice}}-0.12.6 [http://cgit.freedesktop.org/spice/spice/tree/NEWS?id=f0aeb9db000a34a46b51c5d95229171ff1eee307#n3].}}<br />
<br />
Then connect with a spice client<br />
<br />
$ spicec -h 127.0.0.1 -p 5930<br />
<br />
{{Tip|<br />
* The key combination to escape mouse and keyboard grab can be configured for {{ic|spicec}}, the default is {{ic|Shift+F12}}: {{bc|1=$ spicec --hotkeys release-cursor=ctrl+alt}}<br />
* To disable mouse and keyboard grabbing for {{ic|spicec}} (useful to allow your window manager shortcuts to work), set {{ic|1=SPICE_NOGRAB=1}}.<br />
* {{Pkg|virt-manager}} has a SPICE client built in.<br />
* {{Pkg|spice-gtk3}} provides another client for demoing purposes. Example usage: {{ic|spicy -h 127.0.0.1 -p 5930}}.<br />
}}<br />
<br />
==== SPICE Guest Additions ====<br />
For improved support for multiple monitors, clipboard sharing and more, you have to install additional packages in your ''guest'':<br />
* {{AUR|spice-vdagent}}: for [http://people.freedesktop.org/~teuf/spice-doc/html/ch02s05.html Agent] support. Do not forget to enable the {{ic|spice-vdagentd}} service.<br />
* {{AUR|xf86-video-qxl}}: for the QXL display driver.<br />
* For other operating systems, see http://people.freedesktop.org/~teuf/spice-doc/html/ch04.html<br />
<br />
In addition to the {{ic|-spice}} option, these options are also needed:<br />
<br />
-device virtio-serial \<br />
-chardev spicevmc,id=vdagent,name=vdagent \<br />
-device virtserialport,chardev=vdagent,name=com.redhat.spice.0<br />
<br />
The spicec and spicy program are intended for testing purposes, to enable additional monitors you have to install the {{Pkg|virtviewer}} package. Then connect with the VM using:<br />
<br />
remote-viewer spice://localhost:5930<br />
<br />
==== Multi-monitor support ====<br />
The Linux QXL driver supports four heads (virtual screens) by default. This can be changed via the {{ic|1=qxl.heads=N}} kernel parameter.<br />
<br />
The default VGA memory size for QXL devices is 16M (VRAM size is 64M). This is not sufficient if you would like to enable two 1920x1200 monitors since that requires 2 × 1920 × 4 (color depth) × 1200 = 17.6 MiB VGA memory. This can be changed by replacing {{ic|-vga qxl}} by {{ic|<nowiki>-vga none -device qxl-vga,vgamem_mb=32</nowiki>}}. If you ever increase vgamem_mb beyond 64M, then you also have to increase the {{ic|vram_size_mb}} option.<br />
<br />
=== Copy and paste ===<br />
<br />
To have copy and paste between the host and the guest you need to enable the spice agent communication channel. It requires to add a virtio-serial device to the guest, and open a port for the spice vdagent. It is also required to install the spice vdagent in guest ({{AUR|spice-vdagent}} for Arch guests, [http://www.spice-space.org/download.html Windows guest tools] for Windows guests). Make sure the agent is running (and for future, started automatically).<br />
<br />
Start QEMU with the following options:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The {{ic|-device virtio-serial-pci}} option adds the virtio-serial device, {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in that device and {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port.<br />
<br />
It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 10.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-i386 -nographic -net user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either rdesktop or freerdp to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|~/.bashrc}} file.<br />
<br />
=== No visible Cursor ===<br />
<br />
Add {{ic|-show-cursor}} to QEMU's options to see a mouse cursor.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps}}.<br />
<br />
$ qemu-system-i386 -k ''keymap'' ''disk_image''<br />
<br />
=== Virtual machine runs too slowly ===<br />
<br />
There are a number of techniques that you can use to improve the performance if your virtual machine. For example:<br />
<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU. If you do not do this, it may be trying to emulate a more generic CPU.<br />
* If the host machine has multiple CPUs, assign the guest more CPUs using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* Use KVM if possible: add {{ic|1=-machine type=pc,accel=kvm}} to the QEMU start command you use.<br />
* If supported by drivers in the guest operating system, use [http://wiki.libvirt.org/page/Virtio virtio] for network and/or block devices. For example:<br />
$ qemu-system-i386 -net nic,model=virtio -net tap,if=tap0,script=no -drive file=''disk_image'',media=disk,if=virtio<br />
* Use TAP devices instead of user-mode networking. See [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, disable the cache:<br />
$ qemu-system-i386 -drive file=''disk_image'',if=virtio,cache=none<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]:<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU with the {{ic|-balloon virtio}} option.<br />
<br />
See http://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
=== Guest display stretches on window resize ===<br />
<br />
To restore default window size, press {{ic|Ctrl+Alt+u}}.<br />
<br />
=== ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy ===<br />
<br />
If an error message like this is printed when starting QEMU with {{ic|-enable-kvm}} option:<br />
<br />
ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy<br />
failed to initialize KVM: Device or resource busy<br />
<br />
that means another [[hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<br />
<br />
=== libgfapi error message ===<br />
<br />
The error message displayed at startup:<br />
<br />
Failed to open module: libgfapi.so.0: cannot open shared object file: No such file or directory<br />
<br />
is not a problem, it just means that you are lacking the optional GlusterFS dependency.<br />
<br />
=== Kernel panic on LIVE-environments===<br />
<br />
If you start a live-environment (or better: booting a system) you may encounter this:<br />
<br />
[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)<br />
<br />
or some other boot hindering process (e.g. can't unpack initramfs, cant start service foo).<br />
Try starting the VM with the {{ic|-m VALUE}} switch and an appropriate amount of RAM, if the ram is to low you will probably encounter similar issues as above/without the memory-switch.<br />
<br />
<br />
== See also ==<br />
<br />
* [http://qemu.org Official QEMU website]<br />
* [http://www.linux-kvm.org Official KVM website]<br />
* [http://qemu.weilnetz.de/qemu-doc.html QEMU Emulator User Documentation]<br />
* [https://en.wikibooks.org/wiki/QEMU QEMU Wikibook]<br />
* [http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU] by AlienBOB (last updated in 2008)<br />
* [http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army] by Falconindy<br />
* [http://git.qemu.org/?p=qemu.git;a=tree;f=docs Lastest docs]<br />
* [http://qemu.weilnetz.de/ QEMU on Windows]<br />
* [http://en.wikipedia.org/wiki/Qemu Wikipedia]<br />
* [https://wiki.debian.org/QEMU QEMU - Debian Wiki]<br />
* [https://people.gnome.org/~markmc/qemu-networking.html QEMU Networking on gnome.org]<br />
* [http://bsdwiki.reedmedia.net/wiki/networking_qemu_virtual_bsd_systems.html Networking QEMU Virtual BSD Systems]<br />
* [https://www.gnu.org/software/hurd/hurd/running/qemu.html QEMU on gnu.org]<br />
* [https://wiki.freebsd.org/qemu QEMU on FreeBSD as host]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Unified_Extensible_Firmware_Interface&diff=294924Unified Extensible Firmware Interface2014-01-29T18:11:13Z<p>Netskink: /* File Extensions */ Deleted the section and moved it to sourceforge wiki. I started thinking it might be of more general interest and less specific for arch users.</p>
<hr />
<div>[[Category:Boot process]]<br />
[[es:Unified Extensible Firmware Interface]]<br />
[[it:Unified Extensible Firmware Interface]]<br />
[[ja:Unified Extensible Firmware Interface]]<br />
[[ru:Unified Extensible Firmware Interface]]<br />
[[zh-CN:Unified Extensible Firmware Interface]]<br />
{{Related articles start}}<br />
{{Related|Arch Boot Process}}<br />
{{Related|Master Boot Record}}<br />
{{Related|GUID Partition Table}}<br />
{{Related articles end}}<br />
<br />
'''Unified Extensible Firmware Interface''' (or UEFI for short) is a new type of firmware that was initially designed by Intel (known as EFI then) mainly for its Itanium based systems. It introduces new ways of booting an OS that is distinct from the commonly used "[[MBR]] boot code" method followed for [[Wikipedia:BIOS|BIOS]] systems. It started as Intel's EFI in versions 1.x and then a group of companies called the UEFI Forum took over its development from which it was called Unified EFI starting with version 2.0. As of 24 July 2013, UEFI Specification 2.4 (released July 11, 2013) is the most recent version.<br />
<br />
{{Note|<br />
* This page explains '''What is UEFI''' and '''UEFI support in Linux kernel'''. It does not describe setting up UEFI Boot Loaders. For that information see [[Boot Loaders]].<br />
* Unless specified as EFI 1.x, EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware. Also unless stated explicitly, these instructions are general and some of them may not work or may be different in Apple Macs. Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one (U)EFI specification and therefore is not a standard UEFI firmware.}}<br />
<br />
== Differences between BIOS and UEFI ==<br />
See [[Arch_Boot_Process#Firmware_types]] for more details.<br />
<br />
== Boot Process under UEFI ==<br />
<br />
# System switched on - Power On Self Test, or POST process.<br />
# UEFI firmware is loaded. Firmware initializes the hardware required for booting.<br />
# Firmware then reads its Boot Manager data to determine which UEFI application to be launched and from where (i.e. from which disk and partition).<br />
# Firmware then launches the UEFI application as defined in the boot entry in the firmware's boot manager.<br />
# The launched UEFI application may launch another application (in case of UEFI Shell or a boot manager like rEFInd) or the kernel and initramfs (in case of a boot loader like GRUB) depending on how the UEFI application was configured.<br />
<br />
{{Note|On some UEFI systems the only possible way to launch UEFI application on boot (if it does not have custom entry in UEFI boot menu) is to put it in this fixed location: {{ic|<EFI SYSTEM PARTITION>/EFI/boot/bootx64.efi}} (for 64-bit x86 system)}}<br />
<br />
=== Multibooting in UEFI ===<br />
<br />
Since each OS or vendor can maintain its own files within the EFI System Partition without affecting the other, multi-booting using UEFI is just a matter of launching a different UEFI application corresponding to the particular OS's bootloader. This removes the need for relying on chainloading mechanisms of one [[Boot Loaders|boot loader]] to load another to switch OSes.<br />
<br />
==== Booting Microsoft Windows ====<br />
<br />
64-bit Windows Vista (SP1+), Windows 7 and Windows 8 versions support booting using x86_64 EFI firmware. Windows forces type of partitioning depending on the firmware used, i.e. if Windows is booted in UEFI mode, it can be installed only to a GPT disk. If the Windows is booted in Legacy BIOS mode, it can be installed only to a MBR disk. This is a limitation enforced by Windows installer. Thus Windows supports either UEFI-GPT boot or BIOS-MBR boot only, not UEFI-MBR or BIOS-GPT boot. <br />
<br />
Such a limitation is not enforced by the Linux kernel, but can depend on how the bootloader is configured. The Windows limitation should be considered if the user wishes to boot Windows and Linux from the same disk, since setting up the bootloader itself depends on the firmware type and disk partitioning used. In case where Windows and Linux dual boot from the same disk, it is advisable to follow the method used by Windows, either go for UEFI-GPT boot or BIOS-MBR boot only, not the other two cases.<br />
<br />
32-bit Windows versions only support BIOS-MBR booting. So, in case of Linux and 32-bit Windows booting from the same disk, the disk has to use MBR. See http://support.microsoft.com/kb/2581408 for more info.<br />
<br />
=== Detecting UEFI Firmware bitness ===<br />
<br />
==== Non Macs ====<br />
<br />
Check whether the dir {{ic|/sys/firmware/efi}} exists, if it exists it means the kernel has booted in EFI mode. In that case the UEFI bitness is same as kernel bitness. (ie. i686 or x86_64)<br />
<br />
{{Note|Intel Atom System-on-Chip systems ship with 32-bit UEFI (as on 2 November 2013). See [[HCL/Firmwares/UEFI#Intel_Atom_System-on-Chip|this page]] for more info.}}<br />
<br />
==== Apple Macs ====<br />
<br />
Pre-2008 Macs mostly have i386-efi firmware while >=2008 Macs have mostly x86_64-efi. All Macs capable of running Mac OS X Snow Leopard 64-bit Kernel have x86_64 EFI 1.x firmware. <br />
<br />
To find out the arch of the efi firmware in a Mac, type the following into the Mac OS X terminal:<br />
<br />
ioreg -l -p IODeviceTree | grep firmware-abi<br />
<br />
If the command returns EFI32 then it is IA32 (32-bit) EFI firmware. If it returns EFI64 then it is x86_64 EFI firmware. Most of the Macs do not have UEFI 2.x firmware as Apple's EFI implementation is not fully compliant with UEFI 2.x Specification.<br />
<br />
=== Secure Boot ===<br />
For an overview about Secure Boot in Linux see http://www.rodsbooks.com/efi-bootloaders/secureboot.html. This section focuses on how to set up Secure Boot in Arch Linux. For the time being, this section is limited to explain the procedure of booting the archiso with Secure Boot enabled.<br />
Booting the archiso with Secure Boot enabled is possible since the efi applications ''PreLoader.efi'' and ''HashTool.efi'' have been added to it. A message will show up that says ''Failed to Start loader... I will now execute HashTool.'' To use HashTool for enrolling the hash of ''loader.efi'' and ''vmlinuz.efi'', follow these steps.<br />
* Select {{ic|OK}}<br />
* In the HashTool main menu, select {{ic|Enroll Hash}}, choose {{ic|\loader.efi}} and confirm with {{ic|Yes}}. Again, select {{ic|Enroll Hash}} and {{ic|archiso}} to enter the archiso directory, then select {{ic|vmlinuz-efi}} and confirm with {{ic|Yes}}. Then choose {{ic|Exit}} to return to the boot device selection menu.<br />
* In the boot device selection menu choose {{ic|Arch Linux archiso x86_64 UEFI CD}}<br />
The archiso boots, and you are presented with a shell prompt, automatically logged in as root. To check if the archiso was booted with SecureBoot, use this command:<br />
<br />
$ od -An -t u1 /sys/firmware/efi/vars/SecureBoot-1234abcde-5678-/data<br />
<br />
If yes, this command returns 1. The characters denoted by 1234 differ from machine to machine. To help with this, you can use tab completion or list the efi variables.<br />
<br />
== Linux Kernel Config options for UEFI ==<br />
<br />
The required Linux Kernel configuration options for UEFI systems are :<br />
<br />
CONFIG_RELOCATABLE=y<br />
CONFIG_EFI=y<br />
CONFIG_EFI_STUB=y<br />
CONFIG_FB_EFI=y<br />
CONFIG_FRAMEBUFFER_CONSOLE=y<br />
<br />
UEFI Runtime Variables Support ('''efivarfs''' filesystem - {{ic|/sys/firmware/efi/efivars}}). This option is important as this is required to manipulate UEFI Runtime Variables using tools like {{ic|/usr/bin/efibootmgr}}. The below config option has been added in kernel 3.10 and above.<br />
<br />
CONFIG_EFIVAR_FS=y<br />
<br />
UEFI Runtime Variables Support (old '''efivars sysfs''' interface - {{ic|/sys/firmware/efi/vars}}). This option should be disabled.<br />
<br />
CONFIG_EFI_VARS=n<br />
<br />
GUID Partition Table [[GPT]] config option - mandatory for UEFI support<br />
<br />
CONFIG_EFI_PARTITION=y<br />
<br />
{{Note|All of the above options are required to boot Linux via UEFI, and are enabled in Archlinux kernels in official repos.}}<br />
<br />
Retrieved from https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt .<br />
<br />
== UEFI Variables ==<br />
<br />
UEFI defines variables through which an operating system can interact with the firmware. UEFI Boot Variables are used by the boot-loader and used by the OS only for early system start-up. UEFI Runtime Variables allow an OS to manage certain settings of the firmware like the UEFI Boot Manager or managing the keys for UEFI Secure Boot Protocol etc. You can get the list using <br />
$ efivar -l<br />
<br />
=== UEFI Variables Support in Linux Kernel ===<br />
<br />
Linux kernel exposes EFI variables data to userspace via 2 interfaces:<br />
<br />
* '''OLD sysfs-efivars''' interface (CONFIG_EFI_VARS) - populated by {{ic|efivars}} kernel module at {{ic|/sys/firmware/efi/vars}} - 1024 byte maximum per-variable data size limitation, no UEFI Secure Boot variables support (due to the size limitation) and not recommended by kernel upstream anymore. Still supported by kernel upstream but '''completely disabled in Arch's official kernels'''.<br />
<br />
* '''NEW efivarfs''' ('''EFI''' '''VAR'''iable '''F'''ile'''S'''ystem) interface (CONFIG_EFIVAR_FS) - mounted using {{ic|efivarfs}} kernel module at {{ic|/sys/firmware/efi/efivars}} - replacement for the OLD sysfs-efivars interface, has no maximum per-variable size limitation, supports UEFI Secure Boot variables and recommended by kernel upstream. Introduced in kernel 3.8 and NEW {{ic|efivarfs}} module split from OLD {{ic|efivars}} kernel module in kernel 3.10 .<br />
<br />
==== Inconsistency between efivarfs and sysfs-efivars ====<br />
<br />
Enabling both OLD sysfs-efivars and NEW efivarfs can cause data inconsistency issues (see See https://lkml.org/lkml/2013/4/16/473 for more info). Due to this OLD sysfs-efivars is completely disabled in Arch's official kernels (since '''core/{{Pkg|linux}}-3.11''' and '''core/{{Pkg|linux-lts}}-3.10''') and only NEW efivarfs is enabled/supported going forward. All the UEFI Variables related tools and utilities in [[official repositories]] support efivarfs as of 01 October 2013.<br />
<br />
{{Note|As a side-effect of disabling OLD sysfs-efivars, {{ic|efi_pstore}} module is also disabled in the official Arch kernels as EFI pstore functionality in the kernel depends of OLD sysfs-efivars support.}}<br />
<br />
If you have both interfaces enabled, you need to disable one of them, and disable and re-enable the other interface (to refresh the data, to prevent inconsistencies) before accessing the EFI VAR data using any userspace tool:<br />
<br />
To disable sysfs-efivars and refresh efivarfs:<br />
# modprobe -r efivars<br />
<br />
# umount /sys/firmware/efi/efivars<br />
# modprobe -r efivarfs<br />
<br />
# modprobe efivarfs<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
To disable efivarfs and refresh sysfs-efivars:<br />
# umount /sys/firmware/efi/efivars<br />
# modprobe -r efivarfs<br />
<br />
# modprobe -r efivars<br />
# modprobe efivars<br />
<br />
=== Requirements for UEFI Variables support to work properly ===<br />
<br />
# EFI Runtime Services support should be present in the kernel ({{ic|1=CONFIG_EFI=y}}, check if present with {{ic|zgrep CONFIG_EFI /proc/config.gz}}).<br />
# Kernel processor bitness/arch and EFI processor bitness/arch should match<br />
# Kernel should be booted in EFI mode (via [[EFISTUB]] or any [[Boot Loaders|EFI boot loader]], not via BIOS/CSM or Apple's "bootcamp" which is also BIOS/CSM)<br />
# EFI Runtime Services in the kernel SHOULD NOT be disabled via kernel cmdline, i.e. {{ic|noefi}} kernel parameter SHOULD NOT be used<br />
# {{ic|efivarfs}} filesystem should be mounted at {{ic|/sys/firmware/efi/efivars}}, otherwise follow [[#Mount efivarfs]] section below.<br />
# {{ic|efivar}} should list (option {{ic|-l}}) the EFI Variables without any error. For sample output see [[#Sample_List_of_UEFI_Variables]].<br />
<br />
If EFI Variables support does not work even after the above conditions are satisfied, try the below workarounds:<br />
<br />
# If any userspace tool is unable to modify efi variables data, check for existence of {{ic|/sys/firmware/efi/efivars/dump-*}} files. If they exist, delete them, reboot and retry again.<br />
# If the above step does not fix the issue, try booting with {{ic|efi_no_storage_paranoia}} kernel parameter to disable kernel efi variable storage space check that may prevent writing/modification of efi variables.<br />
<br />
{{Note|{{ic|efi_no_storage_paranoia}} should only be used when needed and should not be left as a normal boot option. The effect of this kernel command line parameter turns off a safeguard that was put in place to help avoid the bricking of machines when the NVRAM gets too full.}}<br />
<br />
==== Mount efivarfs ====<br />
<br />
If {{ic|efivarfs}} is not automatically mounted at {{ic|/sys/firmware/efi/efivars}} by [[systemd]] during boot, then you need to manually mount it to expose UEFI Variable support to the userspace tools like {{ic|efibootmgr}} etc.:<br />
<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
{{Note|The above command should be run both OUTSIDE (BEFORE) and INSIDE '''chroot''', if any.}}<br />
<br />
It is also a good idea to auto-mount {{ic|efivarfs}} during boot via {{ic|/etc/fstab}} as follows:<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
efivarfs /sys/firmware/efi/efivars efivarfs defaults 0 0<br />
</nowiki>}}<br />
<br />
=== Userspace Tools ===<br />
<br />
There are few tools that can access/modify the UEFI variables, namely<br />
<br />
# '''efivar''' - Library and Tool to manipulate UEFI Variables (used by vathpela's efibootmgr) - https://github.com/vathpela/efivar - {{Pkg|efivar}} or {{AUR|efivar-git}}<br />
# '''efibootmgr''' - Tool to manipulate UEFI Firmware Boot Manager Settings. Upstream (http://linux.dell.com/git/efibootmgr.git) efibootmgr code does not support efivarfs. A fork of efibootmgr by Fedora's Peter Jones (vathpela) supports both efivarfs and sysfs-efivars. It is currently used in official core/{{Pkg|efibootmgr}} pkg and AUR pkg {{AUR|efibootmgr-pjones-git}} - https://github.com/vathpela/efibootmgr/tree/libefivars<br />
# '''uefivars''' - Dumps list of EFI variables with some additional PCI related info (uses efibootmgr code internally) - https://github.com/fpmurphy/Various/tree/master/uefivars-2.0 supports only efivarfs and https://github.com/fpmurphy/Various/tree/master/uefivars-1.0 supports only sysfs-efivars . AUR package {{AUR|uefivars-git}} <br />
# '''efitools''' - Tools to Create and Setup own UEFI Secure Boot Certificates, Keys and Signed Binaries (requires efivarfs) - {{AUR|efitools-git}}<br />
# '''Ubuntu's Firmware Test Suite''' - https://wiki.ubuntu.com/FirmwareTestSuite/ - {{AUR|fwts}} (along with {{AUR|fwts-efi-runtime-dkms}}) or {{AUR|fwts-git}}<br />
<br />
==== efibootmgr ====<br />
<br />
{{Warning|<br />
* Using {{ic|efibootmgr}} in Apple Macs may brick the firmware and may need reflash of the motherboard ROM. There have been bug reports regarding this in Ubuntu/Launchpad bug tracker. Use bless command alone in case of Macs. Experimental "bless" utility for Linux by Fedora developers - {{AUR|mactel-boot}}.}}<br />
{{Note|<br />
* If {{ic|efibootmgr}} completely fails to work in your system, you can reboot into UEFI Shell v2 and use {{ic|bcfg}} command to create a boot entry for the bootloader.<br />
* If you are unable to use {{ic|efibootmgr}}, some UEFI BIOSes allow users to directly manage uefi boot options from within the BIOS. For example, some ASUS BIOSes have a "Add New Boot Option" choice which enables you to select a local EFI System Partition and manually enter the EFI stub location. (for example {{ic|\EFI\refind\refind_x64.efi}}).<br />
* The below commands use {{Pkg|refind-efi}} boot-loader as example.<br />
}}<br />
<br />
Assuming the boot-loader file to be launched is {{ic|/boot/efi/EFI/refind/refind_x64.efi}}, {{ic|/boot/efi/EFI/refind/refind_x64.efi}} can be split up as {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}}, wherein {{ic|/boot/efi}} is the mountpoint of the EFI System Partition, which is assumed to be {{ic|/dev/sdXY}} (here {{ic|X}} and {{ic|Y}} are just placeholders for the actual values - eg:- in {{ic|/dev/sda1}} , {{ic|1=X==a}} {{ic|1=Y==1}}).<br />
<br />
To determine the actual device path for the EFI System Partition (assuming mountpoint {{ic|/boot/efi}} for example) (should be in the form {{ic|/dev/sdXY}}), try :<br />
<br />
# findmnt /boot/efi<br />
TARGET SOURCE FSTYPE OPTIONS<br />
/boot/efi /dev/sdXY vfat rw,flush,tz=UTC<br />
<br />
Verify that uefi variables support in kernel is working properly by running:<br />
<br />
# efivar -l<br />
<br />
If efivar lists the uefi variables without any error, then you can proceed. If not, check whether all the conditions in [[#Requirements for UEFI Variables support to work properly]] are met.<br />
<br />
Then create the boot entry using efibootmgr as follows:<br />
<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_x64.efi -L "rEFInd"<br />
<br />
{{Note|1=UEFI uses backward slash {{ic|\}} as path separator (similar to Windows paths), but the official {{Pkg|efibootmgr}} pkg support passing unix-style paths with forward-slash {{ic|/}} as path-separator for the {{ic|-l}} option. Efibootmgr internally converts {{ic|/}} to {{ic|\}} before encoding the loader path. The relevant git commit that incorporated this feature in efibootmgr is http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/commit/?id=f38f4aaad1dfa677918e417c9faa6e3286411378 .}}<br />
<br />
In the above command {{ic|/boot/efi/EFI/refind/refind_x64.efi}} translates to {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}} which in turn translate to drive {{ic|/dev/sdX}} -> partition {{ic|Y}} -> file {{ic|/EFI/refind/refind_x64.efi}}.<br />
<br />
The 'label' is the name of the menu entry shown in the UEFI boot menu. This name is user's choice and does not affect the booting of the system. More info can be obtained from [http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/plain/README efibootmgr GIT README] .<br />
<br />
FAT32 filesystem is case-insensitive since it does not use UTF-8 encoding by default. In that case the firmware uses capital 'EFI' instead of small 'efi', therefore using {{ic|\EFI\refind\refindx64.efi}} or {{ic|\efi\refind\refind_x64.efi}} does not matter (this will change if the filesystem encoding is UTF-8).<br />
<br />
== EFI System Partition ==<br />
<br />
The EFI System Partition (also called ESP or EFISYS) is a FAT32 formatted physical partition (in the main partition table of the disk, not LVM or software raid etc.) from where the UEFI firmware launches the UEFI bootloader and application. It is a OS independent partition that acts as the storage place for the EFI bootloaders and applications which the firmware launches them. It is mandatory for UEFI boot. It should be marked as '''EF00''' or '''ef00''' type code in gdisk, or '''boot''' flag in case of GNU Parted (only for GPT disk). It is recommended to keep ESP size at 512 MiB although smaller/larger sizes are fine (smaller sizes provided it is higher than the minimum FAT32 FS partition size limit (as mandated by FAT32 specification from Microsoft). For more info visit [[Wikipedia:EFI_System_partition|link]].<br />
<br />
{{Note|<br />
* It is recommended to use always GPT for UEFI boot as some UEFI firmwares do not allow UEFI-MBR boot.<br />
* In GNU Parted, {{ic|boot}} flag (not to be confused with {{ic|legacy_boot}} flag) has different effect in MBR and GPT disk. In MBR disk, it marks the partition as active. In GPT disk, it changes the type code of the partition to {{ic|EFI System Partition}} type. Parted has no flag to mark a partition as ESP in MBR disk (this can be done using fdisk though).<br />
* Microsoft documentation noted the ESP size: For Advanced Format 4K Native drives (4-KB-per-sector) drives, the minimum size is 260 MB, due to a limitation of the FAT32 file format. The minimum partition size of FAT32 drives is calculated as sector size (4KB) x 65527 &#61; 256 MB. Advanced Format 512e drives are not affected by this limitation, because their emulated sector size is 512 bytes. 512 bytes x 65527 &#61; 32 MB, which is less than the 100 MB minimum size for this partition. From: http://technet.microsoft.com/en-us/library/hh824839.aspx#DiskPartitionRules<br />
* In case of [[EFISTUB]], the kernels and initramfs files should be stored in the EFI System Partition. For sake of simplicity, you can also use the ESP as the {{ic|/boot}} partition itself instead of a separate {{ic|/boot}} partition, for EFISTUB booting.<br />
}}<br />
<br />
=== GPT partitioned disks ===<br />
<br />
* Create a partition with partition type {{ic|ef00}} or {{ic|EF00}} using gdisk (from {{Pkg|gptfdisk}} pkg). Then format that partition as FAT32 using {{ic|mkfs.fat -F32 /dev/<THAT_PARTITION>}} <br />
(or)<br />
* Create a FAT32 partition and in GNU Parted set/activate the {{ic|boot}} flag (not {{ic|legacy_boot}} flag) on that partition<br />
<br />
{{Note|If you get the message {{ic|WARNING: Not enough clusters for a 32 bit FAT!}}, reduce cluster size with {{ic|mkfs.fat -s2 -F32 ...}} or {{ic|-s1}}, otherwise the partition may be unreadable by UEFI.}}<br />
<br />
=== MBR partitioned disks ===<br />
<br />
Create a partition with partition type {{ic|0xEF}} using fdisk (from {{Pkg|util-linux}} pkg). Then format that partition as FAT32 using {{ic|mkfs.fat -F32 /dev/<THAT_PARTITION>}}<br />
<br />
== UEFI Shell ==<br />
<br />
The UEFI Shell is a shell/terminal for the firmware which allows launching uefi applications which include uefi bootloaders. Apart from that, the shell can also be used to obtain various other information about the system or the firmware like memory map (memmap), modifyiang boot manager variables (bcfg), running partitioning programs (diskpart), loading uefi drivers, editing text files (edit), hexedit etc. <br />
<br />
=== Obtaining UEFI Shell ===<br />
<br />
You can download a BSD licensed UEFI Shell from Intel's Tianocore UDK/EDK2 Sourceforge.net project.<br />
<br />
* [[AUR]] '''{{AUR|uefi-shell-svn}}''' pkg (recommended) - provides x86_64 Shell in x86_64 system and IA32 Shell in i686 system - compiled directly from latest Tianocore EDK2 SVN source<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/ShellBinPkg/UefiShell/X64/Shell.efi Precompiled x86_64 UEFI Shell v2 binary] (may not be up-to-date)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/EdkShellBinPkg/FullShell/X64/Shell_Full.efi Precompiled x86_64 UEFI Shell v1 binary] (not updated anymore upstream)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/ShellBinPkg/UefiShell/Ia32/Shell.efi Precompiled IA32 UEFI Shell v2 binary] (may not be up-to-date)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/EdkShellBinPkg/FullShell/Ia32/Shell_Full.efi Precompiled IA32 UEFI Shell v1 binary] (not updated anymore upstream)<br />
<br />
Shell v2 works best in UEFI 2.3+ systems and is recommended over Shell v1 in those systems. Shell v1 should work in all UEFI systems irrespective of the spec. version the firmware follows. More info at [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=ShellPkg ShellPkg] and [http://sourceforge.net/mailarchive/message.php?msg_id=28690732 this mail]<br />
<br />
=== Launching UEFI Shell ===<br />
<br />
Few Asus and other AMI Aptio x86_64 UEFI firmware based motherboards (from Sandy Bridge onwards) provide an option called {{ic|"Launch EFI Shell from filesystem device"}} . For those motherboards, download the x86_64 UEFI Shell and copy it to your EFI System Partition as {{ic|<EFI_SYSTEM_PARTITION>/shellx64.efi}} (mostly {{ic|/boot/efi/shellx64.efi}}) .<br />
<br />
Systems with Phoenix SecureCore Tiano UEFI firmware are known to have embedded UEFI Shell which can be launched using either {{ic|F6}}, {{ic|F11}} or {{ic|F12}} key.<br />
<br />
{{Note|If you are unable to launch UEFI Shell from the firmware directly using any of the above mentioned methods, create a FAT32 USB pen drive with {{ic|Shell.efi}} copied as {{ic|(USB)/efi/boot/bootx64.efi}}. This USB should come up in the firmware boot menu. Launching this option will launch the UEFI Shell for you.}}<br />
<br />
=== Important UEFI Shell Commands ===<br />
<br />
UEFI Shell commands usually support {{ic|-b}} option which makes output pause after each page. {{ic|map}} lists recognized filesystems ({{ic|fs0}}, ...) and data storage devices ({{ic|blk0}}, ...). Run {{ic|help -b}} to list available commands.<br />
<br />
More info at http://software.intel.com/en-us/articles/efi-shells-and-scripting/<br />
<br />
==== bcfg ====<br />
<br />
BCFG command is used to modify the UEFI NVRAM entries, which allow the user to change the boot entries or driver options. This command is described in detail in page 83 (Section 5.3) of "UEFI Shell Specification 2.0" PDF document.<br />
<br />
{{Note|<br />
* Users are recommended to try {{ic|bcfg}} only if {{ic|efibootmgr}} fails to create working boot entries in their system.<br />
* UEFI Shell v1 official binary does not support {{ic|bcfg}} command. You can download a [http://dl.dropbox.com/u/17629062/Shell2.zip modified UEFI Shell v2 binary] which may work in UEFI pre-2.3 firmwares.<br />
}}<br />
<br />
To dump a list of current boot entries:<br />
<br />
Shell> bcfg boot dump -v<br />
<br />
To add a boot menu entry for rEFInd (for example) as 4th (numbering starts from zero) option in the boot menu:<br />
<br />
Shell> bcfg boot add 3 fs0:\EFI\refind\refind_x64.efi "rEFInd"<br />
<br />
where {{ic|fs0:}} is the mapping corresponding to the EFI System Partition and {{ic|fs0:\EFI\refind\refind_x64.efi}} is the file to be launched.<br />
<br />
To remove the 4th boot option:<br />
<br />
Shell> bcfg boot rm 3<br />
<br />
To move the boot option #3 to #0 (i.e. 1st or the default entry in the UEFI Boot menu):<br />
<br />
Shell> bcfg boot mv 3 0<br />
<br />
For bcfg help text:<br />
<br />
Shell> help bcfg -v -b<br />
<br />
or:<br />
<br />
Shell> bcfg -? -v -b<br />
<br />
==== edit ====<br />
<br />
EDIT command provides a basic text editor with an interface similar to nano text editor, but slightly less functional. It handles UTF-8 encoding and takes care or LF vs CRLF line endings.<br />
<br />
To edit, for example rEFInd's {{ic|refind.conf}} in the EFI System Partition ({{ic|fs0:}} in the firmware)<br />
<br />
Shell> fs0:<br />
FS0:\> cd \EFI\arch\refind<br />
FS0:\EFI\arch\refind\> edit refind.conf<br />
<br />
Type {{ic|Ctrl-E}} for help.<br />
<br />
== UEFI Linux Hardware Compatibility ==<br />
<br />
See [[HCL/Firmwares/UEFI]] for the main article.<br />
<br />
== UEFI Bootable Media ==<br />
<br />
=== Create UEFI bootable USB from ISO ===<br />
<br />
Follow [[USB Flash Installation Media#BIOS and UEFI Bootable USB]]<br />
<br />
=== Remove UEFI boot support from Optical Media ===<br />
<br />
{{Note|This section mentions removing UEFI boot support from a '''CD/DVD only''' (Optical Media), not from a USB flash drive.}}<br />
<br />
Most of the 32-bit EFI Macs and some 64-bit EFI Macs refuse to boot from a UEFI(X64)+BIOS bootable CD/DVD. If one wishes to proceed with the installation using optical media, it might be necessary to remove UEFI support first.<br />
<br />
* Mount the official installation media and obtain the {{ic|archisolabel}} as shown in the previous section.<br />
<br />
# mount -o loop ''input.iso'' /mnt/iso<br />
<br />
* Then rebuild the ISO, excluding the UEFI Optical Media booting support, using {{ic|xorriso}} from {{pkg|libisoburn}}<br />
{{bc|1=<br />
$ xorriso -as mkisofs -iso-level 3 \<br />
-full-iso9660-filenames\<br />
-volid "''archisolabel''" \<br />
-appid "Arch Linux CD" \<br />
-publisher "Arch Linux <https://www.archlinux.org>" \<br />
-preparer "prepared by $USER" \<br />
-eltorito-boot isolinux/isolinux.bin \<br />
-eltorito-catalog isolinux/boot.cat \<br />
-no-emul-boot -boot-load-size 4 -boot-info-table \<br />
-isohybrid-mbr "/mnt/iso/isolinux/isohdpfx.bin" \<br />
-output ''output.iso'' /mnt/iso/<br />
}}<br />
<br />
* Burn {{ic|''output.iso''}} to optical media and proceed with installation normally.<br />
<br />
== Testing UEFI in systems without native support ==<br />
<br />
=== OVMF for Virtual Machines ===<br />
<br />
OVMF [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=OVMF] is a tianocore project to enable UEFI support for Virtual Machines. OVMF contains a sample UEFI firmware for QEMU.<br />
<br />
You can build OVMF (with Secure Boot support) from AUR {{AUR|ovmf-svn}} and run it as follows:<br />
<br />
$ qemu-system-x86_64 -enable-kvm -net none -m 1024 -bios /usr/share/ovmf/x86_64/bios.bin <br />
<br />
=== DUET for BIOS only systems ===<br />
<br />
DUET is a tianocore project that enables chainloading a full UEFI environment from a BIOS system, in a way similar to BIOS OS booting. This method is being discussed extensively in http://www.insanelymac.com/forum/topic/186440-linux-and-windows-uefi-boot-using-tianocore-duet-firmware/. Pre-build DUET images can be downloaded from one of the repos at https://gitorious.org/tianocore_uefi_duet_builds. Specific instructions for setting up DUET is available at https://gitorious.org/tianocore_uefi_duet_builds/tianocore_uefi_duet_installer/blobs/raw/master/Migle_BootDuet_INSTALL.txt. <br />
<br />
You can also try http://sourceforge.net/projects/cloverefiboot/ which provides modified DUET images that may contain some system specific fixes and is more frequently updated compared to the gitorious repos.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Windows 7 will not boot in UEFI Mode ===<br />
<br />
If you have installed Windows to a different harddisk with GPT partitioning and still have a MBR partitioned harddisk in your computer, then it is possible that the UEFI BIOS is starting it's CSM support (for booting MBR partitions) and therefor Windows will not boot. To solve this merge your MBR harddisk to GPT partitioning or disable the SATA port where the MBR harddisk is plugged in or unplug the SATA connector from this harddisk.<br />
<br />
Mainboards with this kind of problem:<br />
<br />
Gigabyte Z77X-UD3H rev. 1.1 (UEFI BIOS version F19e)<br />
<br />
- UEFI BIOS option for booting UEFI Only does not pretend the UEFI BIOS from starting CSM<br />
<br />
=== USB media gets struck with black screen ===<br />
<br />
* This issue can occur either due to [[KMS]] issue. Try [[Kernel_Mode_Setting#Disabling_modesetting|Disabling KMS]] while booting the USB.<br />
<br />
* If the issue is not due to KMS, then it may be due to bug in [[EFISTUB]] booting (see [https://bugs.archlinux.org/task/33745] and [https://bbs.archlinux.org/viewtopic.php?id=156670] for more information.). Both Official ISO ([[Archiso]]) and [[Archboot]] iso use EFISTUB (via [[Gummiboot]] Boot Manager for menu) for booting the kernel in UEFI mode. In such a case you have to use [[GRUB]] as the USB's UEFI bootloader by following the below section.<br />
<br />
==== Using GRUB ====<br />
<br />
* Create USB Flash Installation drive as mentioned in [[USB_Flash_Installation_Media#BIOS_and_UEFI_Bootable_USB|link]]. After that follow the below steps to use GRUB instead of Gummiboot.<br />
<br />
* Backup {{ic|<USB>/EFI/boot/loader.efi}} to {{ic|<USB>/EFI/boot/gummiboot.efi}}<br />
<br />
* [[GRUB#GRUB_Standalone|Create a GRUB standalone image]] and copy it to {{ic|<USB>/EFI/boot/loader.efi}}<br />
<br />
* Create {{ic|<USB>/EFI/boot/grub.cfg}} with the following contents:<br />
<br />
{{hc|grub.cfg for Official ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux archiso x86_64" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --label ARCHISO_XXXXXX<br />
linux /arch/boot/x86_64/vmlinuz archisobasedir=arch archisolabel=ARCHISO_XXXXXX add_efi_memmap<br />
initrd /arch/boot/x86_64/archiso.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --label ARCHISO_XXXXXX<br />
chainloader /EFI/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --label ARCHISO_XXXXXX<br />
chainloader /EFI/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
{{hc|grub.cfg for Archboot ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux x86_64 Archboot" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
linux /boot/vmlinuz_x86_64 cgroup_disable=memory loglevel=7 add_efi_memmap<br />
initrd /boot/initramfs_x86_64.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:UEFI]]<br />
* [[Wikipedia:EFI System partition]]<br />
* [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt Linux Kernel x86_64 UEFI Documentation]<br />
* [http://www.uefi.org/home/ UEFI Forum] - contains the official [http://www.uefi.org/specs/ UEFI Specifications] - GUID Partition Table is part of UEFI Specification<br />
* [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Welcome_to_TianoCore Intel's Tianocore Project] for Open-Source UEFI firmware which includes DuetPkg for direct BIOS based booting and OvmfPkg used in QEMU and Oracle VirtualBox<br />
* [http://uefidk.intel.com/ Intel UEFI Community Resource Center]<br />
* [http://www.intel.com/technology/efi/ Intel's page on EFI]<br />
* [http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/efi-boot-process.html FGA: The EFI boot process]<br />
* [http://www.microsoft.com/whdc/device/storage/GPT_FAQ.mspx Microsoft's Windows and GPT FAQ] - Contains info on Windows UEFI booting also<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Windows_x64_BIOS_to_UEFI Convert Windows Vista SP1+ or 7 x86_64 boot from BIOS-MBR mode to UEFI-GPT mode without Reinstall]<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Linux_Windows_BIOS_UEFI_boot_USB Create a Linux BIOS+UEFI and Windows x64 BIOS+UEFI bootable USB drive]<br />
* [http://rodsbooks.com/bios2uefi/ Rod Smith - A BIOS to UEFI Transformation]<br />
* [https://lkml.org/lkml/2011/6/8/322 UEFI Boot problems on some newer machines (LKML)]<br />
* [http://software.intel.com/en-us/articles/efi-shells-and-scripting/ EFI Shells and Scripting - Intel Documentation]<br />
* [http://software.intel.com/en-us/articles/uefi-shell/ UEFI Shell - Intel Documentation]<br />
* [http://www.hpuxtips.es/?q=node/293 UEFI Shell - bcfg command info]<br />
* [http://dl.dropbox.com/u/17629062/Shell2.zip UEFI Shell v2 binary with bcfg modified to work with UEFI pre-2.3 firmware - from Clover efiboot]<br />
* [http://linuxplumbers.ubicast.tv/videos/plumbing-uefi-into-linux/ LPC 2012 Plumbing UEFI into Linux]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-1/ LPC 2012 UEFI Tutorial : part 1]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-2/ LPC 2012 UEFI Tutorial : part 2]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Unified_Extensible_Firmware_Interface&diff=294815Unified Extensible Firmware Interface2014-01-28T23:14:52Z<p>Netskink: /* File Extensions */ work in progress</p>
<hr />
<div>[[Category:Boot process]]<br />
[[es:Unified Extensible Firmware Interface]]<br />
[[it:Unified Extensible Firmware Interface]]<br />
[[ja:Unified Extensible Firmware Interface]]<br />
[[ru:Unified Extensible Firmware Interface]]<br />
[[zh-CN:Unified Extensible Firmware Interface]]<br />
{{Related articles start}}<br />
{{Related|Arch Boot Process}}<br />
{{Related|Master Boot Record}}<br />
{{Related|GUID Partition Table}}<br />
{{Related articles end}}<br />
<br />
'''Unified Extensible Firmware Interface''' (or UEFI for short) is a new type of firmware that was initially designed by Intel (known as EFI then) mainly for its Itanium based systems. It introduces new ways of booting an OS that is distinct from the commonly used "[[MBR]] boot code" method followed for [[Wikipedia:BIOS|BIOS]] systems. It started as Intel's EFI in versions 1.x and then a group of companies called the UEFI Forum took over its development from which it was called Unified EFI starting with version 2.0. As of 24 July 2013, UEFI Specification 2.4 (released July 11, 2013) is the most recent version.<br />
<br />
{{Note|<br />
* This page explains '''What is UEFI''' and '''UEFI support in Linux kernel'''. It does not describe setting up UEFI Boot Loaders. For that information see [[Boot Loaders]].<br />
* Unless specified as EFI 1.x, EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware. Also unless stated explicitly, these instructions are general and some of them may not work or may be different in Apple Macs. Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one (U)EFI specification and therefore is not a standard UEFI firmware.}}<br />
<br />
== Differences between BIOS and UEFI ==<br />
See [[Arch_Boot_Process#Firmware_types]] for more details.<br />
<br />
== Boot Process under UEFI ==<br />
<br />
# System switched on - Power On Self Test, or POST process.<br />
# UEFI firmware is loaded. Firmware initializes the hardware required for booting.<br />
# Firmware then reads its Boot Manager data to determine which UEFI application to be launched and from where (i.e. from which disk and partition).<br />
# Firmware then launches the UEFI application as defined in the boot entry in the firmware's boot manager.<br />
# The launched UEFI application may launch another application (in case of UEFI Shell or a boot manager like rEFInd) or the kernel and initramfs (in case of a boot loader like GRUB) depending on how the UEFI application was configured.<br />
<br />
{{Note|On some UEFI systems the only possible way to launch UEFI application on boot (if it does not have custom entry in UEFI boot menu) is to put it in this fixed location: {{ic|<EFI SYSTEM PARTITION>/EFI/boot/bootx64.efi}} (for 64-bit x86 system)}}<br />
<br />
=== Multibooting in UEFI ===<br />
<br />
Since each OS or vendor can maintain its own files within the EFI System Partition without affecting the other, multi-booting using UEFI is just a matter of launching a different UEFI application corresponding to the particular OS's bootloader. This removes the need for relying on chainloading mechanisms of one [[Boot Loaders|boot loader]] to load another to switch OSes.<br />
<br />
==== Booting Microsoft Windows ====<br />
<br />
64-bit Windows Vista (SP1+), Windows 7 and Windows 8 versions support booting using x86_64 EFI firmware. Windows forces type of partitioning depending on the firmware used, i.e. if Windows is booted in UEFI mode, it can be installed only to a GPT disk. If the Windows is booted in Legacy BIOS mode, it can be installed only to a MBR disk. This is a limitation enforced by Windows installer. Thus Windows supports either UEFI-GPT boot or BIOS-MBR boot only, not UEFI-MBR or BIOS-GPT boot. <br />
<br />
Such a limitation is not enforced by the Linux kernel, but can depend on how the bootloader is configured. The Windows limitation should be considered if the user wishes to boot Windows and Linux from the same disk, since setting up the bootloader itself depends on the firmware type and disk partitioning used. In case where Windows and Linux dual boot from the same disk, it is advisable to follow the method used by Windows, either go for UEFI-GPT boot or BIOS-MBR boot only, not the other two cases.<br />
<br />
32-bit Windows versions only support BIOS-MBR booting. So, in case of Linux and 32-bit Windows booting from the same disk, the disk has to use MBR. See http://support.microsoft.com/kb/2581408 for more info.<br />
<br />
=== Detecting UEFI Firmware bitness ===<br />
<br />
==== Non Macs ====<br />
<br />
Check whether the dir {{ic|/sys/firmware/efi}} exists, if it exists it means the kernel has booted in EFI mode. In that case the UEFI bitness is same as kernel bitness. (ie. i686 or x86_64)<br />
<br />
{{Note|Intel Atom System-on-Chip systems ship with 32-bit UEFI (as on 2 November 2013). See [[HCL/Firmwares/UEFI#Intel_Atom_System-on-Chip|this page]] for more info.}}<br />
<br />
==== Apple Macs ====<br />
<br />
Pre-2008 Macs mostly have i386-efi firmware while >=2008 Macs have mostly x86_64-efi. All Macs capable of running Mac OS X Snow Leopard 64-bit Kernel have x86_64 EFI 1.x firmware. <br />
<br />
To find out the arch of the efi firmware in a Mac, type the following into the Mac OS X terminal:<br />
<br />
ioreg -l -p IODeviceTree | grep firmware-abi<br />
<br />
If the command returns EFI32 then it is IA32 (32-bit) EFI firmware. If it returns EFI64 then it is x86_64 EFI firmware. Most of the Macs do not have UEFI 2.x firmware as Apple's EFI implementation is not fully compliant with UEFI 2.x Specification.<br />
<br />
=== Secure Boot ===<br />
For an overview about Secure Boot in Linux see http://www.rodsbooks.com/efi-bootloaders/secureboot.html. This section focuses on how to set up Secure Boot in Arch Linux. For the time being, this section is limited to explain the procedure of booting the archiso with Secure Boot enabled.<br />
Booting the archiso with Secure Boot enabled is possible since the efi applications ''PreLoader.efi'' and ''HashTool.efi'' have been added to it. A message will show up that says ''Failed to Start loader... I will now execute HashTool.'' To use HashTool for enrolling the hash of ''loader.efi'' and ''vmlinuz.efi'', follow these steps.<br />
* Select {{ic|OK}}<br />
* In the HashTool main menu, select {{ic|Enroll Hash}}, choose {{ic|\loader.efi}} and confirm with {{ic|Yes}}. Again, select {{ic|Enroll Hash}} and {{ic|archiso}} to enter the archiso directory, then select {{ic|vmlinuz-efi}} and confirm with {{ic|Yes}}. Then choose {{ic|Exit}} to return to the boot device selection menu.<br />
* In the boot device selection menu choose {{ic|Arch Linux archiso x86_64 UEFI CD}}<br />
The archiso boots, and you are presented with a shell prompt, automatically logged in as root. To check if the archiso was booted with SecureBoot, use this command:<br />
<br />
$ od -An -t u1 /sys/firmware/efi/vars/SecureBoot-1234abcde-5678-/data<br />
<br />
If yes, this command returns 1. The characters denoted by 1234 differ from machine to machine. To help with this, you can use tab completion or list the efi variables.<br />
<br />
== Linux Kernel Config options for UEFI ==<br />
<br />
The required Linux Kernel configuration options for UEFI systems are :<br />
<br />
CONFIG_RELOCATABLE=y<br />
CONFIG_EFI=y<br />
CONFIG_EFI_STUB=y<br />
CONFIG_FB_EFI=y<br />
CONFIG_FRAMEBUFFER_CONSOLE=y<br />
<br />
UEFI Runtime Variables Support ('''efivarfs''' filesystem - {{ic|/sys/firmware/efi/efivars}}). This option is important as this is required to manipulate UEFI Runtime Variables using tools like {{ic|/usr/bin/efibootmgr}}. The below config option has been added in kernel 3.10 and above.<br />
<br />
CONFIG_EFIVAR_FS=y<br />
<br />
UEFI Runtime Variables Support (old '''efivars sysfs''' interface - {{ic|/sys/firmware/efi/vars}}). This option should be disabled.<br />
<br />
CONFIG_EFI_VARS=n<br />
<br />
GUID Partition Table [[GPT]] config option - mandatory for UEFI support<br />
<br />
CONFIG_EFI_PARTITION=y<br />
<br />
{{Note|All of the above options are required to boot Linux via UEFI, and are enabled in Archlinux kernels in official repos.}}<br />
<br />
Retrieved from https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt .<br />
<br />
== UEFI Variables ==<br />
<br />
UEFI defines variables through which an operating system can interact with the firmware. UEFI Boot Variables are used by the boot-loader and used by the OS only for early system start-up. UEFI Runtime Variables allow an OS to manage certain settings of the firmware like the UEFI Boot Manager or managing the keys for UEFI Secure Boot Protocol etc. You can get the list using <br />
$ efivar -l<br />
<br />
=== UEFI Variables Support in Linux Kernel ===<br />
<br />
Linux kernel exposes EFI variables data to userspace via 2 interfaces:<br />
<br />
* '''OLD sysfs-efivars''' interface (CONFIG_EFI_VARS) - populated by {{ic|efivars}} kernel module at {{ic|/sys/firmware/efi/vars}} - 1024 byte maximum per-variable data size limitation, no UEFI Secure Boot variables support (due to the size limitation) and not recommended by kernel upstream anymore. Still supported by kernel upstream but '''completely disabled in Arch's official kernels'''.<br />
<br />
* '''NEW efivarfs''' ('''EFI''' '''VAR'''iable '''F'''ile'''S'''ystem) interface (CONFIG_EFIVAR_FS) - mounted using {{ic|efivarfs}} kernel module at {{ic|/sys/firmware/efi/efivars}} - replacement for the OLD sysfs-efivars interface, has no maximum per-variable size limitation, supports UEFI Secure Boot variables and recommended by kernel upstream. Introduced in kernel 3.8 and NEW {{ic|efivarfs}} module split from OLD {{ic|efivars}} kernel module in kernel 3.10 .<br />
<br />
==== Inconsistency between efivarfs and sysfs-efivars ====<br />
<br />
Enabling both OLD sysfs-efivars and NEW efivarfs can cause data inconsistency issues (see See https://lkml.org/lkml/2013/4/16/473 for more info). Due to this OLD sysfs-efivars is completely disabled in Arch's official kernels (since '''core/{{Pkg|linux}}-3.11''' and '''core/{{Pkg|linux-lts}}-3.10''') and only NEW efivarfs is enabled/supported going forward. All the UEFI Variables related tools and utilities in [[official repositories]] support efivarfs as of 01 October 2013.<br />
<br />
{{Note|As a side-effect of disabling OLD sysfs-efivars, {{ic|efi_pstore}} module is also disabled in the official Arch kernels as EFI pstore functionality in the kernel depends of OLD sysfs-efivars support.}}<br />
<br />
If you have both interfaces enabled, you need to disable one of them, and disable and re-enable the other interface (to refresh the data, to prevent inconsistencies) before accessing the EFI VAR data using any userspace tool:<br />
<br />
To disable sysfs-efivars and refresh efivarfs:<br />
# modprobe -r efivars<br />
<br />
# umount /sys/firmware/efi/efivars<br />
# modprobe -r efivarfs<br />
<br />
# modprobe efivarfs<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
To disable efivarfs and refresh sysfs-efivars:<br />
# umount /sys/firmware/efi/efivars<br />
# modprobe -r efivarfs<br />
<br />
# modprobe -r efivars<br />
# modprobe efivars<br />
<br />
=== Requirements for UEFI Variables support to work properly ===<br />
<br />
# EFI Runtime Services support should be present in the kernel ({{ic|1=CONFIG_EFI=y}}, check if present with {{ic|zgrep CONFIG_EFI /proc/config.gz}}).<br />
# Kernel processor bitness/arch and EFI processor bitness/arch should match<br />
# Kernel should be booted in EFI mode (via [[EFISTUB]] or any [[Boot Loaders|EFI boot loader]], not via BIOS/CSM or Apple's "bootcamp" which is also BIOS/CSM)<br />
# EFI Runtime Services in the kernel SHOULD NOT be disabled via kernel cmdline, i.e. {{ic|noefi}} kernel parameter SHOULD NOT be used<br />
# {{ic|efivarfs}} filesystem should be mounted at {{ic|/sys/firmware/efi/efivars}}, otherwise follow [[#Mount efivarfs]] section below.<br />
# {{ic|efivar}} should list (option {{ic|-l}}) the EFI Variables without any error. For sample output see [[#Sample_List_of_UEFI_Variables]].<br />
<br />
If EFI Variables support does not work even after the above conditions are satisfied, try the below workarounds:<br />
<br />
# If any userspace tool is unable to modify efi variables data, check for existence of {{ic|/sys/firmware/efi/efivars/dump-*}} files. If they exist, delete them, reboot and retry again.<br />
# If the above step does not fix the issue, try booting with {{ic|efi_no_storage_paranoia}} kernel parameter to disable kernel efi variable storage space check that may prevent writing/modification of efi variables.<br />
<br />
{{Note|{{ic|efi_no_storage_paranoia}} should only be used when needed and should not be left as a normal boot option. The effect of this kernel command line parameter turns off a safeguard that was put in place to help avoid the bricking of machines when the NVRAM gets too full.}}<br />
<br />
==== Mount efivarfs ====<br />
<br />
If {{ic|efivarfs}} is not automatically mounted at {{ic|/sys/firmware/efi/efivars}} by [[systemd]] during boot, then you need to manually mount it to expose UEFI Variable support to the userspace tools like {{ic|efibootmgr}} etc.:<br />
<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
{{Note|The above command should be run both OUTSIDE (BEFORE) and INSIDE '''chroot''', if any.}}<br />
<br />
It is also a good idea to auto-mount {{ic|efivarfs}} during boot via {{ic|/etc/fstab}} as follows:<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
efivarfs /sys/firmware/efi/efivars efivarfs defaults 0 0<br />
</nowiki>}}<br />
<br />
=== Userspace Tools ===<br />
<br />
There are few tools that can access/modify the UEFI variables, namely<br />
<br />
# '''efivar''' - Library and Tool to manipulate UEFI Variables (used by vathpela's efibootmgr) - https://github.com/vathpela/efivar - {{Pkg|efivar}} or {{AUR|efivar-git}}<br />
# '''efibootmgr''' - Tool to manipulate UEFI Firmware Boot Manager Settings. Upstream (http://linux.dell.com/git/efibootmgr.git) efibootmgr code does not support efivarfs. A fork of efibootmgr by Fedora's Peter Jones (vathpela) supports both efivarfs and sysfs-efivars. It is currently used in official core/{{Pkg|efibootmgr}} pkg and AUR pkg {{AUR|efibootmgr-pjones-git}} - https://github.com/vathpela/efibootmgr/tree/libefivars<br />
# '''uefivars''' - Dumps list of EFI variables with some additional PCI related info (uses efibootmgr code internally) - https://github.com/fpmurphy/Various/tree/master/uefivars-2.0 supports only efivarfs and https://github.com/fpmurphy/Various/tree/master/uefivars-1.0 supports only sysfs-efivars . AUR package {{AUR|uefivars-git}} <br />
# '''efitools''' - Tools to Create and Setup own UEFI Secure Boot Certificates, Keys and Signed Binaries (requires efivarfs) - {{AUR|efitools-git}}<br />
# '''Ubuntu's Firmware Test Suite''' - https://wiki.ubuntu.com/FirmwareTestSuite/ - {{AUR|fwts}} (along with {{AUR|fwts-efi-runtime-dkms}}) or {{AUR|fwts-git}}<br />
<br />
==== efibootmgr ====<br />
<br />
{{Warning|<br />
* Using {{ic|efibootmgr}} in Apple Macs may brick the firmware and may need reflash of the motherboard ROM. There have been bug reports regarding this in Ubuntu/Launchpad bug tracker. Use bless command alone in case of Macs. Experimental "bless" utility for Linux by Fedora developers - {{AUR|mactel-boot}}.}}<br />
{{Note|<br />
* If {{ic|efibootmgr}} completely fails to work in your system, you can reboot into UEFI Shell v2 and use {{ic|bcfg}} command to create a boot entry for the bootloader.<br />
* If you are unable to use {{ic|efibootmgr}}, some UEFI BIOSes allow users to directly manage uefi boot options from within the BIOS. For example, some ASUS BIOSes have a "Add New Boot Option" choice which enables you to select a local EFI System Partition and manually enter the EFI stub location. (for example {{ic|\EFI\refind\refind_x64.efi}}).<br />
* The below commands use {{Pkg|refind-efi}} boot-loader as example.<br />
}}<br />
<br />
Assuming the boot-loader file to be launched is {{ic|/boot/efi/EFI/refind/refind_x64.efi}}, {{ic|/boot/efi/EFI/refind/refind_x64.efi}} can be split up as {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}}, wherein {{ic|/boot/efi}} is the mountpoint of the EFI System Partition, which is assumed to be {{ic|/dev/sdXY}} (here {{ic|X}} and {{ic|Y}} are just placeholders for the actual values - eg:- in {{ic|/dev/sda1}} , {{ic|1=X==a}} {{ic|1=Y==1}}).<br />
<br />
To determine the actual device path for the EFI System Partition (assuming mountpoint {{ic|/boot/efi}} for example) (should be in the form {{ic|/dev/sdXY}}), try :<br />
<br />
# findmnt /boot/efi<br />
TARGET SOURCE FSTYPE OPTIONS<br />
/boot/efi /dev/sdXY vfat rw,flush,tz=UTC<br />
<br />
Verify that uefi variables support in kernel is working properly by running:<br />
<br />
# efivar -l<br />
<br />
If efivar lists the uefi variables without any error, then you can proceed. If not, check whether all the conditions in [[#Requirements for UEFI Variables support to work properly]] are met.<br />
<br />
Then create the boot entry using efibootmgr as follows:<br />
<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_x64.efi -L "rEFInd"<br />
<br />
{{Note|1=UEFI uses backward slash {{ic|\}} as path separator (similar to Windows paths), but the official {{Pkg|efibootmgr}} pkg support passing unix-style paths with forward-slash {{ic|/}} as path-separator for the {{ic|-l}} option. Efibootmgr internally converts {{ic|/}} to {{ic|\}} before encoding the loader path. The relevant git commit that incorporated this feature in efibootmgr is http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/commit/?id=f38f4aaad1dfa677918e417c9faa6e3286411378 .}}<br />
<br />
In the above command {{ic|/boot/efi/EFI/refind/refind_x64.efi}} translates to {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}} which in turn translate to drive {{ic|/dev/sdX}} -> partition {{ic|Y}} -> file {{ic|/EFI/refind/refind_x64.efi}}.<br />
<br />
The 'label' is the name of the menu entry shown in the UEFI boot menu. This name is user's choice and does not affect the booting of the system. More info can be obtained from [http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/plain/README efibootmgr GIT README] .<br />
<br />
FAT32 filesystem is case-insensitive since it does not use UTF-8 encoding by default. In that case the firmware uses capital 'EFI' instead of small 'efi', therefore using {{ic|\EFI\refind\refindx64.efi}} or {{ic|\efi\refind\refind_x64.efi}} does not matter (this will change if the filesystem encoding is UTF-8).<br />
<br />
== EFI System Partition ==<br />
<br />
The EFI System Partition (also called ESP or EFISYS) is a FAT32 formatted physical partition (in the main partition table of the disk, not LVM or software raid etc.) from where the UEFI firmware launches the UEFI bootloader and application. It is a OS independent partition that acts as the storage place for the EFI bootloaders and applications which the firmware launches them. It is mandatory for UEFI boot. It should be marked as '''EF00''' or '''ef00''' type code in gdisk, or '''boot''' flag in case of GNU Parted (only for GPT disk). It is recommended to keep ESP size at 512 MiB although smaller/larger sizes are fine (smaller sizes provided it is higher than the minimum FAT32 FS partition size limit (as mandated by FAT32 specification from Microsoft). For more info visit [[Wikipedia:EFI_System_partition|link]].<br />
<br />
{{Note|<br />
* It is recommended to use always GPT for UEFI boot as some UEFI firmwares do not allow UEFI-MBR boot.<br />
* In GNU Parted, {{ic|boot}} flag (not to be confused with {{ic|legacy_boot}} flag) has different effect in MBR and GPT disk. In MBR disk, it marks the partition as active. In GPT disk, it changes the type code of the partition to {{ic|EFI System Partition}} type. Parted has no flag to mark a partition as ESP in MBR disk (this can be done using fdisk though).<br />
* Microsoft documentation noted the ESP size: For Advanced Format 4K Native drives (4-KB-per-sector) drives, the minimum size is 260 MB, due to a limitation of the FAT32 file format. The minimum partition size of FAT32 drives is calculated as sector size (4KB) x 65527 &#61; 256 MB. Advanced Format 512e drives are not affected by this limitation, because their emulated sector size is 512 bytes. 512 bytes x 65527 &#61; 32 MB, which is less than the 100 MB minimum size for this partition. From: http://technet.microsoft.com/en-us/library/hh824839.aspx#DiskPartitionRules<br />
* In case of [[EFISTUB]], the kernels and initramfs files should be stored in the EFI System Partition. For sake of simplicity, you can also use the ESP as the {{ic|/boot}} partition itself instead of a separate {{ic|/boot}} partition, for EFISTUB booting.<br />
}}<br />
<br />
=== GPT partitioned disks ===<br />
<br />
* Create a partition with partition type {{ic|ef00}} or {{ic|EF00}} using gdisk (from {{Pkg|gptfdisk}} pkg). Then format that partition as FAT32 using {{ic|mkfs.fat -F32 /dev/<THAT_PARTITION>}} <br />
(or)<br />
* Create a FAT32 partition and in GNU Parted set/activate the {{ic|boot}} flag (not {{ic|legacy_boot}} flag) on that partition<br />
<br />
{{Note|If you get the message {{ic|WARNING: Not enough clusters for a 32 bit FAT!}}, reduce cluster size with {{ic|mkfs.fat -s2 -F32 ...}} or {{ic|-s1}}, otherwise the partition may be unreadable by UEFI.}}<br />
<br />
=== MBR partitioned disks ===<br />
<br />
Create a partition with partition type {{ic|0xEF}} using fdisk (from {{Pkg|util-linux}} pkg). Then format that partition as FAT32 using {{ic|mkfs.fat -F32 /dev/<THAT_PARTITION>}}<br />
<br />
== UEFI Shell ==<br />
<br />
The UEFI Shell is a shell/terminal for the firmware which allows launching uefi applications which include uefi bootloaders. Apart from that, the shell can also be used to obtain various other information about the system or the firmware like memory map (memmap), modifyiang boot manager variables (bcfg), running partitioning programs (diskpart), loading uefi drivers, editing text files (edit), hexedit etc. <br />
<br />
=== Obtaining UEFI Shell ===<br />
<br />
You can download a BSD licensed UEFI Shell from Intel's Tianocore UDK/EDK2 Sourceforge.net project.<br />
<br />
* [[AUR]] '''{{AUR|uefi-shell-svn}}''' pkg (recommended) - provides x86_64 Shell in x86_64 system and IA32 Shell in i686 system - compiled directly from latest Tianocore EDK2 SVN source<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/ShellBinPkg/UefiShell/X64/Shell.efi Precompiled x86_64 UEFI Shell v2 binary] (may not be up-to-date)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/EdkShellBinPkg/FullShell/X64/Shell_Full.efi Precompiled x86_64 UEFI Shell v1 binary] (not updated anymore upstream)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/ShellBinPkg/UefiShell/Ia32/Shell.efi Precompiled IA32 UEFI Shell v2 binary] (may not be up-to-date)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/EdkShellBinPkg/FullShell/Ia32/Shell_Full.efi Precompiled IA32 UEFI Shell v1 binary] (not updated anymore upstream)<br />
<br />
Shell v2 works best in UEFI 2.3+ systems and is recommended over Shell v1 in those systems. Shell v1 should work in all UEFI systems irrespective of the spec. version the firmware follows. More info at [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=ShellPkg ShellPkg] and [http://sourceforge.net/mailarchive/message.php?msg_id=28690732 this mail]<br />
<br />
=== Launching UEFI Shell ===<br />
<br />
Few Asus and other AMI Aptio x86_64 UEFI firmware based motherboards (from Sandy Bridge onwards) provide an option called {{ic|"Launch EFI Shell from filesystem device"}} . For those motherboards, download the x86_64 UEFI Shell and copy it to your EFI System Partition as {{ic|<EFI_SYSTEM_PARTITION>/shellx64.efi}} (mostly {{ic|/boot/efi/shellx64.efi}}) .<br />
<br />
Systems with Phoenix SecureCore Tiano UEFI firmware are known to have embedded UEFI Shell which can be launched using either {{ic|F6}}, {{ic|F11}} or {{ic|F12}} key.<br />
<br />
{{Note|If you are unable to launch UEFI Shell from the firmware directly using any of the above mentioned methods, create a FAT32 USB pen drive with {{ic|Shell.efi}} copied as {{ic|(USB)/efi/boot/bootx64.efi}}. This USB should come up in the firmware boot menu. Launching this option will launch the UEFI Shell for you.}}<br />
<br />
=== Important UEFI Shell Commands ===<br />
<br />
UEFI Shell commands usually support {{ic|-b}} option which makes output pause after each page. {{ic|map}} lists recognized filesystems ({{ic|fs0}}, ...) and data storage devices ({{ic|blk0}}, ...). Run {{ic|help -b}} to list available commands.<br />
<br />
More info at http://software.intel.com/en-us/articles/efi-shells-and-scripting/<br />
<br />
==== bcfg ====<br />
<br />
BCFG command is used to modify the UEFI NVRAM entries, which allow the user to change the boot entries or driver options. This command is described in detail in page 83 (Section 5.3) of "UEFI Shell Specification 2.0" PDF document.<br />
<br />
{{Note|<br />
* Users are recommended to try {{ic|bcfg}} only if {{ic|efibootmgr}} fails to create working boot entries in their system.<br />
* UEFI Shell v1 official binary does not support {{ic|bcfg}} command. You can download a [http://dl.dropbox.com/u/17629062/Shell2.zip modified UEFI Shell v2 binary] which may work in UEFI pre-2.3 firmwares.<br />
}}<br />
<br />
To dump a list of current boot entries:<br />
<br />
Shell> bcfg boot dump -v<br />
<br />
To add a boot menu entry for rEFInd (for example) as 4th (numbering starts from zero) option in the boot menu:<br />
<br />
Shell> bcfg boot add 3 fs0:\EFI\refind\refind_x64.efi "rEFInd"<br />
<br />
where {{ic|fs0:}} is the mapping corresponding to the EFI System Partition and {{ic|fs0:\EFI\refind\refind_x64.efi}} is the file to be launched.<br />
<br />
To remove the 4th boot option:<br />
<br />
Shell> bcfg boot rm 3<br />
<br />
To move the boot option #3 to #0 (i.e. 1st or the default entry in the UEFI Boot menu):<br />
<br />
Shell> bcfg boot mv 3 0<br />
<br />
For bcfg help text:<br />
<br />
Shell> help bcfg -v -b<br />
<br />
or:<br />
<br />
Shell> bcfg -? -v -b<br />
<br />
==== edit ====<br />
<br />
EDIT command provides a basic text editor with an interface similar to nano text editor, but slightly less functional. It handles UTF-8 encoding and takes care or LF vs CRLF line endings.<br />
<br />
To edit, for example rEFInd's {{ic|refind.conf}} in the EFI System Partition ({{ic|fs0:}} in the firmware)<br />
<br />
Shell> fs0:<br />
FS0:\> cd \EFI\arch\refind<br />
FS0:\EFI\arch\refind\> edit refind.conf<br />
<br />
Type {{ic|Ctrl-E}} for help.<br />
<br />
== UEFI Linux Hardware Compatibility ==<br />
<br />
See [[HCL/Firmwares/UEFI]] for the main article.<br />
<br />
== UEFI Bootable Media ==<br />
<br />
=== Create UEFI bootable USB from ISO ===<br />
<br />
Follow [[USB Flash Installation Media#BIOS and UEFI Bootable USB]]<br />
<br />
=== Remove UEFI boot support from Optical Media ===<br />
<br />
{{Note|This section mentions removing UEFI boot support from a '''CD/DVD only''' (Optical Media), not from a USB flash drive.}}<br />
<br />
Most of the 32-bit EFI Macs and some 64-bit EFI Macs refuse to boot from a UEFI(X64)+BIOS bootable CD/DVD. If one wishes to proceed with the installation using optical media, it might be necessary to remove UEFI support first.<br />
<br />
* Mount the official installation media and obtain the {{ic|archisolabel}} as shown in the previous section.<br />
<br />
# mount -o loop ''input.iso'' /mnt/iso<br />
<br />
* Then rebuild the ISO, excluding the UEFI Optical Media booting support, using {{ic|xorriso}} from {{pkg|libisoburn}}<br />
{{bc|1=<br />
$ xorriso -as mkisofs -iso-level 3 \<br />
-full-iso9660-filenames\<br />
-volid "''archisolabel''" \<br />
-appid "Arch Linux CD" \<br />
-publisher "Arch Linux <https://www.archlinux.org>" \<br />
-preparer "prepared by $USER" \<br />
-eltorito-boot isolinux/isolinux.bin \<br />
-eltorito-catalog isolinux/boot.cat \<br />
-no-emul-boot -boot-load-size 4 -boot-info-table \<br />
-isohybrid-mbr "/mnt/iso/isolinux/isohdpfx.bin" \<br />
-output ''output.iso'' /mnt/iso/<br />
}}<br />
<br />
* Burn {{ic|''output.iso''}} to optical media and proceed with installation normally.<br />
<br />
== Testing UEFI in systems without native support ==<br />
<br />
=== OVMF for Virtual Machines ===<br />
<br />
OVMF [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=OVMF] is a tianocore project to enable UEFI support for Virtual Machines. OVMF contains a sample UEFI firmware for QEMU.<br />
<br />
You can build OVMF (with Secure Boot support) from AUR {{AUR|ovmf-svn}} and run it as follows:<br />
<br />
$ qemu-system-x86_64 -enable-kvm -net none -m 1024 -bios /usr/share/ovmf/x86_64/bios.bin <br />
<br />
=== DUET for BIOS only systems ===<br />
<br />
DUET is a tianocore project that enables chainloading a full UEFI environment from a BIOS system, in a way similar to BIOS OS booting. This method is being discussed extensively in http://www.insanelymac.com/forum/topic/186440-linux-and-windows-uefi-boot-using-tianocore-duet-firmware/. Pre-build DUET images can be downloaded from one of the repos at https://gitorious.org/tianocore_uefi_duet_builds. Specific instructions for setting up DUET is available at https://gitorious.org/tianocore_uefi_duet_builds/tianocore_uefi_duet_installer/blobs/raw/master/Migle_BootDuet_INSTALL.txt. <br />
<br />
You can also try http://sourceforge.net/projects/cloverefiboot/ which provides modified DUET images that may contain some system specific fixes and is more frequently updated compared to the gitorious repos.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Windows 7 will not boot in UEFI Mode ===<br />
<br />
If you have installed Windows to a different harddisk with GPT partitioning and still have a MBR partitioned harddisk in your computer, then it is possible that the UEFI BIOS is starting it's CSM support (for booting MBR partitions) and therefor Windows will not boot. To solve this merge your MBR harddisk to GPT partitioning or disable the SATA port where the MBR harddisk is plugged in or unplug the SATA connector from this harddisk.<br />
<br />
Mainboards with this kind of problem:<br />
<br />
Gigabyte Z77X-UD3H rev. 1.1 (UEFI BIOS version F19e)<br />
<br />
- UEFI BIOS option for booting UEFI Only does not pretend the UEFI BIOS from starting CSM<br />
<br />
=== USB media gets struck with black screen ===<br />
<br />
* This issue can occur either due to [[KMS]] issue. Try [[Kernel_Mode_Setting#Disabling_modesetting|Disabling KMS]] while booting the USB.<br />
<br />
* If the issue is not due to KMS, then it may be due to bug in [[EFISTUB]] booting (see [https://bugs.archlinux.org/task/33745] and [https://bbs.archlinux.org/viewtopic.php?id=156670] for more information.). Both Official ISO ([[Archiso]]) and [[Archboot]] iso use EFISTUB (via [[Gummiboot]] Boot Manager for menu) for booting the kernel in UEFI mode. In such a case you have to use [[GRUB]] as the USB's UEFI bootloader by following the below section.<br />
<br />
==== Using GRUB ====<br />
<br />
* Create USB Flash Installation drive as mentioned in [[USB_Flash_Installation_Media#BIOS_and_UEFI_Bootable_USB|link]]. After that follow the below steps to use GRUB instead of Gummiboot.<br />
<br />
* Backup {{ic|<USB>/EFI/boot/loader.efi}} to {{ic|<USB>/EFI/boot/gummiboot.efi}}<br />
<br />
* [[GRUB#GRUB_Standalone|Create a GRUB standalone image]] and copy it to {{ic|<USB>/EFI/boot/loader.efi}}<br />
<br />
* Create {{ic|<USB>/EFI/boot/grub.cfg}} with the following contents:<br />
<br />
{{hc|grub.cfg for Official ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux archiso x86_64" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --label ARCHISO_XXXXXX<br />
linux /arch/boot/x86_64/vmlinuz archisobasedir=arch archisolabel=ARCHISO_XXXXXX add_efi_memmap<br />
initrd /arch/boot/x86_64/archiso.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --label ARCHISO_XXXXXX<br />
chainloader /EFI/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --label ARCHISO_XXXXXX<br />
chainloader /EFI/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
{{hc|grub.cfg for Archboot ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux x86_64 Archboot" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
linux /boot/vmlinuz_x86_64 cgroup_disable=memory loglevel=7 add_efi_memmap<br />
initrd /boot/initramfs_x86_64.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
== File Extensions ==<br />
<br />
These are the file extensions encountered when building UEFI using the tianocore EDKII.<br />
<br />
{| class="wikitable" border="1" cellpadding="5" cellspacing="0"<br />
! File Extension !! Description <br />
|-<br />
| .app || An intermediate DXE application program file that is produced by the GenFfsFile build tool from .pkg, .dpx, .sst, .pei and .pe32 files. <br />
|-<br />
| .asm || Assembly source code file <br />
|-<br />
| .bin || A binary file that is produced by the Pe2Bin build tool from .exe and also produced by other build tools.<br />
|-<br />
| .bin1 || An intermediate file that is produced by the SplitFile build tool from a .bin file. This file is not used.<br />
|-<br />
| .bin2 || An intermediate file that is produced by the SplitFile build tool from a .bin file.<br />
|-<br />
| .c || C source code file<br />
|-<br />
|to be completed<br />
|}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:UEFI]]<br />
* [[Wikipedia:EFI System partition]]<br />
* [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt Linux Kernel x86_64 UEFI Documentation]<br />
* [http://www.uefi.org/home/ UEFI Forum] - contains the official [http://www.uefi.org/specs/ UEFI Specifications] - GUID Partition Table is part of UEFI Specification<br />
* [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Welcome_to_TianoCore Intel's Tianocore Project] for Open-Source UEFI firmware which includes DuetPkg for direct BIOS based booting and OvmfPkg used in QEMU and Oracle VirtualBox<br />
* [http://uefidk.intel.com/ Intel UEFI Community Resource Center]<br />
* [http://www.intel.com/technology/efi/ Intel's page on EFI]<br />
* [http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/efi-boot-process.html FGA: The EFI boot process]<br />
* [http://www.microsoft.com/whdc/device/storage/GPT_FAQ.mspx Microsoft's Windows and GPT FAQ] - Contains info on Windows UEFI booting also<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Windows_x64_BIOS_to_UEFI Convert Windows Vista SP1+ or 7 x86_64 boot from BIOS-MBR mode to UEFI-GPT mode without Reinstall]<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Linux_Windows_BIOS_UEFI_boot_USB Create a Linux BIOS+UEFI and Windows x64 BIOS+UEFI bootable USB drive]<br />
* [http://rodsbooks.com/bios2uefi/ Rod Smith - A BIOS to UEFI Transformation]<br />
* [https://lkml.org/lkml/2011/6/8/322 UEFI Boot problems on some newer machines (LKML)]<br />
* [http://software.intel.com/en-us/articles/efi-shells-and-scripting/ EFI Shells and Scripting - Intel Documentation]<br />
* [http://software.intel.com/en-us/articles/uefi-shell/ UEFI Shell - Intel Documentation]<br />
* [http://www.hpuxtips.es/?q=node/293 UEFI Shell - bcfg command info]<br />
* [http://dl.dropbox.com/u/17629062/Shell2.zip UEFI Shell v2 binary with bcfg modified to work with UEFI pre-2.3 firmware - from Clover efiboot]<br />
* [http://linuxplumbers.ubicast.tv/videos/plumbing-uefi-into-linux/ LPC 2012 Plumbing UEFI into Linux]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-1/ LPC 2012 UEFI Tutorial : part 1]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-2/ LPC 2012 UEFI Tutorial : part 2]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Unified_Extensible_Firmware_Interface&diff=294813Unified Extensible Firmware Interface2014-01-28T23:06:55Z<p>Netskink: tianocore has a lot of documentation in pdf form which is not in wiki form. Archlinux can use uefi and its a mess of tangled documentation. Starting new sections here since this is a more user friendly contribution wiki..</p>
<hr />
<div>[[Category:Boot process]]<br />
[[es:Unified Extensible Firmware Interface]]<br />
[[it:Unified Extensible Firmware Interface]]<br />
[[ja:Unified Extensible Firmware Interface]]<br />
[[ru:Unified Extensible Firmware Interface]]<br />
[[zh-CN:Unified Extensible Firmware Interface]]<br />
{{Related articles start}}<br />
{{Related|Arch Boot Process}}<br />
{{Related|Master Boot Record}}<br />
{{Related|GUID Partition Table}}<br />
{{Related articles end}}<br />
<br />
'''Unified Extensible Firmware Interface''' (or UEFI for short) is a new type of firmware that was initially designed by Intel (known as EFI then) mainly for its Itanium based systems. It introduces new ways of booting an OS that is distinct from the commonly used "[[MBR]] boot code" method followed for [[Wikipedia:BIOS|BIOS]] systems. It started as Intel's EFI in versions 1.x and then a group of companies called the UEFI Forum took over its development from which it was called Unified EFI starting with version 2.0. As of 24 July 2013, UEFI Specification 2.4 (released July 11, 2013) is the most recent version.<br />
<br />
{{Note|<br />
* This page explains '''What is UEFI''' and '''UEFI support in Linux kernel'''. It does not describe setting up UEFI Boot Loaders. For that information see [[Boot Loaders]].<br />
* Unless specified as EFI 1.x, EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware. Also unless stated explicitly, these instructions are general and some of them may not work or may be different in Apple Macs. Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one (U)EFI specification and therefore is not a standard UEFI firmware.}}<br />
<br />
== Differences between BIOS and UEFI ==<br />
See [[Arch_Boot_Process#Firmware_types]] for more details.<br />
<br />
== Boot Process under UEFI ==<br />
<br />
# System switched on - Power On Self Test, or POST process.<br />
# UEFI firmware is loaded. Firmware initializes the hardware required for booting.<br />
# Firmware then reads its Boot Manager data to determine which UEFI application to be launched and from where (i.e. from which disk and partition).<br />
# Firmware then launches the UEFI application as defined in the boot entry in the firmware's boot manager.<br />
# The launched UEFI application may launch another application (in case of UEFI Shell or a boot manager like rEFInd) or the kernel and initramfs (in case of a boot loader like GRUB) depending on how the UEFI application was configured.<br />
<br />
{{Note|On some UEFI systems the only possible way to launch UEFI application on boot (if it does not have custom entry in UEFI boot menu) is to put it in this fixed location: {{ic|<EFI SYSTEM PARTITION>/EFI/boot/bootx64.efi}} (for 64-bit x86 system)}}<br />
<br />
=== Multibooting in UEFI ===<br />
<br />
Since each OS or vendor can maintain its own files within the EFI System Partition without affecting the other, multi-booting using UEFI is just a matter of launching a different UEFI application corresponding to the particular OS's bootloader. This removes the need for relying on chainloading mechanisms of one [[Boot Loaders|boot loader]] to load another to switch OSes.<br />
<br />
==== Booting Microsoft Windows ====<br />
<br />
64-bit Windows Vista (SP1+), Windows 7 and Windows 8 versions support booting using x86_64 EFI firmware. Windows forces type of partitioning depending on the firmware used, i.e. if Windows is booted in UEFI mode, it can be installed only to a GPT disk. If the Windows is booted in Legacy BIOS mode, it can be installed only to a MBR disk. This is a limitation enforced by Windows installer. Thus Windows supports either UEFI-GPT boot or BIOS-MBR boot only, not UEFI-MBR or BIOS-GPT boot. <br />
<br />
Such a limitation is not enforced by the Linux kernel, but can depend on how the bootloader is configured. The Windows limitation should be considered if the user wishes to boot Windows and Linux from the same disk, since setting up the bootloader itself depends on the firmware type and disk partitioning used. In case where Windows and Linux dual boot from the same disk, it is advisable to follow the method used by Windows, either go for UEFI-GPT boot or BIOS-MBR boot only, not the other two cases.<br />
<br />
32-bit Windows versions only support BIOS-MBR booting. So, in case of Linux and 32-bit Windows booting from the same disk, the disk has to use MBR. See http://support.microsoft.com/kb/2581408 for more info.<br />
<br />
=== Detecting UEFI Firmware bitness ===<br />
<br />
==== Non Macs ====<br />
<br />
Check whether the dir {{ic|/sys/firmware/efi}} exists, if it exists it means the kernel has booted in EFI mode. In that case the UEFI bitness is same as kernel bitness. (ie. i686 or x86_64)<br />
<br />
{{Note|Intel Atom System-on-Chip systems ship with 32-bit UEFI (as on 2 November 2013). See [[HCL/Firmwares/UEFI#Intel_Atom_System-on-Chip|this page]] for more info.}}<br />
<br />
==== Apple Macs ====<br />
<br />
Pre-2008 Macs mostly have i386-efi firmware while >=2008 Macs have mostly x86_64-efi. All Macs capable of running Mac OS X Snow Leopard 64-bit Kernel have x86_64 EFI 1.x firmware. <br />
<br />
To find out the arch of the efi firmware in a Mac, type the following into the Mac OS X terminal:<br />
<br />
ioreg -l -p IODeviceTree | grep firmware-abi<br />
<br />
If the command returns EFI32 then it is IA32 (32-bit) EFI firmware. If it returns EFI64 then it is x86_64 EFI firmware. Most of the Macs do not have UEFI 2.x firmware as Apple's EFI implementation is not fully compliant with UEFI 2.x Specification.<br />
<br />
=== Secure Boot ===<br />
For an overview about Secure Boot in Linux see http://www.rodsbooks.com/efi-bootloaders/secureboot.html. This section focuses on how to set up Secure Boot in Arch Linux. For the time being, this section is limited to explain the procedure of booting the archiso with Secure Boot enabled.<br />
Booting the archiso with Secure Boot enabled is possible since the efi applications ''PreLoader.efi'' and ''HashTool.efi'' have been added to it. A message will show up that says ''Failed to Start loader... I will now execute HashTool.'' To use HashTool for enrolling the hash of ''loader.efi'' and ''vmlinuz.efi'', follow these steps.<br />
* Select {{ic|OK}}<br />
* In the HashTool main menu, select {{ic|Enroll Hash}}, choose {{ic|\loader.efi}} and confirm with {{ic|Yes}}. Again, select {{ic|Enroll Hash}} and {{ic|archiso}} to enter the archiso directory, then select {{ic|vmlinuz-efi}} and confirm with {{ic|Yes}}. Then choose {{ic|Exit}} to return to the boot device selection menu.<br />
* In the boot device selection menu choose {{ic|Arch Linux archiso x86_64 UEFI CD}}<br />
The archiso boots, and you are presented with a shell prompt, automatically logged in as root. To check if the archiso was booted with SecureBoot, use this command:<br />
<br />
$ od -An -t u1 /sys/firmware/efi/vars/SecureBoot-1234abcde-5678-/data<br />
<br />
If yes, this command returns 1. The characters denoted by 1234 differ from machine to machine. To help with this, you can use tab completion or list the efi variables.<br />
<br />
== Linux Kernel Config options for UEFI ==<br />
<br />
The required Linux Kernel configuration options for UEFI systems are :<br />
<br />
CONFIG_RELOCATABLE=y<br />
CONFIG_EFI=y<br />
CONFIG_EFI_STUB=y<br />
CONFIG_FB_EFI=y<br />
CONFIG_FRAMEBUFFER_CONSOLE=y<br />
<br />
UEFI Runtime Variables Support ('''efivarfs''' filesystem - {{ic|/sys/firmware/efi/efivars}}). This option is important as this is required to manipulate UEFI Runtime Variables using tools like {{ic|/usr/bin/efibootmgr}}. The below config option has been added in kernel 3.10 and above.<br />
<br />
CONFIG_EFIVAR_FS=y<br />
<br />
UEFI Runtime Variables Support (old '''efivars sysfs''' interface - {{ic|/sys/firmware/efi/vars}}). This option should be disabled.<br />
<br />
CONFIG_EFI_VARS=n<br />
<br />
GUID Partition Table [[GPT]] config option - mandatory for UEFI support<br />
<br />
CONFIG_EFI_PARTITION=y<br />
<br />
{{Note|All of the above options are required to boot Linux via UEFI, and are enabled in Archlinux kernels in official repos.}}<br />
<br />
Retrieved from https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt .<br />
<br />
== UEFI Variables ==<br />
<br />
UEFI defines variables through which an operating system can interact with the firmware. UEFI Boot Variables are used by the boot-loader and used by the OS only for early system start-up. UEFI Runtime Variables allow an OS to manage certain settings of the firmware like the UEFI Boot Manager or managing the keys for UEFI Secure Boot Protocol etc. You can get the list using <br />
$ efivar -l<br />
<br />
=== UEFI Variables Support in Linux Kernel ===<br />
<br />
Linux kernel exposes EFI variables data to userspace via 2 interfaces:<br />
<br />
* '''OLD sysfs-efivars''' interface (CONFIG_EFI_VARS) - populated by {{ic|efivars}} kernel module at {{ic|/sys/firmware/efi/vars}} - 1024 byte maximum per-variable data size limitation, no UEFI Secure Boot variables support (due to the size limitation) and not recommended by kernel upstream anymore. Still supported by kernel upstream but '''completely disabled in Arch's official kernels'''.<br />
<br />
* '''NEW efivarfs''' ('''EFI''' '''VAR'''iable '''F'''ile'''S'''ystem) interface (CONFIG_EFIVAR_FS) - mounted using {{ic|efivarfs}} kernel module at {{ic|/sys/firmware/efi/efivars}} - replacement for the OLD sysfs-efivars interface, has no maximum per-variable size limitation, supports UEFI Secure Boot variables and recommended by kernel upstream. Introduced in kernel 3.8 and NEW {{ic|efivarfs}} module split from OLD {{ic|efivars}} kernel module in kernel 3.10 .<br />
<br />
==== Inconsistency between efivarfs and sysfs-efivars ====<br />
<br />
Enabling both OLD sysfs-efivars and NEW efivarfs can cause data inconsistency issues (see See https://lkml.org/lkml/2013/4/16/473 for more info). Due to this OLD sysfs-efivars is completely disabled in Arch's official kernels (since '''core/{{Pkg|linux}}-3.11''' and '''core/{{Pkg|linux-lts}}-3.10''') and only NEW efivarfs is enabled/supported going forward. All the UEFI Variables related tools and utilities in [[official repositories]] support efivarfs as of 01 October 2013.<br />
<br />
{{Note|As a side-effect of disabling OLD sysfs-efivars, {{ic|efi_pstore}} module is also disabled in the official Arch kernels as EFI pstore functionality in the kernel depends of OLD sysfs-efivars support.}}<br />
<br />
If you have both interfaces enabled, you need to disable one of them, and disable and re-enable the other interface (to refresh the data, to prevent inconsistencies) before accessing the EFI VAR data using any userspace tool:<br />
<br />
To disable sysfs-efivars and refresh efivarfs:<br />
# modprobe -r efivars<br />
<br />
# umount /sys/firmware/efi/efivars<br />
# modprobe -r efivarfs<br />
<br />
# modprobe efivarfs<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
To disable efivarfs and refresh sysfs-efivars:<br />
# umount /sys/firmware/efi/efivars<br />
# modprobe -r efivarfs<br />
<br />
# modprobe -r efivars<br />
# modprobe efivars<br />
<br />
=== Requirements for UEFI Variables support to work properly ===<br />
<br />
# EFI Runtime Services support should be present in the kernel ({{ic|1=CONFIG_EFI=y}}, check if present with {{ic|zgrep CONFIG_EFI /proc/config.gz}}).<br />
# Kernel processor bitness/arch and EFI processor bitness/arch should match<br />
# Kernel should be booted in EFI mode (via [[EFISTUB]] or any [[Boot Loaders|EFI boot loader]], not via BIOS/CSM or Apple's "bootcamp" which is also BIOS/CSM)<br />
# EFI Runtime Services in the kernel SHOULD NOT be disabled via kernel cmdline, i.e. {{ic|noefi}} kernel parameter SHOULD NOT be used<br />
# {{ic|efivarfs}} filesystem should be mounted at {{ic|/sys/firmware/efi/efivars}}, otherwise follow [[#Mount efivarfs]] section below.<br />
# {{ic|efivar}} should list (option {{ic|-l}}) the EFI Variables without any error. For sample output see [[#Sample_List_of_UEFI_Variables]].<br />
<br />
If EFI Variables support does not work even after the above conditions are satisfied, try the below workarounds:<br />
<br />
# If any userspace tool is unable to modify efi variables data, check for existence of {{ic|/sys/firmware/efi/efivars/dump-*}} files. If they exist, delete them, reboot and retry again.<br />
# If the above step does not fix the issue, try booting with {{ic|efi_no_storage_paranoia}} kernel parameter to disable kernel efi variable storage space check that may prevent writing/modification of efi variables.<br />
<br />
{{Note|{{ic|efi_no_storage_paranoia}} should only be used when needed and should not be left as a normal boot option. The effect of this kernel command line parameter turns off a safeguard that was put in place to help avoid the bricking of machines when the NVRAM gets too full.}}<br />
<br />
==== Mount efivarfs ====<br />
<br />
If {{ic|efivarfs}} is not automatically mounted at {{ic|/sys/firmware/efi/efivars}} by [[systemd]] during boot, then you need to manually mount it to expose UEFI Variable support to the userspace tools like {{ic|efibootmgr}} etc.:<br />
<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
{{Note|The above command should be run both OUTSIDE (BEFORE) and INSIDE '''chroot''', if any.}}<br />
<br />
It is also a good idea to auto-mount {{ic|efivarfs}} during boot via {{ic|/etc/fstab}} as follows:<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
efivarfs /sys/firmware/efi/efivars efivarfs defaults 0 0<br />
</nowiki>}}<br />
<br />
=== Userspace Tools ===<br />
<br />
There are few tools that can access/modify the UEFI variables, namely<br />
<br />
# '''efivar''' - Library and Tool to manipulate UEFI Variables (used by vathpela's efibootmgr) - https://github.com/vathpela/efivar - {{Pkg|efivar}} or {{AUR|efivar-git}}<br />
# '''efibootmgr''' - Tool to manipulate UEFI Firmware Boot Manager Settings. Upstream (http://linux.dell.com/git/efibootmgr.git) efibootmgr code does not support efivarfs. A fork of efibootmgr by Fedora's Peter Jones (vathpela) supports both efivarfs and sysfs-efivars. It is currently used in official core/{{Pkg|efibootmgr}} pkg and AUR pkg {{AUR|efibootmgr-pjones-git}} - https://github.com/vathpela/efibootmgr/tree/libefivars<br />
# '''uefivars''' - Dumps list of EFI variables with some additional PCI related info (uses efibootmgr code internally) - https://github.com/fpmurphy/Various/tree/master/uefivars-2.0 supports only efivarfs and https://github.com/fpmurphy/Various/tree/master/uefivars-1.0 supports only sysfs-efivars . AUR package {{AUR|uefivars-git}} <br />
# '''efitools''' - Tools to Create and Setup own UEFI Secure Boot Certificates, Keys and Signed Binaries (requires efivarfs) - {{AUR|efitools-git}}<br />
# '''Ubuntu's Firmware Test Suite''' - https://wiki.ubuntu.com/FirmwareTestSuite/ - {{AUR|fwts}} (along with {{AUR|fwts-efi-runtime-dkms}}) or {{AUR|fwts-git}}<br />
<br />
==== efibootmgr ====<br />
<br />
{{Warning|<br />
* Using {{ic|efibootmgr}} in Apple Macs may brick the firmware and may need reflash of the motherboard ROM. There have been bug reports regarding this in Ubuntu/Launchpad bug tracker. Use bless command alone in case of Macs. Experimental "bless" utility for Linux by Fedora developers - {{AUR|mactel-boot}}.}}<br />
{{Note|<br />
* If {{ic|efibootmgr}} completely fails to work in your system, you can reboot into UEFI Shell v2 and use {{ic|bcfg}} command to create a boot entry for the bootloader.<br />
* If you are unable to use {{ic|efibootmgr}}, some UEFI BIOSes allow users to directly manage uefi boot options from within the BIOS. For example, some ASUS BIOSes have a "Add New Boot Option" choice which enables you to select a local EFI System Partition and manually enter the EFI stub location. (for example {{ic|\EFI\refind\refind_x64.efi}}).<br />
* The below commands use {{Pkg|refind-efi}} boot-loader as example.<br />
}}<br />
<br />
Assuming the boot-loader file to be launched is {{ic|/boot/efi/EFI/refind/refind_x64.efi}}, {{ic|/boot/efi/EFI/refind/refind_x64.efi}} can be split up as {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}}, wherein {{ic|/boot/efi}} is the mountpoint of the EFI System Partition, which is assumed to be {{ic|/dev/sdXY}} (here {{ic|X}} and {{ic|Y}} are just placeholders for the actual values - eg:- in {{ic|/dev/sda1}} , {{ic|1=X==a}} {{ic|1=Y==1}}).<br />
<br />
To determine the actual device path for the EFI System Partition (assuming mountpoint {{ic|/boot/efi}} for example) (should be in the form {{ic|/dev/sdXY}}), try :<br />
<br />
# findmnt /boot/efi<br />
TARGET SOURCE FSTYPE OPTIONS<br />
/boot/efi /dev/sdXY vfat rw,flush,tz=UTC<br />
<br />
Verify that uefi variables support in kernel is working properly by running:<br />
<br />
# efivar -l<br />
<br />
If efivar lists the uefi variables without any error, then you can proceed. If not, check whether all the conditions in [[#Requirements for UEFI Variables support to work properly]] are met.<br />
<br />
Then create the boot entry using efibootmgr as follows:<br />
<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_x64.efi -L "rEFInd"<br />
<br />
{{Note|1=UEFI uses backward slash {{ic|\}} as path separator (similar to Windows paths), but the official {{Pkg|efibootmgr}} pkg support passing unix-style paths with forward-slash {{ic|/}} as path-separator for the {{ic|-l}} option. Efibootmgr internally converts {{ic|/}} to {{ic|\}} before encoding the loader path. The relevant git commit that incorporated this feature in efibootmgr is http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/commit/?id=f38f4aaad1dfa677918e417c9faa6e3286411378 .}}<br />
<br />
In the above command {{ic|/boot/efi/EFI/refind/refind_x64.efi}} translates to {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}} which in turn translate to drive {{ic|/dev/sdX}} -> partition {{ic|Y}} -> file {{ic|/EFI/refind/refind_x64.efi}}.<br />
<br />
The 'label' is the name of the menu entry shown in the UEFI boot menu. This name is user's choice and does not affect the booting of the system. More info can be obtained from [http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/plain/README efibootmgr GIT README] .<br />
<br />
FAT32 filesystem is case-insensitive since it does not use UTF-8 encoding by default. In that case the firmware uses capital 'EFI' instead of small 'efi', therefore using {{ic|\EFI\refind\refindx64.efi}} or {{ic|\efi\refind\refind_x64.efi}} does not matter (this will change if the filesystem encoding is UTF-8).<br />
<br />
== EFI System Partition ==<br />
<br />
The EFI System Partition (also called ESP or EFISYS) is a FAT32 formatted physical partition (in the main partition table of the disk, not LVM or software raid etc.) from where the UEFI firmware launches the UEFI bootloader and application. It is a OS independent partition that acts as the storage place for the EFI bootloaders and applications which the firmware launches them. It is mandatory for UEFI boot. It should be marked as '''EF00''' or '''ef00''' type code in gdisk, or '''boot''' flag in case of GNU Parted (only for GPT disk). It is recommended to keep ESP size at 512 MiB although smaller/larger sizes are fine (smaller sizes provided it is higher than the minimum FAT32 FS partition size limit (as mandated by FAT32 specification from Microsoft). For more info visit [[Wikipedia:EFI_System_partition|link]].<br />
<br />
{{Note|<br />
* It is recommended to use always GPT for UEFI boot as some UEFI firmwares do not allow UEFI-MBR boot.<br />
* In GNU Parted, {{ic|boot}} flag (not to be confused with {{ic|legacy_boot}} flag) has different effect in MBR and GPT disk. In MBR disk, it marks the partition as active. In GPT disk, it changes the type code of the partition to {{ic|EFI System Partition}} type. Parted has no flag to mark a partition as ESP in MBR disk (this can be done using fdisk though).<br />
* Microsoft documentation noted the ESP size: For Advanced Format 4K Native drives (4-KB-per-sector) drives, the minimum size is 260 MB, due to a limitation of the FAT32 file format. The minimum partition size of FAT32 drives is calculated as sector size (4KB) x 65527 &#61; 256 MB. Advanced Format 512e drives are not affected by this limitation, because their emulated sector size is 512 bytes. 512 bytes x 65527 &#61; 32 MB, which is less than the 100 MB minimum size for this partition. From: http://technet.microsoft.com/en-us/library/hh824839.aspx#DiskPartitionRules<br />
* In case of [[EFISTUB]], the kernels and initramfs files should be stored in the EFI System Partition. For sake of simplicity, you can also use the ESP as the {{ic|/boot}} partition itself instead of a separate {{ic|/boot}} partition, for EFISTUB booting.<br />
}}<br />
<br />
=== GPT partitioned disks ===<br />
<br />
* Create a partition with partition type {{ic|ef00}} or {{ic|EF00}} using gdisk (from {{Pkg|gptfdisk}} pkg). Then format that partition as FAT32 using {{ic|mkfs.fat -F32 /dev/<THAT_PARTITION>}} <br />
(or)<br />
* Create a FAT32 partition and in GNU Parted set/activate the {{ic|boot}} flag (not {{ic|legacy_boot}} flag) on that partition<br />
<br />
{{Note|If you get the message {{ic|WARNING: Not enough clusters for a 32 bit FAT!}}, reduce cluster size with {{ic|mkfs.fat -s2 -F32 ...}} or {{ic|-s1}}, otherwise the partition may be unreadable by UEFI.}}<br />
<br />
=== MBR partitioned disks ===<br />
<br />
Create a partition with partition type {{ic|0xEF}} using fdisk (from {{Pkg|util-linux}} pkg). Then format that partition as FAT32 using {{ic|mkfs.fat -F32 /dev/<THAT_PARTITION>}}<br />
<br />
== UEFI Shell ==<br />
<br />
The UEFI Shell is a shell/terminal for the firmware which allows launching uefi applications which include uefi bootloaders. Apart from that, the shell can also be used to obtain various other information about the system or the firmware like memory map (memmap), modifyiang boot manager variables (bcfg), running partitioning programs (diskpart), loading uefi drivers, editing text files (edit), hexedit etc. <br />
<br />
=== Obtaining UEFI Shell ===<br />
<br />
You can download a BSD licensed UEFI Shell from Intel's Tianocore UDK/EDK2 Sourceforge.net project.<br />
<br />
* [[AUR]] '''{{AUR|uefi-shell-svn}}''' pkg (recommended) - provides x86_64 Shell in x86_64 system and IA32 Shell in i686 system - compiled directly from latest Tianocore EDK2 SVN source<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/ShellBinPkg/UefiShell/X64/Shell.efi Precompiled x86_64 UEFI Shell v2 binary] (may not be up-to-date)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/EdkShellBinPkg/FullShell/X64/Shell_Full.efi Precompiled x86_64 UEFI Shell v1 binary] (not updated anymore upstream)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/ShellBinPkg/UefiShell/Ia32/Shell.efi Precompiled IA32 UEFI Shell v2 binary] (may not be up-to-date)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/EdkShellBinPkg/FullShell/Ia32/Shell_Full.efi Precompiled IA32 UEFI Shell v1 binary] (not updated anymore upstream)<br />
<br />
Shell v2 works best in UEFI 2.3+ systems and is recommended over Shell v1 in those systems. Shell v1 should work in all UEFI systems irrespective of the spec. version the firmware follows. More info at [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=ShellPkg ShellPkg] and [http://sourceforge.net/mailarchive/message.php?msg_id=28690732 this mail]<br />
<br />
=== Launching UEFI Shell ===<br />
<br />
Few Asus and other AMI Aptio x86_64 UEFI firmware based motherboards (from Sandy Bridge onwards) provide an option called {{ic|"Launch EFI Shell from filesystem device"}} . For those motherboards, download the x86_64 UEFI Shell and copy it to your EFI System Partition as {{ic|<EFI_SYSTEM_PARTITION>/shellx64.efi}} (mostly {{ic|/boot/efi/shellx64.efi}}) .<br />
<br />
Systems with Phoenix SecureCore Tiano UEFI firmware are known to have embedded UEFI Shell which can be launched using either {{ic|F6}}, {{ic|F11}} or {{ic|F12}} key.<br />
<br />
{{Note|If you are unable to launch UEFI Shell from the firmware directly using any of the above mentioned methods, create a FAT32 USB pen drive with {{ic|Shell.efi}} copied as {{ic|(USB)/efi/boot/bootx64.efi}}. This USB should come up in the firmware boot menu. Launching this option will launch the UEFI Shell for you.}}<br />
<br />
=== Important UEFI Shell Commands ===<br />
<br />
UEFI Shell commands usually support {{ic|-b}} option which makes output pause after each page. {{ic|map}} lists recognized filesystems ({{ic|fs0}}, ...) and data storage devices ({{ic|blk0}}, ...). Run {{ic|help -b}} to list available commands.<br />
<br />
More info at http://software.intel.com/en-us/articles/efi-shells-and-scripting/<br />
<br />
==== bcfg ====<br />
<br />
BCFG command is used to modify the UEFI NVRAM entries, which allow the user to change the boot entries or driver options. This command is described in detail in page 83 (Section 5.3) of "UEFI Shell Specification 2.0" PDF document.<br />
<br />
{{Note|<br />
* Users are recommended to try {{ic|bcfg}} only if {{ic|efibootmgr}} fails to create working boot entries in their system.<br />
* UEFI Shell v1 official binary does not support {{ic|bcfg}} command. You can download a [http://dl.dropbox.com/u/17629062/Shell2.zip modified UEFI Shell v2 binary] which may work in UEFI pre-2.3 firmwares.<br />
}}<br />
<br />
To dump a list of current boot entries:<br />
<br />
Shell> bcfg boot dump -v<br />
<br />
To add a boot menu entry for rEFInd (for example) as 4th (numbering starts from zero) option in the boot menu:<br />
<br />
Shell> bcfg boot add 3 fs0:\EFI\refind\refind_x64.efi "rEFInd"<br />
<br />
where {{ic|fs0:}} is the mapping corresponding to the EFI System Partition and {{ic|fs0:\EFI\refind\refind_x64.efi}} is the file to be launched.<br />
<br />
To remove the 4th boot option:<br />
<br />
Shell> bcfg boot rm 3<br />
<br />
To move the boot option #3 to #0 (i.e. 1st or the default entry in the UEFI Boot menu):<br />
<br />
Shell> bcfg boot mv 3 0<br />
<br />
For bcfg help text:<br />
<br />
Shell> help bcfg -v -b<br />
<br />
or:<br />
<br />
Shell> bcfg -? -v -b<br />
<br />
==== edit ====<br />
<br />
EDIT command provides a basic text editor with an interface similar to nano text editor, but slightly less functional. It handles UTF-8 encoding and takes care or LF vs CRLF line endings.<br />
<br />
To edit, for example rEFInd's {{ic|refind.conf}} in the EFI System Partition ({{ic|fs0:}} in the firmware)<br />
<br />
Shell> fs0:<br />
FS0:\> cd \EFI\arch\refind<br />
FS0:\EFI\arch\refind\> edit refind.conf<br />
<br />
Type {{ic|Ctrl-E}} for help.<br />
<br />
== UEFI Linux Hardware Compatibility ==<br />
<br />
See [[HCL/Firmwares/UEFI]] for the main article.<br />
<br />
== UEFI Bootable Media ==<br />
<br />
=== Create UEFI bootable USB from ISO ===<br />
<br />
Follow [[USB Flash Installation Media#BIOS and UEFI Bootable USB]]<br />
<br />
=== Remove UEFI boot support from Optical Media ===<br />
<br />
{{Note|This section mentions removing UEFI boot support from a '''CD/DVD only''' (Optical Media), not from a USB flash drive.}}<br />
<br />
Most of the 32-bit EFI Macs and some 64-bit EFI Macs refuse to boot from a UEFI(X64)+BIOS bootable CD/DVD. If one wishes to proceed with the installation using optical media, it might be necessary to remove UEFI support first.<br />
<br />
* Mount the official installation media and obtain the {{ic|archisolabel}} as shown in the previous section.<br />
<br />
# mount -o loop ''input.iso'' /mnt/iso<br />
<br />
* Then rebuild the ISO, excluding the UEFI Optical Media booting support, using {{ic|xorriso}} from {{pkg|libisoburn}}<br />
{{bc|1=<br />
$ xorriso -as mkisofs -iso-level 3 \<br />
-full-iso9660-filenames\<br />
-volid "''archisolabel''" \<br />
-appid "Arch Linux CD" \<br />
-publisher "Arch Linux <https://www.archlinux.org>" \<br />
-preparer "prepared by $USER" \<br />
-eltorito-boot isolinux/isolinux.bin \<br />
-eltorito-catalog isolinux/boot.cat \<br />
-no-emul-boot -boot-load-size 4 -boot-info-table \<br />
-isohybrid-mbr "/mnt/iso/isolinux/isohdpfx.bin" \<br />
-output ''output.iso'' /mnt/iso/<br />
}}<br />
<br />
* Burn {{ic|''output.iso''}} to optical media and proceed with installation normally.<br />
<br />
== Testing UEFI in systems without native support ==<br />
<br />
=== OVMF for Virtual Machines ===<br />
<br />
OVMF [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=OVMF] is a tianocore project to enable UEFI support for Virtual Machines. OVMF contains a sample UEFI firmware for QEMU.<br />
<br />
You can build OVMF (with Secure Boot support) from AUR {{AUR|ovmf-svn}} and run it as follows:<br />
<br />
$ qemu-system-x86_64 -enable-kvm -net none -m 1024 -bios /usr/share/ovmf/x86_64/bios.bin <br />
<br />
=== DUET for BIOS only systems ===<br />
<br />
DUET is a tianocore project that enables chainloading a full UEFI environment from a BIOS system, in a way similar to BIOS OS booting. This method is being discussed extensively in http://www.insanelymac.com/forum/topic/186440-linux-and-windows-uefi-boot-using-tianocore-duet-firmware/. Pre-build DUET images can be downloaded from one of the repos at https://gitorious.org/tianocore_uefi_duet_builds. Specific instructions for setting up DUET is available at https://gitorious.org/tianocore_uefi_duet_builds/tianocore_uefi_duet_installer/blobs/raw/master/Migle_BootDuet_INSTALL.txt. <br />
<br />
You can also try http://sourceforge.net/projects/cloverefiboot/ which provides modified DUET images that may contain some system specific fixes and is more frequently updated compared to the gitorious repos.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Windows 7 will not boot in UEFI Mode ===<br />
<br />
If you have installed Windows to a different harddisk with GPT partitioning and still have a MBR partitioned harddisk in your computer, then it is possible that the UEFI BIOS is starting it's CSM support (for booting MBR partitions) and therefor Windows will not boot. To solve this merge your MBR harddisk to GPT partitioning or disable the SATA port where the MBR harddisk is plugged in or unplug the SATA connector from this harddisk.<br />
<br />
Mainboards with this kind of problem:<br />
<br />
Gigabyte Z77X-UD3H rev. 1.1 (UEFI BIOS version F19e)<br />
<br />
- UEFI BIOS option for booting UEFI Only does not pretend the UEFI BIOS from starting CSM<br />
<br />
=== USB media gets struck with black screen ===<br />
<br />
* This issue can occur either due to [[KMS]] issue. Try [[Kernel_Mode_Setting#Disabling_modesetting|Disabling KMS]] while booting the USB.<br />
<br />
* If the issue is not due to KMS, then it may be due to bug in [[EFISTUB]] booting (see [https://bugs.archlinux.org/task/33745] and [https://bbs.archlinux.org/viewtopic.php?id=156670] for more information.). Both Official ISO ([[Archiso]]) and [[Archboot]] iso use EFISTUB (via [[Gummiboot]] Boot Manager for menu) for booting the kernel in UEFI mode. In such a case you have to use [[GRUB]] as the USB's UEFI bootloader by following the below section.<br />
<br />
==== Using GRUB ====<br />
<br />
* Create USB Flash Installation drive as mentioned in [[USB_Flash_Installation_Media#BIOS_and_UEFI_Bootable_USB|link]]. After that follow the below steps to use GRUB instead of Gummiboot.<br />
<br />
* Backup {{ic|<USB>/EFI/boot/loader.efi}} to {{ic|<USB>/EFI/boot/gummiboot.efi}}<br />
<br />
* [[GRUB#GRUB_Standalone|Create a GRUB standalone image]] and copy it to {{ic|<USB>/EFI/boot/loader.efi}}<br />
<br />
* Create {{ic|<USB>/EFI/boot/grub.cfg}} with the following contents:<br />
<br />
{{hc|grub.cfg for Official ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux archiso x86_64" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --label ARCHISO_XXXXXX<br />
linux /arch/boot/x86_64/vmlinuz archisobasedir=arch archisolabel=ARCHISO_XXXXXX add_efi_memmap<br />
initrd /arch/boot/x86_64/archiso.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --label ARCHISO_XXXXXX<br />
chainloader /EFI/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --label ARCHISO_XXXXXX<br />
chainloader /EFI/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
{{hc|grub.cfg for Archboot ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux x86_64 Archboot" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
linux /boot/vmlinuz_x86_64 cgroup_disable=memory loglevel=7 add_efi_memmap<br />
initrd /boot/initramfs_x86_64.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
== File Extensions ==<br />
<br />
These are the file extensions encountered when building UEFI using the tianocore EDKII.<br />
<br />
{| class="wikitable" border="1" cellpadding="5" cellspacing="0"<br />
! File Extension !! Description <br />
|-<br />
| .app || An intermediate DXE application program file that is produced by the GenFfsFile build tool from .pkg, .dpx, .sst, .pei and .pe32 files. /<br />
|-<br />
| .asm || Assembly source code file <br />
|}<br />
<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:UEFI]]<br />
* [[Wikipedia:EFI System partition]]<br />
* [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt Linux Kernel x86_64 UEFI Documentation]<br />
* [http://www.uefi.org/home/ UEFI Forum] - contains the official [http://www.uefi.org/specs/ UEFI Specifications] - GUID Partition Table is part of UEFI Specification<br />
* [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Welcome_to_TianoCore Intel's Tianocore Project] for Open-Source UEFI firmware which includes DuetPkg for direct BIOS based booting and OvmfPkg used in QEMU and Oracle VirtualBox<br />
* [http://uefidk.intel.com/ Intel UEFI Community Resource Center]<br />
* [http://www.intel.com/technology/efi/ Intel's page on EFI]<br />
* [http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/efi-boot-process.html FGA: The EFI boot process]<br />
* [http://www.microsoft.com/whdc/device/storage/GPT_FAQ.mspx Microsoft's Windows and GPT FAQ] - Contains info on Windows UEFI booting also<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Windows_x64_BIOS_to_UEFI Convert Windows Vista SP1+ or 7 x86_64 boot from BIOS-MBR mode to UEFI-GPT mode without Reinstall]<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Linux_Windows_BIOS_UEFI_boot_USB Create a Linux BIOS+UEFI and Windows x64 BIOS+UEFI bootable USB drive]<br />
* [http://rodsbooks.com/bios2uefi/ Rod Smith - A BIOS to UEFI Transformation]<br />
* [https://lkml.org/lkml/2011/6/8/322 UEFI Boot problems on some newer machines (LKML)]<br />
* [http://software.intel.com/en-us/articles/efi-shells-and-scripting/ EFI Shells and Scripting - Intel Documentation]<br />
* [http://software.intel.com/en-us/articles/uefi-shell/ UEFI Shell - Intel Documentation]<br />
* [http://www.hpuxtips.es/?q=node/293 UEFI Shell - bcfg command info]<br />
* [http://dl.dropbox.com/u/17629062/Shell2.zip UEFI Shell v2 binary with bcfg modified to work with UEFI pre-2.3 firmware - from Clover efiboot]<br />
* [http://linuxplumbers.ubicast.tv/videos/plumbing-uefi-into-linux/ LPC 2012 Plumbing UEFI into Linux]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-1/ LPC 2012 UEFI Tutorial : part 1]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-2/ LPC 2012 UEFI Tutorial : part 2]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=292473Bluetooth headset2014-01-11T20:08:18Z<p>Netskink: /* ALSA, bluez5 and PulseAudio method */ It works and its lengthy but that is whats required.</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Related articles start}}<br />
{{Related|Bluetooth}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
<br />
Before you get started, you have to make sure that [[bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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 />
== PulseAudio method ==<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 />
== ALSA, bluez5 and PulseAudio method ==<br />
<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 />
=== 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 <ip address>. The ip 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 flashplayer 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 pulldown 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)<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 />
<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Talk:Bluetooth_headset&diff=292472Talk:Bluetooth headset2014-01-11T20:07:19Z<p>Netskink: /* bluez5 method: overcomplicated instructions */</p>
<hr />
<div>== <s>Blog link dead</s> ==<br />
<br />
The link for the blog in the Pulseaudio method section is dead. I managed to access it through archive.org. Will re-upload the page to some HTML pastebin or something and re-link.<br />
<br />
:The link was updated a long time ago, closing. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:13, 27 December 2013 (UTC)<br />
<br />
== Tested headsets ==<br />
<br />
Added tested headsets section. Not really Arch Specific, but it is very helpful for Linux users out there looking to use a bluetooth wireless headset with Linux. Couldn't find any wiki or site that lists similar tests so I placed it here... --[[User:Divansantana|Divan Santana]] ([[User talk:Divansantana|talk]]) 17:50, 12 August 2013 (UTC)<br />
<br />
* Parrot Zik doesn't actually work that brilliantly - I have a terrible lag, and there is no microphone support.<br />
:: Agreed that there is no mic support. Mine pretty much never stutters, but does lag behind in real time sometimes. Most of the time it's not noticeable for me unless playing a game. [[User:Divansantana|Divan Santana]] ([[User talk:Divansantana|talk]]) 16:04, 13 September 2013 (UTC)<br />
<br />
== bluez5 method: overcomplicated instructions ==<br />
<br />
The method in [[Bluetooth_Headset#ALSA.2C_bluez5_and_PulseAudio_method]] describes two different methods:<br />
<br />
# using [[ALSA]] as a backend, similar to [[Bluetooth_Headset#ALSA-BTSCO_method]] but relying on {{Pkg|bluez}} instead of {{Pkg|bluez4}}<br />
# using [[PulseAudio]] as a backend - this is tested in the article with [[Audacious]], which is configured to use PulseAudio as a backend<br />
<br />
I see two possible solutions:<br />
<br />
# split the section into two sections, each describing different backend<br />
# drop the ALSA instructions completely, suggest to install {{Pkg|pulseaudio-alsa}}<br />
<br />
I also think that suggesting to install {{Pkg|audacious}} just for testing the output is unnecessary, any application using PulseAudio can be used for this purpose.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:25, 27 December 2013 (UTC)<br />
<br />
Point 1. Regarding bluez5 vs bluez4<br />
Its fine to have a bluez5 implmentation since bluez4 method differs. The problems I encountered had numerous unanswered replies on the forums. ie. a user can pair but not connect. <br />
<br />
Point 2. Regarding pulseaudio<br />
My understanding is that pulseaudio is not required in bluez4 but is in bluez5.<br />
<br />
Point 3. Any app can be chosen to test, but the point is that a app needs to be chosen and the user needs to know how to select pulseaudio otherwise they will not know.<br />
<br />
<br />
<br />
-- [[User:Netskink|Netskink]] ([[User talk:Netskink|talk]]) 12:02, 11 January 2014 (UTC)</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=287893Bluetooth headset2013-12-13T23:22:08Z<p>Netskink: /* Procedure */ Tell the user how this is a procedure for pair and connect, then give a procedure for justing connecting a prior paired device.</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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 />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<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 />
== [[ALSA]], Bluez5, and [[PulseAudio]] Method ==<br />
<br />
[[ALSA]], 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 />
=== 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 />
<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.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| alsa-lib || alsa-plugins<br />
|-<br />
| alsa-tools || alsa-utils<br />
|}<br />
<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. Supposedly bluez5 unlike bluez4 requires [[PulseAudio]] to interface with wireless headsets. During testing this requirement seems true.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| bluez 5 || bluez-libs<br />
|-<br />
| bluez-utils || <br />
|}<br />
<br />
<br />
==== Install [[PulseAudio]] ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The [http://aur.archlinux.org/packages/pulseaudio-git PulseAudio] package from [[AUR]] has capabilities not provided by the stock [[PulseAudio]] package. The additional capabilites are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [http://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| [https://aur.archlinux.org/packages/pulseaudio-git pulseaudio-git] || libcanberra-pulse<br />
|}<br />
<br />
==== Install [[Audacious]] ====<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Install [[Audacious]] to test audio playback.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| audacious || audacious-plugins<br />
|}<br />
<br />
==== Install [[Python]] and associated libraries ====<br />
<br />
[[Audacious]] and the [[PulseAudio]] mixer {{Pkg|pavucontrol}} require [[Python]] and [[QT]]. <br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| python || python-dbus || python-dbus-common || python-lxml<br />
|-<br />
|-<br />
| python2 || python2-beaker || python2-cairo || python2-dbus<br />
|-<br />
| python2-gobject || python2-gobject2 || python2-mako || python2-markupsafe<br />
|-<br />
| python2-pyqt4 || python2-sip || python-pyqt4 || python-sip <br />
|-<br />
| python-xdg<br />
|}<br />
<br />
==== Install [[QT]] and associated libraries ====<br />
<br />
[[QT]] provides GUI capabilities used by [[Audacious]] and [[PulseAudio]].<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| libdbusmenu-qt || phonon-qt4 || polkit-qt || poppler-qt4<br />
|-<br />
| pyqt4-common || python-pyqt4 || python2-pyqt4 || qt4<br />
|-<br />
| qtwebkit<br />
|}<br />
<br />
<br />
=== Procedure ===<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 />
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 />
<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 <ip address>. The ip 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 />
<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<br />
this jives with my experience.<br />
<br />
Startup 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 />
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 />
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 />
<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 />
<!-- This configuration file specifies the required security policies<br />
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 />
<br />
===== Tested Apps =====<br />
<br />
As noted above this will work easily with audacious. Youtube videos with chromium and flashplayer 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 pulldown 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)<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 />
<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=287739Bluetooth headset2013-12-12T19:47:23Z<p>Netskink: /* ALSA, Bluez5, and PulseAudio Method */ Youtube debugging started.</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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 />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<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 />
== [[ALSA]], Bluez5, and [[PulseAudio]] Method ==<br />
<br />
[[ALSA]], 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 />
=== 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 />
<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.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| alsa-lib || alsa-plugins<br />
|-<br />
| alsa-tools || alsa-utils<br />
|}<br />
<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. Supposedly bluez5 unlike bluez4 requires [[PulseAudio]] to interface with wireless headsets. During testing this requirement seems true.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| bluez 5 || bluez-libs<br />
|-<br />
| bluez-utils || <br />
|}<br />
<br />
<br />
==== Install [[PulseAudio]] ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The [http://aur.archlinux.org/packages/pulseaudio-git PulseAudio] package from [[AUR]] has capabilities not provided by the stock [[PulseAudio]] package. The additional capabilites are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [http://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| [https://aur.archlinux.org/packages/pulseaudio-git pulseaudio-git] || libcanberra-pulse<br />
|}<br />
<br />
==== Install [[Audacious]] ====<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Install [[Audacious]] to test audio playback.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| audacious || audacious-plugins<br />
|}<br />
<br />
==== Install [[Python]] and associated libraries ====<br />
<br />
[[Audacious]] and the [[PulseAudio]] mixer {{Pkg|pavucontrol}} require [[Python]] and [[QT]]. <br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| python || python-dbus || python-dbus-common || python-lxml<br />
|-<br />
|-<br />
| python2 || python2-beaker || python2-cairo || python2-dbus<br />
|-<br />
| python2-gobject || python2-gobject2 || python2-mako || python2-markupsafe<br />
|-<br />
| python2-pyqt4 || python2-sip || python-pyqt4 || python-sip <br />
|-<br />
| python-xdg<br />
|}<br />
<br />
==== Install [[QT]] and associated libraries ====<br />
<br />
[[QT]] provides GUI capabilities used by [[Audacious]] and [[PulseAudio]].<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| libdbusmenu-qt || phonon-qt4 || polkit-qt || poppler-qt4<br />
|-<br />
| pyqt4-common || python-pyqt4 || python2-pyqt4 || qt4<br />
|-<br />
| qtwebkit<br />
|}<br />
<br />
<br />
=== Procedure ===<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 />
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 />
<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 this config file which is setup for what appears to be the root user.<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 />
<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<br />
this jives with my experience.<br />
<br />
Startup 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 />
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 />
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 />
<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 />
<!-- This configuration file specifies the required security policies<br />
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 />
<br />
===== Tested Apps =====<br />
<br />
As noted above this will work easily with audacious. Youtube videos with chromium and flashplayer 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 pulldown 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)<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 />
<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=287025Bluetooth headset2013-12-07T21:28:17Z<p>Netskink: /* ALSA, Bluez5, and PulseAudio Method */ Additional Config File settings</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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 />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<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 />
== [[ALSA]], Bluez5, and [[PulseAudio]] Method ==<br />
<br />
[[ALSA]], 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 />
=== 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 />
<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.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| alsa-lib || alsa-plugins<br />
|-<br />
| alsa-tools || alsa-utils<br />
|}<br />
<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. Supposedly bluez5 unlike bluez4 requires [[PulseAudio]] to interface with wireless headsets. During testing this requirement seems true.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| bluez 5 || bluez-libs<br />
|-<br />
| bluez-utils || <br />
|}<br />
<br />
<br />
==== Install [[PulseAudio]] ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The [http://aur.archlinux.org/packages/pulseaudio-git PulseAudio] package from [[AUR]] has capabilities not provided by the stock [[PulseAudio]] package. The additional capabilites are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [http://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| [https://aur.archlinux.org/packages/pulseaudio-git pulseaudio-git] || libcanberra-pulse<br />
|}<br />
<br />
==== Install [[Audacious]] ====<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Install [[Audacious]] to test audio playback.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| audacious || audacious-plugins<br />
|}<br />
<br />
==== Install [[Python]] and associated libraries ====<br />
<br />
[[Audacious]] and the [[PulseAudio]] mixer {{Pkg|pavucontrol}} require [[Python]] and [[QT]]. <br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| python || python-dbus || python-dbus-common || python-lxml<br />
|-<br />
|-<br />
| python2 || python2-beaker || python2-cairo || python2-dbus<br />
|-<br />
| python2-gobject || python2-gobject2 || python2-mako || python2-markupsafe<br />
|-<br />
| python2-pyqt4 || python2-sip || python-pyqt4 || python-sip <br />
|-<br />
| python-xdg<br />
|}<br />
<br />
==== Install [[QT]] and associated libraries ====<br />
<br />
[[QT]] provides GUI capabilities used by [[Audacious]] and [[PulseAudio]].<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| libdbusmenu-qt || phonon-qt4 || polkit-qt || poppler-qt4<br />
|-<br />
| pyqt4-common || python-pyqt4 || python2-pyqt4 || qt4<br />
|-<br />
| qtwebkit<br />
|}<br />
<br />
<br />
=== Procedure ===<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 />
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 />
<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 this config file which is setup for what appears to be the root user.<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 />
<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<br />
this jives with my experience.<br />
<br />
Startup 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 />
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 />
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 />
<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 />
<!-- This configuration file specifies the required security policies<br />
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 />
<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)<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=287020Bluetooth headset2013-12-07T21:02:55Z<p>Netskink: /* ALSA, Bluez5, and PulseAudio Method */ grammar, markup, output of bluetoothctl and screenshot of app settings.</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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 />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<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 />
== [[ALSA]], Bluez5, and [[PulseAudio]] Method ==<br />
<br />
[[ALSA]], 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 />
=== 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 />
<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.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| alsa-lib || alsa-plugins<br />
|-<br />
| alsa-tools || alsa-utils<br />
|}<br />
<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. Supposedly bluez5 unlike bluez4 requires [[PulseAudio]] to interface with wireless headsets. During testing this requirement seems true.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| bluez 5 || bluez-libs<br />
|-<br />
| bluez-utils || <br />
|}<br />
<br />
<br />
==== Install [[PulseAudio]] ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The [http://aur.archlinux.org/packages/pulseaudio-git PulseAudio] package from [[AUR]] has capabilities not provided by the stock [[PulseAudio]] package. The additional capabilites are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [http://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| [https://aur.archlinux.org/packages/pulseaudio-git pulseaudio-git] || libcanberra-pulse<br />
|}<br />
<br />
==== Install [[Audacious]] ====<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Install [[Audacious]] to test audio playback.<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| audacious || audacious-plugins<br />
|}<br />
<br />
==== Install [[Python]] and associated libraries ====<br />
<br />
[[Audacious]] and the [[PulseAudio]] mixer {{Pkg|pavucontrol}} require [[Python]] and [[QT]]. <br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| python || python-dbus || python-dbus-common || python-lxml<br />
|-<br />
|-<br />
| python2 || python2-beaker || python2-cairo || python2-dbus<br />
|-<br />
| python2-gobject || python2-gobject2 || python2-mako || python2-markupsafe<br />
|-<br />
| python2-pyqt4 || python2-sip || python-pyqt4 || python-sip <br />
|-<br />
| python-xdg<br />
|}<br />
<br />
==== Install [[QT]] and associated libraries ====<br />
<br />
[[QT]] provides GUI capabilities used by [[Audacious]] and [[PulseAudio]].<br />
<br />
{| border="1"<br />
|+ Packages<br />
|-<br />
| libdbusmenu-qt || phonon-qt4 || polkit-qt || poppler-qt4<br />
|-<br />
| pyqt4-common || python-pyqt4 || python2-pyqt4 || qt4<br />
|-<br />
| qtwebkit<br />
|}<br />
<br />
<br />
=== Procedure ===<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 />
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 />
<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 this config file which is setup for what appears to be the root user.<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 />
<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<br />
this jives with my experience.<br />
<br />
Startup 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 />
== 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)<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=287010Bluetooth headset2013-12-07T20:16:39Z<p>Netskink: /* ALSA, Bluez5, and PulseAudio Method */ Grammar and additonal links</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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 />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<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 />
== [[ALSA]], Bluez5, and [[PulseAudio]] Method ==<br />
<br />
[[ALSA]], 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 />
=== 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 />
<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.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| alsa-lib || alsa-plugins<br />
|-<br />
| alsa-tools || alsa-utils<br />
|}<br />
<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. Supposedly bluez5 unlike bluez4 requires [[PulseAudio]] to interface with wireless headsets. During testing this requirement seems true.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| bluez 5.11-1 || bluez-libs<br />
|-<br />
| bluez-utils || <br />
|}<br />
<br />
<br />
==== Install [[PulseAudio]] ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The [http://aur.archlinux.org/packages/pulseaudio-git PulseAudio] package from [[AUR]] has capabilities not provided by the stock [[PulseAudio]] package. The additional capabilites are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [http://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| [https://aur.archlinux.org/packages/pulseaudio-git pulseaudio-git] || libcanberra-pulse<br />
|}<br />
<br />
==== Install [[Audacious]] ====<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Install [[Audacious]] to test audio playback.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| audacious || audacious-plugins<br />
|}<br />
<br />
==== Install [[Python]] and associated libraries ====<br />
<br />
[[Audacious]] and the [[PulseAudio]] mixer {{Pkg|pavucontrol}} require [[Python]] and [[QT]]. <br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| python || python-dbus || python-dbus-common || python-lxml<br />
|-<br />
|-<br />
| python2 || python2-beaker || python2-cairo || python2-dbus<br />
|-<br />
| python2-gobject || python2-gobject2 || python2-mako || python2-markupsafe<br />
|-<br />
| python2-pyqt4 || python2-sip || python-pyqt4 || python-sip <br />
|-<br />
| python-xdg<br />
|}<br />
<br />
==== Install [[QT]] and associated libraries ====<br />
<br />
[[QT]] provides GUI capabilities used by [[Audacious]] and [[PulseAudio]].<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| libdbusmenu-qt || phonon-qt4 || polkit-qt || poppler-qt4<br />
|-<br />
| pyqt4-common || python-pyqt4 || python2-pyqt4 || qt4<br />
|-<br />
| qtwebkit<br />
|}<br />
<br />
<br />
=== Procedure ===<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 up a terminal and start the bluetooth service<br />
# systemctl start bluetooth<br />
<br />
Start up another terminal in X and start the pulseaudio daemon.<br />
$ pulseaudio -D<br />
<br />
Start up bluetoothctrl and pair and connect your headset<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 />
<output omitted for bluetooth results><br />
[bluetooth]# power on<br />
[bluetooth]# pairable on<br />
[bluetooth]# agent on<br />
[bluetooth]# default-agent<br />
[bluetooth]# scan on<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[bluetooth]# info 00:1A:7D:12:36:B9<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<br />
this jives with my experience.<br />
<br />
Startup up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<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)<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=287003Bluetooth headset2013-12-07T19:53:25Z<p>Netskink: /* ALSA, BLUEZ5, and PULSEAUDIO Method */ Section rewrite, adding package and wiki links.</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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 />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<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 />
== [[ALSA]], Bluez5, and [[PulseAudio]] Method ==<br />
<br />
[[ALSA]], 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 might not be the minimum required set and needs to be examined more closely.<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 />
<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.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| alsa-lib || alsa-plugins<br />
|-<br />
| alsa-tools || alsa-utils<br />
|}<br />
<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. Supposedly bluez5 unlike bluez4 requires [[PulseAudio]] to interface with wireless headsets. During testing this requirement seems true.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| bluez 5.11-1 || bluez-libs<br />
|-<br />
| bluez-utils || <br />
|}<br />
<br />
<br />
==== Install [[PulseAudio]] ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The [https://aur.archlinux.org/packages/pulseaudio-git PulseAudio] package from [[AUR]] has capabilities not provided by the stock [[PulseAudio]] package which are required by Bluez.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| [https://aur.archlinux.org/packages/pulseaudio-git pulseaudio-git] || libcanberra-pulse<br />
|}<br />
<br />
==== Install [[Audacious]] ====<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Install [[Audacious]] to test audio playback.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| audacious || audacious-plugins<br />
|}<br />
<br />
==== Install [[Python]] and associated libraries ====<br />
<br />
Audacious and the PulseAudio mixer {{Pkg|pavucontrol}} require [[Python]] and [[QT]]. <br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| python || python-dbus || python-dbus-common || python-lxml<br />
|-<br />
| python-lxml || python-pyqt4 || python-sip || python-xdg<br />
|-<br />
| python2 || python2-beaker || python2-cairo || python2-dbus<br />
|-<br />
| python2-gobject || python2-gobject2 || python2-mako || python2-markupsafe<br />
|-<br />
| python2-pyqt4 || python2-sip || || <br />
|}<br />
<br />
==== Install [[QT]] and associated libraries ====<br />
<br />
[[QT]] provides GUI capabilities used by audacious and pulseaudio.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| libdbusmenu-qt || phonon-qt4 || polkit-qt || poppler-qt4<br />
|-<br />
| pyqt4-common || python-pyqt4 || python2-pyqt4 || qt4<br />
|}<br />
<br />
<br />
=== Procedure ===<br />
Once the required packages are installed, this procedure shows how to use the headset to play audio. 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 up a terminal and start the bluetooth service<br />
# systemctl start bluetooth<br />
<br />
Start up another terminal in X and start the pulseaudio daemon.<br />
$ pulseaudio -D<br />
<br />
Start up bluetoothctrl and pair and connect your headset<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 />
<output omitted for bluetooth results><br />
[bluetooth]# power on<br />
[bluetooth]# pairable on<br />
[bluetooth]# agent on<br />
[bluetooth]# default-agent<br />
[bluetooth]# scan on<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[bluetooth]# info 00:1A:7D:12:36:B9<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<br />
this jives with my experience.<br />
<br />
Startup up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<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)<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=286987Bluetooth headset2013-12-07T19:20:38Z<p>Netskink: /* ALSA, BLUEZ5, and PULSEAUDIO method */ Trying to fix the noted poor writing section. Overall structure changes.</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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 />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<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 />
== ALSA, BLUEZ5, and PULSEAUDIO Method ==<br />
{{Poor writing|Using first person, should use package templates, see [[Help:Style]] and related.}}<br />
<br />
Bluez5, pulseaudio and ALSA 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 might not be the minimum required set and needs to be examined more closely.<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 />
<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.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| alsa-lib || alsa-plugins<br />
|-<br />
| alsa-tools || alsa-utils<br />
|}<br />
<br />
<br />
==== Install Bluez5 =====<br />
<br />
Bluez5 is the latest bluetooth stack. Supposedly bluez5 unlike bluez4 requires pulseaudio to interface with wireless headsets. During testing this requirement seems true.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| bluez 5.11-1 || bluez-libs<br />
|-<br />
| bluez-utils || <br />
|}<br />
<br />
<br />
===== Install Pulseaudio =====<br />
<br />
Pulseaudio interfaces with ALSA, Bluez and other user mode programs. The pulseaudio package from AUR has capabilities not provided by the stock pulseaudio package which are required by Bluez.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| pulseaudio-git || libcanberra-pulse<br />
|}<br />
<br />
===== Install Audacious =====<br />
Audacious is a program which plays audio files. It can work directly with ALSA or with Pulseaudio. Install audacious to test audio playback.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| audacious || audacious-plugins<br />
|}<br />
<br />
==== Install Python and associated libraries ====<br />
<br />
Audacious and the pulseaudio mixer pavucontrol require python and QT. <br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| python || python-dbus || python-dbus-common || python-lxml<br />
|-<br />
| python-lxml || python-pyqt4 || python-sip || python-xdg<br />
|-<br />
| python2 || python2-beaker || python2-cairo || python2-dbus<br />
|-<br />
| python2-gobject || python2-gobject2 || python2-mako || python2-markupsafe<br />
|-<br />
| python2-pyqt4 || python2-sip || || <br />
|}<br />
<br />
==== Install QT and associated libraries ====<br />
<br />
QT provides GUI capabilities used by audacious and pulseaudio.<br />
<br />
{| border="1"<br />
|+ Tabular data<br />
|-<br />
| libdbusmenu-qt || phonon-qt4 || polkit-qt || poppler-qt4<br />
|-<br />
| pyqt4-common || python-pyqt4 || python2-pyqt4 || qt4<br />
|}<br />
<br />
<br />
=== Procedure ===<br />
Once the required packages are installed, this procedure shows how to use the headset to play audio. 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 up a terminal and start the bluetooth service<br />
# systemctl start bluetooth<br />
<br />
Start up another terminal in X and start the pulseaudio daemon.<br />
$ pulseaudio -D<br />
<br />
Start up bluetoothctrl and pair and connect your headset<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 />
<output omitted for bluetooth results><br />
[bluetooth]# power on<br />
[bluetooth]# pairable on<br />
[bluetooth]# agent on<br />
[bluetooth]# default-agent<br />
[bluetooth]# scan on<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
<br />
Start up alsa, for simplicity unmute 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<br />
this jives with my experience.<br />
<br />
Startup up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<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)<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=286968Bluetooth headset2013-12-07T18:06:52Z<p>Netskink: /* ALSA, BLUEZ5, and PULSEAUDIO method */ Trying to clean up the article per comments.</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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 />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<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 />
== ALSA, BLUEZ5, and PULSEAUDIO method ==<br />
{{Poor writing|Using first person, should use package templates, see [[Help:Style]] and related.}}<br />
<br />
I'm not an expert in any of this but this how I muddled my way through this process. Perhaps someone can tighten up the install method. FWIW, I was using a T61p laptop and SoundBot 220 bluetooth headset.<br />
<br />
Install Alsa and associated libraries.<br />
*alsa-lib 1.0.27.2-1<br />
*alsa-plugins 1.0.27-2<br />
*alsa-tools 1.0.27-5<br />
*alsa-utils 1.0.27.2-1<br />
<br />
Install Bluez5<br />
*bluez 5.11-1<br />
*bluez-libs 5.11-1<br />
*bluez-utils 5.11-1<br />
<br />
Install Pulseaudio<br />
*libcanberra-pulse 0.30-4<br />
*pulseaudio-git v4.0.318.gce304d6-1<br />
<br />
Optional, I chose to use audacious as my player<br />
*audacious 3.4.2-1<br />
*audacious-plugins 3.4.2-1<br />
<br />
At one point, I needed a ton of python and Qt code. I hate to dump this here, but you might as well see it all.<br />
*python 3.3.3-1<br />
*python-dbus 1.2.0-1<br />
*python-dbus-common 1.2.0-1<br />
*python-lxml 3.2.3-1<br />
*python-pyqt4 4.10.3-1<br />
*python-sip 4.15.3-1<br />
*python-xdg 0.25-1<br />
*python2 2.7.6-1<br />
*python2-beaker 1.6.4-1<br />
*python2-cairo 1.10.0-1<br />
*python2-dbus 1.2.0-1<br />
*python2-gobject 3.10.2-1<br />
*python2-gobject2 2.28.6-9<br />
*python2-mako 0.9.0-1<br />
*python2-markupsafe 0.18-2<br />
*python2-pyqt4 4.10.3-1<br />
*python2-sip 4.15.3-1<br />
<br />
And lastly the QT packages<br />
*libdbusmenu-qt 0.9.2-2<br />
*phonon-qt4 4.7.0-2<br />
*polkit-qt 0.103.0-2<br />
*poppler-qt4 0.24.4-1<br />
*pyqt4-common 4.10.3-1<br />
*python-pyqt4 4.10.3-1<br />
*python2-pyqt4 4.10.3-1<br />
*qt4 4.8.5-6<br />
<br />
Start up a terminal and start the bluetooth service<br />
# systemctl start bluetooth<br />
<br />
Start up another terminal in X and start the pulseaudio daemon.<br />
$ pulseaudio -D<br />
<br />
Start up bluetoothctrl and pair and connect your headset<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 />
<output omitted for bluetooth results><br />
[bluetooth]# power on<br />
[bluetooth]# pairable on<br />
[bluetooth]# agent on<br />
[bluetooth]# default-agent<br />
[bluetooth]# scan on<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
<br />
Start up alsa, for simplicity unmute 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<br />
this jives with my experience.<br />
<br />
Startup up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<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)<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=286443Bluetooth headset2013-12-06T04:00:18Z<p>Netskink: After numerous attempts and many posts, I finally got bluez5, pulseaudio, and alsa working with my wireless headset.</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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's also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher explanations. Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
<br />
== ALSA, BLUEZ5, and PULSEAUDIO method ==<br />
<br />
I'm not an expert in any of this but this how I muddled my way through this process. Perhaps someone can tighten up the install method. FWIW, I was using a T61p laptop and SoundBot 220 bluetooth headset.<br />
<br />
Install Alsa and associated libraries.<br />
*alsa-lib 1.0.27.2-1<br />
*alsa-plugins 1.0.27-2<br />
*alsa-tools 1.0.27-5<br />
*alsa-utils 1.0.27.2-1<br />
<br />
Install Bluez5<br />
*bluez 5.11-1<br />
*bluez-libs 5.11-1<br />
*bluez-utils 5.11-1<br />
<br />
Install Pulseaudio<br />
*libcanberra-pulse 0.30-4<br />
*pulseaudio-git v4.0.318.gce304d6-1<br />
<br />
Optional, I chose to use audacious as my player<br />
*audacious 3.4.2-1<br />
*audacious-plugins 3.4.2-1<br />
<br />
At one point, I needed a ton of python and Qt code. I hate to dump this here, but you might as well see it all.<br />
*python 3.3.3-1<br />
*python-dbus 1.2.0-1<br />
*python-dbus-common 1.2.0-1<br />
*python-lxml 3.2.3-1<br />
*python-pyqt4 4.10.3-1<br />
*python-sip 4.15.3-1<br />
*python-xdg 0.25-1<br />
*python2 2.7.6-1<br />
*python2-beaker 1.6.4-1<br />
*python2-cairo 1.10.0-1<br />
*python2-dbus 1.2.0-1<br />
*python2-gobject 3.10.2-1<br />
*python2-gobject2 2.28.6-9<br />
*python2-mako 0.9.0-1<br />
*python2-markupsafe 0.18-2<br />
*python2-pyqt4 4.10.3-1<br />
*python2-sip 4.15.3-1<br />
<br />
And lastly the QT packages<br />
*libdbusmenu-qt 0.9.2-2<br />
*phonon-qt4 4.7.0-2<br />
*polkit-qt 0.103.0-2<br />
*poppler-qt4 0.24.4-1<br />
*pyqt4-common 4.10.3-1<br />
*python-pyqt4 4.10.3-1<br />
*python2-pyqt4 4.10.3-1<br />
*qt4 4.8.5-6<br />
<br />
Start up a terminal and start the bluetooth service<br />
# systemctl start bluetooth<br />
<br />
Start up another terminal in X and start the pulseaudio daemon.<br />
$ pulseaudio -D<br />
<br />
Start up bluetoothctrl and pair and connect your headset<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 />
<output omitted for bluetooth results><br />
[bluetooth]# power on<br />
[bluetooth]# pairable on<br />
[bluetooth]# agent on<br />
[bluetooth]# default-agent<br />
[bluetooth]# scan on<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
<br />
Start up alsa, for simplicity unmute 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<br />
this jives with my experience.<br />
<br />
Startup up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
<br />
<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'll 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 />
== 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)<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<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>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=286442Bluetooth headset2013-12-06T03:29:44Z<p>Netskink: /* Tested Headsets */</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|This article describes how to set up a bluetooth headset.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth}}<br />
{{Article summary end}}<br />
Before you get started, you have to make sure that [[Bluetooth|bluetooth]] is set up and working.<br />
<br />
== ALSA-BTSCO method ==<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's also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
The following method is '''out-of-date''' and '''obsoleted'''.<br />
<br />
'''NOTE: This method is also outdated as with newer versions of BlueZ. Anyone know what the exact version number when this stopped working is?''' <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 />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<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 />
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 />
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 />
*** To find hci# for a usb dongle, type in <br />
$ hcitool dev<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 />
== PulseAudio method ==<br />
<br />
This one`s 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 futher 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'll 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 />
== 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)<br />
* SoundBot SB220 works with bluez5 and pulseaudio-git.<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>Netskinkhttps://wiki.archlinux.org/index.php?title=User_talk:Netskink&diff=285843User talk:Netskink2013-12-02T00:25:59Z<p>Netskink: Contact info and intro.</p>
<hr />
<div><br />
Hello <br />
<br />
This is John. d a v i s @ g m a i l . c o m.<br />
<br />
My website is www.skink.net<br />
<br />
I primarily use archlinux on thinkpad laptops. T61p, X220, T42p and Alienware m11xR2.<br />
<br />
On IRC I use nick davis.<br />
<br />
Good luck and have fun.<br />
<br />
John</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Media_Transfer_Protocol&diff=284985Media Transfer Protocol2013-11-28T01:26:06Z<p>Netskink: /* go-mtpfs */ The only mtp package which worked for my nexus 4.</p>
<hr />
<div>[[Category:Sound]]<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 />
MTP support is provided by [http://libmtp.sourceforge.net/ libmtp], [[pacman|installable]] with the {{Pkg|libmtp}} package from the [[official repositories]].<br />
<br />
==Usage==<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.<br />
<br />
To connect to your MTP device, you use:<br />
# mtp-connect<br />
<br />
If connection is successful, you will be given several switch options 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 />
==Using media players==<br />
You can also use your MTP device in music players such as Amarok. To do this you may have to edit {{ic|/etc/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 />
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#Mounting USB devices]]}}<br />
<br />
==jmtpfs==<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 these commands to mount and unmount your device :<br />
$ jmtpfs ~/mtp<br />
<br />
$ fusermount -u ~/mtp<br />
<br />
==go-mtpfs==<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 />
If the above instructions don't 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) and Samsung Galaxy S 3 mini. (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 />
<br />
As in the section above install {{aur|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" doesn't 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 is has 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]. <br />
*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 />
* You can grab the stable {{Pkg|gvfs-mtp}} package from extra. You may want to reboot your PC to make it actually working.<br />
<br />
*Devices will have gvfs paths like this<br />
gvfs-ls mtp://[usb:002,013]/<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. Remember '''do not''' run the following commands as root.<br />
<br />
* To list MTP devices run<br />
simple-mtpfs --list-devices<br />
<br />
* To mount a MTP devices (in this example device 0) run<br />
simple-mtpfs /path/to/your/mount/point<br />
<br />
* To un mount run<br />
fusermount -u /path/to/your/mount/point<br />
<br />
==KDE MTP KIO Slave==<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 />
The device will be available under the path mtp:/<br />
<br />
===Workaround if the KDE device actions doesn't work===<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 />
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 />
* HTC Phones automatically enter usb debugging mode on usb connect. Manually turn it off once connected to give libmtp access to the device.<br />
<br />
MTP is still buggy and may crash despite the best efforts of developers. The following are alternatives:<br />
* AirDroid - an Android app to access files via your web browser.<br />
* FTP client on Android - If you run a local FTP server on Arch (such as [[Vsftp]]), there are many FTP clients available on the Play Store which will give read/ write access to your device's files.<br />
* FTP Server on Android. Note: since FTP client using passive transfer (server connect to client) do not forget to disable firewall or adding rules for allowing FTP server connect to your PC.<br />
** Ftp Server (by The Olive Tree) app in Play Store acts as FTP server on Android and allows RW access to pretty much all your storage.<br />
*** Pro: Doesn't require root and just works!<br />
*** Cons: Doesn't work with tethering network.<br />
** FTPServer (by Andreas Liebig) - Just work.<br />
* SSH server on Android.<br />
** For example, SSHelper, available on the Play Store, just works without requiring root access. Assuming SSHelper is listening on port 20 and the phone's IP address is 192.168.0.20, the following command will synchronise a local directory with the external SD card of the Android device:<br />
rsync --rsh="ssh -p 20" --modify-window=1 ~/local_files 192.168.0.20:/mnt/extSdCard/remote_files<br />
Note the {{ic|--modify-window}} option, which is often used when rsyncing to a FAT filesystem (such as the one used by Android devices for their internal memory and external SD cards).<br />
* Samba - an Android app to share your SD card as a windows fileshare. Pros: Your desktop apps work as before (since the SD card appears as a windows fileshare). Cons: you need to root your phone.<br />
* adb - Part of the Android development kit is adb android debug bridge. It can be used to push and pull files from an Android device.<br />
** The device need USB debbuging to be active and later connected to the computer with usb.<br />
** To send a file to the device use {{ic|adb push /what-to-copy /where-to-place-it}}<br />
** To receive a file {{ic|adb pull /what-you-want-to-copy /where-you-want-it}}<br />
*** Pro: Stable, can be used for a lot more then just copy files back and forth.<br />
*** Cons: Can be somewhat slow.<br />
<br />
==Security features on android==<br />
If you use android 4.x please unlock phone (screen unlock) and then connect phone to USB.<br />
<br />
If you not unlock you have in KDE "No Storages found. Maybe you need to unlock your device?" or error 02fe in console.</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Xen&diff=279970Xen2013-10-27T02:58:12Z<p>Netskink: /* Installation of Xen systemd services */ show as console font</p>
<hr />
<div><br />
[[Category:Virtualization]]<br />
[[Category:Kernel]]<br />
[[de:Xen]]<br />
[[es:Xen]]<br />
[[ru:Xen]]<br />
{{Article summary start}}<br />
{{Article summary text|This article is about basic usage of Xen, including running Arch as both a Xen dom0 ''host'' and as a domU ''guest''.}}<br />
{{Article summary heading|Required software}}<br />
{{Article summary link|Xen|http://www.xen.org/}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|KVM}}<br />
{{Article summary wiki|QEMU}}<br />
{{Article summary wiki|VirtualBox}}<br />
{{Article summary wiki|VMware}}<br />
{{Article summary wiki|Moving an existing install into (or out of) a virtual machine}}<br />
{{Article summary end}}<br />
<br />
From [http://wiki.xen.org/wiki/Xen_Overview Xen Overview]:<br />
<br />
:''Xen is an open-source type-1 or baremetal hypervisor, which makes it possible to run many instances of an operating system or indeed different operating systems in parallel on a single machine (or host). Xen is the only type-1 hypervisor that is available as open source. Xen is used as the basis for a number of different commercial and open source applications, such as: server virtualization, Infrastructure as a Service (IaaS), desktop virtualization, security applications, embedded and hardware appliances.''<br />
<br />
==Introduction==<br />
<br />
The Xen hypervisor is a thin layer of software which emulates a computer architecture allowing multiple operating systems to run simultaneously. The hypervisor is started by the boot loader of the computer it is installed on. Once the hypervisor is loaded, it starts the "dom0" (short for "domain 0", sometimes called the host or privileged domain) which in our case runs Arch Linux. Once the dom0 has started, one or more "domUs" (short for user domains, sometimes called VMs or guests) can be started and controlled from the dom0. Xen supports both paravirtualized (PV) and hardware virtualized (HVM) domUs. See [http://wiki.xen.org/wiki/Xen_Overview Xen.org] for a full overview.<br />
<br />
==System requirements==<br />
The Xen hypervisor requires kernel level support which is included in recent Linux kernels and is built into the {{Pkg|linux}} and {{Pkg|linux-lts}} Arch kernel packages. To run run HVM domUs the physical hardware must have either Intel VT-x or AMD-V (SVM) virtualization support. In order to verify this, run the following command when the Xen hypervisor is not running:<br />
$ grep -E "(vmx|svm)" --color=always /proc/cpuinfo<br />
If the above command does not produce output, then hardware virtualization support is unavailable and your hardware is unable to run HVM domUs. If you believe the CPU supports one of these features you should access the host system's BIOS configuration menu during the boot process and look if options related to virtualization support have been disabled. If such an option exists and is disabled, then enable it, boot the system and repeat the above command. The Xen hypervisor also supports PCI passthrough where PCI devices can be passed directly to the domU even in the absence of dom0 support for the device. In order to use PCI passthrough the CPU must support IOMMU/VT-d.<br />
<br />
== Configuring dom0 ==<br />
The Xen hypervisor relies on a full install of the base operating system. Before attempting to install the Xen hypevisor, the host machine should have a fully operational and up-to-date install of Arch Linux. This installation can be a minimal install with only the base package and does not require a [[Desktop Environment]] or even [[Xorg]]. If you are building a new host from scratch, see the [[Installation Guide]] for instructions on installing Arch Linux. The following configuration steps are required to convert a standard installation into a working dom0 running on top of the Xen hypevisor:<br />
<br />
* Installation of the Xen hypervisor<br />
* Modification of the bootloader to boot the Xen hypervisor<br />
* Creation of a network bridge<br />
* Installation of Xen systemd services<br />
<br />
=== Installation of the Xen hypervisor ===<br />
To install the Xen hypervisor install either the current stable {{AUR|xen}} or the bleeding edge unstable {{AUR|xen-hg-unstable}} packages available in the [[Arch User Repository]]. Both packages provide the Xen hypervisor, current xl interface and all configuration and support files, including systemd services. The multilib repository needs to be enabled to install Xen (See [[Pacman#Repositories]] for details). Install the {{AUR|xen-docs}} package from the [[Arch User Repository]] for the man pages and documentation.<br />
<br />
=== Modification of the bootloader ===<br />
The boot loader must be modified to load a special Xen kernel (xen.gz) which is then used to boot the normal kernel. To do this a new bootloader entry is needed.<br />
<br />
For grub users, the Xen package provides the ''/etc/grub.d/09_xen'' generator file. The file ''/etc/xen/grub.conf'' can be edited to customize the Xen boot commands. For example, to allocate 512M of RAM to dom0 at boot, modify ''/etc/xen/grub.conf'' by replacing the line:<br />
#XEN_HYPERVISOR_CMDLINE="xsave=1"<br />
<br />
with<br />
XEN_HYPERVISOR_CMDLINE="dom0_mem=512M xsave=1"<br />
<br />
After customizing the options, update the bootloader configuration with the following command:<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
More information on using the GRUB bootloader is available at [[Grub]].<br />
<br />
For syslinux users, add a stanza like this:<br />
LABEL xen<br />
MENU LABEL My Xen<br />
KERNEL mboot.c32<br />
APPEND ../xen-4.3.0.gz --- ../vmlinuz-linux console=tty0 root=/dev/sda3 ro --- ../initramfs-linux.img<br />
<br />
Also this requires mboot.c32 to be in the same directory as the config file. If you have /boot and /usr in the same partition you can possibly link it. I don't know since I have /boot in a seperate partition. So, for users with /boot in a seperate paritition from /usr<br />
# cp /usr/lib/syslinux/mboot.c32 /boot/syslinux<br />
<br />
=== Creation of a network bridge ===<br />
Xen requires that network communications between domUs and the dom0 (and beyond) be set up manually. The use of both DHCP and static addressing is possible, and the choice should be determined by the network topology. Complex setups are possible, see the [http://wiki.xen.org/wiki/Xen_Networking Networking] article on the Xen wiki for details and ''/etc/xen/scripts'' for scripts for various networking configurations. A basic bridged network, in which a virtual switch is created in dom0 that every domU is attached to, can be setup by modifying the example configuration files provided by [[Netctl]] in ''etc/netctl/examples''. By default, Xen expects a bridge to exist named xenbr0. To set this up with netctl, do the following:<br />
<br />
# cd /etc/netctl<br />
# cp examples/bridge xenbridge-dhcp<br />
<br />
make the following changes to /etc/netctl/xenbridge-dhcp:<br />
Description="Xen bridge connection"<br />
Interface=xenbr0<br />
Connection=bridge<br />
BindsToInterface=(eth0) # Use the name of the external interface found with the 'ip link' command<br />
IP=dhcp<br />
assuming your existing network connection is called eth0. <br />
<br />
Start the network bridge with:<br />
# netctl start xenbridge-dhcp<br />
<br />
when the prompt returns, check all is well: {{hc|# brctl show|<br />
bridge name bridge id STP enabled interfaces<br />
xenbr0 8000.001a9206c0c0 no eth0<br />
}}<br />
If the bridge is working it can be set to start automatically after rebooting with:<br />
# netctl enable xenbridge-dhcp<br />
<br />
=== Installation of Xen systemd services ===<br />
The Xen dom0 requires the xenstored, xenconsoled, and xendomains system services (see [[Systemd]] for details).<br />
<br />
Archlinux uses systemd, but the current xen package has init scripts. You can start the daemons mentioned above like so:<br />
<br />
# /etc/rc.d/xencommons start<br />
<br />
=== Confirming successful installation ===<br />
Reboot your dom0 host and ensure that the Xen kernel boots correctly and that all settings survive a reboot. A properly set up dom0 should report the following when you run xl list (as root):<br />
{{hc|# xl list|<br />
Name ID Mem VCPUs State Time(s)<br />
Domain-0 0 511 2 r----- 41652.9}}<br />
Of course, the Mem, VCPUs and Time columns will be different depending on machine configuration and uptime. The important thing is that dom0 is listed.<br />
<br />
In addition to the required steps above, see [http://wiki.xen.org/wiki/Xen_Best_Practices best practices for running Xen] which includes information on allocating a fixed amount of memory and how to dedicate (pin) a CPU core for dom0 use. It also may be beneficial to create a xenfs filesystem mount point by including in ''/etc/fstab''<br />
none /proc/xen xenfs defaults 0 0<br />
<br />
== Using Xen ==<br />
Xen supports both paravirtualized (PV) and hardware virtualized (HVM) domUs. In the following sections the steps for creating HVM and PV domUs running Arch Linux are described. In general, the steps for creating an HVM domU are independent of the domU OS and HVM domUs support a wide range of operating systems including microsot Windows. To use HVM domUs the dom0 hardware must have virtualization support. Paravirtualized domUs do not require virtualization support, but instead require modifications to the guest operating system making the installation procedure different for each operating system (see the [http://wiki.xen.org/wiki/Category:Guest_Install Guest Install] page of the Xen wiki for links to instructions). Some operating systems (e.g., Microsoft Windows) cannot be installed as a PV domU. In general, HVM domUs often run slower than PV domUs since HVMs run on emulated hardware. While there are some common steps involved in setting up PV and HVM domUs, the processes are substantially different. In both cases, for each domU, a "hard disk" will need to be created and a configuration file needs to be written. Additionally, for installation each domU will need access to a copy of the installation ISO stored on the dom0 (see the [https://www.archlinux.org/download/ Download Page] to obtain the Arch Linux ISO).<br />
<br />
=== Create a domU "hard disk" ===<br />
Xen supports a number of different types of "hard disks" including [[LVM| Logical Volumes]], [[Partitioning|raw partitions]], and image files. To create a [[Wikipedia: Sparse file|sparse file]], that will grow to a maximum of 10GiB, called domU.img, use:<br />
truncate -s 10G domU.img<br />
If file IO speed is of greater importance than domain portability, using [[LVM|Logical Volumes]] or [[Partitioning|raw partitions]] may be a better choice.<br />
<br />
Xen may present any partition / disk available to the host machine to a domain as either a partition or disk. This means that, for example, an LVM partition on the host can appear as a hard drive (and hold multiple partitions) to a domain. Note that making sub-partitons on a partition will make accessing those partitions on the host machine more difficult. See the kpartx man page for information on how to map out partitions within a partition.<br />
<br />
=== Create a domU configuration ===<br />
Each domU requires a separate configuration file that is used to create the virtual machine. Full details about the configuration files can be found at the [http://wiki.xensource.com/xenwiki/XenConfigurationFileOptions| Xen Wiki] or the xl.cfg man page. Both HVM and PV domUs share some components of the configuration file. These include<br />
<nowiki><br />
name = "domU"<br />
memory = 256<br />
disk = [ "file:/path/to/ISO,sdb,r", "phy:/path/to/partition,sda1,w" ]<br />
vif = [ 'mac=00:16:3e:XX:XX:XX,bridge=xenbr0' ]<br />
</nowiki><br />
The {{ic|name&#61;}} is the name by which the xl tools manage the domU and needs to be unique across all domUs. The {{ic|disk&#61;}} includes information about both the the installation media ({{ic|file:}}) and the partition created for the domU {{ic|phy}}. If an image file is being used instead of a physical partition, the {{ic|phy:}} needs to be changed to {{ic|file:}}. The {{ic|vif&#61;}} defines a network controller. The 00:16:3e MAC block is reserved for Xen domains, so the last three digits of the {{ic|mac&#61;}} must be randomly filled in (hex values 0-9 and a-f only).<br />
<br />
=== Managing a domU ===<br />
If a domU should be started on boot, create a symlink to the configuration file in /etc/xen/auto and ensure the xendomains service is set up correctly. Some useful commands for managing domUs are:<br />
# xl top<br />
# xl list<br />
# xl console domUname<br />
# xl shutdown domUname<br />
# xl destroy domUname<br />
<br />
== Configuring a hardware virtualized (HVM) Arch domU ==<br />
In order to use HVM domUs install the {{Pkg|mesa-libgl}} and {{Pkg|bluez-libs}} packages.<br />
<br />
A minimal configuration file for a HVM Arch domU is:<br />
<nowiki><br />
name = 'HVM_domU'<br />
builder = 'hvm'<br />
memory = 256<br />
vcpus = 2<br />
disk = [ 'phy:/dev/mapper/vg0-hvm_arch,xvda,w', 'file:/path/to/ISO,hdc:cdrom,r' ]<br />
vif = [ 'mac=00:16:3e:00:00:00,bridge=xenbr0' ]<br />
vnc = 1<br />
vnclisten = '0.0.0.0'<br />
vncdisplay = 1<br />
</nowiki><br />
Since HVM machines do not have a console, they can only be connected to via a [[Vncserver|vncviewer]]. The configuration file allows for unauthenticated remote access of the domU vncserver and is not suitable for unsecured networks. The vncserver will be available on port 590X, where X is the value of {{ic|vncdisplay}}, of the dom0. The domU can be created with:<br />
<br />
# xl create /path/to/config/file<br />
<br />
and its status can be checked with<br />
<br />
# xl list<br />
<br />
Once the domU is created, connect to it via the vncserver and install Arch Linux as described in the [[Installation Guide]].<br />
<br />
== Configuring a paravirtualized (PV) Arch domU ==<br />
A minimal configuration file for a PV Arch domU is:<br />
<nowiki><br />
name = "PV_domU"<br />
kernel = "/mnt/arch/boot/x86_64/vmlinuz"<br />
ramdisk = "/mnt/arch/boot/x86_64/archiso.img"<br />
extra = "archisobasedir=arch archisolabel=ARCH_201301"<br />
memory = 256<br />
disk = [ "phy:/path/to/partition,sda1,w", "file:/path/to/ISO,sdb,r" ]<br />
vif = [ 'mac=00:16:3e:XX:XX:XX,bridge=xenbr0' ]<br />
</nowiki><br />
This file needs to tweaked for your specific use. Most importantly, the {{ic|1=archisolabel=ARCH_201301}} line must be edited to use the release year/month of the ISO being used. If you want to install 32-bit Arch, change the kernel and ramdisk paths from /x86_64/ to /i686/.<br />
<br />
Before creating the domU, the installation ISO must be loop-mounted. To do this, ensure the directory /mnt exists and is empty, then run the following command (being sure to fill in the correct ISO path):<br />
# mount -o loop /path/to/iso /mnt<br />
<br />
Once the ISO is mounted, the domU can be created with:<br />
<br />
# xl create -c /path/to/config/file<br />
<br />
The -c option will enter the domU's console when successfully created and install Arch Linux as described in the [[Installation Guide]]. There will be a few deviations, however. The block devices listed in the disks line of the cfg file will show up as {{ic|/dev/xvd*}}. Use these devices when partitioning the domU. After installation and before the domU is rebooted, the xen-blkfront xen-fbfront xen-netfront xen-kbdfront modules must be added to [[Mkinitcpio]]. Without these modules, the domU will not boot correctly. For booting, it is not necessary to install Grub. Xen has a Python-based grub emulator, so all that is needed to boot is a grub.cfg file: (It may be necessary to create the /boot/grub directory)<br />
{{hc|/boot/grub/grub.cfg|<nowiki>menuentry 'Arch GNU/Linux, with Linux core repo kernel' --class arch --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-core repo kernel-true-__UUID__' {<br />
insmod gzio<br />
insmod part_msdos<br />
insmod ext2<br />
set root='hd0,msdos1'<br />
if [ x$feature_platform_search_hint = xy ]; then<br />
search --no-floppy --fs-uuid --set=root --hint-bios=hd0,msdos1 --hint-efi=hd0,msdos1 --hint-baremetal=ahci0,msdos1 __UUID__<br />
else<br />
search --no-floppy --fs-uuid --set=root __UUID__<br />
fi<br />
echo 'Loading Linux core repo kernel ...'<br />
linux /boot/vmlinuz-linux root=UUID=__UUID__ ro<br />
echo 'Loading initial ramdisk ...'<br />
initrd /boot/initramfs-linux.img<br />
}</nowiki>}}<br />
This file must be edited to match the UUID of the root partition. From within the domU, run the following command:<br />
# blkid<br />
Replace all instances of __UUID__ with the real UUID of the root partition (the one that mounts as "/").<br />
<br />
Shutdown the domU with the {{ic|poweroff}} command. The console will be returned to the hypervisor when the domain is fully shut down, and the domain will no longer appear in the xl domains list. Now the ISO file may be unmounted:<br />
# umount /mnt<br />
The domU cfg file should now be edited. Delete the "kernel = ", "ramdisk = ", and "extra = " lines and replace them with the following line:<br />
bootloader = "pygrub"<br />
Also remove the ISO disk from the "disk = " line.<br />
<br />
The Arch domU is now set up. It may be started with the same line as before:<br />
# xl create -c /etc/xen/archdomu.cfg<br />
<br />
== Common Errors ==<br />
* 'xl list' complains about libxl<br />
- Either you have not booted into the Xen system, or xen modules listed in ''xencommons'' script are not installed<br />
<br />
* ''xl create'' fails<br />
- check the guest's kernel is located correctly, check the pv-xxx.cfg file for spelling mistakes (like using ''initrd'' instead of ''ramdisk'')<br />
<br />
* Arch linux guest hangs with a ctrl-d message<br />
- press ctrl-d until you get back to a prompt, rebuild its initramfs described <br />
<br />
* Error message "''failed to execute '/usr/lib/udev/socket:/org/xen/xend/udev_event' 'socket:/org/xen/xend/udev_event': No such file or directory''"<br />
- caused by ''/etc/udev/rules.d/xend.rules''; xend is (a) deprecated and (b) not used, so it is safe to remove xend.rules<br />
<br />
==Resources==<br />
* [http://www.xen.org/ The homepage at xen.org]<br />
* [http://wiki.xen.org/wiki/Main_Page The wiki at xen.org ]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Xen&diff=279969Xen2013-10-27T02:56:24Z<p>Netskink: /* Installation of Xen systemd services */ Added note about how to start up the xencommons script.</p>
<hr />
<div><br />
[[Category:Virtualization]]<br />
[[Category:Kernel]]<br />
[[de:Xen]]<br />
[[es:Xen]]<br />
[[ru:Xen]]<br />
{{Article summary start}}<br />
{{Article summary text|This article is about basic usage of Xen, including running Arch as both a Xen dom0 ''host'' and as a domU ''guest''.}}<br />
{{Article summary heading|Required software}}<br />
{{Article summary link|Xen|http://www.xen.org/}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|KVM}}<br />
{{Article summary wiki|QEMU}}<br />
{{Article summary wiki|VirtualBox}}<br />
{{Article summary wiki|VMware}}<br />
{{Article summary wiki|Moving an existing install into (or out of) a virtual machine}}<br />
{{Article summary end}}<br />
<br />
From [http://wiki.xen.org/wiki/Xen_Overview Xen Overview]:<br />
<br />
:''Xen is an open-source type-1 or baremetal hypervisor, which makes it possible to run many instances of an operating system or indeed different operating systems in parallel on a single machine (or host). Xen is the only type-1 hypervisor that is available as open source. Xen is used as the basis for a number of different commercial and open source applications, such as: server virtualization, Infrastructure as a Service (IaaS), desktop virtualization, security applications, embedded and hardware appliances.''<br />
<br />
==Introduction==<br />
<br />
The Xen hypervisor is a thin layer of software which emulates a computer architecture allowing multiple operating systems to run simultaneously. The hypervisor is started by the boot loader of the computer it is installed on. Once the hypervisor is loaded, it starts the "dom0" (short for "domain 0", sometimes called the host or privileged domain) which in our case runs Arch Linux. Once the dom0 has started, one or more "domUs" (short for user domains, sometimes called VMs or guests) can be started and controlled from the dom0. Xen supports both paravirtualized (PV) and hardware virtualized (HVM) domUs. See [http://wiki.xen.org/wiki/Xen_Overview Xen.org] for a full overview.<br />
<br />
==System requirements==<br />
The Xen hypervisor requires kernel level support which is included in recent Linux kernels and is built into the {{Pkg|linux}} and {{Pkg|linux-lts}} Arch kernel packages. To run run HVM domUs the physical hardware must have either Intel VT-x or AMD-V (SVM) virtualization support. In order to verify this, run the following command when the Xen hypervisor is not running:<br />
$ grep -E "(vmx|svm)" --color=always /proc/cpuinfo<br />
If the above command does not produce output, then hardware virtualization support is unavailable and your hardware is unable to run HVM domUs. If you believe the CPU supports one of these features you should access the host system's BIOS configuration menu during the boot process and look if options related to virtualization support have been disabled. If such an option exists and is disabled, then enable it, boot the system and repeat the above command. The Xen hypervisor also supports PCI passthrough where PCI devices can be passed directly to the domU even in the absence of dom0 support for the device. In order to use PCI passthrough the CPU must support IOMMU/VT-d.<br />
<br />
== Configuring dom0 ==<br />
The Xen hypervisor relies on a full install of the base operating system. Before attempting to install the Xen hypevisor, the host machine should have a fully operational and up-to-date install of Arch Linux. This installation can be a minimal install with only the base package and does not require a [[Desktop Environment]] or even [[Xorg]]. If you are building a new host from scratch, see the [[Installation Guide]] for instructions on installing Arch Linux. The following configuration steps are required to convert a standard installation into a working dom0 running on top of the Xen hypevisor:<br />
<br />
* Installation of the Xen hypervisor<br />
* Modification of the bootloader to boot the Xen hypervisor<br />
* Creation of a network bridge<br />
* Installation of Xen systemd services<br />
<br />
=== Installation of the Xen hypervisor ===<br />
To install the Xen hypervisor install either the current stable {{AUR|xen}} or the bleeding edge unstable {{AUR|xen-hg-unstable}} packages available in the [[Arch User Repository]]. Both packages provide the Xen hypervisor, current xl interface and all configuration and support files, including systemd services. The multilib repository needs to be enabled to install Xen (See [[Pacman#Repositories]] for details). Install the {{AUR|xen-docs}} package from the [[Arch User Repository]] for the man pages and documentation.<br />
<br />
=== Modification of the bootloader ===<br />
The boot loader must be modified to load a special Xen kernel (xen.gz) which is then used to boot the normal kernel. To do this a new bootloader entry is needed.<br />
<br />
For grub users, the Xen package provides the ''/etc/grub.d/09_xen'' generator file. The file ''/etc/xen/grub.conf'' can be edited to customize the Xen boot commands. For example, to allocate 512M of RAM to dom0 at boot, modify ''/etc/xen/grub.conf'' by replacing the line:<br />
#XEN_HYPERVISOR_CMDLINE="xsave=1"<br />
<br />
with<br />
XEN_HYPERVISOR_CMDLINE="dom0_mem=512M xsave=1"<br />
<br />
After customizing the options, update the bootloader configuration with the following command:<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
More information on using the GRUB bootloader is available at [[Grub]].<br />
<br />
For syslinux users, add a stanza like this:<br />
LABEL xen<br />
MENU LABEL My Xen<br />
KERNEL mboot.c32<br />
APPEND ../xen-4.3.0.gz --- ../vmlinuz-linux console=tty0 root=/dev/sda3 ro --- ../initramfs-linux.img<br />
<br />
Also this requires mboot.c32 to be in the same directory as the config file. If you have /boot and /usr in the same partition you can possibly link it. I don't know since I have /boot in a seperate partition. So, for users with /boot in a seperate paritition from /usr<br />
# cp /usr/lib/syslinux/mboot.c32 /boot/syslinux<br />
<br />
=== Creation of a network bridge ===<br />
Xen requires that network communications between domUs and the dom0 (and beyond) be set up manually. The use of both DHCP and static addressing is possible, and the choice should be determined by the network topology. Complex setups are possible, see the [http://wiki.xen.org/wiki/Xen_Networking Networking] article on the Xen wiki for details and ''/etc/xen/scripts'' for scripts for various networking configurations. A basic bridged network, in which a virtual switch is created in dom0 that every domU is attached to, can be setup by modifying the example configuration files provided by [[Netctl]] in ''etc/netctl/examples''. By default, Xen expects a bridge to exist named xenbr0. To set this up with netctl, do the following:<br />
<br />
# cd /etc/netctl<br />
# cp examples/bridge xenbridge-dhcp<br />
<br />
make the following changes to /etc/netctl/xenbridge-dhcp:<br />
Description="Xen bridge connection"<br />
Interface=xenbr0<br />
Connection=bridge<br />
BindsToInterface=(eth0) # Use the name of the external interface found with the 'ip link' command<br />
IP=dhcp<br />
assuming your existing network connection is called eth0. <br />
<br />
Start the network bridge with:<br />
# netctl start xenbridge-dhcp<br />
<br />
when the prompt returns, check all is well: {{hc|# brctl show|<br />
bridge name bridge id STP enabled interfaces<br />
xenbr0 8000.001a9206c0c0 no eth0<br />
}}<br />
If the bridge is working it can be set to start automatically after rebooting with:<br />
# netctl enable xenbridge-dhcp<br />
<br />
=== Installation of Xen systemd services ===<br />
The Xen dom0 requires the xenstored, xenconsoled, and xendomains system services (see [[Systemd]] for details).<br />
<br />
Archlinux uses systemd, but the current xen package has init scripts. You can start the daemons mentioned above like so:<br />
<br />
# /etc/rc.d/xencommons start<br />
<br />
=== Confirming successful installation ===<br />
Reboot your dom0 host and ensure that the Xen kernel boots correctly and that all settings survive a reboot. A properly set up dom0 should report the following when you run xl list (as root):<br />
{{hc|# xl list|<br />
Name ID Mem VCPUs State Time(s)<br />
Domain-0 0 511 2 r----- 41652.9}}<br />
Of course, the Mem, VCPUs and Time columns will be different depending on machine configuration and uptime. The important thing is that dom0 is listed.<br />
<br />
In addition to the required steps above, see [http://wiki.xen.org/wiki/Xen_Best_Practices best practices for running Xen] which includes information on allocating a fixed amount of memory and how to dedicate (pin) a CPU core for dom0 use. It also may be beneficial to create a xenfs filesystem mount point by including in ''/etc/fstab''<br />
none /proc/xen xenfs defaults 0 0<br />
<br />
== Using Xen ==<br />
Xen supports both paravirtualized (PV) and hardware virtualized (HVM) domUs. In the following sections the steps for creating HVM and PV domUs running Arch Linux are described. In general, the steps for creating an HVM domU are independent of the domU OS and HVM domUs support a wide range of operating systems including microsot Windows. To use HVM domUs the dom0 hardware must have virtualization support. Paravirtualized domUs do not require virtualization support, but instead require modifications to the guest operating system making the installation procedure different for each operating system (see the [http://wiki.xen.org/wiki/Category:Guest_Install Guest Install] page of the Xen wiki for links to instructions). Some operating systems (e.g., Microsoft Windows) cannot be installed as a PV domU. In general, HVM domUs often run slower than PV domUs since HVMs run on emulated hardware. While there are some common steps involved in setting up PV and HVM domUs, the processes are substantially different. In both cases, for each domU, a "hard disk" will need to be created and a configuration file needs to be written. Additionally, for installation each domU will need access to a copy of the installation ISO stored on the dom0 (see the [https://www.archlinux.org/download/ Download Page] to obtain the Arch Linux ISO).<br />
<br />
=== Create a domU "hard disk" ===<br />
Xen supports a number of different types of "hard disks" including [[LVM| Logical Volumes]], [[Partitioning|raw partitions]], and image files. To create a [[Wikipedia: Sparse file|sparse file]], that will grow to a maximum of 10GiB, called domU.img, use:<br />
truncate -s 10G domU.img<br />
If file IO speed is of greater importance than domain portability, using [[LVM|Logical Volumes]] or [[Partitioning|raw partitions]] may be a better choice.<br />
<br />
Xen may present any partition / disk available to the host machine to a domain as either a partition or disk. This means that, for example, an LVM partition on the host can appear as a hard drive (and hold multiple partitions) to a domain. Note that making sub-partitons on a partition will make accessing those partitions on the host machine more difficult. See the kpartx man page for information on how to map out partitions within a partition.<br />
<br />
=== Create a domU configuration ===<br />
Each domU requires a separate configuration file that is used to create the virtual machine. Full details about the configuration files can be found at the [http://wiki.xensource.com/xenwiki/XenConfigurationFileOptions| Xen Wiki] or the xl.cfg man page. Both HVM and PV domUs share some components of the configuration file. These include<br />
<nowiki><br />
name = "domU"<br />
memory = 256<br />
disk = [ "file:/path/to/ISO,sdb,r", "phy:/path/to/partition,sda1,w" ]<br />
vif = [ 'mac=00:16:3e:XX:XX:XX,bridge=xenbr0' ]<br />
</nowiki><br />
The {{ic|name&#61;}} is the name by which the xl tools manage the domU and needs to be unique across all domUs. The {{ic|disk&#61;}} includes information about both the the installation media ({{ic|file:}}) and the partition created for the domU {{ic|phy}}. If an image file is being used instead of a physical partition, the {{ic|phy:}} needs to be changed to {{ic|file:}}. The {{ic|vif&#61;}} defines a network controller. The 00:16:3e MAC block is reserved for Xen domains, so the last three digits of the {{ic|mac&#61;}} must be randomly filled in (hex values 0-9 and a-f only).<br />
<br />
=== Managing a domU ===<br />
If a domU should be started on boot, create a symlink to the configuration file in /etc/xen/auto and ensure the xendomains service is set up correctly. Some useful commands for managing domUs are:<br />
# xl top<br />
# xl list<br />
# xl console domUname<br />
# xl shutdown domUname<br />
# xl destroy domUname<br />
<br />
== Configuring a hardware virtualized (HVM) Arch domU ==<br />
In order to use HVM domUs install the {{Pkg|mesa-libgl}} and {{Pkg|bluez-libs}} packages.<br />
<br />
A minimal configuration file for a HVM Arch domU is:<br />
<nowiki><br />
name = 'HVM_domU'<br />
builder = 'hvm'<br />
memory = 256<br />
vcpus = 2<br />
disk = [ 'phy:/dev/mapper/vg0-hvm_arch,xvda,w', 'file:/path/to/ISO,hdc:cdrom,r' ]<br />
vif = [ 'mac=00:16:3e:00:00:00,bridge=xenbr0' ]<br />
vnc = 1<br />
vnclisten = '0.0.0.0'<br />
vncdisplay = 1<br />
</nowiki><br />
Since HVM machines do not have a console, they can only be connected to via a [[Vncserver|vncviewer]]. The configuration file allows for unauthenticated remote access of the domU vncserver and is not suitable for unsecured networks. The vncserver will be available on port 590X, where X is the value of {{ic|vncdisplay}}, of the dom0. The domU can be created with:<br />
<br />
# xl create /path/to/config/file<br />
<br />
and its status can be checked with<br />
<br />
# xl list<br />
<br />
Once the domU is created, connect to it via the vncserver and install Arch Linux as described in the [[Installation Guide]].<br />
<br />
== Configuring a paravirtualized (PV) Arch domU ==<br />
A minimal configuration file for a PV Arch domU is:<br />
<nowiki><br />
name = "PV_domU"<br />
kernel = "/mnt/arch/boot/x86_64/vmlinuz"<br />
ramdisk = "/mnt/arch/boot/x86_64/archiso.img"<br />
extra = "archisobasedir=arch archisolabel=ARCH_201301"<br />
memory = 256<br />
disk = [ "phy:/path/to/partition,sda1,w", "file:/path/to/ISO,sdb,r" ]<br />
vif = [ 'mac=00:16:3e:XX:XX:XX,bridge=xenbr0' ]<br />
</nowiki><br />
This file needs to tweaked for your specific use. Most importantly, the {{ic|1=archisolabel=ARCH_201301}} line must be edited to use the release year/month of the ISO being used. If you want to install 32-bit Arch, change the kernel and ramdisk paths from /x86_64/ to /i686/.<br />
<br />
Before creating the domU, the installation ISO must be loop-mounted. To do this, ensure the directory /mnt exists and is empty, then run the following command (being sure to fill in the correct ISO path):<br />
# mount -o loop /path/to/iso /mnt<br />
<br />
Once the ISO is mounted, the domU can be created with:<br />
<br />
# xl create -c /path/to/config/file<br />
<br />
The -c option will enter the domU's console when successfully created and install Arch Linux as described in the [[Installation Guide]]. There will be a few deviations, however. The block devices listed in the disks line of the cfg file will show up as {{ic|/dev/xvd*}}. Use these devices when partitioning the domU. After installation and before the domU is rebooted, the xen-blkfront xen-fbfront xen-netfront xen-kbdfront modules must be added to [[Mkinitcpio]]. Without these modules, the domU will not boot correctly. For booting, it is not necessary to install Grub. Xen has a Python-based grub emulator, so all that is needed to boot is a grub.cfg file: (It may be necessary to create the /boot/grub directory)<br />
{{hc|/boot/grub/grub.cfg|<nowiki>menuentry 'Arch GNU/Linux, with Linux core repo kernel' --class arch --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-core repo kernel-true-__UUID__' {<br />
insmod gzio<br />
insmod part_msdos<br />
insmod ext2<br />
set root='hd0,msdos1'<br />
if [ x$feature_platform_search_hint = xy ]; then<br />
search --no-floppy --fs-uuid --set=root --hint-bios=hd0,msdos1 --hint-efi=hd0,msdos1 --hint-baremetal=ahci0,msdos1 __UUID__<br />
else<br />
search --no-floppy --fs-uuid --set=root __UUID__<br />
fi<br />
echo 'Loading Linux core repo kernel ...'<br />
linux /boot/vmlinuz-linux root=UUID=__UUID__ ro<br />
echo 'Loading initial ramdisk ...'<br />
initrd /boot/initramfs-linux.img<br />
}</nowiki>}}<br />
This file must be edited to match the UUID of the root partition. From within the domU, run the following command:<br />
# blkid<br />
Replace all instances of __UUID__ with the real UUID of the root partition (the one that mounts as "/").<br />
<br />
Shutdown the domU with the {{ic|poweroff}} command. The console will be returned to the hypervisor when the domain is fully shut down, and the domain will no longer appear in the xl domains list. Now the ISO file may be unmounted:<br />
# umount /mnt<br />
The domU cfg file should now be edited. Delete the "kernel = ", "ramdisk = ", and "extra = " lines and replace them with the following line:<br />
bootloader = "pygrub"<br />
Also remove the ISO disk from the "disk = " line.<br />
<br />
The Arch domU is now set up. It may be started with the same line as before:<br />
# xl create -c /etc/xen/archdomu.cfg<br />
<br />
== Common Errors ==<br />
* 'xl list' complains about libxl<br />
- Either you have not booted into the Xen system, or xen modules listed in ''xencommons'' script are not installed<br />
<br />
* ''xl create'' fails<br />
- check the guest's kernel is located correctly, check the pv-xxx.cfg file for spelling mistakes (like using ''initrd'' instead of ''ramdisk'')<br />
<br />
* Arch linux guest hangs with a ctrl-d message<br />
- press ctrl-d until you get back to a prompt, rebuild its initramfs described <br />
<br />
* Error message "''failed to execute '/usr/lib/udev/socket:/org/xen/xend/udev_event' 'socket:/org/xen/xend/udev_event': No such file or directory''"<br />
- caused by ''/etc/udev/rules.d/xend.rules''; xend is (a) deprecated and (b) not used, so it is safe to remove xend.rules<br />
<br />
==Resources==<br />
* [http://www.xen.org/ The homepage at xen.org]<br />
* [http://wiki.xen.org/wiki/Main_Page The wiki at xen.org ]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_T420&diff=278898Lenovo ThinkPad T4202013-10-18T03:31:10Z<p>Netskink: /* No backlight controls */ minor edit to bypass Xwindows keybinding issues.</p>
<hr />
<div>[[Category:Lenovo]]<br />
[[zh-CN:Lenovo ThinkPad T420]]<br />
This article covers the installation and configuration of Arch Linux on a Lenovo T420 laptop.<br />
<br />
== Installation ==<br />
<br />
This laptop supports [[Unified_Extensible_Firmware_Interface|UEFI]] as well as the traditional BIOS.<br />
<br />
There are no issues with installing Arch Linux with the latest [https://www.archlinux.org/download/ Archiso].<br />
<br />
The rest of the installation process can be followed with the [[Installation Guide]].<br />
<br />
== Hardware ==<br />
<br />
All hardware works out of the box except the following:<br />
<br />
=== Fingerprint reader ===<br />
<br />
Fingerprint reader works great with fprint and PAM (installation of fingerprint-gui recommended).<br />
<br />
See [[Fprint#Setup_fingerprint-gui]] for more information.<br />
<br />
=== Some Media keys ===<br />
<br />
* See [[#Media Keys|Media Keys]]<br />
<br />
=== Untested ===<br />
<br />
* Firewire<br />
<br />
==Laptop Settings==<br />
<br />
===ACPI===<br />
<br />
[[ACPI_modules|ACPI]] is well supported here. No obvious troubleshoots.<br />
<br />
=== Tp_smapi ===<br />
<br />
Unfortunately, [[Tp_smapi|tp_smapi]] is only partially supported on the Thinkpad T420. A number of features work since version 0.41. For example, the hard drive protection mechanism [[HDAPS]] now works well. See the linked wiki entry.<br />
<br />
Some features like setting the starting threshold for charging the battery do not yet work. To control the battery charging thresholds, install the Perl script {{AUR|tpacpi-bat}} from the [[AUR]].<br />
<br />
Insert the {{ic|acpi_call}} kernel module by running<br />
modprobe acpi_call<br />
<br />
Manually set the thresholds by calling<br />
perl /usr/lib/perl5/vendor_perl/tpacpi-bat -v startChargeThreshold 0 40<br />
perl /usr/lib/perl5/vendor_perl/tpacpi-bat -v stopChargeThreshold 0 80<br />
The example values 40 and 80 given here are in percent of the full battery capacity. Adjust them to your own needs. You may also want to write a simple {{ic|set-battery.service}} and enable it to set them at startup. While these values should be permanent, they will be reset any time the battery is removed.<br />
<br />
[Unit]<br />
Description=Set battery capacity<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/perl /usr/lib/perl5/vendor_perl/tpacpi-bat -v stopChargeThreshold 0 80<br />
ExecStart=/usr/bin/perl /usr/lib/perl5/vendor_perl/tpacpi-bat -v startChargeThreshold 0 40<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
<br />
<br />
Also, if you are dual booting with Windows, you can still control the battery charging thresholds with Lenovo's Power Manager which communicates directly to the battery controller.<br />
<br />
When using systemd, you may want to blacklist the tp_smapi module if your systemd-modules-load.service fails, as new ThinkPads handle everything over acpi.<br />
<br />
=== CPU frequency scaling ===<br />
<br />
[[CPU Frequency Scaling|CPU frequency scaling]] is fully supported with all of the available processor models with this laptop.<br />
<br />
=== Fans ===<br />
<br />
The thinkpad_acpi kernel module needs to be configured so user space programs can control the fan speed.<br />
<br />
{{hc|/etc/modprobe.d/thinkpad_acpi.conf|2=options thinkpad_acpi fan_control=1}}<br />
<br />
The {{AUR|thinkfan}} configuration file also needs to know how to set the fan speed. Replace the default sensor settings with the following.<br />
<br />
{{hc|/etc/thinkfan.conf|sensor /sys/devices/virtual/thermal/thermal_zone0/temp}}<br />
<br />
Enable [[systemd]] [[daemon]] '''thinkfan'''.<br />
<br />
=== Laptop Mode Tools ===<br />
<br />
No significant issues were found using [[Laptop Mode Tools]].<br />
<br />
Possible bug with [[#Shutdown on Battery]]<br />
<br />
{{AUR|tlp}} From the [[AUR]] is an alternative tool that can replace {{Pkg|laptop-mode-tools}}.<br />
<br />
=== Synaptics ===<br />
<br />
TouchPad and TrackPoint do work out of the box, but the TouchPad is way too sensitive (i.e. fast) to be usable, since it is recognized as a mouse. To fix this, [[pacman|install]] the {{Pkg|xf86-input-synaptics}} package and add the following two files to your {{ic|/etc/X11/xorg.conf.d/}} directory:<br />
<br />
{{hc|50-thinkpad-trackpoint.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "ThinkPad TrackPoint"<br />
MatchProduct "TPPS/2 IBM TrackPoint"<br />
MatchDevicePath "/dev/input/event*"<br />
Option "EmulateWheel" "true"<br />
Option "EmulateWheelButton" "2"<br />
Option "XAxisMapping" "6 7"<br />
Option "YAxisMapping" "4 5"<br />
EndSection<br />
</nowiki>}}<br />
<br />
{{hc|50-twofingerscroll.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "two finger scrolling"<br />
Driver "synaptics"<br />
MatchProduct "SynPS/2 Synaptics TouchPad"<br />
MatchDevicePath "/dev/input/event*"<br />
Option "VertTwoFingerScroll" "on"<br />
Option "HorizTwoFingerScroll" "on"<br />
Option "EmulateTwoFingerMinW" "8"<br />
Option "EmulateTwoFingerMinZ" "40"<br />
Option "TapButton1" "1"<br />
EndSection<br />
</nowiki>}}<br />
<br />
Adjust to your own needs. Read [[Touchpad Synaptics]] for more information.<br />
<br />
To adjust the speed/sensitivity of the TrackPoint add these lines in a systemd tmpfile:<br />
<br />
{{hc|/etc/tmpfiles.d/local.conf|<br />
w /sys/devices/platform/i8042/serio1/speed - - - - 180<br />
w /sys/devices/platform/i8042/serio1/sensitivity - - - - 200<br />
}}<br />
<br />
Possible range of values are 1-255.<br />
<br />
=== NVIDIA Optimus ===<br />
<br />
[[Bumblebee|Bumblebee]] works as intended on models with NVIDIA Optimus<br />
<br />
=== Optional kernel boot arguments ===<br />
Using the following kernel boot parameters [http://www.phoronix.com/scan.php?page=article&item=intel_i915_power&num=1| reduces battery drain]:<br />
<br />
{{bc|<nowiki><br />
i915.i915_enable_rc6=1<br />
i915.i915_enable_fbc=1<br />
i915.lvds_downclock=1 <br />
i915.semaphores=1<br />
</nowiki>}}<br />
<br />
{{Note| With the current 3.6.x kernels, there appears to be a power regression with an unknown cause. It is yet to be fixed in any 3.7 versions of the kernel.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Media Keys ===<br />
<br />
Media keys that work out of the box:<br />
* Wireless On/Off<br />
* Backlight Brightness settings<br />
* Thinklight<br />
* Mute<br />
<br />
Media Keys that Do Not work out of the box:<br />
* [[Lenovo_ThinkPad_T420#Volume_up.2Fdown_not_changing_volume|Volume keys]] (Works out-of-the-box in [[Gnome|Gnome]])<br />
* Microphone mute (Will most likely require a custom kernel patch)<br />
You must find a workaround and bind the keys yourself for the rest of them.<br />
<br />
=== Rebind Forward and Back keys ===<br />
<br />
Keys forward and back (next to cursor keys) can be easily remapped to PageDown/PageUp.<br />
<br />
[[pacman|Install]] xmodmap with the package {{Pkg|xorg-server-utils}}<br />
<br />
Create a {{ic|~/.Xmodmap}} file with content:<br />
keysym XF86Back = Page_Up<br />
keysym XF86Forward = Page_Down<br />
<br />
Add this line to your {{ic|~/.xinitrc}} to make it work:<br />
xmodmap ~/.Xmodmap<br />
<br />
You can also re-map AudioPrev ({{ic|Fn+Left}}) and AudioNext ({{ic|Fn+Right}}) to Home/End:<br />
keysym XF86AudioNext = End<br />
keysym XF86AudioPrev = Home<br />
<br />
{{Note|<br />
* You have to log out for the changes to take effect.<br />
* The keys should work out of the box, at least on [[KDE]].<br />
}}<br />
<br />
=== Turn touchpad on and off ===<br />
<br />
For some, the ({{ic|Fn+F8}}) key does not switch the touchpad on and off. Here is a simple keybind to add to your {{ic|~/.xbindkeysrc}} for keys to quickly change your touchpad state. For these to take effect, run {{ic|xbindkeysrc}}. This binds {{ic|Fn+F8}} to 'toggle the touchpad on and off'. (Tested in i3wm and xfce4, where normal {{ic|Fn+F8}} does not toggle the touchpad)<br />
<br />
# Toggle the Touchpad on|off<br />
"synclient TouchpadOff=$(synclient -l | grep -ce TouchpadOff.*0)"<br />
m:0x0 + c:199<br />
XF86TouchpadToggle<br />
<br />
=== Volume up/down not changing volume ===<br />
<br />
Another quick keybind for {{ic|~/.xbindkeysrc}} to change the volume (which does not work on some DEs). Again, run {{ic|xbindkeys}} for these to take effect. Taken from [[Xbindkeys]]<br />
<br />
#increase volume<br />
"amixer set Master playback 1+"<br />
m:0x0 + c:123<br />
XF86AudioRaiseVolume<br />
<br />
#decrase volume<br />
"amixer set Master playback 1-"<br />
m:0x0 + c:122<br />
XF86AudioLowerVolume<br />
<br />
Also, while the mute button works, I rebound it to interface with ALSA. <br />
<br />
# Toggle mute<br />
"amixer set Master toggle"<br />
m:0x0 + c:121<br />
XF86AudioMute<br />
<br />
=== Shutdown on battery ===<br />
<br />
Some users have reported that the T420 was rebooting on shutdown on battery power. There have been quite a few attempts to fix this. Three are detailed here. <br />
<br />
One way is to disable the module {{ic|ehci_hcd}}. See [[Kernel_modules#Blacklisting]] for more information.<br />
<br />
Or try disable Laptop-mode. <br />
Add {{Ic|!laptop-mode}} to the {{Ic|DAEMONS}} array in {{ic|/etc/rc.conf}}:<br />
DAEMONS=(...!laptop-mode...)<br />
<br />
[https://bbs.archlinux.org/viewtopic.php?pid=1106437#p1106437 This forum post] details another way to have your computer not reboot on shutdown. Turning off the {{ic|laptop-mode}} daemon causes battery life to suffer, so when on the move and in need of a simple way to shutdown, this seems to work better.<br />
<br />
=== Hang on reboot ===<br />
<br />
This is a problem on many laptops and can be fixed by [[Kernel modules#Blacklisting|blacklisting]] the {{ic|e1000e}} kernel module.<br />
<br />
=== No 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 />
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 />
== See also ==<br />
<br />
* [[Lenovo ThinkPad T420s]]<br />
* [http://sysphere.org/~anrxc/j/articles/thinkpad-t420/index.html Arch Linux on ThinkPad T420i]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=ThinkPad_multimedia_buttons&diff=278076ThinkPad multimedia buttons2013-10-09T03:45:54Z<p>Netskink: /* Configuring Buttons to Software */ noticed i had left off a part.</p>
<hr />
<div>== Configuring the mute, volume up and volume down buttons in ArchLinux: ==<br />
=== Step 1 Device Drivers ===<br />
:Install the necessary device drivers and configure the OS_Linux in the kernel command line.<br />
=== Step 2 Applications ===<br />
:Install ALSA and make sure that alsamixer is able to mute/unmute and adjust volume.<br />
=== Configuring Buttons to Software ===<br />
:Step one and two are well documented. Search the wiki for other instructions on how to do this.<br />
<br />
:You are ready to proceed to this step if you can play audio with your favorite application and adjust the sound volume using the alsamixer application in [[alsa]] package.<br />
<br />
:This [http://wiki.archlinux.org/index.php/Lenovo_ThinkPad_T400#Multimedia_Keys page] will show you how to use [[Extra_Keyboard_Keys#Using_xev|xev]] to determine the keycodes for the mute, volume up and volume down buttons.<br />
<br />
:That page also shows how to use {{Pkg|xbindkeys}} to setup a .xbindkeysrc.scm file. However, the device settings might vary for your setup. Here is how to use amixer to find your device settings. Use the amixer command with the parameter scontrols. This gives the name for the master volume control.<br />
<br />
$ amixer scontrols<br />
Simple mixer control 'Master',0<br />
Simple mixer control 'Capture',0<br />
$<br />
<br />
:Open alsamixer and examine the output as you issue commands to set the volume. As you adjust the volume setting using amixer, you should see the volume level in alsamixer change. Here I am adjusting the volume louder with each invocation of amixer<br />
<br />
$ amixer -c 0 sset 'Master',0 40 <br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 40 [54%] [-34.00dB] [on]<br />
$ amixer -c 0 sset 'Master',0 60<br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 60 [81%] [-14.00dB] [on]<br />
$ amixer -c 0 sset 'Master',0 80<br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 74 [100%] [0.00dB] [on]<br />
$<br />
<br />
:This command sets the volume to a specified level, however we want the volume buttons to adjust the current volume. Thus, we use the +/-dB form of the command. This is shown in the final .xbindkeysrc.scm. Likewise the mute button is specified.<br />
<br />
$ cat .xbindkeysrc.scm <br />
(xbindkey '("XF86AudioRaiseVolume") "amixer -c 0 sset 'Master',0 2dB+")<br />
(xbindkey '("XF86AudioLowerVolume") "amixer -c 0 sset 'Master',0 2dB-")<br />
(xbindkey '("XF86AudioMute") "amixer set Master toggle")<br />
<br />
:Restart xwindows and now your media buttons should work.</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Xen&diff=278070Xen2013-10-08T22:11:00Z<p>Netskink: /* Modification of the bootloader */ instructions on syslinux bootloader</p>
<hr />
<div><br />
[[Category:Virtualization]]<br />
[[Category:Kernel]]<br />
[[de:Xen]]<br />
[[es:Xen]]<br />
[[ru:Xen]]<br />
{{Article summary start}}<br />
{{Article summary text|This article is about basic usage of Xen, including running Arch as both a Xen dom0 ''host'' and as a domU ''guest''.}}<br />
{{Article summary heading|Required software}}<br />
{{Article summary link|Xen|http://www.xen.org/}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|KVM}}<br />
{{Article summary wiki|QEMU}}<br />
{{Article summary wiki|VirtualBox}}<br />
{{Article summary wiki|VMware}}<br />
{{Article summary wiki|Moving an existing install into (or out of) a virtual machine}}<br />
{{Article summary end}}<br />
<br />
From [http://wiki.xen.org/wiki/Xen_Overview Xen Overview]:<br />
<br />
:''Xen is an open-source type-1 or baremetal hypervisor, which makes it possible to run many instances of an operating system or indeed different operating systems in parallel on a single machine (or host). Xen is the only type-1 hypervisor that is available as open source. Xen is used as the basis for a number of different commercial and open source applications, such as: server virtualization, Infrastructure as a Service (IaaS), desktop virtualization, security applications, embedded and hardware appliances.''<br />
<br />
==Introduction==<br />
<br />
The Xen hypervisor is a thin layer of software which emulates a computer architecture allowing multiple operating systems to run simultaneously. The hypervisor is started by the boot loader of the computer it is installed on. Once the hypervisor is loaded, it starts the "dom0" (short for "domain 0", sometimes called the host or privileged domain) which in our case runs Arch Linux. Once the dom0 has started, one or more "domUs" (short for user domains, sometimes called VMs or guests) can be started and controlled from the dom0. Xen supports both paravirtualized (PV) and hardware virtualized (HVM) domUs. See [http://wiki.xen.org/wiki/Xen_Overview Xen.org] for a full overview.<br />
<br />
==System requirements==<br />
The Xen hypervisor requires kernel level support which is included in recent Linux kernels and is built into the {{Pkg|linux}} and {{Pkg|linux-lts}} Arch kernel packages. To run run HVM domUs the physical hardware must have either Intel VT-x or AMD-V (SVM) virtualization support. In order to verify this, run the following command when the Xen hypervisor is not running:<br />
$ grep -E "(vmx|svm)" --color=always /proc/cpuinfo<br />
If the above command does not produce output, then hardware virtualization support is unavailable and your hardware is unable to run HVM domUs. If you believe the CPU supports one of these features you should access the host system's BIOS configuration menu during the boot process and look if options related to virtualization support have been disabled. If such an option exists and is disabled, then enable it, boot the system and repeat the above command. The Xen hypervisor also supports PCI passthrough where PCI devices can be passed directly to the domU even in the absence of dom0 support for the device. In order to use PCI passthrough the CPU must support IOMMU/VT-d.<br />
<br />
== Configuring dom0 ==<br />
The Xen hypervisor relies on a full install of the base operating system. Before attempting to install the Xen hypevisor, the host machine should have a fully operational and up-to-date install of Arch Linux. This installation can be a minimal install with only the base package and does not require a [[Desktop Environment]] or even [[Xorg]]. If you are building a new host from scratch, see the [[Installation Guide]] for instructions on installing Arch Linux. The following configuration steps are required to convert a standard installation into a working dom0 running on top of the Xen hypevisor:<br />
<br />
* Installation of the Xen hypervisor<br />
* Modification of the bootloader to boot the Xen hypervisor<br />
* Creation of a network bridge<br />
* Installation of Xen systemd services<br />
<br />
=== Installation of the Xen hypervisor ===<br />
To install the Xen hypervisor install either the current stable {{AUR|xen}} or the bleeding edge unstable {{AUR|xen-hg-unstable}} packages available in the [[Arch User Repository]]. Both packages provide the Xen hypervisor, current xl interface and all configuration and support files, including systemd services. The multilib repository needs to be enabled to install Xen (See [[Pacman#Repositories]] for details). Install the {{AUR|xen-docs}} package from the [[Arch User Repository]] for the man pages and documentation.<br />
<br />
=== Modification of the bootloader ===<br />
The boot loader must be modified to load a special Xen kernel (xen.gz) which is then used to boot the normal kernel. To do this a new bootloader entry is needed.<br />
<br />
For grub users, the Xen package provides the ''/etc/grub.d/09_xen'' generator file. The file ''/etc/xen/grub.conf'' can be edited to customize the Xen boot commands. For example, to allocate 512M of RAM to dom0 at boot, modify ''/etc/xen/grub.conf'' by replacing the line:<br />
#XEN_HYPERVISOR_CMDLINE="xsave=1"<br />
<br />
with<br />
XEN_HYPERVISOR_CMDLINE="dom0_mem=512M xsave=1"<br />
<br />
After customizing the options, update the bootloader configuration with the following command:<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
More information on using the GRUB bootloader is available at [[Grub]].<br />
<br />
For syslinux users, add a stanza like this:<br />
LABEL xen<br />
MENU LABEL My Xen<br />
KERNEL mboot.c32<br />
APPEND ../xen-4.3.0.gz --- ../vmlinuz-linux console=tty0 root=/dev/sda3 ro --- ../initramfs-linux.img<br />
<br />
Also this requires mboot.c32 to be in the same directory as the config file. If you have /boot and /usr in the same partition you can possibly link it. I don't know since I have /boot in a seperate partition. So, for users with /boot in a seperate paritition from /usr<br />
# cp /usr/lib/syslinux/mboot.c32 /boot/syslinux<br />
<br />
=== Creation of a network bridge ===<br />
Xen requires that network communications between domUs and the dom0 (and beyond) be set up manually. The use of both DHCP and static addressing is possible, and the choice should be determined by the network topology. Complex setups are possible, see the [http://wiki.xen.org/wiki/Xen_Networking Networking] article on the Xen wiki for details and ''/etc/xen/scripts'' for scripts for various networking configurations. A basic bridged network, in which a virtual switch is created in dom0 that every domU is attached to, can be setup by modifying the example configuration files provided by [[Netctl]] in ''etc/netctl/examples''. By default, Xen expects a bridge to exist named xenbr0. To set this up with netctl, do the following:<br />
<br />
# cd /etc/netctl<br />
# cp examples/bridge xenbridge-dhcp<br />
<br />
make the following changes to /etc/netctl/xenbridge-dhcp:<br />
Description="Xen bridge connection"<br />
Interface=xenbr0<br />
Connection=bridge<br />
BindsToInterface=(eth0) # Use the name of the external interface found with the 'ip link' command<br />
IP=dhcp<br />
assuming your existing network connection is called eth0. <br />
<br />
Start the network bridge with:<br />
# netctl start xenbridge-dhcp<br />
<br />
when the prompt returns, check all is well: {{hc|# brctl show|<br />
bridge name bridge id STP enabled interfaces<br />
xenbr0 8000.001a9206c0c0 no eth0<br />
}}<br />
If the bridge is working it can be set to start automatically after rebooting with:<br />
# netctl enable xenbridge-dhcp<br />
<br />
=== Installation of Xen systemd services ===<br />
The Xen dom0 requires the xenstored, xenconsoled, and xendomains system services (see [[Systemd]] for details).<br />
<br />
=== Confirming successful installation ===<br />
Reboot your dom0 host and ensure that the Xen kernel boots correctly and that all settings survive a reboot. A properly set up dom0 should report the following when you run xl list (as root):<br />
{{hc|# xl list|<br />
Name ID Mem VCPUs State Time(s)<br />
Domain-0 0 511 2 r----- 41652.9}}<br />
Of course, the Mem, VCPUs and Time columns will be different depending on machine configuration and uptime. The important thing is that dom0 is listed.<br />
<br />
In addition to the required steps above, see [http://wiki.xen.org/wiki/Xen_Best_Practices best practices for running Xen] which includes information on allocating a fixed amount of memory and how to dedicate (pin) a CPU core for dom0 use. It also may be beneficial to create a xenfs filesystem mount point by including in ''/etc/fstab''<br />
none /proc/xen xenfs defaults 0 0<br />
<br />
== Using Xen ==<br />
Xen supports both paravirtualized (PV) and hardware virtualized (HVM) domUs. In the following sections the steps for creating HVM and PV domUs running Arch Linux are described. In general, the steps for creating an HVM domU are independent of the domU OS and HVM domUs support a wide range of operating systems including microsot Windows. To use HVM domUs the dom0 hardware must have virtualization support. Paravirtualized domUs do not require virtualization support, but instead require modifications to the guest operating system making the installation procedure different for each operating system (see the [http://wiki.xen.org/wiki/Category:Guest_Install Guest Install] page of the Xen wiki for links to instructions). Some operating systems (e.g., Microsoft Windows) cannot be installed as a PV domU. In general, HVM domUs often run slower than PV domUs since HVMs run on emulated hardware. While there are some common steps involved in setting up PV and HVM domUs, the processes are substantially different. In both cases, for each domU, a "hard disk" will need to be created and a configuration file needs to be written. Additionally, for installation each domU will need access to a copy of the installation ISO stored on the dom0 (see the [https://www.archlinux.org/download/ Download Page] to obtain the Arch Linux ISO).<br />
<br />
=== Create a domU "hard disk" ===<br />
Xen supports a number of different types of "hard disks" including [[LVM| Logical Volumes]], [[Partitioning|raw partitions]], and image files. To create a [[Wikipedia: Sparse file|sparse file]], that will grow to a maximum of 10GiB, called domU.img, use:<br />
truncate -s 10G domU.img<br />
If file IO speed is of greater importance than domain portability, using [[LVM|Logical Volumes]] or [[Partitioning|raw partitions]] may be a better choice.<br />
<br />
Xen may present any partition / disk available to the host machine to a domain as either a partition or disk. This means that, for example, an LVM partition on the host can appear as a hard drive (and hold multiple partitions) to a domain. Note that making sub-partitons on a partition will make accessing those partitions on the host machine more difficult. See the kpartx man page for information on how to map out partitions within a partition.<br />
<br />
=== Create a domU configuration ===<br />
Each domU requires a separate configuration file that is used to create the virtual machine. Full details about the configuration files can be found at the [http://wiki.xensource.com/xenwiki/XenConfigurationFileOptions| Xen Wiki] or the xl.cfg man page. Both HVM and PV domUs share some components of the configuration file. These include<br />
<nowiki><br />
name = "domU"<br />
memory = 256<br />
disk = [ "file:/path/to/ISO,sdb,r", "phy:/path/to/partition,sda1,w" ]<br />
vif = [ 'mac=00:16:3e:XX:XX:XX,bridge=xenbr0' ]<br />
</nowiki><br />
The {{ic|name&#61;}} is the name by which the xl tools manage the domU and needs to be unique across all domUs. The {{ic|disk&#61;}} includes information about both the the installation media ({{ic|file:}}) and the partition created for the domU {{ic|phy}}. If an image file is being used instead of a physical partition, the {{ic|phy:}} needs to be changed to {{ic|file:}}. The {{ic|vif&#61;}} defines a network controller. The 00:16:3e MAC block is reserved for Xen domains, so the last three digits of the {{ic|mac&#61;}} must be randomly filled in (hex values 0-9 and a-f only).<br />
<br />
=== Managing a domU ===<br />
If a domU should be started on boot, create a symlink to the configuration file in /etc/xen/auto and ensure the xendomains service is set up correctly. Some useful commands for managing domUs are:<br />
# xl top<br />
# xl list<br />
# xl console domUname<br />
# xl shutdown domUname<br />
# xl destroy domUname<br />
<br />
== Configuring a hardware virtualized (HVM) Arch domU ==<br />
In order to use HVM domUs install the {{Pkg|mesa-libgl}} and {{Pkg|bluez-libs}} packages.<br />
<br />
A minimal configuration file for a HVM Arch domU is:<br />
<nowiki><br />
name = 'HVM_domU'<br />
builder = 'hvm'<br />
memory = 256<br />
vcpus = 2<br />
disk = [ 'phy:/dev/mapper/vg0-hvm_arch,xvda,w', 'file:/path/to/ISO,hdc:cdrom,r' ]<br />
vif = [ 'mac=00:16:3e:00:00:00,bridge=xenbr0' ]<br />
vnc = 1<br />
vnclisten = '0.0.0.0'<br />
vncdisplay = 1<br />
</nowiki><br />
Since HVM machines do not have a console, they can only be connected to via a [[Vncserver|vncviewer]]. The configuration file allows for unauthenticated remote access of the domU vncserver and is not suitable for unsecured networks. The vncserver will be available on port 590X, where X is the value of {{ic|vncdisplay}}, of the dom0. The domU can be created with:<br />
<br />
# xl create /path/to/config/file<br />
<br />
and its status can be checked with<br />
<br />
# xl list<br />
<br />
Once the domU is created, connect to it via the vncserver and install Arch Linux as described in the [[Installation Guide]].<br />
<br />
== Configuring a paravirtualized (PV) Arch domU ==<br />
A minimal configuration file for a PV Arch domU is:<br />
<nowiki><br />
name = "PV_domU"<br />
kernel = "/mnt/arch/boot/x86_64/vmlinuz"<br />
ramdisk = "/mnt/arch/boot/x86_64/archiso.img"<br />
extra = "archisobasedir=arch archisolabel=ARCH_201301"<br />
memory = 256<br />
disk = [ "phy:/path/to/partition,sda1,w", "file:/path/to/ISO,sdb,r" ]<br />
vif = [ 'mac=00:16:3e:XX:XX:XX,bridge=xenbr0' ]<br />
</nowiki><br />
This file needs to tweaked for your specific use. Most importantly, the {{ic|1=archisolabel=ARCH_201301}} line must be edited to use the release year/month of the ISO being used. If you want to install 32-bit Arch, change the kernel and ramdisk paths from /x86_64/ to /i686/.<br />
<br />
Before creating the domU, the installation ISO must be loop-mounted. To do this, ensure the directory /mnt exists and is empty, then run the following command (being sure to fill in the correct ISO path):<br />
# mount -o loop /path/to/iso /mnt<br />
<br />
Once the ISO is mounted, the domU can be created with:<br />
<br />
# xl create -c /path/to/config/file<br />
<br />
The -c option will enter the domU's console when successfully created and install Arch Linux as described in the [[Installation Guide]]. There will be a few deviations, however. The block devices listed in the disks line of the cfg file will show up as {{ic|/dev/xvd*}}. Use these devices when partitioning the domU. After installation and before the domU is rebooted, the xen-blkfront xen-fbfront xen-netfront xen-kbdfront modules must be added to [[Mkinitcpio]]. Without these modules, the domU will not boot correctly. For booting, it is not necessary to install Grub. Xen has a Python-based grub emulator, so all that is needed to boot is a grub.cfg file: (It may be necessary to create the /boot/grub directory)<br />
{{hc|/boot/grub/grub.cfg|<nowiki>menuentry 'Arch GNU/Linux, with Linux core repo kernel' --class arch --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-core repo kernel-true-__UUID__' {<br />
insmod gzio<br />
insmod part_msdos<br />
insmod ext2<br />
set root='hd0,msdos1'<br />
if [ x$feature_platform_search_hint = xy ]; then<br />
search --no-floppy --fs-uuid --set=root --hint-bios=hd0,msdos1 --hint-efi=hd0,msdos1 --hint-baremetal=ahci0,msdos1 __UUID__<br />
else<br />
search --no-floppy --fs-uuid --set=root __UUID__<br />
fi<br />
echo 'Loading Linux core repo kernel ...'<br />
linux /boot/vmlinuz-linux root=UUID=__UUID__ ro<br />
echo 'Loading initial ramdisk ...'<br />
initrd /boot/initramfs-linux.img<br />
}</nowiki>}}<br />
This file must be edited to match the UUID of the root partition. From within the domU, run the following command:<br />
# blkid<br />
Replace all instances of __UUID__ with the real UUID of the root partition (the one that mounts as "/").<br />
<br />
Shutdown the domU with the {{ic|poweroff}} command. The console will be returned to the hypervisor when the domain is fully shut down, and the domain will no longer appear in the xl domains list. Now the ISO file may be unmounted:<br />
# umount /mnt<br />
The domU cfg file should now be edited. Delete the "kernel = ", "ramdisk = ", and "extra = " lines and replace them with the following line:<br />
bootloader = "pygrub"<br />
Also remove the ISO disk from the "disk = " line.<br />
<br />
The Arch domU is now set up. It may be started with the same line as before:<br />
# xl create -c /etc/xen/archdomu.cfg<br />
<br />
== Common Errors ==<br />
* 'xl list' complains about libxl<br />
- Either you have not booted into the Xen system, or xen modules listed in ''xencommons'' script are not installed<br />
<br />
* ''xl create'' fails<br />
- check the guest's kernel is located correctly, check the pv-xxx.cfg file for spelling mistakes (like using ''initrd'' instead of ''ramdisk'')<br />
<br />
* Arch linux guest hangs with a ctrl-d message<br />
- press ctrl-d until you get back to a prompt, rebuild its initramfs described <br />
<br />
* Error message "''failed to execute '/usr/lib/udev/socket:/org/xen/xend/udev_event' 'socket:/org/xen/xend/udev_event': No such file or directory''"<br />
- caused by ''/etc/udev/rules.d/xend.rules''; xend is (a) deprecated and (b) not used, so it is safe to remove xend.rules<br />
<br />
==Resources==<br />
* [http://www.xen.org/ The homepage at xen.org]<br />
* [http://wiki.xen.org/wiki/Main_Page The wiki at xen.org ]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Lenovo/IBM_Notebooks&diff=277005Lenovo/IBM Notebooks2013-09-29T05:04:42Z<p>Netskink: /* See also */ Added link to Thinkpad Multimedia Buttons. This will also get folks the page which helped me since its cited.</p>
<hr />
<div>[[Category:IBM]]<br />
[[Category:Lenovo]]<br />
<br />
Lenovo and previously IBM are producing wonderful machines which are known to support Linux very well. There are wiki pages with hints and guides for many models in the Arch wiki. The following table tries to give an overview.<br />
<br />
Indented list entries are duplicates.<br />
<br />
==Models==<br />
<br />
Taken from [http://www.thinkwiki.org/wiki/ThinkPad_History] and [http://www.thinkwiki.org/wiki/Category:Models].<br />
<br />
===Withdrawn Series===<br />
<br />
*[[IBM ThinkPad 600E]] (1998)<br />
<br />
===ThinkPad R===<br />
<br />
*[[IBM ThinkPad R40]] (2003)<br />
*[[IBM ThinkPad R60E]] (2006)<br />
*Lenovo ThinkPad R500 (2008)<br />
<br />
===ThinkPad T===<br />
*[[IBM ThinkPad T21]] (2000)<br />
*[[IBM ThinkPad T23]] (2001)<br />
*[[IBM ThinkPad T30]] (2002)<br />
*[[IBM ThinkPad T41]] (2003)<br />
*[[IBM ThinkPad T42]] (2004)<br />
*[[IBM ThinkPad T43p]] (2005)<br />
*[[Lenovo Thinkpad T61]] (2007)<br />
**[[IBM ThinkPad T61]] (2007)<br />
*[[Lenovo ThinkPad T400]] (2008)<br />
*[[Lenovo ThinkPad T400s]] (2009)<br />
*[[Lenovo ThinkPad T420]] (2011)<br />
*[[Lenovo ThinkPad T420s]] (2011)<br />
<br />
===ThinkPad W===<br />
<br />
===ThinkPad X===<br />
<br />
*[[IBM ThinkPad X31]] (2003)<br />
*[[IBM ThinkPad X41]] (2005)<br />
*[[IBM ThinkPad X60]] (2006)<br />
*[[IBM ThinkPad X60s]] (2006)<br />
*[[Lenovo Thinkpad X60 Tablet]] (2006)<br />
*[[Lenovo ThinkPad X61T]] (2007)<br />
*[[Lenovo Thinkpad X300]] (2008)<br />
*[[Lenovo ThinkPad X200]] (2008)<br />
*[[Lenovo ThinkPad X201]] (2010)<br />
*[[Lenovo ThinkPad X1]] (2011)<br />
*[[Lenovo ThinkPad X100e]] (2010)<br />
*[[Lenovo ThinkPad X120e]] (2011)<br />
*[[Lenovo ThinkPad X220]] (2011)<br />
*[[Lenovo ThinkPad X230]] (2012)<br />
<br />
===ThinkPad SL===<br />
<br />
*[[Lenovo Thinkpad SL500]] (2008)<br />
*[[Lenovo ThinkPad SL510]]<br />
<br />
===Ideapad===<br />
<br />
*[[Lenovo Ideapad S10]]<br />
*[[Lenovo Ideapad y530]]<br />
*[[Lenovo Ideapad G580]]<br />
*[[Lenovo Ideapad S10-3]]<br />
*[[Lenovo Ideapad s10-3t]]<br />
<br />
===Edge===<br />
<br />
*[[ThinkPad Edge]]<br />
<br />
==See also==<br />
<br />
* [[HCL/Laptops/IBM]]<br />
* [[Thinkpad Fan Control]]<br />
* [[Thinkpad Multimedia Buttons]]<br />
* [http://www.thinkwiki.org Thinkwiki]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Thinkpad_multimedia_buttons&diff=277004Thinkpad multimedia buttons2013-09-29T05:03:45Z<p>Netskink: Netskink moved page Thinkpad multimedia buttons to Thinkpad Multimedia Buttons: Convention</p>
<hr />
<div>#REDIRECT [[Thinkpad Multimedia Buttons]]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=ThinkPad_multimedia_buttons&diff=277003ThinkPad multimedia buttons2013-09-29T05:03:45Z<p>Netskink: Netskink moved page Thinkpad multimedia buttons to Thinkpad Multimedia Buttons: Convention</p>
<hr />
<div>== Configuring the mute, volume up and volume down buttons in ArchLinux: ==<br />
=== Step 1 Device Drivers ===<br />
:Install the necessary device drivers and configure the OS_Linux in the kernel command line.<br />
=== Step 2 Applications ===<br />
:Install ALSA and make sure that alsamixer is able to mute/unmute and adjust volume.<br />
=== Configuring Buttons to Software ===<br />
:Step one and two are well documented. Search the wiki for other instructions on how to do this.<br />
<br />
:You are ready to proceed to this step if you can play audio with your favorite application and adjust the sound volume using the alsamixer application in [[alsa]] package.<br />
<br />
:This [http://wiki.archlinux.org/index.php/Lenovo_ThinkPad_T400#Multimedia_Keys page] will show you how to use [[Extra_Keyboard_Keys#Using_xev|xev]] to determine the keycodes for the mute, volume up and volume down buttons.<br />
<br />
:That page also shows how to use {{Pkg|xbindkeys}} to setup a .xbindkeysrc.scm file. However, the device settings might vary for your setup. Here is how to use amixer to find your device settings. Use the amixer command with the parameter scontrols. This gives the name for the master volume control.<br />
<br />
$ amixer scontrols<br />
Simple mixer control 'Master',0<br />
Simple mixer control 'Capture',0<br />
$<br />
<br />
:Open alsamixer and examine the output as you issue commands to set the volume. As you adjust the volume setting using amixer, you should see the volume level in alsamixer change. Here I am adjusting the volume louder with each invocation of amixer<br />
<br />
$ amixer -c 0 sset 'Master',0 40 <br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 40 [54%] [-34.00dB] [on]<br />
$ amixer -c 0 sset 'Master',0 60<br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 60 [81%] [-14.00dB] [on]<br />
$ amixer -c 0 sset 'Master',0 80<br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 74 [100%] [0.00dB] [on]<br />
$<br />
<br />
:This command sets the volume to a specified level, however we want the volume buttons to adjust the current volume. Thus, we use the +/-dB form of the command. This is shown in the final .xbindkeysrc.scm. Likewise the mute button is specified.<br />
<br />
$ cat .xbindkeysrc.scm <br />
(xbindkey '("XF86AudioRaiseVolume") "amixer -c 0 sset 'Master',0 2dB+")<br />
(xbindkey '("XF86AudioLowerVolume") "amixer -c 0 sset 'Master',0 2dB-")<br />
(xbindkey '("XF86AudioMute") "<br />
<br />
:Restart xwindows and now your media buttons should work.</div>Netskinkhttps://wiki.archlinux.org/index.php?title=ThinkPad_multimedia_buttons&diff=277002ThinkPad multimedia buttons2013-09-29T04:59:04Z<p>Netskink: /* Configuring Buttons to Software */</p>
<hr />
<div>== Configuring the mute, volume up and volume down buttons in ArchLinux: ==<br />
=== Step 1 Device Drivers ===<br />
:Install the necessary device drivers and configure the OS_Linux in the kernel command line.<br />
=== Step 2 Applications ===<br />
:Install ALSA and make sure that alsamixer is able to mute/unmute and adjust volume.<br />
=== Configuring Buttons to Software ===<br />
:Step one and two are well documented. Search the wiki for other instructions on how to do this.<br />
<br />
:You are ready to proceed to this step if you can play audio with your favorite application and adjust the sound volume using the alsamixer application in [[alsa]] package.<br />
<br />
:This [http://wiki.archlinux.org/index.php/Lenovo_ThinkPad_T400#Multimedia_Keys page] will show you how to use [[Extra_Keyboard_Keys#Using_xev|xev]] to determine the keycodes for the mute, volume up and volume down buttons.<br />
<br />
:That page also shows how to use {{Pkg|xbindkeys}} to setup a .xbindkeysrc.scm file. However, the device settings might vary for your setup. Here is how to use amixer to find your device settings. Use the amixer command with the parameter scontrols. This gives the name for the master volume control.<br />
<br />
$ amixer scontrols<br />
Simple mixer control 'Master',0<br />
Simple mixer control 'Capture',0<br />
$<br />
<br />
:Open alsamixer and examine the output as you issue commands to set the volume. As you adjust the volume setting using amixer, you should see the volume level in alsamixer change. Here I am adjusting the volume louder with each invocation of amixer<br />
<br />
$ amixer -c 0 sset 'Master',0 40 <br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 40 [54%] [-34.00dB] [on]<br />
$ amixer -c 0 sset 'Master',0 60<br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 60 [81%] [-14.00dB] [on]<br />
$ amixer -c 0 sset 'Master',0 80<br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 74 [100%] [0.00dB] [on]<br />
$<br />
<br />
:This command sets the volume to a specified level, however we want the volume buttons to adjust the current volume. Thus, we use the +/-dB form of the command. This is shown in the final .xbindkeysrc.scm. Likewise the mute button is specified.<br />
<br />
$ cat .xbindkeysrc.scm <br />
(xbindkey '("XF86AudioRaiseVolume") "amixer -c 0 sset 'Master',0 2dB+")<br />
(xbindkey '("XF86AudioLowerVolume") "amixer -c 0 sset 'Master',0 2dB-")<br />
(xbindkey '("XF86AudioMute") "<br />
<br />
:Restart xwindows and now your media buttons should work.</div>Netskinkhttps://wiki.archlinux.org/index.php?title=ThinkPad_multimedia_buttons&diff=277001ThinkPad multimedia buttons2013-09-29T04:57:53Z<p>Netskink: I was looking at the referenced page for a specific thinkpad model and it did not work for my specific model. I thought this would help for all thinkpads.</p>
<hr />
<div>== Configuring the mute, volume up and volume down buttons in ArchLinux: ==<br />
=== Step 1 Device Drivers ===<br />
:Install the necessary device drivers and configure the OS_Linux in the kernel command line.<br />
=== Step 2 Applications ===<br />
:Install ALSA and make sure that alsamixer is able to mute/unmute and adjust volume.<br />
=== Configuring Buttons to Software ===<br />
:Step one and two are well documented. Search the wiki for other instructions on how to do this.<br />
<br />
:You are ready to proceed to this step if you can play audio with your favorite application and adjust the sound volume using the alsamixer application in [[alsa]] package.<br />
<br />
:This [http://wiki.archlinux.org/index.php/Lenovo_ThinkPad_T400#Multimedia_Keys page] will show you how to use [[Extra_Keyboard_Keys#Using_xev|xev]] to determine the keycodes for the mute, volume up and volume down buttons.<br />
<br />
:That page also shows how to use [[xbindeys]] to setup a .xbindkeysrc.scm file. However, the device settings might vary for your setup. Here is how to use amixer to find your device settings. Use the amixer command with the parameter scontrols. This gives the name for the master volume control.<br />
<br />
$ amixer scontrols<br />
Simple mixer control 'Master',0<br />
Simple mixer control 'Capture',0<br />
$<br />
<br />
:Open alsamixer and examine the output as you issue commands to set the volume. As you adjust the volume setting using amixer, you should see the volume level in alsamixer change. Here I am adjusting the volume louder with each invocation of amixer<br />
<br />
$ amixer -c 0 sset 'Master',0 40 <br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 40 [54%] [-34.00dB] [on]<br />
$ amixer -c 0 sset 'Master',0 60<br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 60 [81%] [-14.00dB] [on]<br />
$ amixer -c 0 sset 'Master',0 80<br />
Simple mixer control 'Master',0<br />
Capabilities: pvolume pvolume-joined pswitch pswitch-joined<br />
Playback channels: Mono<br />
Limits: Playback 0 - 74<br />
Mono: Playback 74 [100%] [0.00dB] [on]<br />
$<br />
<br />
:This command sets the volume to a specified level, however we want the volume buttons to adjust the current volume. Thus, we use the +/-dB form of the command. This is shown in the final .xbindkeysrc.scm. Likewise the mute button is specified.<br />
<br />
$ cat .xbindkeysrc.scm <br />
(xbindkey '("XF86AudioRaiseVolume") "amixer -c 0 sset 'Master',0 2dB+")<br />
(xbindkey '("XF86AudioLowerVolume") "amixer -c 0 sset 'Master',0 2dB-")<br />
(xbindkey '("XF86AudioMute") "<br />
<br />
:Restart xwindows and now your media buttons should work.</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth&diff=276252Bluetooth2013-09-21T19:19:21Z<p>Netskink: /* hciconfig */ results of entering the commands.</p>
<hr />
<div>[[Category:Bluetooth]]<br />
[[cs:Bluetooth]]<br />
[[de:Bluetooth]]<br />
[[es:Bluetooth]]<br />
[[fr:Bluetooth]]<br />
[[it:Bluetooth]]<br />
[[ru:Bluetooth]]<br />
[[zh-CN:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers the installation and use of Bluetooth on Arch Linux.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth mouse configuration}}<br />
{{Article summary end}}<br />
<br />
{{Out of date|Several generations of various deprecated tools are mentioned. bluez4 and bluez are confused. This article needs cleanup from someone who knows what commands belong in which packages.}}<br />
<br />
[http://www.bluetooth.org/ Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. In Linux, the canonical implementation of the Bluetooth protocol stack is [http://www.bluez.org/ BlueZ].<br />
<br />
== Installation ==<br />
<br />
To use Bluetooth, [[pacman|install]] {{Pkg|bluez}}, available in the [[official repositories]]. The {{ic|dbus}} daemon(start automatically by systemd) is used to read settings and for PIN pairing, while the {{ic|bluetooth}} daemon is required for the Bluetooth protocol.<br />
<br />
<br />
<br />
# systemctl status bluetooth.service<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: inactive (dead)<br />
Docs: man:bluetoothd(8)<br />
<br />
Enable the ''bluetooth'' service to start it at system boot up.<br />
<br />
# systemctl enable bluetooth.service<br />
ln -s '/usr/lib/systemd/system/bluetooth.service' '/etc/systemd/system/dbus-org.bluez.service'<br />
ln -s '/usr/lib/systemd/system/bluetooth.service' '/etc/systemd/system/bluetooth.target.wants/bluetooth.service'<br />
<br />
Start the bluetooth [[systemd]] service.<br />
<br />
# systemctl status bluetooth.service<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; enabled)<br />
Active: inactive (dead)<br />
Docs: man:bluetoothd(8)<br />
<br />
# systemctl start bluetooth.service<br />
<br />
== Graphical front-ends ==<br />
<br />
The following packages allow for a graphical interface to customize Bluetooth.<br />
<br />
=== Blueman ===<br />
<br />
See [[Blueman]] article.<br />
<br />
=== GNOME Bluetooth ===<br />
<br />
[http://live.gnome.org/GnomeBluetooth GNOME Bluetooth] is a fork of the old ''bluez-gnome'' and is focused on integration with the [[GNOME]] desktop environment. GNOME Bluetooth is required by {{Pkg|gnome-shell}}, so you should already have it installed if you are running GNOME 3. Otherwise, it can be installed with the package {{Pkg|gnome-bluetooth}}. Note that gnome-shell, gnome-bluetooth <= 3.8 depend upon {{Pkg|bluez4}}. From gnome-shell 3.10 onwards, {{Pkg|bluez}} will be supported. More information regarding the GNOME migration to ''bluez'' can be found [http://worldofgnome.org/gnome-3-10-port-to-bluez-5/ here] (June 2013 blog post).<br />
<br />
Run {{ic|bluetooth-applet}} for a nice Bluetooth applet. You should now be able to setup devices and send files by right-clicking the Bluetooth icon. To make the applet run on login, add it to ''System > Preferences > Startup Applications''.<br />
<br />
To add a Bluetooth entry to the ''SendTo'' menu in Thunar's file properties menu, see instructions [http://thunar.xfce.org/pwiki/documentation/sendto_menu here].<br />
<br />
=== BlueDevil ===<br />
<br />
{{Note|As of 2013-09-01, ''bluedevil'' depends on the older {{Pkg|bluez4}}, which conflicts with the current {{Pkg|bluez}} (v5). Additionally, {{AUR|bluedevil-git}} is not updated to fix this dependency.}}<br />
<br />
The Bluetooth tool for [[KDE]] is [https://projects.kde.org/projects/extragear/base/bluedevil BlueDevil]. It can be installed with the package {{Pkg|bluedevil}}, available in the [[Official Repositories]].<br />
<br />
Make sure {{ic|bluetooth}} daemon is running, as described above. You should get a Bluetooth icon both in Dolphin and in the system tray, from which you can configure BlueDevil and detect Bluetooth devices by clicking the icon. You can also configure BlueDevil from the KDE System Settings<br />
<br />
=== Fluxbox, Openbox, other WM ===<br />
<br />
Of course you can still use the preceding applications even if GNOME, Xfce or KDE are not your desktop manager. This list should help you figuring out which application does what:<br />
* bluetooth-applet -- tray icon with access to settings, pairing wizard, management of known devices<br />
* /usr/lib/gnome-user-share/gnome-user-share -- needs to be running if you're about to receive files via obexBT from a paired/bonded device<br />
<br />
if you're receiving an error during transmission and/or there's no file received add this into<br />
<br />
{{ic|/etc/dbus-1/system.d/bluetooth.conf}}<br />
<policy user="your_user_id"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent"/><br />
</policy><br />
<br />
* bluetooth-wizard -- for new devices to be paired<br />
* bluetooth-properties -- accessible also via bluetooth-applet icon<br />
* gnome-file-share-properties -- permissions on receiving files via bluetooth<br />
* bluez-sendto -- gui for sending files to a remote device<br />
<br />
== Bluez Utils ==<br />
<br />
The package {{Pkg|bluez-utils}} contains various commands,<br />
which are useful to configure and troubleshoot Bluetooth<br />
from the command line.<br />
<br />
=== hciconfig ===<br />
<br />
Print name and basic information about all the Bluetooth devices installed in the system:<br />
# hciconfig<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 90:4C:E5:DB:E9:77 ACL MTU: 1021:8 SCO MTU: 64:1<br />
DOWN <br />
RX bytes:484 acl:0 sco:0 events:20 errors:0<br />
TX bytes:323 acl:0 sco:0 commands:20 errors:0<br />
<br />
<br />
<br />
<br />
hciconfig is part of the {{Pkg|bluez-utils}} package.<br />
<br />
To activate a device, use:<br />
# hciconfig ''device-name'' up<br />
example using soundbot wireless headset. The wireless headset button is long-pressed to enable pairing mode<br />
after the hiconfig up command is issued:<br />
# hciconfig hci0 up<br />
# hcitool scan <br />
Scanning ...<br />
00:1A:7D:12:36:B9 SoundBot SB220<br />
<br />
=== hcitool ===<br />
<br />
To scan for remote devices:<br />
$ hcitool scan<br />
<br />
== Pairing ==<br />
Many bluetooth devices require [http://en.wikipedia.org/wiki/Bluetooth#Pairing pairing].<br />
The exact procedure depends on the devices involved and their input functionality.<br />
<br />
=== With bluez5 ===<br />
<br />
Start the {{ic|bluetoothctl}} interactive command. There you can input {{ic|help}} to get a list of available commands. <br />
* Enter {{ic|devices}} to get the MAC Address of the device with which you want to pair.<br />
* Enter {{ic|pair ''MAC Address''}} to do the pairing.<br />
* Finally, use {{ic|connect ''MAC_address''}} to establish a connection.<br />
<br />
=== With bluez4 ===<br />
<br />
The procedure on a mobile may be as follows:<br />
* The computer sends a connect request to the mobile. <br />
* A pin, determined by the computer, is prompted for at the mobile<br />
* The same key must be re-entered at the computer.<br />
<br />
To pair with a device without using the gnome-bluez package, the ''bluez-simple-agent'' utility that comes with the bluez package can be used. This utility depends on three packages from the official repositories: {{Pkg|python2-dbus}} {{Pkg|python2-gobject}} {{Pkg|dbus-glib}}.<br />
<br />
First, scan for external devices:<br />
$ hcitool scan<br />
<br />
Run the script as root:<br />
<br />
# bluez-simple-agent<br />
<br />
The message "Agent registered" should be returned, press control-c to quit. <br />
<br />
Below is a basic example of pairing with a specific device. The script will ask for the passcode, enter the code and confirm with enter.<br />
<br />
# bluez-simple-agent hci0 00:11:22:33:AA:BB<br />
<br />
{{Note|bluez-simple-agent is only needed once for pairing a device, not every time you want to connect.}}<br />
<br />
See the Examples section below for pairing examples with various devices.<br />
<br />
== Using Obex for sending and receiving files ==<br />
<br />
Another option, rather than using KDE or Gnome Bluetooth packages, is Obexfs which allows you to mount your phone and treat it as part of your filesystem. Note that to use Obexfs, you need a device that provides an Obex FTP service.<br />
<br />
Install {{Pkg|obexfs}} and then your phone can then be mounted by running <br />
$ obexfs -b ''devices_MAC_address'' /mountpoint<br />
<br />
For more mounting options see http://dev.zuckschwerdt.org/openobex/wiki/ObexFs<br />
<br />
For devices don't support Obex FTP service, check if Obex Object Push is supported.<br />
<br />
# sdptool browse ''XX:XX:XX:XX:XX:XX''<br />
<br />
Read the output, look for Obex Object Push, remember the channel for this service. If supported, you can use ussp-push to send files to this device:<br />
<br />
# ussp-push ''XX:XX:XX:XX:XX:XX''@''CHANNEL'' ''file'' ''wanted_file_name_on_phone''<br />
<br />
== Examples ==<br />
<br />
=== Siemens S55 ===<br />
<br />
This is what I did to connect to my S55. (I have not figured out how to initiate the connection from the phone)<br />
* The steps under installation<br />
<br />
{{hc|$ hcitool scan|<br />
Scanning ...<br />
''XX:XX:XX:XX:XX:XX'' NAME<br />
}}<br />
$ B=''XX:XX:XX:XX:XX:XX''<br />
Start the simple-agent in a second terminal:<br />
{{hc|$ su -c bluez-simple-agent|<br />
Password: <br />
Agent registered<br />
}}<br />
Back to the first console:<br />
{{hc|$ obexftp -b $B -l "Address book"|<nowiki><br />
# Phone ask for pin, I enter it and answer yes when asked if I want to save the device<br />
...<br />
<file name="5F07.adr" size="78712" modified="20030101T001858" user-perm="WD" group-perm="" /><br />
...<br />
</nowiki>}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -g "Address book/5F07.adr"|<br />
Browsing 00:01:E3:6B:FF:D7 ...<br />
Channel: 5<br />
Connecting...done<br />
Receiving "Address book/5F07.adr"... Sending "Address book"... done<br />
Disconnecting...done<br />
}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -p a|<br />
...<br />
Sending "a"... done<br />
Disconnecting...done<br />
}}<br />
<br />
=== Logitech mouse MX Laser / M555b ===<br />
<br />
To quickly test the connection:<br />
<br />
$ hidd --connect ''XX:XX:XX:XX:XX:XX''<br />
<br />
For automated reconnection, use your desktop wizard to configure the bluetooth mouse.<br />
If your desktop environment doesn't includes support for this task, see the [[Bluetooth mouse manual configuration]] guide.<br />
<br />
=== Motorola V900 ===<br />
<br />
After installing blueman and running blueman-applet, click "find me" under connections > bluetooth in Motorla device. In blueman-applet, scan devices, find the motorola, click "add" in blueman-applet. Click "bond" in blueman-applet, enter some pin, enter the same pin in motorola when it asks. In terminal:<br />
<br />
{{bc|<br />
$ mkdir ~/bluetooth-temp<br />
$ obexfs -n ''XX:XX:XX:XX:XX:XX'' ~/bluetooth-temp<br />
$ cd ~/bluetooth-temp<br />
}}<br />
<br />
and browse... Only audio, video, and pictures are available when you do this.<br />
<br />
=== Motorola RAZ ===<br />
<br />
Install {{Pkg|obextool}} {{Pkg|obexfs}} {{Pkg|obexftp}} {{Pkg|openobex}} {{Pkg|bluez}}.<br />
<br />
{{hc|# lsusb|<br />
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 002 Device 002: ID 03f0:171d Hewlett-Packard Wireless (Bluetooth + WLAN) Interface [Integrated Module]<br />
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|# hciconfig|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
{{hc|# hcitool dev|<br />
Devices:<br />
hci0 00:16:41:97:BA:5E<br />
}}<br />
<br />
Make sure that bluetooth on your phone is enabled and your phone is visible!<br />
<br />
{{hc|# hcitool scan|<br />
Scanning ...<br />
00:1A:1B:82:9B:6D [quirxi]<br />
}}<br />
<br />
{{hc|# hcitool inq|<br />
Inquiring ...<br />
00:1A:1B:82:9B:6D clock offset: 0x1ee4 class: 0x522204<br />
}}<br />
<br />
{{hc|# l2ping 00:1A:1B:82:9B:6D|<br />
Ping: 00:1A:1B:82:9B:6D from 00:16:41:97:BA:5E (data size 44) ...<br />
44 bytes from 00:1A:1B:82:9B:6D id 0 time 23.94ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 1 time 18.85ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 2 time 30.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 3 time 18.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 4 time 17.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 5 time 17.88ms<br />
6 sent, 6 received, 0% loss<br />
}}<br />
<br />
{{hc|# hcitool name 00:1A:1B:82:9B:6D|<br />
[quirxi]<br />
}}<br />
<br />
{{hc|# hciconfig -a hci0|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:9740 acl:122 sco:0 events:170 errors:0<br />
TX bytes:2920 acl:125 sco:0 commands:53 errors:0<br />
Features: 0xff 0xff 0x8d 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3<br />
Link policy:<br />
Link mode: SLAVE ACCEPT<br />
Name: 'BCM2045'<br />
Class: 0x000000<br />
Service Classes: Unspecified<br />
Device Class: Miscellaneous,<br />
HCI Version: 2.0 (0x3) Revision: 0x204a<br />
LMP Version: 2.0 (0x3) Subversion: 0x4176<br />
Manufacturer: Broadcoml / Corporation (15)<br />
}}<br />
<br />
{{hc|# hcitool info 00:1A:1B:82:9B:6D|<br />
Requesting information ...<br />
BD Address: 00:1A:1B:82:9B:6D<br />
Device Name: [quirxi]<br />
LMP Version: 1.2 (0x2) LMP Subversion: 0x309<br />
Manufacturer: Broadcom Corporation (15)<br />
Features: 0xff 0xfe 0x0d 0x00 0x08 0x08 0x00 0x00<br />
<3-slot packets> <5-slot packets> <encryption> <slot offset><br />
<timing accuracy> <role switch> <hold mode> <sniff mode><br />
<RSSI> <channel quality> <SCO link> <HV2 packets><br />
<HV3 packets> <A-law log> <CVSD> <power control><br />
<transparent SCO> <AFH cap. slave> <AFH cap. master><br />
}}<br />
<br />
Edit your {{ic|/etc/bluetooth/main.conf}} and enter the proper class for your phone ( Class = 0x100100 ):<br />
{{bc|<nowiki><br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100<br />
Class = 0x100100<br />
</nowiki>}}<br />
<br />
{{hc|# systemctl start bluetooth|<br />
:: Stopping bluetooth subsystem: pand dund rfcomm hidd bluetoothd<br />
[DONE]<br />
:: Starting bluetooth subsystem: bluetoothd<br />
}}<br />
<br />
Pairing with bluez-simple-agent only has to be done once. On your Motorola phone give 0000 in as your PIN when phone asks for it!<br />
{{hc|/usr/bin/bluez-simple-agent hci0 00:1A:1B:82:9B:6D|<br />
RequestPinCode (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
Enter PIN Code: 0000<br />
Release<br />
New device (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
}}<br />
<br />
Now you can browse the filesystem of your phone with obexftp:<br />
{{hc|obexftp -v -b 00:1A:1B:82:9B:6D -B 9 -l|<nowiki><br />
Connecting..\done<br />
Tried to connect for 448ms<br />
Receiving "(null)"...-<?xml version="1.0" ?><br />
<!DOCTYPE folder-listing SYSTEM "obex-folder-listing.dtd"><br />
<folder-listing><br />
<parent-folder /><br />
<folder name="audio" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="video" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="picture" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
</folder-listing><br />
done<br />
Disconnecting..\done<br />
</nowiki>}}<br />
<br />
Or you can mount your phone into a directory on your computer and treat it like a normal file system:<br />
{{bc|<br />
# groupadd bluetooth<br />
# mkdir /mnt/bluetooth<br />
# chown root:bluetooth /mnt/bluetooth<br />
# chmod 775 /mnt/bluetooth<br />
# usermod -a -G bluetooth arno<br />
# obexfs -b 00:1A:1B:82:9B:6D /mnt/bluetooth/<br />
}}<br />
<br />
=== Pairing with an iPhone using bluez-simple-agent ===<br />
<br />
Assuming a bluetooth device called hci0 and an iPhone that showed up in a hcitool scan as '00:00:DE:AD:BE:EF':<br />
<br />
# bluez-simple-agent hci0 00:00:DE:AD:BE:EF<br />
Passcode:<br />
<br />
=== Headset and ALSA devices ===<br />
<br />
==== by referencing the bluetooth device in asound.conf ====<br />
<br />
1. Scan for your device:<br />
$ hcitool (-i ''optional hci#''***) scan<br />
2. 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 />
3. Add this to your {{ic|/etc/asound.conf}} file:<br />
<br />
{{bc|<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 />
<br />
4. Check to see if it has been added to ALSA devices<br />
$ aplay -L<br />
<br />
5. 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 />
To find hci# for a usb dongle, type in:<br />
$ hcitool dev<br />
<br />
==== by using bluez-tools from the AUR ====<br />
<br />
You can use {{AUR|bluez-tools}} from the [[AUR]] with PulseAudio to stream audio to a bluetooth headset.<br />
Find the MAC of the headset:<br />
$ hcitool scan<br />
Connect to the headset:<br />
$ bt-audio -c XX:XX:XX:XX:XX:XX<br />
Open pulseaudio volume control:<br />
$ pavucontrol<br />
The headset should show up in the Configuration tab.<br />
<br />
=== Microsoft Bluetooth Mobile Keyboard 6000 ===<br />
<br />
1. Scan for your device<br />
$ hcitool (-i ''optional_hci#''***) scan<br />
Scanning ...<br />
00:11:22:33:44:55 Microsoft Bluetooth Mobile Keyboard 6000<br />
<br />
2. On second console run as root (do not terminate):<br />
# bluez-simple-agent<br />
Agent registered<br />
<br />
3. Back on first console run:<br />
$ bluez-simple-agent hci0 00:11:22:33:44:55<br />
Enter PIN Code: 1234<br />
(now enter that PIN on the keyboard and press enter)<br />
Release<br />
New device (/org/bluez/5373/hci0/dev_00_11_22_33_44_55)<br />
<br />
4.<br />
$ bluez-test-device trusted 00:11:22:33:44:55<br />
<br />
5.<br />
$ bluez-test-input connect 00:11:22:33:44:55<br />
<br />
No your keyboard should work. You can terminate bluez-simple-agent on second console with {{ic|Ctrl+C}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== passkey-agent ===<br />
<br />
$ passkey-agent --default 1234<br />
Can't register passkey agent<br />
The name org.bluez was not provided by any .service files<br />
and<br />
$ hciconfig dev<br />
# (no listing)<br />
Try running {{ic|hciconfig hc0 up}}<br />
<br />
=== gnome-bluetooth ===<br />
<br />
If you see this when trying to enable receiving files in bluetooth-properties:<br />
Bluetooth OBEX start failed: Invalid path<br />
Bluetooth FTP start failed: Invalid path<br />
Then install {{Pkg|xdg-user-dirs}} and issue:<br />
$ xdg-user-dirs-update<br />
You can edit the paths using:<br />
$ vi ~/.config/user-dirs.dirs<br />
<br />
=== Bluetooth USB Dongle ===<br />
<br />
If you are using a USB dongle, you should check that your Bluetooth dongle is recognized. You can do that by inspecting {{ic|/var/log/messages.log}} when plugging in the USB dongle (or running {{ic|journalctl -f}} with systemd). It should look something like the following (look out for hci):<br />
<br />
{{bc|<br />
Feb 20 15:00:24 hostname kernel: [ 2661.349823] usb 4-1: new full-speed USB device number 3 using uhci_hcd<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: HCI dev 0 registered<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: Listening for HCI events on hci0<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: HCI dev 0 up<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: Adapter /org/bluez/4568/hci0 has been enabled<br />
}}<br />
<br />
For a list of supported hardware please refer to the [[#Resources|Resource]] section on this page.<br />
<br />
If you only get the first two lines, you may see that it found the device but you need to bring it up.<br />
Example:<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:00:00:00:00:00 ACL MTU: 0:0 SCO MTU: 0:0<br />
DOWN <br />
RX bytes:0 acl:0 sco:0 events:0 errors:0<br />
TX bytes:0 acl:0 sco:0 commands:0 errors:<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:02:72:C4:7C:06 ACL MTU: 377:10 SCO MTU: 64:8<br />
UP RUNNING <br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
If this fails with an error like:<br />
Operation not possible due to RF-kill<br />
it could be due either to the {{ic|rfkill}} utility, in which case it should be resolved with<br />
# rfkill unblock all<br />
or, it could simply be the hardware switch of the computer. The hardware bluetooth switch (at least sometimes) controls access to USB bluetooth dongles also. Flip/press this switch and try bringing the device up again.<br />
<br />
To verify that the device was detected you can use {{ic|hcitool}} which is part of the {{ic|bluez-utils}}. You can get a list of available devices and their identifiers and their MAC address by issuing:<br />
<br />
{{hc|$ hcitool dev|<br />
Devices:<br />
hci0 00:1B:DC:0F:DB:40<br />
}}<br />
<br />
More detailed informations about the device can be retrieved by using {{ic|hciconfig}}.<br />
<br />
{{hc|$ hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:1B:DC:0F:DB:40 ACL MTU: 310:10 SCO MTU: 64:8<br />
UP RUNNING PSCAN ISCAN <br />
RX bytes:1226 acl:0 sco:0 events:27 errors:0<br />
TX bytes:351 acl:0 sco:0 commands:26 errors:0<br />
Features: 0xff 0xff 0x8f 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3 <br />
Link policy: RSWITCH HOLD SNIFF PARK <br />
Link mode: SLAVE ACCEPT <br />
Name: 'BlueZ (0)'<br />
Class: 0x000100<br />
Service Classes: Unspecified<br />
Device Class: Computer, Uncategorized<br />
HCI Ver: 2.0 (0x3) HCI Rev: 0xc5c LMP Ver: 2.0 (0x3) LMP Subver: 0xc5c<br />
Manufacturer: Cambridge Silicon Radio (10)<br />
}}<br />
<br />
=== Logitech Bluetooth USB Dongle ===<br />
<br />
There are Logitech dongles (ex. Logitech MX5000) that can work in two modes Embedded and HCI. In embedded mode dongle emulates a USB device so it seems to your PC that your using a normal USB mouse/keyoard.<br />
<br />
If you hold the little red Button on the USB BT mini-receiver it will enable the other mode. Hold the red button on the BT dongle and plug it into the computer, and after 3-5 seconds of holding the button, the Bluetooth icon will appear in the system tray. [http://ubuntuforums.org/showthread.php?t=1332197 Discussion]<br />
<br />
=== hcitool scan: Device not found ===<br />
<br />
* On some Dell laptops (e.g. Studio 15) you have to switch the Bluetooth mode from HID to HCI using<br />
# hid2hci<br />
<br />
{{Note|hid2hci is no longer in the $PATH, it is under /lib/udev/hid2hci, but udev should run it automatically for you.}}<br />
<br />
* If the device won't show up and you have a Windows operating system on your machine, try booting it and enable the bluetooth adapter from windows.<br />
<br />
* Sometimes also this simple command helps:<br />
# hciconfig hci0 up<br />
<br />
=== rfkill unblock: Do not unblock ===<br />
<br />
If your device still soft blocked and you run connman.<br />
<br />
Try this:<br />
$ connmanctl enable bluetooth<br />
<br />
=== My computer is not visible ===<br />
<br />
Can't discover computer from your phone? Enable PSCAN and ISCAN:<br />
# enable PSCAN and ISCAN<br />
$ hciconfig hci0 piscan <br />
# check it worked<br />
{{hc|$ hciconfig|<br />
hci0: Type: USB<br />
BD Address: 00:12:34:56:78:9A ACL MTU: 192:8 SCO MTU: 64:8<br />
'''UP RUNNING PSCAN ISCAN'''<br />
RX bytes:20425 acl:115 sco:0 events:526 errors:0<br />
TX bytes:5543 acl:84 sco:0 commands:340 errors:0<br />
}}<br />
<br />
{{Note|Check DiscoverableTimeout and PairableTimeout in {{ic|/etc/bluetooth/main.conf}}}}<br />
<br />
Try changing device class in {{ic|/etc/bluetooth/main.conf}} as following:<br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100 (from default config)<br />
Class = 0x100100<br />
<br />
This was the only solution to make my computer visible for my phone. <br />
<br />
=== Nautilus cannot browse files ===<br />
<br />
If nautilus doesn't open and show this error:<br />
Nautilus cannot handle obex: locations. Couldn't display "obex://[XX:XX:XX:XX:XX:XX]/".<br />
Install {{Pkg|gvfs-obexftp}} package.<br />
<br />
=== Sennheiser MM400 Headset connection problems ===<br />
<br />
If your {{ic|Sennheiser MM400 Headset}} immediately disconnects after connecting as {{ic|Headset Service}} with Blueman, try to connect it as {{ic|Audio Sink}}. Afterwards you can change the headset's {{ic|Audio Profile}} to {{ic|Telephony Duplex}} with a right click in Blueman.<br />
With this option headset functionality will be available although the headset was only connected as {{ic|Audio Sink}} in first place and no disconnection will happen (tested with bluez 4.96-3, pulseaudio 1.1-1 and blueman 1.23-2).<br />
<br />
=== My device is paired but no sound is played from it ===<br />
<br />
Try to first inspect {{ic|/var/log/messages.log}}. If you see such messages:<br />
{{bc|<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Service not connected<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Bluetooth audio service not available<br />
}}<br />
try first:<br />
# pactl load-module module-bluetooth-device<br />
<br />
If the module fails to work, do this workaround:<br />
Open {{ic|/etc/bluetooth/audio.conf}} and add after '''[General]''' (on a new line)<br />
Enable=Socket<br />
Then restart the bluetooth daemon.<br />
Pair again your device, and you should find it in the pulseaudio settings (advanced settings for the sound)<br />
<br />
[http://wiki.gentoo.org/index.php?title=Bluetooth_Headset&redirect=no More information on Gentoo Wiki]<br />
<br />
If after fixing this you still can't get sound, try using blueman (this is the only one that works for me), make sure that notify-osd is installed or it might show you weird error messages like this one: "Stream setup failed"<br />
<br />
fail (/usr/lib/python2.7/site-packages/blueman/gui/manager/ManagerDeviceMenu.py:134)<br />
fail (DBusException(dbus.String(u'Stream setup failed'),),)<br />
<br />
== See also ==<br />
<br />
*[http://www.gentoo.org/doc/en/bluetooth-guide.xml Gentoo Linux Bluetooth guide]<br />
*[http://en.opensuse.org/HCL:Bluetooth openSUSE Bluetooth Hardware Compatibility List]<br />
*[http://linuxgazette.net/109/oregan3.html Accessing a Bluetooth phone (Linux Gazette)]<br />
*[http://www.adamish.com/blog/#a000361 Bluetooth computer visibility]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth for your mobile phone: Bluetooth pairing, data synchronization, photo download, Internet Dial-Up (tethering)]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth pairing and applications for synchronizing phone numbers, SMS-messages, phone call entries, your calendar and time; tethering]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth&diff=276250Bluetooth2013-09-21T19:15:49Z<p>Netskink: /* hciconfig */ showing the result of seeing the bluetooth device on the computer.</p>
<hr />
<div>[[Category:Bluetooth]]<br />
[[cs:Bluetooth]]<br />
[[de:Bluetooth]]<br />
[[es:Bluetooth]]<br />
[[fr:Bluetooth]]<br />
[[it:Bluetooth]]<br />
[[ru:Bluetooth]]<br />
[[zh-CN:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers the installation and use of Bluetooth on Arch Linux.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth mouse configuration}}<br />
{{Article summary end}}<br />
<br />
{{Out of date|Several generations of various deprecated tools are mentioned. bluez4 and bluez are confused. This article needs cleanup from someone who knows what commands belong in which packages.}}<br />
<br />
[http://www.bluetooth.org/ Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. In Linux, the canonical implementation of the Bluetooth protocol stack is [http://www.bluez.org/ BlueZ].<br />
<br />
== Installation ==<br />
<br />
To use Bluetooth, [[pacman|install]] {{Pkg|bluez}}, available in the [[official repositories]]. The {{ic|dbus}} daemon(start automatically by systemd) is used to read settings and for PIN pairing, while the {{ic|bluetooth}} daemon is required for the Bluetooth protocol.<br />
<br />
<br />
<br />
# systemctl status bluetooth.service<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: inactive (dead)<br />
Docs: man:bluetoothd(8)<br />
<br />
Enable the ''bluetooth'' service to start it at system boot up.<br />
<br />
# systemctl enable bluetooth.service<br />
ln -s '/usr/lib/systemd/system/bluetooth.service' '/etc/systemd/system/dbus-org.bluez.service'<br />
ln -s '/usr/lib/systemd/system/bluetooth.service' '/etc/systemd/system/bluetooth.target.wants/bluetooth.service'<br />
<br />
Start the bluetooth [[systemd]] service.<br />
<br />
# systemctl status bluetooth.service<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; enabled)<br />
Active: inactive (dead)<br />
Docs: man:bluetoothd(8)<br />
<br />
# systemctl start bluetooth.service<br />
<br />
== Graphical front-ends ==<br />
<br />
The following packages allow for a graphical interface to customize Bluetooth.<br />
<br />
=== Blueman ===<br />
<br />
See [[Blueman]] article.<br />
<br />
=== GNOME Bluetooth ===<br />
<br />
[http://live.gnome.org/GnomeBluetooth GNOME Bluetooth] is a fork of the old ''bluez-gnome'' and is focused on integration with the [[GNOME]] desktop environment. GNOME Bluetooth is required by {{Pkg|gnome-shell}}, so you should already have it installed if you are running GNOME 3. Otherwise, it can be installed with the package {{Pkg|gnome-bluetooth}}. Note that gnome-shell, gnome-bluetooth <= 3.8 depend upon {{Pkg|bluez4}}. From gnome-shell 3.10 onwards, {{Pkg|bluez}} will be supported. More information regarding the GNOME migration to ''bluez'' can be found [http://worldofgnome.org/gnome-3-10-port-to-bluez-5/ here] (June 2013 blog post).<br />
<br />
Run {{ic|bluetooth-applet}} for a nice Bluetooth applet. You should now be able to setup devices and send files by right-clicking the Bluetooth icon. To make the applet run on login, add it to ''System > Preferences > Startup Applications''.<br />
<br />
To add a Bluetooth entry to the ''SendTo'' menu in Thunar's file properties menu, see instructions [http://thunar.xfce.org/pwiki/documentation/sendto_menu here].<br />
<br />
=== BlueDevil ===<br />
<br />
{{Note|As of 2013-09-01, ''bluedevil'' depends on the older {{Pkg|bluez4}}, which conflicts with the current {{Pkg|bluez}} (v5). Additionally, {{AUR|bluedevil-git}} is not updated to fix this dependency.}}<br />
<br />
The Bluetooth tool for [[KDE]] is [https://projects.kde.org/projects/extragear/base/bluedevil BlueDevil]. It can be installed with the package {{Pkg|bluedevil}}, available in the [[Official Repositories]].<br />
<br />
Make sure {{ic|bluetooth}} daemon is running, as described above. You should get a Bluetooth icon both in Dolphin and in the system tray, from which you can configure BlueDevil and detect Bluetooth devices by clicking the icon. You can also configure BlueDevil from the KDE System Settings<br />
<br />
=== Fluxbox, Openbox, other WM ===<br />
<br />
Of course you can still use the preceding applications even if GNOME, Xfce or KDE are not your desktop manager. This list should help you figuring out which application does what:<br />
* bluetooth-applet -- tray icon with access to settings, pairing wizard, management of known devices<br />
* /usr/lib/gnome-user-share/gnome-user-share -- needs to be running if you're about to receive files via obexBT from a paired/bonded device<br />
<br />
if you're receiving an error during transmission and/or there's no file received add this into<br />
<br />
{{ic|/etc/dbus-1/system.d/bluetooth.conf}}<br />
<policy user="your_user_id"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent"/><br />
</policy><br />
<br />
* bluetooth-wizard -- for new devices to be paired<br />
* bluetooth-properties -- accessible also via bluetooth-applet icon<br />
* gnome-file-share-properties -- permissions on receiving files via bluetooth<br />
* bluez-sendto -- gui for sending files to a remote device<br />
<br />
== Bluez Utils ==<br />
<br />
The package {{Pkg|bluez-utils}} contains various commands,<br />
which are useful to configure and troubleshoot Bluetooth<br />
from the command line.<br />
<br />
=== hciconfig ===<br />
<br />
Print name and basic information about all the Bluetooth devices installed in the system:<br />
# hciconfig<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 90:4C:E5:DB:E9:77 ACL MTU: 1021:8 SCO MTU: 64:1<br />
DOWN <br />
RX bytes:484 acl:0 sco:0 events:20 errors:0<br />
TX bytes:323 acl:0 sco:0 commands:20 errors:0<br />
<br />
<br />
<br />
<br />
hciconfig is part of the {{Pkg|bluez-utils}} package.<br />
<br />
To activate a device, use:<br />
# hciconfig ''device-name'' up<br />
<br />
=== hcitool ===<br />
<br />
To scan for remote devices:<br />
$ hcitool scan<br />
<br />
== Pairing ==<br />
Many bluetooth devices require [http://en.wikipedia.org/wiki/Bluetooth#Pairing pairing].<br />
The exact procedure depends on the devices involved and their input functionality.<br />
<br />
=== With bluez5 ===<br />
<br />
Start the {{ic|bluetoothctl}} interactive command. There you can input {{ic|help}} to get a list of available commands. <br />
* Enter {{ic|devices}} to get the MAC Address of the device with which you want to pair.<br />
* Enter {{ic|pair ''MAC Address''}} to do the pairing.<br />
* Finally, use {{ic|connect ''MAC_address''}} to establish a connection.<br />
<br />
=== With bluez4 ===<br />
<br />
The procedure on a mobile may be as follows:<br />
* The computer sends a connect request to the mobile. <br />
* A pin, determined by the computer, is prompted for at the mobile<br />
* The same key must be re-entered at the computer.<br />
<br />
To pair with a device without using the gnome-bluez package, the ''bluez-simple-agent'' utility that comes with the bluez package can be used. This utility depends on three packages from the official repositories: {{Pkg|python2-dbus}} {{Pkg|python2-gobject}} {{Pkg|dbus-glib}}.<br />
<br />
First, scan for external devices:<br />
$ hcitool scan<br />
<br />
Run the script as root:<br />
<br />
# bluez-simple-agent<br />
<br />
The message "Agent registered" should be returned, press control-c to quit. <br />
<br />
Below is a basic example of pairing with a specific device. The script will ask for the passcode, enter the code and confirm with enter.<br />
<br />
# bluez-simple-agent hci0 00:11:22:33:AA:BB<br />
<br />
{{Note|bluez-simple-agent is only needed once for pairing a device, not every time you want to connect.}}<br />
<br />
See the Examples section below for pairing examples with various devices.<br />
<br />
== Using Obex for sending and receiving files ==<br />
<br />
Another option, rather than using KDE or Gnome Bluetooth packages, is Obexfs which allows you to mount your phone and treat it as part of your filesystem. Note that to use Obexfs, you need a device that provides an Obex FTP service.<br />
<br />
Install {{Pkg|obexfs}} and then your phone can then be mounted by running <br />
$ obexfs -b ''devices_MAC_address'' /mountpoint<br />
<br />
For more mounting options see http://dev.zuckschwerdt.org/openobex/wiki/ObexFs<br />
<br />
For devices don't support Obex FTP service, check if Obex Object Push is supported.<br />
<br />
# sdptool browse ''XX:XX:XX:XX:XX:XX''<br />
<br />
Read the output, look for Obex Object Push, remember the channel for this service. If supported, you can use ussp-push to send files to this device:<br />
<br />
# ussp-push ''XX:XX:XX:XX:XX:XX''@''CHANNEL'' ''file'' ''wanted_file_name_on_phone''<br />
<br />
== Examples ==<br />
<br />
=== Siemens S55 ===<br />
<br />
This is what I did to connect to my S55. (I have not figured out how to initiate the connection from the phone)<br />
* The steps under installation<br />
<br />
{{hc|$ hcitool scan|<br />
Scanning ...<br />
''XX:XX:XX:XX:XX:XX'' NAME<br />
}}<br />
$ B=''XX:XX:XX:XX:XX:XX''<br />
Start the simple-agent in a second terminal:<br />
{{hc|$ su -c bluez-simple-agent|<br />
Password: <br />
Agent registered<br />
}}<br />
Back to the first console:<br />
{{hc|$ obexftp -b $B -l "Address book"|<nowiki><br />
# Phone ask for pin, I enter it and answer yes when asked if I want to save the device<br />
...<br />
<file name="5F07.adr" size="78712" modified="20030101T001858" user-perm="WD" group-perm="" /><br />
...<br />
</nowiki>}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -g "Address book/5F07.adr"|<br />
Browsing 00:01:E3:6B:FF:D7 ...<br />
Channel: 5<br />
Connecting...done<br />
Receiving "Address book/5F07.adr"... Sending "Address book"... done<br />
Disconnecting...done<br />
}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -p a|<br />
...<br />
Sending "a"... done<br />
Disconnecting...done<br />
}}<br />
<br />
=== Logitech mouse MX Laser / M555b ===<br />
<br />
To quickly test the connection:<br />
<br />
$ hidd --connect ''XX:XX:XX:XX:XX:XX''<br />
<br />
For automated reconnection, use your desktop wizard to configure the bluetooth mouse.<br />
If your desktop environment doesn't includes support for this task, see the [[Bluetooth mouse manual configuration]] guide.<br />
<br />
=== Motorola V900 ===<br />
<br />
After installing blueman and running blueman-applet, click "find me" under connections > bluetooth in Motorla device. In blueman-applet, scan devices, find the motorola, click "add" in blueman-applet. Click "bond" in blueman-applet, enter some pin, enter the same pin in motorola when it asks. In terminal:<br />
<br />
{{bc|<br />
$ mkdir ~/bluetooth-temp<br />
$ obexfs -n ''XX:XX:XX:XX:XX:XX'' ~/bluetooth-temp<br />
$ cd ~/bluetooth-temp<br />
}}<br />
<br />
and browse... Only audio, video, and pictures are available when you do this.<br />
<br />
=== Motorola RAZ ===<br />
<br />
Install {{Pkg|obextool}} {{Pkg|obexfs}} {{Pkg|obexftp}} {{Pkg|openobex}} {{Pkg|bluez}}.<br />
<br />
{{hc|# lsusb|<br />
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 002 Device 002: ID 03f0:171d Hewlett-Packard Wireless (Bluetooth + WLAN) Interface [Integrated Module]<br />
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|# hciconfig|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
{{hc|# hcitool dev|<br />
Devices:<br />
hci0 00:16:41:97:BA:5E<br />
}}<br />
<br />
Make sure that bluetooth on your phone is enabled and your phone is visible!<br />
<br />
{{hc|# hcitool scan|<br />
Scanning ...<br />
00:1A:1B:82:9B:6D [quirxi]<br />
}}<br />
<br />
{{hc|# hcitool inq|<br />
Inquiring ...<br />
00:1A:1B:82:9B:6D clock offset: 0x1ee4 class: 0x522204<br />
}}<br />
<br />
{{hc|# l2ping 00:1A:1B:82:9B:6D|<br />
Ping: 00:1A:1B:82:9B:6D from 00:16:41:97:BA:5E (data size 44) ...<br />
44 bytes from 00:1A:1B:82:9B:6D id 0 time 23.94ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 1 time 18.85ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 2 time 30.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 3 time 18.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 4 time 17.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 5 time 17.88ms<br />
6 sent, 6 received, 0% loss<br />
}}<br />
<br />
{{hc|# hcitool name 00:1A:1B:82:9B:6D|<br />
[quirxi]<br />
}}<br />
<br />
{{hc|# hciconfig -a hci0|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:9740 acl:122 sco:0 events:170 errors:0<br />
TX bytes:2920 acl:125 sco:0 commands:53 errors:0<br />
Features: 0xff 0xff 0x8d 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3<br />
Link policy:<br />
Link mode: SLAVE ACCEPT<br />
Name: 'BCM2045'<br />
Class: 0x000000<br />
Service Classes: Unspecified<br />
Device Class: Miscellaneous,<br />
HCI Version: 2.0 (0x3) Revision: 0x204a<br />
LMP Version: 2.0 (0x3) Subversion: 0x4176<br />
Manufacturer: Broadcoml / Corporation (15)<br />
}}<br />
<br />
{{hc|# hcitool info 00:1A:1B:82:9B:6D|<br />
Requesting information ...<br />
BD Address: 00:1A:1B:82:9B:6D<br />
Device Name: [quirxi]<br />
LMP Version: 1.2 (0x2) LMP Subversion: 0x309<br />
Manufacturer: Broadcom Corporation (15)<br />
Features: 0xff 0xfe 0x0d 0x00 0x08 0x08 0x00 0x00<br />
<3-slot packets> <5-slot packets> <encryption> <slot offset><br />
<timing accuracy> <role switch> <hold mode> <sniff mode><br />
<RSSI> <channel quality> <SCO link> <HV2 packets><br />
<HV3 packets> <A-law log> <CVSD> <power control><br />
<transparent SCO> <AFH cap. slave> <AFH cap. master><br />
}}<br />
<br />
Edit your {{ic|/etc/bluetooth/main.conf}} and enter the proper class for your phone ( Class = 0x100100 ):<br />
{{bc|<nowiki><br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100<br />
Class = 0x100100<br />
</nowiki>}}<br />
<br />
{{hc|# systemctl start bluetooth|<br />
:: Stopping bluetooth subsystem: pand dund rfcomm hidd bluetoothd<br />
[DONE]<br />
:: Starting bluetooth subsystem: bluetoothd<br />
}}<br />
<br />
Pairing with bluez-simple-agent only has to be done once. On your Motorola phone give 0000 in as your PIN when phone asks for it!<br />
{{hc|/usr/bin/bluez-simple-agent hci0 00:1A:1B:82:9B:6D|<br />
RequestPinCode (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
Enter PIN Code: 0000<br />
Release<br />
New device (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
}}<br />
<br />
Now you can browse the filesystem of your phone with obexftp:<br />
{{hc|obexftp -v -b 00:1A:1B:82:9B:6D -B 9 -l|<nowiki><br />
Connecting..\done<br />
Tried to connect for 448ms<br />
Receiving "(null)"...-<?xml version="1.0" ?><br />
<!DOCTYPE folder-listing SYSTEM "obex-folder-listing.dtd"><br />
<folder-listing><br />
<parent-folder /><br />
<folder name="audio" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="video" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="picture" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
</folder-listing><br />
done<br />
Disconnecting..\done<br />
</nowiki>}}<br />
<br />
Or you can mount your phone into a directory on your computer and treat it like a normal file system:<br />
{{bc|<br />
# groupadd bluetooth<br />
# mkdir /mnt/bluetooth<br />
# chown root:bluetooth /mnt/bluetooth<br />
# chmod 775 /mnt/bluetooth<br />
# usermod -a -G bluetooth arno<br />
# obexfs -b 00:1A:1B:82:9B:6D /mnt/bluetooth/<br />
}}<br />
<br />
=== Pairing with an iPhone using bluez-simple-agent ===<br />
<br />
Assuming a bluetooth device called hci0 and an iPhone that showed up in a hcitool scan as '00:00:DE:AD:BE:EF':<br />
<br />
# bluez-simple-agent hci0 00:00:DE:AD:BE:EF<br />
Passcode:<br />
<br />
=== Headset and ALSA devices ===<br />
<br />
==== by referencing the bluetooth device in asound.conf ====<br />
<br />
1. Scan for your device:<br />
$ hcitool (-i ''optional hci#''***) scan<br />
2. 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 />
3. Add this to your {{ic|/etc/asound.conf}} file:<br />
<br />
{{bc|<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 />
<br />
4. Check to see if it has been added to ALSA devices<br />
$ aplay -L<br />
<br />
5. 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 />
To find hci# for a usb dongle, type in:<br />
$ hcitool dev<br />
<br />
==== by using bluez-tools from the AUR ====<br />
<br />
You can use {{AUR|bluez-tools}} from the [[AUR]] with PulseAudio to stream audio to a bluetooth headset.<br />
Find the MAC of the headset:<br />
$ hcitool scan<br />
Connect to the headset:<br />
$ bt-audio -c XX:XX:XX:XX:XX:XX<br />
Open pulseaudio volume control:<br />
$ pavucontrol<br />
The headset should show up in the Configuration tab.<br />
<br />
=== Microsoft Bluetooth Mobile Keyboard 6000 ===<br />
<br />
1. Scan for your device<br />
$ hcitool (-i ''optional_hci#''***) scan<br />
Scanning ...<br />
00:11:22:33:44:55 Microsoft Bluetooth Mobile Keyboard 6000<br />
<br />
2. On second console run as root (do not terminate):<br />
# bluez-simple-agent<br />
Agent registered<br />
<br />
3. Back on first console run:<br />
$ bluez-simple-agent hci0 00:11:22:33:44:55<br />
Enter PIN Code: 1234<br />
(now enter that PIN on the keyboard and press enter)<br />
Release<br />
New device (/org/bluez/5373/hci0/dev_00_11_22_33_44_55)<br />
<br />
4.<br />
$ bluez-test-device trusted 00:11:22:33:44:55<br />
<br />
5.<br />
$ bluez-test-input connect 00:11:22:33:44:55<br />
<br />
No your keyboard should work. You can terminate bluez-simple-agent on second console with {{ic|Ctrl+C}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== passkey-agent ===<br />
<br />
$ passkey-agent --default 1234<br />
Can't register passkey agent<br />
The name org.bluez was not provided by any .service files<br />
and<br />
$ hciconfig dev<br />
# (no listing)<br />
Try running {{ic|hciconfig hc0 up}}<br />
<br />
=== gnome-bluetooth ===<br />
<br />
If you see this when trying to enable receiving files in bluetooth-properties:<br />
Bluetooth OBEX start failed: Invalid path<br />
Bluetooth FTP start failed: Invalid path<br />
Then install {{Pkg|xdg-user-dirs}} and issue:<br />
$ xdg-user-dirs-update<br />
You can edit the paths using:<br />
$ vi ~/.config/user-dirs.dirs<br />
<br />
=== Bluetooth USB Dongle ===<br />
<br />
If you are using a USB dongle, you should check that your Bluetooth dongle is recognized. You can do that by inspecting {{ic|/var/log/messages.log}} when plugging in the USB dongle (or running {{ic|journalctl -f}} with systemd). It should look something like the following (look out for hci):<br />
<br />
{{bc|<br />
Feb 20 15:00:24 hostname kernel: [ 2661.349823] usb 4-1: new full-speed USB device number 3 using uhci_hcd<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: HCI dev 0 registered<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: Listening for HCI events on hci0<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: HCI dev 0 up<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: Adapter /org/bluez/4568/hci0 has been enabled<br />
}}<br />
<br />
For a list of supported hardware please refer to the [[#Resources|Resource]] section on this page.<br />
<br />
If you only get the first two lines, you may see that it found the device but you need to bring it up.<br />
Example:<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:00:00:00:00:00 ACL MTU: 0:0 SCO MTU: 0:0<br />
DOWN <br />
RX bytes:0 acl:0 sco:0 events:0 errors:0<br />
TX bytes:0 acl:0 sco:0 commands:0 errors:<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:02:72:C4:7C:06 ACL MTU: 377:10 SCO MTU: 64:8<br />
UP RUNNING <br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
If this fails with an error like:<br />
Operation not possible due to RF-kill<br />
it could be due either to the {{ic|rfkill}} utility, in which case it should be resolved with<br />
# rfkill unblock all<br />
or, it could simply be the hardware switch of the computer. The hardware bluetooth switch (at least sometimes) controls access to USB bluetooth dongles also. Flip/press this switch and try bringing the device up again.<br />
<br />
To verify that the device was detected you can use {{ic|hcitool}} which is part of the {{ic|bluez-utils}}. You can get a list of available devices and their identifiers and their MAC address by issuing:<br />
<br />
{{hc|$ hcitool dev|<br />
Devices:<br />
hci0 00:1B:DC:0F:DB:40<br />
}}<br />
<br />
More detailed informations about the device can be retrieved by using {{ic|hciconfig}}.<br />
<br />
{{hc|$ hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:1B:DC:0F:DB:40 ACL MTU: 310:10 SCO MTU: 64:8<br />
UP RUNNING PSCAN ISCAN <br />
RX bytes:1226 acl:0 sco:0 events:27 errors:0<br />
TX bytes:351 acl:0 sco:0 commands:26 errors:0<br />
Features: 0xff 0xff 0x8f 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3 <br />
Link policy: RSWITCH HOLD SNIFF PARK <br />
Link mode: SLAVE ACCEPT <br />
Name: 'BlueZ (0)'<br />
Class: 0x000100<br />
Service Classes: Unspecified<br />
Device Class: Computer, Uncategorized<br />
HCI Ver: 2.0 (0x3) HCI Rev: 0xc5c LMP Ver: 2.0 (0x3) LMP Subver: 0xc5c<br />
Manufacturer: Cambridge Silicon Radio (10)<br />
}}<br />
<br />
=== Logitech Bluetooth USB Dongle ===<br />
<br />
There are Logitech dongles (ex. Logitech MX5000) that can work in two modes Embedded and HCI. In embedded mode dongle emulates a USB device so it seems to your PC that your using a normal USB mouse/keyoard.<br />
<br />
If you hold the little red Button on the USB BT mini-receiver it will enable the other mode. Hold the red button on the BT dongle and plug it into the computer, and after 3-5 seconds of holding the button, the Bluetooth icon will appear in the system tray. [http://ubuntuforums.org/showthread.php?t=1332197 Discussion]<br />
<br />
=== hcitool scan: Device not found ===<br />
<br />
* On some Dell laptops (e.g. Studio 15) you have to switch the Bluetooth mode from HID to HCI using<br />
# hid2hci<br />
<br />
{{Note|hid2hci is no longer in the $PATH, it is under /lib/udev/hid2hci, but udev should run it automatically for you.}}<br />
<br />
* If the device won't show up and you have a Windows operating system on your machine, try booting it and enable the bluetooth adapter from windows.<br />
<br />
* Sometimes also this simple command helps:<br />
# hciconfig hci0 up<br />
<br />
=== rfkill unblock: Do not unblock ===<br />
<br />
If your device still soft blocked and you run connman.<br />
<br />
Try this:<br />
$ connmanctl enable bluetooth<br />
<br />
=== My computer is not visible ===<br />
<br />
Can't discover computer from your phone? Enable PSCAN and ISCAN:<br />
# enable PSCAN and ISCAN<br />
$ hciconfig hci0 piscan <br />
# check it worked<br />
{{hc|$ hciconfig|<br />
hci0: Type: USB<br />
BD Address: 00:12:34:56:78:9A ACL MTU: 192:8 SCO MTU: 64:8<br />
'''UP RUNNING PSCAN ISCAN'''<br />
RX bytes:20425 acl:115 sco:0 events:526 errors:0<br />
TX bytes:5543 acl:84 sco:0 commands:340 errors:0<br />
}}<br />
<br />
{{Note|Check DiscoverableTimeout and PairableTimeout in {{ic|/etc/bluetooth/main.conf}}}}<br />
<br />
Try changing device class in {{ic|/etc/bluetooth/main.conf}} as following:<br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100 (from default config)<br />
Class = 0x100100<br />
<br />
This was the only solution to make my computer visible for my phone. <br />
<br />
=== Nautilus cannot browse files ===<br />
<br />
If nautilus doesn't open and show this error:<br />
Nautilus cannot handle obex: locations. Couldn't display "obex://[XX:XX:XX:XX:XX:XX]/".<br />
Install {{Pkg|gvfs-obexftp}} package.<br />
<br />
=== Sennheiser MM400 Headset connection problems ===<br />
<br />
If your {{ic|Sennheiser MM400 Headset}} immediately disconnects after connecting as {{ic|Headset Service}} with Blueman, try to connect it as {{ic|Audio Sink}}. Afterwards you can change the headset's {{ic|Audio Profile}} to {{ic|Telephony Duplex}} with a right click in Blueman.<br />
With this option headset functionality will be available although the headset was only connected as {{ic|Audio Sink}} in first place and no disconnection will happen (tested with bluez 4.96-3, pulseaudio 1.1-1 and blueman 1.23-2).<br />
<br />
=== My device is paired but no sound is played from it ===<br />
<br />
Try to first inspect {{ic|/var/log/messages.log}}. If you see such messages:<br />
{{bc|<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Service not connected<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Bluetooth audio service not available<br />
}}<br />
try first:<br />
# pactl load-module module-bluetooth-device<br />
<br />
If the module fails to work, do this workaround:<br />
Open {{ic|/etc/bluetooth/audio.conf}} and add after '''[General]''' (on a new line)<br />
Enable=Socket<br />
Then restart the bluetooth daemon.<br />
Pair again your device, and you should find it in the pulseaudio settings (advanced settings for the sound)<br />
<br />
[http://wiki.gentoo.org/index.php?title=Bluetooth_Headset&redirect=no More information on Gentoo Wiki]<br />
<br />
If after fixing this you still can't get sound, try using blueman (this is the only one that works for me), make sure that notify-osd is installed or it might show you weird error messages like this one: "Stream setup failed"<br />
<br />
fail (/usr/lib/python2.7/site-packages/blueman/gui/manager/ManagerDeviceMenu.py:134)<br />
fail (DBusException(dbus.String(u'Stream setup failed'),),)<br />
<br />
== See also ==<br />
<br />
*[http://www.gentoo.org/doc/en/bluetooth-guide.xml Gentoo Linux Bluetooth guide]<br />
*[http://en.opensuse.org/HCL:Bluetooth openSUSE Bluetooth Hardware Compatibility List]<br />
*[http://linuxgazette.net/109/oregan3.html Accessing a Bluetooth phone (Linux Gazette)]<br />
*[http://www.adamish.com/blog/#a000361 Bluetooth computer visibility]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth for your mobile phone: Bluetooth pairing, data synchronization, photo download, Internet Dial-Up (tethering)]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth pairing and applications for synchronizing phone numbers, SMS-messages, phone call entries, your calendar and time; tethering]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth&diff=276249Bluetooth2013-09-21T19:13:51Z<p>Netskink: /* Installation */ Showing the commands usage and results.</p>
<hr />
<div>[[Category:Bluetooth]]<br />
[[cs:Bluetooth]]<br />
[[de:Bluetooth]]<br />
[[es:Bluetooth]]<br />
[[fr:Bluetooth]]<br />
[[it:Bluetooth]]<br />
[[ru:Bluetooth]]<br />
[[zh-CN:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers the installation and use of Bluetooth on Arch Linux.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth mouse configuration}}<br />
{{Article summary end}}<br />
<br />
{{Out of date|Several generations of various deprecated tools are mentioned. bluez4 and bluez are confused. This article needs cleanup from someone who knows what commands belong in which packages.}}<br />
<br />
[http://www.bluetooth.org/ Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. In Linux, the canonical implementation of the Bluetooth protocol stack is [http://www.bluez.org/ BlueZ].<br />
<br />
== Installation ==<br />
<br />
To use Bluetooth, [[pacman|install]] {{Pkg|bluez}}, available in the [[official repositories]]. The {{ic|dbus}} daemon(start automatically by systemd) is used to read settings and for PIN pairing, while the {{ic|bluetooth}} daemon is required for the Bluetooth protocol.<br />
<br />
<br />
<br />
# systemctl status bluetooth.service<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: inactive (dead)<br />
Docs: man:bluetoothd(8)<br />
<br />
Enable the ''bluetooth'' service to start it at system boot up.<br />
<br />
# systemctl enable bluetooth.service<br />
ln -s '/usr/lib/systemd/system/bluetooth.service' '/etc/systemd/system/dbus-org.bluez.service'<br />
ln -s '/usr/lib/systemd/system/bluetooth.service' '/etc/systemd/system/bluetooth.target.wants/bluetooth.service'<br />
<br />
Start the bluetooth [[systemd]] service.<br />
<br />
# systemctl status bluetooth.service<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; enabled)<br />
Active: inactive (dead)<br />
Docs: man:bluetoothd(8)<br />
<br />
# systemctl start bluetooth.service<br />
<br />
== Graphical front-ends ==<br />
<br />
The following packages allow for a graphical interface to customize Bluetooth.<br />
<br />
=== Blueman ===<br />
<br />
See [[Blueman]] article.<br />
<br />
=== GNOME Bluetooth ===<br />
<br />
[http://live.gnome.org/GnomeBluetooth GNOME Bluetooth] is a fork of the old ''bluez-gnome'' and is focused on integration with the [[GNOME]] desktop environment. GNOME Bluetooth is required by {{Pkg|gnome-shell}}, so you should already have it installed if you are running GNOME 3. Otherwise, it can be installed with the package {{Pkg|gnome-bluetooth}}. Note that gnome-shell, gnome-bluetooth <= 3.8 depend upon {{Pkg|bluez4}}. From gnome-shell 3.10 onwards, {{Pkg|bluez}} will be supported. More information regarding the GNOME migration to ''bluez'' can be found [http://worldofgnome.org/gnome-3-10-port-to-bluez-5/ here] (June 2013 blog post).<br />
<br />
Run {{ic|bluetooth-applet}} for a nice Bluetooth applet. You should now be able to setup devices and send files by right-clicking the Bluetooth icon. To make the applet run on login, add it to ''System > Preferences > Startup Applications''.<br />
<br />
To add a Bluetooth entry to the ''SendTo'' menu in Thunar's file properties menu, see instructions [http://thunar.xfce.org/pwiki/documentation/sendto_menu here].<br />
<br />
=== BlueDevil ===<br />
<br />
{{Note|As of 2013-09-01, ''bluedevil'' depends on the older {{Pkg|bluez4}}, which conflicts with the current {{Pkg|bluez}} (v5). Additionally, {{AUR|bluedevil-git}} is not updated to fix this dependency.}}<br />
<br />
The Bluetooth tool for [[KDE]] is [https://projects.kde.org/projects/extragear/base/bluedevil BlueDevil]. It can be installed with the package {{Pkg|bluedevil}}, available in the [[Official Repositories]].<br />
<br />
Make sure {{ic|bluetooth}} daemon is running, as described above. You should get a Bluetooth icon both in Dolphin and in the system tray, from which you can configure BlueDevil and detect Bluetooth devices by clicking the icon. You can also configure BlueDevil from the KDE System Settings<br />
<br />
=== Fluxbox, Openbox, other WM ===<br />
<br />
Of course you can still use the preceding applications even if GNOME, Xfce or KDE are not your desktop manager. This list should help you figuring out which application does what:<br />
* bluetooth-applet -- tray icon with access to settings, pairing wizard, management of known devices<br />
* /usr/lib/gnome-user-share/gnome-user-share -- needs to be running if you're about to receive files via obexBT from a paired/bonded device<br />
<br />
if you're receiving an error during transmission and/or there's no file received add this into<br />
<br />
{{ic|/etc/dbus-1/system.d/bluetooth.conf}}<br />
<policy user="your_user_id"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent"/><br />
</policy><br />
<br />
* bluetooth-wizard -- for new devices to be paired<br />
* bluetooth-properties -- accessible also via bluetooth-applet icon<br />
* gnome-file-share-properties -- permissions on receiving files via bluetooth<br />
* bluez-sendto -- gui for sending files to a remote device<br />
<br />
== Bluez Utils ==<br />
<br />
The package {{Pkg|bluez-utils}} contains various commands,<br />
which are useful to configure and troubleshoot Bluetooth<br />
from the command line.<br />
<br />
=== hciconfig ===<br />
<br />
Print name and basic information about all the Bluetooth devices installed in the system:<br />
$ hciconfig<br />
<br />
hciconfig is part of the {{Pkg|bluez-utils}} package.<br />
<br />
To activate a device, use:<br />
# hciconfig ''device-name'' up<br />
<br />
=== hcitool ===<br />
<br />
To scan for remote devices:<br />
$ hcitool scan<br />
<br />
== Pairing ==<br />
Many bluetooth devices require [http://en.wikipedia.org/wiki/Bluetooth#Pairing pairing].<br />
The exact procedure depends on the devices involved and their input functionality.<br />
<br />
=== With bluez5 ===<br />
<br />
Start the {{ic|bluetoothctl}} interactive command. There you can input {{ic|help}} to get a list of available commands. <br />
* Enter {{ic|devices}} to get the MAC Address of the device with which you want to pair.<br />
* Enter {{ic|pair ''MAC Address''}} to do the pairing.<br />
* Finally, use {{ic|connect ''MAC_address''}} to establish a connection.<br />
<br />
=== With bluez4 ===<br />
<br />
The procedure on a mobile may be as follows:<br />
* The computer sends a connect request to the mobile. <br />
* A pin, determined by the computer, is prompted for at the mobile<br />
* The same key must be re-entered at the computer.<br />
<br />
To pair with a device without using the gnome-bluez package, the ''bluez-simple-agent'' utility that comes with the bluez package can be used. This utility depends on three packages from the official repositories: {{Pkg|python2-dbus}} {{Pkg|python2-gobject}} {{Pkg|dbus-glib}}.<br />
<br />
First, scan for external devices:<br />
$ hcitool scan<br />
<br />
Run the script as root:<br />
<br />
# bluez-simple-agent<br />
<br />
The message "Agent registered" should be returned, press control-c to quit. <br />
<br />
Below is a basic example of pairing with a specific device. The script will ask for the passcode, enter the code and confirm with enter.<br />
<br />
# bluez-simple-agent hci0 00:11:22:33:AA:BB<br />
<br />
{{Note|bluez-simple-agent is only needed once for pairing a device, not every time you want to connect.}}<br />
<br />
See the Examples section below for pairing examples with various devices.<br />
<br />
== Using Obex for sending and receiving files ==<br />
<br />
Another option, rather than using KDE or Gnome Bluetooth packages, is Obexfs which allows you to mount your phone and treat it as part of your filesystem. Note that to use Obexfs, you need a device that provides an Obex FTP service.<br />
<br />
Install {{Pkg|obexfs}} and then your phone can then be mounted by running <br />
$ obexfs -b ''devices_MAC_address'' /mountpoint<br />
<br />
For more mounting options see http://dev.zuckschwerdt.org/openobex/wiki/ObexFs<br />
<br />
For devices don't support Obex FTP service, check if Obex Object Push is supported.<br />
<br />
# sdptool browse ''XX:XX:XX:XX:XX:XX''<br />
<br />
Read the output, look for Obex Object Push, remember the channel for this service. If supported, you can use ussp-push to send files to this device:<br />
<br />
# ussp-push ''XX:XX:XX:XX:XX:XX''@''CHANNEL'' ''file'' ''wanted_file_name_on_phone''<br />
<br />
== Examples ==<br />
<br />
=== Siemens S55 ===<br />
<br />
This is what I did to connect to my S55. (I have not figured out how to initiate the connection from the phone)<br />
* The steps under installation<br />
<br />
{{hc|$ hcitool scan|<br />
Scanning ...<br />
''XX:XX:XX:XX:XX:XX'' NAME<br />
}}<br />
$ B=''XX:XX:XX:XX:XX:XX''<br />
Start the simple-agent in a second terminal:<br />
{{hc|$ su -c bluez-simple-agent|<br />
Password: <br />
Agent registered<br />
}}<br />
Back to the first console:<br />
{{hc|$ obexftp -b $B -l "Address book"|<nowiki><br />
# Phone ask for pin, I enter it and answer yes when asked if I want to save the device<br />
...<br />
<file name="5F07.adr" size="78712" modified="20030101T001858" user-perm="WD" group-perm="" /><br />
...<br />
</nowiki>}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -g "Address book/5F07.adr"|<br />
Browsing 00:01:E3:6B:FF:D7 ...<br />
Channel: 5<br />
Connecting...done<br />
Receiving "Address book/5F07.adr"... Sending "Address book"... done<br />
Disconnecting...done<br />
}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -p a|<br />
...<br />
Sending "a"... done<br />
Disconnecting...done<br />
}}<br />
<br />
=== Logitech mouse MX Laser / M555b ===<br />
<br />
To quickly test the connection:<br />
<br />
$ hidd --connect ''XX:XX:XX:XX:XX:XX''<br />
<br />
For automated reconnection, use your desktop wizard to configure the bluetooth mouse.<br />
If your desktop environment doesn't includes support for this task, see the [[Bluetooth mouse manual configuration]] guide.<br />
<br />
=== Motorola V900 ===<br />
<br />
After installing blueman and running blueman-applet, click "find me" under connections > bluetooth in Motorla device. In blueman-applet, scan devices, find the motorola, click "add" in blueman-applet. Click "bond" in blueman-applet, enter some pin, enter the same pin in motorola when it asks. In terminal:<br />
<br />
{{bc|<br />
$ mkdir ~/bluetooth-temp<br />
$ obexfs -n ''XX:XX:XX:XX:XX:XX'' ~/bluetooth-temp<br />
$ cd ~/bluetooth-temp<br />
}}<br />
<br />
and browse... Only audio, video, and pictures are available when you do this.<br />
<br />
=== Motorola RAZ ===<br />
<br />
Install {{Pkg|obextool}} {{Pkg|obexfs}} {{Pkg|obexftp}} {{Pkg|openobex}} {{Pkg|bluez}}.<br />
<br />
{{hc|# lsusb|<br />
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 002 Device 002: ID 03f0:171d Hewlett-Packard Wireless (Bluetooth + WLAN) Interface [Integrated Module]<br />
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|# hciconfig|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
{{hc|# hcitool dev|<br />
Devices:<br />
hci0 00:16:41:97:BA:5E<br />
}}<br />
<br />
Make sure that bluetooth on your phone is enabled and your phone is visible!<br />
<br />
{{hc|# hcitool scan|<br />
Scanning ...<br />
00:1A:1B:82:9B:6D [quirxi]<br />
}}<br />
<br />
{{hc|# hcitool inq|<br />
Inquiring ...<br />
00:1A:1B:82:9B:6D clock offset: 0x1ee4 class: 0x522204<br />
}}<br />
<br />
{{hc|# l2ping 00:1A:1B:82:9B:6D|<br />
Ping: 00:1A:1B:82:9B:6D from 00:16:41:97:BA:5E (data size 44) ...<br />
44 bytes from 00:1A:1B:82:9B:6D id 0 time 23.94ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 1 time 18.85ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 2 time 30.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 3 time 18.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 4 time 17.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 5 time 17.88ms<br />
6 sent, 6 received, 0% loss<br />
}}<br />
<br />
{{hc|# hcitool name 00:1A:1B:82:9B:6D|<br />
[quirxi]<br />
}}<br />
<br />
{{hc|# hciconfig -a hci0|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:9740 acl:122 sco:0 events:170 errors:0<br />
TX bytes:2920 acl:125 sco:0 commands:53 errors:0<br />
Features: 0xff 0xff 0x8d 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3<br />
Link policy:<br />
Link mode: SLAVE ACCEPT<br />
Name: 'BCM2045'<br />
Class: 0x000000<br />
Service Classes: Unspecified<br />
Device Class: Miscellaneous,<br />
HCI Version: 2.0 (0x3) Revision: 0x204a<br />
LMP Version: 2.0 (0x3) Subversion: 0x4176<br />
Manufacturer: Broadcoml / Corporation (15)<br />
}}<br />
<br />
{{hc|# hcitool info 00:1A:1B:82:9B:6D|<br />
Requesting information ...<br />
BD Address: 00:1A:1B:82:9B:6D<br />
Device Name: [quirxi]<br />
LMP Version: 1.2 (0x2) LMP Subversion: 0x309<br />
Manufacturer: Broadcom Corporation (15)<br />
Features: 0xff 0xfe 0x0d 0x00 0x08 0x08 0x00 0x00<br />
<3-slot packets> <5-slot packets> <encryption> <slot offset><br />
<timing accuracy> <role switch> <hold mode> <sniff mode><br />
<RSSI> <channel quality> <SCO link> <HV2 packets><br />
<HV3 packets> <A-law log> <CVSD> <power control><br />
<transparent SCO> <AFH cap. slave> <AFH cap. master><br />
}}<br />
<br />
Edit your {{ic|/etc/bluetooth/main.conf}} and enter the proper class for your phone ( Class = 0x100100 ):<br />
{{bc|<nowiki><br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100<br />
Class = 0x100100<br />
</nowiki>}}<br />
<br />
{{hc|# systemctl start bluetooth|<br />
:: Stopping bluetooth subsystem: pand dund rfcomm hidd bluetoothd<br />
[DONE]<br />
:: Starting bluetooth subsystem: bluetoothd<br />
}}<br />
<br />
Pairing with bluez-simple-agent only has to be done once. On your Motorola phone give 0000 in as your PIN when phone asks for it!<br />
{{hc|/usr/bin/bluez-simple-agent hci0 00:1A:1B:82:9B:6D|<br />
RequestPinCode (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
Enter PIN Code: 0000<br />
Release<br />
New device (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
}}<br />
<br />
Now you can browse the filesystem of your phone with obexftp:<br />
{{hc|obexftp -v -b 00:1A:1B:82:9B:6D -B 9 -l|<nowiki><br />
Connecting..\done<br />
Tried to connect for 448ms<br />
Receiving "(null)"...-<?xml version="1.0" ?><br />
<!DOCTYPE folder-listing SYSTEM "obex-folder-listing.dtd"><br />
<folder-listing><br />
<parent-folder /><br />
<folder name="audio" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="video" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="picture" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
</folder-listing><br />
done<br />
Disconnecting..\done<br />
</nowiki>}}<br />
<br />
Or you can mount your phone into a directory on your computer and treat it like a normal file system:<br />
{{bc|<br />
# groupadd bluetooth<br />
# mkdir /mnt/bluetooth<br />
# chown root:bluetooth /mnt/bluetooth<br />
# chmod 775 /mnt/bluetooth<br />
# usermod -a -G bluetooth arno<br />
# obexfs -b 00:1A:1B:82:9B:6D /mnt/bluetooth/<br />
}}<br />
<br />
=== Pairing with an iPhone using bluez-simple-agent ===<br />
<br />
Assuming a bluetooth device called hci0 and an iPhone that showed up in a hcitool scan as '00:00:DE:AD:BE:EF':<br />
<br />
# bluez-simple-agent hci0 00:00:DE:AD:BE:EF<br />
Passcode:<br />
<br />
=== Headset and ALSA devices ===<br />
<br />
==== by referencing the bluetooth device in asound.conf ====<br />
<br />
1. Scan for your device:<br />
$ hcitool (-i ''optional hci#''***) scan<br />
2. 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 />
3. Add this to your {{ic|/etc/asound.conf}} file:<br />
<br />
{{bc|<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 />
<br />
4. Check to see if it has been added to ALSA devices<br />
$ aplay -L<br />
<br />
5. 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 />
To find hci# for a usb dongle, type in:<br />
$ hcitool dev<br />
<br />
==== by using bluez-tools from the AUR ====<br />
<br />
You can use {{AUR|bluez-tools}} from the [[AUR]] with PulseAudio to stream audio to a bluetooth headset.<br />
Find the MAC of the headset:<br />
$ hcitool scan<br />
Connect to the headset:<br />
$ bt-audio -c XX:XX:XX:XX:XX:XX<br />
Open pulseaudio volume control:<br />
$ pavucontrol<br />
The headset should show up in the Configuration tab.<br />
<br />
=== Microsoft Bluetooth Mobile Keyboard 6000 ===<br />
<br />
1. Scan for your device<br />
$ hcitool (-i ''optional_hci#''***) scan<br />
Scanning ...<br />
00:11:22:33:44:55 Microsoft Bluetooth Mobile Keyboard 6000<br />
<br />
2. On second console run as root (do not terminate):<br />
# bluez-simple-agent<br />
Agent registered<br />
<br />
3. Back on first console run:<br />
$ bluez-simple-agent hci0 00:11:22:33:44:55<br />
Enter PIN Code: 1234<br />
(now enter that PIN on the keyboard and press enter)<br />
Release<br />
New device (/org/bluez/5373/hci0/dev_00_11_22_33_44_55)<br />
<br />
4.<br />
$ bluez-test-device trusted 00:11:22:33:44:55<br />
<br />
5.<br />
$ bluez-test-input connect 00:11:22:33:44:55<br />
<br />
No your keyboard should work. You can terminate bluez-simple-agent on second console with {{ic|Ctrl+C}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== passkey-agent ===<br />
<br />
$ passkey-agent --default 1234<br />
Can't register passkey agent<br />
The name org.bluez was not provided by any .service files<br />
and<br />
$ hciconfig dev<br />
# (no listing)<br />
Try running {{ic|hciconfig hc0 up}}<br />
<br />
=== gnome-bluetooth ===<br />
<br />
If you see this when trying to enable receiving files in bluetooth-properties:<br />
Bluetooth OBEX start failed: Invalid path<br />
Bluetooth FTP start failed: Invalid path<br />
Then install {{Pkg|xdg-user-dirs}} and issue:<br />
$ xdg-user-dirs-update<br />
You can edit the paths using:<br />
$ vi ~/.config/user-dirs.dirs<br />
<br />
=== Bluetooth USB Dongle ===<br />
<br />
If you are using a USB dongle, you should check that your Bluetooth dongle is recognized. You can do that by inspecting {{ic|/var/log/messages.log}} when plugging in the USB dongle (or running {{ic|journalctl -f}} with systemd). It should look something like the following (look out for hci):<br />
<br />
{{bc|<br />
Feb 20 15:00:24 hostname kernel: [ 2661.349823] usb 4-1: new full-speed USB device number 3 using uhci_hcd<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: HCI dev 0 registered<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: Listening for HCI events on hci0<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: HCI dev 0 up<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: Adapter /org/bluez/4568/hci0 has been enabled<br />
}}<br />
<br />
For a list of supported hardware please refer to the [[#Resources|Resource]] section on this page.<br />
<br />
If you only get the first two lines, you may see that it found the device but you need to bring it up.<br />
Example:<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:00:00:00:00:00 ACL MTU: 0:0 SCO MTU: 0:0<br />
DOWN <br />
RX bytes:0 acl:0 sco:0 events:0 errors:0<br />
TX bytes:0 acl:0 sco:0 commands:0 errors:<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:02:72:C4:7C:06 ACL MTU: 377:10 SCO MTU: 64:8<br />
UP RUNNING <br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
If this fails with an error like:<br />
Operation not possible due to RF-kill<br />
it could be due either to the {{ic|rfkill}} utility, in which case it should be resolved with<br />
# rfkill unblock all<br />
or, it could simply be the hardware switch of the computer. The hardware bluetooth switch (at least sometimes) controls access to USB bluetooth dongles also. Flip/press this switch and try bringing the device up again.<br />
<br />
To verify that the device was detected you can use {{ic|hcitool}} which is part of the {{ic|bluez-utils}}. You can get a list of available devices and their identifiers and their MAC address by issuing:<br />
<br />
{{hc|$ hcitool dev|<br />
Devices:<br />
hci0 00:1B:DC:0F:DB:40<br />
}}<br />
<br />
More detailed informations about the device can be retrieved by using {{ic|hciconfig}}.<br />
<br />
{{hc|$ hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:1B:DC:0F:DB:40 ACL MTU: 310:10 SCO MTU: 64:8<br />
UP RUNNING PSCAN ISCAN <br />
RX bytes:1226 acl:0 sco:0 events:27 errors:0<br />
TX bytes:351 acl:0 sco:0 commands:26 errors:0<br />
Features: 0xff 0xff 0x8f 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3 <br />
Link policy: RSWITCH HOLD SNIFF PARK <br />
Link mode: SLAVE ACCEPT <br />
Name: 'BlueZ (0)'<br />
Class: 0x000100<br />
Service Classes: Unspecified<br />
Device Class: Computer, Uncategorized<br />
HCI Ver: 2.0 (0x3) HCI Rev: 0xc5c LMP Ver: 2.0 (0x3) LMP Subver: 0xc5c<br />
Manufacturer: Cambridge Silicon Radio (10)<br />
}}<br />
<br />
=== Logitech Bluetooth USB Dongle ===<br />
<br />
There are Logitech dongles (ex. Logitech MX5000) that can work in two modes Embedded and HCI. In embedded mode dongle emulates a USB device so it seems to your PC that your using a normal USB mouse/keyoard.<br />
<br />
If you hold the little red Button on the USB BT mini-receiver it will enable the other mode. Hold the red button on the BT dongle and plug it into the computer, and after 3-5 seconds of holding the button, the Bluetooth icon will appear in the system tray. [http://ubuntuforums.org/showthread.php?t=1332197 Discussion]<br />
<br />
=== hcitool scan: Device not found ===<br />
<br />
* On some Dell laptops (e.g. Studio 15) you have to switch the Bluetooth mode from HID to HCI using<br />
# hid2hci<br />
<br />
{{Note|hid2hci is no longer in the $PATH, it is under /lib/udev/hid2hci, but udev should run it automatically for you.}}<br />
<br />
* If the device won't show up and you have a Windows operating system on your machine, try booting it and enable the bluetooth adapter from windows.<br />
<br />
* Sometimes also this simple command helps:<br />
# hciconfig hci0 up<br />
<br />
=== rfkill unblock: Do not unblock ===<br />
<br />
If your device still soft blocked and you run connman.<br />
<br />
Try this:<br />
$ connmanctl enable bluetooth<br />
<br />
=== My computer is not visible ===<br />
<br />
Can't discover computer from your phone? Enable PSCAN and ISCAN:<br />
# enable PSCAN and ISCAN<br />
$ hciconfig hci0 piscan <br />
# check it worked<br />
{{hc|$ hciconfig|<br />
hci0: Type: USB<br />
BD Address: 00:12:34:56:78:9A ACL MTU: 192:8 SCO MTU: 64:8<br />
'''UP RUNNING PSCAN ISCAN'''<br />
RX bytes:20425 acl:115 sco:0 events:526 errors:0<br />
TX bytes:5543 acl:84 sco:0 commands:340 errors:0<br />
}}<br />
<br />
{{Note|Check DiscoverableTimeout and PairableTimeout in {{ic|/etc/bluetooth/main.conf}}}}<br />
<br />
Try changing device class in {{ic|/etc/bluetooth/main.conf}} as following:<br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100 (from default config)<br />
Class = 0x100100<br />
<br />
This was the only solution to make my computer visible for my phone. <br />
<br />
=== Nautilus cannot browse files ===<br />
<br />
If nautilus doesn't open and show this error:<br />
Nautilus cannot handle obex: locations. Couldn't display "obex://[XX:XX:XX:XX:XX:XX]/".<br />
Install {{Pkg|gvfs-obexftp}} package.<br />
<br />
=== Sennheiser MM400 Headset connection problems ===<br />
<br />
If your {{ic|Sennheiser MM400 Headset}} immediately disconnects after connecting as {{ic|Headset Service}} with Blueman, try to connect it as {{ic|Audio Sink}}. Afterwards you can change the headset's {{ic|Audio Profile}} to {{ic|Telephony Duplex}} with a right click in Blueman.<br />
With this option headset functionality will be available although the headset was only connected as {{ic|Audio Sink}} in first place and no disconnection will happen (tested with bluez 4.96-3, pulseaudio 1.1-1 and blueman 1.23-2).<br />
<br />
=== My device is paired but no sound is played from it ===<br />
<br />
Try to first inspect {{ic|/var/log/messages.log}}. If you see such messages:<br />
{{bc|<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Service not connected<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Bluetooth audio service not available<br />
}}<br />
try first:<br />
# pactl load-module module-bluetooth-device<br />
<br />
If the module fails to work, do this workaround:<br />
Open {{ic|/etc/bluetooth/audio.conf}} and add after '''[General]''' (on a new line)<br />
Enable=Socket<br />
Then restart the bluetooth daemon.<br />
Pair again your device, and you should find it in the pulseaudio settings (advanced settings for the sound)<br />
<br />
[http://wiki.gentoo.org/index.php?title=Bluetooth_Headset&redirect=no More information on Gentoo Wiki]<br />
<br />
If after fixing this you still can't get sound, try using blueman (this is the only one that works for me), make sure that notify-osd is installed or it might show you weird error messages like this one: "Stream setup failed"<br />
<br />
fail (/usr/lib/python2.7/site-packages/blueman/gui/manager/ManagerDeviceMenu.py:134)<br />
fail (DBusException(dbus.String(u'Stream setup failed'),),)<br />
<br />
== See also ==<br />
<br />
*[http://www.gentoo.org/doc/en/bluetooth-guide.xml Gentoo Linux Bluetooth guide]<br />
*[http://en.opensuse.org/HCL:Bluetooth openSUSE Bluetooth Hardware Compatibility List]<br />
*[http://linuxgazette.net/109/oregan3.html Accessing a Bluetooth phone (Linux Gazette)]<br />
*[http://www.adamish.com/blog/#a000361 Bluetooth computer visibility]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth for your mobile phone: Bluetooth pairing, data synchronization, photo download, Internet Dial-Up (tethering)]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth pairing and applications for synchronizing phone numbers, SMS-messages, phone call entries, your calendar and time; tethering]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth&diff=276248Bluetooth2013-09-21T18:56:18Z<p>Netskink: /* hciconfig */ Added pkg info to the text.</p>
<hr />
<div>[[Category:Bluetooth]]<br />
[[cs:Bluetooth]]<br />
[[de:Bluetooth]]<br />
[[es:Bluetooth]]<br />
[[fr:Bluetooth]]<br />
[[it:Bluetooth]]<br />
[[ru:Bluetooth]]<br />
[[zh-CN:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers the installation and use of Bluetooth on Arch Linux.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth mouse configuration}}<br />
{{Article summary end}}<br />
<br />
{{Out of date|Several generations of various deprecated tools are mentioned. bluez4 and bluez are confused. This article needs cleanup from someone who knows what commands belong in which packages.}}<br />
<br />
[http://www.bluetooth.org/ Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. In Linux, the canonical implementation of the Bluetooth protocol stack is [http://www.bluez.org/ BlueZ].<br />
<br />
== Installation ==<br />
<br />
To use Bluetooth, [[pacman|install]] {{Pkg|bluez}}, available in the [[official repositories]]. The {{ic|dbus}} daemon(start automatically by systemd) is used to read settings and for PIN pairing, while the {{ic|bluetooth}} daemon is required for the Bluetooth protocol.<br />
<br />
Start the bluetooth [[systemd]] service.<br />
<br />
Enable the ''bluetooth'' service to start it at system boot up.<br />
<br />
== Graphical front-ends ==<br />
<br />
The following packages allow for a graphical interface to customize Bluetooth.<br />
<br />
=== Blueman ===<br />
<br />
See [[Blueman]] article.<br />
<br />
=== GNOME Bluetooth ===<br />
<br />
[http://live.gnome.org/GnomeBluetooth GNOME Bluetooth] is a fork of the old ''bluez-gnome'' and is focused on integration with the [[GNOME]] desktop environment. GNOME Bluetooth is required by {{Pkg|gnome-shell}}, so you should already have it installed if you are running GNOME 3. Otherwise, it can be installed with the package {{Pkg|gnome-bluetooth}}. Note that gnome-shell, gnome-bluetooth <= 3.8 depend upon {{Pkg|bluez4}}. From gnome-shell 3.10 onwards, {{Pkg|bluez}} will be supported. More information regarding the GNOME migration to ''bluez'' can be found [http://worldofgnome.org/gnome-3-10-port-to-bluez-5/ here] (June 2013 blog post).<br />
<br />
Run {{ic|bluetooth-applet}} for a nice Bluetooth applet. You should now be able to setup devices and send files by right-clicking the Bluetooth icon. To make the applet run on login, add it to ''System > Preferences > Startup Applications''.<br />
<br />
To add a Bluetooth entry to the ''SendTo'' menu in Thunar's file properties menu, see instructions [http://thunar.xfce.org/pwiki/documentation/sendto_menu here].<br />
<br />
=== BlueDevil ===<br />
<br />
{{Note|As of 2013-09-01, ''bluedevil'' depends on the older {{Pkg|bluez4}}, which conflicts with the current {{Pkg|bluez}} (v5). Additionally, {{AUR|bluedevil-git}} is not updated to fix this dependency.}}<br />
<br />
The Bluetooth tool for [[KDE]] is [https://projects.kde.org/projects/extragear/base/bluedevil BlueDevil]. It can be installed with the package {{Pkg|bluedevil}}, available in the [[Official Repositories]].<br />
<br />
Make sure {{ic|bluetooth}} daemon is running, as described above. You should get a Bluetooth icon both in Dolphin and in the system tray, from which you can configure BlueDevil and detect Bluetooth devices by clicking the icon. You can also configure BlueDevil from the KDE System Settings<br />
<br />
=== Fluxbox, Openbox, other WM ===<br />
<br />
Of course you can still use the preceding applications even if GNOME, Xfce or KDE are not your desktop manager. This list should help you figuring out which application does what:<br />
* bluetooth-applet -- tray icon with access to settings, pairing wizard, management of known devices<br />
* /usr/lib/gnome-user-share/gnome-user-share -- needs to be running if you're about to receive files via obexBT from a paired/bonded device<br />
<br />
if you're receiving an error during transmission and/or there's no file received add this into<br />
<br />
{{ic|/etc/dbus-1/system.d/bluetooth.conf}}<br />
<policy user="your_user_id"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent"/><br />
</policy><br />
<br />
* bluetooth-wizard -- for new devices to be paired<br />
* bluetooth-properties -- accessible also via bluetooth-applet icon<br />
* gnome-file-share-properties -- permissions on receiving files via bluetooth<br />
* bluez-sendto -- gui for sending files to a remote device<br />
<br />
== Bluez Utils ==<br />
<br />
The package {{Pkg|bluez-utils}} contains various commands,<br />
which are useful to configure and troubleshoot Bluetooth<br />
from the command line.<br />
<br />
=== hciconfig ===<br />
<br />
Print name and basic information about all the Bluetooth devices installed in the system:<br />
$ hciconfig<br />
<br />
hciconfig is part of the {{Pkg|bluez-utils}} package.<br />
<br />
To activate a device, use:<br />
# hciconfig ''device-name'' up<br />
<br />
=== hcitool ===<br />
<br />
To scan for remote devices:<br />
$ hcitool scan<br />
<br />
== Pairing ==<br />
Many bluetooth devices require [http://en.wikipedia.org/wiki/Bluetooth#Pairing pairing].<br />
The exact procedure depends on the devices involved and their input functionality.<br />
<br />
=== With bluez5 ===<br />
<br />
Start the {{ic|bluetoothctl}} interactive command. There you can input {{ic|help}} to get a list of available commands. <br />
* Enter {{ic|devices}} to get the MAC Address of the device with which you want to pair.<br />
* Enter {{ic|pair ''MAC Address''}} to do the pairing.<br />
* Finally, use {{ic|connect ''MAC_address''}} to establish a connection.<br />
<br />
=== With bluez4 ===<br />
<br />
The procedure on a mobile may be as follows:<br />
* The computer sends a connect request to the mobile. <br />
* A pin, determined by the computer, is prompted for at the mobile<br />
* The same key must be re-entered at the computer.<br />
<br />
To pair with a device without using the gnome-bluez package, the ''bluez-simple-agent'' utility that comes with the bluez package can be used. This utility depends on three packages from the official repositories: {{Pkg|python2-dbus}} {{Pkg|python2-gobject}} {{Pkg|dbus-glib}}.<br />
<br />
First, scan for external devices:<br />
$ hcitool scan<br />
<br />
Run the script as root:<br />
<br />
# bluez-simple-agent<br />
<br />
The message "Agent registered" should be returned, press control-c to quit. <br />
<br />
Below is a basic example of pairing with a specific device. The script will ask for the passcode, enter the code and confirm with enter.<br />
<br />
# bluez-simple-agent hci0 00:11:22:33:AA:BB<br />
<br />
{{Note|bluez-simple-agent is only needed once for pairing a device, not every time you want to connect.}}<br />
<br />
See the Examples section below for pairing examples with various devices.<br />
<br />
== Using Obex for sending and receiving files ==<br />
<br />
Another option, rather than using KDE or Gnome Bluetooth packages, is Obexfs which allows you to mount your phone and treat it as part of your filesystem. Note that to use Obexfs, you need a device that provides an Obex FTP service.<br />
<br />
Install {{Pkg|obexfs}} and then your phone can then be mounted by running <br />
$ obexfs -b ''devices_MAC_address'' /mountpoint<br />
<br />
For more mounting options see http://dev.zuckschwerdt.org/openobex/wiki/ObexFs<br />
<br />
For devices don't support Obex FTP service, check if Obex Object Push is supported.<br />
<br />
# sdptool browse ''XX:XX:XX:XX:XX:XX''<br />
<br />
Read the output, look for Obex Object Push, remember the channel for this service. If supported, you can use ussp-push to send files to this device:<br />
<br />
# ussp-push ''XX:XX:XX:XX:XX:XX''@''CHANNEL'' ''file'' ''wanted_file_name_on_phone''<br />
<br />
== Examples ==<br />
<br />
=== Siemens S55 ===<br />
<br />
This is what I did to connect to my S55. (I have not figured out how to initiate the connection from the phone)<br />
* The steps under installation<br />
<br />
{{hc|$ hcitool scan|<br />
Scanning ...<br />
''XX:XX:XX:XX:XX:XX'' NAME<br />
}}<br />
$ B=''XX:XX:XX:XX:XX:XX''<br />
Start the simple-agent in a second terminal:<br />
{{hc|$ su -c bluez-simple-agent|<br />
Password: <br />
Agent registered<br />
}}<br />
Back to the first console:<br />
{{hc|$ obexftp -b $B -l "Address book"|<nowiki><br />
# Phone ask for pin, I enter it and answer yes when asked if I want to save the device<br />
...<br />
<file name="5F07.adr" size="78712" modified="20030101T001858" user-perm="WD" group-perm="" /><br />
...<br />
</nowiki>}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -g "Address book/5F07.adr"|<br />
Browsing 00:01:E3:6B:FF:D7 ...<br />
Channel: 5<br />
Connecting...done<br />
Receiving "Address book/5F07.adr"... Sending "Address book"... done<br />
Disconnecting...done<br />
}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -p a|<br />
...<br />
Sending "a"... done<br />
Disconnecting...done<br />
}}<br />
<br />
=== Logitech mouse MX Laser / M555b ===<br />
<br />
To quickly test the connection:<br />
<br />
$ hidd --connect ''XX:XX:XX:XX:XX:XX''<br />
<br />
For automated reconnection, use your desktop wizard to configure the bluetooth mouse.<br />
If your desktop environment doesn't includes support for this task, see the [[Bluetooth mouse manual configuration]] guide.<br />
<br />
=== Motorola V900 ===<br />
<br />
After installing blueman and running blueman-applet, click "find me" under connections > bluetooth in Motorla device. In blueman-applet, scan devices, find the motorola, click "add" in blueman-applet. Click "bond" in blueman-applet, enter some pin, enter the same pin in motorola when it asks. In terminal:<br />
<br />
{{bc|<br />
$ mkdir ~/bluetooth-temp<br />
$ obexfs -n ''XX:XX:XX:XX:XX:XX'' ~/bluetooth-temp<br />
$ cd ~/bluetooth-temp<br />
}}<br />
<br />
and browse... Only audio, video, and pictures are available when you do this.<br />
<br />
=== Motorola RAZ ===<br />
<br />
Install {{Pkg|obextool}} {{Pkg|obexfs}} {{Pkg|obexftp}} {{Pkg|openobex}} {{Pkg|bluez}}.<br />
<br />
{{hc|# lsusb|<br />
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 002 Device 002: ID 03f0:171d Hewlett-Packard Wireless (Bluetooth + WLAN) Interface [Integrated Module]<br />
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|# hciconfig|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
{{hc|# hcitool dev|<br />
Devices:<br />
hci0 00:16:41:97:BA:5E<br />
}}<br />
<br />
Make sure that bluetooth on your phone is enabled and your phone is visible!<br />
<br />
{{hc|# hcitool scan|<br />
Scanning ...<br />
00:1A:1B:82:9B:6D [quirxi]<br />
}}<br />
<br />
{{hc|# hcitool inq|<br />
Inquiring ...<br />
00:1A:1B:82:9B:6D clock offset: 0x1ee4 class: 0x522204<br />
}}<br />
<br />
{{hc|# l2ping 00:1A:1B:82:9B:6D|<br />
Ping: 00:1A:1B:82:9B:6D from 00:16:41:97:BA:5E (data size 44) ...<br />
44 bytes from 00:1A:1B:82:9B:6D id 0 time 23.94ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 1 time 18.85ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 2 time 30.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 3 time 18.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 4 time 17.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 5 time 17.88ms<br />
6 sent, 6 received, 0% loss<br />
}}<br />
<br />
{{hc|# hcitool name 00:1A:1B:82:9B:6D|<br />
[quirxi]<br />
}}<br />
<br />
{{hc|# hciconfig -a hci0|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:9740 acl:122 sco:0 events:170 errors:0<br />
TX bytes:2920 acl:125 sco:0 commands:53 errors:0<br />
Features: 0xff 0xff 0x8d 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3<br />
Link policy:<br />
Link mode: SLAVE ACCEPT<br />
Name: 'BCM2045'<br />
Class: 0x000000<br />
Service Classes: Unspecified<br />
Device Class: Miscellaneous,<br />
HCI Version: 2.0 (0x3) Revision: 0x204a<br />
LMP Version: 2.0 (0x3) Subversion: 0x4176<br />
Manufacturer: Broadcoml / Corporation (15)<br />
}}<br />
<br />
{{hc|# hcitool info 00:1A:1B:82:9B:6D|<br />
Requesting information ...<br />
BD Address: 00:1A:1B:82:9B:6D<br />
Device Name: [quirxi]<br />
LMP Version: 1.2 (0x2) LMP Subversion: 0x309<br />
Manufacturer: Broadcom Corporation (15)<br />
Features: 0xff 0xfe 0x0d 0x00 0x08 0x08 0x00 0x00<br />
<3-slot packets> <5-slot packets> <encryption> <slot offset><br />
<timing accuracy> <role switch> <hold mode> <sniff mode><br />
<RSSI> <channel quality> <SCO link> <HV2 packets><br />
<HV3 packets> <A-law log> <CVSD> <power control><br />
<transparent SCO> <AFH cap. slave> <AFH cap. master><br />
}}<br />
<br />
Edit your {{ic|/etc/bluetooth/main.conf}} and enter the proper class for your phone ( Class = 0x100100 ):<br />
{{bc|<nowiki><br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100<br />
Class = 0x100100<br />
</nowiki>}}<br />
<br />
{{hc|# systemctl start bluetooth|<br />
:: Stopping bluetooth subsystem: pand dund rfcomm hidd bluetoothd<br />
[DONE]<br />
:: Starting bluetooth subsystem: bluetoothd<br />
}}<br />
<br />
Pairing with bluez-simple-agent only has to be done once. On your Motorola phone give 0000 in as your PIN when phone asks for it!<br />
{{hc|/usr/bin/bluez-simple-agent hci0 00:1A:1B:82:9B:6D|<br />
RequestPinCode (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
Enter PIN Code: 0000<br />
Release<br />
New device (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
}}<br />
<br />
Now you can browse the filesystem of your phone with obexftp:<br />
{{hc|obexftp -v -b 00:1A:1B:82:9B:6D -B 9 -l|<nowiki><br />
Connecting..\done<br />
Tried to connect for 448ms<br />
Receiving "(null)"...-<?xml version="1.0" ?><br />
<!DOCTYPE folder-listing SYSTEM "obex-folder-listing.dtd"><br />
<folder-listing><br />
<parent-folder /><br />
<folder name="audio" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="video" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="picture" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
</folder-listing><br />
done<br />
Disconnecting..\done<br />
</nowiki>}}<br />
<br />
Or you can mount your phone into a directory on your computer and treat it like a normal file system:<br />
{{bc|<br />
# groupadd bluetooth<br />
# mkdir /mnt/bluetooth<br />
# chown root:bluetooth /mnt/bluetooth<br />
# chmod 775 /mnt/bluetooth<br />
# usermod -a -G bluetooth arno<br />
# obexfs -b 00:1A:1B:82:9B:6D /mnt/bluetooth/<br />
}}<br />
<br />
=== Pairing with an iPhone using bluez-simple-agent ===<br />
<br />
Assuming a bluetooth device called hci0 and an iPhone that showed up in a hcitool scan as '00:00:DE:AD:BE:EF':<br />
<br />
# bluez-simple-agent hci0 00:00:DE:AD:BE:EF<br />
Passcode:<br />
<br />
=== Headset and ALSA devices ===<br />
<br />
==== by referencing the bluetooth device in asound.conf ====<br />
<br />
1. Scan for your device:<br />
$ hcitool (-i ''optional hci#''***) scan<br />
2. 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 />
3. Add this to your {{ic|/etc/asound.conf}} file:<br />
<br />
{{bc|<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 />
<br />
4. Check to see if it has been added to ALSA devices<br />
$ aplay -L<br />
<br />
5. 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 />
To find hci# for a usb dongle, type in:<br />
$ hcitool dev<br />
<br />
==== by using bluez-tools from the AUR ====<br />
<br />
You can use {{AUR|bluez-tools}} from the [[AUR]] with PulseAudio to stream audio to a bluetooth headset.<br />
Find the MAC of the headset:<br />
$ hcitool scan<br />
Connect to the headset:<br />
$ bt-audio -c XX:XX:XX:XX:XX:XX<br />
Open pulseaudio volume control:<br />
$ pavucontrol<br />
The headset should show up in the Configuration tab.<br />
<br />
=== Microsoft Bluetooth Mobile Keyboard 6000 ===<br />
<br />
1. Scan for your device<br />
$ hcitool (-i ''optional_hci#''***) scan<br />
Scanning ...<br />
00:11:22:33:44:55 Microsoft Bluetooth Mobile Keyboard 6000<br />
<br />
2. On second console run as root (do not terminate):<br />
# bluez-simple-agent<br />
Agent registered<br />
<br />
3. Back on first console run:<br />
$ bluez-simple-agent hci0 00:11:22:33:44:55<br />
Enter PIN Code: 1234<br />
(now enter that PIN on the keyboard and press enter)<br />
Release<br />
New device (/org/bluez/5373/hci0/dev_00_11_22_33_44_55)<br />
<br />
4.<br />
$ bluez-test-device trusted 00:11:22:33:44:55<br />
<br />
5.<br />
$ bluez-test-input connect 00:11:22:33:44:55<br />
<br />
No your keyboard should work. You can terminate bluez-simple-agent on second console with {{ic|Ctrl+C}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== passkey-agent ===<br />
<br />
$ passkey-agent --default 1234<br />
Can't register passkey agent<br />
The name org.bluez was not provided by any .service files<br />
and<br />
$ hciconfig dev<br />
# (no listing)<br />
Try running {{ic|hciconfig hc0 up}}<br />
<br />
=== gnome-bluetooth ===<br />
<br />
If you see this when trying to enable receiving files in bluetooth-properties:<br />
Bluetooth OBEX start failed: Invalid path<br />
Bluetooth FTP start failed: Invalid path<br />
Then install {{Pkg|xdg-user-dirs}} and issue:<br />
$ xdg-user-dirs-update<br />
You can edit the paths using:<br />
$ vi ~/.config/user-dirs.dirs<br />
<br />
=== Bluetooth USB Dongle ===<br />
<br />
If you are using a USB dongle, you should check that your Bluetooth dongle is recognized. You can do that by inspecting {{ic|/var/log/messages.log}} when plugging in the USB dongle (or running {{ic|journalctl -f}} with systemd). It should look something like the following (look out for hci):<br />
<br />
{{bc|<br />
Feb 20 15:00:24 hostname kernel: [ 2661.349823] usb 4-1: new full-speed USB device number 3 using uhci_hcd<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: HCI dev 0 registered<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: Listening for HCI events on hci0<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: HCI dev 0 up<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: Adapter /org/bluez/4568/hci0 has been enabled<br />
}}<br />
<br />
For a list of supported hardware please refer to the [[#Resources|Resource]] section on this page.<br />
<br />
If you only get the first two lines, you may see that it found the device but you need to bring it up.<br />
Example:<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:00:00:00:00:00 ACL MTU: 0:0 SCO MTU: 0:0<br />
DOWN <br />
RX bytes:0 acl:0 sco:0 events:0 errors:0<br />
TX bytes:0 acl:0 sco:0 commands:0 errors:<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:02:72:C4:7C:06 ACL MTU: 377:10 SCO MTU: 64:8<br />
UP RUNNING <br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
If this fails with an error like:<br />
Operation not possible due to RF-kill<br />
it could be due either to the {{ic|rfkill}} utility, in which case it should be resolved with<br />
# rfkill unblock all<br />
or, it could simply be the hardware switch of the computer. The hardware bluetooth switch (at least sometimes) controls access to USB bluetooth dongles also. Flip/press this switch and try bringing the device up again.<br />
<br />
To verify that the device was detected you can use {{ic|hcitool}} which is part of the {{ic|bluez-utils}}. You can get a list of available devices and their identifiers and their MAC address by issuing:<br />
<br />
{{hc|$ hcitool dev|<br />
Devices:<br />
hci0 00:1B:DC:0F:DB:40<br />
}}<br />
<br />
More detailed informations about the device can be retrieved by using {{ic|hciconfig}}.<br />
<br />
{{hc|$ hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:1B:DC:0F:DB:40 ACL MTU: 310:10 SCO MTU: 64:8<br />
UP RUNNING PSCAN ISCAN <br />
RX bytes:1226 acl:0 sco:0 events:27 errors:0<br />
TX bytes:351 acl:0 sco:0 commands:26 errors:0<br />
Features: 0xff 0xff 0x8f 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3 <br />
Link policy: RSWITCH HOLD SNIFF PARK <br />
Link mode: SLAVE ACCEPT <br />
Name: 'BlueZ (0)'<br />
Class: 0x000100<br />
Service Classes: Unspecified<br />
Device Class: Computer, Uncategorized<br />
HCI Ver: 2.0 (0x3) HCI Rev: 0xc5c LMP Ver: 2.0 (0x3) LMP Subver: 0xc5c<br />
Manufacturer: Cambridge Silicon Radio (10)<br />
}}<br />
<br />
=== Logitech Bluetooth USB Dongle ===<br />
<br />
There are Logitech dongles (ex. Logitech MX5000) that can work in two modes Embedded and HCI. In embedded mode dongle emulates a USB device so it seems to your PC that your using a normal USB mouse/keyoard.<br />
<br />
If you hold the little red Button on the USB BT mini-receiver it will enable the other mode. Hold the red button on the BT dongle and plug it into the computer, and after 3-5 seconds of holding the button, the Bluetooth icon will appear in the system tray. [http://ubuntuforums.org/showthread.php?t=1332197 Discussion]<br />
<br />
=== hcitool scan: Device not found ===<br />
<br />
* On some Dell laptops (e.g. Studio 15) you have to switch the Bluetooth mode from HID to HCI using<br />
# hid2hci<br />
<br />
{{Note|hid2hci is no longer in the $PATH, it is under /lib/udev/hid2hci, but udev should run it automatically for you.}}<br />
<br />
* If the device won't show up and you have a Windows operating system on your machine, try booting it and enable the bluetooth adapter from windows.<br />
<br />
* Sometimes also this simple command helps:<br />
# hciconfig hci0 up<br />
<br />
=== rfkill unblock: Do not unblock ===<br />
<br />
If your device still soft blocked and you run connman.<br />
<br />
Try this:<br />
$ connmanctl enable bluetooth<br />
<br />
=== My computer is not visible ===<br />
<br />
Can't discover computer from your phone? Enable PSCAN and ISCAN:<br />
# enable PSCAN and ISCAN<br />
$ hciconfig hci0 piscan <br />
# check it worked<br />
{{hc|$ hciconfig|<br />
hci0: Type: USB<br />
BD Address: 00:12:34:56:78:9A ACL MTU: 192:8 SCO MTU: 64:8<br />
'''UP RUNNING PSCAN ISCAN'''<br />
RX bytes:20425 acl:115 sco:0 events:526 errors:0<br />
TX bytes:5543 acl:84 sco:0 commands:340 errors:0<br />
}}<br />
<br />
{{Note|Check DiscoverableTimeout and PairableTimeout in {{ic|/etc/bluetooth/main.conf}}}}<br />
<br />
Try changing device class in {{ic|/etc/bluetooth/main.conf}} as following:<br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100 (from default config)<br />
Class = 0x100100<br />
<br />
This was the only solution to make my computer visible for my phone. <br />
<br />
=== Nautilus cannot browse files ===<br />
<br />
If nautilus doesn't open and show this error:<br />
Nautilus cannot handle obex: locations. Couldn't display "obex://[XX:XX:XX:XX:XX:XX]/".<br />
Install {{Pkg|gvfs-obexftp}} package.<br />
<br />
=== Sennheiser MM400 Headset connection problems ===<br />
<br />
If your {{ic|Sennheiser MM400 Headset}} immediately disconnects after connecting as {{ic|Headset Service}} with Blueman, try to connect it as {{ic|Audio Sink}}. Afterwards you can change the headset's {{ic|Audio Profile}} to {{ic|Telephony Duplex}} with a right click in Blueman.<br />
With this option headset functionality will be available although the headset was only connected as {{ic|Audio Sink}} in first place and no disconnection will happen (tested with bluez 4.96-3, pulseaudio 1.1-1 and blueman 1.23-2).<br />
<br />
=== My device is paired but no sound is played from it ===<br />
<br />
Try to first inspect {{ic|/var/log/messages.log}}. If you see such messages:<br />
{{bc|<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Service not connected<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Bluetooth audio service not available<br />
}}<br />
try first:<br />
# pactl load-module module-bluetooth-device<br />
<br />
If the module fails to work, do this workaround:<br />
Open {{ic|/etc/bluetooth/audio.conf}} and add after '''[General]''' (on a new line)<br />
Enable=Socket<br />
Then restart the bluetooth daemon.<br />
Pair again your device, and you should find it in the pulseaudio settings (advanced settings for the sound)<br />
<br />
[http://wiki.gentoo.org/index.php?title=Bluetooth_Headset&redirect=no More information on Gentoo Wiki]<br />
<br />
If after fixing this you still can't get sound, try using blueman (this is the only one that works for me), make sure that notify-osd is installed or it might show you weird error messages like this one: "Stream setup failed"<br />
<br />
fail (/usr/lib/python2.7/site-packages/blueman/gui/manager/ManagerDeviceMenu.py:134)<br />
fail (DBusException(dbus.String(u'Stream setup failed'),),)<br />
<br />
== See also ==<br />
<br />
*[http://www.gentoo.org/doc/en/bluetooth-guide.xml Gentoo Linux Bluetooth guide]<br />
*[http://en.opensuse.org/HCL:Bluetooth openSUSE Bluetooth Hardware Compatibility List]<br />
*[http://linuxgazette.net/109/oregan3.html Accessing a Bluetooth phone (Linux Gazette)]<br />
*[http://www.adamish.com/blog/#a000361 Bluetooth computer visibility]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth for your mobile phone: Bluetooth pairing, data synchronization, photo download, Internet Dial-Up (tethering)]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth pairing and applications for synchronizing phone numbers, SMS-messages, phone call entries, your calendar and time; tethering]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Bluetooth&diff=276247Bluetooth2013-09-21T18:55:17Z<p>Netskink: /* hciconfig */ Added note for where to find hciconfig since it was not obvious.</p>
<hr />
<div>[[Category:Bluetooth]]<br />
[[cs:Bluetooth]]<br />
[[de:Bluetooth]]<br />
[[es:Bluetooth]]<br />
[[fr:Bluetooth]]<br />
[[it:Bluetooth]]<br />
[[ru:Bluetooth]]<br />
[[zh-CN:Bluetooth]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers the installation and use of Bluetooth on Arch Linux.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Bluetooth mouse configuration}}<br />
{{Article summary end}}<br />
<br />
{{Out of date|Several generations of various deprecated tools are mentioned. bluez4 and bluez are confused. This article needs cleanup from someone who knows what commands belong in which packages.}}<br />
<br />
[http://www.bluetooth.org/ Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. In Linux, the canonical implementation of the Bluetooth protocol stack is [http://www.bluez.org/ BlueZ].<br />
<br />
== Installation ==<br />
<br />
To use Bluetooth, [[pacman|install]] {{Pkg|bluez}}, available in the [[official repositories]]. The {{ic|dbus}} daemon(start automatically by systemd) is used to read settings and for PIN pairing, while the {{ic|bluetooth}} daemon is required for the Bluetooth protocol.<br />
<br />
Start the bluetooth [[systemd]] service.<br />
<br />
Enable the ''bluetooth'' service to start it at system boot up.<br />
<br />
== Graphical front-ends ==<br />
<br />
The following packages allow for a graphical interface to customize Bluetooth.<br />
<br />
=== Blueman ===<br />
<br />
See [[Blueman]] article.<br />
<br />
=== GNOME Bluetooth ===<br />
<br />
[http://live.gnome.org/GnomeBluetooth GNOME Bluetooth] is a fork of the old ''bluez-gnome'' and is focused on integration with the [[GNOME]] desktop environment. GNOME Bluetooth is required by {{Pkg|gnome-shell}}, so you should already have it installed if you are running GNOME 3. Otherwise, it can be installed with the package {{Pkg|gnome-bluetooth}}. Note that gnome-shell, gnome-bluetooth <= 3.8 depend upon {{Pkg|bluez4}}. From gnome-shell 3.10 onwards, {{Pkg|bluez}} will be supported. More information regarding the GNOME migration to ''bluez'' can be found [http://worldofgnome.org/gnome-3-10-port-to-bluez-5/ here] (June 2013 blog post).<br />
<br />
Run {{ic|bluetooth-applet}} for a nice Bluetooth applet. You should now be able to setup devices and send files by right-clicking the Bluetooth icon. To make the applet run on login, add it to ''System > Preferences > Startup Applications''.<br />
<br />
To add a Bluetooth entry to the ''SendTo'' menu in Thunar's file properties menu, see instructions [http://thunar.xfce.org/pwiki/documentation/sendto_menu here].<br />
<br />
=== BlueDevil ===<br />
<br />
{{Note|As of 2013-09-01, ''bluedevil'' depends on the older {{Pkg|bluez4}}, which conflicts with the current {{Pkg|bluez}} (v5). Additionally, {{AUR|bluedevil-git}} is not updated to fix this dependency.}}<br />
<br />
The Bluetooth tool for [[KDE]] is [https://projects.kde.org/projects/extragear/base/bluedevil BlueDevil]. It can be installed with the package {{Pkg|bluedevil}}, available in the [[Official Repositories]].<br />
<br />
Make sure {{ic|bluetooth}} daemon is running, as described above. You should get a Bluetooth icon both in Dolphin and in the system tray, from which you can configure BlueDevil and detect Bluetooth devices by clicking the icon. You can also configure BlueDevil from the KDE System Settings<br />
<br />
=== Fluxbox, Openbox, other WM ===<br />
<br />
Of course you can still use the preceding applications even if GNOME, Xfce or KDE are not your desktop manager. This list should help you figuring out which application does what:<br />
* bluetooth-applet -- tray icon with access to settings, pairing wizard, management of known devices<br />
* /usr/lib/gnome-user-share/gnome-user-share -- needs to be running if you're about to receive files via obexBT from a paired/bonded device<br />
<br />
if you're receiving an error during transmission and/or there's no file received add this into<br />
<br />
{{ic|/etc/dbus-1/system.d/bluetooth.conf}}<br />
<policy user="your_user_id"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent"/><br />
</policy><br />
<br />
* bluetooth-wizard -- for new devices to be paired<br />
* bluetooth-properties -- accessible also via bluetooth-applet icon<br />
* gnome-file-share-properties -- permissions on receiving files via bluetooth<br />
* bluez-sendto -- gui for sending files to a remote device<br />
<br />
== Bluez Utils ==<br />
<br />
The package {{Pkg|bluez-utils}} contains various commands,<br />
which are useful to configure and troubleshoot Bluetooth<br />
from the command line.<br />
<br />
=== hciconfig ===<br />
<br />
Print name and basic information about all the Bluetooth devices installed in the system:<br />
$ hciconfig<br />
<br />
hciconfig is part of the bluez-utils package.<br />
<br />
To activate a device, use:<br />
# hciconfig ''device-name'' up<br />
<br />
=== hcitool ===<br />
<br />
To scan for remote devices:<br />
$ hcitool scan<br />
<br />
== Pairing ==<br />
Many bluetooth devices require [http://en.wikipedia.org/wiki/Bluetooth#Pairing pairing].<br />
The exact procedure depends on the devices involved and their input functionality.<br />
<br />
=== With bluez5 ===<br />
<br />
Start the {{ic|bluetoothctl}} interactive command. There you can input {{ic|help}} to get a list of available commands. <br />
* Enter {{ic|devices}} to get the MAC Address of the device with which you want to pair.<br />
* Enter {{ic|pair ''MAC Address''}} to do the pairing.<br />
* Finally, use {{ic|connect ''MAC_address''}} to establish a connection.<br />
<br />
=== With bluez4 ===<br />
<br />
The procedure on a mobile may be as follows:<br />
* The computer sends a connect request to the mobile. <br />
* A pin, determined by the computer, is prompted for at the mobile<br />
* The same key must be re-entered at the computer.<br />
<br />
To pair with a device without using the gnome-bluez package, the ''bluez-simple-agent'' utility that comes with the bluez package can be used. This utility depends on three packages from the official repositories: {{Pkg|python2-dbus}} {{Pkg|python2-gobject}} {{Pkg|dbus-glib}}.<br />
<br />
First, scan for external devices:<br />
$ hcitool scan<br />
<br />
Run the script as root:<br />
<br />
# bluez-simple-agent<br />
<br />
The message "Agent registered" should be returned, press control-c to quit. <br />
<br />
Below is a basic example of pairing with a specific device. The script will ask for the passcode, enter the code and confirm with enter.<br />
<br />
# bluez-simple-agent hci0 00:11:22:33:AA:BB<br />
<br />
{{Note|bluez-simple-agent is only needed once for pairing a device, not every time you want to connect.}}<br />
<br />
See the Examples section below for pairing examples with various devices.<br />
<br />
== Using Obex for sending and receiving files ==<br />
<br />
Another option, rather than using KDE or Gnome Bluetooth packages, is Obexfs which allows you to mount your phone and treat it as part of your filesystem. Note that to use Obexfs, you need a device that provides an Obex FTP service.<br />
<br />
Install {{Pkg|obexfs}} and then your phone can then be mounted by running <br />
$ obexfs -b ''devices_MAC_address'' /mountpoint<br />
<br />
For more mounting options see http://dev.zuckschwerdt.org/openobex/wiki/ObexFs<br />
<br />
For devices don't support Obex FTP service, check if Obex Object Push is supported.<br />
<br />
# sdptool browse ''XX:XX:XX:XX:XX:XX''<br />
<br />
Read the output, look for Obex Object Push, remember the channel for this service. If supported, you can use ussp-push to send files to this device:<br />
<br />
# ussp-push ''XX:XX:XX:XX:XX:XX''@''CHANNEL'' ''file'' ''wanted_file_name_on_phone''<br />
<br />
== Examples ==<br />
<br />
=== Siemens S55 ===<br />
<br />
This is what I did to connect to my S55. (I have not figured out how to initiate the connection from the phone)<br />
* The steps under installation<br />
<br />
{{hc|$ hcitool scan|<br />
Scanning ...<br />
''XX:XX:XX:XX:XX:XX'' NAME<br />
}}<br />
$ B=''XX:XX:XX:XX:XX:XX''<br />
Start the simple-agent in a second terminal:<br />
{{hc|$ su -c bluez-simple-agent|<br />
Password: <br />
Agent registered<br />
}}<br />
Back to the first console:<br />
{{hc|$ obexftp -b $B -l "Address book"|<nowiki><br />
# Phone ask for pin, I enter it and answer yes when asked if I want to save the device<br />
...<br />
<file name="5F07.adr" size="78712" modified="20030101T001858" user-perm="WD" group-perm="" /><br />
...<br />
</nowiki>}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -g "Address book/5F07.adr"|<br />
Browsing 00:01:E3:6B:FF:D7 ...<br />
Channel: 5<br />
Connecting...done<br />
Receiving "Address book/5F07.adr"... Sending "Address book"... done<br />
Disconnecting...done<br />
}}<br />
{{hc|$ obexftp -b 00:01:E3:6B:FF:D7 -p a|<br />
...<br />
Sending "a"... done<br />
Disconnecting...done<br />
}}<br />
<br />
=== Logitech mouse MX Laser / M555b ===<br />
<br />
To quickly test the connection:<br />
<br />
$ hidd --connect ''XX:XX:XX:XX:XX:XX''<br />
<br />
For automated reconnection, use your desktop wizard to configure the bluetooth mouse.<br />
If your desktop environment doesn't includes support for this task, see the [[Bluetooth mouse manual configuration]] guide.<br />
<br />
=== Motorola V900 ===<br />
<br />
After installing blueman and running blueman-applet, click "find me" under connections > bluetooth in Motorla device. In blueman-applet, scan devices, find the motorola, click "add" in blueman-applet. Click "bond" in blueman-applet, enter some pin, enter the same pin in motorola when it asks. In terminal:<br />
<br />
{{bc|<br />
$ mkdir ~/bluetooth-temp<br />
$ obexfs -n ''XX:XX:XX:XX:XX:XX'' ~/bluetooth-temp<br />
$ cd ~/bluetooth-temp<br />
}}<br />
<br />
and browse... Only audio, video, and pictures are available when you do this.<br />
<br />
=== Motorola RAZ ===<br />
<br />
Install {{Pkg|obextool}} {{Pkg|obexfs}} {{Pkg|obexftp}} {{Pkg|openobex}} {{Pkg|bluez}}.<br />
<br />
{{hc|# lsusb|<br />
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 002 Device 002: ID 03f0:171d Hewlett-Packard Wireless (Bluetooth + WLAN) Interface [Integrated Module]<br />
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub<br />
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|# hciconfig|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
{{hc|# hcitool dev|<br />
Devices:<br />
hci0 00:16:41:97:BA:5E<br />
}}<br />
<br />
Make sure that bluetooth on your phone is enabled and your phone is visible!<br />
<br />
{{hc|# hcitool scan|<br />
Scanning ...<br />
00:1A:1B:82:9B:6D [quirxi]<br />
}}<br />
<br />
{{hc|# hcitool inq|<br />
Inquiring ...<br />
00:1A:1B:82:9B:6D clock offset: 0x1ee4 class: 0x522204<br />
}}<br />
<br />
{{hc|# l2ping 00:1A:1B:82:9B:6D|<br />
Ping: 00:1A:1B:82:9B:6D from 00:16:41:97:BA:5E (data size 44) ...<br />
44 bytes from 00:1A:1B:82:9B:6D id 0 time 23.94ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 1 time 18.85ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 2 time 30.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 3 time 18.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 4 time 17.88ms<br />
44 bytes from 00:1A:1B:82:9B:6D id 5 time 17.88ms<br />
6 sent, 6 received, 0% loss<br />
}}<br />
<br />
{{hc|# hcitool name 00:1A:1B:82:9B:6D|<br />
[quirxi]<br />
}}<br />
<br />
{{hc|# hciconfig -a hci0|<br />
hci0: Type: BR/EDR Bus: USB<br />
BD Address: 00:16:41:97:BA:5E ACL MTU: 1017:8 SCO MTU: 64:8<br />
UP RUNNING<br />
RX bytes:9740 acl:122 sco:0 events:170 errors:0<br />
TX bytes:2920 acl:125 sco:0 commands:53 errors:0<br />
Features: 0xff 0xff 0x8d 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3<br />
Link policy:<br />
Link mode: SLAVE ACCEPT<br />
Name: 'BCM2045'<br />
Class: 0x000000<br />
Service Classes: Unspecified<br />
Device Class: Miscellaneous,<br />
HCI Version: 2.0 (0x3) Revision: 0x204a<br />
LMP Version: 2.0 (0x3) Subversion: 0x4176<br />
Manufacturer: Broadcoml / Corporation (15)<br />
}}<br />
<br />
{{hc|# hcitool info 00:1A:1B:82:9B:6D|<br />
Requesting information ...<br />
BD Address: 00:1A:1B:82:9B:6D<br />
Device Name: [quirxi]<br />
LMP Version: 1.2 (0x2) LMP Subversion: 0x309<br />
Manufacturer: Broadcom Corporation (15)<br />
Features: 0xff 0xfe 0x0d 0x00 0x08 0x08 0x00 0x00<br />
<3-slot packets> <5-slot packets> <encryption> <slot offset><br />
<timing accuracy> <role switch> <hold mode> <sniff mode><br />
<RSSI> <channel quality> <SCO link> <HV2 packets><br />
<HV3 packets> <A-law log> <CVSD> <power control><br />
<transparent SCO> <AFH cap. slave> <AFH cap. master><br />
}}<br />
<br />
Edit your {{ic|/etc/bluetooth/main.conf}} and enter the proper class for your phone ( Class = 0x100100 ):<br />
{{bc|<nowiki><br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100<br />
Class = 0x100100<br />
</nowiki>}}<br />
<br />
{{hc|# systemctl start bluetooth|<br />
:: Stopping bluetooth subsystem: pand dund rfcomm hidd bluetoothd<br />
[DONE]<br />
:: Starting bluetooth subsystem: bluetoothd<br />
}}<br />
<br />
Pairing with bluez-simple-agent only has to be done once. On your Motorola phone give 0000 in as your PIN when phone asks for it!<br />
{{hc|/usr/bin/bluez-simple-agent hci0 00:1A:1B:82:9B:6D|<br />
RequestPinCode (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
Enter PIN Code: 0000<br />
Release<br />
New device (/org/bluez/10768/hci0/dev_00_1A_1B_82_9B_6D)<br />
}}<br />
<br />
Now you can browse the filesystem of your phone with obexftp:<br />
{{hc|obexftp -v -b 00:1A:1B:82:9B:6D -B 9 -l|<nowiki><br />
Connecting..\done<br />
Tried to connect for 448ms<br />
Receiving "(null)"...-<?xml version="1.0" ?><br />
<!DOCTYPE folder-listing SYSTEM "obex-folder-listing.dtd"><br />
<folder-listing><br />
<parent-folder /><br />
<folder name="audio" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="video" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
<folder name="picture" size="0" type="folder" modified="20101010T132323Z" user-perm="RW" /><br />
</folder-listing><br />
done<br />
Disconnecting..\done<br />
</nowiki>}}<br />
<br />
Or you can mount your phone into a directory on your computer and treat it like a normal file system:<br />
{{bc|<br />
# groupadd bluetooth<br />
# mkdir /mnt/bluetooth<br />
# chown root:bluetooth /mnt/bluetooth<br />
# chmod 775 /mnt/bluetooth<br />
# usermod -a -G bluetooth arno<br />
# obexfs -b 00:1A:1B:82:9B:6D /mnt/bluetooth/<br />
}}<br />
<br />
=== Pairing with an iPhone using bluez-simple-agent ===<br />
<br />
Assuming a bluetooth device called hci0 and an iPhone that showed up in a hcitool scan as '00:00:DE:AD:BE:EF':<br />
<br />
# bluez-simple-agent hci0 00:00:DE:AD:BE:EF<br />
Passcode:<br />
<br />
=== Headset and ALSA devices ===<br />
<br />
==== by referencing the bluetooth device in asound.conf ====<br />
<br />
1. Scan for your device:<br />
$ hcitool (-i ''optional hci#''***) scan<br />
2. 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 />
3. Add this to your {{ic|/etc/asound.conf}} file:<br />
<br />
{{bc|<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 />
<br />
4. Check to see if it has been added to ALSA devices<br />
$ aplay -L<br />
<br />
5. 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 />
To find hci# for a usb dongle, type in:<br />
$ hcitool dev<br />
<br />
==== by using bluez-tools from the AUR ====<br />
<br />
You can use {{AUR|bluez-tools}} from the [[AUR]] with PulseAudio to stream audio to a bluetooth headset.<br />
Find the MAC of the headset:<br />
$ hcitool scan<br />
Connect to the headset:<br />
$ bt-audio -c XX:XX:XX:XX:XX:XX<br />
Open pulseaudio volume control:<br />
$ pavucontrol<br />
The headset should show up in the Configuration tab.<br />
<br />
=== Microsoft Bluetooth Mobile Keyboard 6000 ===<br />
<br />
1. Scan for your device<br />
$ hcitool (-i ''optional_hci#''***) scan<br />
Scanning ...<br />
00:11:22:33:44:55 Microsoft Bluetooth Mobile Keyboard 6000<br />
<br />
2. On second console run as root (do not terminate):<br />
# bluez-simple-agent<br />
Agent registered<br />
<br />
3. Back on first console run:<br />
$ bluez-simple-agent hci0 00:11:22:33:44:55<br />
Enter PIN Code: 1234<br />
(now enter that PIN on the keyboard and press enter)<br />
Release<br />
New device (/org/bluez/5373/hci0/dev_00_11_22_33_44_55)<br />
<br />
4.<br />
$ bluez-test-device trusted 00:11:22:33:44:55<br />
<br />
5.<br />
$ bluez-test-input connect 00:11:22:33:44:55<br />
<br />
No your keyboard should work. You can terminate bluez-simple-agent on second console with {{ic|Ctrl+C}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== passkey-agent ===<br />
<br />
$ passkey-agent --default 1234<br />
Can't register passkey agent<br />
The name org.bluez was not provided by any .service files<br />
and<br />
$ hciconfig dev<br />
# (no listing)<br />
Try running {{ic|hciconfig hc0 up}}<br />
<br />
=== gnome-bluetooth ===<br />
<br />
If you see this when trying to enable receiving files in bluetooth-properties:<br />
Bluetooth OBEX start failed: Invalid path<br />
Bluetooth FTP start failed: Invalid path<br />
Then install {{Pkg|xdg-user-dirs}} and issue:<br />
$ xdg-user-dirs-update<br />
You can edit the paths using:<br />
$ vi ~/.config/user-dirs.dirs<br />
<br />
=== Bluetooth USB Dongle ===<br />
<br />
If you are using a USB dongle, you should check that your Bluetooth dongle is recognized. You can do that by inspecting {{ic|/var/log/messages.log}} when plugging in the USB dongle (or running {{ic|journalctl -f}} with systemd). It should look something like the following (look out for hci):<br />
<br />
{{bc|<br />
Feb 20 15:00:24 hostname kernel: [ 2661.349823] usb 4-1: new full-speed USB device number 3 using uhci_hcd<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: HCI dev 0 registered<br />
Feb 20 15:00:24 hostname bluetoothd[4568]: Listening for HCI events on hci0<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: HCI dev 0 up<br />
Feb 20 15:00:25 hostname bluetoothd[4568]: Adapter /org/bluez/4568/hci0 has been enabled<br />
}}<br />
<br />
For a list of supported hardware please refer to the [[#Resources|Resource]] section on this page.<br />
<br />
If you only get the first two lines, you may see that it found the device but you need to bring it up.<br />
Example:<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:00:00:00:00:00 ACL MTU: 0:0 SCO MTU: 0:0<br />
DOWN <br />
RX bytes:0 acl:0 sco:0 events:0 errors:0<br />
TX bytes:0 acl:0 sco:0 commands:0 errors:<br />
}}<br />
<br />
# hciconfig hci0 up<br />
<br />
{{hc|hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:02:72:C4:7C:06 ACL MTU: 377:10 SCO MTU: 64:8<br />
UP RUNNING <br />
RX bytes:348 acl:0 sco:0 events:11 errors:0<br />
TX bytes:38 acl:0 sco:0 commands:11 errors:0<br />
}}<br />
<br />
If this fails with an error like:<br />
Operation not possible due to RF-kill<br />
it could be due either to the {{ic|rfkill}} utility, in which case it should be resolved with<br />
# rfkill unblock all<br />
or, it could simply be the hardware switch of the computer. The hardware bluetooth switch (at least sometimes) controls access to USB bluetooth dongles also. Flip/press this switch and try bringing the device up again.<br />
<br />
To verify that the device was detected you can use {{ic|hcitool}} which is part of the {{ic|bluez-utils}}. You can get a list of available devices and their identifiers and their MAC address by issuing:<br />
<br />
{{hc|$ hcitool dev|<br />
Devices:<br />
hci0 00:1B:DC:0F:DB:40<br />
}}<br />
<br />
More detailed informations about the device can be retrieved by using {{ic|hciconfig}}.<br />
<br />
{{hc|$ hciconfig -a hci0|<br />
hci0: Type: USB<br />
BD Address: 00:1B:DC:0F:DB:40 ACL MTU: 310:10 SCO MTU: 64:8<br />
UP RUNNING PSCAN ISCAN <br />
RX bytes:1226 acl:0 sco:0 events:27 errors:0<br />
TX bytes:351 acl:0 sco:0 commands:26 errors:0<br />
Features: 0xff 0xff 0x8f 0xfe 0x9b 0xf9 0x00 0x80<br />
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3 <br />
Link policy: RSWITCH HOLD SNIFF PARK <br />
Link mode: SLAVE ACCEPT <br />
Name: 'BlueZ (0)'<br />
Class: 0x000100<br />
Service Classes: Unspecified<br />
Device Class: Computer, Uncategorized<br />
HCI Ver: 2.0 (0x3) HCI Rev: 0xc5c LMP Ver: 2.0 (0x3) LMP Subver: 0xc5c<br />
Manufacturer: Cambridge Silicon Radio (10)<br />
}}<br />
<br />
=== Logitech Bluetooth USB Dongle ===<br />
<br />
There are Logitech dongles (ex. Logitech MX5000) that can work in two modes Embedded and HCI. In embedded mode dongle emulates a USB device so it seems to your PC that your using a normal USB mouse/keyoard.<br />
<br />
If you hold the little red Button on the USB BT mini-receiver it will enable the other mode. Hold the red button on the BT dongle and plug it into the computer, and after 3-5 seconds of holding the button, the Bluetooth icon will appear in the system tray. [http://ubuntuforums.org/showthread.php?t=1332197 Discussion]<br />
<br />
=== hcitool scan: Device not found ===<br />
<br />
* On some Dell laptops (e.g. Studio 15) you have to switch the Bluetooth mode from HID to HCI using<br />
# hid2hci<br />
<br />
{{Note|hid2hci is no longer in the $PATH, it is under /lib/udev/hid2hci, but udev should run it automatically for you.}}<br />
<br />
* If the device won't show up and you have a Windows operating system on your machine, try booting it and enable the bluetooth adapter from windows.<br />
<br />
* Sometimes also this simple command helps:<br />
# hciconfig hci0 up<br />
<br />
=== rfkill unblock: Do not unblock ===<br />
<br />
If your device still soft blocked and you run connman.<br />
<br />
Try this:<br />
$ connmanctl enable bluetooth<br />
<br />
=== My computer is not visible ===<br />
<br />
Can't discover computer from your phone? Enable PSCAN and ISCAN:<br />
# enable PSCAN and ISCAN<br />
$ hciconfig hci0 piscan <br />
# check it worked<br />
{{hc|$ hciconfig|<br />
hci0: Type: USB<br />
BD Address: 00:12:34:56:78:9A ACL MTU: 192:8 SCO MTU: 64:8<br />
'''UP RUNNING PSCAN ISCAN'''<br />
RX bytes:20425 acl:115 sco:0 events:526 errors:0<br />
TX bytes:5543 acl:84 sco:0 commands:340 errors:0<br />
}}<br />
<br />
{{Note|Check DiscoverableTimeout and PairableTimeout in {{ic|/etc/bluetooth/main.conf}}}}<br />
<br />
Try changing device class in {{ic|/etc/bluetooth/main.conf}} as following:<br />
# Default device class. Only the major and minor device class bits are<br />
# considered.<br />
#Class = 0x000100 (from default config)<br />
Class = 0x100100<br />
<br />
This was the only solution to make my computer visible for my phone. <br />
<br />
=== Nautilus cannot browse files ===<br />
<br />
If nautilus doesn't open and show this error:<br />
Nautilus cannot handle obex: locations. Couldn't display "obex://[XX:XX:XX:XX:XX:XX]/".<br />
Install {{Pkg|gvfs-obexftp}} package.<br />
<br />
=== Sennheiser MM400 Headset connection problems ===<br />
<br />
If your {{ic|Sennheiser MM400 Headset}} immediately disconnects after connecting as {{ic|Headset Service}} with Blueman, try to connect it as {{ic|Audio Sink}}. Afterwards you can change the headset's {{ic|Audio Profile}} to {{ic|Telephony Duplex}} with a right click in Blueman.<br />
With this option headset functionality will be available although the headset was only connected as {{ic|Audio Sink}} in first place and no disconnection will happen (tested with bluez 4.96-3, pulseaudio 1.1-1 and blueman 1.23-2).<br />
<br />
=== My device is paired but no sound is played from it ===<br />
<br />
Try to first inspect {{ic|/var/log/messages.log}}. If you see such messages:<br />
{{bc|<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Service not connected<br />
Jan 12 20:08:58 localhost pulseaudio[1584]: [pulseaudio] module-bluetooth-device.c: Bluetooth audio service not available<br />
}}<br />
try first:<br />
# pactl load-module module-bluetooth-device<br />
<br />
If the module fails to work, do this workaround:<br />
Open {{ic|/etc/bluetooth/audio.conf}} and add after '''[General]''' (on a new line)<br />
Enable=Socket<br />
Then restart the bluetooth daemon.<br />
Pair again your device, and you should find it in the pulseaudio settings (advanced settings for the sound)<br />
<br />
[http://wiki.gentoo.org/index.php?title=Bluetooth_Headset&redirect=no More information on Gentoo Wiki]<br />
<br />
If after fixing this you still can't get sound, try using blueman (this is the only one that works for me), make sure that notify-osd is installed or it might show you weird error messages like this one: "Stream setup failed"<br />
<br />
fail (/usr/lib/python2.7/site-packages/blueman/gui/manager/ManagerDeviceMenu.py:134)<br />
fail (DBusException(dbus.String(u'Stream setup failed'),),)<br />
<br />
== See also ==<br />
<br />
*[http://www.gentoo.org/doc/en/bluetooth-guide.xml Gentoo Linux Bluetooth guide]<br />
*[http://en.opensuse.org/HCL:Bluetooth openSUSE Bluetooth Hardware Compatibility List]<br />
*[http://linuxgazette.net/109/oregan3.html Accessing a Bluetooth phone (Linux Gazette)]<br />
*[http://www.adamish.com/blog/#a000361 Bluetooth computer visibility]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth for your mobile phone: Bluetooth pairing, data synchronization, photo download, Internet Dial-Up (tethering)]<br />
*[http://www.elstel.org/MobilePhone.html Bluetooth pairing and applications for synchronizing phone numbers, SMS-messages, phone call entries, your calendar and time; tethering]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Fluxbox&diff=248044Fluxbox2013-02-21T02:35:01Z<p>Netskink: </p>
<hr />
<div>[[Category:Stacking WMs]]<br />
[[cs:Fluxbox]]<br />
[[de:Fluxbox]]<br />
[[es:Fluxbox]]<br />
[[fr:Fluxbox]]<br />
[[it:Fluxbox]]<br />
[[ko:Fluxbox]]<br />
[[pl:Fluxbox]]<br />
[[pt:Fluxbox]]<br />
[[ru:Fluxbox]]<br />
[[sr:Fluxbox]]<br />
[[zh-TW:Fluxbox]]<br />
Fluxbox is yet another window manager for X11. It is based on the (now abandoned) Blackbox 0.61.1 code, but with significant enhancements and continued development. Fluxbox is very light on resources and fast, yet provides interesting window management tools such as tabbing and grouping. Its configuration files are easy to understand and edit and there are hundreds of fluxbox "styles" to make your desktop look great. ArchLinux with FluxBox can turn an old Pentium 800 box with just 256MB of RAM into a very usable computer.<br />
<br />
==Installation==<br />
<br />
Installing Fluxbox is as easy as:<br />
<br />
# pacman -S fluxbox<br />
<br />
Unless of course you have not yet installed [[Xorg]], in which case, do that as well.<br />
<br />
== Starting Fluxbox ==<br />
=== Method 1: KDM/GDM/LightDM Login Managers ===<br />
Users of [[KDM]], [[GDM]] or [[Lightdm]] should find a new fluxbox entry added to their session menu automatically. Simply choose the fluxbox option from the session menu when logging in.<br />
<br />
=== Method 2: ~/.xinitrc ===<br />
<br />
Edit {{ic|~/.xinitrc}} and add the following code:<br />
<br />
exec startfluxbox<br />
<br />
See [[xinitrc]] for details, such as preserving the logind (and/or consolekit) session.<br />
<br />
== Configuration ==<br />
<br />
System-wide fluxbox configuration files are in {{ic|/usr/share/fluxbox}} while user configuration files are in {{ic|~/.fluxbox}}. The user config files are:<br />
<ul><br />
<li>init: the main fluxbox resource configuration file. See [http://fluxbox-wiki.org/index.php?title=Editing_the_init_file Editing the init file]<br />
<li>menu: the fluxbox menu config. See below and [http://fluxbox-wiki.org/index.php?title=Editing_the_menu Editing the menu file]<br />
<li>keys: the fluxbox keyboard shortcuts (hotkeys) file. See below and [http://fluxbox-wiki.org/index.php?title=Keyboard_shortcuts here]<br />
<li>startup: where to launch startup apps but see below for .xinitrc and also [http://fluxbox-wiki.org/index.php?title=Editing_the_startup_file here]<br />
<li>overlay: a config file to override elements of styles. See [http://fluxbox-wiki.org/index.php?title=Style_overlay here].<br />
<li>apps: a config file for remembering the window configuration of specific apps. See [http://fluxbox-wiki.org/index.php?title=Editing_the_apps_file here]<br />
<li>windowmenu: a config file for altering the Window Menu itself: [http://fluxbox-wiki.org/index.php?title=Editing_the_windowmenu read this]<br />
</ul><br />
There are a couple of other less important config files in the directory. But the main ones to be concerned with are init, menu, keys and perhaps startup.<br />
<br />
=== Menu Management ===<br />
<br />
When you first install fluxbox a very basic applications menu will be created at ~/.fluxbox/menu. You access the menu via a right mouse button click on the desktop. As with other lightweight window managers Fluxbox does not automatically update its menu when you install new applications. It is therefore recommended that you install most of the apps you want on your system first and then re-generate or edit the menu. To enhance the menu and add/edit items there are basically four ways to do it:<br />
<br />
==== fluxbox-generate_menu ====<br />
There is a built-in command provided with fluxbox:<br />
$ fluxbox-generate_menu<br />
This command will auto-generate a {{ic|~/.fluxbox/menu/}} file based on your installed programs. However, the menu it generates will not be as comprehensive as that generated by "menumaker" (see immediately below).<br />
<br />
====MenuMaker====<br />
[http://menumaker.sourceforge.net MenuMaker] is a powerful tool that creates XML-based menus for a variety of Window Managers, including Fluxbox. MenuMaker will search your computer for executable programs and create a menu based on the results. It can be configured to exclude Legacy X, GNOME, KDE, or Xfce applications if desired.<br />
<br />
To install MenuMaker:<br />
# pacman -S menumaker<br />
<br />
Once installed, you can generate a complete menu and overwrite the default one by running:<br />
$ mmaker -f FluxBox<br />
<br />
To see MenuMaker options:<br />
$ mmaker --help<br />
<br />
==== Arch Linux Xdg menu ====<br />
Requires [[XdgMenu]] which is available via pacman:<br />
# pacman -S archlinux-xdg-menu<br />
<br />
To then create a fluxbox menu:<br />
$ xdg_menu --fullmenu --format fluxbox --root-menu /etc/xdg/menus/arch-applications.menu >~/.fluxbox/menu<br />
<br />
More info:<br />
$ xdg_menu --help<br />
<br />
==== Manually create/edit the menu ====<br />
Use your favourite text editor and edit the file: "~/.fluxbox/menu" .<br />
The basic syntax for a menu item to appear is:<br />
[exec] (name) {command} <path to icon><br />
<br />
...where "name" is the text you wish to appear for that menu item and "command" is the location of the binary, e.g.:<br />
[exec] (Firefox Browser) {/usr/bin/firefox} <path to firefox icon><br />
<br />
Note that the "<path to icon>" is optional. If you want to create a submenu the syntax is:<br />
[submenu] (Name)<br />
...<br />
...<br />
[end]<br />
When done editing save the file and exit. There is no need to restart fluxbox. For more info read [http://fluxbox-wiki.org/index.php?title=Editing_the_menu editing the fluxbox menu].<br />
<br />
===Init===<br />
The ~/.fluxbox/init file is FluxBox's primary configuration resource file. You can change the basic functionality of fluxbox, windows, toolbar, focus, etc. Some of these options are also available from the Fluxbox, Configuration Menu. For more detail read [http://fluxbox-wiki.org/index.php?title=Editing_the_init_file Editing the init file].<br />
<br />
===Hotkeys===<br />
Fluxbox offers basic hotkeys functionality. The fluxbox hotkey file is located at {{ic|~/.fluxbox/keys}}.<br />
The Control key is represented by "Control". Mod1 corresponds to the Alt key and Mod4 corresponds to Meta (not a standard key but most users map Meta to the "Win" key). When installed and first run Fluxbox will provide you with a very usable, almost complete set of hotkeys. You should peruse and learn the ~/.fluxbox/keys file to enhance your FluxBox experience.<br />
<br />
Example: here is a quick way to control the Master volume:<br />
Control Mod1 Up :Exec amixer set Master,0 5%+ <br />
Control Mod1 Down :Exec amixer set Master,0 5%-<br />
<br />
===Workspaces===<br />
Fluxbox defaults to having four workspaces. These are accessible using Ctrl+F1-F4 shortcuts, or by using the left mouse button to click the arrows on the toolbar. You can also access workspaces via a middle mouse button click on desktop which pops up the Workspaces Menu.<br />
<br />
===Tabbing and Grouping===<br />
With at least two windows visible on your desktop use ctrl +left click on the upper window tab of one window and drag it into the other open window. The two windows will now be grouped together with window tabs in the upper window tab bar. You may now perform a window operation that will affect the entire window "group". To reverse the tabbing use ctrl +left click on a tab and drag it to an empty space on the desktop.<br />
<br />
===Background (Wallpaper)===<br />
Setting the background in Fluxbox has historically been convoluted, especially where transparency was required. The fluxbox-wiki now has an entry for [http://fluxbox-wiki.org/index.php?title=Howto_set_the_background background setting], so please refer to that. <br />
<br />
The easiest way to do it with ArchLinux is to first of all check that you have a background setting application available:<br />
$ fbsetbg -i<br />
<br />
If not, install either feh, esetroot or wmsetbg using pacman. Then add this "fbsetbg" line to your ~/.xinitrc file, before the "exec" line, e.g.:<br />
fbsetbg /path/to/my/image.image<br />
<br />
====Swapping Multiple Backgrounds Easily====<br />
<br />
Place the following submenu in your fluxbox menu:<br />
[submenu] (Backgrounds)<br />
[wallpapers] (~/.fluxbox/backgrounds) {feh --bg-scale}<br />
[wallpapers] (/usr/share/fluxbox/backgrounds) {feh --bg-scale}<br />
[end]<br />
Then put your background images into {{ic|~/.fluxbox/backgrounds}} or any other folder you specify, they will then appear in the same fashion as your styles.<br />
<br />
The same applies to a dual screen wallpaper on a system without 'xinerama' (NVidia TwinView for example) :<br />
[submenu] (Backgrounds)<br />
[wallpapers] (/path/to/your/backgrounds) {feh --bg-scale --no-xinerama }<br />
[end]<br />
<br />
====Using Feh with FluxBox====<br />
Install feh with:<br />
# pacman -S feh<br />
<br />
To make sure fluxbox will load feh background next time start:<br />
<br />
'''1.''' Make {{ic|.fehbg}} executable:<br />
$ chmod 770 ~/.fehbg<br />
<br />
'''2.''' Then add (or modify) the following line to the file {{ic|~/.fluxbox/init}}:<br />
session.screen0.rootCommand: ~/.fehbg<br />
<br />
'''3.''' or add (or modify) the following line to the file {{ic|~/.fluxbox/startup}}:<br />
~/.fehbg<br />
<br />
===Theming===<br />
To install a fluxbox theme extract the theme archive file to a styles directory. The default directories are:<br />
*global - {{ic|/usr/share/fluxbox/styles}}<br />
*user only - {{ic|~/.fluxbox/styles}}<br />
<br />
The ArchLinux [[AUR]] currently contains a compilation of good looking fluxbox themes called "fluxbox-styles". Get it [https://aur.archlinux.org/packages.php?ID=28743 here] and install this package for more themes than you could possibly use. When installed correctly they will appear in the Fluxbox, Styles section of your Fluxbox menu.<br />
<br />
To create your own Fluxbox styles read [[Fluxbox_Style_Guide]] and this [http://tenr.de/howto/style_fluxbox/style_fluxbox.html style guide].<br />
<br />
If you use mmaker -f FluxBox to create your menus, you will not see the styles menu selection after you install the styles. To correct this add the following to ~/.fluxbox/menu after the restart menu item:<br />
[submenu] (System Styles) {Choose a style...}<br />
[stylesdir] (/usr/share/fluxbox/styles)<br />
[end]<br />
[submenu] (User Styles) {Choose a style...}<br />
[stylesdir] (~/.fluxbox/styles)<br />
[end]<br />
<br />
<br />
===The Slit===<br />
Fluxbox, WindowMaker and a couple of other lightweight window managers have a "Slit". This is a dock for any application that can be 'dockable'. A docked application is anchored and appears on every workspace. It cannot be moved freely and is not influenced by any manipulation to windows. It is basically a small widget. Dock apps that are useful in such a situation tend to be clocks, system monitors, weather, etc. Visit [http://dockapps.windowmaker.org/ dockapps.windowmaker.org]<br />
<br />
===Autostarting Applications===<br />
The ArchLinux way to autostart apps is to put all code into {{ic|~/.xinitrc}}. Please read [[Xinitrc]]. However, fluxbox provides functionality to autostart applications on its own. The {{ic|~/.fluxbox/startup}} file is a script for autostarting applications as well as starting fluxbox itself. The # symbol denotes a comment.<br />
<br />
A sample file:<br />
fbsetbg -l <nowiki>#</nowiki> sets the last background set, very useful and recommended.<br />
<nowiki>#</nowiki> In the below commands the ampersand symbol (&) is required on all applications that do not terminate immediately. <br />
<nowiki>#</nowiki> failure to provide them will cause fluxbox not to start.<br />
idesk & <br />
xterm &<br />
<nowiki>#</nowiki> exec is for starting fluxbox itself, do not put an ampersand (&) after this or fluxbox will exit immediately<br />
exec /usr/bin/fluxbox<br />
<nowiki>#</nowiki> or if you want to keep a log, uncomment the below command and comment out the above command:<br />
<nowiki>#</nowiki> exec /usr/bin/fluxbox -log ~/.fluxbox/log<br />
<br />
===Other Menus===<br />
<br />
In the "Menu Management" section (above) we were discussing the main "Applications" Menu, called the "Root" menu in fluxbox lingo. FluxBox also has other menus available to the user:<br />
<ul><br />
<li>Workspaces Menu: middle click on desktop.<br />
<li>Configuration Menu: located within the "Fluxbox" section of the "Root" menu.<br />
<li>Window menu: right click on the titlebar of any window, or its bar if minimized. Can be edited. See fluxbox-menu man page.<br />
<li>Toolbar menu: right click on empty part of toolbar. Also found as a sub-menu within the Configuration Menu.<br />
<li>Slit Menu: found as a sub-menu within the configuration menu.<br />
</ul><br />
<br />
===True Transparency===<br />
To enable true transparency in fluxbox you need an X compositor such as [[Xcompmgr]].<br />
<br />
===Notifications===<br />
To enable connection notifications on-screen for fluxbox read [https://bbs.archlinux.org/viewtopic.php?id=138616 this Arch forum thread].<br />
<br />
===A life after xorg.conf===<br />
Xorg no longer requires an xorg.conf file. Traditionally this is where you would change your keyboard settings and powersave settings. Luckily there are elegant solutions not using xorg.conf. <br />
<br />
====Setting your keyboard right====<br />
Just add the following line to {{ic|~/.fluxbox/startup}}:<br />
setxkbmap us -variant intl & # to have a us keyboard with special characters enabled (like éóíáú)<br />
<br />
Instead of 'us' you can also pass your language code and remove the variant option (ex.: 'us_intl', which works like the command above in some setups). See man setxkbmap for more options.<br />
<br />
To make a help function in your menu, just add in {{ic|~/.fluxbox/menu}}:<br />
[submenu] (Keyboard)<br />
[exec] (normal) {setxkbmap us}<br />
[exec] (international) {setxkbmap us -variant intl}<br />
[end]<br />
<br />
==See also==<br />
* [http://fluxbox.org/ Fluxbox Homepage]<br />
* [http://fluxbox-wiki.org/ Fluxbox Wiki]<br />
* [http://en.gentoo-wiki.com/wiki/Fluxbox Gentoo Wiki about Fluxbox]<br />
* [http://www.gentoo.org/doc/en/fluxbox-config.xml Gentoo Fluxbox Documentation]<br />
* [http://box-look.org/ Themes for Fluxbox]<br />
* [[Fluxbox_Style_Guide|Fluxbox Style Guide]]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=77729 Narada's Fluxbox Guide]<br />
* The fluxbox man pages: fluxbox, fluxbox-menu, fluxbox-style, fluxbox-keys, fluxbox-apps, fluxbox-remote, fbsetroot, fbsetbg, fbrun, startfluxbox.<br />
* [https://bbs.archlinux.org/viewtopic.php?id=90260 Archlinux-FluxBox screenshots]</div>Netskinkhttps://wiki.archlinux.org/index.php?title=Steam&diff=247912Steam2013-02-19T18:13:07Z<p>Netskink: </p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Wine]]<br />
[[ja:Steam]]<br />
[[zh-CN:Steam]]<br />
{{Article summary start}}<br />
{{Article summary text|[http://store.steampowered.com/about/ Steam] is a content delivery system made by Valve Software. It is best known as the platform needed to play Source Engine games (e.g. Half-Life 2, Counter-Strike). Today it offers many games from many other developers.}}<br />
<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Wine}}<br />
{{Article summary end}}<br />
<br />
See the [[Wikipedia:Steam (software)|Steam Wikipedia page]] and the page in the [http://appdb.winehq.org/objectManager.php?sClass=version&iId=19444 Wine Application Database] for more info.<br />
<br />
== Native Steam on Linux ==<br />
<br />
{{Note|Arch Linux is not [https://support.steampowered.com/kb_article.php?ref&#61;1504-QHXN-8366 officially supported].}}<br />
<br />
{{Note|If you have a pure 64-bit installation, you will need to enable the [[multilib]] repository in pacman. This is because the Steam client is a 32-bit application. It may also make sense to install multilib-devel to provide some important multilib libraries. You also most likely need to install the 32-bit version of your graphics driver to run Steam.}}<br />
<br />
Install {{Pkg|steam}} from the [[multilib]] repository.<br />
<br />
Steam makes heavy usage of the Arial font. A decent Arial font to use is {{Pkg|ttf-liberation}} or the official Microsoft Arial fonts: {{aur|ttf-microsoft-arial}} or {{aur|ttf-ms-fonts}} packages from the [[AUR]]. Asian languages require {{Pkg|wqy-zenhei}} to display properly.<br />
<br />
Steam is '''not supported''' on this distribution. As such some fixes are needed on the users part to get things functioning properly. Several games have dependencies which may be missing from your system. If a game fails to launch (often without error messages) then make sure all of the libraries listed below that game are installed. Please install {{Pkg|libtxc_dxtn}} and {{Pkg|lib32-libtxc_dxtn}} as almost all games require it.<br />
<br />
===General troubleshooting===<br />
{{Note|In addition to being documented here, any bug/fix/error should be, if not already, reported on Valve's bug tracker on their [https://github.com/ValveSoftware/steam-for-linux GitHub page].}}<br />
<br />
{{Note|Connection problems may occur when using DD-WRT with peer-to-peer traffic filtering.}}<br />
<br />
====GUI problems with KDE====<br />
: Valve GitHub [https://github.com/ValveSoftware/steam-for-linux/issues/594 issue 594]<br />
<br />
If you are using KDE and you have problems with the GUI (such as lag or random crashes) modify the compositing type to OpenGL/Raster. In KDE system settings, go to "Desktop Effects" in the "Workspace Appearance and Behaviour" section. Open the "Advanced" tab. Change "Compositing type" from XRender to OpenGL.<br />
<br />
====The close button only minimizes the window====<br />
: Valve GitHub [https://github.com/ValveSoftware/steam-for-linux/issues/1025 issue 1025]<br />
<br />
If you have your tray icon working you have the option of making the close button close to tray instead of minimize. To do this, set the environment variable <code>STEAM_FRAME_FORCE_CLOSE</code> to <code>1</code>. You can do this by launching Steam using the following command.<br />
$ STEAM_FRAME_FORCE_CLOSE=1 steam<br />
<br />
====Flash not working on 64-bit systems====<br />
: Steam Support [https://support.steampowered.com/kb_article.php?ref=1493-GHZB-7612 article]<br />
<br />
First ensure {{pkg|lib32-flashplugin}} is installed. Then create a local Steam flash plugin folder<br />
mkdir ~/.steam/bin32/plugins/<br />
and set a symbolic link to the global lib32 flash plugin file in your upper new folder<br />
ln -s /usr/lib32/mozilla/plugins/libflashplayer.so ~/.steam/bin32/plugins/<br />
<br />
====Text is corrupt or missing====<br />
The Steam Support [https://support.steampowered.com/kb_article.php?ref=1974-YFKL-4947 instructions] for Windows seem to work on Linux also: Simply download [https://support.steampowered.com/downloads/1974-YFKL-4947/SteamFonts.zip SteamFonts.zip] and install them (copying to ~/.fonts/ works at least).<br />
<br />
====Error on some games: S3TC support is missing====<br />
Install the following dependencies:<br />
* {{pkg|libtxc_dxtn}}<br />
* {{pkg|lib32-libtxc_dxtn}}<br />
<br />
====Black screen on (Valve?) games (but audio works)====<br />
Check the Steam stdout/stderr for Error lines, some quick dependencies for reference:<br />
* {{pkg|libgles}}<br />
* {{pkg|lib32-libgles}}<br />
* {{pkg|lib32-intel-dri}} (not confirmed as absolutely necessary)<br />
<br />
run steam from console via primusrun steam<br />
<br />
=== Game-specific depencencies and troubleshooting ===<br />
{{Note|Steam installs library dependencies of a game to a library directory, but some are missing at the moment. Report bugs involving missing libraries on Valve's bug tracker on their [https://github.com/ValveSoftware/steam-for-linux GIT page] before adding workarounds here, and then provide a link to the bug so it can be removed as the issues are fixed. Libraries like {{pkg|glu}} and {{pkg|libtxc_dxtn}} are exceptions to this, as they are just part of the implementation of the open drivers.}}<br />
<br />
====Amnesia: The Dark Descent====<br />
=====Dependencies=====<br />
* {{pkg|lib32-freealut}}<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libxmu}}<br />
* {{pkg|lib32-sdl_ttf}}<br />
<br />
=====Troubleshooting=====<br />
======Segfault======<br />
If you are using open source drivers you will need {{pkg|lib32-libtxc_dxtn}} . See [http://www.frictionalgames.com/forum/thread-10924.html official forum] for details<br />
<br />
====And Yet It Moves====<br />
=====Dependencies=====<br />
* {{aur|lib32-libtheora}}<br />
* {{aur|lib32-libjpeg6}}<br />
* {{aur|lib32-libtiff4}}<br />
<br />
=====Compatibility=====<br />
Game refuses to launch and following message can be observed on console<br />
readlink: extra operand ‘Yet’<br />
Try 'readlink --help' for more information.<br />
To fix this, open {{ic|~/.steam/root/SteamApps/common/And Yet It Moves/AndYetItMovesSteam.sh}} in text editor and replace line<br />
ayim_dir="$(dirname "$(readlink -f ${BASH_SOURCE[0]})")"<br />
with<br />
ayim_dir="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"<br />
<br />
====Bastion====<br />
=====Dependencies=====<br />
* {{pkg|lib32-libtxc_dxtn}}<br />
<br />
====Counter-Strike: Source====<br />
=====Troubleshooting=====<br />
======Game crashes upon joining======<br />
If the game is constantly crashing when trying to join a game and in <code>~/.steam/root/SteamApps/your@account/Counter Strike Source/hl2.sh</code> you have <code>__GL_THREADED_OPTIMIZATIONS=1</code>, try changing it to <code>0</code>.<br />
<br />
====Crusader Kings II====<br />
Game is installed into {{ic|$HOME/Steam/SteamApps/common/Crusader Kings II}}.<br />
<br />
Game can be started directly, without need of running Steam on background, using command {{ic|$HOME/Steam/SteamApps/common/Crusader Kings II/ck2}}.<br />
<br />
Saves are stored in {{ic|$HOME/Steam/SteamApps/common/Crusader Kings II/save games/}}.<br />
<br />
=====Troubleshooting=====<br />
======No audio======<br />
{community,multilib}-testing/{{pkg|steam}} 1.0.0.28-3 should export this variable inside {{ic|/usr/bin/steam}}<br />
<br />
export the variable somewhere before in your system.<br />
export SDL_AUDIODRIVER=alsa<br />
<br />
======Black map======<br />
1. If the map is black and you do not see the character portraits, remove the first two lines and the last line from {{ic|~/.local/share/Steam/SteamApps/common/Crusader Kings II/gfx/FX/standardfuncsgfx.fxh}}, and install {{pkg|lib32-libtxc_dxtn}} ([http://steamcommunity.com/app/203770/discussions/0/846942156138239751#p3 source]). This fix worked on ATI Radeon with open-source drivers.<br />
<br />
2. Thought the solution mentioned in ([http://steamcommunity.com/app/203770/discussions/0/846942156138239751#p3 source article]) might help a lot of affected, even there in disc. were also many people, whom this solution helped only partially, or not at all. Alternate option, if previous is not working might be to try install the proprietary graphics drivers instead of those open-source one.<br />
<br />
====FTL: Faster than Light====<br />
=====Dependencies=====<br />
Libraries are downloaded and and placed in the game's data directory for both architectures. As long as you run FTL by the launcher script (or via the shortcut in Steam) you should not need to download any further libraries.<br />
<br />
=====Compatibility=====<br />
After installation, FTL may fail to run due to a 'Text file busy' error (characterised in Steam by your portrait border going green then blue again). The easiest way to mend this is to just reboot your system. Upon logging back in FTL should run.<br />
<br />
The Steam overlay in FTL does not function as it is not a 3D accelerated game. Because of this the desktop notifications will be visible. If playing in fullscreen, therefore, these notifications in some systems may steal focus and revert you back to windowed mode with no way of going back to fullscreen without relaunching. The binaries for FTL on Steam have no DRM and it is possible to run the game ''without'' Steam running, so in some cases that may be optimum - just ensure that you launch FTL via the launcher script in {{ic|~/.steam/root/SteamApps/common/FTL Faster than Light/data/}} rather than the FTL binary in the $arch directory.<br />
<br />
=====Problems with open-source video driver=====<br />
FTL may fail to run if you are using an opensource driver for your video card. There are two solutions: install a proprietary video driver or delete (rename if you are unsure) the library "libstdc++.so.6" inside {{ic|~/.steam/root/SteamApps/common/FTL\ Faster\ Than\ Light/data/amd64/lib}} This is if you are using a 64bit system, I suppose that in case you are using a 32bit system you have to remove (rename) the same library located into {{ic|~/.steam/root/SteamApps/common/FTL\ Faster\ Than\ Light/data/x86/lib}}.<br />
<br />
====Harvest: Massive Encounter====<br />
=====Dependencies=====<br />
* {{pkg|lib32-gtk2}}<br />
* {{pkg|lib32-libvorbis}}<br />
* {{aur|lib32-nvidia-cg-toolkit}}<br />
* {{aur|lib32-libjpeg6}}<br />
<br />
=====Compatibility=====<br />
Game refuses to launch and throws you to library installer loop. Just edit {{ic| ~/.steam/root/SteamApps/common/Harvest Massive Encounter/run_harvest}} and remove everything but<br />
#!/bin/bash<br />
INSTDIR="`dirname $0`" ; cd "${INSTDIR}" ; INSTDIR="`pwd`"<br />
export LD_LIBRARY_PATH=${INSTDIR}/bin:~/.steam/bin<br />
exec ./Harvest<br />
<br />
====Killing Floor====<br />
=====Troubleshooting=====<br />
======Screen resolution======<br />
Killing Floor runs pretty much from scratch, although you might have to change in-game resolution screen as the default one is '''800x600''' and a '''4:3''' screen format.<br />
If you try to modify screen resolution in-game, it might crash your desktop enviroment.<br />
To fix this, please set the desired resolution screen size by modifing your {{ic|~/.killingfloor/System/KillingFloor.ini}} with your prefered editor.<br />
{{hc|# nano ~/.killingfloor/System/KillingFloor.ini|<nowiki><br />
...<br />
<br />
[WinDrv.WindowsClient]<br />
WindowedViewportX=????<br />
WindowedViewportY=????<br />
FullscreenViewportX=????<br />
FullscreenViewportY=????<br />
MenuViewportX=???<br />
MenuViewportY=???<br />
<br />
...<br />
<br />
[SDLDrv.SDLClient]<br />
WindowedViewportX=????<br />
WindowedViewportY=????<br />
FullscreenViewportX=????<br />
FullscreenViewportY=????<br />
MenuViewportX=????<br />
MenuViewportY=????<br />
<br />
...<br />
</nowiki>}}<br />
{{Note|Replace all the '''????''' with the corresponding numbers according the desired resolution. If you have an 1366x768 screen and want to use it at it's fullest, change all the Viewport fields to something like '''ViewportX&#61;1366''' and '''ViewportY&#61;768''' in the corresponding areas.}}<br />
{{Note| The dots in the middle indicate that there are more fields in that .ini file. But for screen resolution troubleshooting, you don't need to modify anything else.}}<br />
<br />
Save the file and restart the game, it should work now.<br />
<br />
======Windowed Mode======<br />
Uncheck fullscreen in the options menu, and use {{Keypress|Ctrl+g}} to stop mouse capturing (that was non-obvious to discover..). This way you can easily minimize it and do other other things..and let your WM handle things.<br />
<br />
====Multiwinia====<br />
=====Dependencies=====<br />
* {{pkg|lib32-openal}}<br />
<br />
Game will not launch without {{pkg|lib32-openal}}.<br />
<br />
====Penumbra: Overture====<br />
=====Dependencies=====<br />
(Taken from {{aur|penumbra-collection}} and {{aur|penumbra-overture-ep1-demo}})<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libxft}}<br />
* {{pkg|lib32-libvorbis}}<br />
* {{pkg|lib32-openal}}<br />
* {{pkg|lib32-sdl_ttf}}<br />
* {{pkg|lib32-sdl_image}}<br />
<br />
=====Troubleshooting=====<br />
======Windowed Mode======<br />
There is no in-game option to change to the windowed mode, you will have to edit {{ic|~/.frictionalgames/Penumbra/Overture/settings.cfg}} to activate it.<br />
Find {{ic|FullScreen&#61;"true"}} and change it to {{ic|FullScreen&#61;"false"}}, after this the game should start in windowed mode.<br />
<br />
====Psychonauts====<br />
=====Dependencies=====<br />
* {{pkg|libtxc_dxtn}} and {{pkg|lib32-libtxc_dxtn}}<br />
<br />
====Serious Sam 3: BFE====<br />
=====Dependencies=====<br />
* {{pkg|lib32-libtxc_dxtn}}<br />
<br />
=====Troubleshooting=====<br />
======No audio======<br />
Try running:<br />
# pacman -S lib32-alsa-plugins<br />
# mkdir -p /usr/lib/i386-linux-gnu/alsa-lib/<br />
# ln -s /usr/lib32/alsa-lib/libasound_module_pcm_pulse.so /usr/lib/i386-linux-gnu/alsa-lib/<br />
<br />
If that doesn't work, try tweaking ~/.alsoftrc as proposed by the [http://steamcommunity.com/app/221410/discussions/3/846940248238406974/ Steam community] (Serious Sam 3: BFE uses OpenAL to output sound). If you are not using Pulse Audio, you may want to write the following configuration:<br />
<br />
{{hc|$ nano ~/.alsoftrc|<nowiki><br />
[general]<br />
drivers = alsa<br />
[alsa]<br />
device = default<br />
capture = default<br />
mmap = true<br />
</nowiki>}}<br />
<br />
====Spacechem====<br />
=====Dependencies=====<br />
* {{pkg|lib32-sqlite}}<br />
* {{pkg|lib32-sdl_image}}<br />
* {{aur|lib32-sdl_mixer}}<br />
<br />
=====Troubleshooting=====<br />
======Game crash======<br />
The shipped x86 version of Spacechem doesn't work on x64 with the game's own libSDL* files, and crashes with some strange output.<br />
<br />
To solve this just remove or move the three files {{ic|libSDL-1.2.so.0}}, {{ic|libSDL_image-1.2.so.0}}, {{ic|libSDL_mixer-1.2.so.0}} from {{ic|~/.steam/root/SteamApps/common/SpaceChem}}<br />
<br />
====Space Pirates and Zombies====<br />
=====Troubleshooting=====<br />
======No audio======<br />
Apply the fix documented in Serious Sam 3: BFE above.<br />
<br />
====Splice====<br />
Splice comes with both x86 and x64 binaries. Steam does not have to be running to launch this game.<br />
=====Dependencies=====<br />
* {{pkg|glu}}<br />
* {{pkg|mono}}<br />
<br />
====Steel Storm: Burning Retribution====<br />
=====Troubleshooting=====<br />
======Start with black screen======<br />
The game tries to launch in 1024x768 resolution with fullscreen mode by default. It is impossible on some devices.<br />
(for example laptop Samsung Series9 with intel hd4000 video).<br />
<br />
You can launch the game in windowed mode. To do this open game Properties in Steam, in General tab select "Set launch options..." and type "-window".<br />
<br />
Now you can change the resolution in game.<br />
<br />
======No English fonts======<br />
If you use intel video card, just disable S3TC in DriConf.<br />
<br />
====Superbrothers: Sword & Sworcery EP====<br />
=====Dependencies=====<br />
* {{pkg|lib32-glu}}<br />
<br />
====Team Fortress 2 ====<br />
=====Dependencies=====<br />
* {{pkg|lib32-libtxc_dxtn}}<br />
<br />
=====Troubleshooting=====<br />
======No audio======<br />
It happens if there is no PulseAudio in your system.<br />
If you want to use [[ALSA]], you need to launch Steam or the game directly with {{ic|1=SDL_AUDIODRIVER=alsa}} <br />
(From [http://steamcommunity.com/app/221410/discussions/0/882966056462819091/#c882966056470753683 SteamCommunity]).<br />
<br />
If it still does not work, you may also need to set the environment variable AUDIODEV. For instance {{ic|1=AUDIODEV=Live}}. Use {{ic|aplay -l}} to list the available sound cards.<br />
<br />
====The Book of Unwritten Tales====<br />
If the game does not start, go to Properties --> Uncheck "Enable Steam Community In-Game".<br />
<br />
The game may segfault upon clicking the Setting menu and possibly during or before gameplay. This is a known issue and you will unfortunately have to wait for a fix from the developer.<br />
=====Dependencies=====<br />
* {{aur|lib32-libxaw}}<br />
* {{aur|lib32-jasper}}<br />
<br />
====The Clockwork Man====<br />
=====Dependencies=====<br />
* {{pkg|lib32-libidn}}<br />
<br />
====Trine 2====<br />
=====Dependencies=====<br />
* {{pkg|lib32-glu}}<br />
* {{pkg|lib32-libxxf86vm}}<br />
* {{pkg|lib32-libglapi}}<br />
* {{pkg|lib32-libdrm}}<br />
* {{pkg|lib32-openal}}<br />
<br />
=====Troubleshooting=====<br />
* If colors are wrong with FOSS drivers (r600g at least), try to run the game in windowed mode, rendering will be corrected. ([https://bugs.freedesktop.org/show_bug.cgi?id=60553 bugreport])<br />
* If sound plays choppy, try to edit {{ic|/etc/openal/alsoft.conf}} with values<br />
<br />
drivers=pulse,alsa<br />
frequency=48000<br />
<br />
====Unity of Command====<br />
=====Dependencies=====<br />
* {{pkg|lib32-pango}}<br />
<br />
=====Troubleshooting=====<br />
* If squares are shown instead of text, try removing {{ic|$HOME/Steam/SteamApps/common/Unity of Command/bin/libpangoft2-1.0.so.0}}.<br />
<br />
====World of Goo====<br />
=====Changing Resolution=====<br />
* To change the game resolution edit the section "Graphics display" in the configuration file {{ic|$HOME/Steam/SteamApps/common/World of Goo/properties/config.txt}}. For example, see below:<br />
<!-- Graphics display --><br />
<param name="screen_width" value="1680" /><br />
<param name="screen_height" value="1050" /><br />
<param name="color_depth" value="0" /><br />
<param name="fullscreen" value="true" /><br />
<param name="ui_inset" value="10" /><br />
<br />
===Skins for Steam===<br />
<br />
The Steam interface can be fully customized by copying its various interface files in its skins directory and modifying them.<br />
<br />
====Steam Skin Manager====<br />
<br />
The process of applying a skin to Steam can be greatly simplified using {{aur|steam-skin-manager}} from the AUR. The package also comes with a hacked version of the Steam launcher which allows the window manager to draw its borders on the Steam window.<br />
<br />
As a result, skins for Steam will come in two flavors, one with and one without window buttons. The skin manager will prompt you whether you use the hacked version or not, and will automatically apply the theme corresponding to your GTK theme if it is found. You can of course still apply another skin if you want.<br />
<br />
The package ships with two themes for the default Ubuntu themes, Ambiance and Radiance. A Faience theme is under development and already has its own package on the AUR {{aur|steam-skin-faience-git}}.<br />
<br />
== Steam on Wine ==<br />
<br />
Install {{Pkg|wine}} from the official repositories and follow the instructions provided in the [[Wine|article]].<br />
<br />
Install the required Microsoft fonts {{AUR|ttf-microsoft-tahoma}} and {{AUR|ttf-ms-fonts}} from the [[AUR]] or through {{AUR|winetricks-svn}}.<br />
{{Note|If you have access to Windows discs, you may want to install {{AUR|ttf-win7-fonts}} instead.}}<br />
<br />
If you have an old Wine prefix ({{ic|~/.wine}}), you should remove it and let Wine create a new one to avoid problems (you can transfer over anything you want to keep to the new Wine prefix).<br />
<br />
===Installation===<br />
<br />
Download and run the Steam installer from [http://store.steampowered.com/about/ steampowered.com]. It is no longer an {{ic|.exe}} file so you have to start it with {{ic|msiexec}}: <br />
$ msiexec /i SteamInstall.msi<br />
<br />
===Starting Steam===<br />
<br />
On x86:<br />
$ wine ~/.wine/drive_c/Program\ Files/Steam/Steam.exe<br />
<br />
On x86_64 (with steam installed to a clean wine prefix):<br />
$ wine ~/.wine/drive_c/Program\ Files\ \(x86\)/Steam/Steam.exe<br />
<br />
Alternatively, you may use this method:<br />
<br />
$ wine "C:\\Program Files\\Steam\\steam.exe" <br />
<br />
You should consider making an alias to easily start steam (and put it in your shell's rc file), example:<br />
alias steam='wine ~/.wine/drive_c/Program\ Files\ \(x86\)/Steam/Steam.exe >/dev/null 2>&1 &'<br />
<br />
{{Note|If you are using an nvidia card through bumblebee, you should prefix those commands with {{ic|optirun}}.}}<br />
<br />
===Tips===<br />
<br />
====Performance====<br />
<br />
Consider disabling wine debugging output by adding this to your shell rc file:<br />
export WINEDEBUG=-all<br />
or, just add it to your steam alias to only disable it for steam:<br />
alias steam='WINEDEBUG=-all wine ~/.wine/drive_c/Program\ Files\ \(x86\)/Steam/Steam.exe >/dev/null 2>&1 &'<br />
Additionally, Source games rely on a paged pool memory size specification for audio, and WINE by default does not have this set. To set it:<br />
wine reg add "HKLM\\System\\CurrentControlSet\\Control\\Session Manager\\Memory Management\\" /v PagedPoolSize /t REG_DWORD /d 402653184 /f<br />
<br />
==== Application Launch Options ====<br />
Go to "Properties" -> "Set Launch Options", e.g.:<br />
{{bc|-console -dxlevel 90 -width 1280 -height 1024<br />
}}<br />
* {{ic|console}}<br />
Activate the console in the application to change detailed applications settings.<br />
* {{ic|dxlevel}}<br />
Set the application's DirectX level, e.g. 90 for DirectX Version 9.0. It is recommended to use the video card's DirectX version to prevent crashes. See the official Valve Software Wiki http://developer.valvesoftware.com/wiki/DirectX_Versions for details.<br />
* {{ic|width}} and {{ic|height}}<br />
Set the screen resolution. In some cases the graphic settings are not saved in the application and the applications always starts in the default resolution.<br />
Please refer to http://developer.valvesoftware.com/wiki/Launch_options for a complete list of launch options.<br />
<br />
==== Using a Pre-Existing Steam Install ====<br />
<br />
If you have a shared drive with Windows, or already have a Steam installation somewhere else, you can simply symlink the Steam directory to {{ic|~/.wine/drive_c/Program Files/Steam/}} . However, be sure to do '''all''' the previous steps in this wiki. Confirm Steam launches and logs into your account, ''then'' do this:<br />
<br />
cd ~/.wine/drive_c/Program\ Files/ <br />
mv Steam/ Steam.backup/ (or you can just delete the directory)<br />
ln -s /mnt/windows_partition/Program\ Files/Steam/<br />
<br />
{{Note|If you have trouble starting Steam after symlinking the entire Steam folder, try linking only the {{ic|steamapps}} subdirectory in your existing wine steam folder instead.}}<br />
<br />
{{Note|If you still have trouble starting games, use {{ic|sudo mount --bind /path/to/SteamApps ~/.local/share/Steam/SteamApps -ouser&#61;your-user-name }}, this is the only thing that worked for me with {{ic|TF2}}}}<br />
<br />
====Running Steam in a second X Server====<br />
<br />
Assuming you are using the script above to start Steam, make a new script, called {{ic|x.steam.sh}}. You should run this when you want to start Steam in a new X server, and {{ic|steam.sh}} if you want Steam to start in the current X server. <br />
<br />
If due to misconfiguration a black screen is shown, you could always close down the second X server by pressing {{Keypress|Ctrl}} + {{Keypress|Alt}} + {{Keypress|Backspace}}.<br />
<br />
{{bc|1=<br />
#!/bin/bash <br />
<br />
DISPLAY=:1.0<br />
<br />
xinit $HOME/steam.sh $* -- :1<br />
}}<br />
<br />
Now you can use {{Keypress|Ctrl}} + {{Keypress|Alt}} + {{Keypress|F7}} to get to your first X server with your normal desktop, and {{Keypress|Ctrl}} + {{Keypress|Alt}} + {{Keypress|F8}} to go back to your game. <br />
<br />
Because the second X server is ''only'' running the game and the first X server with all your programs is backgrounded, performance should increase. In addition, it is much more convenient to switch X servers while in game to access other resources, rather than having to exit the game completely or {{Keypress|Alt}}-{{Keypress|Tab}} out. Finally, it is useful for when Steam or WINE goes haywire and leaves a bunch of processes in memory after Steam crashes. Simply {{Keypress|Ctrl}} + {{Keypress|Alt}} + {{Keypress|Backspace}} on the second X server to kill that X and all processes on that desktop will terminate as well. <br />
<br />
'''If you get errors that look like "Xlib: connection to ":1.0" refused by server" when starting the second X''': You will need to adjust your X permissions.<br />
<br />
'''If you lose the ability to use the keyboard while using Steam''': This is an odd bug that does not happen with other games. A solution is to use a WM in the second X as well. Thankfully, you do not need to run a large WM. Openbox and icewm have been confirmed to fix this bug (evilwm, pekwm, lwm ''do not'' work), but the icewm taskbar shows up on the bottom of the game, thus it's recommended to use [[Openbox]]. Install {{Pkg|openbox}} from the [[official repositories]], then add {{Ic|openbox &}} to the top of your {{ic|steam.sh}} file. Note you can run other programs (ex. Teamspeak &) or set X settings (ex. xset, xmodmap) before the WINE call as well.<br />
<br />
====Steam Links in Firefox, Chrome, Etc====<br />
To make steam:// urls in your browser connect with steam in wine, there are several things you can do. One involves making steam url-handler keys in gconf, another involves making protocol files for kde, others involve tinkering with desktop files or the Local State file for chromium. These seem to only work in firefox or under certain desktop configurations. One way to do it that works more globally is using mimeo, a tool made by Xyne (an Arch TU) which follows. For another working and less invasive (but firefox-only) way, see the first post [http://ubuntuforums.org/showthread.php?t=433548 here] .<br />
<br />
* Make {{ic| /usr/bin/steam}} with your favorite editor and paste:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
#<br />
# Steam wrapper script<br />
#<br />
exec wine "c:\\program files\\steam\\steam.exe" "$@"<br />
}}<br />
<br />
* Make it executable.<br />
<br />
# chmod +x /usr/bin/steam<br />
<br />
* Install {{AUR|mimeo}} and {{AUR|xdg-utils-mimeo}} from AUR. You will need to replace the existing {{pkg|xdg-utils}} if installed. In XFCE, you will also need {{pkg|xorg-utils}}.<br />
<br />
* Create {{ic|~/.config/mimeo.conf}} with your favorite editor and paste:<br />
<br />
{{bc|<br />
/usr/bin/steam %u<br />
^steam://<br />
}}<br />
<br />
* Lastly, open {{ic|/usr/bin/xdg-open}} in your favorite editor. Go to the {{ic|detectDE()}} section and change it to look as follows:<br />
<br />
{{bc|<nowiki><br />
detectDE()<br />
{<br />
#if [ x"$KDE_FULL_SESSION" = x"true" ]; then DE=kde;<br />
#elif [ x"$GNOME_DESKTOP_SESSION_ID" != x"" ]; then DE=gnome;<br />
#elif `dbus-send --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.GetNameOwner string:org.gnome.SessionManager > /dev/null 2>&1` ; then DE=gnome;<br />
#elif xprop -root _DT_SAVE_MODE 2> /dev/null | grep ' = \"xfce4\"$' >/dev/null 2>&1; then DE=xfce;<br />
#elif [ x"$DESKTOP_SESSION" == x"LXDE" ]; then DE=lxde;<br />
#else DE=""<br />
#fi<br />
DE=""<br />
}<br />
</nowiki>}}<br />
<br />
* Restart the browser and you should be good to go. In chromium, you cannot enter a {{ic|steam://}} link in the url box like you can with firefox. The forum link above has a {{ic|steam://open/friends}} link to try if needed.<br />
<br />
{{Note|If you have any problems with file associations after doing this, simply revert to regular xdg-utils and undo your changes to {{ic|/usr/bin/xdg-open}}.}}<br />
{{Note|Those on other distributions that stumble upon this page, see the link above for firefox specific instructions. No easy way to get it working on Chromium on other distros exists.}}<br />
<br />
====No text rendered problem====<br />
If there is no text/font rendered when starting steam you should try to start steam with the parameter {{ic|-no-dwrite}}. Read more in [https://bbs.archlinux.org/viewtopic.php?id=146223 the forum thread about it.]<br />
{{bc|wine ~/.wine/drive_c/Program\ Files\ \(x86\)/Steam/Steam.exe -no-dwrite}}<br />
<br />
== See Also ==<br />
* https://wiki.gentoo.org/wiki/Steam</div>Netskink