https://wiki.archlinux.org/api.php?action=feedcontributions&user=Bluerider&feedformat=atomArchWiki - User contributions [en]2024-03-28T19:15:55ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=GTK&diff=431904GTK2016-04-20T03:34:08Z<p>Bluerider: /* GTK+ and HTML with Broadway */</p>
<hr />
<div>[[Category:Widget toolkits]]<br />
[[cs:GTK+]]<br />
[[de:GTK+]]<br />
[[es:GTK+]]<br />
[[it:GTK+]]<br />
[[ja:GTK+]]<br />
[[ru:GTK+]]<br />
[[uk:GTK+]]<br />
[[zh-CN:GTK+]]<br />
{{Related articles start}}<br />
{{Related|Uniform Look for Qt and GTK Applications}}<br />
{{Related|Qt}}<br />
{{Related|GNU Project}}<br />
{{Related|GTK+/Development}}<br />
{{Related articles end}}<br />
From the [http://www.gtk.org GTK+ website]:<br />
:''GTK+, or the GIMP Toolkit, is a multi-platform toolkit for creating graphical user interfaces. Offering a complete set of widgets, GTK+ is suitable for projects ranging from small one-off tools to complete application suites.''<br />
<br />
GTK+, The GIMP Toolkit, was initially made by the [[GNU Project]] for the [[GIMP]] but is now a very popular toolkit with bindings for many languages. This article will explore the tools used to configure the GTK+ theme, style, icon, font and font size, and also detail manual configuration.<br />
<br />
== Installation ==<br />
<br />
Two versions of GTK+ are currently available in the [[official repositories]]. They can be [[install]]ed with the following packages:<br />
* '''GTK+ 3.x''' is available with the {{Pkg|gtk3}} package.<br />
* '''GTK+ 2.x''' is available with the {{Pkg|gtk2}} package.<br />
* '''GTK+ 1.x''' is available with the {{AUR|gtk}} package.<br />
<br />
== Themes ==<br />
<br />
In GTK+ 2, the default theme is ''Raleigh'', but Arch Linux has a custom configuration file at {{ic|/usr/share/gtk-2.0/gtkrc}}, which sets the default theme to ''Adwaita''. In GTK+ 3, the default theme is ''Adwaita'', but ''HighContrast'', ''HighContrastInverse'' and ''Raleigh'' themes are also included.<br />
<br />
To force a specific theme, you can set environment variables.<br />
* For GTK+ 2, use the {{ic|GTK2_RC_FILES}} environment variable, for example:<br />
$ GTK2_RC_FILES=/usr/share/themes/Industrial/gtk-2.0/gtkrc gimp<br />
:will launch GIMP with the Industrial theme.<br />
* For GTK+ 3, use the {{ic|GTK_THEME}} environment variable, for example:<br />
$ GTK_THEME=Adwaita:dark gnome-calculator<br />
:will launch GNOME Calculator with the dark variant of Adwaita theme.<br />
<br />
More themes can be installed from the official repositories or the [[AUR]].<br />
<br />
'''GTK+ 2 and GTK+ 3.20 or newer are supported:'''<br />
* {{App|GNOME Standard Themes|Default themes for the GNOME desktop. Includes: ''Adwaita'', ''HighContrast''|https://github.com/GNOME/gnome-themes-standard|{{Pkg|gnome-themes-standard}}}}<br />
* {{App|MATE Themes|Default themes for the MATE desktop. Includes: ''BlackMATE'', ''BlueMenta'', ''Blue-Submarine'', ''ContrastHighInverse'', ''Green-Submarine'', ''Menta'', ''TraditionalGreen'', ''TraditionalOk''|https://github.com/mate-desktop/mate-themes|{{Pkg|mate-themes}}}}<br />
* {{App|Numix|A flat and light theme with a modern look (GNOME, Openbox, Unity, Xfce).|https://github.com/shimmerproject/Numix|{{Pkg|numix-themes}}}}<br />
* {{App|Adapta| An adaptive Gtk+ theme based on Material Design Guidelines.|https://github.com/tista500/Adapta|{{AUR|adapta-gtk-theme}}}}<br />
* {{App|Arc|A flat theme with a modern look and transparent elements.|https://github.com/horst3180/arc-theme|{{AUR|gtk-theme-arc}}}}<br />
* {{App|Vertex|Theme for GTK 3, GTK 2, Gnome-Shell and Cinnamon.|https://github.com/horst3180/vertex-theme|{{AUR|vertex-themes}}}}<br />
* {{App|Zuki|Themes for GTK, gnome-shell and more.|https://github.com/lassekongo83/zuki-themes|{{AUR|zuki-themes-git}}}}<br />
<br />
'''GTK+ 2 and GTK+ 3.18 or older are supported:'''<br />
* {{App|Breeze|GTK+ version of KDE's default widget theme.|https://quickgit.kde.org/?p&#61;breeze-gtk.git|{{Pkg|breeze-gtk}}}}<br />
* {{App|Deepin|Default theme for the Deepin desktop.|https://github.com/linuxdeepin/deepin-gtk-theme|{{Pkg|deepin-gtk-theme}}}}<br />
* {{App|Albatross|A dark, smooth Xfce theme, introduced in the release of Xubuntu 9.10.|https://github.com/shimmerproject/Albatross|{{AUR|xfce-theme-albatross}}}}<br />
* {{App|Blackbird|Dark Desktop Suite for Xfce.|https://github.com/shimmerproject/Blackbird|{{AUR|xfce-theme-blackbird}}}}<br />
* {{App|Ceti-2|Theme for GTK 3, GTK 2 and Gnome-Shell.|https://github.com/horst3180/ceti-2-theme|{{AUR|ceti-2-themes}}}}<br />
* {{App|Clearlooks-Phénix|GTK3 theme visually close to Clearlooks.|https://github.com/jpfleury/clearlooks-phenix|{{AUR|clearlooks-phenix-gtk-theme}}}}<br />
* {{App|Gnome-breeze|A GTK theme created to match with the new Plasma 5 Breeze.|https://github.com/dirruk1/gnome-breeze|{{AUR|gnome-breeze-git}}}}<br />
* {{App|Greybird|A grey and blue Xfce theme, used by default in Xubuntu 12.04.|https://github.com/shimmerproject/Greybird|{{AUR|xfce-theme-greybird}}}}<br />
* {{App|Orion|A modern and light GTK theme.|https://github.com/shimmerproject/Orion|{{AUR|gtk-theme-orion}}}}<br />
<br />
'''Only GTK+ 2 is supported:'''<br />
* {{App|GTK+ Engines|Theme engines for GTK+ 2. Includes: ''Clearlooks'', ''Crux'', ''Industrial'', ''Mist'', ''Redmond'', ''ThinIce''|https://github.com/GNOME/gtk-engines|{{Pkg|gtk-engines}}}}<br />
* {{App|Xfce Gtk+ Engine|Xfce Gtk+-2.0 engine and themes|http://git.xfce.org/xfce/gtk-xfce-engine/|{{Pkg|gtk-xfce-engine}}}}<br />
* {{App|Oxygen-Gtk|Port of the default KDE widget theme (Oxygen) to GTK2|https://projects.kde.org/projects/playground/artwork/oxygen-gtk/|{{Pkg|oxygen-gtk2}}}}<br />
* {{App|Aurora Gtk Engine|Latest member of the Clearlooks family.|http://gnome-look.org/content/show.php/Aurora+Gtk+Engine?content&#61;56438|{{Pkg|gtk-engine-aurora}}}}<br />
* {{App|Openbox Themes|Various themes for the Openbox window manager.|https://www.debian.org/|{{Pkg|openbox-themes}}}}<br />
* {{App|QtCurve|A configurable set of widget styles for KDE and Gtk.|https://projects.kde.org/projects/playground/base/qtcurve|{{Pkg|qtcurve-gtk2}}}}<br />
<br />
There are a number of additional GTK+ themes in the [[AUR]]: [https://aur.archlinux.org/packages.php?K=gtk-theme search for gtk-theme], [https://aur.archlinux.org/packages.php?K=gtk2-theme search for gtk2-theme].<br />
<br />
{{Note|<br />
*Because GTK+ 3 changes rapidly, GTK+ 3 themes often require re-working after a GTK+ 3 release. For this reason, not all GTK+ 3 themes may look as intended when used with the latest GTK+ 3 version.<br />
* Some themes may require {{Pkg|librsvg}} to display correctly, but not all specify it as a dependency. Try installing it if the chosen theme looks broken.<br />
* Some themes are not usable as-is for displaying a panel (light text over light background), so you need to use the provided [http://i.imgur.com/QmeyN.png panel background].<br />
}}<br />
<br />
=== GTK+ and Qt ===<br />
<br />
If you have GTK+ and Qt (KDE) applications on your desktop then you know that their looks do not blend well. If you wish to make your GTK+ styles match your Qt styles please read [[Uniform look for Qt and GTK applications]].<br />
<br />
== Configuration tools ==<br />
<br />
Most major [[desktop environments]] provide tools to configure the GTK+ theme, icons, font and font size, and manage these settings via [http://standards.freedesktop.org/xsettings-spec/xsettings-spec-0.5.html XSettings]:<br />
* If you use [[Cinnamon]], use Themes tool (''cinnamon-settings themes''): go to ''System Settings > Themes''.<br />
* If you use [[Enlightenment]]: go to ''Settings > All > Look > Application Theme''.<br />
* If you use [[GNOME]], use GNOME Tweak Tool (''gnome-tweak-tool''): install {{Pkg|gnome-tweak-tool}}.<br />
* If you use [[MATE]], use the Appearance Preferences tool (''mate-appearance-properties''): go to ''System > Settings > Appearance''.<br />
* If you use [[Xfce]], use the Appearance tool: go to ''Settings > Appearance''.<br />
<br />
Other GUI tools generally overwrite the [[#Configuration|configuration files]].<br />
<br />
'''Both GTK+ 2 and GTK+ 3 are supported:'''<br />
* {{App|KDE GTK Configurator|Application that allows you to change style and font of GTK+ 2 and Gtk+ 3 applications.|https://projects.kde.org/kde-gtk-config|{{Pkg|kde-gtk-config}}}}<br />
:After installation, {{ic|kde-gtk-config}} can also be found in ''System Settings > Application Style > GTK''.<br />
* {{App|LXAppearance|Desktop independent GTK+ 2 and GTK+ 3 style configuration tool from the LXDE project (it does not require other parts of the LXDE desktop).|http://wiki.lxde.org/en/LXAppearance|{{Pkg|lxappearance}}}}<br />
<br />
'''Only GTK+ 2 is supported:'''<br />
* {{App|GTK+ Change Theme|Little program that lets you change your GTK+ 2.0 theme (considered a better alternative to ''switch2'').|http://plasmasturm.org/code/gtk-chtheme/|{{Pkg|gtk-chtheme}}}}<br />
* {{App|GTK+ Preference Tool|GTK+ theme selector and font switcher.|http://gtk-win.sourceforge.net/home/index.php/Main/GTKPreferenceTool|{{Pkg|gtk2_prefs}}}}<br />
* {{App|GTK+ Theme Switch|Simple GTK+ theme switcher.|http://muhri.net/nav.php3?node&#61;gts|{{Pkg|gtk-theme-switch2}}}}<br />
<br />
== Configuration ==<br />
<br />
GTK+ settings can be specified manually in configuration files, but desktop environments and applications can override these settings. Depending on GTK+ version, these files are located at:<br />
* GTK+ 2 user specific: {{ic|~/.gtkrc-2.0}}<br />
* GTK+ 2 system wide: {{ic|/etc/gtk-2.0/gtkrc}}<br />
* GTK+ 3 user specific: {{ic|$XDG_CONFIG_HOME/gtk-3.0/settings.ini}}, or {{ic|$HOME/.config/gtk-3.0/settings.ini}} if {{ic|$XDG_CONFIG_HOME}} is not set<br />
* GTK+ 3 system wide: {{ic|/etc/gtk-3.0/settings.ini}}<br />
<br />
{{Note|<br />
*See the [http://library.gnome.org/devel/gtk3/stable/GtkSettings.html#GtkSettings.properties GTK+ 3 ''GtkSettings'' properties] (and [http://library.gnome.org/devel/gtk2/stable/GtkSettings.html#GtkSettings.properties GTK+ 2 properties]) in the GTK+ programming reference manual for the full list of currently supported GTK+ configuration options.<br />
*Some of the settings described below (such as {{ic|gtk-icon-sizes}}) are deprecated and ignored since GTK+ 3.10.<br />
*If you edit your GTK+ configuration files, only newly started applications will display the changes.}}<br />
<br />
=== Basic theme configuration ===<br />
<br />
To manually change the GTK+ theme, icons, font and font size, add the following to the configuration files, for example:<br />
<br />
'''GTK+ 2:'''<br />
{{hc|~/.gtkrc-2.0|2=<br />
gtk-icon-theme-name = "Adwaita"<br />
gtk-theme-name = "Adwaita"<br />
gtk-font-name = "DejaVu Sans 11"<br />
}}<br />
<br />
'''GTK+ 3:'''<br />
{{hc|$XDG_CONFIG_HOME/gtk-3.0/settings.ini|2=<br />
[Settings]<br />
gtk-icon-theme-name = Adwaita<br />
gtk-theme-name = Adwaita<br />
gtk-font-name = DejaVu Sans 11<br />
}}<br />
<br />
{{Note|The icon theme name is the name defined in the theme's index file, ''not'' the name of its directory.}}<br />
<br />
=== Dark theme variant ===<br />
<br />
Some GTK+ 3 theme contain a dark theme variant, but it's only used by default, when the application request it explicitly. To use dark theme variant with all GTK+ 3 applications, set:<br />
<br />
gtk-application-prefer-dark-theme = true<br />
<br />
=== Keyboard shortcuts ===<br />
<br />
Keyboard shortcuts (otherwise known as ''accelerators'' in GTK+) may be changed by hovering the mouse over the respective menu item, and pressing the desired key combination. To enable this feature, set:<br />
<br />
gtk-can-change-accels = 1<br />
<br />
=== GNOME menu delay ===<br />
<br />
This setting controls the delay between pointing the mouse at a menu and that menu opening. This delay is measured in milliseconds.<br />
<br />
gtk-menu-popup-delay = 0<br />
<br />
=== Reduce widget sizes ===<br />
<br />
If you have a small screen or you just do not like big icons and widgets, you can resize things easily. <br />
<br />
To have icons without text in toolbars ([https://developer.gnome.org/gtk3/stable/gtk3-Standard-Enumerations.html#GtkToolbarStyle valid values]), use<br />
<br />
gtk-toolbar-style = GTK_TOOLBAR_ICONS<br />
<br />
To use smaller icons, use a line like this:<br />
<br />
gtk-icon-sizes = "panel-menu=16,16:panel=16,16:gtk-menu=16,16:gtk-large-toolbar=16,16\<br />
:gtk-small-toolbar=16,16:gtk-button=16,16"<br />
<br />
Or to remove icons from buttons completely:<br />
<br />
gtk-button-images = 0<br />
<br />
You can also remove icons from menus:<br />
<br />
gtk-menu-images = 0<br />
<br />
See also [http://martin.ankerl.com/2008/10/10/how-to-make-a-compact-gnome-theme/] and [http://gnome-look.org/content/show.php/Simple+eGTK?content=119812].<br />
<br />
=== File-Chooser Startup-Location ===<br />
<br />
Open the file-chooser within the '''current-working-directory''' and not with the artifical '''recent''' location. Normally the '''current-working-directory''' is '''home-directory'''.<br />
<br />
'''GTK+ 3'''<br />
<br />
Modify DConf with ''gsettings'', there is no configuration file available:<br />
<br />
$ gsettings set org.gtk.Settings.FileChooser startup-mode cwd<br />
<br />
'''GTK+ 2'''<br />
<br />
Modify {{ic|~/.config/gtk-2.0/gtkfilechooser.ini}}configuration file:<br />
<br />
{{hc|~/.config/gtk-2.0/gtkfilechooser.ini|<br />
StartupMode&#61;cwd}}<br />
<br />
=== Legacy scrolling behavior ===<br />
<br />
{{Note|This setting is not obeyed by all GTK+ applications.}}<br />
{{Tip|Legacy scrolling behaviour can be achieved reliably simply by using right click instead of left click.}}<br />
<br />
Prior to GTK+ 3.6, clicking on either side of the slider in the scrollbar would move the scrollbar in the direction of the click by approximately one page. Since GTK+ 3.6, the slider will move directly to the position of the click. This behaviour can be reverted in some applications by creating the file with the content below:<br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|<nowiki><br />
[Settings]<br />
gtk-primary-button-warps-slider = false<br />
</nowiki>}}<br />
<br />
=== Disable overlay scrollbars ===<br />
<br />
Since GTK+ 3.15, overlay scrollbars are enabled by default, meaning that scrollbars will be shown only on mouseover in GTK+ 3 applications. This behavior can be reverted by setting the following environment variable: {{ic|1=GTK_OVERLAY_SCROLLING=0}}. <br />
<br />
See [[Environment variables#Graphical applications]].<br />
<br />
==== Remove overlay scroll indicators ====<br />
<br />
The positions of the overlay scrollbars are indicated by thin dashed lines in the application window. These dashed lines will be present even when overlay scrolling is disabled using the environment variable discussed in the section above. To remove the indicator lines, create the following file:<br />
<br />
{{hc|~/.config/gtk-3.0/gtk.css|<br />
/* Remove dotted lines from GTK+ 3 applications */<br />
.undershoot.top, .undershoot.right, .undershoot.bottom, .undershoot.left { background-image: none; }<br />
}}<br />
<br />
== GTK+ and HTML with Broadway ==<br />
The GDK Broadway backend provides support for displaying GTK+ applications in a web browser, using HTML5 and web sockets. <br />
[https://developer.gnome.org/gtk3/3.8/gtk-broadway.html]<br />
<br />
When using broadwayd, specify the display number to use, prefixed with a colon, similar to X. The default display number is 1.<br />
<br />
$ display_number&#61;:5<br />
Start it.<br />
$ broadwayd $display_number <br />
<br />
Port Used on default<br />
port &#61; 8080 + $display_number<br />
<br />
Point your browser to http://127.0.0.1:port<br />
<br />
To Start apps<br />
<br />
$ GDK_BACKEND&#61;broadway BROADWAY_DISPLAY&#61;$display_number ''<<app>>''<br />
<br />
Alternatively can set address and port<br />
<br />
$ broadwayd --port $port_number --address $address $display_number<br />
<br />
== Troubleshooting ==<br />
<br />
=== Different themes between GTK+ 2 and GTK+ 3 applications ===<br />
<br />
In general, if a selected theme has support for both GTK+ 2 and GTK+ 3, the theme will be applied to all GTK+ 2 and GTK+ 3 applications. If a selected theme has support for only GTK+ 2, it will be used for GTK+ 2 applications and the default GTK+ theme will be used for GTK+ 3 applications. If the selected theme has support for only GTK+ 3, it will be used for GTK+ 3 applications and the default GTK+ theme will be used for GTK+ 2 applications. Thus for application theme consistency, it is best to use a theme which has support for both GTK+ 2 and GTK+ 3.<br />
<br />
You could find what themes installed on your system have both an GTK+ 2 and GTK+ 3 version by using this command (does not work with names containing spaces):<br />
find $(find ~/.themes /usr/share/themes/ -wholename "*/gtk-3.0" | sed -e "s/^\(.*\)\/gtk-3.0$/\1/") -wholename "*/gtk-2.0" | sed -e "s/.*\/\(.*\)\/gtk-2.0/\1"/<br />
<br />
=== Theme not applied to root applications ===<br />
<br />
As user theme files ({{ic|$XDG_CONFIG_HOME/gtk-3.0/settings.ini}}, {{ic|~/.gtkrc-2.0}}) are not read by other accounts, the selected theme will not apply to [[Running_X_apps_as_root|X applications run as root]]. Possible solutions include:<br />
<br />
* Create symlinks, e.g<br />
# ln -s /home/[username]/.gtkrc-2.0 /etc/gtk-2.0/gtkrc<br />
# ln -s /home/[username]/.config/gtk-3.0/settings.ini /etc/gtk-3.0/settings.ini<br />
* Configure system-wide theme files: {{ic|/etc/gtk-3.0/settings.ini}} (GTK+ 3) or {{ic|/etc/gtk-2.0/gtkrc}} (GTK+ 2)<br />
* Adjust the theme as root<br />
# gksu lxappearance<br />
* Use a settings daemon (this is what most desktop environments do). A desktop-agnostic variant using [http://standards.freedesktop.org/xsettings-spec/xsettings-spec-0.5.html XSettings] is available in the [[AUR]] under {{aur|xsettingsd-git}}.<br />
<br />
=== Client-side decorations ===<br />
<br />
GTK 3.12 introduced [http://blogs.gnome.org/mclasen/2013/12/05/client-side-decorations-in-themes/ client-side decorations], which move the title-bar away from the window manager. This may present issues such as [http://redmine.audacious-media-player.org/boards/1/topics/1135 double title-bars], no title-bar at all or [https://github.com/chjj/compton/issues/189 double shadows] with compositing enabled.<br />
<br />
To remove the shadow and gap around windows (for example in combination with a tiling window manager), create the following file:<br />
<br />
{{hc|~/.config/gtk-3.0/gtk.css|<nowiki>.window-frame, .window-frame:backdrop {<br />
box-shadow: 0 0 0 black;<br />
border-style: none;<br />
margin: 0;<br />
border-radius: 0;<br />
}<br />
<br />
.titlebar {<br />
border-radius: 0;<br />
}<br />
<br />
.window-frame.csd.popup {<br />
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2), 0 0 0 1px rgba(0, 0, 0, 0.13);<br />
}<br />
<br />
.header-bar {<br />
background-image: none;<br />
background-color: #ededed;<br />
box-shadow: none;<br />
}<br />
/* You may want to use this if you don't like the double title.<br />
GtkLabel.title {<br />
opacity: 0;<br />
}*/<br />
</nowiki>}}<br />
<br />
To adjust the buttons in the header bar, use the {{ic|gtk-decoration-layout}} setting. [https://developer.gnome.org/gtk3/stable/GtkSettings.html#GtkSettings--gtk-decoration-layout] The below examples removes all buttons:<br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|2=<br />
gtk-decoration-layout=menu:<br />
}}<br />
<br />
=== cedilla ç/Ç instead of ć/Ć ===<br />
<br />
See [https://bugs.launchpad.net/ubuntu/+source/gtk+2.0/+bug/518056], and [https://bugs.launchpad.net/ubuntu/+source/gtk+2.0/+bug/518056/comments/37] for a workaround using Xcompose (US international layout).<br />
<br />
===Suppress warning about accessibility bus===<br />
<br />
If you do not use any [https://wiki.gnome.org/Accessibility Gnome Accessibility] features, you may receive warnings like:<br />
<br />
WARNING **: Couldn't connect to accessibility bus:<br />
<br />
To suppress these warnings, execute programs with {{ic|1=NO_AT_BRIDGE=1}} or set that as a global [[environment variable]].<br />
<br />
=== Titlebar background color mismatch ===<br />
<br />
If you are using a [[window manager]] which uses a window decoration theme that mimics the GTK+ theme background color, you may find that the titlebar color no longer completely matches the application color in some GTK+ 3 applications. As a workaround, create the following file:<br />
{{hc|~/.config/gtk-3.0/gtk.css|<br />
/* Always use background color */<br />
GtkWindow {<br />
background-color: @theme_bg_color;<br />
}<br />
<br />
/* Fix tooltip background override */<br />
.tooltip {<br />
background-color: rgba(0, 0, 0, 0.8);<br />
}<br />
<br />
.tooltip * {<br />
background-color: transparent;<br />
}<br />
<br />
/* Fix Nautilus desktop window background override */<br />
NautilusWindow {<br />
background-color: transparent; <br />
}<br />
}}<br />
<br />
=== Wrong focus events with tiling window managers ===<br />
<br />
{{Note|1=This disables touchscreen support for GTK3 applications. [https://bugzilla.gnome.org/show_bug.cgi?id=677329#c14]}}<br />
<br />
[[Define]] {{ic|1=GDK_CORE_DEVICE_EVENTS=1}} to use GTK2 style input, instead of xinput2. [https://bugzilla.gnome.org/show_bug.cgi?id=677329#c10]<br />
<br />
=== Thumbnail support for GTK+ 2 file dialog ===<br />
<br />
Install {{AUR|gtk2-patched-filechooser-icon-view}} to have the option to view files as thumbnails instead of list in the GTK+ file chooser.<br />
<br />
== Examples ==<br />
<br />
GTK+ 2 configuration example:<br />
<br />
{{hc|~/.gtkrc-2.0|2=<br />
# GTK theme<br />
include "/usr/share/themes/Clearlooks/gtk-2.0/gtkrc"<br />
<br />
# Font<br />
style "myfont" {<br />
font_name = "DejaVu Sans 8"<br />
}<br />
widget_class "*" style "myfont"<br />
gtk-font-name = "DejaVu Sans 8"<br />
<br />
# Icon theme<br />
gtk-icon-theme-name = "Tango"<br />
<br />
# Toolbar style<br />
gtk-toolbar-style = GTK_TOOLBAR_ICONS<br />
}}<br />
<br />
GTK+ 3 example of a configuration as converted from GTK+ 2.x to GTK+ 3.x by {{Pkg|lxappearance}}:<br />
<br />
{{hc|$XDG_CONFIG_HOME/gtk-3.0/settings.ini|2=<br />
[Settings] <br />
gtk-theme-name=TraditionalOk<br />
gtk-icon-theme-name=Fog<br />
gtk-font-name=Luxi Sans 12<br />
gtk-cursor-theme-name=mate<br />
gtk-cursor-theme-size=24<br />
gtk-toolbar-style=GTK_TOOLBAR_BOTH_HORIZ<br />
gtk-toolbar-icon-size=GTK_ICON_SIZE_LARGE_TOOLBAR<br />
gtk-button-images=1<br />
gtk-menu-images=1<br />
gtk-enable-event-sounds=0<br />
gtk-enable-input-feedback-sounds=0<br />
gtk-xft-antialias=1<br />
gtk-xft-hinting=1<br />
gtk-xft-hintstyle=hintslight<br />
gtk-xft-rgba=rgb<br />
}}<br />
<br />
== See also ==<br />
<br />
* [http://www.gtk.org/ The official GTK+ website]<br />
* [[Wikipedia:GTK+|Wikipedia article about GTK+]]<br />
* [http://developer.gnome.org/gtk-tutorial/stable/ GTK+ 2.0 Tutorial]<br />
* [http://developer.gnome.org/gtk3/stable/ GTK+ 3 Reference Manual]<br />
* [http://developer.gnome.org/gtkmm-tutorial/stable/ gtkmm Tutorial]<br />
* [http://developer.gnome.org/gtkmm/stable/ gtkmm Reference Manual]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Samba&diff=429830Samba2016-04-06T02:02:40Z<p>Bluerider: /* Creating a share */ Added line needed to access user shares</p>
<hr />
<div>[[Category:Network sharing]]<br />
[[cs:Samba]]<br />
[[da:Samba]]<br />
[[de:Samba]]<br />
[[es:Samba]]<br />
[[fr:Samba]]<br />
[[it:Samba]]<br />
[[ja:Samba]]<br />
[[ru:Samba]]<br />
[[sr:Samba]]<br />
[[tr:Samba]]<br />
[[zh-CN:Samba]]<br />
[[zh-TW:Samba]]<br />
{{Related articles start}}<br />
{{Related|Samba/Tips and tricks}}<br />
{{Related|Active Directory Integration}}<br />
{{Related|Samba 4 Active Directory domain controller}}<br />
{{Related|OpenChange server}}<br />
{{Related|NFS}}<br />
{{Related articles end}}<br />
<br />
'''Samba''' is a re-implementation of the [[wikipedia:Server_Message_Block|SMB/CIFS]] networking protocol, it facilitates file and printer sharing among Linux and Windows systems as an alternative to [[NFS]]. Some users say that Samba is easily configured and that operation is very straight-forward. However, many new users run into problems with its complexity and non-intuitive mechanism. This article provides instructions for users on how to setup Samba. It is strongly suggested that the user sticks close to the following directions.<br />
<br />
== Server configuration ==<br />
<br />
To share files with Samba, [[install]] the {{Pkg|samba}} package.<br />
<br />
The Samba server is configured in {{ic|/etc/samba/smb.conf.default}}. Copy the default Samba configuration file to {{ic|/etc/samba/smb.conf}}:<br />
# cp /etc/samba/smb.conf.default /etc/samba/smb.conf<br />
Otherwise, smbd will fail to start.<br />
<br />
=== Creating a share ===<br />
<br />
Edit {{ic|/etc/samba/smb.conf}}, scroll down to the '''Share Definitions''' section. The default configuration automatically creates a share for each user's home directory. However, users cannot actually log in unless they add a users wildcard.<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
[homes]<br />
comment = Home Directories<br />
browseable = no<br />
writable = yes<br />
valid users = %S<br />
}}<br />
<br />
It also creates a share for printers by default. There are a number of commented sample configurations included. More information about available options for shared resources can be found in {{ic|man smb.conf}}. [http://www.samba.org/samba/docs/man/manpages-3/smb.conf.5.html There] is also an on-line version available.<br />
<br />
On Windows side, be sure to change {{ic|smb.conf}} to the in-use Windows Workgroup (default: {{ic|WORKGROUP}}).<br />
<br />
=== Starting services ===<br />
<br />
To provide basic file sharing through SMB [[start/enable]] {{ic|smbd.service}} and/or {{ic|nmbd.service}} services. See [http://www.samba.org/samba/docs/man/manpages-3/smbd.8.html smbd] and [http://www.samba.org/samba/docs/man/manpages-3/nmbd.8.html nmbd] manpages for details, as the {{ic|nmbd.service}} service may not always be required.<br />
<br />
{{Tip|Instead of having the service running since boot, you can enable {{ic|smbd.socket}} so the daemon is started on the first incoming connection. Do not forget to disable {{ic|smbd.service}}.}}<br />
<br />
=== Creating usershare path ===<br />
{{Note|This is an optional feature. Skip this section if you do not need it.}}<br />
<br />
"Usershare" is a feature that gives non-root users the capability to add, modify, and delete their own share definitions. <br />
<br />
This creates the usershare directory in {{ic|/var/lib/samba}}:<br />
<br />
# mkdir -p /var/lib/samba/usershare<br />
<br />
This makes the group sambashare:<br />
<br />
# groupadd -r sambashare<br />
<br />
This changes the owner of the directory and group you just created to root:<br />
<br />
# chown root:sambashare /var/lib/samba/usershare<br />
<br />
This changes the permissions of the usershare directory so that users in the group sambashare can read, write and execute files:<br />
<br />
# chmod 1770 /var/lib/samba/usershare<br />
<br />
Set the following variables in {{ic|smb.conf}} configuration file: <br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
[global]<br />
usershare path = /var/lib/samba/usershare<br />
usershare max shares = 100<br />
usershare allow guests = yes<br />
usershare owner only = yes<br />
...<br />
}}<br />
<br />
Add your user to the ''sambashare'' group. Replace {{ic|''your_username''}} with the name of your user:<br />
<br />
# gpasswd sambashare -a ''your_username''<br />
<br />
Restart {{ic|smbd.service}} and {{ic|nmbd.service}} services.<br />
<br />
Log out and log back in. You should now be able to configure your samba share using GUI. For example, in [[Thunar]] you can right click on any directory and share it on the network. If you want to share pathes inside your home directory you must make it listable for the group others.<br />
<br />
=== Adding a user ===<br />
<br />
You may use an existing user account or create a [[Users and groups#User management|Linux user account]] as Samba user.<br />
<br />
Samba uses a password separate from that of the Linux user accounts. Replace {{ic|samba_user}} with the chosen Samba user account:<br />
<br />
# pdbedit -a -u ''samba_user''<br />
<br />
{{Note|Depending on the [https://www.samba.org/samba/docs/man/manpages-3/smb.conf.5.html#SERVERROLE server role], existing [[File permissions and attributes]] may need to be altered for the Samba user account.}}<br />
<br />
=== Changing Samba user's password ===<br />
<br />
To change a user's password, use {{ic|smbpasswd}}:<br />
<br />
# smbpasswd ''samba_user''<br />
<br />
=== Required ports ===<br />
<br />
If you are using a [[firewall]], do not forget to open required ports (usually 137-139 + 445). For a complete list please check [https://wiki.samba.org/index.php/Samba_port_usage Samba port usage].<br />
<br />
=== Sample configuration ===<br />
See {{ic|man smb.conf}} for details and explanation of configuration options. There is also an [http://www.samba.org/samba/docs/man/manpages-3/smb.conf.5.html online version] available.<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
deadtime = 60 ; This is useful to stop a server's resources being exhausted by a large number of inactive connections<br />
disable netbios = yes ; Disable netbios announcing<br />
dns proxy = no ; nmbd spawns a second copy of itself to do the DNS name lookup requests on 'yes'<br />
hosts allow = 192.168.1. 127. 10. ; This parameter is a comma, space, or tab delimited set of hosts which are permitted to access a service<br />
invalid users = root ; This is a list of users that should not be allowed to login to this service<br />
security = user ; Use as standalone file server<br />
map to guest = Bad User ; Means user logins with an invalid password are rejected, or allow guest login and mapped into the guest account<br />
max connections = 100 ; Number of simultaneous connections to a service to be limited<br />
workgroup = WORKGROUP ; Workgroup the server will appear to be in when queried by clients<br />
<br />
; Uncomment the following lines to disable printer support<br />
;load printers = no<br />
;printing = bsd<br />
;printcap name = /dev/null<br />
;disable spoolss = yes<br />
<br />
; Default permissions for all shares <br />
inherit owner = yes ; Take the ownership of the parent directory when creating files/folders<br />
create mask = 0664 ; Create file mask<br />
directory mask = 0775 ; Create director mask<br />
force create mode = 0664 ; Force create file mask<br />
force directory mode = 0775 ; Force create directory mask<br />
<br />
; Private Share<br />
[private] ; translate into: \\server\private<br />
comment = My Private Share ; Seen next to a share when a client queries the server<br />
path = /path/to/data ; Directory to which the user of the service is to be given access<br />
read only = no ; An inverted synonym to writeable.<br />
valid users = user1 user2 @group1 @group2; restrict a service to a particular set of users and/or groups<br />
<br />
; Public Share<br />
;[public]<br />
; comment = My Public Share<br />
; path = /path/to/public<br />
; read only = yes<br />
; guest ok = yes; No password required to connect to the service<br />
</nowiki>}}<br />
<br />
Restart the {{ic|smbd}} service to apply configuration changes.<br />
{{note|Connected clients may need to reconnect before configuration changes take effect.}}<br />
<br />
=== Validate configuration ===<br />
The command {{ic|testparm}} validates the configuration of {{ic|smb.conf}}:<br />
<br />
# testparm -s<br />
<br />
== Client configuration ==<br />
<br />
For a lightweight method (without support for listing public shares, etc.), only install {{Pkg|cifs-utils}} to provide {{ic|/usr/bin/mount.cifs}}.<br />
<br />
Install {{Pkg|smbclient}} for an ftp-like command line interface. See {{ic|man smbclient}} for commonly used commands.<br />
<br />
Depending on the [[desktop environment]], GUI methods may be available. See [[#File manager configuration]] for use with a file manager.<br />
<br />
{{Note|After installing {{Pkg|cifs-utils}} or {{Pkg|smbclient}}, load the {{ic|cifs}} [[kernel module]] or reboot to prevent mount fails.}}<br />
<br />
=== List Public Shares ===<br />
To following command lists public shares on a server:<br />
<br />
$ smbclient -L ''hostname'' -U%<br />
<br />
=== WINS host names ===<br />
<br />
The {{pkg|smbclient}} package provides a driver to resolve host names using WINS. To enable it, add “wins” to the “hosts” line in /etc/nsswitch.conf.<br />
<br />
=== Manual mounting ===<br />
<br />
Create a mount point for the share:<br />
<br />
# mkdir /mnt/''mountpoint''<br />
<br />
Mount the share using {{ic|mount.cifs}} as {{ic|type}}. Not all the options listed below are needed or desirable:<br />
{{bc|1=<br />
# mount -t cifs //''SERVER''/''sharename'' /mnt/''mountpoint'' -o user=''username'',password=''password'',uid=''username'',gid=''group'',workgroup=''workgroup'',ip=''serverip'',iocharset=''utf8''<br />
}}<br />
<br />
To allow users to mount it as long as the mount point resides in a directory controllable by the user; i.e. the user's home, append the {{ic|users}} mount option.<br />
<br />
{{Note|The option is user'''s''' (plural). For other filesystem types handled by mount, this option is usually ''user''; sans the "'''s'''".}}<br />
{{Warning|Using {{ic|uid}} and/or {{ic|gid}} as mount options may cause I/O errors, it's recommended to set/check the [[File permissions and attributes]] instead.}}<br />
<br />
''SERVER''<br />
: The server name.<br />
<br />
''sharename''<br />
: The shared directory.<br />
<br />
''mountpoint''<br />
: The local directory where the share will be mounted.<br />
<br />
{{ic|<nowiki>-o [options]</nowiki>}}<br />
: See {{ic|man mount.cifs}} for more information.<br />
<br />
{{Note|<br />
* The output "mount error(13): Permission denied", might be due to a bug in mount.cifs. See the following bug report. https://bugs.archlinux.org/task/43015#comment130771<br />
Try specifying the option <nowiki>"sec=ntlmv2"</nowiki> as workaround.<br />
* Abstain from using a trailing {{ic|/}}. {{ic|//''SERVER''/''sharename'''''/'''}} will not work.<br />
* If your mount does not work stable, stutters or freezes, try to enable different SMB protocol version with {{ic|1=vers=}} option. For example, {{ic|1=vers=2.0}} for Windows Vista mount.<br />
* If having timeouts on a mounted network share with cifs on a shutdown, see [[WPA supplicant#Problem with mounted network shares (cifs) and shutdown (Date: 1st Oct. 2015)]].<br />
}}<br />
<br />
===== Storing Share Passwords =====<br />
Storing passwords in a world readable file is not recommended. A safer method is to create a credentials file:<br />
{{hc|/path/to/credentials/share|2=<br />
username=''myuser''<br />
password=''mypass''<br />
}}<br />
Replace {{ic|<nowiki>username=myuser,password=mypass</nowiki>}} with {{ic|<nowiki>credentials=/path/to/credentials/share</nowiki>}}.<br />
<br />
The credential file should explicitly readable/writeable to root:<br />
# chmod 600 /path/to/credentials/share<br />
<br />
=== Automatic mounting ===<br />
{{Note|You may need to [[enable]] {{ic|systemd-networkd-wait-online.service}} or {{ic| NetworkManager-wait-online.service}} (depending on your setup) to proper enable booting on start-up.}}<br />
<br />
==== As mount entry ====<br />
<br />
This is an simple example of a {{ic|cifs}} [[fstab|mount entry]] that requires authentication:<br />
{{hc|/etc/fstab|2=<br />
//''SERVER''/''sharename'' /mnt/''mountpoint'' cifs username=''myuser'',password=''mypass'' 0 0<br />
}}<br />
<br />
{{Note|Space in sharename should be replaced by {{ic|\040}} (ASCII code for space in octal). For example, {{ic|//''SERVER''/share name}} on the command line should be {{ic|//''SERVER''/share\040name}} in {{ic|/etc/fstab}}.}}<br />
<br />
To speed up the service on boot, add the {{ic|1=x-systemd.automount}} option to the entry:<br />
{{hc|/etc/fstab|2=<br />
//''SERVER''/''SHARENAME'' /mnt/''mountpoint'' cifs credentials=''/path/to/smbcredentials/share'',x-systemd.automount 0 0<br />
}}<br />
<br />
==== As systemd unit ====<br />
Create a new {{ic|.mount}} file inside {{ic|/etc/systemd/system}}, e.g. {{ic|mnt-myshare.mount}}.<br />
<br />
{{ic|1=Requires=}} replace (if needed) with your [[:Category:Network_configuration|Network configuration]].<br />
<br />
{{ic|1=What=}} path to share<br />
<br />
{{ic|1=Where=}} path to mount the share<br />
<br />
{{ic|1=Options=}} share mounting options<br />
<br />
{{hc|/etc/systemd/system/mnt-myshare.mount|<nowiki><br />
[Unit]<br />
Description=Mount Share at boot<br />
Requires=systemd-networkd.service<br />
After=network-online.target<br />
Wants=network-online.target<br />
<br />
[Mount]<br />
What=//server/share<br />
Where=/mnt/myshare<br />
Options=credentials=/etc/samba/creds/myshare,iocharset=utf8,rw,x-systemd.automount<br />
Type=cifs<br />
TimeoutSec=30<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
To use {{ic|myshare.mount}}, [[start]] the unit and [[enable]] it to run on system boot.<br />
<br />
==== smbnetfs ====<br />
<br />
{{Note|1=smbnetfs needs an intact Samba server setup.<br />
See above on how to do that.}}<br />
<br />
First, check if you can see all the shares you are interested in mounting:<br />
$ smbtree -U ''remote_user''<br />
<br />
If that does not work, find and modify the following line<br />
in {{ic|/etc/samba/smb.conf}} accordingly:<br />
<br />
domain master = auto<br />
<br />
Now [[restart]] {{ic|smbd.service}} and {{ic|nmbd.service}}.<br />
<br />
If everything works as expected, [[pacman#Installing specific packages|install]] {{Pkg|smbnetfs}} from the official repositories.<br />
<br />
Then, add the following line to {{ic|/etc/fuse.conf}}:<br />
<br />
user_allow_other<br />
<br />
Now copy the directory {{ic|/etc/smbnetfs/.smb}} to your home directory:<br />
<br />
$ cp -a /etc/smbnetfs/.smb ~<br />
<br />
Then create a link to {{ic|smb.conf}}:<br />
<br />
$ ln -sf /etc/samba/smb.conf ~/.smb/smb.conf<br />
<br />
If a username and a password are required to access some of the shared folders, edit {{ic|~/.smb/smbnetfs.auth}}<br />
to include one or more entries like this:<br />
<br />
{{hc|~/.smb/smbnetfs.auth|<br />
auth "hostname" "username" "password"<br />
}}<br />
<br />
It is also possible to add entries for specific hosts to be mounted by smbnetfs, if necessary.<br />
More details can be found in {{ic|~/.smb/smbnetfs.conf}}.<br />
<br />
If you are using the Dolphin or Nautilus file managers, you may want to add the following to {{ic|~/.smb/smbnetfs.conf}} to avoid "Disk full" errors as smbnetfs by default will report 0 bytes of free space:<br />
{{hc|~/.smb/smbnetfs.conf|<br />
free_space_size 1073741824<br />
}}<br />
<br />
When you are done with the configuration, you need to run<br />
$ chmod 600 ~/.smb/smbnetfs.*<br />
Otherwise, smbnetfs complains about 'insecure config file permissions'.<br />
<br />
Finally, to mount your Samba network neighbourhood to a directory of your choice, call<br />
$ smbnetfs ''mount_point''<br />
<br />
===== Daemon =====<br />
<br />
The Arch Linux package also maintains an additional system-wide operation mode for smbnetfs. To enable it, you need to make the<br />
said modifications in the directoy {{ic|/etc/smbnetfs/.smb}}.<br />
<br />
Then, you can start and/or enable the {{ic|smbnetfs}} [[daemon]] as usual. The system-wide mount point is at {{ic|/mnt/smbnet/}}.<br />
<br />
==== autofs ====<br />
<br />
See [[Autofs]] for information on the kernel-based automounter for Linux.<br />
<br />
=== File manager configuration ===<br />
<br />
==== GNOME Files, Nemo, Caja, Thunar and PCManFM ====<br />
<br />
In order to access samba shares through GNOME Files, Nemo, Caja, Thunar or PCManFM, install the {{Pkg|gvfs-smb}} package, available in the [[official repositories]].<br />
<br />
Press {{ic|Ctrl+l}} and enter {{ic|smb://''servername''/''share''}} in the location bar to access your share.<br />
<br />
The mounted share is likely to be present at {{ic|/run/user/''your_UID''/gvfs}} or {{ic|~/.gvfs}} in the filesystem.<br />
<br />
==== KDE ====<br />
<br />
KDE, has the ability to browse Samba shares built in. Therefore do not need any additional packages. However, for a GUI in the KDE System Settings, install the {{Pkg|kdenetwork-filesharing}} package from the official repositories.<br />
<br />
If when navigating with Dolphin you get a "Time Out" Error, you should uncomment and edit this line in smb.conf:{{bc|1=name resolve order = lmhosts bcast host wins}}<br />
as shown in this [http://ubuntuforums.org/showthread.php?t=1605499 page].<br />
<br />
==== Other graphical environments ====<br />
<br />
There are a number of useful programs, but they may need to have packages created for them. This can be done with the Arch package build system. The good thing about these others is that they do not require a particular environment to be installed to support them, and so they bring along less baggage.<br />
<br />
* {{Pkg|pyneighborhood}} is available in the official repositories.<br />
* LinNeighborhood, RUmba, xffm-samba plugin for Xffm are not available in the official repositories or the AUR. As they are not officially (or even unofficially supported), they may be obsolete and may not work at all.<br />
<br />
== Tips and tricks ==<br />
=== Block certain file extensions on Samba share ===<br />
{{Note|Setting this parameter will affect the performance of Samba, as it will be forced to check all files and directories for a match as they are scanned.}}<br />
Samba offers an option to block files with certain patterns, like file extensions. This option can be used to prevent dissemination of viruses or to dissuade users from wasting space with certain files. More information about this option can be found in {{ic|man smb.conf}}.<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
[myshare]<br />
comment = Private<br />
path = /mnt/data<br />
read only = no<br />
veto files = /*.exe/*.com/*.dll/*.bat/*.vbs/*.tmp/*.mp3/*.avi/*.mp4/*.wmv/*.wma/<br />
}}<br />
<br />
=== Discovering network shares ===<br />
If nothing is known about other systems on the local network, and automated tools such as [[#smbnetfs|smbnetfs]] are not available, the following methods allow one to manually probe for Samba shares.<br />
<br />
1. First, install {{Pkg|nmap}} and {{Pkg|smbclient}} using [[pacman]]:<br />
# pacman -S nmap smbclient<br />
<br />
2. {{ic|nmap}} checks which ports are open:<br />
# nmap -p 139 -sT 192.168.1.*<br />
<br />
In this case, a scan on the 192.168.1.* IP address range and port 139 has been performed, resulting in:<br />
{{hc<br />
|$ nmap -sT 192.168.1.*<br />
|Starting nmap 3.78 ( http://www.insecure.org/nmap/ ) at 2005-02-15 11:45 PHT<br />
Interesting ports on 192.168.1.1:<br />
(The 1661 ports scanned but not shown below are in state: closed)<br />
PORT STATE SERVICE<br />
'''139/tcp open netbios-ssn'''<br />
5000/tcp open UPnP<br />
<br />
Interesting ports on 192.168.1.5:<br />
(The 1662 ports scanned but not shown below are in state: closed)<br />
PORT STATE SERVICE<br />
6000/tcp open X11<br />
<br />
Nmap run completed -- 256 IP addresses (2 hosts up) scanned in 7.255 seconds<br />
}}<br />
<br />
The first result is another system; the second happens to be the client from where this scan was performed.<br />
<br />
3. Now that systems with port 139 open are revealed, use {{ic|nmblookup}} to check for NetBIOS names: <br />
{{hc<br />
|$ nmblookup -A 192.168.1.1<br />
|Looking up status of 192.168.1.1<br />
PUTER <00> - B <ACTIVE><br />
HOMENET <00> - <GROUP> B <ACTIVE><br />
PUTER <03> - B <ACTIVE><br />
'''PUTER <20> - B <ACTIVE>'''<br />
HOMENET <1e> - <GROUP> B <ACTIVE><br />
USERNAME <03> - B <ACTIVE><br />
HOMENET <1d> - B <ACTIVE><br />
MSBROWSE <01> - <GROUP> B <ACTIVE><br />
}}<br />
<br />
Regardless of the output, look for '''<20>''', which shows the host with open services.<br />
<br />
4. Use {{ic|smbclient}} to list which services are shared on ''PUTER''. If prompted for a password, pressing enter should still display the list:<br />
{{hc<br />
|$ smbclient -L \\PUTER<br />
|<nowiki><br />
Sharename Type Comment<br />
--------- ---- -------<br />
MY_MUSIC Disk<br />
SHAREDDOCS Disk<br />
PRINTER$ Disk<br />
PRINTER Printer<br />
IPC$ IPC Remote Inter Process Communication<br />
<br />
Server Comment<br />
--------- -------<br />
PUTER<br />
<br />
Workgroup Master<br />
--------- -------<br />
HOMENET PUTER<br />
</nowiki>}}<br />
<br />
=== Remote control of Windows computer ===<br />
Samba offers a set of tools for communication with Windows. These can be handy if access to a Windows computer through remote desktop is not an option, as shown by some examples.<br />
<br />
Send shutdown command with a comment:<br />
<br />
$ net rpc shutdown -C "comment" -I IPADDRESS -U USERNAME%PASSWORD<br />
A forced shutdown instead can be invoked by changing -C with comment to a single -f. For a restart, only add -r, followed by a -C or -f.<br />
<br />
Stop and start services:<br />
<br />
$ net rpc service stop SERVICENAME -I IPADDRESS -U USERNAME%PASSWORD<br />
<br />
To see all possible net rpc command:<br />
<br />
$ net rpc<br />
<br />
== Troubleshooting ==<br />
<br />
=== Failed to start Samba SMB/CIFS server ===<br />
<br />
Check if the permissions are set correctly for {{ic|/var/cache/samba/}} and restart the {{ic|smbd.service}} or {{ic|smbd.socket}}:<br />
# chmod 0755 /var/cache/samba/msg<br />
<br />
=== Unable to overwrite files, permissions errors ===<br />
Possible solutions:<br />
*Append the mount option {{ic|nodfs}} to the {{ic|/etc/fstab}} [[#Add_Share_to_.2Fetc.2Ffstab|entry]].<br />
*Add {{ic|<nowiki>msdfs root = no</nowiki>}} to the {{ic|[global]}} section of the server's {{ic|/etc/samba/smb.conf}}.<br />
<br />
=== Windows clients keep asking for password even if Samba shares are created with guest permissions ===<br />
Set {{ic|map to guest}} inside the {{ic|global}} section of {{ic|/etc/samba/smb.conf}}:<br />
map to guest = Bad User<br />
<br />
=== Windows 7 connectivity problems - mount error(12): cannot allocate memory ===<br />
<br />
A known Windows 7 bug that causes "mount error(12): cannot allocate memory" on an otherwise perfect cifs share on the Linux end can be fixed by setting a few registry keys on the Windows box as follows:<br />
<br />
*{{ic|HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\LargeSystemCache}} (set to {{ic|1}})<br />
*{{ic|HKLM\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters\Size}} (set to {{ic|3}})<br />
<br />
Alternatively, start Command Prompt in Admin Mode and execute the following:<br />
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management" /v "LargeSystemCache" /t REG_DWORD /d 1 /f<br />
reg add "HKLM\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters" /v "Size" /t REG_DWORD /d 3 /f<br />
<br />
Do one of the following for the settings to take effect:<br />
* Restart Windows<br />
* Restart the Server service via services.msc<br />
* From the Command Prompt run: 'net stop lanmanserver' and 'net start lanmanserver' - The server may automatically restart after stopping it.<br />
<br />
{{Note|Googling will reveal another tweak recommending users to add a key modifying the "IRPStackSize" size. This is incorrect for fixing this issue under Windows 7. Do not attempt it.}}<br />
<br />
[http://alan.lamielle.net/2009/09/03/windows-7-nonpaged-pool-srv-error-2017 Original article].<br />
<br />
=== Trouble accessing a password-protected share from Windows ===<br />
<br />
{{Note|This needs to be added to the '''local smb.conf''', not to the server's smb.conf}}<br />
<br />
For trouble accessing a password protected share from Windows, try adding this to {{ic|/etc/samba/smb.conf}}:[http://blogs.computerworld.com/networking_nightmare_ii_adding_linux]<br />
<br />
[global]<br />
# lanman fix<br />
client lanman auth = yes<br />
client ntlmv2 auth = no<br />
<br />
=== Getting a dialog box up takes a long time ===<br />
<br />
I had a problem that it took ~30 seconds to get a password dialog box up when trying to connect from both Windows XP/Windows 7. Analyzing the error.log on the server I saw:<br />
<br />
[2009/11/11 06:20:12, 0] printing/print_cups.c:cups_connect(103)<br />
Unable to connect to CUPS server localhost:631 - Interrupted system call<br />
<br />
This keeps samba from asking cups and also from complaining about /etc/printcap missing:<br />
<br />
printing = bsd<br />
printcap name = /dev/null<br />
<br />
=== Error: Failed to retrieve printer list: NT_STATUS_UNSUCCESSFUL ===<br />
<br />
If you are a home user and using samba purely for file sharing from a server or NAS, you are probably not interested in sharing printers through it. If so, you can prevent this error from occurring by adding the following lines to your {{ic|/etc/samba/smb.conf}}:<br />
{{bc|<nowiki><br />
load printers = No<br />
printing = bsd<br />
printcap name = /dev/null<br />
disable spoolss = Yes<br />
</nowiki>}}<br />
[[Restart]] the samba service, {{ic|smbd.service}}, and then check your logs:<br />
{{bc|cat /var/log/samba/smbd.log}}<br />
and the error should now no longer be appearing.<br />
<br />
=== Sharing a folder fails ===<br />
<br />
It means that while you are sharing a folder from ''Dolphin'' (file manager) and everything seems ok at first, after restarting ''Dolphin'' the share icon is gone from the shared folder, and also some output like this in terminal (''Konsole'') output:<br />
<br />
‘net usershare’ returned error 255: net usershare: usershares are currently disabled<br />
<br />
To fix it, enable usershare as described in [[#Creating usershare path]].<br />
<br />
=== "Browsing" network fails with "Failed to retrieve share list from server" ===<br />
And you are using a firewall (iptables) because you do not trust your local (school, university, hotel) local network. This may be due to the following: When the smbclient is browsing the local network it sends out a broadcast request on udp port 137. The servers on the network then reply to your client but as the source address of this reply is different from the destination address iptables saw when sending the request for the listing out, iptables will not recognize the reply as being "ESTABLISHED" or "RELATED", and hence the packet is dropped. A possible solution is to add:{{bc|<br />
iptables -t raw -A OUTPUT -p udp -m udp --dport 137 -j CT --helper netbios-ns<br />
}}<br />
to your iptables setup.<br />
<br />
=== You are not the owner of the folder ===<br />
<br />
Simply try to reboot the system.<br />
<br />
=== protocol negotiation failed: NT_STATUS_INVALID_NETWORK_RESPONSE ===<br />
<br />
The client probably does not have access to shares. Make sure clients' IP address is in {{ic|1=hosts allow =}} line in {{ic|/etc/samba/smb.conf}}.<br />
<br />
=== Connection to SERVER failed: (Error NT_STATUS_UNSUCCESSFUL) ===<br />
<br />
You are probably passing wrong server name to {{ic|smbclient}}. To find out the server name, run {{ic|hostnamectl}} on the server and look at "Transient hostname" line<br />
<br />
=== Connection to SERVER failed: (Error NT_STATUS_CONNECTION_REFUSED) ===<br />
<br />
Make sure that the server has started. The shared directories should exist and be accessible.<br />
<br />
== See also ==<br />
<br />
* [http://www.samba.org/samba/docs/SambaIntro.html Samba: An Introduction]<br />
* [http://www.samba.org/ Official Samba site]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=QEMU&diff=389916QEMU2015-08-04T04:33:37Z<p>Bluerider: /* With loop module autodetecting partitions */ Need -P to mount partitions</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 />
[[Install]] {{Pkg|qemu}}.<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 />
From [[official repositories]]:<br />
* {{Pkg|virt-manager}} (part of [[libvirt]])<br />
* {{Pkg|gnome-boxes}}<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
From [[AUR]]:<br />
* {{AUR|aqemu-git}}<br />
* {{AUR|virtualbricks}}<br />
<br />
== Creating new virtualized system ==<br />
<br />
{{Tip|If you are virtualizing Arch Linux, it is possible to create a disk image directly on an existing Arch Linux system, see [[Creating Arch Linux disk image#Install Arch Linux in a disk image without the installation media]] for details.}}<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 from the [[AUR]] 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 />
==== 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 />
{{Tip|If you cannot get a DHCP address in the host, it might be because [[iptables]] is up by default in the bridge.}}<br />
<br />
* It is recommended for performance and security reasons to disable the 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 />
=== Networking with VDE2 ===<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [http://wiki.virtualsquare.org/wiki/index.php/Main_Page the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-i386 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep -f vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be executable<br />
<br />
# chmod u+x /etc/systemd/scripts/qemu-network-env<br />
<br />
You can [[start]] {ic|qemu-network-env.service}} as usual.<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
== Graphics ==<br />
<br />
{{expansion|{{ic|cirrus}} is mentioned but doesn't have a section}}<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|cirrus}}, {{ic|vmware}}, {{ic|qxl}}, and {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels.<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, these condition must be met:<br />
<br />
* [[#Spice support|Spice]] has to be enabled on the host system.<br />
* A [http://www.spice-space.org/download.html guest driver] has to be installed on the guest system. On an Arch guest it is enough to install {{AUR|xf86-video-qxl}} from the [[AUR]].<br />
* The virtual machine has to be started with {{ic|-vga qxl}} switch.<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 [[Persistent_block_device_naming#By-uuid|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 />
==== Block device drivers ====<br />
<br />
Preparing a 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 />
Then connect with the the spice client<br />
<br />
$ spicec -h 127.0.0.1 -p 5930<br />
<br />
{{Tip|<br />
* Spice guest drivers can be downloaded [http://www.spice-space.org/download.html here] in the ''Guest'' section.<br />
* The key combination to escape mouse and keyboard grab can be configured, the default is {{ic|Shift+F12}}: {{bc|1=$ spicec --hotkeys release-cursor=ctrl+alt}}<br />
* To disable mouse and keyboard grabbing (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 />
}}<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 8.<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 [[:Category:Hypervisors|hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<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>Blueriderhttps://wiki.archlinux.org/index.php?title=Talk:Mirrors&diff=367335Talk:Mirrors2015-03-27T02:00:36Z<p>Bluerider: /* rsync errors in tier2 mirrors */ Fixed some typos</p>
<hr />
<div>== warn about pacman -Syyu step ==<br />
<br />
:''Moved from [[Talk:Installation guide]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 21:43, 21 December 2014 (UTC)<br />
<br />
on some systems (vmware, fusion, maybe others), after changing the mirrorlist, pacman -Syyu results in complete system corruption and dm errors. I would add a sentence suggesting delaying this to after the install. [[User:Iaw4|Iaw4]] ([[User talk:Iaw4|talk]]) 13:07, 20 December 2014 (UTC) iaw4<br />
<br />
:There's no mention of pacman -Syyu in this guide, maybe you mean [[Mirrors#Force_pacman_to_refresh_the_package_lists]], and you should be able to add a note there. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:51, 21 December 2014 (UTC)<br />
<br />
::Yeah, though the cause of this issue is not clear (see [https://bbs.archlinux.org/viewtopic.php?pid=1485907] and [https://bbs.archlinux.org/viewtopic.php?id=190422]) so I wouldn't add a note just yet. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 21:40, 21 December 2014 (UTC)<br />
<br />
=== rsync errors in tier2 mirrors ===<br />
<br />
It is possible for arch mirrors to be in an inconsistent state if rsync fails at some point. This is due to mirrors not generating their own package databases but rather copying the one from lower tier mirrors. In these cases, trying to grab a package from these mirrors may result in a 404 error due to incomplete syncing. The method described in [https://wiki.archlinux.org/index.php/DeveloperWiki:NewMirrors#2-tier_mirroring_scheme Tier 2 requirements] does not adequately protect this case.<br />
<br />
The following code will re-run rsync if it ever fails to ensure mirrors are properly synced.<br />
<br />
{{bc|<nowiki><br />
RET=1<br />
COUNTER=100<br />
until [[ RET -eq 0 && COUNTER -gt 0 ]]; do<br />
rsync -rtlH --safe-links --delete-after --progress -h --timeout=600 --contimeout=60 -p \<br />
--delay-updates --no-motd --bwlimit=4096 \<br />
--temp-dir="/tmp" \<br />
--exclude='*.links.tar.gz*' \<br />
--exclude='/other' \<br />
--exclude='/sources' \<br />
--exclude='/iso' \<br />
'rsync://mirror.pkgbuild.com/packages/' \<br />
"/srv/repo" &&<br />
RET=0<br />
COUNTER=$[COUNTER-1]<br />
done;<br />
</nowiki>}}</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Talk:Mirrors&diff=367321Talk:Mirrors2015-03-26T21:55:39Z<p>Bluerider: /* warn about pacman -Syyu step */</p>
<hr />
<div>== warn about pacman -Syyu step ==<br />
<br />
:''Moved from [[Talk:Installation guide]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 21:43, 21 December 2014 (UTC)<br />
<br />
on some systems (vmware, fusion, maybe others), after changing the mirrorlist, pacman -Syyu results in complete system corruption and dm errors. I would add a sentence suggesting delaying this to after the install. [[User:Iaw4|Iaw4]] ([[User talk:Iaw4|talk]]) 13:07, 20 December 2014 (UTC) iaw4<br />
<br />
:There's no mention of pacman -Syyu in this guide, maybe you mean [[Mirrors#Force_pacman_to_refresh_the_package_lists]], and you should be able to add a note there. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:51, 21 December 2014 (UTC)<br />
<br />
::Yeah, though the cause of this issue is not clear (see [https://bbs.archlinux.org/viewtopic.php?pid=1485907] and [https://bbs.archlinux.org/viewtopic.php?id=190422]) so I wouldn't add a note just yet. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 21:40, 21 December 2014 (UTC)<br />
<br />
=== rsync errors in tier2 mirrors ===<br />
<br />
It is possible for arch mirrors to be in an inconsistent state if rsync fails at some point. This is due to mirrors not generating their own package databases but rather copying the one from lower tier mirrors. In these cases, trying to grab a package from these mirrors may result in a 404 error due to incomplete syncing. The method described in [https://wiki.archlinux.org/index.php/DeveloperWiki:NewMirrors#2-tier_mirroring_scheme lTier 2 requirements] does not adequately protect this case.<br />
<br />
The following code will re-run rsync if it ever fails to ensure mirrors are properly synced.<br />
<br />
{{bc|<nowiki><br />
RET=1<br />
COUNTER=100<br />
until [[ RET -eq 0 && COUNTER -gt 0]]; do<br />
rsync -rtlH --safe-links --delete-after --progress -h --timeout=600 --contimeout=60 -p \<br />
--delay-updates --no-motd --bwlimit=4096 \<br />
--temp-dir="/tmp" \<br />
--exclude='*.links.tar.gz*' \<br />
--exclude='/other' \<br />
--exclude='/sources' \<br />
--exclude='/iso' \<br />
'rsync://mirror.pkgbuild.com/packages/' \<br />
"/srv/repo" &&<br />
RET=0<br />
COUNTER=$[COUNTER-1]<br />
done;<br />
</nowiki>}}</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Improving_performance&diff=367023Improving performance2015-03-25T00:57:25Z<p>Bluerider: /* Running root on ram overlay */ Added concept of running on a root overlay and AUR package link.</p>
<hr />
<div>[[Category:Hardware]]<br />
[[Category:System administration]]<br />
[[ar:Maximizing Performance]]<br />
[[es:Maximizing Performance]]<br />
[[ja:パフォーマンスの最大化]]<br />
[[ru:Maximizing Performance]]<br />
[[zh-CN:Maximizing Performance]]<br />
{{Related articles start}}<br />
{{Related|ccache}}<br />
{{Related|Improve pacman performance}}<br />
{{Related|SSH#Speeding up SSH}}<br />
{{Related|LibreOffice#Speed up Libreoffice}}<br />
{{Related|Openoffice#Speed up OpenOffice}}<br />
{{Related|Laptop}}<br />
{{Related|Swap#Swappiness}}<br />
{{Related|Preload}}<br />
{{Related|Improve boot performance}}<br />
{{Related articles end}}<br />
This article provides information on basic system diagnostics relating to performance as well as steps that may be taken to reduce resource consumption or to otherwise optimize the system with the end-goal being either perceived or documented improvements to a system's performance.<br />
<br />
== The basics ==<br />
<br />
=== Know your system ===<br />
<br />
The best way to tune a system is to target bottlenecks, or subsystems which limit overall speed. The system specifications can help identify them.<br />
<br />
* If the computer becomes slow when large applications (such as OpenOffice.org and Firefox) run at the same time, check if the amount of RAM is sufficient. Use the following command, and check the "available" column:<br />
<br />
$ free -h<br />
<br />
* If boot time is slow, and applications take a long time to load at first launch (only), then the hard drive is likely to blame. The speed of a hard drive can be measured with the {{ic|hdparm}} command:<br />
<br />
# hdparm -t /dev/sdx<br />
<br />
{{Pkg|hdparm}} indicates only the pure read speed of a hard drive, and is not a valid benchmark. A value higher than 40MB/s (while idle) is however acceptable on an average system.<br />
<br />
* If CPU load is consistently high even with enough RAM available, then lowering CPU use should be a priority. This can be monitored in several ways, for example with {{Pkg|htop}}:<br />
<br />
$ htop<br />
<br />
* If only applications using direct rendering are slow (i.e those which use the GPU, such as video players and games), then improving GPU performance should help. The first step is to verify if direct rendering is actually enabled. This is indicated by the {{ic|glxinfo}} command:<br />
<br />
$ glxinfo | grep direct<br />
<br />
{{ic|glxinfo}} is part of the {{Pkg|mesa-demos}} package.<br />
<br />
===The first thing to do===<br />
<br />
The simplest and most efficient way of improving overall performance is to run lightweight environments and applications.<br />
<br />
* Use a [[window manager]] instead of a [[desktop environment]]. Choices include [[Awesome]], [[dwm]], [[Fluxbox]], [[i3]], [[JWM]], [[Openbox]], [[wmii]] and [[xmonad]]. If choosing a desktop environment, consider [[LXDE]] or [[Xfce]].<br />
* Use {{ic|pstree}} or {{Pkg|htop}} to list running daemons and their resource use.<br />
<br />
=== Benchmarking ===<br />
<br />
The effects of optimization are often difficult to judge. They can however be measured by [[benchmarking]] tools.<br />
<br />
== Storage devices ==<br />
<br />
{{Poor writing|Subjective writing}}<br />
<br />
=== Swap files ===<br />
<br />
Creating your swap files on a separate disk can also help quite a bit, especially if your machine swaps frequently. It happens if you do not have enough RAM for your environment. Using KDE with all the features and applications that come along may require several GiB of memory, whereas a tiny window manager with console applications will perfectly fit in less than 512 MiB of memory.<br />
<br />
=== RAID ===<br />
<br />
If you have multiple disks available, you can set them up as a software [[RAID]] for serious speed improvements. In a RAID 0 array there is no redundancy in case of drive failure, but for each additional disk you add to the array, the speed of the disk becomes that much faster.<br />
<br />
=== Multiple hardware paths ===<br />
<br />
An internal hardware path is how the storage device is connected to your motherboard. There are different ways to connect to the motherboard such as TCP/IP through a NIC, plugged in directly using PCIe/PCI, Firewire, Raid Card, USB, etc. By spreading your storage devices across these multiple connection points you maximize the capabilities of your motherboard, for example 6 hard-drives connected via USB would be much much slower than 3 over USB and 3 over Firewire. The reason is that each entry path into the motherboard is like a pipe, and there is a set limit to how much can go through that pipe at any one time. The good news is that the motherboard usually has several pipes.<br />
<br />
More Examples<br />
<br />
# Directly to the motherboard using pci/PCIe/ata<br />
# Using an external enclosure to house the disk over USB/Firewire<br />
# Turn the device into a network storage device by connecting over tcp/ip<br />
<br />
Note also that if you have a 2 USB ports on the front of your machine, and 4 USB ports on the back, and you have 4 disks, it would probably be fastest to put 2 on front/2 on back or 3 on back/1 on front. This is because internally the front ports are likely a separate Root Hub than the back, meaning you can send twice as much data by using both than just 1. Use the following commands to determine the various paths on your machine.<br />
<br />
{{hc|USB Device Tree|$ lsusb -tv}}<br />
<br />
{{hc|PCI Device Tree|$ lspci -tv}}<br />
<br />
=== Partitioning ===<br />
<br />
If using a traditional spinning HDD, your partition layout can influence the system's performance. Sectors at the beginning of the drive (closer to the outside of the disk) are faster than those at the end. Also, a smaller partition requires less movements from the drive's head, and so speed up disk operations. Therefore, it is advised to create a small partition (10GB, more or less depending on your needs) only for your system, as near to the beginning of the drive as possible. Other data (pictures, videos) should be kept on a separate partition, and this is usually achieved by separating the home directory ({{ic|/home/''user''}}) from the system ({{ic|/}}).<br />
<br />
=== Choosing and tuning your filesystem ===<br />
<br />
Choosing the best filesystem for a specific system is very important because each has its own strengths. The [[File systems]] article provides a short summary of the most popular ones. You can also find relevant articles [[:Category:File systems|here]].<br />
<br />
==== Mount options ====<br />
<br />
The [[fstab#atime options|noatime]] option is known to improve performance of the filesystem.<br />
<br />
Other mount options are filesystem specific, therefore see the relevant articles for the filesystems:<br />
<br />
* [[Ext3]]<br />
* [[Ext4#Tips and tricks]]<br />
* [[JFS Filesystem#Optimizations]]<br />
* [[XFS]]<br />
* [[Btrfs#Defragmentation]] and [[Btrfs#Compression]]<br />
<br />
===== Reiserfs =====<br />
<br />
The {{Ic|1=data=writeback}} mount option improves speed, but may corrupt data during power loss. The {{Ic|notail}} mount option increases the space used by the filesystem by about 5%, but also improves overall speed. You can also reduce disk load by putting the journal and data on separate drives. This is done when creating the filesystem: <br />
<br />
# mkreiserfs –j /dev/sd'''a1''' /dev/sd'''b1'''<br />
<br />
Replace {{ic|/dev/sd'''a1'''}} with the partition reserved for the journal, and {{ic|/dev/sd'''b1'''}} with the partition for data. You can learn more about reiserfs with this [http://www.funtoo.org/Funtoo_Filesystem_Guide,_Part_2 article].<br />
<br />
=== Tuning kernel parameters ===<br />
<br />
There are several key tunables affecting the performance of block devices, see [[sysctl#Virtual memory]] for more information.<br />
<br />
=== Tuning IO schedulers ===<br />
<br />
The kernel supports different schedulers for storage disk in-/output (IO). These are the [[wikipedia:CFQ|CFQ]] scheduler (Completely Fair Queuing), the [[wikipedia:NOOP_scheduler|NOOP]] and [[wikipedia:Deadline_scheduler|Deadline]]. <br />
<br />
A HDD has spinning disks and head that move physically to the required location. Such structure leads to following characteristics:<br />
* random latency it quite high, for modern HDD it is ~10ms (ignoring a disk controller write buffer).<br />
* sequential access provides much higher throughput. In this case head needs to move less distance.<br />
<br />
In case if we have a lot of running processes that make IO requests to different parts of storage (i.e. random access) then we can expect that a disk handles ~100 IO requests per second. Because modern systems can easily generate load much higher than 100 requests per second we have a queue of requests that have to wait for access to the storage. One way to improve throughput is to linearize access, i.e. order waiting requests by its logical address and always choose the closest request. Historically this was the first Linux IO scheduler called elevator scheduler.<br />
<br />
One of the problems with the elevator algorithm is that it makes suffer processes with sequential access. Such processes read a block of data then process it for several microseconds then read next block and so on. The elevator scheduler does not know that the process is going to read another block nearby and, thus, moves to another request at some other location. To overcome the problem anticipatory IO scheduler was added. For synchronous requests this algorithm waits for a short amount of time before moving to another request.<br />
<br />
While these schedulers try to improve total throughput they also might leave some unlucky requests waiting for a very long time. As an example, imagine the majority of processes make requests at the beginning of storage space while an unlucky process makes a request at the other end of storage. So developers tried to make the algorithm more fair and the deadline scheduler was added. It has a queue ordered by address (the same as elevator). If some request sits in this queue for a long time then it moves to an "expired" queue ordered by expire time. The scheduler checks the expire queue first and processes requests from there and only then moves to elevator queue. It is important to understand that this algorithm scarifies total throughput for fairness.<br />
<br />
CFQ (the default scheduler nowadays) aggregates all ideas from above and adds {{ic|cgroup}} support that allows to reserve some amount of IO to a specific {{ic|cgroup}}. It is useful on shared (and cloud) hosting - users who paid for 20 IO/s want to get their share if needed.<br />
<br />
The characteristics of a SSD are different. It does not have moving parts. Random access is as fast as sequential one. An SSD can handle multiple requests at the same time. Modern devices' throughput ~10K IO/s, which is higher than workload on most systems. Essentially a user cannot generate enough requests to saturate a SDD, the requests queue is effectively always empty. In this case IO scheduler does not provide any improvements. Thus, it is recommended to use the noop scheduler for an SSD.<br />
<br />
It is possible to change the scheduler at runtime and even to use different schedulers for separate storage devices at the same time. See [[Solid_State_Drives#I.2FO_Scheduler|SSD IO scheduler]] for commands and examples.<br />
<br />
=== RAM disks ===<br />
<br />
{{Merge|tmpfs|Post from 2009, check if still relevant}}<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=493773#p493773].<br />
<br />
=== USB storage devices ===<br />
<br />
{{Accuracy|Commands still unclear}}<br />
<br />
If USB drives like pendrives are slow to copy files, append these three lines in a [[systemd]] tmpfile:<br />
<br />
{{hc|/etc/tmpfiles.d/local.conf|<br />
w /sys/kernel/mm/transparent_hugepage/enabled - - - - madvise<br />
w /sys/kernel/mm/transparent_hugepage/defrag - - - - madvise<br />
w /sys/kernel/mm/transparent_hugepage/khugepaged/defrag - - - - 0<br />
}}<br />
<br />
See also [[sysctl#Virtual memory]], [http://unix.stackexchange.com/questions/107703/why-is-my-pc-freezing-while-im-copying-a-file-to-a-pendrive] and [http://lwn.net/Articles/572911/].<br />
<br />
== CPU ==<br />
<br />
The only way to directly improve CPU speed is overclocking. As it is a complicated and risky task, it is not recommended for anyone except experts. The best way to overclock is through the BIOS. When purchasing your system, keep in mind that most Intel motherboards are notorious for disabling the capability to overclock.<br />
<br />
Many Intel i5 and i7 chips, even when overclocked properly through the BIOS or UEFI interface, will not report the correct clock frequency to acpi_cpufreq and most other utilities. This will result in excessive messages in dmesg about delays unless the module acpi_cpufreq is unloaded and blacklisted. The only tool known to correctly read the clock speed of these overclocked chips under Linux is i7z. The {{Pkg|i7z}} package is available in the community repo and {{AUR|i7z-git}} is available in the [[AUR]].<br />
<br />
A way to modify performance ([http://lkml.org/lkml/2009/9/6/136 ref]) is to use Con Kolivas' desktop-centric kernel patchset, which, among other things, replaces the Completely Fair Scheduler (CFS) with the Brain Fuck Scheduler (BFS).<br />
<br />
Kernel PKGBUILDs that include the BFS patch can be installed from the [[AUR]] or [[Unofficial user repositories]]. See the respective pages for {{AUR|linux-ck}} and [[Linux-ck]] wiki page, {{AUR|linux-pf}} and [[Linux-pf]] wiki page or {{AUR|linux-bfs}} for more information on their additional patches.<br />
<br />
{{Note|BFS/CK are designed for desktop/laptop use and not servers. They provide low latency and work well for 16 CPUs or less. Also, Con Kolivas suggests setting HZ to 1000. For more information, see the [http://ck.kolivas.org/patches/bfs/bfs-faq.txt BFS FAQ] and [http://users.on.net/~ckolivas/kernel/ Kernel patch homepage of Con Kolivas].}}<br />
<br />
=== Verynice ===<br />
<br />
[[VeryNice]] is a daemon, available in the [[AUR]] as {{AUR|verynice}}, for dynamically adjusting the nice levels of executables. The nice level represents the priority of the executable when allocating CPU resources. Simply define executables for which responsiveness is important, like X or multimedia applications, as ''goodexe'' in {{ic|/etc/verynice.conf}}. Similarly, CPU-hungry executables running in the background, like make, can be defined as ''badexe''. This prioritization greatly improves system responsiveness under heavy load.<br />
<br />
=== cgroups ===<br />
<br />
See [[cgroups]].<br />
<br />
=== irqbalance ===<br />
<br />
The purpose of {{Pkg|irqbalance}} is distribute hardware interrupts across processors on a multiprocessor system in order to increase performance. It can be [[systemd#Using units|controlled]] by the provided {{ic|irqbalance.service}}.<br />
<br />
== Graphics ==<br />
<br />
As with CPUs, overclocking can directly improve performance, but is generally recommended against. There are several packages in the [[AUR]], such as {{AUR|rovclock}}, {{AUR|amdoverdrivectrl}} (ATI), and {{AUR|nvclock}} (NVIDIA).<br />
<br />
=== Xorg.conf configuration ===<br />
<br />
Graphics performance may depend on the settings in {{ic|/etc/X11/xorg.conf}}; see the [[NVIDIA]], [[ATI]] and [[Intel]] articles. Improper settings may stop Xorg from working, so caution is advised.<br />
<br />
=== Driconf ===<br />
<br />
{{Pkg|driconf}} is a small utility which allows to change direct rendering settings for open source drivers. Enabling ''HyperZ'' may improve performance.<br />
<br />
== RAM and swap ==<br />
<br />
=== Relocate files to tmpfs ===<br />
<br />
{{Out of date|/tmp configured using tmpfs is now considered the standard method and is included in the beginner's installation guide.}}<br />
<br />
Relocate files, such as your browser profile, to a [[Wikipedia:tmpfs|tmpfs]] file system, including {{ic|/tmp}}, or {{ic|/dev/shm}} for improvements in application response as all the files are now stored in RAM.<br />
<br />
Use an active management script for maximal reliability and ease of use. <br />
<br />
Refer to the [[Profile-sync-daemon]] wiki article for more information on syncing browser profiles.<br />
<br />
Refer to the [[Anything-sync-daemon]] wiki article for more information on syncing any specified folder.<br />
<br />
=== Running root on ram overlay ===<br />
<br />
If running off a slow writing medium (USB, spinning HDDs) and storage requirements are low, it may be advisable to run root on an overlay ontop of read only root (on disk). This can vastly improve performance at the cost of a limited writable space to root. See [https://aur.archlinux.org/packages/liveroot/ liveroot]<br />
<br />
=== Zram or zswap ===<br />
<br />
The [https://www.kernel.org/doc/Documentation/blockdev/zram.txt zram] kernel module (previously called '''compcache''') provides a compressed block device in RAM. If you use it as swap device, the RAM can hold much more information but uses more CPU. Still, it is much quicker than swapping to a hard drive. If a system often falls back to swap, this could improve responsiveness.<br />
<br />
Example: To set up one lz4 compressed zram device with 32GiB capacity and a higher-than-normal priority (only for the current session):<br />
<br />
# modprobe zram<br />
# echo lz4 > /sys/block/zram0/comp_algorithm<br />
# echo 32G > /sys/block/zram0/disksize<br />
# mkswap --label zram0 /dev/zram0<br />
# swapon --priority 100 /dev/zram0<br />
<br />
To disable it again, either reboot or run<br />
<br />
# swapoff /dev/zram0<br />
# rmmod zram<br />
<br />
If you want to automatically initialize zram on every boot, consider writing a [[systemd]] service for it.<br />
<br />
A detailed explanation of all steps, options and potential problems is provided in the official documentation of the module [https://www.kernel.org/doc/Documentation/blockdev/zram.txt here].<br />
<br />
The AUR package {{AUR|zramswap}} provides an automated script for setting up such swap devices with optimal settings for your system (such as RAM size and CPU core number). The script creates one zram device per CPU core with a total space equivalent to the RAM available. To do this automatically on every boot, enable {{ic|zramswap.service}} via [[systemd#Basic systemctl usage|systemctl]]. <br />
<br />
You will have a compressed swap with higher priority than your regular swap which will utilize multiple CPU cores for compessing data.<br />
<br />
{{Tip|Using zram is also a good way to reduce disk read/write cycles due to swap on SSDs.}}<br />
<br />
Similar benefits (at similar costs) can be achieved using [[Zswap|zswap]] rather than zram. The two are generally similar in intent although not operation: zswap operates as a compressed RAM cache and neither requires (nor permits) extensive userspace configuration.<br />
<br />
=== Using the graphic card's RAM ===<br />
<br />
In the unlikely case that you have very little RAM and a surplus of video RAM, you can use the latter as swap. See [[Swap on video ram]].<br />
<br />
== Network ==<br />
<br />
Use a DNS caching server in your local network. Every time a connections is made, the TCP/IP stack must resolve a fully qualified donamin name to an IP address. Only then the connection can be done. To use a DNS caching server directly present in your local network will decreases the latency on new connections. Your DSL router should contain such server, if not you can install your own. See [[Dnsmasq]] for more details.<br />
<br />
== Application-specific tips ==<br />
<br />
=== Firefox ===<br />
<br />
See [[Firefox tweaks#Performance]] and [[Firefox Ramdisk]].<br />
<br />
Firefox in the official repositories is built with the profile guided optimization flag enabled. You may want to use it in your custom build.<br />
To do this append:<br />
<br />
ac_add_options --enable-profile-guided-optimization<br />
<br />
to your {{ic|.mozconfig}} file.</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Btrfs&diff=365588Btrfs2015-03-15T20:55:02Z<p>Bluerider: /* Troubleshooting */ Add instructions on how to fix empty directory not empty situations</p>
<hr />
<div>[[Category:File systems]]<br />
[[ja:Btrfs]]<br />
[[zh-CN:Btrfs]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|Btrfs - Tips and tricks}}<br />
{{Related|Mkinitcpio-btrfs}}<br />
{{Related|Snapper}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Btrfs]]<br />
<br />
:''Btrfs (B-tree file system, variously pronounced: "Butter F S", "Better F S", "B-tree F S", or simply "Bee Tee Arr Eff Ess") is a GPL-licensed experimental copy-on-write file system for Linux. Development began at Oracle Corporation in 2007.''<br />
<br />
From [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs Wiki]<br />
<br />
:''Btrfs is a new copy on write (CoW) filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, repair and easy administration. Jointly developed at Oracle, Red Hat, Fujitsu, Intel, SUSE, STRATO and many others, Btrfs is licensed under the GPL and open for contribution from anyone.''<br />
<br />
{{Warning|<br />
* Btrfs has some features that are considered experimental. See the Btrfs Wiki's [https://btrfs.wiki.kernel.org/index.php/Main_Page#Stability_status Stability status,] [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_btrfs_stable.3F Is Btrfs stable,] and [https://btrfs.wiki.kernel.org/index.php/Getting_started Getting started] for more detailed information.<br />
* Beware of the [[#Limitations|limitations]].<br />
}}<br />
<br />
== Installation ==<br />
<br />
Btrfs is included in the default kernel and its tools ({{Pkg|btrfs-progs}}) are available in the official repositories. [[GRUB]], [[mkinitcpio]], and [[Syslinux]] have support for Btrfs and require no additional configuration.<br />
<br />
=== Additional packages ===<br />
<br />
* {{Pkg|btrfs-progs}} includes ''btrfsck'', a tool that can fix errors on Btrfs filesystems.<br />
* {{AUR|mkinitcpio-btrfs}} enables roll-back abilities.<br />
* {{AUR|btrfs-progs-git}} for nightly<br />
<br />
{{Tip|See [https://btrfs.wiki.kernel.org/index.php/Getting_started Btrfs Wiki Getting Started] for suggestions regarding running Btrfs effectively.}}<br />
<br />
== General administration of Btrfs ==<br />
<br />
=== Creating a new file system ===<br />
<br />
A Btrfs file system can either be newly created or have one converted.<br />
<br />
To format a partition do:<br />
<br />
# mkfs.btrfs -L ''mylabel'' /dev/''partition''<br />
<br />
{{Note|1=As of [https://git.kernel.org/cgit/linux/kernel/git/mason/btrfs-progs.git/commit/?id=c652e4efb8e2dd76ef1627d8cd649c6af5905902 this] commit (November 2013), Btrfs default blocksize is 16KB.}}<br />
<br />
To use a larger blocksize for data/metadata, specify a value for the leafsize via the {{ic|-l}} switch as shown in this example using 16KB blocks:<br />
<br />
# mkfs.btrfs -L ''mylabel'' -l 16k /dev/''partition''<br />
<br />
Multiple devices can be entered to create a RAID. Supported RAID levels include RAID 0, RAID 1, RAID 10, RAID 5 and RAID 6. By default the metadata is mirrored and data is striped. See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Using Btrfs with Multiple Devices] for more information about how to create a Btrfs RAID volume.<br />
<br />
# mkfs.btrfs [''options''] /dev/''part1'' /dev/''part2''<br />
<br />
=== Convert from Ext3/4 ===<br />
<br />
Boot from an install CD, then convert by doing:<br />
<br />
# btrfs-convert /dev/''partition''<br />
<br />
Mount the partion and test the conversion by checking the files. Be sure to change the {{ic|/etc/fstab}} to reflect the change ('''type''' to {{ic|btrfs}} and '''fs_passno''' [the last field] to {{ic|0}} as Btrfs does not do a file system check on boot). Also note that the UUID of the partition will have changed, so update fstab accordingly when using UUIDs. {{ic|chroot}} into the system and rebuild the GRUB menu list (see [[Install from Existing Linux]] and [[GRUB]] articles). If converting a root filesystem, while still chrooted run {{ic|mkinitcpio -p linux}} to regenerate the initramfs or the system will not successfully boot. If you get stuck in grub with 'unknown filesystem' try reinstalling grub with {{ic|grub-install /dev/''partition''}} and regenerate the config as well {{ic|grub-mkconfig -o /boot/grub/grub.cfg}}.<br />
<br />
To complete, delete the sub-volume saved image is on, and finally [[#Balance|balance]] the file system to reclaim the space.<br />
<br />
# btrfs subvolume delete /ext2_saved<br />
<br />
=== Mount options ===<br />
<br />
{{Warning|Specific mount options can disable safety features and increase the risk of complete file system corruption.}}<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Mount_options Btrfs Wiki Mount options] and [https://btrfs.wiki.kernel.org/index.php/Gotchas Btrfs Wiki Gotchas] for more information.<br />
<br />
In addition to configurations that can be made during or after file system creation, the various mount options for Btrfs can drastically change its performance characteristics.<br />
<br />
As this is a file system that is still in active development. Changes and regressions should be expected. See links in the [[#See also]] section for some benchmarks.<br />
<br />
==== Examples ====<br />
<br />
* '''Linux 3.15'''<br />
** Btrfs on a SSD for system installation and an emphasis on maximizing performance.<br />
*:{{bc|1=noatime,discard,ssd,autodefrag,compress=lzo,space_cache}}<br />
** Btrfs on a HDD for archival purposes with an emphasis on maximizing space.<br />
*: {{bc|1=noatime,autodefrag,compress-force=lzo,space_cache}}<br />
<br />
=== Displaying used/free space ===<br />
<br />
General linux userspace tools such as {{ic|/usr/bin/df}} will inaccurately report free space on a Btrfs partition since it does not take into account space allocated for and used by the metadata. It is recommended to use {{ic|/usr/bin/btrfs}} to query a Btrfs partition. Below is an illustration of this effect, first querying using {{ic|df -h}}, and then using {{ic|btrfs filesystem df}}:<br />
<br />
{{hc|$ df -h /|<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/sda3 119G 3.0G 116G 3% /<br />
}}<br />
<br />
{{hc|$ btrfs filesystem df /|2=<br />
Data: total=3.01GB, used=2.73GB<br />
System: total=4.00MB, used=16.00KB<br />
Metadata: total=1.01GB, used=181.83MB<br />
}}<br />
<br />
Notice that {{ic|df -h}} reports 3.0GB used but {{ic|btrfs filesystem df}} reports 2.73GB for the data. This is due to the way Btrfs allocates space into the pool. The true disk usage is the sum of all three 'used' values which is inferior to 3.0GB as reported by {{ic|df -h}}.<br />
<br />
{{Note|1=If you see an entry of type {{ic|unknown}} in the output of {{ic|btrfs filesystem df}} at kernel >= 3.15, this is a display bug. As of [http://thread.gmane.org/gmane.comp.file-systems.btrfs/34419 this patch], the entry means GlobalReserve, which is kind of a buffer for changes not yet flushed. This entry is displayed as {{ic|unknown, single}} in RAID setups and is not possible to re-balance.}}<br />
<br />
Another useful command to show a less verbose readout of used space is {{ic|btrfs filesystem show}}:<br />
<br />
{{hc|# btrfs filesystem show /dev/sda3|<br />
failed to open /dev/sr0: No medium found<br />
Label: 'arch64' uuid: 02ad2ea2-be12-2233-8765-9e0a48e9303a<br />
Total devices 1 FS bytes used 2.91GB<br />
devid 1 size 118.95GB used 4.02GB path /dev/sda2<br />
<br />
Btrfs v0.20-rc1-358-g194aa4a-dirty<br />
}}<br />
<br />
== Limitations ==<br />
<br />
A few limitations should be known before trying.<br />
<br />
=== Encryption ===<br />
<br />
Btrfs has no built-in encryption support (this may come in future); users can encrypt the partition before running {{ic|mkfs.btrfs}}. See [[dm-crypt]]. <br />
<br />
Existing Btrfs file system, can use something like [[EncFS]] or [[TrueCrypt]], though perhaps without some of Btrfs' features.<br />
<br />
=== Swap file ===<br />
<br />
Btrfs does not yet support [[Swap#Swap_file|swap files]]. This is due to swap files requiring a function that Btrfs doesn't have for possibility of file system corruption [https://btrfs.wiki.kernel.org/index.php/FAQ#Does_btrfs_support_swap_files.3F]. Patches for swapfile support are already available [https://lkml.org/lkml/2014/12/9/718] and may be included in an upcoming kernel release. As an alternative a swap file can be mounted on a loop device with poorer performance but will not be able to hibernate. Install the package {{Pkg|systemd-swap}} from the [[official repositories]] to automate this.<br />
<br />
=== Linux-rt kernel ===<br />
<br />
As of version 3.14.12_rt9, the [[Kernel#-rt|linux-rt]] kernel does not boot with the Btrfs file system. This is due to the slow development of the ''rt'' patchset.<br />
<br />
== Features ==<br />
<br />
Various features are available and can be adjusted.<br />
<br />
=== Copy-On-Write (CoW) ===<br />
<br />
The resolution at which data are written to the filesystem is dictated by Btrfs itself and by system-wide settings. Btrfs defaults to a 30 seconds checkpoint interval in which new data are committed to the filesystem. This is tuneable using mount options (see below)<br />
<br />
System-wide settings also affect commit intervals. They include the files under {{ic|/proc/sys/vm/*}} and are out-of-scope of this wiki article. The kernel documentation for them resides in {{ic|Documentation/sysctl/vm.txt}}.<br />
<br />
CoW comes with some advantages, but can negatively affect performance with large files that have small random writes. It is recommended to disable CoW for database files and virtual machine images. <br />
<br />
One can disable CoW for the entire block device by mounting it with {{ic|nodatacow}} option. However, this will disable CoW for the entire file system.<br />
<br />
{{Note|{{ic|nodatacow}} will only affect newly created file. CoW may still happen for existing file.}}<br />
<br />
To disable CoW for single files/directories do:<br />
<br />
$ chattr +C ''/dir/file''<br />
<br />
{{Note|From chattr man page: For btrfs, the 'C' flag should be set on new or empty files. If it is set on a file which already has data blocks, it is undefined when the blocks assigned to the file will be fully stable. If the 'C' flag is set on a directory, it will have no effect on the directory, but new files created in that directory will have the No_COW attribute.}}<br />
<br />
{{Tip|In accordance with the note above, you can use the following trick to disable CoW on existing files in a directory:<br />
$ mv ''/path/to/dir'' ''/path/to/dir''_old<br />
$ mkdir ''/path/to/dir''<br />
$ chattr +C ''/path/to/dir''<br />
$ cp -a ''/path/to/dir''_old/* ''/path/to/dir''<br />
$ rm -rf ''/path/to/dir''_old<br />
Make sure that the data are not used during this process. Also note that {{ic|mv}} or {{ic|cp --reflink}} as described below will not work.<br />
}}<br />
<br />
Likewise, to save space by forcing CoW when copying files use:<br />
<br />
$ cp --reflink ''source'' ''dest'' <br />
<br />
As {{ic|''dest''}} file is changed, only those blocks that are changed from source will be written to the disk. One might consider aliasing ''cp'' to {{ic|1=cp --reflink=auto}}.<br />
<br />
=== Multi-device filesystem and RAID feature ===<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Using Btrfs with Multiple Devices] for suggestions.<br />
<br />
==== Multi-device filesystem ====<br />
<br />
When creating a Btrfs filesystem, one can pass many partitions or disk devices to ''mkfs.btrfs''. The filesystem will be created across these devices. One can '''"'''pool'''"''' this way, multiple partitions or devices to get a single Btrfs filesystem.<br />
<br />
One can also add or remove device from an existing btrfs filesystem (caution is mandatory).<br />
<br />
==== RAID features ====<br />
<br />
{{Warning|Parity RAID (RAID 5 and RAID 6) are not currently complete, and have significant problems with recovery from the loss of a device. They should not be used for anything other than testing purposes.}}<br />
<br />
When creating a multi-device filesystem, one can also specify to use RAID0, RAID1, RAID10, RAID5 or RAID6 across the devices comprising the filesystem. RAID levels can be applied independently to data and metadata. By default, metadata is duplicated on single volumes or RAID1 on multi-disk sets.<br />
<br />
Btrfs works in block-pairs for raid0, raid1, and raid10. This means:<br />
<br />
raid0 - block-pair striped across 2 devices<br />
<br />
raid1 - block-pair written to 2 devices<br />
<br />
The raid level can be changed while the disks are online using the {{ic|btrfs balance}} command:<br />
<br />
# btrfs balance start -mconvert=RAIDLEVEL -dconvert=RAIDLEVEL /path/to/mount<br />
<br />
For 2 disk sets, this matches raid levels as defined in md-raid (mdadm). For 3+ disk-sets, the result is entirely different than md-raid. <br />
<br />
For example:<br />
* Three 1TB disks in an md based raid1 yields a {{ic|/dev/md0}} with 1TB free space and the ability to safely lose 2 disks without losing data.<br />
* Three 1TB disks in a Btrfs volume with data=raid1 will allow the storage of approximately 1.5TB of data before reporting full. Only 1 disk can safely be lost without losing data.<br />
<br />
Btrfs uses a round-robin scheme to decide how block-pairs are spread among disks. As of Linux 3.0, a quasi-round-robin scheme is used which prefers larger disks when distributing block pairs. This allows raid0 and raid1 to take advantage of most (and sometimes all) space in a disk set made of multiple disks. For example, a set consisting of a 1TB disk and 2 500GB disks with data=raid1 will place a copy of every block on the 1TB disk and alternate (round-robin) placing blocks on each of the 500GB disks. Full space utilization will be made. A set made from a 1TB disk, a 750GB disk, and a 500GB disk will work the same, but the filesystem will report full with 250GB unusable on the 750GB disk. To always take advantage of the full space (even in the last example), use data=single. (data=single is akin to JBOD defined by some raid controllers) See [https://btrfs.wiki.kernel.org/index.php/FAQ#How_much_space_do_I_get_with_unequal_devices_in_RAID-1_mode.3F the BTRFS FAQ] for more info.<br />
<br />
=== Sub-volumes ===<br />
<br />
See the following links for more details:<br />
* [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes Btrfs Wiki SysadminGuide#Subvolumes]<br />
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Basic_Filesystem_Commands Btrfs Wiki Getting started#Basic Filessystem Commands]<br />
* [https://btrfs.wiki.kernel.org/index.php/Trees Btrfs Wiki Trees] <br />
<br />
==== Creating sub-volumes ====<br />
<br />
To create a sub-volume:<br />
<br />
# btrfs subvolume create ''subvolume-name''<br />
<br />
==== Listing sub-volumes ====<br />
<br />
To see a list of current sub-volumes:<br />
<br />
# btrfs subvolume list -p .<br />
<br />
==== Setting a default sub-volume ====<br />
<br />
{{Warning|Changing the default subvolume with btrfs subvolume default will make the top level of the filesystem inaccessible, except by use of the {{ic|1=subvolid=0}} mount option. Reference: [https://btrfs.wiki.kernel.org/index.php/SysadminGuide Btrfs Wiki Sysadmin Guide].}}<br />
<br />
The default sub-volume is mounted if no {{ic|1=subvol=}} mount option is provided.<br />
<br />
# btrfs subvolume set-default ''subvolume-id'' /.<br />
<br />
'''Example:'''<br />
<br />
{{hc|# btrfs subvolume list .|<br />
ID 258 gen 9512 top level 5 path root_subvolume<br />
ID 259 gen 9512 top level 258 path home<br />
ID 260 gen 9512 top level 258 path var<br />
ID 261 gen 9512 top level 258 path usr<br />
}}<br />
<br />
# btrfs subvolume set-default 258 .<br />
<br />
'''Reset:'''<br />
<br />
# btrfs subvolume set-default 0 .<br />
<br />
==== Snapshots ====<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Snapshots Btrfs Wiki SysadminGuide#Snapshots] for details.<br />
<br />
To create a snapshot:<br />
<br />
# btrfs subvolume snapshot ''source'' [''dest''/]''name''<br />
<br />
Snapshots are not recursive. Every sub-volume inside sub-volume will be an empty directory inside the snapshot.<br />
<br />
==== Installing with root on btrfs subvolume ====<br />
<br />
{{Moveto||Does not fit into [[#Features]] section, maybe we should start new one...}}<br />
<br />
{{Accuracy|Setting {{ic|rootvol}} as the default subvolume (see [[#Setting a default sub-volume]]) would be much simpler, for both installation and booting.}}<br />
<br />
{{Warning|When using legacy BIOS booting, syslinux is not capable of booting from a btrfs subvolume with the following setup, one must always use GRUB. (It is possible with a different, more complicated btrfs subvolume setup, that is out of the scope of this section.)}}<br />
<br />
For increased flexibility, install the system into a dedicated sub-volume.<br />
Set up a btrfs filesystem as to your liking and mount it to /mnt. The following mkfs command is given as an example.<br />
<br />
# mkfs.btrfs /dev/sda1 <br />
# mount /dev/sda1 /mnt<br />
<br />
Create a subvolume for root, where rootvol is an arbitrary name. If you wish, create additional subvolumes at this step, for example to accommodate /home.<br />
<br />
# cd /mnt<br />
# btrfs subvolume create rootvol<br />
# cd /<br />
# umount /mnt<br />
<br />
Mount the subvolume.<br />
<br />
# mount -o subvol=rootvol /dev/sda1 /mnt<br />
<br />
From here continue the installation process from the pacstrap step, as per the [[Installation guide]] or [[Beginners' guide]].<br />
<br />
Additional considerations:<br />
* In /etc/fstab, the mount option subvol="subvolume-name" has to be specified, and the fsck setting in the last field has to be 0.<br />
* In the kernel boot parameters, use: {{ic|1=rootflags=subvol=''subvolume-name''}}. It is still necessary to add the standard root parameter with {{ic| 1=root=/dev/sda1}}.<br />
* It is advisable to add '''crc32c''' (or '''crc32c-intel''' for Intel machines) to the modules array in {{ic|/etc/mkinitcpio.conf}}<br />
<br />
{{Note|Child sub-volumes are automatically mounted by Btrfs when the parent sub-volume is mounted.}}<br />
<br />
=== Defragmentation ===<br />
<br />
Btrfs supports online defragmentation. To defragment the metadata of the root folder:<br />
<br />
# btrfs filesystem defragment /<br />
<br />
This ''will not'' defragment the entire file system. For more information read [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ#Defragmenting_a_directory_doesn.27t_work this page] on the btrfs wiki.<br />
<br />
To defragment the entire file system verbosely:<br />
<br />
# btrfs filesystem defragment -r -v /<br />
<br />
{{Note|The command above will defragment only file data. To defragment directory metadata for every directory in the file system, run this command: {{bc|# find / -xdev -type d -print -exec btrfs filesystem defragment '{}' \;}}}}<br />
<br />
=== Compression ===<br />
<br />
Btrfs supports transparent compression, meaning every file on the partition is automatically compressed. This not only reduces the size of files, but also [http://www.phoronix.com/scan.php?page=article&item=btrfs_compress_2635&num=1 improves performance], in particular if using the [http://www.phoronix.com/scan.php?page=article&item=btrfs_lzo_2638&num=1 lzo algorithm], in some specific use cases (e.g. single thread with heavy file IO), while obviously harming performance on other cases (e.g. multithreaded and/or cpu intensive tasks with large file IO).<br />
<br />
Compression is enabled using the {{ic|1=compress=zlib}} or {{ic|1=compress=lzo}} mount options. Only files created or modified after the mount option is added will be compressed. However, it can be applied quite easily to existing files (e.g. after a conversion from ext3/4) using the {{ic|btrfs filesystem defragment -c''alg''}} command, where {{ic|''alg''}} is either {{ic|zlib}} or {{ic|lzo}}. In order to re-compress the whole file system with {{ic|lzo}}, run the following command:<br />
<br />
# btrfs filesystem defragment -r -v -clzo /<br />
<br />
{{Tip|Compression can also be enabled per-file without using the {{ic|compress}} mount option; simply apply {{ic|chattr +c}} to the file. When applied to directories, it will cause new files to be automatically compressed as they come.}}<br />
<br />
When installing Arch to an empty Btrfs partition, set the {{ic|compress}} option after [[Beginners' guide#Prepare_the_storage_drive|preparing the storage drive]]. Simply switch to another terminal ({{ic|Ctrl+Alt+''number''}}), and run the following command:<br />
<br />
# mount -o remount,compress=lzo /mnt/target<br />
<br />
After the installation is finished, add {{ic|1=compress=lzo}} to the mount options of the root file system in [[fstab]].<br />
<br />
=== Checkpoint interval ===<br />
<br />
Starting with Linux 3.12, users are able to change the checkpoint interval from the default 30 s to any value by appending the {{ic|commit}} mount option in {{ic|/etc/fstab}} for the btrfs partition.<br />
<br />
LABEL=arch64 / btrfs defaults,noatime,ssd,compress=lzo,commit=120 0 0<br />
<br />
=== Partitioning ===<br />
<br />
Btrfs can occupy an entire data storage device, replacing the [[MBR]] or [[GPT]] partitioning schemes. One can use [[Btrfs#Sub-volumes|subvolumes]] to simulate partitions.<br />
There are some limitations to this approach in single disk setups:<br />
<br />
* Cannot use different [[File systems|file systems]] for different [[fstab|mount points]].<br />
* Cannot use [[Swap|swap area]] as Btrfs does not support [[Swap#Swap_file|swap files]] and there is no place to create [[Swap#Swap_partition|swap partition]]. This also limits the use of hibernation/resume, which needs a swap area to store the hibernation image.<br />
* Cannot use [[UEFI]] to boot.<br />
<br />
To overwrite the existing partition table with Btrfs, run the following command:<br />
<br />
# mkfs.btrfs /dev/sd''X''<br />
<br />
Do not specify {{ic|/dev/sda''X''}} or it will format an existing partition instead of replacing the entire partitioning scheme.<br />
<br />
Install the [[Bootloaders|boot loader]] in a like fashion to installing it for a data storage device with a [[MBR|Master Boot Record]]. For example:<br />
<br />
# grub-install --recheck /dev/sd''X''<br />
<br />
for [[Grub#Install_to_440-byte_MBR_boot_code_region|GRUB]].<br />
<br />
{{Warning|Using the {{ic|btrfs filesystem set-default}} command to change the default sub-volume from anything other than the top level (ID 0) may break Grub. See [[Btrfs#Setting a default sub-volume]] to reset.}}<br />
<br />
=== Scrub ===<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary].<br />
<br />
# btrfs scrub start /<br />
# btrfs scrub status /<br />
<br />
{{Warning|The running scrub process will prevent the system from suspending, see [http://comments.gmane.org/gmane.comp.file-systems.btrfs/33106 this thread] for details.}}<br />
<br />
If running the scrub as a systemd service, use {{ic|1=Type=forking}}. Alternatively, you can pass the "-B" flag to btrfs scrub start to run it in the foreground and use the default Type value.<br />
<br />
=== Balance ===<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/FAQ#What_does_.22balance.22_do.3F Upstream FAQ page].<br />
<br />
Since {{Pkg|btrfs-progs}}-3.12 ''balancing'' is a background process - see {{ic|man 8 btrfs-balance}} for full description.<br />
<br />
# btrfs balance start /<br />
# btrfs balance status /<br />
<br />
== Troubleshooting ==<br />
<br />
=== cannot remove file, directory not empty even though directory is empty ===<br />
<br />
The btrfs tree may be dirty and need to be fscked. See [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ#I_cannot_delete_an_empty_directory I cannot delete an empty directory]<br />
<br />
=== GRUB ===<br />
<br />
==== Partition offset ====<br />
<br />
{{Note|1=The offset problem may happen when you try to embed {{ic|core.img}} into a partitioned disk. It means that [https://wiki.archlinux.org/index.php?title=Talk:Btrfs&diff=319474&oldid=292530 it is OK] to embed grub's {{ic|corg.img}} into a Btrfs pool on a partitionless disk (e.g. {{ic|/dev/sd''X''}}) directly.}}<br />
<br />
[[GRUB]] can boot Btrfs partitions however the module may be larger than other [[file systems]]. And the {{ic|core.img}} file made by {{ic|grub-install}} may not fit in the first 63 sectors (31.5KiB) of the drive between the MBR and the first partition. Up-to-date partitioning tools such as {{ic|fdisk}} and {{ic|gdisk}} avoid this issue by offsetting the first partition by roughly 1MiB or 2MiB.<br />
<br />
==== Missing root ====<br />
<br />
Users experiencing the following: {{ic|1=error no such device: root}} when booting from a RAID style setup then edit /usr/share/grub/grub-mkconfig_lib and remove both quotes from the line {{ic|1=echo " search --no-floppy --fs-uuid --set=root ${hints} ${fs_uuid}"}}. Regenerate the config for grub and the system should boot without an error.<br />
<br />
=== BTRFS: open_ctree failed ===<br />
<br />
As of November 2014 there seems to be a bug in [[systemd]] or [[mkinitcpio]] causing the following error on systems with multi-device Btrfs filesystem using the {{ic|btrfs}} hook in {{ic|mkinitcpio.conf}}:<br />
<br />
{{bc|<nowiki><br />
BTRFS: open_ctree failed<br />
mount: wrong fs type, bad option, bad superblock on /dev/sdb2, missing codepage or helper program, or other error<br />
<br />
In some cases useful info is found in syslog - try dmesg|tail or so.<br />
<br />
You are now being dropped into an emergency shell.<br />
</nowiki>}}<br />
<br />
A workaround is to remove {{ic|btrfs}} from the {{ic|HOOKS}} array in {{ic|/etc/mkinitcpio.conf}} and instead adding {{ic|btrfs}} to the {{ic|MODULES}} array. Then regenerate the initramfs with {{ic|mkinitcpio -p linux}} (adjust the preset if needed) and reboot.<br />
<br />
See the [https://bbs.archlinux.org/viewtopic.php?id=189845 original forums thread] and {{Bug|42884}} for further information and discussion.<br />
<br />
== See also ==<br />
<br />
* '''Official site'''<br />
** [https://btrfs.wiki.kernel.org/ Btrfs Wiki]<br />
** [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary]<br />
* '''Official FAQs'''<br />
** [https://btrfs.wiki.kernel.org/index.php/FAQ Btrfs Wiki FAQ]<br />
** [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ Btrfs Wiki Problem FAQ]<br />
* '''Btrfs pull requests'''<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1401.3/03045.html 3.14]<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1311.1/03526.html 3.13]<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1309.1/02981.html 3.12]<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1305.1/01064.html 3.11]<br />
* '''Performance related'''<br />
** [http://superuser.com/questions/432188/should-i-put-my-multi-device-btrfs-filesystem-on-disk-partitions-or-raw-devices Btrfs on raw disks?]<br />
** [http://comments.gmane.org/gmane.comp.file-systems.btrfs/19440 Varying leafsize and nodesize in Btrfs]<br />
** [http://comments.gmane.org/gmane.comp.file-systems.btrfs/15646 Btrfs support for efficient SSD operation (data blocks alignment)]<br />
** [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_Btrfs_optimized_for_SSD.3F Is Btrfs optimized for SSDs?]<br />
** '''Phoronix mount option benchmarking'''<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_314_btrfs Linux 3.14]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_311&num=1 Linux 3.11]<br />
*** [http://www.phoronix.com/scan.php?page=news_item&px=MTM0OTU Linux 3.9]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=btrfs_linux37_mounts&num=1 Linux 3.7]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_options&num=1 Linux 3.2]<br />
** [http://blog.erdemagaoglu.com/post/4605524309/lzo-vs-snappy-vs-lzf-vs-zlib-a-comparison-of Lzo vs. zLib]<br />
* '''Miscellaneous'''<br />
** [http://www.funtoo.org/wiki/BTRFS_Fun Funtoo Wiki Btrfs Fun]<br />
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA0ODU Avi Miller presenting Btrfs] at SCALE 10x, January 2012.<br />
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA4Mzc Summary of Chris Mason's talk] from LFCS 2012<br />
** [http://git.kernel.org/?p&#61;linux/kernel/git/torvalds/linux-2.6.git;a&#61;commit;h&#61;35054394c4b3cecd52577c2662c84da1f3e73525 Btrfs: stop providing a bmap operation to avoid swapfile corruptions] 2009-01-21<br />
** [http://marc.merlins.org/perso/btrfs/post_2014-03-22_Btrfs-Tips_-Doing-Fast-Incremental-Backups-With-Btrfs-Send-and-Receive.html Doing Fast Incremental Backups With Btrfs Send and Receive]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=QEMU&diff=364727QEMU2015-03-09T02:44:41Z<p>Bluerider: /* Spice support */ Add in needed IP Address for ipv6</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 />
Install {{Pkg|qemu}} from the [[official repositories]].<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 />
From [[official repositories]]:<br />
* {{Pkg|virt-manager}} (part of [[libvirt]])<br />
* {{Pkg|gnome-boxes}}<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
From [[AUR]]:<br />
* {{AUR|aqemu-git}}<br />
* {{AUR|virtualbricks}}<br />
<br />
== Creating new virtualized system ==<br />
<br />
{{Tip|If you are virtualizing Arch Linux, it is possible to create a disk image directly on an existing Arch Linux system, see [[Creating Arch Linux disk image#Install Arch Linux in a disk image without the installation media]] for details.}}<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 VM installed on it unbootable. For full explanation see [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages here] and workaround below.}}<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 />
{{Tip|1=Workaround resizing an image containing an NTFS boot file system (this example is for qcow2 format image but method is the same for other formats):<br />
<br />
Important: first shut down any VMs using the image!<br />
<br />
Convert the image to raw format and add blank space at the end (keeping the original image as backup):<br />
<br />
$ qemu-img convert -f qcow2 -O raw myimg.qcow2 myimg.raw<br />
$ truncate -s +4G myimg.raw<br />
$ mv myimg.qcow2 myimg.qcow2.bak<br />
<br />
Convert the enlarged image back to qcow2, and delete the raw:<br />
<br />
$ qemu-img convert -f raw -O qcow2 myimg.raw myimg.qcow2<br />
$ rm myimg.raw<br />
<br />
Match the original image permissions:<br />
<br />
$ chown --reference=myimg.qcow2.bak myimg.qcow2<br />
$ chmod --reference=myimg.qcow2.bak myimg.qcow2<br />
<br />
Then resize partitions using preferred tool (e.g. for Windows Vista or later, you can just boot Windows and use the built-in [http://www.howtogeek.com/howto/windows-vista/resize-a-partition-for-free-in-windows-vista/ Disk Management utility]).<br />
}}<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]], [[Samba|SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[Secure Shell|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 [[Samba|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 could occur, unless you had mounted the partitions read-only.}}<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.<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 ''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 from the [[Arch User Repository|AUR]] 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 [[Kernels|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 />
==== 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 />
{{Tip|If you cannot get a DHCP address in the host, it might be because [[iptables]] is up by default in the bridge.}}<br />
<br />
* It is recommended for performance and security reasons to disable the 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 />
=== 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 it as usual (see [[systemd#Using units]] for details):<br />
<br />
# systemctl start qemu-network-env<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
== Graphics ==<br />
<br />
{{expansion|{{ic|cirrus}} is mentioned but doesn't have a section}}<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|cirrus}}, {{ic|vmware}}, {{ic|qxl}}, and {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels.<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, these condition must be met:<br />
<br />
* [[#Spice support|Spice]] has to be enabled on the host system.<br />
* A [http://www.spice-space.org/download.html guest driver] has to be installed on the guest system. On an Arch guest it is enough to install {{AUR|xf86-video-qxl}} from the [[AUR]].<br />
* The virtual machine has to be started with {{ic|-vga qxl}} switch.<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 [[Persistent_block_device_naming#By-uuid|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 />
==== Block device drivers ====<br />
<br />
Preparing a Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [http://www.linux-kvm.org/page/WindowsGuestDrivers/Download_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 />
Then connect with the the spice client<br />
<br />
$ spicec -h 127.0.0.1 -p 5930<br />
<br />
{{Tip|<br />
* Spice guest drivers can be downloaded [http://www.spice-space.org/download.html here] in the ''Guest'' section.<br />
* The key combination to escape mouse and keyboard grab can be configured, the default is {{ic|Shift+F12}}: {{bc|1=$ spicec --hotkeys release-cursor=ctrl+alt}}<br />
* To disable mouse and keyboard grabbing (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 />
}}<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 8.<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 [[:Category:Hypervisors|hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<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<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>Blueriderhttps://wiki.archlinux.org/index.php?title=QEMU&diff=364463QEMU2015-03-07T15:09:20Z<p>Bluerider: /* Mouse integration */ Add instructions on seeing a mouse cursor in virtual machine</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 />
Install {{Pkg|qemu}} from the [[official repositories]].<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 />
From [[official repositories]]:<br />
* {{Pkg|virt-manager}} (part of [[libvirt]])<br />
* {{Pkg|gnome-boxes}}<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
From [[AUR]]:<br />
* {{AUR|aqemu-git}}<br />
* {{AUR|virtualbricks}}<br />
<br />
== Creating new virtualized system ==<br />
<br />
{{Tip|If you are virtualizing Arch Linux, it is possible to create a disk image directly on an existing Arch Linux system, see [[Creating Arch Linux disk image#Install Arch Linux in a disk image without the installation media]] for details.}}<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 VM installed on it unbootable. For full explanation see [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages here] and workaround below.}}<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 />
{{Tip|1=Workaround resizing an image containing an NTFS boot file system (this example is for qcow2 format image but method is the same for other formats):<br />
<br />
Important: first shut down any VMs using the image!<br />
<br />
Convert the image to raw format and add blank space at the end (keeping the original image as backup):<br />
<br />
$ qemu-img convert -f qcow2 -O raw myimg.qcow2 myimg.raw<br />
$ truncate -s +4G myimg.raw<br />
$ mv myimg.qcow2 myimg.qcow2.bak<br />
<br />
Convert the enlarged image back to qcow2, and delete the raw:<br />
<br />
$ qemu-img convert -f raw -O qcow2 myimg.raw myimg.qcow2<br />
$ rm myimg.raw<br />
<br />
Match the original image permissions:<br />
<br />
$ chown --reference=myimg.qcow2.bak myimg.qcow2<br />
$ chmod --reference=myimg.qcow2.bak myimg.qcow2<br />
<br />
Then resize partitions using preferred tool (e.g. for Windows Vista or later, you can just boot Windows and use the built-in [http://www.howtogeek.com/howto/windows-vista/resize-a-partition-for-free-in-windows-vista/ Disk Management utility]).<br />
}}<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]], [[Samba|SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[Secure Shell|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 [[Samba|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 could occur, unless you had mounted the partitions read-only.}}<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.<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 ''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 from the [[Arch User Repository|AUR]] 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 [[Kernels|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 />
==== 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 />
{{Tip|If you cannot get a DHCP address in the host, it might be because [[iptables]] is up by default in the bridge.}}<br />
<br />
* It is recommended for performance and security reasons to disable the 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 />
=== 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 it as usual (see [[systemd#Using units]] for details):<br />
<br />
# systemctl start qemu-network-env<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
== Graphics ==<br />
<br />
{{expansion|{{ic|cirrus}} is mentioned but doesn't have a section}}<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|cirrus}}, {{ic|vmware}}, {{ic|qxl}}, and {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels.<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, these condition must be met:<br />
<br />
* [[#Spice support|Spice]] has to be enabled on the host system.<br />
* A [http://www.spice-space.org/download.html guest driver] has to be installed on the guest system. On an Arch guest it is enough to install {{AUR|xf86-video-qxl}} from the [[AUR]].<br />
* The virtual machine has to be started with {{ic|-vga qxl}} switch.<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 [[Persistent_block_device_naming#By-uuid|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 />
==== Block device drivers ====<br />
<br />
Preparing a Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [http://www.linux-kvm.org/page/WindowsGuestDrivers/Download_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 />
=== No visible Cursor ===<br />
<br />
Add -show-cursor to cmdline options to see a mouse cursor.<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<br />
<br />
Then connect with the the spice client<br />
<br />
$ spicec -h 127.0.0.1 -p 5930<br />
<br />
{{Tip|<br />
* Spice guest drivers can be downloaded [http://www.spice-space.org/download.html here] in the ''Guest'' section.<br />
* The key combination to escape mouse and keyboard grab can be configured, the default is {{ic|Shift+F12}}: {{bc|1=$ spicec --hotkeys release-cursor=ctrl+alt}}<br />
* To disable mouse and keyboard grabbing (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 />
}}<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 8.<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 />
=== 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 [[:Category:Hypervisors|hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<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<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>Blueriderhttps://wiki.archlinux.org/index.php?title=QEMU&diff=360119QEMU2015-02-09T17:06:28Z<p>Bluerider: /* Graphics */ Xorg accelerated video driver</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 />
Install {{Pkg|qemu}} from the [[official repositories]].<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 />
From [[official repositories]]:<br />
* {{Pkg|virt-manager}} (part of [[libvirt]])<br />
* {{Pkg|gnome-boxes}}<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
From [[AUR]]:<br />
* {{AUR|aqemu-git}}<br />
* {{AUR|virtualbricks}}<br />
<br />
== Creating new virtualized system ==<br />
<br />
{{Tip|If you are virtualizing Arch Linux, it is possible to create a disk image directly on an existing Arch Linux system, see [[Creating Arch Linux disk image#Install Arch Linux in a disk image without the installation media]] for details.}}<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 VM installed on it unbootable. For full explanation see [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages here] and workaround below.}}<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 />
{{Tip|1=Workaround resizing an image containing an NTFS boot file system (this example is for qcow2 format image but method is the same for other formats):<br />
<br />
Important: first shut down any VMs using the image!<br />
<br />
Convert the image to raw format and add blank space at the end (keeping the original image as backup):<br />
<br />
$ qemu-img convert -f qcow2 -O raw myimg.qcow2 myimg.raw<br />
$ truncate -s +4G myimg.raw<br />
$ mv myimg.qcow2 myimg.qcow2.bak<br />
<br />
Convert the enlarged image back to qcow2, and delete the raw:<br />
<br />
$ qemu-img convert -f raw -O qcow2 myimg.raw myimg.qcow2 <br />
$ rm myimg.raw <br />
<br />
Match the original image permissions:<br />
<br />
$ chown --reference=myimg.qcow2.bak myimg.qcow2<br />
$ chmod --reference=myimg.qcow2.bak myimg.qcow2<br />
<br />
Then resize partitions using preferred tool (e.g. for Windows Vista or later, you can just boot Windows and use the built-in [http://www.howtogeek.com/howto/windows-vista/resize-a-partition-for-free-in-windows-vista/ Disk Management utility]).<br />
}}<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 />
* It need to be enabled 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]], [[Samba|SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[Secure Shell|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 [[Samba|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 could occur, unless you had mounted the partitions read-only.}}<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.<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 ''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 from the [[Arch User Repository|AUR]] can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a /dev/loop0<br />
<br />
=== Mounting a partition inside a qcow2 image ===<br />
<br />
You may mount a partition inside a qcow2 image using {{ic|qemu-nbd}}. See [http://en.wikibooks.org/wiki/QEMU/Images#Mounting_an_image_on_the_host Wikibooks].<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you need to change the owner of the partition's device file to that user.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[Kernels|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, 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 />
==== 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 />
{{Tip|If you cannot get a DHCP address in the host, it might be because [[iptables]] is up by default in the bridge.}}<br />
<br />
* It is recommended for performance and security reasons to disable the 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 />
=== 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 it as usual (see [[systemd#Using units]] for details):<br />
<br />
# systemctl start qemu-network-env<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
== Graphics ==<br />
<br />
{{expansion|{{ic|cirrus}} is mentioned but doesn't have a section}}<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|cirrus}}, {{ic|vmware}}, {{ic|qxl}}, and {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels.<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, these condition must be met:<br />
<br />
* [[#Spice support|Spice]] has to be enabled on the host system.<br />
* A [http://www.spice-space.org/download.html guest driver] has to be installed on the guest system. On an Arch guest it is enough to install {{AUR|xf86-video-qxl}} from the [[AUR]].<br />
* The virtual machine has to be started with {{ic|-vga qxl}} switch.<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 />
=== xorg ===<br />
<br />
For KMS and accelerated graphics with xorg, install {{Pkg|xf86-video-modesetting}} in guest OS.<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 [[Persistent_block_device_naming#By-uuid|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 />
==== Block device drivers ====<br />
<br />
Preparing a Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [http://www.linux-kvm.org/page/WindowsGuestDrivers/Download_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<br />
<br />
Then connect with the the spice client<br />
<br />
$ spicec -h 127.0.0.1 -p 5930<br />
<br />
{{Tip|<br />
* Spice guest drivers can be downloaded [http://www.spice-space.org/download.html here] in the ''Guest'' section.<br />
* The key combination to escape mouse and keyboard grab can be configured, the default is {{ic|Shift+F12}}: {{bc|1=$ spicec --hotkeys release-cursor=ctrl+alt}}<br />
* To disable mouse and keyboard grabbing (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 />
}}<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 8.<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 />
=== 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 [[:Category:Hypervisors|hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<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<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>Blueriderhttps://wiki.archlinux.org/index.php?title=MariaDB&diff=345667MariaDB2014-11-22T01:41:19Z<p>Bluerider: Removed gzip pipe since the above text indicates to pipe the command through a stream compressor</p>
<hr />
<div>[[Category:Database management systems]]<br />
[[cs:MySQL]]<br />
[[de:MySQL]]<br />
[[es:MySQL]]<br />
[[fr:MySQL]]<br />
[[it:MySQL]]<br />
[[ja:MySQL]]<br />
[[ru:MySQL]]<br />
[[sr:MySQL]]<br />
[[tr:MySQL]]<br />
[[zh-CN:MySQL]]<br />
{{Related articles start}}<br />
{{Related|phpMyAdmin}}<br />
{{Related|Adminer}}<br />
{{Related articles end}}<br />
MySQL is a widely spread, multi-threaded, multi-user SQL database. For more information about features, see the [http://www.mysql.com/ official homepage].<br />
<br />
{{Note|MariaDB is now officially Arch Linux's default implementation of MySQL. It is recommended for all users to [[#Upgrade from Oracle MySQL to MariaDB|upgrade]] to MariaDB. Oracle MySQL was dropped to the [[AUR]]. See [https://www.archlinux.org/news/mariadb-replaces-mysql-in-repositories/ the announcement].}}<br />
<br />
== Installation ==<br />
<br />
The MySQL implementation chosen by Arch Linux is called [https://mariadb.org/ MariaDB].<br />
[[pacman|Install]] {{Pkg|mariadb}} from the [[official repositories]].<br />
Alternative implementations are:<br />
* {{App|Oracle MySQL|An implementation by Oracle Corporation.|https://www.mysql.com/|{{AUR|mysql}}}}<br />
* {{App|Percona Server|An implementation by Percona LLC.|http://www.percona.com/software/percona-server/|{{Pkg|percona-server}}}}<br />
<br />
{{Tip|If the database (in {{ic|/var/lib/mysql}}) resides in a [[btrfs]] file system you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the directory before creating any database:<br />
{{ic|# chattr +C /var/lib/mysql}}<br />
}}<br />
<br />
Start/enable {{ic|mysqld.service}} [[systemd#Using units|using systemd]], and then run the setup script:<br />
# mysql_secure_installation<br />
<br />
Restart {{ic|mysqld.service}} afterwards.<br />
<br />
MariaDB should now be up and running and secured! To simplify administration, you might want to install a front-end such as {{AUR|mysql-workbench}}.<br />
<br />
=== Upgrade from Oracle MySQL to MariaDB ===<br />
{{Note|It could be needed to remove the following files from {{ic|/var/lib/mysql}} : {{ic|ib_logfile0}}, {{ic|ib_logfile1}} and {{ic|aria_log_control}} before restarting the daemon in the following procedure.}}<br />
<br />
Users who want to switch will need to stop {{ic|mysqld.service}}, install {{pkg|mariadb}}, start {{ic|mysqld.service}}, and execute:<br />
# mysql_upgrade -u root -p<br />
in order to migrate their systems.<br />
<br />
=== On update ===<br />
You might consider running this command after you have done a major version upgrade (such as from 5.5 to 10.0, or from 10.0 to 10.1), and have restarted MySQL:<br />
# mysql_upgrade -u root -p<br />
<br />
== Configuration ==<br />
Once you have started the MySQL server, you probably want to add a root account in order to maintain your MySQL users and databases. This can be done manually or automatically, as mentioned by the output of the above script. Either run the commands to set a password for the root account, or run the secure installation script.<br />
<br />
You now should be able to do further configuration using your favorite interface. For example you can use MySQL's command line tool to log in as root into your MySQL server:<br />
$ mysql -u root -p<br />
<br />
=== Add user ===<br />
Creating a new user takes two steps: create the user; grant him privileges. In the below example, we create user ''monty'' with ''some_pass'' as password. <br />
<br />
{{hc|$ mysql -u root -p|<br />
MariaDB> CREATE USER 'monty'@'localhost' IDENTIFIED BY 'some_pass';<br />
MariaDB> GRANT ALL PRIVILEGES ON *.* TO 'monty'@'localhost'<br />
-> WITH GRANT OPTION;<br />
MariaDB> quit}}<br />
<br />
=== Configuration files ===<br />
<br />
''MariaDB'' configuration options are read from the following files in the given order (according to {{ic|mysqld --help --verbose | tail -20}} output):<br />
/etc/my.cnf /etc/mysql/my.cnf ~/.my.cnf<br />
<br />
Depending on the scope of the changes you want to make (system-wide, user-only...), use the corresponding file. See [https://mariadb.com/kb/en/mariadb/documentation/getting-started/starting-and-stopping-mariadb/mysqld-configuration-files-and-groups/ this entry] of the KnowledgeBase for more information.<br />
<br />
=== Grant remote access ===<br />
If you want to access your MySQL server from other LAN hosts, you have to comment out (with #) the following lines in your {{ic|/etc/mysql/my.cnf}}:<br />
[mysqld]<br />
...<br />
#skip-networking<br />
#bind-address = <some ip-address><br />
...<br />
Then you grant any mysql user you like remote access from your local network (example for root):<br />
Connect to your database as root:<br />
$ mysql -u root -p<br />
Check current users with remote access privileged:<br />
SELECT User, Host FROM mysql.user WHERE Host <> 'localhost';<br />
Now grant remote access for your user (here root)::<br />
GRANT ALL PRIVILEGES ON *.* TO 'root'@'192.168.1.%' IDENTIFIED BY 'my_optional_remote_password' WITH GRANT OPTION;<br />
You can change the '%' wildcard to a specific host if you like. The password can be different from user's main password.<br />
<br />
=== Disable remote access ===<br />
The MySQL server is accessible from the network by default. If MySQL is only needed for the localhost, you can improve security by not listening on TCP port 3306. To refuse remote connections, uncomment the following line in {{ic|/etc/mysql/my.cnf}}:<br />
skip-networking<br />
<br />
You will still be able to log in from the localhost.<br />
<br />
=== Enable auto-completion ===<br />
{{Note|Enabling this feature can make the client initialization longer.}}<br />
The MySQL client completion feature is disabled by default. To enable it system-wide edit {{ic|/etc/mysql/my.cnf}}, and replace {{ic|no-auto-rehash}} by {{ic|auto-rehash}}. Completion will be enabled next time you run the MySQL client.<br />
<br />
=== Using UTF-8 ===<br />
In the {{ic|/etc/mysql/my.cnf}} file section under the {{ic|mysqld}} group, add:<br />
<br />
{{bc|<nowiki><br />
[mysqld]<br />
init_connect = 'SET collation_connection = utf8_general_ci,NAMES utf8'<br />
collation_server = utf8_general_ci<br />
character_set_client = utf8<br />
character_set_server = utf8<br />
</nowiki>}}<br />
<br />
=== Using a TMPFS for tmpdir ===<br />
The directory used by MySQL for storing temporary files is named ''tmpdir''. For example, it is used to perform disk based large sorts, as well as for internal and explicit temporary tables.<br />
<br />
Create the directory with appropriate permissions:<br />
# mkdir -pv /var/lib/mysqltmp<br />
# chown mysql:mysql /var/lib/mysqltmp<br />
<br />
Find the id and gid of the {{ic|mysql}} user and group:<br />
$ id mysql<br />
uid=27(mysql) gid=27(mysql) groups=27(mysql)<br />
<br />
Add to your {{ic|/etc/fstab}} file.<br />
tmpfs /var/lib/mysqltmp tmpfs rw,gid=27,uid=27,size=100M,mode=0750,noatime 0 0<br />
<br />
Add to your {{ic|/etc/mysql/my.cnf}} file under the {{ic|mysqld}} group:<br />
tmpdir = /var/lib/mysqltmp<br />
<br />
Then reboot or ( shutdown mysql, mount the tmpdir, start mysql ).<br />
<br />
=== Time zone tables ===<br />
Although time zone tables are created during the installation, they are not automatically populated. They need to be populated if you are planning on using CONVERT_TZ() in SQL queries.<br />
<br />
To populate the time zone tables with all the time zones:<br />
$ mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql<br />
<br />
Optionally, you may populate the table with specific time zone files:<br />
$ mysql_tzinfo_to_sql <timezone_file> <timezone_name> | mysql -u root -p mysql<br />
<br />
== Backup ==<br />
<br />
There are various [https://mariadb.com/kb/en/mariadb/documentation/backing-up-and-restoring/ tools and strategies] to back up your databases.<br />
<br />
If you are using the default InnoDB storage engine, a [https://mariadb.com/kb/en/mariadb/documentation/clients-and-utilities/backup-restore-and-import/mysqldump/#examples suggested] way of backing up all your bases online while provisioning for [https://dev.mysql.com/doc/refman/5.6/en/password-security-user.html point-in-time recovery] (also known as “roll-forward,” when you need to restore an old backup and replay the changes that happened since that backup) is to execute the following command:<br />
<br />
$ mysqldump --single-transaction --flush-logs --master-data=2 --all-databases -u root -p > all_databases.sql<br />
<br />
This will prompt for '''MariaDB's''' root user's password, which was defined during database [[#Configuration|#configuration]].<br />
<br />
Specifying the password on the command line is [https://dev.mysql.com/doc/refman/5.6/en/password-security-user.html strongly discouraged], as it exposes it to discovery by other users through the use of {{ic|ps aux}} or other techniques. Instead, the aforementioned command will prompt for the specified user's password, concealing it away.<br />
<br />
=== Compression ===<br />
As SQL tables can get pretty large, it is recommended to pipe the output of the aforementioned command in your favourite [[List_of_applications/Utilities#Archiving_and_compression_tools|compression utility]]:<br />
$ mysqldump --single-transaction --flush-logs --master-data=2 --all-databases -u root -p<br />
<br />
=== Non-interactive ===<br />
<br />
If you want to setup non-interactive backup script for use in [[cron]] jobs or [[Systemd/cron_functionality|systemd timers]], see [https://dev.mysql.com/doc/refman/5.6/en/option-files.html option files] and [https://stackoverflow.com/a/9293090 this illustration] for ''mysqldump''.<br />
<br />
Basically you should add the following section to the relevant [[#Configuration_files|configuration file]]:<br />
{{bc|<nowiki><br />
[mysqldump]<br />
user=mysqluser<br />
password=secret<br />
</nowiki>}}<br />
<br />
Mentioning a user here is optional, but doing so will free you from having to mention it on the command line.<br />
<br />
==== Example script ====<br />
<br />
The database can be dumped to a file for easy backup. The following shell script will do this for you, creating a {{ic|db_backup.gz}} file in the same directory as the script, containing your database dump:<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
<br />
THISDIR=$(dirname $(readlink -f "$0"))<br />
<br />
mysqldump --single-transaction --flush-logs --master-data=2 --all-databases \<br />
| gzip > $THISDIR/db_backup.gz<br />
echo 'purge master logs before date_sub(now(), interval 7 day);' | mysql<br />
</nowiki>}}<br />
<br />
See also the official {{ic|mysqldump}} page in the [http://dev.mysql.com/doc/refman/5.6/en/mysqldump.html MySQL] and [https://mariadb.com/kb/en/mariadb/documentation/clients-and-utilities/backup-restore-and-import/mysqldump MariaDB] manuals.<br />
<br />
== Troubleshooting ==<br />
=== MySQL daemon cannot start ===<br />
If MySQL fails to start and there is no entry in the log files, you might want to check the permissions of files in the directories {{ic|/var/lib/mysql}} and {{ic|/var/lib/mysql/mysql}}. If the owner of files in these directories is not {{ic|mysql:mysql}}, you should do the following:<br />
# chown mysql:mysql /var/lib/mysql -R<br />
If you run into permission problems despite having followed the above, ensure that your {{ic|my.cnf}} is copied to {{ic|/etc/}}:<br />
# cp /etc/mysql/my.cnf /etc/my.cnf<br />
Now try and start the daemon.<br />
<br />
If you get these messages in your {{ic|/var/lib/mysql/hostname.err}}:<br />
[ERROR] Can't start server : Bind on unix socket: Permission denied<br />
[ERROR] Do you already have another mysqld server running on socket: /var/run/mysqld/mysqld.sock ?<br />
[ERROR] Aborting<br />
the permissions of {{ic|/var/run/mysqld}} could be the culprit.<br />
# chown mysql:mysql /var/run/mysqld -R<br />
<br />
If you run mysqld and the following error appears:<br />
Fatal error: Can’t open and lock privilege tables: Table ‘mysql.host’ doesn’t exist<br />
Run the following command from the {{ic|/usr}} directory to install the default tables:<br />
# cd /usr<br />
# mysql_install_db --user=mysql --ldata=/var/lib/mysql/<br />
<br />
=== Unable to run mysql_upgrade because MySQL cannot start ===<br />
Try run MySQL in safemode:<br />
# mysqld_safe --datadir=/var/lib/mysql/<br />
And then run:<br />
# mysql_upgrade -u root -p<br />
<br />
=== Reset the root password ===<br />
Stop {{ic|mysqld.service}}. Issue the following command:<br />
# mysqld_safe --skip-grant-tables &<br />
Connect to the mysql server. Issue the following command:<br />
# mysql -u root mysql<br />
Change root password:<br />
mysq/> use mysql;<br />
mysql> UPDATE mysql.user SET Password=PASSWORD('MyNewPass') WHERE User='root';<br />
mysql> FLUSH PRIVILEGES;<br />
mysql> exit<br />
Start {{ic|mysqld.service}}.<br />
<br />
=== Check and repair all tables ===<br />
Check and auto repair all tables in all databases, [http://dev.mysql.com/doc/refman/5.7/en/mysqlcheck.html see more]:<br />
# mysqlcheck -A --auto-repair -u root -p<br />
<br />
=== Optimize all tables ===<br />
Forcefully optimize all tables, automatically fixing table errors that may come up.<br />
# mysqlcheck -A --auto-repair -f -o -u root -p<br />
<br />
=== OS error 22 when running on ZFS ===<br />
If you are using [[ZFS]] and get the following error:<br />
InnoDB: Operating system error number 22 in a file operation.<br />
You need to disable aio_writes by adding a line to the mysqld-section in /etc/mysql/my.cnf <br />
[mysqld]<br />
...<br />
innodb_use_native_aio = 0<br />
<br />
However, if the post install scripts failed because of the above issue, MySQL/MariaDB might be in an invalid state. To recover from this state, execute the following:<br />
rm -rf /var/lib/mysql/*<br />
mysql_install_db --user=mysql --basedir=/usr --datadir=/var/lib/mysql<br />
chown -R mysql:mysql /var/lib/mysql &>/dev/null<br />
/usr/bin/systemd-tmpfiles --create mysql.conf<br />
<br />
After which MySQL/MariaDB should be installed correctly.<br />
<br />
=== Cannot login through CLI, but phpmyadmin works well ===<br />
This may happen if you're using a long (>70-75) password.<br />
As for 5.5.36, for some reason, mysql CLI cannot handle that much characters in readline mode.<br />
So, if you're planning to use the recommended password input mode:<br />
$ mysql -u <user> -p<br />
Password:<br />
consider changing the password to smaller one.<br />
<br />
{{Note|You still can log in by specifying the password an an argument to mysql command. <br />
{{Warning|This behavior considered dangerous, because your password might leak, for example, to the logs. Use it only in case of emergency and don't forget to change password right afterwards.}}<br />
$ mysql -u <user> -p"<some-veryveryveryveryveryveryveryveryveryveryveryveryveryveryvery-long-and-veryveryveryveryveryveryveryveryveryvery-strong-password>"<br />
}}<br />
<br />
===MySQL binary logs are taking up huge disk space===<br />
By default, mysqld creates binary log files in /var/lib/mysql. This is useful for replication master server or data recovery. But these binary logs can eat up your disk space. If you don't plan to use replication or data recovery features, you may disable binary logging by commenting out these lines in /etc/mysql/my.cnf:<br />
#log-bin=mysql-bin<br />
#binlog_format=mixed<br />
Alternatively, you can purge some binary logs in /var/lib/mysql to free up disk space with this command:<br />
#mysql -u root -p"PASSWORD" -e "PURGE BINARY LOGS TO 'mysql-bin.0000xx';"<br />
<br />
== See also ==<br />
<br />
* [https://mariadb.org/ MariaDB Official Website]<br />
* [https://mariadb.com/kb/en/ MariaDB knowledge Base]<br />
* [http://dev.mysql.com/doc/ MySQL documentation ]<br />
* [[LAMP]] - ArchWiki article covering the setup of a LAMP server (Linux Apache MySQL PHP)<br />
* [[PhpMyAdmin]] - ArchWiki article covering the web-based tool to help manage MySQL databases using an Apache/PHP front-end.<br />
* [[PHP]] - ArchWiki article on PHP.<br />
* [http://www.askapache.com/mysql/performance-tuning-mysql.html MySQL Performance Tuning Scripts and Know-How]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Steam&diff=344573Steam2014-11-14T06:40:03Z<p>Bluerider: /* Flash audio not working on 64-bit systems */ Move post down one subsection</p>
<hr />
<div>[[Category:Gaming]]<br />
[[ja:Steam]]<br />
[[ru:Steam]]<br />
[[zh-CN:Steam]]<br />
{{Related articles start}}<br />
{{Related|Steam/Wine}}<br />
{{Related|Steam/Game-specific troubleshooting}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Steam (software)|Wikipedia]]:<br />
: ''Steam is a digital distribution, digital rights management, multiplayer and communications platform developed by Valve Corporation. It is used to distribute games and related media online, from small independent developers to larger software houses.''<br />
<br />
[http://store.steampowered.com/about/ Steam] is best known as the platform needed to play Source Engine games (e.g. Half-Life 2, Counter-Strike). Today it offers many games from many other developers.<br />
<br />
== Installation ==<br />
<br />
{{Note|<br />
* Arch Linux is '''not''' [https://support.steampowered.com/kb_article.php?ref&#61;1504-QHXN-8366 officially supported].<br />
* Because the Steam client is a 32-bit application, you will need to enable the [[multilib]] repository if you have a 64-bit system. It may also make sense to install {{Grp|multilib-devel}} to provide some important multilib libraries.<br />
}}<br />
<br />
Steam can be installed with the package {{Pkg|steam}}, available in the [[official repositories]]. If you have a 64-bit system, enable the [[multilib]] repository first.<br />
<br />
Steam is not supported on this distribution. As such some fixes are needed on the users part to get things functioning properly:<br />
<br />
*Steam makes heavy usage of the Arial font. A decent Arial font to use is {{Pkg|ttf-liberation}} or [[#Text is corrupt or missing|the fonts provided by Steam]]. Asian languages require {{Pkg|wqy-zenhei}} to display properly.<br />
<br />
*'''If you have a 64-bit system, you will need to install [[Xorg#Driver installation|the 32-bit version of your graphics driver]] (the package in the ''Multilib Package'' column) to run 32-bit games'''.<br />
<br />
*If you have a 64-bit system, you will need to install {{pkg|lib32-alsa-plugins}} to enable sound in 32-bit games.<br />
<br />
*Several games have dependencies which may be missing from your system. If a game fails to launch (often without error messages) then make sure all of the libraries listed in [[Steam/Game-specific troubleshooting]] are installed.<br />
<br />
== Starting Steam ==<br />
<br />
=== Big Picture Mode (with a Display Manager) ===<br />
<br />
To start Steam in Big Picture Mode from a Display Manager (such as LightDM), create a {{ic|/usr/share/xsessions/steam-big-picture.desktop}} file with the following content:<br />
<br />
{{hc|/usr/share/xsessions/steam-big-picture.desktop|<nowiki><br />
[Desktop Entry]<br />
Name=Steam Big Picture Mode<br />
Comment=Start Steam in Big Picture Mode<br />
Exec='/usr/bin/steam -bigpicture'<br />
TryExec='/usr/bin/steam -bigpicture'<br />
Icon=<br />
Type=Application</nowiki>}}<br />
<br />
Alternatively, under Steam > Settings > Interface, check 'Start Steam in Big Picture Mode' and start Steam normally. This can behave slightly better with certain window managers than the command line option.<br />
<br />
=== Silent Mode ===<br />
<br />
If your steam main window is showing at startup, you can add the {{ic|-silent}} parameter to your startup command to hide the window:<br />
/usr/bin/steam -silent %U<br />
<br />
alternatively, you can edit the following desktop file, and manually add the parameter:<br />
<br />
{{hc|~/.config/autostart/steam.desktop|<nowiki><br />
[Desktop Entry]<br />
Name=Steam<br />
Comment=Application for managing and playing games on Steam<br />
Exec=/usr/bin/steam -silent %U<br />
Icon=steam<br />
Terminal=false<br />
Type=Application<br />
Categories=Network;FileTransfer;Game;<br />
MimeType=x-scheme-handler/steam;<br />
Actions=Store;Community;Library;Servers;Screenshots;News;Settings;BigPicture;Friends;<br />
...</nowiki>}}<br />
<br />
== Troubleshooting ==<br />
<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 />
=== Steam runtime issues ===<br />
<br />
[https://github.com/ValveSoftware/steam-runtime/issues/13 Upstream GitHub issue tracker]<br />
<br />
Steam ships with its own versions of some libraries (the "Steam Runtime") in an attempt to emulate the Ubuntu 12.04 environment in later versions of Ubuntu.<br />
<br />
However, some core libraries included in the Steam Runtime will often conflict with the newer versions of other libraries included in Arch Linux (such as drivers, and specifically the open-source [[ATI]] driver).<br />
<br />
You can work around this by deleting the Steam Runtime versions of these libraries, forcing Steam to fall back to the up-to-date system versions (the ones installed by [[pacman]]).<br />
<br />
Note that Steam will frequently re-install these runtime libraries when Steam is updated, so until [https://github.com/ValveSoftware/steam-runtime/issues/13 ValveSoftware/steam-runtime#13] is resolved, whenever Steam updates, you should exit, remove the libraries, and restart it again.<br />
<br />
Run these commands to remove runtime libraries known to cause issues with Arch Linux:<br />
<br />
{{bc|<br />
rm ~/.local/share/Steam/ubuntu12_32/steam-runtime/i386/usr/lib/i386-linux-gnu/libstdc++.so.6<br />
rm ~/.local/share/Steam/ubuntu12_32/steam-runtime/i386/lib/i386-linux-gnu/libgcc_s.so.1<br />
rm ~/.local/share/Steam/ubuntu12_32/steam-runtime/amd64/lib/x86_64-linux-gnu/libgcc_s.so.1<br />
rm ~/.local/share/Steam/ubuntu12_32/steam-runtime/amd64/usr/lib/x86_64-linux-gnu/libstdc++.so.6<br />
rm ~/.local/share/Steam/ubuntu12_32/steam-runtime/i386/usr/lib/i386-linux-gnu/libxcb.so.1<br />
}}<br />
<br />
Examples of issues / error messages known to occur if these libraries are present:<br />
<br />
* {{ic|Failed to load libGL: undefined symbol: xcb_send_fd}}<br />
* {{ic|ERROR: ld.so: object '~/.local/share/Steam/ubuntu12_32/gameoverlayrenderer.so' from LD_PRELOAD cannot be preloaded (wrong ELF class: ELFCLASS32): ignored.}}<br />
* Problems with 64-bit games like XCOM<br />
* "OpenGL GLX context is not using direct rendering, which may cause performance problems." [[#OpenGL not using direct rendering / Steam crashes Xorg|(see below)]]<br />
* "Could not find required OpenGL entry point 'glGetError'! Either your video card is unsupported or your OpenGL driver needs to be updated."<br />
* The Steam client itself crashing<br />
<br />
Forum threads:<br />
<br />
* https://bbs.archlinux.org/viewtopic.php?id=181171<br />
* https://bbs.archlinux.org/viewtopic.php?id=183141<br />
<br />
See also [[#Using native runtime]] below.<br />
<br />
=== The close button only minimizes the window ===<br />
<br />
: Valve GitHub [https://github.com/ValveSoftware/steam-for-linux/issues/1025 issue 1025]<br />
<br />
To close the Steam window (and remove it from the taskbar) when you press '''x''', but keep Steam running in the tray, set the environment variable {{ic|STEAM_FRAME_FORCE_CLOSE}} to {{ic|1}}. You can do this by launching Steam using the following command.<br />
$ STEAM_FRAME_FORCE_CLOSE=1 steam<br />
<br />
If you start steam with the .desktop file, you need to replace the {{ic|Exec}} with following line:<br />
Exec=sh -c 'STEAM_FRAME_FORCE_CLOSE=1 steam' %U<br />
<br />
=== Flash not working on 64-bit systems ===<br />
<br />
: Steam Support [https://support.steampowered.com/kb_article.php?ref=1493-GHZB-7612 article]<br />
<br />
First ensure {{Pkg|lib32-flashplugin}} is installed. It should be working at this point, if not 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 />
=== Flash audio not working on 64-bit systems ===<br />
<br />
If you don't have audio in the videos which play within the Steam Client and you're sure you have libflashplayer.so installed correctly, it's possible Steam is using packaged ALSA libs which aren't working.<br><br />
If launching Steam from a terminal and attempting to playback a video within the steam client results in an error similar to the following:<br><br />
{{bc|ALSA lib pcm_dmix.c:1018:(snd_pcm_dmix_open) unable to open slave}}<br><br />
There is a workaround which involves renaming or deleting some Steam Runtime folders and library files.<br><br />
The bugs have already been reported here: [https://github.com/ValveSoftware/steam-for-linux/issues/3376 #3376] and [https://github.com/ValveSoftware/steam-for-linux/issues/3504 #3504]<br><br />
The solution is to rename or delete the alsa-lib folder and the libasound.so.* files.<br><br />
They can be found within<br><br />
{{bc|~/.steam/steam/ubuntu12_32/steam-runtime/i386/usr/lib/i386-linux-gnu/}}<br><br />
<br />
=== Text is corrupt or missing ===<br />
<br />
The Steam Support [https://support.steampowered.com/kb_article.php?ref=1974-YFKL-4947 instructions] for Windows seem to work on Linux also.<br />
<br />
You can install them via {{AUR|steam-fonts}} from the [[AUR]], or manually by downloading and [[fonts#Manual installation|installing]] [https://support.steampowered.com/downloads/1974-YFKL-4947/SteamFonts.zip SteamFonts.zip].<br />
<br />
=== SetLocale('en_US.UTF-8') fails at game startup ===<br />
<br />
Uncomment {{ic|en_US.UTF-8 UTF-8}} in {{ic|/etc/locale.gen}} and then run {{ic|locale-gen}} as root.<br />
<br />
=== The game crashes immediately after start ===<br />
<br />
If your game crashes immediately, try disabling: ''"Enable the Steam Overlay while in-game"'' in game ''Properties''.<br />
<br />
=== OpenGL not using direct rendering / Steam crashes Xorg ===<br />
<br />
Sometimes presented with the error message "OpenGL GLX context is not using direct rendering, which may cause performance problems." [https://support.steampowered.com/kb_article.php?ref=9938-EYZB-7457]<br />
<br />
If you still encounter this problem after addressing [[#Steam runtime issues]], you have probably not installed your 32-bit graphics driver correctly. See [[Xorg#Driver installation]] for which packages to install.<br />
<br />
You can check/test if it is installed correctly by installing {{Pkg|lib32-mesa-demos}} and running the following command:<br />
<br />
$ glxinfo32 | grep OpenGL.<br />
<br />
=== No audio in certain games ===<br />
<br />
If there is no audio in certain games, and the suggestions provided in [[Steam/Game-specific troubleshooting]] do not fix the problem, [[#Using native runtime]] may provide a successful workaround. (See the note about "Steam Runtime issues" at the top of this section.)<br />
<br />
=== You are missing the following 32-bit libraries, and Steam may not run: libGL.so.1 ===<br />
<br />
You may encounter this error when you launch Steam at first time. Make sure you have installed the {{ic|lib32}} version of all your video drivers. For example, if you have installed {{Pkg|catalyst-utils-pxp}}, {{Pkg|xf86-video-dri}}, {{Pkg|mesa-dri}}, {{Pkg|mesa-libgl}} for AMD and Intel double card, then you should install {{Pkg|lib32-catalyst-utils-pxp}}, {{Pkg|lib32-mesa-dri}}, {{Pkg|lib32-mesa-libgl}}.<br />
<br />
In some cases, if you get this error after reinstalling your NVidia proprietary drivers, or switching from a version to another, [[reinstall]] {{Pkg|lib32-nvidia-utils}} and {{Pkg|lib32-nvidia-libgl}}.<br />
<br />
=== Games do not launch on older intel hardware ===<br />
<br />
On older Intel hardware, if the game immediately crashes when run, it may be because your hardware does not directly support the latest OpenGL. It appears as a gameoverlayrenderer.so error in /tmp/dumps/mobile_stdout.txt, but looking in /tmp/gameoverlayrenderer.log it shows a GLXBadFBConfig error. <br />
<br />
This can be fixed, however, by forcing the game to use a later version of OpenGL than it wants. Right click on the game, select Properties. Then, click "Set Launch Options" in the "General" tab and paste the following:<br />
<br />
MESA_GL_VERSION_OVERRIDE=3.1 MESA_GLSL_VERSION_OVERRIDE=140 %command%<br />
<br />
== Launching games with custom commands, such as Bumblebee/Primus ==<br />
<br />
Steam has fortunately added support for launching games using your own custom command. To do so, navigate to the Library page, right click on the selected game, click Properties, and Set Launch Options. Steam replaces the tag {{ic|%command%}} with the command it actually wishes to run. For example, to launch Team Fortress 2 with primusrun and at resolution 1920x1080, you would enter:<br />
<br />
primusrun %command% -w 1920 -h 1080<br />
<br />
If you are running the [[Linux-ck]] kernel, you may have some success in reducing overall latencies and improving performance by launching the game in SCHED_ISO (low latency, avoid choking CPU) via {{Pkg|schedtool}}<br />
<br />
# schedtool -I -e %command% ''other arguments''<br />
<br />
=== Killing standalone compositors when launching games ===<br />
<br />
Further to this, utilising the {{ic|%command%}} switch, you can kill standalone compositors (such as Xcompmgr or [[Compton]]) - which can cause lag and tearing in some games on some systems - and relaunch them after the game ends by adding the following to your game's launch options.<br />
<br />
killall compton && %command%; nohup compton &<br />
<br />
Replace {{ic|compton}} in the above command with whatever your compositor is. You can also add -options to {{ic|%command%}} or {{ic|compton}}, of course.<br />
<br />
Steam will latch on to any processes launched after {{ic|%command%}} and your Steam status will show as in game. So in this example, we run the compositor through {{ic|nohup}} so it is not attached to Steam (it will keep running if you close Steam) and follow it with an ampersand so that the line of commands ends, clearing your Steam status.<br />
<br />
== Using native runtime ==<br />
<br />
Steam, by default, ships with a copy of every library it uses, packaged within itself, so that games can launch without issue. This can be a resource hog, and the slightly out-of-date libraries they package may be missing important features (Notably, the OpenAL version they ship lacks HRTF and surround71 support). To use your own system libraries, you can run Steam with:<br />
<br />
$ STEAM_RUNTIME=0 steam<br />
<br />
However, if you are missing any libraries Steam makes use of, this will fail to launch properly. An easy way to find the missing libraries is to run the following commands:<br />
<br />
$ cd ~/.local/share/Steam/ubuntu12_32<br />
$ LD_LIBRARY_PATH=".:${LD_LIBRARY_PATH}" ldd $(file *|sed '/ELF/!d;s/:.*//g')|grep 'not found'|sort|uniq<br />
<br />
{{Note|The libraries will have to be 32-bit, which means you may have to download some from the AUR if on x86_64, such as NetworkManager.}}<br />
<br />
Once you have done this, run steam again with {{ic|1=STEAM_RUNTIME=0 steam}} and verify it is not loading anything outside of the handful of steam support libraries:<br />
<br />
$ cat /proc/$(pidof steam)/maps|sed '/\.local/!d;s/.* //g'|sort|uniq<br />
<br />
'''Convenience repository'''<br />
<br />
The unofficial [[Unofficial_user_repositories#alucryd-multilib|alucryd-multilib]] repository contains all libraries needed to run native steam on x86_64. Please note that, for some reason, steam does not pick up sdl2 or libav* even if you have them installed. It will still use the ones it ships with.<br />
<br />
All you need to install is the meta-package {{ic|steam-libs}}, it will pull all the libs for you. Please report if there is any missing library, the maintainer already had some lib32 packages installed so a library may have been overlooked.<br />
<br />
== Skins for Steam ==<br />
<br />
{{Note|Using skins that are not up-to-date with the version of the Steam client may cause visual errors.}}<br />
<br />
The Steam interface can be fully customized by copying its various interface files in its skins directory and modifying them.<br />
<br />
An extensive list of skins can be found on [http://forums.steampowered.com/forums/showthread.php?t=1161035 Steam's forums].<br />
<br />
=== 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.<br />
<br />
== Changing the Steam friends notification placement ==<br />
<br />
{{Note|A handful of games do not support this, for example this can not work with XCOM: Enemy Unknown.}}<br />
<br />
=== Use a skin ===<br />
<br />
You can create a skin that does nothing but change the notification corner. First you need to create the directories:<br />
<br />
$ mkdir -p $HOME/Top-Right/resource<br />
$ cp -R $HOME/.steam/steam/resource/styles $HOME/Top-Right/resource/<br />
$ mv $HOME/Top-Right $HOME/.local/share/Steam/skins/<br />
$ cd .local/share/Steam/skins/<br />
$ cp -R Top-Right Top-Left && cp -R Top-Right Bottom-Right<br />
<br />
Then modify the correct files. {{ic|Top-Right/resource/styles/gameoverlay.style}} will change the corner for the in-game overlay whereas {{ic|steam.style}} will change it for your desktop.<br />
<br />
Now find the entry: {{ic|Notifications.PanelPosition}} in whichever file you opened and change it to the appropriate value, for example for Top-Right:<br />
<br />
Notifications.PanelPosition "TopRight"<br />
<br />
This line will look the same in both files. Repeat the process for all the 3 variants ({{ic|Top-Right}}, {{ic|Top-Left}} and {{ic|Bottom-Left}}) and adjust the corners for the desktop and in-game overlay to your satisfaction for each skin, then save the files.<br />
<br />
To finish you will have to select the skin in Steam: ''Settings > Interface'' and ''<default skin>'' in the drop-down menu.<br />
<br />
You can use these files across distributions and even between Windows and Linux (OS X has its own entry for the desktop notification placement)<br />
<br />
=== On The fly patch ===<br />
<br />
This method is more compatible with future updates of Steams since the files in the skins above are updated as part of steam and as such if the original files change, the skin will not follow the graphics update to steam and will have to be re-created every time something like that happens. Doing things this way will also give you the ability to use per-game notification locations as you can run a patch changing the location of the notifications by specifying it in the launch options for games.<br />
<br />
Steam updates the files we need to edit everytime it updates (which is everytime it is launched) so the most effective way to do this is patching the file after Steam has already been launched.<br />
<br />
First you will need a patch:<br />
<br />
{{hc|$HOME/.steam/topright.patch|<nowiki><br />
--- A/steam/resource/styles/gameoverlay.styles 2013-06-14 23:49:36.000000000 +0000<br />
+++ B/steam/resource/styles/gameoverlay.styles 2014-07-08 23:13:15.255806000 +0000<br />
@@ -7,7 +7,7 @@<br />
mostly_black "0 0 0 240"<br />
semi_black "0 0 0 128"<br />
semi_gray "32 32 32 220"<br />
- Notifications.PanelPosition "BottomRight"<br />
+ Notifications.PanelPosition "TopRight"<br />
}<br />
<br />
styles<br />
<br />
</nowiki>}}<br />
<br />
{{Note|The patch file should have all above lines, including the newline at the end.}}<br />
<br />
You can edit the entry and change it between "BottomRight"(default), "TopRight" "TopLeft" and "BottomLeft": the following will assume you used "TopRight" as in the original file.<br />
<br />
Next create an alias in {{ic|$HOME/.bashrc}}:<br />
<br />
alias steam_topright='pushd $HOME/.steam/ && patch -p1 -f -r - --no-backup-if-mismatch < topright.patch && popd'<br />
<br />
Log out and back in to refresh the aliases. Launch Steam and wait for it to fully load, then run the alias <br />
<br />
$ steam_topright<br />
<br />
And most games you launch after this will have their notification in the upper right corner.<br />
<br />
You can also duplicate the patch and make more aliases for the other corners if you do not want all games to use the same corner so you can switch back.<br />
<br />
To automate the process you will need a script file as steam launch options cannot read your aliases. The location and name of the file could for example be '''$HOME/.scripts/steam_topright.sh''', and assuming that is the path you used, it needs to be executable:<br />
<br />
$ chmod +755 $HOME/.scripts/steam_topright.sh<br />
<br />
The contents of the file should be the following:<br />
<br />
#!/bin/sh<br />
pushd $HOME/.steam/ && patch -p1 -f -r - --no-backup-if-mismatch < topright.patch && popd<br />
<br />
And the launch options should be something like the following.<br />
<br />
$HOME/.scripts/steam_topright.sh && %command%<br />
<br />
There is another file in the same folder as '''gameoverlay.style''' folder called '''steam.style''' which has an entry with the exact same function as the file we patched and will change the notification corner for the desktop only (not in-game), but for editing this file to actually work it has to be set before steam is launched and the folder set to read-only so steam cannot re-write the file. Therefore the only two ways to modify that file is to make the directory read only so steam cannot change it when it is launched (can break updates) or making a skin like in method 1.<br />
<br />
== See also ==<br />
<br />
* https://wiki.gentoo.org/wiki/Steam</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Openbox&diff=317071Openbox2014-05-29T03:46:46Z<p>Bluerider: Undo revision 316253 by Lonaowna (talk) I don't see dbus mentioned anywhere in the xinitrc page. Please show me where it is.</p>
<hr />
<div>[[Category:Stacking WMs]]<br />
[[cs:Openbox]]<br />
[[de:Openbox]]<br />
[[es:Openbox]]<br />
[[fr:Openbox]]<br />
[[it:Openbox]]<br />
[[ja:Openbox]]<br />
[[ko:Openbox]]<br />
[[lt:Openbox]]<br />
[[nl:Openbox]]<br />
[[pl:Openbox]]<br />
[[ru:Openbox]]<br />
[[sk:Openbox]]<br />
[[sr:Openbox]]<br />
[[tr:Openbox]]<br />
[[zh-CN:Openbox]]<br />
[[zh-TW:Openbox]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Window manager}}<br />
{{Related|Oblogout}}<br />
{{Related articles end}}<br />
<br />
Openbox is a lightweight, powerful, and highly configurable ''stacking'' [[Window manager|window manager]] with extensive standards support. It may be built upon and run independently as the basis of a unique [[desktop environment]], or within other integrated desktop environments such as [[KDE]] and [[Xfce]], as an alternative to the window managers they provide. The [[LXDE]] desktop environment is itself built around Openbox.<br />
<br />
A comprehensive list of features are documented at the [http://openbox.org/ official Openbox website]. This article pertains to specifically installing Openbox under Arch Linux.<br />
<br />
== Installation ==<br />
<br />
Install {{Pkg|openbox}}, available in the [[official repositories]].<br />
<br />
== Openbox Sessions ==<br />
<br />
Again, Openbox may be run independently as a standalone window manager, or within other integrated desktop environments such as [[KDE]] and [[XFCE]] as an alternative to the window managers they provide.<br />
<br />
=== Standalone ===<br />
<br />
Many popular [[Display manager|display managers]] such as [[LXDM]], [[SLiM]], and [[LightDM]] will automatically detect Openbox, allowing for it to be run as a standalone session.<br />
<br />
However, it may be necessary to manually specify the command to start an openbox session where intending to set it as a default session for [[SLiM]], or where not using a display manager at all (e.g. logging in at the command line, followed by the command {{ic|startx}}). In either instance, it will be necessary to modify the [[Xinitrc]] file in order to add the following command:<br />
<br />
exec openbox-session<br />
<br />
=== Within other desktop environments ===<br />
<br />
When replacing the native window manager of a desktop environment with Openbox, any desktop compositing effects - such a transparency - provided by that native window manager will be lost. This is because Openbox itself does not provide any compositing functionality. However, it is easily possible to use a separate compositing program to [[Openbox#Compositing effects|re-enable compositing]]. <br />
<br />
==== GNOME ====<br />
<br />
Openbox does not seem to work with [[GNOME|GNOME 3]]. The {{ic|Gnome-Shell}} touch-style interface requires both its native window manager and its native gtk-window-decorator packages to function. Furthermore, attempting to run Openbox within the {{ic|Classic-Gnome-Shell}} interface results in the loss of the {{ic|gnome-panel}}. Ceasing Openbox and attempting to restore the native window manager will result in crashing the desktop. Gnome 3 is tightly integrated, and is therefore deliberately designed not to be modular in nature (i.e. allowing components to be changed).<br />
<br />
==== KDE ====<br />
See the [[KDE#Using Openbox in KDE|using Openbox in KDE]] section of the main [[KDE]] article.<br />
<br />
==== Xfce ====<br />
<br />
See the [[Xfce#Replacing_the_native_window_manager|replacing the native window manager]] section of the main [[Xfce]] article.<br />
<br />
== System configuration==<br />
<br />
Those installing Openbox - particularly as a stand-alone Window Manager - will have noticed that several elements may fail to work properly, or even work at all. Examples of the common problems encountered are:<br />
<br />
* '''File Managers''': Other partitions are not displayed or accessible. The trash function - where provided - does not work <br />
* '''Authentication''': Passwords are not stored / remembered during sessions<br />
* '''Secure Shell (SSH)''': SSH agent will not start<br />
* '''Wireless Connection''': Instant failure when attempting to connect to wifi (related to authentication) <br />
* '''Themes''': Application windows are mismatched or haphazard-looking<br />
* '''Folders''': Expected folders such as {{ic|Documents}}, {{ic|Downloads}} and so forth are missing from the {{ic|Home}} folder<br />
* '''System Tray''': Installed packages fail to autostart or can be seen running twice<br />
<br />
Most of these problems are actually the result of [[Dbus]] and [[GTK]] issues, both of which can be fixed simultaneously by editing the [[xprofile|~/.xprofile]] file - or if using [[SLiM]] as a [[display manager]] instead - by editing the [[xinitrc|~/.xinitrc]] file. It will also be necessary to install some key packages to ensure full functionality.<br />
<br />
=== D-Bus ===<br />
<br />
File manager, authentication, SSH agent, and WiFi-connection problems will likely be due to that [[D-Bus]] is not functioning correctly. Most [[display manager]]s such as [[GDM]], [[KDM]], [[LightDM]] and [[LXDM]] will handle this for you.<br />
<br />
When using [[xinit]] or certain other DMs (such as [[XDM]] and [[SLiM]]), make sure {{ic|~/.xinitrc}} is based on {{ic|/etc/skel/.xinitrc}} (so that it sources {{ic|/etc/X11/xinit/xinitrc.d/}}, see [[xinitrc]] for more information).<br />
<br />
To launch dbus + openbox with {{ic|startx}}, append {{ic| exec dbus-launch --sh-syntax --exit-with-session openbox-session}} to {{ic|~/.xinitrc}}.<br />
<br />
=== GTK+ 2 ===<br />
<br />
Problems with the theme and look will likely be due to the absence of the appropriate command to ensure that a uniform look must be applied to applications that use GTK 2. Again, edit {{ic|~/.xinitrc}} and/or {{ic|~/.xprofile}} with the following command:<br />
<br />
export GTK2_RC_FILES="$HOME/.gtkrc-2.0" <br />
<br />
The {{ic|~/.gtkrc-2.0}} file will be automatically generated where using [[LXDE|lxappearance]] to set themes.<br />
<br />
It will also be necessary to install {{Pkg|libgnomeui}} to ensure that [[Qt]] is also able to find GTK themes.<br />
<br />
See [[GTK+#GTK+ 2.x]] for an introduction to manually editing {{ic|~/.gtkrc-2.0}}.<br />
<br />
=== XDG ===<br />
<br />
In addition to sourcing the '''local''' {{ic|~/.config/openbox/autostart}} file to autostart applications, Openbox will also source {{ic|.desktop}} files automatically installed by some packages in the '''global''' {{ic|/etc/xdg/autostart}} directory. The package responsible for allowing Openbox to additionally source the {{ic|/etc/xdg/autostart}} directory is {{Pkg|python2-xdg}}. <br />
<br />
For example, where initially autostarting a package such as the [[NetworkManager|Network Manager]] applet ('''nm-applet''') locally, should {{Pkg|python2-xdg}} be installed at a later time - either explicitly or as a dependency for another package - its global XDG {{ic|.desktop}} file will then also be sourced as a consequence, resulting in seeing two icons running in the system tray. It is therefore recommended to install {{Pkg|python2-xdg}} explicitly, as this will ensure that applications that should automatically autostart when installed will do so.<br />
<br />
=== Home folders ===<br />
<br />
{{Tip|This fix will be especially helpful for those who wish to use a file manager to manage their desktop, as it will automatically create a special {{ic|~/Desktop}} directory, which will house all files and application shortcuts stored on the desktop itself.}}<br />
<br />
Where expected {{ic|Home}} folders such as {{ic|Downloads}}, {{ic|Documents}}, etc., are not present, then please review the [[Xdg user directories]] article.<br />
<br />
=== Authentication and passwords ===<br />
<br />
For authentication (e.g. WiFi passwords, etc.), it will be necessary to install the appropriate packages. They are:<br />
<br />
* {{Pkg|polkit}}: Application development toolkit for controlling system-wide privileges; see [[polkit]]<br />
* {{Pkg|lxpolkit}}: Simple policykit authentication agent for LXDE ({{Pkg|polkit-gnome}} currently does not work properly)<br />
* {{Pkg|gnome-keyring}}: store / remember passwords; see [[GNOME Keyring]]<br />
<br />
== Configuration ==<br />
<br />
{{Warning|Edit these files as the user you will be using Openbox with. Not as root!}}<br />
{{Tip|Local configuration files will always override global equivalents. These files may also be manually edited by any appropriate text editor, such as Leafpad or Geany; there is no need to use [[sudo]] or '''gksu''' commands to edit them.}}<br />
<br />
Four key files form the basis of the openbox configuration, each serving a unique role. They are: {{ic|rc.xml}}, {{ic|menu.xml}}, {{ic|autostart}}, and {{ic|environment}}. Although these files are discussed in more detail below, to start configuring Openbox, it will first be necessary to create a '''local''' Openbox profile (i.e for your specific user account) based on them. This can be done by copying them from the '''global''' {{ic|/etc/xdg/openbox}} profile (applicable to any and all users) as a template:<br />
<br />
$ mkdir -p ~/.config/openbox<br />
$ cp -R /etc/xdg/openbox/* ~/.config/openbox<br />
<br />
=== rc.xml ===<br />
<br />
{{Tip|Custom keyboard shortcuts (keybindings) must be added to the {{ic|<keyboard>}} section of this file, and underneath the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading.}}<br />
<br />
{{ic|~/.config/openbox/rc.xml}} is the main configuration file, responsible for determining the behaviour and settings of the overall session, including:<br />
<br />
* Keyboard shortcuts (e.g. starting applications; controlling the volume)<br />
* Theming<br />
* Desktop and Virtual desktop settings, and<br />
* Application Window settings<br />
<br />
This file is also pre-configured, meaning that it will only be necessary to amend existing content in order to customise behaviour to suit personal preference.<br />
<br />
=== menu.xml ===<br />
<br />
{{ic|~/.config/openbox/menu.xml}} defines the type and behaviour of the desktop menu, accessable by right-clicking the background. Although the default provided is a '''static menu''' (meaning that it will not automatically update when new applications are installed), it is possible to employ the use of '''dynamic menus''' that will automatically update as well. <br />
<br />
The available options are discussed extensively below in the [[Openbox#Menus|Menus]] section.<br />
<br />
=== autostart ===<br />
<br />
{{Tip|Be aware that some applications will automatically start via {{ic|.desktop}} files installed in the {{ic|/etc/xdg/autostart/}} or {{ic|~/.config/autostart/}} directories.}}<br />
<br />
{{ic|~/.config/openbox/autostart}} determines which applications are to be launched upon beginning the Openbox session. These may include:<br />
<br />
* Panels and/or docks<br />
* Compositors<br />
* Background providers<br />
* Screensavers<br />
* Applications to autoload or autostart (e.g. [[Conky]])<br />
* [[Daemon]] processes (e.g. File Managers for automounting and other functions)<br />
* Other appropriate commands (e.g. disable [[DPMS]])<br />
<br />
==== Listing commands ====<br />
<br />
There are two very important points to note when adding commands to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
* Each and every command '''must''' be terminated with an ampersand ({{ic|&}}). Where a command does not end with an ampersand, then no further commands listed below it will be executed.<br />
* It is strongly recommended to add delays to the execution of some or all commands in the autostart file, even if only by a single second. The consequence of not doing so is that all commands will be executed simultaneously, potentially resulting in the mis- or non-starting of items. The syntax of the command to delay the execution of commands (in seconds) is:<br />
<br />
(sleep <number of seconds>s && <command>) &<br />
<br />
For example, to delay the execution of [[Conky]] by 3 seconds, the command would be (and note the termination of it with an ampersand):<br />
<br />
(sleep 3s && conky) &<br />
<br />
Here is a more complete example of a possible {{ic|~/.config/openbox/autostart}} file:<br />
<br />
## Autostart File ##<br />
<br />
##Disable DPMS<br />
xset -dpms; xset s off &<br />
<br />
##Compositor<br />
compton -CGb &<br />
<br />
##Background<br />
(sleep 1s && nitrogen --restore) &<br />
<br />
##tint2 panel<br />
(sleep 1s && tint2) &<br />
<br />
##Sound Icon<br />
(sleep 1s && volumeicon) &<br />
<br />
##Screensaver<br />
(sleep 1s && xscreensaver -no-splash) &<br />
<br />
##Conky<br />
(sleep 3s && conky) &<br />
<br />
##Disable touchpad<br />
/usr/bin/synclient TouchpadOff=1 &<br />
<br />
=== environment ===<br />
<br />
{{Note|This is the least important file, and many users may not need to edit it at all.}}<br />
<br />
{{ic|~/.config/openbox/environment}} can be used to export and set relevant environmental variables such as to:<br />
<br />
* Define new pathways (e.g. execute commands that would otherwise require the entire pathway to be listed with them)<br />
* Change language settings, and<br />
* Define other variables to be used (e.g. the fix for GTK theming could be listed here)<br />
<br />
=== Optional GUI configuration packages ===<br />
<br />
Several GUIs are available to quickly and easily configure your Openbox desktop. From the official repositories these include:<br />
<br />
* {{Pkg|obconf}}: Basic Openbox configuration manager<br />
* {{Pkg|lxappearance-obconf}}: LXDE configuration manager (provides additional options)<br />
* {{Pkg|lxinput}}: LXDE keyboard and mouse configuration<br />
* {{Pkg|lxrandr}}: LXDE monitor configuration<br />
<br />
Others, such as {{AUR|obkey}} (configure keyboard shortcuts via the {{ic|rc.xml}} file) and {{AUR|ob-autostart}} (configure the Openbox {{ic|autostart}} file) are available from the [[AUR]]. Programs and applications relating to the configuration of Openbox's desktop menu are discussed in the [[Openbox#Menus|Menus]] section.<br />
<br />
== Openbox reconfiguration ==<br />
<br />
{{Tip|where not already present, it would be worthwhile adding this command to a menu and/or as a keybind for convenience.}}<br />
<br />
Openbox will not always automatically reflect any changes made to its configuration files within a session. As a consequence, it will be necessary to manually reload those files after they have been edited. To do so, enter the following command:<br />
<br />
$ openbox --reconfigure<br />
<br />
Where intending to add this command as a keybinnd to {{ic|~/.config/openbox/rc.xml}}, it will only be necessary to list the command as {{ic|reconfigure}}. An example has been provided below, using the {{ic|Super}}+{{ic|F11}} keybind:<br />
<br />
<keybind key="W-F11"><br />
<action name="Reconfigure"/><br />
</keybind><br />
<br />
== Keybinds ==<br />
<br />
All keybinds must be added to the {{ic|~/.config/openbox/rc.xml}} file, and below the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading. Although a brief overview has been provided here, a more in-depth explanation of keybindings can be found at [http://openbox.org/wiki/Help:Bindings openbox.org]. There is a utility 'obkey' in AUR for adjust key-binding. Before use obkey, you should use obconf to create {{ic|~/.config/openbox/rc.xml}}.<br />
<br />
=== Special keys ===<br />
<br />
While the use of standard alpha-numeric keys for keybindings is self-explanatory, special names are assigned to other types of keys, such as {{ic|modifers}}, {{ic|multimedia}} keys and {{ic|navigation}} keys.<br />
<br />
==== Modifiers ====<br />
<br />
{{ic|Modifer}} keys play an important role in keybindings (e.g. holding down the {{ic|shift}} or {{ic|CTRL / control}} key in combination with another key to undertake an action). Using modifers helps to prevent conflicting keybinds, whereby two or more actions are linked to the same key or combination of keys. The syntax to use a modifer with another key is:<br />
<br />
"<modifier>-<key>"<br />
<br />
The modifer codes are as follows:<br />
<br />
* {{ic|S}}: Shift<br />
* {{ic|C}}: Control / CTRL<br />
* {{ic|A}}: Alt<br />
* {{ic|W}}: Super / Windows<br />
* {{ic|M}}: Meta<br />
* {{ic|H}}: Hyper (If it is bound to something) <br />
<br />
For example, the code below would use {{ic|super}} and {{ic|t}} to launch {{Pkg|lxterminal}}<br />
<br />
<keybind key="W-t"><br />
<action name="Execute"><br />
<command>lxterminal</command><br />
</action><br />
</keybind><br />
<br />
==== Multimedia keys ====<br />
<br />
Where available, it is possible to set the appropriate {{ic|multimedia}} keys to perform their intended functions, such as to control the volume and/or the screen brightness. These will usually be integrated into the {{ic|function}} keys, and are identified by their appropriate symbols. See the [[Multimedia Keys]] article for further information.<br />
<br />
The volume and brightness multimedia codes are as follows (note that commands will still have to be assigned to them to actually function):<br />
<br />
* {{ic|XF86AudioRaiseVolume}}: Increase volume<br />
* {{ic|XF86AudioLowerVolume}}: Decrease volume<br />
* {{ic|XF86AudioMute}}: Mute / unmute volume<br />
* {{ic|XF86MonBrightnessUp}}: Increase screen brightess<br />
* {{ic|XF86MonBrightnessDown}}: Decrease screen brightness<br />
<br />
Examples of how these may be used in {{ic|~/.config/openbox/rc.xml}} have been provided below.<br />
<br />
==== Navigation keys ====<br />
<br />
These are the directional / arrow keys, usually used to move the cursor up, down, left, or right. The (self-explanatory) navigation codes are as follows:<br />
<br />
* {{ic|Up}}: Up<br />
* {{ic|Down}}: Down<br />
* {{ic|Left}}: Left<br />
* {{ic|Right}}: Right<br />
<br />
=== Volume Control ===<br />
<br />
What commands should be used for controlling the volume will depend on whether [[ALSA]], [[PulseAudio]], or [[OSS]] is used for sound.<br />
<br />
==== ALSA ====<br />
<br />
If [[ALSA]] is used for sound, the {{ic|amixer}} program can be used to adjust the volume, which is part of the {{Pkg|alsa-utils}} package. The following example - using the {{ic|multimedia}} keys intended to control the volume - will adjust the volume by +/- 5% (which may be changed, as desired):<br />
<br />
<keybind key="XF86AudioRaiseVolume"><br />
<action name="Execute"><br />
<command>amixer set Master 5%+ unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioLowerVolume"><br />
<action name="Execute"><br />
<command>amixer set Master 5%- unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioMute"><br />
<action name="Execute"><br />
<command>amixer set Master toggle</command><br />
</action><br />
</keybind><br />
<br />
==== Pulseaudio ====<br />
<br />
Where using [[PulseAudio]] with [[ALSA]] as a backend, the {{ic|amixer}} program commands will have to be modifed, as illustrated below in comparison to the ALSA example:<br />
<br />
<keybind key="XF86AudioRaiseVolume"><br />
<action name="Execute"><br />
<command>amixer -D pulse set Master 5%+ unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioLowerVolume"><br />
<action name="Execute"><br />
<command>amixer -D pulse set Master 5%- unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioMute"><br />
<action name="Execute"><br />
<command>amixer set Master toggle</command><br />
</action><br />
</keybind><br />
<br />
==== OSS ====<br />
<br />
{{Note|This option may be suitable for more experienced users.}}<br />
<br />
Where using [[OSS]], it is possible to create keybindings to raise or lower specific mixers. This allows, for example, the volume of a specific application (such as an audio player) to be changed without changing the overall system volume settings in turn. In this instance, the application must first have been [[OSS#Configuring_Applications_for_OSS|configured]] to use its own mixer. <br />
<br />
In the following example, [[MPD]] has been configured to use its own mixer - also named {{ic|mpd}} - to increase and decrease the volume by a single decibel at a time. The {{ic|--}} that appears after the {{ic|ossmix}} command has been added to prevent a negative value from being treated as an argument: <br />
<br />
<keybind key="[chosen keybind]"><br />
<action name="Execute"><br />
<command>ossmix -- mpd +1</command><br />
</action><br />
</keybind><br />
<keybind key="[chosen keybind]"><br />
<action name="Execute"><br />
<command>ossmix -- mpd -1</command><br />
</action><br />
</keybind><br />
<br />
=== Media player control ===<br />
<br />
The {{AUR|playerctl}} command-line utility can be used to bind multimedia keys to player actions. It should work with most media players.<br />
<br />
<keybind key="XF86AudioPlay"><br />
<action name="Execute"><br />
<command>playerctl play</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioPause"><br />
<action name="Execute"><br />
<command>playerctl pause</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioNext"><br />
<action name="Execute"><br />
<command>playerctl next</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioPrev"><br />
<action name="Execute"><br />
<command>playerctl previous</command><br />
</action><br />
</keybind><br />
<br />
=== Brightness control ===<br />
<br />
The {{ic|xbacklight}} program is used to control screen brightness, which is part of the [[Xorg]] X-Window system. In the example below, the {{ic|multimedia}} keys intended to control the screen brightness will adjust the settings by +/- 10%:<br />
<br />
<keybind key="XF86MonBrightnessUp"><br />
<action name="Execute"><br />
<command>xbacklight +10</command><br />
</action><br />
</keybind><br />
<keybind key="XF86MonBrightnessDown"><br />
<action name="Execute"><br />
<command>xbacklight -10</command><br />
</action><br />
</keybind><br />
<br />
=== Window snapping ===<br />
<br />
Many desktop environments and window managers support ''window snapping'' (e.g. Windows 7 Aero snap), whereby they will automatically snap into place when moved to the edge of the screen. This effect can also be simulated in Openbox through the use of keybinds on focused windows. <br />
<br />
As illustrated in the example below, percentages must be used to determine window sizes (see [http://openbox.org/wiki/Help:Actions openbox.org] for further information). In this instance, The {{ic|super}} key is used in conjunction with the {{ic|navigation}} keys:<br />
<br />
<keybind key="W-Left"><br />
<action name="UnmaximizeFull"/><br />
<action name="MaximizeVert"/><br />
<action name="MoveResizeTo"><br />
<width>50%</width><br />
</action><br />
<action name="MoveToEdge"><direction>west</direction></action><br />
</keybind><br />
<keybind key="W-Right"><br />
<action name="UnmaximizeFull"/><br />
<action name="MaximizeVert"/><br />
<action name="MoveResizeTo"><br />
<width>50%</width><br />
</action><br />
<action name="MoveToEdge"><direction>east</direction></action><br />
</keybind><br />
<br />
However, it should be noted that once a window has been 'snapped' to an edge, it will remain vertically maximised unless subsequently maximised and then restored. The solution is to implement additional keybinds - in this instance using the {{ic|down}} and {{ic|up}} keys - to do so. This will also make pulling 'snapped' windows from screen edges faster as well:<br />
<br />
<keybind key="W-Down"><br />
<action name="Unmaximize"/><br />
</keybind><br />
<keybind key="W-Up"><br />
<action name="Maximize"/><br />
</keybind><br />
<br />
This [http://ubuntuforums.org/showthread.php?t=1796793 Ubuntu forum thread] provides more information. Applications such as {{AUR|opensnap-git}} are also available from the AUR to automatically simulate window snapping behaviour without the use of keybinds.<br />
<br />
=== Desktop menu ===<br />
<br />
It is also possible to create a keybind to access the desktop menu. For example, the following code will bring up the menu by pressing {{ic|CTRL}} + {{ic|m}}:<br />
<br />
<keybind key="C-m"><br />
<action name="ShowMenu"><br />
<menu>root-menu</menu><br />
</action><br />
</keybind><br />
<br />
== Menus ==<br />
<br />
It is possible to employ three types of menu in Openbox: {{ic|static}}, {{ic|pipes}} (dynamic), and {{ic|generators}} (static or dynamic). They may also be used alone or in any combination.<br />
<br />
=== Static ===<br />
<br />
As the name would suggest, this default type of menu does not change in any way, and may be manually edited and/or (re)generated automatically through the use on an appropriate software package.<br />
<br />
Fast and efficient, while this type of menu can be used to select applications, it can also be useful to access specific functions and/or perform specific tasks (e.g. desktop configuration), leaving the access of applications to another process (e.g. the {{Pkg|synapse}} or {{Pkg|xfce4-appfinder}} applications).<br />
<br />
The {{ic|~/.config/openbox/menu.xml}} file will be the sole source of static desktop menu content.<br />
<br />
==== menumaker ====<br />
<br />
{{Warning|A root terminal '''must''' be installed in order to use MenuMaker, even though a standard user terminal may be used to run it. {{Pkg|xterm}} is a good choice.}}<br />
<br />
{{Pkg|menumaker}} automatically generates {{ic|xml}} menus for several window managers, including Openbox, [[Fluxbox]], [[IceWM]] and [[XFCE]]. It will search for all installed executable programs and consequently create a menu file for them. It is also possible to configure MenuMaker to exclude certain application types (e.g. relating to [[Gnome]] or [[KDE]]), if desired.<br />
<br />
Once installed and executed, it will automatically generate a new {{ic|~/.config/openbox/menu.xml}} file. To avoid overwriting an existing file, enter:<br />
<br />
$ mmaker -v OpenBox3<br />
<br />
Otherwise, to overwrite an existing file, add the {{ic|force}} argument ({{ic|f}}):<br />
<br />
$ mmaker -vf OpenBox3<br />
<br />
Once a new {{ic|~/.config/openbox/menu.xml}} file has been generated it may then be manually edited, or configured using a GUI menu editor, such as {{Pkg|obmenu}}.<br />
<br />
==== obmenu ====<br />
<br />
{{Warning|{{ic|obm-xdg}} - a pipe menu to generate a list of [[GTK+]] and [[Gnome]] applications - is also provided with obmenu. However, it has long-running bugs whereby it may produce an invalid output, or even not function at all. Consequently it has been omitted from discussion.}}<br />
<br />
{{Pkg|obmenu}} is a "user-friendly" GUI application to edit {{ic|~/.config/openbox/menu.xml}}, without the need to code in {{ic|xml}}.<br />
<br />
==== xdg-menu ====<br />
<br />
{{Pkg|archlinux-xdg-menu}} will automatically generate a menu based on {{ic|xdg}} files contained within the {{ic|/etc/xdg/}} directory for numerous Window Managers, including Openbox. Review the [[Xdg-menu#OpenBox]] article for further information.<br />
<br />
==== logout menu options ====<br />
<br />
{{Tip|The commands provided can also be attached to [[Openbox#Keybinds|keybinds]].}}<br />
<br />
The {{ic|~/.config/openbox/menu.xml}} file can be edited in order to provide a sub-menu with the same options as provided by [[Openbox#oblogout|oblogout]]. The sample script below will provide all of these options, with the exception of the ability to lock the screen:<br />
<br />
<menu id="exit-menu" label="Exit"><br />
<item label="Log Out"><br />
<action name="Execute"><br />
<command>openbox --exit</command><br />
</action><br />
</item><br />
<item label="Shutdown"><br />
<action name="Execute"><br />
<command>systemctl poweroff</command><br />
</action><br />
</item><br />
<item label="Restart"><br />
<action name="Execute"><br />
<command>systemctl reboot</command><br />
</action><br />
</item><br />
<item label="Suspend"><br />
<action name="Execute"><br />
<command>systemctl suspend</command><br />
</action><br />
</item><br />
<item label="Hibernate"><br />
<action name="Execute"><br />
<command>systemctl hibernate</command><br />
</action><br />
</item><br />
</menu><br />
<br />
Once the entries have been composed, add the following line to present the sub-menu where desired within the main desktop menu (usually as the last entry):<br />
<br />
<menu id="exit-menu"/><br />
<br />
=== Pipes ===<br />
<br />
{{Tip|It is entirely feasible for a static menu to contain one or more pipe sub-menus. The functionality of some pipe menus may also rely on the installation of relevant software packages.}}<br />
<br />
This type of menu is in essence a script that provides dynamic, refreshed lists on-the-fly as and when run. These lists may be used for multiple purposes, including to list applications, to provide information, and to provide control functions. Pre-configured pipe menus can be installed, although not from the [[official repositories]]. More experienced users can also modify and/or create their own custom scripts. Again, {{ic|~/.config/openbox/menu.xml}} may and commonly will contain several pipe menus.<br />
<br />
==== Examples ====<br />
<br />
* {{AUR|openbox-xdgmenu}}: fast xdg-menu converter to xml-pipe-menu<br />
* {{AUR|obfilebrowser}}: Application and file browser<br />
* {{AUR|obdevicemenu}}: Management of removable media with [[Udisks#Udisks|Udisks]]<br />
* [https://bbs.archlinux.org/viewtopic.php?pid=1345031 wifi pipe menu]: Wireless networking using [[Netctl]]<br />
<br />
[http://openbox.org/download-pipemenus.php Openbox.org] also provides a further list of pipe menus.<br />
<br />
=== Generators ===<br />
<br />
This type of menu is akin to those provided by the taskbars of desktop environments such as [[XFCE]] or [[LXDE]]. Automatically updating on-the-fly, this type of menu can be powerful and very convenient. It may also be possible to add custom categories and menu entries; read the documentation for your intended dynamic menu to determine if and how this can be done.<br />
<br />
A menu generator will have to be executed from the {{ic|~/.config/openbox/menu.xml}} file.<br />
<br />
==== obmenu-generator ====<br />
<br />
{{Tip|icons can still be disabled in {{AUR|obmenu-generator}}, even where enabled in {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
{{AUR|obmenu-generator}} is currently only available from the [[AUR]], although it is still highly recommended. With the ability to be used as a static or dynamic menu, it is highly configurable, powerful, and versatile. Menu categories and individual entries may also be easily hidden, customised, and/or added with ease. The [http://trizenx.blogspot.co.uk/2012/02/obmenu-generator.html official homepage] provides further information and screenshots.<br />
<br />
Below is an example of how obmenu-generator would be dynamically executed without icons in {{ic|~/.config/openbox/menu.xml}}:<br />
<br />
<?xml version="1.0" encoding="utf-8"?><br />
<openbox_menu><br />
<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator"><br />
</menu><br />
</openbox_menu><br />
<br />
To automatically iconify entries, the {{ic|-i}} option would be added:<br />
<br />
<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator -i"><br />
<br />
==== openbox-menu ====<br />
<br />
{{Tip|If this menu produces an error, it may be solved by enabling icons in {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
{{AUR|openbox-menu}} uses the [[LXDE]] [http://sourceforge.net/projects/lxde/files/menu-cache/ menu-cache] to create dynamic menus. The [http://mimasgpc.free.fr/openbox-menu_en.html official homepage] provides further information and screenshots.<br />
<br />
==== obmenugen ==== <br />
<br />
{{AUR|Obmenugen}} is currently only available from the [[AUR]], and can be used to a generate static or dynamic application menu based on {{ic|.desktop}} files. The [http://obmenugen.sourceforge.net/ official homepage] provides further information.<br />
<br />
=== Menu icons ===<br />
<br />
To show icons next to menu entries, it will be necessary to ensure they are enabled in the {{ic|<menu>}} section of the {{ic|~/.config/openbox/rc.xml}} file:<br />
<br />
<applicationIcons>yes</applicationIcons><br />
<br />
Where using a static menu, it will then be necessary to edit the {{ic|~/.config/openbox/menu.xml}} file to provide both the {{ic|icon <nowiki>=</nowiki>}} command, along with the full path and icon name for each entry. An example of the syntax used to provide an icon for a category is:<br />
<br />
<menu id="apps-menu" label="[label name]" icon="[pathway to icon]/[icon name]"><br />
<br />
=== Desktop menu as a panel menu ===<br />
<br />
{{Tip|XDoTool can simulate any keybind for any action, and as such, it may therefore be used for many other purposes...}}<br />
<br />
{{Pkg|xdotool}} is a package that can issue commands to simulate key presses / keybinds, meaning that it is possible to use it to invoke keybind-related actions without having to actually press their assigned keys. As this includes the ability to invoke an assigned keybind for the Openbox desktop menu, it is therefore possible to use XDoTool to turn the Openbox desktop menu into a panel menu. Especially where the desktop menu is heavily customised and feature-rich, this may prove very useful to:<br />
<br />
* Replace an existing panel menu<br />
* Implement a panel menu where otherwise not provided or possible (e.g. for {{AUR|tint2-svn}})<br />
* Compensate where losing access to the desktop menu due to the use of an application like [[Openbox#xfdesktop|xfdesktop]] to [[Openbox#Desktop_Icons_and_Wallpapers|manage the desktop]].<br />
<br />
Once XDoTool has been installed - if not already present - it will be necessary to create a keybind to access the root menu in {{ic|~/.config/openbox/rc.xml}}, and again below the {{ic|<nowiki><</nowiki>!-- Keybindings for running aplications --<nowiki>></nowiki>}} heading. For example, the following code will bring up the menu by pressing {{ic|CTRL}} + {{ic|m}}:<br />
<br />
<keybind key="C-m"><br />
<action name="ShowMenu"><br />
<menu>root-menu</menu><br />
</action><br />
</keybind><br />
<br />
Openbox must then be [[Openbox#Openbox_Reconfiguration|re-configured]]. In this instance, XDoTool will be used to simulate the {{ic|CTRL}} + {{ic|m}} keypress to access the desktop menu with the following command (note the use of {{ic|+}} in place of {{ic|-}}):<br />
<br />
xdotool key control+m<br />
<br />
How this command may be used as a panel launcher / icon is largely dependent on the features of panel used. While some panels will allow the above command to be executed directly in the process of creating a new launcher, others may require the use of an executable script. As an example, a custom executable script called {{ic|obpanelmenu.sh}} will be created in the {{ic|~/.config}} folder:<br />
<br />
$ ''text editor'' ~/.config/obpanelmenu.sh<br />
<br />
Once the empty file has been opened, the appropriate XDoTool command must be added to the empty file (i.e. to simulate the {{ic|CTRL}} + {{ic|m}} keypress for this example):<br />
<br />
xdotool key control+m<br />
<br />
After the file has been saved and closed, it may then be made into an executable script with the following command:<br />
<br />
$ chmod +x ~/.config/obpanelmenu.sh<br />
<br />
Executing it will bring up the Openbox desktop menu. Consequently, where using a panel that supports drag-and-drop functionality to add new launchers, simply drag the executable script onto it before changing the icon to suit personal taste. For instructions on how to use this executable script with {{AUR|tint2-svn}} - a derivative of the popular {{Pkg|tint2}} panel that allows launchers to be added - see [[Tint2#Application_Launchers_in_tint2-svn_.28AUR.29|Tint2-Svn launchers]].<br />
<br />
== GTK+ desktop theming ==<br />
<br />
{{Tip|It is '''strongly advised''' to install the {{Pkg|obconf}} and {{Pkg|lxappearance-obconf}} GUI applications to configure visual settings and theming. The latter is particularly important as it is responsible for generating the {{ic|~/.gtkrc-2.0}} file (see the [[Openbox#GTK+ 2|GTK fix]] section).}}<br />
<br />
It is important to note that a substantial range of both '''Openbox-specific''' and generalised, '''Openbox-compatible''' [[GTK]] themes are available to change the look of window decorations and the desktop menu. ''Generalised'' themes are designed to be simultaneously compatible with a range of popular desktop environments and/or window managers, commonly including Openbox. For example, {{AUR|gtk-theme-numix-blue}} supports both Openbox and [[XFCE]].<br />
<br />
=== Configuration ===<br />
<br />
{{Pkg|obconf}} and/or {{Pkg|lxappearance-obconf}} should be used to select and configure available GTK themes. See [[Uniform Look for Qt and GTK Applications]] for information about theming Qt based applications like [[Virtualbox]] or [[Skype]].<br />
<br />
=== Installation: official and AUR ===<br />
<br />
A good selection of {{Pkg|openbox-themes}} are available from the official repositories.<br />
<br />
Both Openbox-specific and Openbox-compatible themes installed from the [[Official_repositories|official repositories]] and/or the [[AUR]] will be automatically installed to the {{ic|/usr/share/themes}} directory. Both will also be immediately available for selection.<br />
<br />
=== Installation: other sources ===<br />
<br />
[http://www.box-look.org/index.php?xcontentmode=7402 box-look.org] is an excellent and well-established source of themes. [http://www.deviantart.com/ deviantART.com] is another excellent resource. Many more can be found through the utilisation of a search engine.<br />
<br />
==== Zip and tar files ====<br />
<br />
Themes downloaded from other sources such as [http://box-look.org/ box-look.org] will usually be compressed in a {{ic|.tar.gz}} or {{ic|.zip}} format. Although [[tar]] will have been installed as part of the base arch installation to extract {{ic|.tar.gz}} files, it will be necessary to install a program such as {{Pkg|unzip}} to extract {{ic|.zip}} files in the terminal. user-friendly GUI archivers are also available; see [[List of applications#Compression_tools]] for further information.<br />
<br />
Extracted theme files should also be placed in the {{ic|/usr/share/themes}} directory. For example, assuming downloaded content is automatically stored in the {{ic|~/Downloads}} folder, to simultaneously extract and move a {{ic|.tar.gz}} theme file, the syntax of the command would be:<br />
<br />
# tar xvf ~/Downloads/<theme file name>.tar.gz -C /usr/share/themes/<br />
<br />
To use {{Pkg|unzip}} in the same scenario for a {{ic|.zip}} theme file, the syntax of the command would be:<br />
<br />
# unzip ~/Downloads/<theme file name>.zip -d /usr/share/themes/<br />
<br />
Alternatively, it is also possible to simply move / copy and paste the extracted files to the {{ic|/usr/share/themes}} directory using an installed file manager as '''root'''.<br />
<br />
=== Troubleshooting ===<br />
<br />
There are two particular problems that may be encountered on rare occasions, especially where downloading themes from unsupported websites. These have been addressed below.<br />
<br />
==== Theme cannot be used ====<br />
<br />
If for any reason the newly extracted theme cannot be selected, open the theme directory to first ensure that it is indeed compatible with Openbox by determining that an {{ic|openbox-3}} directory is present, and that within this directory a {{ic|themerc}} file is also present. An {{ic|.obt}} ('''O'''pen'''B'''ox '''T'''heme) file may also be present in some instances, which can then be manually loaded in {{Pkg|obconf}}.<br />
<br />
Where expected files and directories are present and correct, then on occasion it is possible that the theme author has not correctly set permission to access the file (e.g. permission may still be for the account of the author, rather than for '''root'''). To eliminate this possibility, ensure the folder and file permissions are for '''root''':<br />
<br />
# chown -R root /user/share/themes<br />
<br />
==== Theme looks broken ====<br />
<br />
Of course, the first line of enquiry would be to check that it is not just a badly made, broken theme! Otherwise, ensure that the [[Openbox#GTK+ 2|Openbox GTK fix]] has been implemented, and then re-start the session. Unfortunately some older themes can simply break if not maintained sufficiently to keep pace with the changes incurred by [[GTK]] updates. To avoid such occurrences, it is best to check that desired themes have recently been created or at least updated / patched.<br />
<br />
=== Edit or create new themes ===<br />
<br />
{{Tip|Where deciding to modify an existing theme (e.g. the colour scheme), it would be best to work on a copy of it, rather than the original. This will retain the original should anything go wrong, and ensure that your changes are not over-written through an update.}}<br />
<br />
The process of creating new or modifying existing themes is covered extensively at the official [http://openbox.org/wiki/Help:Themes openbox.org] website. A user-friendly GUI to do so - {{AUR|obtheme}} - is also available from the [[AUR]].<br />
<br />
== Compositing effects ==<br />
<br />
Openbox does not natively provide support for compositing, and it will therefore be necessary to install a compositor for this purpose. The use of compositing enables various desktop visual effects, including transparency, fading, and shadows. Although compositing is not a necessary component, it can help to provide a more pleasant-looking environment, and avoid common issues such as screen distortion when [[Openbox#Oblogout|oblogout]] is used, and visual glitches when terminal window transparency has been enabled. Three of the most common choices are:<br />
<br />
* [[Compton]]: Powerful and reliable, with extensive options<br />
* [[Xcompmgr]]: Older and simpler version of compton<br />
* [[Cairo Compmgr]]: Advanced compositing effects, plugin support, and a user-friendly GUI. Also more buggy and far heavier use of system resources.<br />
<br />
== Mouse cursor and application icon themes ==<br />
<br />
Any mouse cursor and/or application icon theme may be used with Openbox. Numerous themes are available from both the [[official repositories]] and the [[AUR]].<br />
<br />
=== xcursor themes (mouse) === <br />
<br />
{{Tip|Review the [[Xcursor]] article for an in-depth explanation.}}<br />
<br />
Standard xcursor theme packages available from the official repositories include {{Pkg|xcursor-themes}}, {{Pkg|xcursor-bluecurve}}, {{Pkg|xcursor-vanilla-dmz}}, and {{Pkg|xcursor-pinux}}. To search the official repositories for all available xcursor themes, enter the following command:<br />
<br />
$ pacman -Ss xcursor<br />
<br />
Installed x-cursor themes may then be set though using the {{Pkg|obconf}} and {{Pkg|lxappearance-obconf}} GUI applications. It may then be necessary to either log out and back in again to implement the change, or to [[Openbox#Openbox_Reconfiguration|reconfigure Openbox]].<br />
<br />
=== Application icon themes ===<br />
<br />
Standard xcursor theme packages available from the official repositories include the {{Pkg|gnome-icon-theme}} and {{Pkg|lxde-icon-theme}}. A nice icon theme currently available from the AUR is {{AUR|numix-icon-theme-git}}. To search the official repositories for all available icon themes, enter the following command:<br />
<br />
$ pacman -Ss icon-theme<br />
<br />
Again, installed icon themes may then be set though using the {{Pkg|obconf}} and {{Pkg|lxappearance-obconf}} GUI applications. It may then be necessary to either log out and back in again to implement the change, or to [[Openbox#Openbox_Reconfiguration|reconfigure Openbox]].<br />
<br />
== Desktop icons and wallpapers ==<br />
<br />
Openbox does not natively support the use of desktop icons or wallpapers. As a consequence, it will be necessary to install additional applications for this purpose, where desired.<br />
<br />
=== Desktop management using file managers ===<br />
<br />
Some file managers have the capacity to fully '''manage the desktop''', meaning that they may be used to provide wallpapers and enable the use of icons on the desktop. The [[LXDE]] desktop environment itself uses PCManFM for this purpose.<br />
<br />
* [[PCManFM]]: See the [[PCManFM#Desktop_management|PCManFM desktop management]] article.<br />
* [[SpaceFM]]: See the [[SpaceFM#Desktop_management|SpaceFM desktop management]] article.<br />
<br />
=== Wallpaper / background programs ===<br />
<br />
{{Tip|The wallpaper programs listed here will have many more options than shown in this brief overview, including the ability to use solid colours for backgrounds. Review their documentation and man pages for more information.}}<br />
<br />
There are numerous packages available to set desktop backgrounds in Openbox, each of which will need to be autostarted in the {{ic|~/.config/openbox/autostart}} file. A few of the most well known have been listed.<br />
<br />
==== nitrogen ====<br />
<br />
{{Tip|If nitrogen does not show in the desktop menu, then it can be manually added.}}<br />
<br />
[[nitrogen]] is a user-friendly choice, as it also provides a GUI window to browse and set installed images. To access the GUI, enter the following command in a terminal:<br />
<br />
$ nitrogen<br />
<br />
To use nitrogen as the background provider, add the following command to the {{ic|~/.config/openbox/autostart}} file so that it will restore the last set wallpaper:<br />
<br />
nitrogen --restore &<br />
<br />
==== feh ====<br />
<br />
[[Feh]] is a popular image viewer that may also be used to set wallpapers. In this instance, it will be necessary to add the full directory path and name of the image to be used as the wallpaper. To use Feh as the background provider, add the following command to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
feh --bg-scale ''/path/to/image.file'' &<br />
<br />
==== hsetroot ====<br />
<br />
{{Pkg|hsetroot}} is a command-line tool specifically designed to set wallpapers. As with Feh, it will be necessary to add the full directory path and name of the image to be used as the wallpaper. To use HSetRoot as the background provider, add the following command to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
hsetroot -fill ''/path/to/image.file'' &<br />
<br />
==== xsetroot ====<br />
<br />
{{ic|xsetroot}} is installed as part of the [[Xorg]] X-Windows system, and may be used to set simple background colours. For example, to use XSetRoot to set a black background, the following would be added to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
xsetroot -solid "#000000" &<br />
<br />
=== Icon programs ===<br />
<br />
While there are programs dedicated to enabling desktop icons alone, it would seem that they have greater drawbacks than the utilisation of file managers for the task. These programs are discussed briefly, below.<br />
<br />
==== idesk ====<br />
<br />
[[idesk]] is a simple program that can enable icons in addition to managing wallpaper. It will be necessary to create an {{ic|~/.idesktop}} directory, and desktop icons must also be manually created. To use idesk to provide icons, add the following command to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
idesk &<br />
<br />
==== xfdesktop ====<br />
<br />
{{Pkg|xfdesktop}} is the desktop manager for [[XFCE]]. The [[Thunar]] file manager will also be downloaded as a dependency. Where this is used, the Openbox desktop menu will no longer be accessible by right-clicking the background. <br />
<br />
As such, it will consequently be necessary to access it by other means, such as by [[Openbox#Desktop_Menu|creating a keybind]], and/or by - where permitted - re-configuring an installed panel to use the [[Openbox#Desktop_menu_as_a_panel_menu|desktop menu as a panel menu]]. To use xfdesktop to provide icons, add the following command to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
xfdesktop &<br />
<br />
=== conky reconfiguration ===<br />
<br />
Particularly where using a file manager to manage the desktop, it will be necessary to edit {{ic|~/.conkyrc}} to change the {{ic|own_window_type}} command in order for [[conky]] to continue to be displayed (where used). The revised command that should be used is:<br />
<br />
own_window_type normal<br />
<br />
== File managers ==<br />
<br />
Multiple [[List of applications#File managers|file managers]] may be used with Openbox, including [[PCManFM]], [[SpaceFM]], [[Thunar]], {{Pkg|xfe}}, and {{Pkg|qtfm}}. Thunar is the native file manager for [[Xfce]], and if installing be aware that some Xfce-related dependencies will also be installed, including {{Pkg|exo}} (set default applications) and '''xfce4-about''' (provide information about the Xfce deskop environment). The menu entries for these may consequently have to be hidden.<br />
<br />
A file manager alone will not provide the same features and functionality as provided by default in full desktop environments like [[Xfce]] and [[KDE]]. For example, it may not be initially possible to view or access other partitions or access removable media. See [[File manager functionality]] for further information.<br />
<br />
== oblogout ==<br />
<br />
See the [[Oblogout]] article for an overview on how to use this useful, graphical logout script.<br />
<br />
== Openbox for multihead users ==<br />
<br />
While Openbox provides better than average multihead support on its own, the {{AUR|openbox-multihead-git}} package from the [[AUR]] provides a development branch called '''Openbox Multihead''' that gives multihead users per-monitor desktops. This model is not commonly found in floating window managers, but exists mainly in tiling window managers. It is explained well on the [http://xmonad.org/tour.html#workspace Xmonad web site]. Also, please see [https://github.com/BurntSushi/openbox-multihead/blob/multihead/README.MULTIHEAD README.MULTIHEAD] for a more comprehensive description of the new features and configuration options found in Openbox Multihead.<br />
<br />
Openbox Multihead will function like normal Openbox when only a single head is available.<br />
<br />
A downside to using Openbox Multihead is that it breaks the EWMH assumption that one and only one desktop is visible at any time. Thus, existing pagers will not work well with it. To remedy this, {{AUR|pager-multihead-git}} can be found in the [[AUR]] and is compatible with Openbox Multihead. [http://imgur.com/a/cnZeq#y04nk Screenshots].<br />
<br />
Finally, a new version of [[PyTyle]] that will work with Openbox Multihead can also be found in the [[AUR]]: {{AUR|pytyle3-git}}.<br />
<br />
Both ''pytyle3'' and ''pager-multihead-git'' will work without Openbox Multihead if only one monitor is active.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Packages for beginners ===<br />
<br />
{{Tip|See the [[List of applications]] article for many more possibilities.}}<br />
<br />
The packages listed below have been listed to aid newer users:<br />
<br />
* Display Manager: [[LXDM]] or [[LightDM]]<br />
* Audio: [[ALSA]]<br />
* Volume: {{Pkg|volumeicon}} or {{AUR|pnmixer}} with {{Pkg|gnome-alsamixer}}<br />
* Network: [[Network manager]] with {{Pkg|network-manager-applet}}<br />
* Panel: [[Tint2]] or [[Tint2#Application_Launchers_in_tint2-svn_.28AUR.29|Tint2-svn]]<br />
* Background: [[Nitrogen]] or [[Feh]]<br />
* Menu: [[Openbox#obmenu-generator|OBMenu-Generator]]<br />
* Compositor: [[Compton]]<br />
* Desktp Notifications: {{Pkg|xfce4-notifyd}}<br />
* Logout script: [[Oblogout]]<br />
* File Manager: [[PCManFM]], [[SpaceFM]], or [[Thunar]]<br />
* Clipboard Manager: {{Pkg|parcellite}}<br />
* Configuration GUIs: {{Pkg|obconf}}, {{Pkg|lxappearance-obconf}}, {{Pkg|lxrandr}}, {{Pkg|lxinput}}, {{AUR|tintwizard}} or {{AUR|tintwizard-svn}}<br />
<br />
=== Set default applications / file associations ===<br />
<br />
See the [[Default applications]] article.<br />
<br />
=== Terminal content copy and paste ===<br />
<br />
Within a terminal, either:<br />
<br />
* {{ic|Ctrl+Ins}} will copy and {{ic|Shift+Ins}} will paste. <br />
* {{ic|Ctrl+Shift+c}} will copy and '''mouse middle-click''' will paste.<br />
<br />
=== Ad-hoc window transparency ===<br />
<br />
{{Warning|This may not work where other actions are defined within the action group.}}<br />
The program {{Pkg|transset-df}} is available in the official repositories, and can enable window transparency on-the-fly.<br />
<br />
For example, using the following code in the {{ic|<mouse>}} section of the {{ic|~/.config/openbox/rc.xml}} file will enable control of application window transparency by hovering the mouse-pointer over the title bar and scrolling with the middle button:<br />
<br />
<context name="Titlebar"><br />
...<br />
<mousebind button="Up" action="Click"><br />
<action name= "Execute" ><br />
<execute>transset-df -p .2 --inc </execute><br />
</action><br />
</mousebind><br />
<mousebind button="Down" action="Click"><br />
<action name= "Execute" ><br />
<execute>transset-df -p .2 --dec </execute><br />
</action><br />
</mousebind><br />
...<br />
</context><br />
<br />
=== Using obxprop for faster configuration ===<br />
<br />
{{Pkg|openbox}} package provides a {{ic|obxprop}} binary that can parse relevant values for applications settings in {{ic|rc.xml}}. Officially {{ic|<nowiki>obxprop | grep "^_OB_APP"</nowiki>}} is recommended for this task. Doing so for multiple applications and its windows can be very inefficient however. The following script {{ic|obxprop2obrc}} makes it much easier to configure even a large number of applications.<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
##Script: obxprop-to-openbox-rc.sh<br />
##Recommended executable name: obxprop2obrc<br />
<br />
while [ $# -ne 0 ]; do<br />
case $1 in<br />
-f*)<br />
shift;<br />
FILE="$1";<br />
shift;<br />
;;<br />
-t*)<br />
shift;<br />
TIME="$1";<br />
shift;<br />
;;<br />
*)<br />
echo Usage: $0 [-f FILE_TEMPLATE] [-t WAIT_TO_KILL_TIME] <br />
exit 1;<br />
;;<br />
esac<br />
done<br />
<br />
if [ $TIME ]; then<br />
OBXPROPS=( $(obxprop | cat & (sleep $TIME && pkill -13 cat) | awk -F \" '/_OB_APP/{ print "\x22"$2"\x22" }' ) );<br />
else<br />
OBXPROPS=( $(obxprop | awk -F \" '/_OB_APP/{ print "\x22"$2"\x22" }' ) );<br />
fi<br />
OBPROPS=(TYPE TITLE GROUP_CLASS GROUP_NAME CLASS NAME ROLE);<br />
j=0;<br />
for i in $( seq 2 2 14 ); do<br />
OBPROP="$( echo ${OBXPROPS[@]} | awk -F \" '{ print $'$i'}' )";<br />
if [[ -z $OBPROP ]]; then <br />
declare ${OBPROPS[$j]}='"*"';<br />
else <br />
declare ${OBPROPS[$j]}="\"$OBPROP\"";<br />
fi<br />
j=$(($j+1));<br />
done;<br />
<br />
echo " <application type="$TYPE" title="$TITLE" class="$CLASS" name="$NAME" role="$ROLE">"<br />
if [ -f "$FILE" ]; then cat "$FILE" && exit; fi<br />
cat << EOF<br />
<desktop>1</desktop><br />
<desktop>all</desktop><br />
<decor>yes</decor><br />
<decor>no</decor><br />
<focus>yes</focus><br />
<focus>no</focus><br />
<fullscreen>yes</fullscreen><br />
<fullscreen>no</fullscreen><br />
<iconic>yes</iconic><br />
<iconic>no</iconic><br />
<maximized>yes</maximized><br />
<maximized>no</maximized><br />
<maximized>both</maximized><br />
<maximized>horizontal</maximized><br />
<maximized>vertical</maximized><br />
<monitor>0</monitor><br />
<monitor>1</monitor><br />
<position force="no"><br />
<position force="yes"><br />
<width>40%</width><br />
<height>30%</height><br />
<x>-1</x><br />
<y>-1</y><br />
<x>center</x><br />
<y>center</y><br />
</position><br />
<layer>above</layer><br />
<layer>normal</layer><br />
<layer>below</layer><br />
<shade>yes</shade><br />
<shade>no</shade><br />
<skip_pager>yes</skip_pager><br />
<skip_pager>no</skip_pager><br />
<skip_taskbar>yes</skip_taskbar><br />
<skip_taskbar>no</skip_taskbar><br />
</application><br />
EOF<br />
</nowiki>}}<br />
<br />
If no further options are used default configuration, that can be edited by deleting unnecessary lines, is printed out. This script can use templates with default values when using {{ic|-f}} switch:<br />
{{hc|<br />
$ obxprop2obrc -f templates-rc-inkscape-dialogs.sc > part-rc-applications-inkscape.xml<br />
$ cat part-rc-applications-inkscape.xml|<nowiki><br />
<application type="normal" title="Align and Distribute (Shift+Ctrl+A)" class="Inkscape" name="inkscape" role="*"><br />
<desktop>3</desktop><br />
<decor>yes</decor><br />
<maximized>no</maximized><br />
<position force="yes"><br />
<width>20%</width><br />
<height>30%</height><br />
<x>-1</x><br />
<y>-1</y><br />
</position><br />
<layer>normal</layer><br />
<shade>yes</shade><br />
</application><br />
</nowiki>}}<br />
<br />
It also has a time switch {{ic|-t}} which kills obxprop and thus can reduce time significantly in certain situations, although it may not work perfectly.<br />
<br />
=== Xprop values for applications ===<br />
<br />
{{Pkg|xorg-xprop}} is available in the official repositories, and can be used to relay property values for selected applications. Where frequently using per-application settings, the following [[Bash#Aliases|Bash Alias]] may be useful:<br />
dy:<br />
<br />
alias xp='xprop | grep "WM_WINDOW_ROLE\|WM_CLASS" && echo "WM_CLASS(STRING) = \"NAME\", \"CLASS\""'<br />
<br />
To use Xorg-XProp, run using the alias given {{ic|xp}}, and click on the active program desired to define with per-application settins. The results displayed will only be the information that Openbox itself requires, namely the {{ic|WM_WINDOW_ROLE}} and {{ic|WM_CLASS}} (name and class) values:<br />
<br />
WM_WINDOW_ROLE(STRING) = "roster"<br />
WM_CLASS(STRING) = "gajim.py", "Gajim.py"<br />
WM_CLASS(STRING) = "NAME", "CLASS"<br />
<br />
==== Firefox ====<br />
<br />
For whatever reason, Firefox and like-minded equivalents ignore application rules (e.g. ''<desktop>'') unless {{ic|class&#61;"Firefox*"}} is used. This applies irrespective of whatever values '''xprop''' may report for the program's {{ic|WM_CLASS}}.<br />
<br />
=== Switching between keyboard layouts ===<br />
<br />
See the article section [[Keyboard configuration in Xorg#Switching between keyboard layouts|switching between keyboard layouts]] for instructions.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Windows load behind the active window ===<br />
<br />
Some application windows (such as Firefox windows) may load behind the currently active window, causing you to need to switch to the window you just created to focus it. To fix this behavior add this to your {{ic|~/.config/openbox/rc.xml}} file, inbetween the {{ic|1=<openbox_config>}} and {{ic|1=</openbox_config>}} tags:<br />
<br />
{{bc|1=<br />
<applications><br />
<application class="*"><br />
<focus>yes</focus><br />
</application><br />
</applications><br />
}}<br />
<br />
== See also ==<br />
<br />
* [http://openbox.org/ Openbox Website] - Official website<br />
* [http://planetob.openmonkey.com/ Planet Openbox] - Openbox news portal<br />
* [http://www.box-look.org/ Box-Look.org] - A good resource for themes and related artwork<br />
* [https://bbs.archlinux.org/viewtopic.php?id=93126 Openbox Hacks and Configs Thread] @ Arch Linux Forums<br />
* [https://bbs.archlinux.org/viewtopic.php?id=45692 Openbox Screenshots Thread] @ Arch Linux Forums<br />
* [http://urukrama.wordpress.com/openbox-guide/ An Openbox guide]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Openbox&diff=316226Openbox2014-05-22T16:21:26Z<p>Bluerider: /* D-Bus */ Add dbus launching without login manager</p>
<hr />
<div>[[Category:Stacking WMs]]<br />
[[cs:Openbox]]<br />
[[de:Openbox]]<br />
[[es:Openbox]]<br />
[[fr:Openbox]]<br />
[[it:Openbox]]<br />
[[ja:Openbox]]<br />
[[ko:Openbox]]<br />
[[lt:Openbox]]<br />
[[nl:Openbox]]<br />
[[pl:Openbox]]<br />
[[ru:Openbox]]<br />
[[sk:Openbox]]<br />
[[sr:Openbox]]<br />
[[tr:Openbox]]<br />
[[zh-CN:Openbox]]<br />
[[zh-TW:Openbox]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Window manager}}<br />
{{Related|Oblogout}}<br />
{{Related articles end}}<br />
<br />
Openbox is a lightweight, powerful, and highly configurable ''stacking'' [[Window manager|window manager]] with extensive standards support. It may be built upon and run independently as the basis of a unique [[desktop environment]], or within other integrated desktop environments such as [[KDE]] and [[Xfce]], as an alternative to the window managers they provide. The [[LXDE]] desktop environment is itself built around Openbox.<br />
<br />
A comprehensive list of features are documented at the [http://openbox.org/ official Openbox website]. This article pertains to specifically installing Openbox under Arch Linux.<br />
<br />
== Installation ==<br />
<br />
Install {{Pkg|openbox}}, available in the [[official repositories]].<br />
<br />
== Openbox Sessions ==<br />
<br />
Again, Openbox may be run independently as a standalone window manager, or within other integrated desktop environments such as [[KDE]] and [[XFCE]] as an alternative to the window managers they provide.<br />
<br />
=== Standalone ===<br />
<br />
Many popular [[Display manager|display managers]] such as [[LXDM]], [[SLiM]], and [[LightDM]] will automatically detect Openbox, allowing for it to be run as a standalone session.<br />
<br />
However, it may be necessary to manually specify the command to start an openbox session where intending to set it as a default session for [[SLiM]], or where not using a display manager at all (e.g. logging in at the command line, followed by the command {{ic|startx}}). In either instance, it will be necessary to modify the [[Xinitrc]] file in order to add the following command:<br />
<br />
exec openbox-session<br />
<br />
=== Within other desktop environments ===<br />
<br />
When replacing the native window manager of a desktop environment with Openbox, any desktop compositing effects - such a transparency - provided by that native window manager will be lost. This is because Openbox itself does not provide any compositing functionality. However, it is easily possible to use a separate compositing program to [[Openbox#Compositing effects|re-enable compositing]]. <br />
<br />
==== GNOME ====<br />
<br />
Openbox does not seem to work with [[GNOME|GNOME 3]]. The {{ic|Gnome-Shell}} touch-style interface requires both its native window manager and its native gtk-window-decorator packages to function. Furthermore, attempting to run Openbox within the {{ic|Classic-Gnome-Shell}} interface results in the loss of the {{ic|gnome-panel}}. Ceasing Openbox and attempting to restore the native window manager will result in crashing the desktop. Gnome 3 is tightly integrated, and is therefore deliberately designed not to be modular in nature (i.e. allowing components to be changed).<br />
<br />
==== KDE ====<br />
See the [[KDE#Using Openbox in KDE|using Openbox in KDE]] section of the main [[KDE]] article.<br />
<br />
==== Xfce ====<br />
<br />
See the [[Xfce#Replacing_the_native_window_manager|replacing the native window manager]] section of the main [[Xfce]] article.<br />
<br />
== System configuration==<br />
<br />
Those installing Openbox - particularly as a stand-alone Window Manager - will have noticed that several elements may fail to work properly, or even work at all. Examples of the common problems encountered are:<br />
<br />
* '''File Managers''': Other partitions are not displayed or accessible. The trash function - where provided - does not work <br />
* '''Authentication''': Passwords are not stored / remembered during sessions<br />
* '''Secure Shell (SSH)''': SSH agent will not start<br />
* '''Wireless Connection''': Instant failure when attempting to connect to wifi (related to authentication) <br />
* '''Themes''': Application windows are mismatched or haphazard-looking<br />
* '''Folders''': Expected folders such as {{ic|Documents}}, {{ic|Downloads}} and so forth are missing from the {{ic|Home}} folder<br />
* '''System Tray''': Installed packages fail to autostart or can be seen running twice<br />
<br />
Most of these problems are actually the result of [[Dbus]] and [[GTK]] issues, both of which can be fixed simultaneously by editing the [[xprofile|~/.xprofile]] file - or if using [[SLiM]] as a [[display manager]] instead - by editing the [[xinitrc|~/.xinitrc]] file. It will also be necessary to install some key packages to ensure full functionality.<br />
<br />
=== D-Bus ===<br />
<br />
File manager, authentication, SSH agent, and WiFi-connection problems will likely be due to that [[D-Bus]] is not functioning correctly. Most [[display manager]]s such as [[GDM]], [[KDM]], [[LightDM]] and [[LXDM]] will handle this for you.<br />
<br />
When using [[xinit]] or certain other DMs (such as [[XDM]] and [[SLiM]]), make sure {{ic|~/.xinitrc}} is based on {{ic|/etc/skel/.xinitrc}} (so that it sources {{ic|/etc/X11/xinit/xinitrc.d/}}, see [[xinitrc]] for more information).<br />
<br />
To launch dbus + openbox with {{ic|startx}}, append {{ic| exec dbus-launch --sh-syntax --exit-with-session openbox-session}} to {{ic|~/.xinitrc}}.<br />
<br />
=== GTK+ 2 ===<br />
<br />
Problems with the theme and look will likely be due to the absence of the appropriate command to ensure that a uniform look must be applied to applications that use GTK 2. Again, edit {{ic|~/.xinitrc}} and/or {{ic|~/.xprofile}} with the following command:<br />
<br />
export GTK2_RC_FILES="$HOME/.gtkrc-2.0" <br />
<br />
The {{ic|~/.gtkrc-2.0}} file will be automatically generated where using [[LXDE|lxappearance]] to set themes.<br />
<br />
It will also be necessary to install {{Pkg|libgnomeui}} to ensure that [[Qt]] is also able to find GTK themes.<br />
<br />
See [[GTK+#GTK+ 2.x]] for an introduction to manually editing {{ic|~/.gtkrc-2.0}}.<br />
<br />
=== XDG ===<br />
<br />
In addition to sourcing the '''local''' {{ic|~/.config/openbox/autostart}} file to autostart applications, Openbox will also source {{ic|.desktop}} files automatically installed by some packages in the '''global''' {{ic|/etc/xdg/autostart}} directory. The package responsible for allowing Openbox to additionally source the {{ic|/etc/xdg/autostart}} directory is {{Pkg|python2-xdg}}. <br />
<br />
For example, where initially autostarting a package such as the [[NetworkManager|Network Manager]] applet ('''nm-applet''') locally, should {{Pkg|python2-xdg}} be installed at a later time - either explicitly or as a dependency for another package - its global XDG {{ic|.desktop}} file will then also be sourced as a consequence, resulting in seeing two icons running in the system tray. It is therefore recommended to install {{Pkg|python2-xdg}} explicitly, as this will ensure that applications that should automatically autostart when installed will do so.<br />
<br />
=== Home folders ===<br />
<br />
{{Tip|This fix will be especially helpful for those who wish to use a file manager to manage their desktop, as it will automatically create a special {{ic|~/Desktop}} directory, which will house all files and application shortcuts stored on the desktop itself.}}<br />
<br />
Where expected {{ic|Home}} folders such as {{ic|Downloads}}, {{ic|Documents}}, etc., are not present, then please review the [[Xdg user directories]] article.<br />
<br />
=== Authentication and passwords ===<br />
<br />
For authentication (e.g. WiFi passwords, etc.), it will be necessary to install the appropriate packages. They are:<br />
<br />
* {{Pkg|polkit}}: Application development toolkit for controlling system-wide privileges; see [[polkit]]<br />
* {{Pkg|lxpolkit}}: Simple policykit authentication agent for LXDE ({{Pkg|polkit-gnome}} currently does not work properly)<br />
* {{Pkg|gnome-keyring}}: store / remember passwords; see [[GNOME Keyring]]<br />
<br />
== Configuration ==<br />
<br />
{{Warning|Edit these files as the user you will be using Openbox with. Not as root!}}<br />
{{Tip|Local configuration files will always override global equivalents. These files may also be manually edited by any appropriate text editor, such as Leafpad or Geany; there is no need to use [[sudo]] or '''gksu''' commands to edit them.}}<br />
<br />
Four key files form the basis of the openbox configuration, each serving a unique role. They are: {{ic|rc.xml}}, {{ic|menu.xml}}, {{ic|autostart}}, and {{ic|environment}}. Although these files are discussed in more detail below, to start configuring Openbox, it will first be necessary to create a '''local''' Openbox profile (i.e for your specific user account) based on them. This can be done by copying them from the '''global''' {{ic|/etc/xdg/openbox}} profile (applicable to any and all users) as a template:<br />
<br />
$ mkdir -p ~/.config/openbox<br />
$ cp -R /etc/xdg/openbox/* ~/.config/openbox<br />
<br />
=== rc.xml ===<br />
<br />
{{Tip|Custom keyboard shortcuts (keybindings) must be added to the {{ic|<keyboard>}} section of this file, and underneath the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading.}}<br />
<br />
{{ic|~/.config/openbox/rc.xml}} is the main configuration file, responsible for determining the behaviour and settings of the overall session, including:<br />
<br />
* Keyboard shortcuts (e.g. starting applications; controlling the volume)<br />
* Theming<br />
* Desktop and Virtual desktop settings, and<br />
* Application Window settings<br />
<br />
This file is also pre-configured, meaning that it will only be necessary to amend existing content in order to customise behaviour to suit personal preference.<br />
<br />
=== menu.xml ===<br />
<br />
{{ic|~/.config/openbox/menu.xml}} defines the type and behaviour of the desktop menu, accessable by right-clicking the background. Although the default provided is a '''static menu''' (meaning that it will not automatically update when new applications are installed), it is possible to employ the use of '''dynamic menus''' that will automatically update as well. <br />
<br />
The available options are discussed extensively below in the [[Openbox#Menus|Menus]] section.<br />
<br />
=== autostart ===<br />
<br />
{{Tip|Be aware that some applications will automatically start via {{ic|.desktop}} files installed in the {{ic|/etc/xdg/autostart/}} or {{ic|~/.config/autostart/}} directories.}}<br />
<br />
{{ic|~/.config/openbox/autostart}} determines which applications are to be launched upon beginning the Openbox session. These may include:<br />
<br />
* Panels and/or docks<br />
* Compositors<br />
* Background providers<br />
* Screensavers<br />
* Applications to autoload or autostart (e.g. [[Conky]])<br />
* [[Daemon]] processes (e.g. File Managers for automounting and other functions)<br />
* Other appropriate commands (e.g. disable [[DPMS]])<br />
<br />
==== Listing commands ====<br />
<br />
There are two very important points to note when adding commands to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
* Each and every command '''must''' be terminated with an ampersand ({{ic|&}}). Where a command does not end with an ampersand, then no further commands listed below it will be executed.<br />
* It is strongly recommended to add delays to the execution of some or all commands in the autostart file, even if only by a single second. The consequence of not doing so is that all commands will be executed simultaneously, potentially resulting in the mis- or non-starting of items. The syntax of the command to delay the execution of commands (in seconds) is:<br />
<br />
(sleep <number of seconds>s && <command>) &<br />
<br />
For example, to delay the execution of [[Conky]] by 3 seconds, the command would be (and note the termination of it with an ampersand):<br />
<br />
(sleep 3s && conky) &<br />
<br />
Here is a more complete example of a possible {{ic|~/.config/openbox/autostart}} file:<br />
<br />
## Autostart File ##<br />
<br />
##Disable DPMS<br />
xset -dpms; xset s off &<br />
<br />
##Compositor<br />
compton -CGb &<br />
<br />
##Background<br />
(sleep 1s && nitrogen --restore) &<br />
<br />
##tint2 panel<br />
(sleep 1s && tint2) &<br />
<br />
##Sound Icon<br />
(sleep 1s && volumeicon) &<br />
<br />
##Screensaver<br />
(sleep 1s && xscreensaver -no-splash) &<br />
<br />
##Conky<br />
(sleep 3s && conky) &<br />
<br />
##Disable touchpad<br />
/usr/bin/synclient TouchpadOff=1 &<br />
<br />
=== environment ===<br />
<br />
{{Note|This is the least important file, and many users may not need to edit it at all.}}<br />
<br />
{{ic|~/.config/openbox/environment}} can be used to export and set relevant environmental variables such as to:<br />
<br />
* Define new pathways (e.g. execute commands that would otherwise require the entire pathway to be listed with them)<br />
* Change language settings, and<br />
* Define other variables to be used (e.g. the fix for GTK theming could be listed here)<br />
<br />
=== Optional GUI configuration packages ===<br />
<br />
Several GUIs are available to quickly and easily configure your Openbox desktop. From the official repositories these include:<br />
<br />
* {{Pkg|obconf}}: Basic Openbox configuration manager<br />
* {{Pkg|lxappearance-obconf}}: LXDE configuration manager (provides additional options)<br />
* {{Pkg|lxinput}}: LXDE keyboard and mouse configuration<br />
* {{Pkg|lxrandr}}: LXDE monitor configuration<br />
<br />
Others, such as {{AUR|obkey}} (configure keyboard shortcuts via the {{ic|rc.xml}} file) and {{AUR|ob-autostart}} (configure the Openbox {{ic|autostart}} file) are available from the [[AUR]]. Programs and applications relating to the configuration of Openbox's desktop menu are discussed in the [[Openbox#Menus|Menus]] section.<br />
<br />
== Openbox reconfiguration ==<br />
<br />
{{Tip|where not already present, it would be worthwhile adding this command to a menu and/or as a keybind for convenience.}}<br />
<br />
Openbox will not always automatically reflect any changes made to its configuration files within a session. As a consequence, it will be necessary to manually reload those files after they have been edited. To do so, enter the following command:<br />
<br />
$ openbox --reconfigure<br />
<br />
Where intending to add this command as a keybinnd to {{ic|~/.config/openbox/rc.xml}}, it will only be necessary to list the command as {{ic|reconfigure}}. An example has been provided below, using the {{ic|Super}}+{{ic|F11}} keybind:<br />
<br />
<keybind key="W-F11"><br />
<action name="Reconfigure"/><br />
</keybind><br />
<br />
== Keybinds ==<br />
<br />
All keybinds must be added to the {{ic|~/.config/openbox/rc.xml}} file, and below the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading. Although a brief overview has been provided here, a more in-depth explanation of keybindings can be found at [http://openbox.org/wiki/Help:Bindings openbox.org]. There is a utility 'obkey' in AUR for adjust key-binding. Before use obkey, you should use obconf to create {{ic|~/.config/openbox/rc.xml}}.<br />
<br />
=== Special keys ===<br />
<br />
While the use of standard alpha-numeric keys for keybindings is self-explanatory, special names are assigned to other types of keys, such as {{ic|modifers}}, {{ic|multimedia}} keys and {{ic|navigation}} keys.<br />
<br />
==== Modifiers ====<br />
<br />
{{ic|Modifer}} keys play an important role in keybindings (e.g. holding down the {{ic|shift}} or {{ic|CTRL / control}} key in combination with another key to undertake an action). Using modifers helps to prevent conflicting keybinds, whereby two or more actions are linked to the same key or combination of keys. The syntax to use a modifer with another key is:<br />
<br />
"<modifier>-<key>"<br />
<br />
The modifer codes are as follows:<br />
<br />
* {{ic|S}}: Shift<br />
* {{ic|C}}: Control / CTRL<br />
* {{ic|A}}: Alt<br />
* {{ic|W}}: Super / Windows<br />
* {{ic|M}}: Meta<br />
* {{ic|H}}: Hyper (If it is bound to something) <br />
<br />
For example, the code below would use {{ic|super}} and {{ic|t}} to launch {{Pkg|lxterminal}}<br />
<br />
<keybind key="W-t"><br />
<action name="Execute"><br />
<command>lxterminal</command><br />
</action><br />
</keybind><br />
<br />
==== Multimedia keys ====<br />
<br />
Where available, it is possible to set the appropriate {{ic|multimedia}} keys to perform their intended functions, such as to control the volume and/or the screen brightness. These will usually be integrated into the {{ic|function}} keys, and are identified by their appropriate symbols. See the [[Multimedia Keys]] article for further information.<br />
<br />
The volume and brightness multimedia codes are as follows (note that commands will still have to be assigned to them to actually function):<br />
<br />
* {{ic|XF86AudioRaiseVolume}}: Increase volume<br />
* {{ic|XF86AudioLowerVolume}}: Decrease volume<br />
* {{ic|XF86AudioMute}}: Mute / unmute volume<br />
* {{ic|XF86MonBrightnessUp}}: Increase screen brightess<br />
* {{ic|XF86MonBrightnessDown}}: Decrease screen brightness<br />
<br />
Examples of how these may be used in {{ic|~/.config/openbox/rc.xml}} have been provided below.<br />
<br />
==== Navigation keys ====<br />
<br />
These are the directional / arrow keys, usually used to move the cursor up, down, left, or right. The (self-explanatory) navigation codes are as follows:<br />
<br />
* {{ic|Up}}: Up<br />
* {{ic|Down}}: Down<br />
* {{ic|Left}}: Left<br />
* {{ic|Right}}: Right<br />
<br />
=== Volume Control ===<br />
<br />
What commands should be used for controlling the volume will depend on whether [[ALSA]], [[PulseAudio]], or [[OSS]] is used for sound.<br />
<br />
==== ALSA ====<br />
<br />
If [[ALSA]] is used for sound, the {{ic|amixer}} program can be used to adjust the volume, which is part of the {{Pkg|alsa-utils}} package. The following example - using the {{ic|multimedia}} keys intended to control the volume - will adjust the volume by +/- 5% (which may be changed, as desired):<br />
<br />
<keybind key="XF86AudioRaiseVolume"><br />
<action name="Execute"><br />
<command>amixer set Master 5%+ unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioLowerVolume"><br />
<action name="Execute"><br />
<command>amixer set Master 5%- unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioMute"><br />
<action name="Execute"><br />
<command>amixer set Master toggle</command><br />
</action><br />
</keybind><br />
<br />
==== Pulseaudio ====<br />
<br />
Where using [[PulseAudio]] with [[ALSA]] as a backend, the {{ic|amixer}} program commands will have to be modifed, as illustrated below in comparison to the ALSA example:<br />
<br />
<keybind key="XF86AudioRaiseVolume"><br />
<action name="Execute"><br />
<command>amixer -D pulse set Master 5%+ unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioLowerVolume"><br />
<action name="Execute"><br />
<command>amixer -D pulse set Master 5%- unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioMute"><br />
<action name="Execute"><br />
<command>amixer set Master toggle</command><br />
</action><br />
</keybind><br />
<br />
==== OSS ====<br />
<br />
{{Note|This option may be suitable for more experienced users.}}<br />
<br />
Where using [[OSS]], it is possible to create keybindings to raise or lower specific mixers. This allows, for example, the volume of a specific application (such as an audio player) to be changed without changing the overall system volume settings in turn. In this instance, the application must first have been [[OSS#Configuring_Applications_for_OSS|configured]] to use its own mixer. <br />
<br />
In the following example, [[MPD]] has been configured to use its own mixer - also named {{ic|mpd}} - to increase and decrease the volume by a single decibel at a time. The {{ic|--}} that appears after the {{ic|ossmix}} command has been added to prevent a negative value from being treated as an argument: <br />
<br />
<keybind key="[chosen keybind]"><br />
<action name="Execute"><br />
<command>ossmix -- mpd +1</command><br />
</action><br />
</keybind><br />
<keybind key="[chosen keybind]"><br />
<action name="Execute"><br />
<command>ossmix -- mpd -1</command><br />
</action><br />
</keybind><br />
<br />
=== Media player control ===<br />
<br />
The {{AUR|playerctl}} command-line utility can be used to bind multimedia keys to player actions. It should work with most media players.<br />
<br />
<keybind key="XF86AudioPlay"><br />
<action name="Execute"><br />
<command>playerctl play</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioPause"><br />
<action name="Execute"><br />
<command>playerctl pause</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioNext"><br />
<action name="Execute"><br />
<command>playerctl next</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioPrev"><br />
<action name="Execute"><br />
<command>playerctl previous</command><br />
</action><br />
</keybind><br />
<br />
=== Brightness control ===<br />
<br />
The {{ic|xbacklight}} program is used to control screen brightness, which is part of the [[Xorg]] X-Window system. In the example below, the {{ic|multimedia}} keys intended to control the screen brightness will adjust the settings by +/- 10%:<br />
<br />
<keybind key="XF86MonBrightnessUp"><br />
<action name="Execute"><br />
<command>xbacklight +10</command><br />
</action><br />
</keybind><br />
<keybind key="XF86MonBrightnessDown"><br />
<action name="Execute"><br />
<command>xbacklight -10</command><br />
</action><br />
</keybind><br />
<br />
=== Window snapping ===<br />
<br />
Many desktop environments and window managers support ''window snapping'' (e.g. Windows 7 Aero snap), whereby they will automatically snap into place when moved to the edge of the screen. This effect can also be simulated in Openbox through the use of keybinds on focused windows. <br />
<br />
As illustrated in the example below, percentages must be used to determine window sizes (see [http://openbox.org/wiki/Help:Actions openbox.org] for further information). In this instance, The {{ic|super}} key is used in conjunction with the {{ic|navigation}} keys:<br />
<br />
<keybind key="W-Left"><br />
<action name="UnmaximizeFull"/><br />
<action name="MaximizeVert"/><br />
<action name="MoveResizeTo"><br />
<width>50%</width><br />
</action><br />
<action name="MoveToEdge"><direction>west</direction></action><br />
</keybind><br />
<keybind key="W-Right"><br />
<action name="UnmaximizeFull"/><br />
<action name="MaximizeVert"/><br />
<action name="MoveResizeTo"><br />
<width>50%</width><br />
</action><br />
<action name="MoveToEdge"><direction>east</direction></action><br />
</keybind><br />
<br />
However, it should be noted that once a window has been 'snapped' to an edge, it will remain vertically maximised unless subsequently maximised and then restored. The solution is to implement additional keybinds - in this instance using the {{ic|down}} and {{ic|up}} keys - to do so. This will also make pulling 'snapped' windows from screen edges faster as well:<br />
<br />
<keybind key="W-Down"><br />
<action name="Unmaximize"/><br />
</keybind><br />
<keybind key="W-Up"><br />
<action name="Maximize"/><br />
</keybind><br />
<br />
This [http://ubuntuforums.org/showthread.php?t=1796793 Ubuntu forum thread] provides more information. Applications such as {{AUR|opensnap-git}} are also available from the AUR to automatically simulate window snapping behaviour without the use of keybinds.<br />
<br />
=== Desktop menu ===<br />
<br />
It is also possible to create a keybind to access the desktop menu. For example, the following code will bring up the menu by pressing {{ic|CTRL}} + {{ic|m}}:<br />
<br />
<keybind key="C-m"><br />
<action name="ShowMenu"><br />
<menu>root-menu</menu><br />
</action><br />
</keybind><br />
<br />
== Menus ==<br />
<br />
It is possible to employ three types of menu in Openbox: {{ic|static}}, {{ic|pipes}} (dynamic), and {{ic|generators}} (static or dynamic). They may also be used alone or in any combination.<br />
<br />
=== Static ===<br />
<br />
As the name would suggest, this default type of menu does not change in any way, and may be manually edited and/or (re)generated automatically through the use on an appropriate software package.<br />
<br />
Fast and efficient, while this type of menu can be used to select applications, it can also be useful to access specific functions and/or perform specific tasks (e.g. desktop configuration), leaving the access of applications to another process (e.g. the {{Pkg|synapse}} or {{Pkg|xfce4-appfinder}} applications).<br />
<br />
The {{ic|~/.config/openbox/menu.xml}} file will be the sole source of static desktop menu content.<br />
<br />
==== menumaker ====<br />
<br />
{{Warning|A root terminal '''must''' be installed in order to use MenuMaker, even though a standard user terminal may be used to run it. {{Pkg|xterm}} is a good choice.}}<br />
<br />
{{Pkg|menumaker}} automatically generates {{ic|xml}} menus for several window managers, including Openbox, [[Fluxbox]], [[IceWM]] and [[XFCE]]. It will search for all installed executable programs and consequently create a menu file for them. It is also possible to configure MenuMaker to exclude certain application types (e.g. relating to [[Gnome]] or [[KDE]]), if desired.<br />
<br />
Once installed and executed, it will automatically generate a new {{ic|~/.config/openbox/menu.xml}} file. To avoid overwriting an existing file, enter:<br />
<br />
$ mmaker -v OpenBox3<br />
<br />
Otherwise, to overwrite an existing file, add the {{ic|force}} argument ({{ic|f}}):<br />
<br />
$ mmaker -vf OpenBox3<br />
<br />
Once a new {{ic|~/.config/openbox/menu.xml}} file has been generated it may then be manually edited, or configured using a GUI menu editor, such as {{Pkg|obmenu}}.<br />
<br />
==== obmenu ====<br />
<br />
{{Warning|{{ic|obm-xdg}} - a pipe menu to generate a list of [[GTK+]] and [[Gnome]] applications - is also provided with obmenu. However, it has long-running bugs whereby it may produce an invalid output, or even not function at all. Consequently it has been omitted from discussion.}}<br />
<br />
{{Pkg|obmenu}} is a "user-friendly" GUI application to edit {{ic|~/.config/openbox/menu.xml}}, without the need to code in {{ic|xml}}.<br />
<br />
==== xdg-menu ====<br />
<br />
{{Pkg|archlinux-xdg-menu}} will automatically generate a menu based on {{ic|xdg}} files contained within the {{ic|/etc/xdg/}} directory for numerous Window Managers, including Openbox. Review the [[Xdg-menu#OpenBox]] article for further information.<br />
<br />
==== logout menu options ====<br />
<br />
{{Tip|The commands provided can also be attached to [[Openbox#Keybinds|keybinds]].}}<br />
<br />
The {{ic|~/.config/openbox/menu.xml}} file can be edited in order to provide a sub-menu with the same options as provided by [[Openbox#oblogout|oblogout]]. The sample script below will provide all of these options, with the exception of the ability to lock the screen:<br />
<br />
<menu id="exit-menu" label="Exit"><br />
<item label="Log Out"><br />
<action name="Execute"><br />
<command>openbox --exit</command><br />
</action><br />
</item><br />
<item label="Shutdown"><br />
<action name="Execute"><br />
<command>systemctl poweroff</command><br />
</action><br />
</item><br />
<item label="Restart"><br />
<action name="Execute"><br />
<command>systemctl reboot</command><br />
</action><br />
</item><br />
<item label="Suspend"><br />
<action name="Execute"><br />
<command>systemctl suspend</command><br />
</action><br />
</item><br />
<item label="Hibernate"><br />
<action name="Execute"><br />
<command>systemctl hibernate</command><br />
</action><br />
</item><br />
</menu><br />
<br />
Once the entries have been composed, add the following line to present the sub-menu where desired within the main desktop menu (usually as the last entry):<br />
<br />
<menu id="exit-menu"/><br />
<br />
=== Pipes ===<br />
<br />
{{Tip|It is entirely feasible for a static menu to contain one or more pipe sub-menus. The functionality of some pipe menus may also rely on the installation of relevant software packages.}}<br />
<br />
This type of menu is in essence a script that provides dynamic, refreshed lists on-the-fly as and when run. These lists may be used for multiple purposes, including to list applications, to provide information, and to provide control functions. Pre-configured pipe menus can be installed, although not from the [[official repositories]]. More experienced users can also modify and/or create their own custom scripts. Again, {{ic|~/.config/openbox/menu.xml}} may and commonly will contain several pipe menus.<br />
<br />
==== Examples ====<br />
<br />
* {{AUR|openbox-xdgmenu}}: fast xdg-menu converter to xml-pipe-menu<br />
* {{AUR|obfilebrowser}}: Application and file browser<br />
* {{AUR|obdevicemenu}}: Management of removable media with [[Udisks#Udisks|Udisks]]<br />
* [https://bbs.archlinux.org/viewtopic.php?pid=1345031 wifi pipe menu]: Wireless networking using [[Netctl]]<br />
<br />
[http://openbox.org/download-pipemenus.php Openbox.org] also provides a further list of pipe menus.<br />
<br />
=== Generators ===<br />
<br />
This type of menu is akin to those provided by the taskbars of desktop environments such as [[XFCE]] or [[LXDE]]. Automatically updating on-the-fly, this type of menu can be powerful and very convenient. It may also be possible to add custom categories and menu entries; read the documentation for your intended dynamic menu to determine if and how this can be done.<br />
<br />
A menu generator will have to be executed from the {{ic|~/.config/openbox/menu.xml}} file.<br />
<br />
==== obmenu-generator ====<br />
<br />
{{Tip|icons can still be disabled in {{AUR|obmenu-generator}}, even where enabled in {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
{{AUR|obmenu-generator}} is currently only available from the [[AUR]], although it is still highly recommended. With the ability to be used as a static or dynamic menu, it is highly configurable, powerful, and versatile. Menu categories and individual entries may also be easily hidden, customised, and/or added with ease. The [http://trizenx.blogspot.co.uk/2012/02/obmenu-generator.html official homepage] provides further information and screenshots.<br />
<br />
Below is an example of how obmenu-generator would be dynamically executed without icons in {{ic|~/.config/openbox/menu.xml}}:<br />
<br />
<?xml version="1.0" encoding="utf-8"?><br />
<openbox_menu><br />
<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator"><br />
</menu><br />
</openbox_menu><br />
<br />
To automatically iconify entries, the {{ic|-i}} option would be added:<br />
<br />
<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator -i"><br />
<br />
==== openbox-menu ====<br />
<br />
{{Tip|If this menu produces an error, it may be solved by enabling icons in {{ic|~/.config/openbox/rc.xml}}.}}<br />
<br />
{{AUR|openbox-menu}} uses the [[LXDE]] [http://sourceforge.net/projects/lxde/files/menu-cache/ menu-cache] to create dynamic menus. The [http://mimasgpc.free.fr/openbox-menu_en.html official homepage] provides further information and screenshots.<br />
<br />
==== obmenugen ==== <br />
<br />
{{AUR|Obmenugen}} is currently only available from the [[AUR]], and can be used to a generate static or dynamic application menu based on {{ic|.desktop}} files. The [http://obmenugen.sourceforge.net/ official homepage] provides further information.<br />
<br />
=== Menu icons ===<br />
<br />
To show icons next to menu entries, it will be necessary to ensure they are enabled in the {{ic|<menu>}} section of the {{ic|~/.config/openbox/rc.xml}} file:<br />
<br />
<applicationIcons>yes</applicationIcons><br />
<br />
Where using a static menu, it will then be necessary to edit the {{ic|~/.config/openbox/menu.xml}} file to provide both the {{ic|icon <nowiki>=</nowiki>}} command, along with the full path and icon name for each entry. An example of the syntax used to provide an icon for a category is:<br />
<br />
<menu id="apps-menu" label="[label name]" icon="[pathway to icon]/[icon name]"><br />
<br />
=== Desktop menu as a panel menu ===<br />
<br />
{{Tip|XDoTool can simulate any keybind for any action, and as such, it may therefore be used for many other purposes...}}<br />
<br />
{{Pkg|xdotool}} is a package that can issue commands to simulate key presses / keybinds, meaning that it is possible to use it to invoke keybind-related actions without having to actually press their assigned keys. As this includes the ability to invoke an assigned keybind for the Openbox desktop menu, it is therefore possible to use XDoTool to turn the Openbox desktop menu into a panel menu. Especially where the desktop menu is heavily customised and feature-rich, this may prove very useful to:<br />
<br />
* Replace an existing panel menu<br />
* Implement a panel menu where otherwise not provided or possible (e.g. for {{AUR|tint2-svn}})<br />
* Compensate where losing access to the desktop menu due to the use of an application like [[Openbox#xfdesktop|xfdesktop]] to [[Openbox#Desktop_Icons_and_Wallpapers|manage the desktop]].<br />
<br />
Once XDoTool has been installed - if not already present - it will be necessary to create a keybind to access the root menu in {{ic|~/.config/openbox/rc.xml}}, and again below the {{ic|<nowiki><</nowiki>!-- Keybindings for running aplications --<nowiki>></nowiki>}} heading. For example, the following code will bring up the menu by pressing {{ic|CTRL}} + {{ic|m}}:<br />
<br />
<keybind key="C-m"><br />
<action name="ShowMenu"><br />
<menu>root-menu</menu><br />
</action><br />
</keybind><br />
<br />
Openbox must then be [[Openbox#Openbox_Reconfiguration|re-configured]]. In this instance, XDoTool will be used to simulate the {{ic|CTRL}} + {{ic|m}} keypress to access the desktop menu with the following command (note the use of {{ic|+}} in place of {{ic|-}}):<br />
<br />
xdotool key control+m<br />
<br />
How this command may be used as a panel launcher / icon is largely dependent on the features of panel used. While some panels will allow the above command to be executed directly in the process of creating a new launcher, others may require the use of an executable script. As an example, a custom executable script called {{ic|obpanelmenu.sh}} will be created in the {{ic|~/.config}} folder:<br />
<br />
$ ''text editor'' ~/.config/obpanelmenu.sh<br />
<br />
Once the empty file has been opened, the appropriate XDoTool command must be added to the empty file (i.e. to simulate the {{ic|CTRL}} + {{ic|m}} keypress for this example):<br />
<br />
xdotool key control+m<br />
<br />
After the file has been saved and closed, it may then be made into an executable script with the following command:<br />
<br />
$ chmod +x ~/.config/obpanelmenu.sh<br />
<br />
Executing it will bring up the Openbox desktop menu. Consequently, where using a panel that supports drag-and-drop functionality to add new launchers, simply drag the executable script onto it before changing the icon to suit personal taste. For instructions on how to use this executable script with {{AUR|tint2-svn}} - a derivative of the popular {{Pkg|tint2}} panel that allows launchers to be added - see [[Tint2#Application_Launchers_in_tint2-svn_.28AUR.29|Tint2-Svn launchers]].<br />
<br />
== GTK+ desktop theming ==<br />
<br />
{{Tip|It is '''strongly advised''' to install the {{Pkg|obconf}} and {{Pkg|lxappearance-obconf}} GUI applications to configure visual settings and theming. The latter is particularly important as it is responsible for generating the {{ic|~/.gtkrc-2.0}} file (see the [[Openbox#GTK+ 2|GTK fix]] section).}}<br />
<br />
It is important to note that a substantial range of both '''Openbox-specific''' and generalised, '''Openbox-compatible''' [[GTK]] themes are available to change the look of window decorations and the desktop menu. ''Generalised'' themes are designed to be simultaneously compatible with a range of popular desktop environments and/or window managers, commonly including Openbox. For example, {{AUR|gtk-theme-numix-blue}} supports both Openbox and [[XFCE]].<br />
<br />
=== Configuration ===<br />
<br />
{{Pkg|obconf}} and/or {{Pkg|lxappearance-obconf}} should be used to select and configure available GTK themes. See [[Uniform Look for Qt and GTK Applications]] for information about theming Qt based applications like [[Virtualbox]] or [[Skype]].<br />
<br />
=== Installation: official and AUR ===<br />
<br />
A good selection of {{Pkg|openbox-themes}} are available from the official repositories.<br />
<br />
Both Openbox-specific and Openbox-compatible themes installed from the [[Official_repositories|official repositories]] and/or the [[AUR]] will be automatically installed to the {{ic|/usr/share/themes}} directory. Both will also be immediately available for selection.<br />
<br />
=== Installation: other sources ===<br />
<br />
[http://www.box-look.org/index.php?xcontentmode=7402 box-look.org] is an excellent and well-established source of themes. [http://www.deviantart.com/ deviantART.com] is another excellent resource. Many more can be found through the utilisation of a search engine.<br />
<br />
==== Zip and tar files ====<br />
<br />
Themes downloaded from other sources such as [http://box-look.org/ box-look.org] will usually be compressed in a {{ic|.tar.gz}} or {{ic|.zip}} format. Although [[tar]] will have been installed as part of the base arch installation to extract {{ic|.tar.gz}} files, it will be necessary to install a program such as {{Pkg|unzip}} to extract {{ic|.zip}} files in the terminal. user-friendly GUI archivers are also available; see [[List of applications#Compression_tools]] for further information.<br />
<br />
Extracted theme files should also be placed in the {{ic|/usr/share/themes}} directory. For example, assuming downloaded content is automatically stored in the {{ic|~/Downloads}} folder, to simultaneously extract and move a {{ic|.tar.gz}} theme file, the syntax of the command would be:<br />
<br />
# tar xvf ~/Downloads/<theme file name>.tar.gz -C /usr/share/themes/<br />
<br />
To use {{Pkg|unzip}} in the same scenario for a {{ic|.zip}} theme file, the syntax of the command would be:<br />
<br />
# unzip ~/Downloads/<theme file name>.zip -d /usr/share/themes/<br />
<br />
Alternatively, it is also possible to simply move / copy and paste the extracted files to the {{ic|/usr/share/themes}} directory using an installed file manager as '''root'''.<br />
<br />
=== Troubleshooting ===<br />
<br />
There are two particular problems that may be encountered on rare occasions, especially where downloading themes from unsupported websites. These have been addressed below.<br />
<br />
==== Theme cannot be used ====<br />
<br />
If for any reason the newly extracted theme cannot be selected, open the theme directory to first ensure that it is indeed compatible with Openbox by determining that an {{ic|openbox-3}} directory is present, and that within this directory a {{ic|themerc}} file is also present. An {{ic|.obt}} ('''O'''pen'''B'''ox '''T'''heme) file may also be present in some instances, which can then be manually loaded in {{Pkg|obconf}}.<br />
<br />
Where expected files and directories are present and correct, then on occasion it is possible that the theme author has not correctly set permission to access the file (e.g. permission may still be for the account of the author, rather than for '''root'''). To eliminate this possibility, ensure the folder and file permissions are for '''root''':<br />
<br />
# chown -R root /user/share/themes<br />
<br />
==== Theme looks broken ====<br />
<br />
Of course, the first line of enquiry would be to check that it is not just a badly made, broken theme! Otherwise, ensure that the [[Openbox#GTK+ 2|Openbox GTK fix]] has been implemented, and then re-start the session. Unfortunately some older themes can simply break if not maintained sufficiently to keep pace with the changes incurred by [[GTK]] updates. To avoid such occurrences, it is best to check that desired themes have recently been created or at least updated / patched.<br />
<br />
=== Edit or create new themes ===<br />
<br />
{{Tip|Where deciding to modify an existing theme (e.g. the colour scheme), it would be best to work on a copy of it, rather than the original. This will retain the original should anything go wrong, and ensure that your changes are not over-written through an update.}}<br />
<br />
The process of creating new or modifying existing themes is covered extensively at the official [http://openbox.org/wiki/Help:Themes openbox.org] website. A user-friendly GUI to do so - {{AUR|obtheme}} - is also available from the [[AUR]].<br />
<br />
== Compositing effects ==<br />
<br />
Openbox does not natively provide support for compositing, and it will therefore be necessary to install a compositor for this purpose. The use of compositing enables various desktop visual effects, including transparency, fading, and shadows. Although compositing is not a necessary component, it can help to provide a more pleasant-looking environment, and avoid common issues such as screen distortion when [[Openbox#Oblogout|oblogout]] is used, and visual glitches when terminal window transparency has been enabled. Three of the most common choices are:<br />
<br />
* [[Compton]]: Powerful and reliable, with extensive options<br />
* [[Xcompmgr]]: Older and simpler version of compton<br />
* [[Cairo Compmgr]]: Advanced compositing effects, plugin support, and a user-friendly GUI. Also more buggy and far heavier use of system resources.<br />
<br />
== Mouse cursor and application icon themes ==<br />
<br />
Any mouse cursor and/or application icon theme may be used with Openbox. Numerous themes are available from both the [[official repositories]] and the [[AUR]].<br />
<br />
=== xcursor themes (mouse) === <br />
<br />
{{Tip|Review the [[Xcursor]] article for an in-depth explanation.}}<br />
<br />
Standard xcursor theme packages available from the official repositories include {{Pkg|xcursor-themes}}, {{Pkg|xcursor-bluecurve}}, {{Pkg|xcursor-vanilla-dmz}}, and {{Pkg|xcursor-pinux}}. To search the official repositories for all available xcursor themes, enter the following command:<br />
<br />
$ pacman -Ss xcursor<br />
<br />
Installed x-cursor themes may then be set though using the {{Pkg|obconf}} and {{Pkg|lxappearance-obconf}} GUI applications. It may then be necessary to either log out and back in again to implement the change, or to [[Openbox#Openbox_Reconfiguration|reconfigure Openbox]].<br />
<br />
=== Application icon themes ===<br />
<br />
Standard xcursor theme packages available from the official repositories include the {{Pkg|gnome-icon-theme}} and {{Pkg|lxde-icon-theme}}. A nice icon theme currently available from the AUR is {{AUR|numix-icon-theme-git}}. To search the official repositories for all available icon themes, enter the following command:<br />
<br />
$ pacman -Ss icon-theme<br />
<br />
Again, installed icon themes may then be set though using the {{Pkg|obconf}} and {{Pkg|lxappearance-obconf}} GUI applications. It may then be necessary to either log out and back in again to implement the change, or to [[Openbox#Openbox_Reconfiguration|reconfigure Openbox]].<br />
<br />
== Desktop icons and wallpapers ==<br />
<br />
Openbox does not natively support the use of desktop icons or wallpapers. As a consequence, it will be necessary to install additional applications for this purpose, where desired.<br />
<br />
=== Desktop management using file managers ===<br />
<br />
Some file managers have the capacity to fully '''manage the desktop''', meaning that they may be used to provide wallpapers and enable the use of icons on the desktop. The [[LXDE]] desktop environment itself uses PCManFM for this purpose.<br />
<br />
* [[PCManFM]]: See the [[PCManFM#Desktop_management|PCManFM desktop management]] article.<br />
* [[SpaceFM]]: See the [[SpaceFM#Desktop_management|SpaceFM desktop management]] article.<br />
<br />
=== Wallpaper / background programs ===<br />
<br />
{{Tip|The wallpaper programs listed here will have many more options than shown in this brief overview, including the ability to use solid colours for backgrounds. Review their documentation and man pages for more information.}}<br />
<br />
There are numerous packages available to set desktop backgrounds in Openbox, each of which will need to be autostarted in the {{ic|~/.config/openbox/autostart}} file. A few of the most well known have been listed.<br />
<br />
==== nitrogen ====<br />
<br />
{{Tip|If nitrogen does not show in the desktop menu, then it can be manually added.}}<br />
<br />
[[nitrogen]] is a user-friendly choice, as it also provides a GUI window to browse and set installed images. To access the GUI, enter the following command in a terminal:<br />
<br />
$ nitrogen<br />
<br />
To use nitrogen as the background provider, add the following command to the {{ic|~/.config/openbox/autostart}} file so that it will restore the last set wallpaper:<br />
<br />
nitrogen --restore &<br />
<br />
==== feh ====<br />
<br />
[[Feh]] is a popular image viewer that may also be used to set wallpapers. In this instance, it will be necessary to add the full directory path and name of the image to be used as the wallpaper. To use Feh as the background provider, add the following command to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
feh --bg-scale ''/path/to/image.file'' &<br />
<br />
==== hsetroot ====<br />
<br />
{{Pkg|hsetroot}} is a command-line tool specifically designed to set wallpapers. As with Feh, it will be necessary to add the full directory path and name of the image to be used as the wallpaper. To use HSetRoot as the background provider, add the following command to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
hsetroot -fill ''/path/to/image.file'' &<br />
<br />
==== xsetroot ====<br />
<br />
{{ic|xsetroot}} is installed as part of the [[Xorg]] X-Windows system, and may be used to set simple background colours. For example, to use XSetRoot to set a black background, the following would be added to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
xsetroot -solid "#000000" &<br />
<br />
=== Icon programs ===<br />
<br />
While there are programs dedicated to enabling desktop icons alone, it would seem that they have greater drawbacks than the utilisation of file managers for the task. These programs are discussed briefly, below.<br />
<br />
==== idesk ====<br />
<br />
[[idesk]] is a simple program that can enable icons in addition to managing wallpaper. It will be necessary to create an {{ic|~/.idesktop}} directory, and desktop icons must also be manually created. To use idesk to provide icons, add the following command to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
idesk &<br />
<br />
==== xfdesktop ====<br />
<br />
{{Pkg|xfdesktop}} is the desktop manager for [[XFCE]]. The [[Thunar]] file manager will also be downloaded as a dependency. Where this is used, the Openbox desktop menu will no longer be accessible by right-clicking the background. <br />
<br />
As such, it will consequently be necessary to access it by other means, such as by [[Openbox#Desktop_Menu|creating a keybind]], and/or by - where permitted - re-configuring an installed panel to use the [[Openbox#Desktop_menu_as_a_panel_menu|desktop menu as a panel menu]]. To use xfdesktop to provide icons, add the following command to the {{ic|~/.config/openbox/autostart}} file:<br />
<br />
xfdesktop &<br />
<br />
=== conky reconfiguration ===<br />
<br />
Particularly where using a file manager to manage the desktop, it will be necessary to edit {{ic|~/.conkyrc}} to change the {{ic|own_window_type}} command in order for [[conky]] to continue to be displayed (where used). The revised command that should be used is:<br />
<br />
own_window_type normal<br />
<br />
== File managers ==<br />
<br />
Multiple [[List of applications#File managers|file managers]] may be used with Openbox, including [[PCManFM]], [[SpaceFM]], [[Thunar]], {{Pkg|xfe}}, and {{Pkg|qtfm}}. Thunar is the native file manager for [[Xfce]], and if installing be aware that some Xfce-related dependencies will also be installed, including {{Pkg|exo}} (set default applications) and '''xfce4-about''' (provide information about the Xfce deskop environment). The menu entries for these may consequently have to be hidden.<br />
<br />
A file manager alone will not provide the same features and functionality as provided by default in full desktop environments like [[Xfce]] and [[KDE]]. For example, it may not be initially possible to view or access other partitions or access removable media. See [[File manager functionality]] for further information.<br />
<br />
== oblogout ==<br />
<br />
See the [[Oblogout]] article for an overview on how to use this useful, graphical logout script.<br />
<br />
== Openbox for multihead users ==<br />
<br />
While Openbox provides better than average multihead support on its own, the {{AUR|openbox-multihead-git}} package from the [[AUR]] provides a development branch called '''Openbox Multihead''' that gives multihead users per-monitor desktops. This model is not commonly found in floating window managers, but exists mainly in tiling window managers. It is explained well on the [http://xmonad.org/tour.html#workspace Xmonad web site]. Also, please see [https://github.com/BurntSushi/openbox-multihead/blob/multihead/README.MULTIHEAD README.MULTIHEAD] for a more comprehensive description of the new features and configuration options found in Openbox Multihead.<br />
<br />
Openbox Multihead will function like normal Openbox when only a single head is available.<br />
<br />
A downside to using Openbox Multihead is that it breaks the EWMH assumption that one and only one desktop is visible at any time. Thus, existing pagers will not work well with it. To remedy this, {{AUR|pager-multihead-git}} can be found in the [[AUR]] and is compatible with Openbox Multihead. [http://imgur.com/a/cnZeq#y04nk Screenshots].<br />
<br />
Finally, a new version of [[PyTyle]] that will work with Openbox Multihead can also be found in the [[AUR]]: {{AUR|pytyle3-git}}.<br />
<br />
Both ''pytyle3'' and ''pager-multihead-git'' will work without Openbox Multihead if only one monitor is active.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Packages for beginners ===<br />
<br />
{{Tip|See the [[List of applications]] article for many more possibilities.}}<br />
<br />
The packages listed below have been listed to aid newer users:<br />
<br />
* Display Manager: [[LXDM]] or [[LightDM]]<br />
* Audio: [[ALSA]]<br />
* Volume: {{Pkg|volumeicon}} or {{AUR|pnmixer}} with {{Pkg|gnome-alsamixer}}<br />
* Network: [[Network manager]] with {{Pkg|network-manager-applet}}<br />
* Panel: [[Tint2]] or [[Tint2#Application_Launchers_in_tint2-svn_.28AUR.29|Tint2-svn]]<br />
* Background: [[Nitrogen]] or [[Feh]]<br />
* Menu: [[Openbox#obmenu-generator|OBMenu-Generator]]<br />
* Compositor: [[Compton]]<br />
* Desktp Notifications: {{Pkg|xfce4-notifyd}}<br />
* Logout script: [[Oblogout]]<br />
* File Manager: [[PCManFM]], [[SpaceFM]], or [[Thunar]]<br />
* Clipboard Manager: {{Pkg|parcellite}}<br />
* Configuration GUIs: {{Pkg|obconf}}, {{Pkg|lxappearance-obconf}}, {{Pkg|lxrandr}}, {{Pkg|lxinput}}, {{AUR|tintwizard}} or {{AUR|tintwizard-svn}}<br />
<br />
=== Set default applications / file associations ===<br />
<br />
See the [[Default applications]] article.<br />
<br />
=== Terminal content copy and paste ===<br />
<br />
Within a terminal, either:<br />
<br />
* {{ic|Ctrl+Ins}} will copy and {{ic|Shift+Ins}} will paste. <br />
* {{ic|Ctrl+Shift+c}} will copy and '''mouse middle-click''' will paste.<br />
<br />
=== Ad-hoc window transparency ===<br />
<br />
{{Warning|This may not work where other actions are defined within the action group.}}<br />
The program {{Pkg|transset-df}} is available in the official repositories, and can enable window transparency on-the-fly.<br />
<br />
For example, using the following code in the {{ic|<mouse>}} section of the {{ic|~/.config/openbox/rc.xml}} file will enable control of application window transparency by hovering the mouse-pointer over the title bar and scrolling with the middle button:<br />
<br />
<context name="Titlebar"><br />
...<br />
<mousebind button="Up" action="Click"><br />
<action name= "Execute" ><br />
<execute>transset-df -p .2 --inc </execute><br />
</action><br />
</mousebind><br />
<mousebind button="Down" action="Click"><br />
<action name= "Execute" ><br />
<execute>transset-df -p .2 --dec </execute><br />
</action><br />
</mousebind><br />
...<br />
</context><br />
<br />
=== Using obxprop for faster configuration ===<br />
<br />
{{Pkg|openbox}} package provides a {{ic|obxprop}} binary that can parse relevant values for applications settings in {{ic|rc.xml}}. Officially {{ic|<nowiki>obxprop | grep "^_OB_APP"</nowiki>}} is recommended for this task. Doing so for multiple applications and its windows can be very inefficient however. The following script {{ic|obxprop2obrc}} makes it much easier to configure even a large number of applications.<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
##Script: obxprop-to-openbox-rc.sh<br />
##Recommended executable name: obxprop2obrc<br />
<br />
while [ $# -ne 0 ]; do<br />
case $1 in<br />
-f*)<br />
shift;<br />
FILE="$1";<br />
shift;<br />
;;<br />
-t*)<br />
shift;<br />
TIME="$1";<br />
shift;<br />
;;<br />
*)<br />
echo Usage: $0 [-f FILE_TEMPLATE] [-t WAIT_TO_KILL_TIME] <br />
exit 1;<br />
;;<br />
esac<br />
done<br />
<br />
if [ $TIME ]; then<br />
OBXPROPS=( $(obxprop | cat & (sleep $TIME && pkill -13 cat) | awk -F \" '/_OB_APP/{ print "\x22"$2"\x22" }' ) );<br />
else<br />
OBXPROPS=( $(obxprop | awk -F \" '/_OB_APP/{ print "\x22"$2"\x22" }' ) );<br />
fi<br />
OBPROPS=(TYPE TITLE GROUP_CLASS GROUP_NAME CLASS NAME ROLE);<br />
j=0;<br />
for i in $( seq 2 2 14 ); do<br />
OBPROP="$( echo ${OBXPROPS[@]} | awk -F \" '{ print $'$i'}' )";<br />
if [[ -z $OBPROP ]]; then <br />
declare ${OBPROPS[$j]}='"*"';<br />
else <br />
declare ${OBPROPS[$j]}="\"$OBPROP\"";<br />
fi<br />
j=$(($j+1));<br />
done;<br />
<br />
echo " <application type="$TYPE" title="$TITLE" class="$CLASS" name="$NAME" role="$ROLE">"<br />
if [ -f "$FILE" ]; then cat "$FILE" && exit; fi<br />
cat << EOF<br />
<desktop>1</desktop><br />
<desktop>all</desktop><br />
<decor>yes</decor><br />
<decor>no</decor><br />
<focus>yes</focus><br />
<focus>no</focus><br />
<fullscreen>yes</fullscreen><br />
<fullscreen>no</fullscreen><br />
<iconic>yes</iconic><br />
<iconic>no</iconic><br />
<maximized>yes</maximized><br />
<maximized>no</maximized><br />
<maximized>both</maximized><br />
<maximized>horizontal</maximized><br />
<maximized>vertical</maximized><br />
<monitor>0</monitor><br />
<monitor>1</monitor><br />
<position force="no"><br />
<position force="yes"><br />
<width>40%</width><br />
<height>30%</height><br />
<x>-1</x><br />
<y>-1</y><br />
<x>center</x><br />
<y>center</y><br />
</position><br />
<layer>above</layer><br />
<layer>normal</layer><br />
<layer>below</layer><br />
<shade>yes</shade><br />
<shade>no</shade><br />
<skip_pager>yes</skip_pager><br />
<skip_pager>no</skip_pager><br />
<skip_taskbar>yes</skip_taskbar><br />
<skip_taskbar>no</skip_taskbar><br />
</application><br />
EOF<br />
</nowiki>}}<br />
<br />
If no further options are used default configuration, that can be edited by deleting unnecessary lines, is printed out. This script can use templates with default values when using {{ic|-f}} switch:<br />
{{hc|<br />
$ obxprop2obrc -f templates-rc-inkscape-dialogs.sc > part-rc-applications-inkscape.xml<br />
$ cat part-rc-applications-inkscape.xml|<nowiki><br />
<application type="normal" title="Align and Distribute (Shift+Ctrl+A)" class="Inkscape" name="inkscape" role="*"><br />
<desktop>3</desktop><br />
<decor>yes</decor><br />
<maximized>no</maximized><br />
<position force="yes"><br />
<width>20%</width><br />
<height>30%</height><br />
<x>-1</x><br />
<y>-1</y><br />
</position><br />
<layer>normal</layer><br />
<shade>yes</shade><br />
</application><br />
</nowiki>}}<br />
<br />
It also has a time switch {{ic|-t}} which kills obxprop and thus can reduce time significantly in certain situations, although it may not work perfectly.<br />
<br />
=== Xprop values for applications ===<br />
<br />
{{Pkg|xorg-xprop}} is available in the official repositories, and can be used to relay property values for selected applications. Where frequently using per-application settings, the following [[Bash#Aliases|Bash Alias]] may be useful:<br />
dy:<br />
<br />
alias xp='xprop | grep "WM_WINDOW_ROLE\|WM_CLASS" && echo "WM_CLASS(STRING) = \"NAME\", \"CLASS\""'<br />
<br />
To use Xorg-XProp, run using the alias given {{ic|xp}}, and click on the active program desired to define with per-application settins. The results displayed will only be the information that Openbox itself requires, namely the {{ic|WM_WINDOW_ROLE}} and {{ic|WM_CLASS}} (name and class) values:<br />
<br />
WM_WINDOW_ROLE(STRING) = "roster"<br />
WM_CLASS(STRING) = "gajim.py", "Gajim.py"<br />
WM_CLASS(STRING) = "NAME", "CLASS"<br />
<br />
==== Firefox ====<br />
<br />
For whatever reason, Firefox and like-minded equivalents ignore application rules (e.g. ''<desktop>'') unless {{ic|class&#61;"Firefox*"}} is used. This applies irrespective of whatever values '''xprop''' may report for the program's {{ic|WM_CLASS}}.<br />
<br />
=== Switching between keyboard layouts ===<br />
<br />
See the article section [[Keyboard configuration in Xorg#Switching between keyboard layouts|switching between keyboard layouts]] for instructions.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Windows load behind the active window ===<br />
<br />
Some application windows (such as Firefox windows) may load behind the currently active window, causing you to need to switch to the window you just created to focus it. To fix this behavior add this to your {{ic|~/.config/openbox/rc.xml}} file, inbetween the {{ic|1=<openbox_config>}} and {{ic|1=</openbox_config>}} tags:<br />
<br />
{{bc|1=<br />
<applications><br />
<application class="*"><br />
<focus>yes</focus><br />
</application><br />
</applications><br />
}}<br />
<br />
== See also ==<br />
<br />
* [http://openbox.org/ Openbox Website] - Official website<br />
* [http://planetob.openmonkey.com/ Planet Openbox] - Openbox news portal<br />
* [http://www.box-look.org/ Box-Look.org] - A good resource for themes and related artwork<br />
* [https://bbs.archlinux.org/viewtopic.php?id=93126 Openbox Hacks and Configs Thread] @ Arch Linux Forums<br />
* [https://bbs.archlinux.org/viewtopic.php?id=45692 Openbox Screenshots Thread] @ Arch Linux Forums<br />
* [http://urukrama.wordpress.com/openbox-guide/ An Openbox guide]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Wine&diff=310771Wine2014-04-18T02:13:51Z<p>Bluerider: /* Removing menu entries */</p>
<hr />
<div>[[Category:Wine]]<br />
[[cs:Wine]]<br />
[[de:Wine]]<br />
[[es:Wine]]<br />
[[fr:Wine]]<br />
[[it:Wine]]<br />
[[ja:Wine]]<br />
[[ru:Wine]]<br />
[[zh-CN:Wine]]<br />
[[zh-TW:Wine]]<br />
{{Related articles start}}<br />
{{Related|Steam/Wine}}<br />
{{Related|CrossOver}}<br />
{{Related articles end}}<br />
[[Wikipedia:Wine (software)|Wine]] is a ''compatibility layer'' capable of running Microsoft Windows applications on Unix-like operating systems. Programs running in Wine act as native programs would, without the performance/memory penalties of an emulator. See the [http://www.winehq.org/ official project home] and [http://wiki.winehq.org/ wiki] pages for longer introduction. <br />
<br />
== Installation ==<br />
{{Warning|If you can access a file or resource with your user account, programs running in Wine can too. Wine prefixes are '''not''' [[wikipedia:Sandbox (computer security)|sandboxes]]. Consider using [[wikipedia:Virtualization|virtualization]] if security is important.}}<br />
<br />
Wine can be [[pacman|installed]] with the package {{Pkg|wine}}, available in the [[official repositories]]. If you are running a 64-bit system, you will need to enable the [[Multilib]] repository first.<br />
<br />
You may also want to install {{pkg|wine_gecko}} and {{pkg|wine-mono}} for applications that need support for Internet Explorer and .NET, respectively. These packages are not strictly required as Wine will download the relevant files as needed. However, having the files downloaded in advance allows you to work off-line and makes it so Wine does not download the files for each WINEPREFIX needing them.<br />
<br />
'''Architectural differences'''<br />
<br />
Wine by default is 32-bit, as is the i686 Arch package. As such, it is unable to execute any 64-bit Windows applications.<br />
<br />
The x86_64 Arch package, however, is built with {{ic|--enable-win64}}. This activates the Wine version of [[Wikipedia:WoW64|WoW64]]. <br />
*In Windows, this complicated subsystem allows the user to use 32-bit and 64-bit Windows programs concurrently and even in the same directory. <br />
*In Wine, the user will have to make separate directories/prefixes. See [http://wiki.winehq.org/Wine64 Wine64] for specific information on this.<br />
<br />
If you run into problems with {{ic|winetricks}} or programs with a 64-bit environment, try creating a new 32-bit {{ic|WINEPREFIX}}. See below: [[#Using WINEARCH]]. Using the x86_64 Wine package with {{ic|1=WINEARCH=win32}} should have the same behaviour as using the i686 Wine package.<br />
<br />
== Configuration ==<br />
Configuring Wine is typically accomplished using:<br />
* [http://wiki.winehq.org/winecfg winecfg] is a GUI configuration tool for Wine. You can run it from a console window with: {{ic|$ winecfg}}, or {{ic|1=$ WINEPREFIX=~/.some_prefix winecfg}}.<br />
* [http://wiki.winehq.org/control control.exe] is Wine's implementation of Windows' Control Panel which can be accessed with: {{ic|$ wine control}}<br />
* [http://wiki.winehq.org/regedit regedit] is Wine's registry editing tool. If winecfg and the Control Panel were not enough, see [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's article on Useful Registry Keys]<br />
<br />
=== WINEPREFIX ===<br />
By default, Wine stores its configuration files and installed Windows programs in {{ic|~/.wine}}. This directory is commonly called a "Wine prefix" or "Wine bottle" It is created/updated automatically whenever you run a Windows program or one of Wine's bundled programs such as {{ic|winecfg}}. The prefix directory also contains a tree which your Windows programs will see as {{ic|C:}} (the C-drive).<br />
<br />
You can override the location Wine uses for a prefix with the {{ic|WINEPREFIX}} environment variable. This is useful if you want to use separate configurations for different Windows programs. The first time a program is run with a new Wine prefix, Wine will automatically create a directory with a bare C-drive and registry.<br />
<br />
For example, if you run one program with {{ic|1= $ env WINEPREFIX=~/.win-a wine program-a.exe}}, and another with {{ic|1= $ env WINEPREFIX=~/.win-b wine program-b.exe}}, the two programs will each have a separate C-drive and separate registries.<br />
<br />
{{Note|Wine prefixes are not sandboxes! Programs running under Wine can still access the rest of the system! (for example, {{ic|Z:}} is mapped to {{ic|/}}, regardless of the Wine prefix.)}}<br />
<br />
To create a default prefix without running a Windows program or other GUI tool you can use:<br />
$ env WINEPREFIX=~/.customprefix wineboot -u<br />
<br />
=== WINEARCH ===<br />
<br />
If you have a 64-bit system, Wine will start an 64-bit environment by default. You can change this behavior using the {{ic|WINEARCH}} environment variable. Rename your {{ic|~/.wine}} directory and create a new wine environment by running {{ic|1=$ WINEARCH=win32 winecfg}}. This will get you a 32-bit wine environment. Not setting {{ic|WINEARCH}} will get you a 64-bit one.<br />
<br />
You can combine this with {{ic|WINEPREFIX}} to make a separate win32 and win64 environment:<br />
<br />
$ WINEARCH=win32 WINEPREFIX=~/win32 winecfg <br />
$ WINEPREFIX=~/win64 winecfg<br />
<br />
{{Note|During prefix creation, the 64-bit version of wine treats all folders as 64-bit prefixes and will not create a 32-bit in any existing folder. To create a 32-bit prefix you have to let wine create the folder specified in {{ic|WINEPREFIX}}.}}<br />
<br />
You can also use {{ic|WINEARCH}} in combination with other Wine programs, such as winetricks (using Steam as an example):<br />
<br />
WINEARCH=win32 WINEPREFIX=~/.local/share/wineprefixes/steam winetricks steam<br />
<br />
To have them permanently defined for [[Bash#Shell and environment variables|bash configuration ~/.bashrc]] do:<br />
<br />
export WINEPREFIX=$HOME/.config/wine/<br />
export WINEARCH=wine32<br />
<br />
=== Graphics drivers ===<br />
<br />
For most games, Wine requires high performance accelerated graphics drivers. This likely means using proprietary [[NVIDIA]] or [[AMD Catalyst]] drivers, although the open source [[ATI]] driver is increasingly become proficient for use with Wine. [[Intel]] drivers should mostly work as well as they are going to out of the box.<br />
<br />
See [http://www.phoronix.com/scan.php?page=news_item&px=MTI5NjU Gaming On Wine: The Good & Bad Graphics Drivers] for more details.<br />
<br />
A good sign that your drivers are inadequate or not properly configured is when Wine reports the following in your terminal window:<br />
Direct rendering is disabled, most likely your OpenGL drivers have not been installed correctly<br />
<br />
For x86-64 systems, additional [[multilib]] packages are required. Please install the one that is listed in the ''Multilib Package'' column in the table in [[Xorg#Driver installation]].<br />
<br />
{{Note|You might need to restart X after having installed the correct library.}}<br />
<br />
=== Sound ===<br />
<br />
By default sound issues may arise when running Wine applications. Ensure only one sound device is selected in {{ic|winecfg}}. Currently, the [[Alsa]] driver is the most supported.<br />
<br />
If you want to use [[Alsa]] driver in Wine, and are using x86_64, you'll need to install the {{Pkg|lib32-alsa-lib}}. If you are also using PulseAudio, you will need to install {{Pkg|lib32-libpulse}}.<br />
<br />
If you want to use [[OSS]] driver in Wine, you will need to install the {{Pkg|lib32-alsa-oss}} package. The OSS driver in the kernel will not suffice.<br />
<br />
If {{ic|winecfg}} '''still''' fails to detect the audio driver (Selected driver: (none)), [http://wiki.jswindle.com/index.php/Wine_Registry#Configuring_Sound configure it via the registry].<br />
<br />
Games that use advanced sound systems may require installations of {{Pkg|lib32-openal}}.<br />
<br />
==== MIDI support ====<br />
<br />
[[MIDI]] was a quite popular system for video games music in the 90. If you are trying out old games, it is not uncommon that the music will not play out of the box.<br />
Wine has excellent MIDI support. However you first need to make it work on your host system. See the wiki page for more details. Last but not least you need to make sure Wine will use the correct MIDI output. See the [http://wiki.winehq.org/MIDI Wine Wiki] for a detailed setup.<br />
<br />
=== Other libraries ===<br />
<br />
*Some applications (e.g. Office 2003/2007) require the MSXML library to parse HTML or XML, in such cases you need to install {{Pkg|lib32-libxml2}}.<br />
<br />
*Some applications that play music may require {{Pkg|lib32-mpg123}}.<br />
<br />
*Some applications that use native image manipulation libraries may require {{Pkg|lib32-giflib}} and {{Pkg|lib32-libpng}}.<br />
<br />
*Some applications that require encryption support may require {{Pkg|lib32-gnutls}}.<br />
<br />
=== Fonts ===<br />
<br />
If Wine applications are not showing easily readable fonts, you may not have Microsoft's Truetype fonts installed. See [[MS Fonts]]. If this does not help, try running {{ic|winetricks allfonts}}.<br />
<br />
After running such programs, kill all wine servers and run {{ic|winecfg}}. Fonts should be legible now.<br />
<br />
If the fonts look somehow smeared, import the following text file into the Wine registry with [http://wiki.winehq.org/regedit regedit]:<br />
[HKEY_CURRENT_USER\Software\Wine\X11 Driver]<br />
"ClientSideWithRender"="N"<br />
<br />
=== Desktop launcher menus ===<br />
<br />
When installing Windows programs with Wine, should result in the appropriate menu/desktop icons being created. For example, if the installation program (e.g. {{ic|setup.exe}}) would normally add an icon to your Desktop or "Start Menu" on Windows, then Wine should create corresponding freedesktop.org style {{ic|.desktop}} files for launching your programs with Wine.<br />
<br />
{{Tip|If menu items were ''not'' created while installing software or have been lost, [http://wiki.winehq.org/winemenubuilder winemenubuilder] may be of some use.}}<br />
<br />
==== Creating menu entries for Wine utilities ====<br />
<br />
By default, installation of Wine does not create desktop menus/icons for the software which comes with Wine (e.g. for {{ic|winecfg}}, {{ic|winebrowser}}, etc). These instructions will add entries for these applications.<br />
<br />
First, install a Windows program using Wine to create the base menu. After the base menu is created, you can create the following files in {{ic|~/.local/share/applications/wine/}}:<br />
<br />
{{hc|wine-browsedrive.desktop|2=<br />
[Desktop Entry]<br />
Name=Browse C: Drive<br />
Comment=Browse your virtual C: drive<br />
Exec=wine winebrowser c:<br />
Terminal=false<br />
Type=Application<br />
Icon=folder-wine<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-uninstaller.desktop|2=<br />
[Desktop Entry]<br />
Name=Uninstall Wine Software<br />
Comment=Uninstall Windows applications for Wine<br />
Exec=wine uninstaller<br />
Terminal=false<br />
Type=Application<br />
Icon=wine-uninstaller<br />
Categories=Wine;<br />
}}<br />
<br />
{{hc|wine-winecfg.desktop|2=<br />
[Desktop Entry]<br />
Name=Configure Wine<br />
Comment=Change application-specific and general Wine options<br />
Exec=winecfg<br />
Terminal=false<br />
Icon=wine-winecfg<br />
Type=Application<br />
Categories=Wine;<br />
}}<br />
<br />
And create the following file in {{ic|~/.config/menus/applications-merged/}}:<br />
<br />
{{hc|wine.menu|2=<br />
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"<br />
"http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd"><br />
<Menu><br />
<Name>Applications</Name><br />
<Menu><br />
<Name>wine-wine</Name><br />
<Directory>wine-wine.directory</Directory><br />
<Include><br />
<Category>Wine</Category><br />
</Include><br />
</Menu><br />
</Menu><br />
}}<br />
<br />
If these settings produce a ugly/non-existent icon, it means that there are no icons for these launchers in the icon set that you have enabled. You should replace the icon settings with the explicit location of the icon that you want. Clicking the icon in the launcher's properties menu will have the same effect. A great icon set that supports these shortcuts is [http://www.gnome-look.org/content/show.php/GNOME-colors?content=82562 GNOME-colors].<br />
<br />
==== Removing menu entries ====<br />
<br />
Menu entries created by Wine are located in {{ic|~/.local/share/applications/wine/Programs/}}. Remove the program's {{ic|.desktop}} entry to remove the application from the menu.<br />
<br />
In addition to remove unwanted extensions binding by wine, do the following (taken from wine website):<br />
{{bc|<nowiki><br />
To clean Open With List, please carefully paste the following commands into a terminal:<br />
<br />
rm -f ~/.local/share/mime/packages/x-wine*<br />
rm -f ~/.local/share/applications/wine-extension*<br />
rm -f ~/.local/share/icons/hicolor/*/*/application-x-wine-extension*<br />
rm -f ~/.local/share/mime/application/x-wine-extension* </nowiki>}}<br />
<br />
==== KDE 4 menu fix ====<br />
<br />
The Wine menu items [https://bugs.launchpad.net/ubuntu/+source/wine/+bug/263041 may appear] in {{ic|"Lost & Found"}} instead of the Wine menu in KDE 4. This is because {{ic|kde-applications.menu}} is missing the {{ic|MergeDir}} option.<br />
<br />
Edit {{ic|/etc/xdg/menus/kde-applications.menu}}<br />
<br />
At the end of the file add {{ic|<MergeDir>applications-merged</MergeDir>}} after {{ic|<DefaultMergeDirs/>}}, it should look like this:<br />
<Menu><br />
<Include><br />
<And><br />
<Category>KDE</Category><br />
<Category>Core</Category><br />
</And><br />
</Include><br />
<DefaultMergeDirs/><br />
'''<MergeDir>applications-merged</MergeDir>'''<br />
<MergeFile>applications-kmenuedit.menu</MergeFile><br />
</Menu><br />
<br />
Alternatively you can create a symlink to a folder that KDE does see:<br />
$ ln -s ~/.config/menus/applications-merged ~/.config/menus/kde-applications-merged<br />
<br />
This has the added bonus that an update to KDE won't change it, but is per user instead of system wide.<br />
<br />
== Running Windows applications ==<br />
<br />
{{Warning|Do not run or install Wine applications as root! See [http://wiki.winehq.org/FAQ#run_as_root Running Wine as root] for the official statement.}}<br />
To run a windows application:<br />
$ wine <path to exe><br />
<br />
To install using an MSI installer, use the included msiexec utility:<br />
$ msiexec installername.msi<br />
<br />
== Tips and tricks ==<br />
<br />
{{Tip|In addition to the links provided in the beginning of the article the following may be of interest:<br />
* [http://appdb.winehq.org/ The Wine Application Database (AppDB)] - Information about running specific Windows applications (Known issues, ratings, guides, etc tailored to specific applications)<br />
* [http://forum.winehq.org/ The WineHQ Forums] - A great place to ask questions ''after'' you have looked through the FAQ and AppDB<br />
}}<br />
<br />
=== exe-thumbnailer ===<br />
<br />
This is a small piece of UI code meant to be installed with (or even before) Wine. It provides thumbnails for executable files that show the embedded icons when available, and also gives the user a hint that Wine will be used to open it. Details can be found at [http://wiki.winehq.org/exe-thumbnailer wine wiki]. gnome-exe-thumbnailer is available in [https://aur.archlinux.org/packages/?K=exe-thumbnailer AUR].<br />
<br />
=== CSMT Patched Wine for Significantly Better Performance ===<br />
<br />
Currently [http://www.winehq.org/pipermail/wine-devel/2013-September/101106.html wine developers] experiment with stream/worker thread optimizations for Wine. You may experience an enormous performance improvement by using this experimental patched Wine versions. Many games may run as fast as on Windows or even faster. This Wine patch is is known as CSMT patch and works with Nvidia and AMD graphics cards.<br />
<br />
{{Note|This is ''still experimental code'', therefore, it may not work as expected. Please, report your experiences to the developers for helping with development of those patches.}}<br />
<br />
The easy way is to install {{Pkg|playonlinux}}. Then install your game and activate the Wine version ''1.7.4-CSMT'' from the ''Tools/Manage Wine Versions'' menu in PlayOnLinux. For now it is recommended to use the patched Wine version ''1.7.4-CSMT''.<br />
<br />
Open your game's configuration settings and copy the following settings to the ''Miscellaneous/Command to exec before running the program'' section of your game configuration settings:<br />
<br />
export WINEDEBUG=-all<br />
export LD_PRELOAD="libpthread.so.0 libGL.so.1"<br />
export __GL_THREADED_OPTIMIZATIONS=0<br />
export __GL_SYNC_TO_VBLANK=1<br />
export __GL_YIELD="NOTHING"<br />
export CSMT=enabled<br />
<br />
Make sure you have disabled ''StrictDrawOrdering'' from ''Tools/General''.<br />
<br />
If you want to compile it yourself from [https://github.com/stefand/wine Github] or you use the [https://aur.archlinux.org/packages/wine-d3dstream-git/ AUR] package instead.<br />
<br />
==== Further Information ====<br />
<br />
[http://www.phoronix.com/forums/showthread.php?93967-Wine-s-Big-Command-Stream-D3D-Patch-Set-Updated/page3&s=7775d7c3d4fa698089d5492bb7b1a435 Phoronix Forum discussion] with the CSMT developer Stefan Dösinger<br />
<br />
[http://wiki.winehq.org/FOSDEM2014?action=AttachFile&do=get&target=d3d-drivers.odp FOSDEM2014 CSMT presentation] of CSMT with benchmarks<br />
<br />
[https://www.youtube.com/playlist?list=PL0P2a_sII2eTd8uq-azTNpQjiFLqBhDjg Here] you find some game videos running with CSMT enabled<br />
<br />
=== Changing the language ===<br />
<br />
Some programs may not offer a language selection, they will guess the desired language upon the sytem locales. Wine will transfer the current environment (including the locales) to the application, so it should work out of the box. If you want to force a program to run in a specific locale (which is fully [[Locale|generated]] on your system), you can call Wine with the following setting:<br />
<br />
LC_ALL=xx_XX.encoding wine /my/program<br />
<br />
For instance<br />
<br />
LC_ALL=it_IT.UTF-8 wine /my/program<br />
<br />
=== Installing Microsoft Office 2010 ===<br />
{{Note|Microsoft Office 2013 does not run at all.}}<br />
<br />
Microsoft Office 2010 works without any problems (tested with Microsoft Office Home and Student 2010, Wine 1.5.27 and 1.7.5). Activation over Internet also works.<br />
<br />
Start by installing {{pkg|wine-mono}}, {{pkg|wine_gecko}}, {{pkg|samba}}, and {{pkg|lib32-libxml2}}.<br />
<br />
Proceed with launching the installer:<br />
$ export WINEPREFIX=.wine # any path to a writable folder on your home directory will do<br />
$ export WINEARCH="win32"<br />
$ wine /path/to/office_cd/setup.exe<br />
You could also put the above exports into your {{ic|.bashrc}}.<br />
<br />
Once installation completes, open Word or Excel to activate over the Internet. Once activated, close the application. Then run {{ic|winecfg}}, and set '''riched20''' (under libraries) to '''(native,builtin)'''. This will enable Powerpoint to work.<br />
<br />
For additional info, see the [http://appdb.winehq.org/appview.php?iVersionId=4992 WineHQ] article.<br />
<br />
{{note|If the activation over internet doesn't work and you want to activate by phone, be sure '''riched20''' is set to ''(native,builtin)'' in order to see the drop-down list of countries.}}<br />
<br />
{{note|{{Pkg|playonlinux}} provides custom installer scripts that make the installation of Office 2003, 2007 and 2010 an ease. You just have to provide the setup.exe or ISO and the installer will guide you seamlessly through the installation procedure. You do not have to deal with the underlying Wine at all.}}<br />
<br />
=== Proper mounting of optical media images ===<br />
<br />
Some applications will check for the optical media to be in drive. They may check for data only, in which case it might be enough to configure the corresponding path as being a CD-ROM drive in {{ic|winecfg}}.<br />
However, other applications will look for a media name and/or a serial number, in which case the image has to be mounted with these special properties.<br />
<br />
Some virtual drive tools do not handle these metadata, like fuse-based virtual drives (Acetoneiso for instance). CDEmu will handle it correctly.<br />
<br />
=== Burning optical media ===<br />
<br />
To burn CDs or DVDs, you will need to load the {{ic|sg}} [[kernel modules|kernel module]].<br />
<br />
=== OpenGL modes ===<br />
<br />
Many games have an OpenGL mode which ''may'' perform better than their default DirectX mode. While the steps to enable OpenGL rendering is ''application specific'', many games accept the {{Ic|-opengl}} parameter.<br />
$ wine /path/to/3d_game.exe -opengl<br />
<br />
You should of course refer to your application's documentation and Wine's [http://appdb.winehq.org AppDB] for such application specific information.<br />
<br />
=== Using Wine as an interpreter for Win16/Win32 binaries ===<br />
<br />
It is also possible to tell the kernel to use wine as an interpreter for all Win16/Win32 binaries:<br />
echo ':DOSWin:M::MZ::/usr/bin/wine:' > /proc/sys/fs/binfmt_misc/register<br />
<br />
To make the setting permanent, create a {{ic|/etc/binfmt.d/wine.conf}} file with the following content:<br />
# Start WINE on Windows executables<br />
:DOSWin:M::MZ::/usr/bin/wine:<br />
<br />
systemd automatically mounts the {{ic|/proc/sys/fs/binfmt_misc}} filesystem using {{ic|proc-sys-fs-binfmt_misc.mount}} (and automount) and runs the {{ic|systemd-binfmt.service}} to load your settings.<br />
<br />
Try it out by running a Windows program:<br />
chmod +x exefile.exe<br />
./exefile.exe<br />
<br />
If all went well, exefile.exe should run.<br />
<br />
=== Wineconsole ===<br />
<br />
Often you may need to run {{ic|.exe}}s to patch game files, for example a widescreen mod for an old game, and running the {{ic|.exe}} normally through wine might yield nothing happening. In this case, you can open a terminal and run the following command:<br />
<br />
$ wineconsole cmd<br />
<br />
Then navigate to the directory and run the {{ic|.exe}} file from there.<br />
<br />
=== Winetricks ===<br />
<br />
[http://wiki.winehq.org/winetricks Winetricks] is a script to allow one to install base requirements needed to run Windows programs. Installable components include DirectX 9.x, MSXML (required by Microsoft Office 2007 and Internet Explorer), Visual Runtime libraries and many more.<br />
<br />
You can install {{pkg|winetricks}} via [[pacman]] or use the {{AUR|winetricks-svn}} package available in the [[AUR]]. Then run it with:<br />
$ winetricks<br />
<br />
=== Installing .NET framework 4.0 ===<br />
First create a new 32bit wine prefix if you are on a 64bit system.<br />
$ WINEARCH=win32 WINEPREFIX=~/win32 winecfg<br />
<br />
Then install the following packages using winetricks<br />
$ WINEARCH=win32 WINEPREFIX=~/win32 winetricks -q msxml3 dotnet40 corefonts<br />
<br />
== Third-party interfaces ==<br />
<br />
These have their own sites, and are ''not supported'' in the official Wine forums/bugzilla.<br />
<br />
=== CrossOver ===<br />
<br />
[http://www.codeweavers.com/about/ CrossOver] Has its own [[CrossOver|wiki page]].<br />
<br />
=== PlayOnLinux/PlayOnMac ===<br />
<br />
[http://www.playonlinux.com/ PlayOnLinux] is a graphical Windows and DOS program manager. It contains scripts to assist the configuration and running of programs, it can manage multiple Wine versions and even use a specific version for each executable (eg. because of regressions). If you need to know which Wine version works best for a certain game, try the [http://appdb.winehq.org/ Wine Application Database]. You can find the {{Pkg|playonlinux}} package in [[community]].<br />
<br />
=== PyWinery ===<br />
<br />
[http://code.google.com/p/pywinery/ PyWinery] is a graphical and simple wine-prefix manager which allows you to launch apps and manage configuration of separate prefixes, also have a button to open winetricks in the same prefix, to open prefix dir, {{ic|winecfg}}, application uninstaller and wineDOS. You can install [https://aur.archlinux.org/packages.php?ID=48382 PyWinery from AUR]. It is especially useful for having differents settings like DirectX games, office, programming, etc, and choose which prefix to use before you open an application or file.<br />
<br />
It's recommended using winetricks by default to open '''.exe''' files, so you can choose between any wine configuration you have.<br />
<br />
=== Q4wine ===<br />
<br />
[http://q4wine.brezblock.org.ua/ Q4Wine] is a graphical wine-prefix manager which allows you to manage configuration of prefixes. Notably it allows exporting QT themes into the wine configuration so that they can integrate nicely. You can find the {{Pkg|q4wine}} package in [[multilib]].<br />
<br />
== See also ==<br />
<br />
* [http://www.winehq.com/ Official Wine website]<br />
* [http://appdb.winehq.org/ Wine application database]<br />
* [http://linuxgamingtoday.wordpress.com/2008/02/16/quick-tips-to-speed-up-your-gaming-in-wine/ Advanced configuring your gfx card and OpenGL settings on wine; Speed up wine]<br />
* [http://wiki.gotux.net/code:perl:fileinfo FileInfo] - Find Win32 PE/COFF headers in EXE/DLL/OCX files under linux/unix environment.<br />
* [https://wiki.gentoo.org/wiki/Wine Gentoo's Wine Wiki Page]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=FFmpeg&diff=307582FFmpeg2014-03-28T23:18:07Z<p>Bluerider: /* x264 lossless */</p>
<hr />
<div>[[Category:Audio/Video]]<br />
From the project [http://www.ffmpeg.org/ home page]:<br />
:''FFmpeg is a complete, cross-platform solution to record, convert and stream audio and video. It includes libavcodec - the leading audio/video codec library.''<br />
<br />
== Package installation ==<br />
<br />
Various flavors and related projects can be [[pacman|installed]] from the [[official repositories]] and the [[AUR]]:<br />
<br />
* {{Pkg|ffmpeg}} – official package<br />
<br />
Notable variants:<br />
<br />
* {{AUR|ffmpeg-git}} – development version<br />
* {{AUR|ffmpeg-full}} – built with as much optional features enabled as possible<br />
<br />
Forks:<br />
<br />
* {{AUR|ffmbc}} – targeted for broadcasting usage<br />
<!-- Why is highlighting the differance in binary name useful? Needs to be replaced with a meaningful description of libav. --><br />
* {{AUR|libav-git}} – the binary it provides is called {{ic|avconv}} instead of {{ic|ffmpeg}}<br />
<br />
== Encoding examples ==<br />
<br />
=== Screen cast ===<br />
<br />
FFmpeg includes the [http://www.ffmpeg.org/ffmpeg-devices.html#x11grab x11grab] and [http://www.ffmpeg.org/ffmpeg-devices.html#alsa-1 ALSA] virtual devices that enable capturing the entire user display and audio input.<br />
<br />
First create {{ic|test.mkv}} with lossless encoding:<br />
<br />
$ ffmpeg -f x11grab -video_size 1920x1080 -i $DISPLAY -f alsa -i default -c:v ffvhuff -c:a flac test.mkv<br />
<br />
where {{ic|-video_size}} specifies the size of the area to capture. Check the FFmpeg manual for examples of how to change the screen or position of the capture area. Then you may process the MKV into a smaller [[Wikipedia:WebM|WebM]] file:<br />
<br />
$ ffmpeg -i test.mkv -c:v libvpx -c:a libvorbis -b:v 2000k -q:a 3 test.webm<br />
<br />
=== Recording webcam ===<br />
<br />
FFmpeg supports grabbing input from Video4Linux2 devices. The following command will record a video from the webcam, assuming that the webcam is correctly recognized under {{ic|/dev/video0}}:<br />
<br />
$ ffmpeg -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
The above produces a silent video. It is also possible to include audio sources from a microphone. The following command will include a stream from the default [[Advanced Linux Sound Architecture|ALSA]] recording device into the video:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
To use [[PulseAudio]] with an ALSA backend:<br />
<br />
$ ffmpeg -f alsa -i pulse -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
For a higher quality capture, try encoding the output using higher quality codecs:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 -acodec flac \<br />
-vcodec libx264 ''output''.mkv<br />
<br />
=== VOB to any container ===<br />
<br />
Concatenate the desired [[Wikipedia:VOB|VOB]] files into a single stream and mux them to MPEG-2:<br />
$ cat f0.VOB f1.VOB f2.VOB | ffmpeg -i - out.mp2<br />
<br />
=== x264 lossless ===<br />
<br />
The ''ultrafast'' preset will provide the fastest encoding and is useful for quick capturing (such as screencasting):<br />
$ ffmpeg -i input -vcodec libx264 -preset ultrafast -qp 0 -acodec copy ''output.mkv''<br />
On the opposite end of the preset spectrum is ''veryslow'' and will encode slower than ''ultrafast'' but provide a smaller output file size:<br />
$ ffmpeg -i input -vcodec libx264 -preset veryslow -qp 0 -acodec copy ''output.mkv''<br />
Both examples will provide the same quality output.<br />
<br />
=== x265 ===<br />
<br />
In encoding x265 files, you need to specify the aspect ratio of the file via {{ic|-aspect <width:height>}}. Example :<br />
{{bc|<nowiki> ffmpeg -i test.mp4 -c:v hevc -aspect 1920:1080 test_hevc.mp4</nowiki>}}<br />
<br />
=== Single-pass MPEG-2 (near lossless) ===<br />
<br />
Allow FFmpeg to automatically set DVD standardized parameters. Encode to DVD [[Wikipedia:MPEG-2|MPEG-2]] at ~30 FPS:<br />
<br />
$ ffmpeg -i ''video''.VOB -target ntsc-dvd -q:a 0 -q:v 0 ''output''.mpg<br />
<br />
Encode to DVD MPEG-2 at ~24 FPS:<br />
<br />
$ ffmpeg -i ''video''.VOB -target film-dvd -q:a 0 -q:v 0 ''output''.mpg<br />
<br />
=== x264: constant rate factor ===<br />
<br />
Used when you want a specific quality output. General usage is to use the highest {{ic|-crf}} value that still provides an acceptable quality. Lower values are higher quality; 0 is lossless, 18 is visually lossless, and 23 is the default value. A sane range is between 18 and 28. Use the slowest {{ic|-preset}} you have patience for. See the [https://ffmpeg.org/trac/ffmpeg/wiki/x264EncodingGuide x264 Encoding Guide] for more information.<br />
$ ffmpeg -i ''video'' -vcodec libx264 -preset slow -crf 22 -acodec libmp3lame -aq 4 ''output''.mkv<br />
{{ic|-tune}} option can be used to [http://forum.doom9.org/showthread.php?t=149394 match the type and content of the of media being encoded].<br />
<br />
=== YouTube ===<br />
<br />
FFmpeg is very useful to encode videos and strip their size before you upload them on YouTube. The following single line of code takes an input file and outputs a mkv container. <br />
<br />
$ ffmpeg -i ''video'' -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy ''output''.mkv<br />
<br />
For more information see the [https://bbs.archlinux.org/viewtopic.php?pid=1200667#p1200667 forums]. You can also create a custom alias {{ic|ytconvert}} which takes the name of the input file as first argument and the name of the .mkv container as second argument. To do so add the following to your {{ic|~/.bashrc}}:<br />
<br />
{{bc|<nowiki><br />
youtubeConvert(){<br />
ffmpeg -i $1 -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy $2.mkv<br />
}<br />
alias ytconvert=youtubeConvert<br />
</nowiki>}}<br />
See also [https://bbs.archlinux.org/viewtopic.php?pid=1200542#p1200542 Arch Linux forum thread].<br />
<br />
=== Two-pass x264 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are recorded during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec libx264 -pass 1 -preset veryslow \<br />
-threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 -f rawvideo -y /dev/null<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.mkv}}):<br />
$ ffmpeg -i ''video''.VOB -acodec libvo-aacenc -ab 256k -ar 96000 -vcodec libx264 \<br />
-pass 2 -preset veryslow -threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 ''video''.mkv<br />
<br />
{{Tip|If you receive {{ic|Unknown encoder 'libvo-aacenc'}} error (given the fact that your ffmpeg is compiled with libvo-aacenc enabled), you may want to try {{ic|-acodec libvo_aacenc}}, an underscore instead of hyphen.}}<br />
<br />
=== Two-pass MPEG-4 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are logged during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec mpeg4 -pass 1 -mbd 2 -trellis 2 -flags +cbp+mv0 \<br />
-pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 -b 3000k \<br />
-f rawvideo -y /dev/null<br />
<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.avi}}):<br />
$ ffmpeg -i ''video''.VOB -acodec copy -vcodec mpeg4 -vtag DX50 -pass 2 -mbd 2 -trellis 2 \<br />
-flags +cbp+mv0 -pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 \<br />
-b 3000k ''video''.avi<br />
* Introducing {{ic|threads}}={{ic|n}}>{{ic|1}} for {{ic|-vcodec mpeg4}} may skew the effects of [[Wikipedia:Motion_estimation|motion estimation]] and lead to [http://ffmpeg.org/faq.html#Why-do-I-see-a-slight-quality-degradation-with-multithreaded-MPEG_002a-encoding_003f reduced video quality] and compression efficiency.<br />
* The two-pass MPEG-4 example above also supports output to the [[Wikipedia:MPEG-4_Part_14|MP4]] container (replace {{ic|.avi}} with {{ic|.mp4}}).<br />
<br />
==== Determining bitrates with fixed output file sizes ====<br />
<br />
* (Desired File Size in MB - Audio File Size in MB) '''x''' 8192 kb/MB '''/''' Length of Media in Seconds (s) '''=''' [[Wikipedia:Bitrate|Bitrate]] in kb/s<br />
:* (3900 MB - 275 MB) = 3625 MB '''x''' 8192 kb/MB '''/''' 8830 s = 3363 kb/s required to achieve an approximate total output file size of 3900 MB<br />
<br />
=== Subtitles ===<br />
<br />
==== Extracting ====<br />
<br />
Subtitles embedded in container files, such as MPEG-2 and Matroska, can be extracted and converted into SRT, SSA, among other subtitle formats.<br />
<br />
* Inspect a file to determine if it contains a subtitle stream:<br />
<br />
{{hc|$ ffprobe foo.mkv|<br />
...<br />
Stream #0:0(und): Video: h264 (High), yuv420p, 1920x800 [SAR 1:1 DAR 12:5], 23.98 fps, 23.98 tbr, 1k tbn, 47.95 tbc (default)<br />
Metadata:<br />
CREATION_TIME : 2012-06-05 05:04:15<br />
LANGUAGE : und<br />
Stream #0:1(und): Audio: aac, 44100 Hz, stereo, fltp (default)<br />
Metadata:<br />
CREATION_TIME : 2012-06-05 05:10:34<br />
LANGUAGE : und<br />
HANDLER_NAME : GPAC ISO Audio Handler<br />
'''Stream #0:2: Subtitle: ssa (default)}}<br />
<br />
* {{ic|foo.mkv}} has an embedded SSA subtitle which can be extracted into an independent file:<br />
<br />
$ ffmpeg -i foo.mkv foo.ssa<br />
<br />
==== Hardsubbing ====<br />
<br />
(instructions based on an [http://trac.ffmpeg.org/wiki/How%20to%20burn%20subtitles%20into%20the%20video FFmpeg wiki article])<br />
<br />
[[Wikipedia:Hardsub|Hardsubbing]] entails merging subtitles with the video. Hardsubs can't be disabled, nor language switched.<br />
<br />
* Overlay {{ic|foo.mpg}} with the subtitles in {{ic|foo.ssa}}:<br />
<br />
$ ffmpeg -i foo.mpg -c copy -vf subtitles=foo.ssa out.mpg<br />
<br />
=== Volume gain ===<br />
<br />
Change the audio volume in multiples of 256 where '''256 = 100%''' (normal) volume. Additional values such as 400 are also valid options. <br />
-vol 256 = 100%<br />
-vol 512 = 200%<br />
-vol 768 = 300%<br />
-vol 1024 = 400%<br />
-vol 2048 = 800%<br />
<br />
To double the volume '''(512 = 200%)''' of an [[Wikipedia:Mp3|MP3]] file:<br />
$ ffmpeg -i ''file''.mp3 -vol 512 ''louder file''.mp3<br />
<br />
To quadruple the volume '''(1024 = 400%)''' of an [[Wikipedia:Ogg|Ogg]] file:<br />
$ ffmpeg -i ''file''.ogg -vol 1024 ''louder file''.ogg<br />
<br />
Note that gain metadata is only written to the output file. Unlike mp3gain or ogggain, the source sound file is untouched.<br />
<br />
=== Extracting audio ===<br />
<br />
{{hc|$ ffmpeg -i ''video''.mpg|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: ac3, 48000 Hz, stereo, s16, 384 kb/s<br />
Stream #0.2: Audio: ac3, 48000 Hz, 5.1, s16, 448 kb/s<br />
Stream #0.3: Audio: dts, 48000 Hz, 5.1 768 kb/s<br />
...<br />
}}<br />
<br />
Extract the first ({{ic|-map 0:1}}) [[Wikipedia:Dolby_Digital|AC-3]] encoded audio stream exactly as it was multiplexed into the file: <br />
$ ffmpeg -i ''video''.mpg -map 0:1 -acodec copy -vn ''video''.ac3<br />
Convert the third ({{ic|-map 0:3}}) [[Wikipedia:DTS_(sound_system)|DTS]] audio stream to an [[Wikipedia:Advanced_Audio_Coding|AAC]] file with a bitrate of 192 kb/s and a [[Wikipedia:Sampling_rate|sampling rate]] of 96000 Hz:<br />
$ ffmpeg -i ''video''.mpg -map 0:3 -acodec libvo-aacenc -ab 192k -ar 96000 -vn ''output''.aac<br />
{{ic|-vn}} disables the processing of the video stream.<br />
<br />
Extract audio stream with certain time interval: <br />
$ ffmpeg -ss 00:01:25 -t 00:00:05 -i ''video''.mpg -map 0:1 -acodec copy -vn ''output''.ac3<br />
{{ic|-ss}} specifies the start point, and {{ic|-t}} specifies the duration.<br />
<br />
=== Stripping audio ===<br />
<br />
# Copy the first video stream ({{ic|-map 0:0}}) along with the second AC-3 audio stream ({{ic|-map 0:2}}).<br />
# Convert the AC-3 audio stream to two-channel MP3 with a bitrate of 128 kb/s and a sampling rate of 48000 Hz.<br />
$ ffmpeg -i ''video''.mpg -map 0:0 -map 0:2 -vcodec copy -acodec libmp3lame \<br />
-ab 128k -ar 48000 -ac 2 ''video''.mkv<br />
<br />
{{hc|$ ffmpeg -i ''video''.mkv|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: mp3, 48000 Hz, stereo, s16, 128 kb/s<br />
}}<br />
<br />
{{Note|Removing undesired audio streams allows for additional bits to be allocated towards improving video quality.}}<br />
<br />
== Preset files ==<br />
<br />
Populate {{ic|~/.ffmpeg}} with the default [http://ffmpeg.org/ffmpeg-doc.html#SEC13 preset files]: <br />
<br />
$ cp -iR /usr/share/ffmpeg ~/.ffmpeg<br />
<br />
Create new and/or modify the default preset files:<br />
<br />
{{hc|~/.ffmpeg/libavcodec-vhq.ffpreset|2=<br />
vtag=DX50<br />
mbd=2<br />
trellis=2<br />
flags=+cbp+mv0<br />
pre_dia_size=4<br />
dia_size=4<br />
precmp=4<br />
cmp=4<br />
subcmp=4<br />
preme=2<br />
qns=2<br />
}}<br />
<br />
=== Using preset files ===<br />
<br />
Enable the {{ic|-vpre}} option after declaring the desired {{ic|-vcodec}}<br />
<br />
==== libavcodec-vhq.ffpreset ====<br />
<br />
* {{ic|libavcodec}} '''=''' Name of the vcodec/acodec<br />
* {{ic|vhq}} '''=''' Name of specific preset to be called out<br />
* {{ic|ffpreset}} '''=''' FFmpeg preset filetype suffix <br />
<br />
===== Two-pass MPEG-4 (very high quality) =====<br />
<br />
First pass of a multipass (bitrate) ratecontrol transcode:<br />
$ ffmpeg -i ''video''.mpg -an -vcodec mpeg4 -pass 1 -vpre vhq -f rawvideo -y /dev/null<br />
Ratecontrol based on the video statistics logged from the first pass: <br />
$ ffmpeg -i ''video''.mpg -acodec libvorbis -aq 8 -ar 48000 -vcodec mpeg4 \<br />
-pass 2 -vpre vhq -b 3000k ''output''.mp4<br />
<br />
* '''libvorbis quality settings (VBR)'''<br />
:* {{ic|-aq 4}} = 128 kb/s<br />
:* {{ic|-aq 5}} = 160 kb/s<br />
:* {{ic|-aq 6}} = 192 kb/s<br />
:* {{ic|-aq 7}} = 224 kb/s<br />
:* {{ic|-aq 8}} = 256 kb/s<br />
<br />
* [http://www.geocities.jp/aoyoume/aotuv/ aoTuV] is generally preferred over [http://vorbis.com/ libvorbis] provided by [http://www.xiph.org/ Xiph.Org] and is provided by [https://aur.archlinux.org/packages.php?ID=6155 libvorbis-aotuv] in the [[AUR]].<br />
<br />
== Package removal ==<br />
<br />
[[pacman]] will not [[Pacman#Removing_packages|remove]] configuration files outside of the defaults that were created during package installation. This includes user-created preset files.<br />
<br />
== See also ==<br />
<br />
* [http://mewiki.project357.com/wiki/X264_Settings x264 Settings] - MeWiki documentation<br />
* [http://ffmpeg.org/ffmpeg-doc.html FFmpeg documentation] - official documentation<br />
* [http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-x264.html Encoding with the x264 codec] - MEncoder documentation<br />
* [http://avidemux.org/admWiki/doku.php?id=tutorial:h.264 H.264 encoding guide] - Avidemux wiki<br />
* [http://howto-pages.org/ffmpeg/ Using FFmpeg] - Linux how to pages<br />
* [http://ffmpeg.org/general.html#Supported-File-Formats-and-Codecs List] of supported audio and video streams</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Arch_Security_Team&diff=305382Arch Security Team2014-03-17T22:36:06Z<p>Bluerider: /* Package Categories and Team Members */</p>
<hr />
<div>[[Category:Arch development]]<br />
[[Category:Security]]<br />
{{Stub|For now, this page is a draft to construct something according to https://mailman.archlinux.org/pipermail/arch-dev-public/2014-March/025952.html}}<br />
<br />
{{Related articles start}}<br />
{{Related|Security Task Force}}<br />
{{Related|CVE-2014}}<br />
{{Related articles end}}<br />
<br />
<br />
This article introduces the Arch CVE Monitoring Team (ACMT) and describes best practices for contributing. <br />
<br />
<br />
==Introduction==<br />
Arch Linux is a community-driven distribution. It relies upon the efforts of volunteers to maintain and improve the distribution itself and to support fellow community members. <br />
<br />
The importance of software security cannot be overstated. Today's society relies upon computer technology for everything from amusement to indispensable national and local infrastructure. Many rely upon Arch Linux to provide these. <br />
<br />
On March 9, 2014, Allan McRae [https://mailman.archlinux.org/pipermail/arch-dev-public/2014-March/025952.html called] upon our community to assist in securing Arch Linux by monitoring any and all relevant resources for announced [[Wikipedia:Common_Vulnerabilities_and_Exposures|Common Vulnerabilities and Exposures]] (CVE's). In contrast to security issues which can be fixed by updating, CVE's require patches to be backported. As such, Arch developers must be notified that this is the case. This is where the ACMT comes in.<br />
<br />
The ACMT should embody the efforts of the "security-conscious" part of the Arch users population. Server owners, maintainers of workstations in production environments as well as concerned personal users would gain the benefit of relatively prompt security updates. The ACMT should help alleviate two important problems: finding bugs, communicating with developers. <br />
<br />
The Team is a volunteer maintained service. Volunteers are welcome to help identify and notify packages with security vulnerabilities.<br />
<br />
==Joining the ACMT==<br />
Joining is as simple as helping. Firstly, join the [https://mailman.archlinux.org/mailman/listinfo/arch-security Arch Security mailing list] and/or IRC chan #archlinux-security. Secondly, consider the area where you'd like to help. It would be ideal to have team members' labor divided across the software ecosystem as equally as possible. This helps the Team to quickly and efficiently find and report CVE's. Software categories are listed [[Arch_CVE_Monitoring_Team#Package_Categories_and_Team_Members|below]]. However, it is not required that those who wish to volunteer restrict their monitoring in any way. "Global" and multiple-category volunteers are needed and encouraged. <br />
<br />
It is recommended that interested parties please consider monitoring those categories for which there are fewer volunteers. However, it is fully recognized that volunteers contribute best in areas in which they're most interested. Please consider both of these factors when selecting where your primary efforts will be placed. However, please note that it is not required that you restrict your monitoring to any one particular category. ''The goal of the ACMT is to simply keep Arch Linux secure. Any and all efforts are more than welcome and unreservedly appreciated.''<br />
<br />
If you would like to join the Team, please edit this page to include your name in the [[Arch_CVE_Monitoring_Team#Package_Categories_and_Team_Members|Package Categories and Team Members]] section below. Please place your name beneath the package category for which you will be monitoring. If you do not care to monitor specific categories and you would like to contribute any and all, please place your name in the "Global" category. ''These options are not mutually exclusive.''<br />
<br />
==Participation Guidelines==<br />
<br />
ACMT monitors all packages within the following repositories:<br />
* ''core''<br />
* ''extra''<br />
* ''community''<br />
<br />
Follow mailing lists (both development and user), security advisories (if any) and bug trackers on a regular basis. A few resources are listed below. You will quickly learn the different kind of vulnerabilities if you are unfamiliar. For those who will monitor languages, it is ideal to be able to operate at both the interpreter level (often written in C) and the language level. <br />
<br />
Everyone should file bug reports. If you are unsure how to file a bug report, please refer to the [[Reporting_Bug_Guidelines| Bug Reporting Guidelines]]. <br />
<br />
People with the technical ability are encouraged to not only file bug reports about CVE's, but write/comment patches, test, communicate with upstream developers, among other things.<br />
<br />
==Procedure==<br />
A critical security exploit has been found in a software package within the Arch Linux official repositories. An ACMT member picks up this information from some mailing list he/she is following. If upstream released a new version that corrects the issue, the ACMT member should flag the package out-of-date and post pertinent information to the arch-security mailing list, which will likely get the attention of the developers. If, on the other hand, upstream releases only a patch, the ACMT member should file a bug report.<br />
<br />
===Bug Report Template===<br />
<br />
{{bc|<br />
Title : [<pkg-name>] security patch for <CVE-id><br />
Description:<br />
Quick description of the issue (or copy/paste from oss-sec, upstream bug reports, etc.)<br />
upstream bug report [0]<br />
<br />
Resolution:<br />
patch [1] <br />
<br />
Resources:<br />
[0] links to upstream bug report<br />
[1] link to patch<br />
}}<br />
<br />
The criticality of the bug report should be set to either Critical or High, depending on the severity of the issue.<br />
Some updates will be much more critical than others. However, updates are always recommended in the case of any vulnerability.<br />
<br />
==Resources==<br />
===RSS===<br />
;National Vulnerability Database (NVD)<br />
: All CVE vulnerabilites: http://nvd.nist.gov/download/nvd-rss.xml<br />
: All fully analyzed CVE vulnerabilities: http://nvd.nist.gov/download/nvd-rss-analyzed.xml<br />
<br />
===Mailing Lists===<br />
;oss-sec: main list dealing with security of free software, a lot of CVE attributions happen here, required if you wish to follow security news.<br><br />
:info: http://oss-security.openwall.org/wiki/mailing-lists/oss-security<br />
:subscribe: oss-security-subscribe(at)lists.openwall.com<br />
:archive: http://www.openwall.com/lists/oss-security/<br />
<br />
;bugtraq:a full disclosure moderated mailing list (noisy)<br />
:info: http://www.securityfocus.com/archive/1/description<br />
:subscribe: bugtraq-subscribe(at)securityfocus.com<br />
<br />
;full-disclosure: another full-disclosure mailing-list (noisy)<br />
:info: http://lists.grok.org.uk/full-disclosure-charter.html<br />
:subscribe: full-disclosure-request(at)lists.grok.org.uk<br />
<br />
Also consider following the mailing lists for specific packages, such as LibreOffice, X.org, Puppetlabs, ISC, etc.<br />
<br />
===Other Distributions===<br />
Resources of other distributions (to look for CVE, patch, comments etc.):<br />
;RedHat and Fedora:<br />
:rss advisories: https://admin.fedoraproject.org/updates/rss/rss2.0?type=security<br />
:CVE tracker: https://access.redhat.com/security/cve/<CVE-id><br />
:bug tracker: https://bugzilla.redhat.com/show_bug.cgi?id=<CVE-id><br />
<br />
;Ubuntu:<br />
:advisories: http://www.ubuntu.com/usn/atom.xml<br />
:CVE tracker: http://people.canonical.com/~ubuntu-security/cve/?cve=<CVE-id><br />
:database: https://code.launchpad.net/~ubuntu-security/ubuntu-cve-tracker/master<br />
<br />
;Debian:<br />
:CVE tracker: http://security-tracker.debian.org/tracker/<CVE-id><br />
:patch-tracker: http://patch-tracker.debian.org/<br />
:database: http://anonscm.debian.org/viewvc/secure-testing/data/<br />
<br />
;OpenSUSE:<br />
:CVE tracker: http://support.novell.com/security/cve/<CVE-id>.html<br />
<br />
===Other===<br />
;Mitre and NVD links for CVE's:<br />
:http://cve.mitre.org/cgi-bin/cvename.cgi?name=<CVE-id><br />
:http://web.nvd.nist.gov/view/vuln/detail?vulnId=<CVE-id><br />
<br />
NVD and Mitre do not necessarily fill their CVE entry immediately after attribution, so it's not always relevant for Arch. The CVE-id and the "Date Entry Created" fields do not have particular meaning. CVE are attributed by CVE Numbering Authorities (CNA), and each CNA obtain CVE blocks from Mitre when needed/asked, so the CVE ID is not linked to the attribution date. The "Date Entry Created" field often only indicates when the CVE block was given to the CNA, nothing more.<br />
<br />
;Linux Weekly News: LWN provides a daily notice of security updates for various distributions<br />
:http://lwn.net/headlines/newrss<br />
<br />
===More===<br />
For more resources, please see the OpenWall's [http://oss-security.openwall.org/wiki/ Open Source Software Security Wiki]. <br />
<br />
<br />
==Package Categories and Team Members==<br />
Below is a list of general package categories. Should you like, you are welcome to add a new category. Please remember the KISS philosophy when editing the list. <br />
<br />
*Global<br />
:Billy Wayne McCann<br />
:[Your Name Here]<br />
* Kernel<br />
:Mark Lee<br />
* Filesystems<br />
:[Your Name Here]<br />
* GNU userland<br />
:[[User:RbN|RbN]]<br />
* Xorg<br />
:[[User:RbN|RbN]]<br />
* Systemd<br />
:[[User:RbN|RbN]]<br />
* Perl and associated software<br />
:[Your Name Here]<br />
* Python and associated software<br />
:[Your Name Here]<br />
* Java and associated software<br />
:[Your Name Here]<br />
* Ruby and associated software<br />
:[Your Name Here]<br />
* Gtk/Gnome and associated software<br />
:[Your Name Here]<br />
* QT/KDE and associated software<br />
:Billy Wayne McCann (KDE)<br />
:[Your Name Here]<br />
* Various Windows Managers (please include which WM along with your name)<br />
:[Your Name Here]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Intel_graphics&diff=303565Intel graphics2014-03-08T05:31:44Z<p>Bluerider: /* Module-based Powersaving Options */</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X Server]]<br />
[[cs:Intel]]<br />
[[de:Intel]]<br />
[[es:Intel]]<br />
[[fr:Intel]]<br />
[[hu:Intel]]<br />
[[it:Intel]]<br />
[[ja:Intel Graphics]]<br />
[[pl:Intel]]<br />
[[ru:Intel]]<br />
[[zh-CN:Intel Graphics]]<br />
[[zh-TW:Intel]]<br />
{{Related articles start}}<br />
{{Related|Intel GMA3600}}<br />
{{Related|Poulsbo}}<br />
{{Related|Xorg}}<br />
{{Related articles end}}<br />
<br />
Since Intel provides and supports open source drivers, Intel graphics are now essentially plug-and-play.<br />
<br />
For a comprehensive list of Intel GPU models and corresponding chipsets and CPUs, see [[Wikipedia:Comparison of Intel graphics processing units|this comparison on Wikipedia]].<br />
<br />
{{Note|PowerVR-based graphics ([[Poulsbo|GMA 500]] and [[Intel GMA3600|GMA 3600]] series) are not supported by open source drivers.}}<br />
<br />
== Installation ==<br />
<br />
Prerequisite: [[Xorg]].<br />
<br />
[[pacman|Install]] the {{Pkg|xf86-video-intel}} package from the [[official repositories]]. It provides the DDX driver for 2D acceleration and it pulls in {{Pkg|intel-dri}} as a dependency, providing the DRI driver for 3D acceleration.<br />
<br />
For 32-bit 3D support on x86_64, install {{Pkg|lib32-intel-dri}} from the [[multilib]] repository.<br />
<br />
Hardware accelerated video decoding/encoding on older GPUs is provided by the [[XvMC]] driver which is included with the DDX driver. For newer GPUs install the [[VA-API]] driver provided by the {{Pkg|libva-intel-driver}} package.<br />
<br />
== Configuration ==<br />
<br />
There is no need for any kind of configuration to get X.Org running (an {{ic|xorg.conf}} is not needed, but needs to be configured correctly if present).<br />
<br />
For the list of options, type {{ic|man intel}}.<br />
<br />
== KMS (Kernel Mode Setting) ==<br />
<br />
{{Tip|If you have problems with the resolution, check [[Kernel_Mode_Setting#Forcing_modes_and_EDID|this page]].}}<br />
<br />
[[KMS]] is required in order to run X and a desktop environment such as [[GNOME]], [[KDE]], [[Xfce]], [[LXDE]], etc. KMS is supported by Intel chipsets that use the i915 DRM driver and is enabled by default as of kernel v2.6.32. Versions 2.10 and newer of the {{Pkg|xf86-video-intel}} driver no longer support UMS (except for the very old 810 chipset family), making the use of KMS mandatory<sup>[https://www.archlinux.org/news/484/]</sup>. KMS is typically initialized after the kernel is bootstrapped. It is possible, however, to enable KMS during bootstrap itself, allowing the entire boot process to run at the native resolution.<br />
<br />
{{Note|Users '''must''' remove any deprecated references to {{ic|vga}} or {{ic|nomodeset}} from boot configuration.}}<br />
<br />
To proceed, add the {{ic|i915}} module to the {{ic|MODULES}} line in {{ic|/etc/mkinitcpio.conf}}:<br />
<br />
MODULES="'''i915'''"<br />
<br />
If you are using a custom EDID file, you should embed it into initramfs as well:<br />
<br />
{{hc|/etc/mkinitcpio.conf|<br />
2=FILES="/lib/firmware/edid/your_edid.bin"}}<br />
<br />
Now, regenerate the initramfs:<br />
<br />
# mkinitcpio -p linux<br />
<br />
and reboot the system. Everything should work now.<br />
<br />
== Module-based Powersaving Options ==<br />
<br />
The {{ic|i915}} kernel module allows for configuration via [[Kernel_modules#Setting_module_options|module options]]. Some of the module options impact power saving.<br />
<br />
To check which options are currently enabled; run {{bc|<nowiki># for i in /sys/module/i915/parameters/*;do echo ${i}=`cat $i`;done</nowiki>}}<br />
<br />
A list of all options along with short descriptions and default values can be generated with the following command:<br />
<br />
$ modinfo i915 | grep parm<br />
<br />
The following set of options should be generally safe to enable:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|<nowiki><br />
options i915 i915_enable_rc6=7 i915_enable_fbc=1 lvds_downclock=1<br />
</nowiki>}}<br />
<br />
Framebuffer compression may be unreliable on old intel generations of intel GPUs (which exactly?). Check you system journal for messages like:<br />
kernel: drm: not enough stolen space for compressed buffer, disabling.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Choose acceleration method ===<br />
*UXA - (Unified Acceleration Architecture) is the mature backend that was introduced to support the GEM driver model.<br />
*SNA - (Sandybridge's New Acceleration) is the faster successor for hardware supporting it.<br />
<br />
The default method is SNA(as of 2013-08-05[https://projects.archlinux.org/svntogit/packages.git/commit/trunk?h=packages/xf86-video-intel&id=d03f5fb77df413017821f492aa81e5d68def7e48]), which is less stable but faster than UXA. Check benchmarks done by Phoronix [http://www.phoronix.com/scan.php?page=news_item&px=MTEzOTE]. These can be found [http://www.phoronix.com/scan.php?page=article&item=intel_glamor_first&num=1 here for Sandy Bridge] and [http://www.phoronix.com/scan.php?page=article&item=intel_ivy_glamor&num=1 here for Ivy Bridge]. UXA is still a solid option, if experiencing trouble with SNA.<br />
SNA can for example cause a black screen on leaving fullscreen of a Flash video.<br />
<br />
To use the old UXA method, create {{ic|/etc/X11/xorg.conf.d/20-intel.conf}} with the following content:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "AccelMethod" "uxa"<br />
EndSection}}<br />
<br />
One can also want to test the new Glamor mode which accelerates 2D graphics with OpenGL. To use it, create {{ic|/etc/X11/xorg.conf.d/20-intel.conf}} with the following content:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "AccelMethod" "glamor"<br />
EndSection}}<br />
<br />
=== Disable Vertical Synchronization (VSYNC) ===<br />
The intel-driver uses [http://www.intel.com/support/graphics/sb/CS-004527.htm Triple Buffering] for vertical synchronization, this allows for full performance and avoids tearing. To turn vertical synchronization off (e.g. for benchmarking) use this .drirc in your home directory:<br />
<br />
{{hc|~/.drirc|<br />
<device screen&#61;"0" driver&#61;"dri2"><br />
<application name&#61;"Default"><br />
<option name&#61;"vblank_mode" value&#61;"0"/><br />
</application><br />
</device>}}<br />
<br />
Don't use {{Pkg|driconf}} to create this file, it's buggy and will set the wrong driver.<br />
<br />
=== Setting scaling mode ===<br />
<br />
This can be useful for some full screen applications:<br />
<br />
$ xrandr --output LVDS1 --set PANEL_FITTING param<br />
<br />
where {{ic|param}} can be:<br />
<br />
* {{ic|center}}: resolution will be kept exactly as defined, no scaling will be made,<br />
* {{ic|full}}: scale the resolution so it uses the entire screen or<br />
* {{ic|full_aspect}}: scale the resolution to the maximum possible but keep the aspect ratio.<br />
<br />
If it does not work, try:<br />
<br />
$ xrandr --output LVDS1 --set "scaling mode" param<br />
<br />
where {{ic|param}} is one of {{ic|"Full"}}, {{ic|"Center"}} or {{ic|"Full aspect"}}.<br />
<br />
=== KMS Issue: console is limited to small area ===<br />
<br />
One of the low-resolution video ports may be enabled on boot which is causing the terminal to utilize a small area of the screen. To fix, explicitly disable the port with an i915 module setting with {{ic|1=video=SVIDEO-1:d}} in the kernel command line parameter in the bootloader. See [[Kernel parameters]] for more info.<br />
<br />
If that does not work, try disabling TV1 or VGA1 instead of SVIDEO-1.<br />
<br />
=== H.264 decoding on GMA 4500 ===<br />
<br />
The {{Pkg|libva-intel-driver}} package provides MPEG-2 decoding only for GMA 4500 series GPUs. The H.264 decoding support is maintained in a separated g45-h264 branch, which can be used by installing {{AUR|libva-driver-intel-g45-h264}} package, available in the [[Arch User Repository]]. Note however that this support is experimental and not currently in active development. Using the VA-API with this driver on a GMA 4500 series GPU will offload the CPU but may not result in as smooth a playback as non-accelerated playback. Tests using mplayer showed that using vaapi to play back an H.264 encoded 1080p video halved the CPU load (compared to the XV overlay) but resulted in very choppy playback, while 720p worked reasonably well [https://bbs.archlinux.org/viewtopic.php?id=150550]. This is echoed by other experiences [http://www.emmolution.org/?p=192&cpage=1#comment-12292].<br />
<br />
=== Setting gamma and brightness ===<br />
<br />
Intel offers no way to adjust these at the driver level. Luckily these can be set with {{ic|xgamma}} and {{ic|xrandr}}.<br />
<br />
Gamma can be set with:<br />
<br />
$ xgamma -gamma 1.0<br />
<br />
or:<br />
<br />
$ xrandr --output VGA1 --gamma 1.0:1.0:1.0<br />
<br />
Brightness can be set with:<br />
<br />
$ xrandr --output VGA1 --brightness 1.0<br />
<br />
== Troubleshooting ==<br />
<br />
=== Blank screen during boot, when "Loading modules" ===<br />
<br />
If using "late start" KMS and the screen goes blank when "Loading modules", it may help to add {{ic|i915}} and {{ic|intel_agp}} to the initramfs. See [[Intel#KMS (Kernel Mode Setting)|the above]] KMS section.<br />
<br />
Alternatively, appending the following [[Kernel parameters|kernel parameter]] seems to work as well:<br />
<br />
video=SVIDEO-1:d<br />
<br />
If you need to output to VGA then try this:<br />
<br />
video=VGA-1:1280x800<br />
<br />
=== Tear-free video ===<br />
<br />
{{tip|If using the [[GNOME]] desktop environment, a simpler and less performance-impacting fix can be found at [[GNOME#Tear-free_video_with_Intel_HD_Graphics]].}}<br />
<br />
The SNA acceleration method causes tearing for some people. To fix this, enable the {{ic|"Tearfree"}} option in the driver:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "TearFree" "true"<br />
EndSection}}<br />
<br />
See the [https://bugs.freedesktop.org/show_bug.cgi?id=37686 original bug report] for more info.<br />
<br />
{{Note|<br />
* This option may not work when {{ic|SwapbuffersWait}} is {{ic|false}}.<br />
* This option is problematic for applications that are very picky about vsync timing, like [[Wikipedia:Super Meat Boy|Super Meat Boy]].<br />
* This option does not work with UXA acceleration method, only with SNA.<br />
}}<br />
<br />
=== X freeze/crash with intel driver ===<br />
<br />
Some issues with X crashing, GPU hanging, or problems with X freezing, can be fixed by disabling the GPU usage with the {{ic|NoAccel}} option:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "NoAccel" "True"<br />
EndSection}}<br />
<br />
Alternatively, try to disable the 3D acceleration only with the {{ic|DRI}} option:<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "DRI" "False"<br />
EndSection}}<br />
<br />
If you experience crashes and have<br />
<br />
Option "TearFree" "true"<br />
Option "AccelMethod" "sna"<br />
<br />
in your config file, in most cases these can be fixed by adding<br />
<br />
i915.semaphores=1<br />
<br />
to your boot parameters.<br />
<br />
=== Adding undetected resolutions ===<br />
<br />
This issue is covered on the [[Xrandr#Adding_undetected_resolutions|Xrandr page]].<br />
<br />
=== Weathered colors (colorspace problem) ===<br />
<br />
{{Note|This problem is related to the changes in the kernel 3.9. This problem still remains in kernel 3.10}}<br />
Kernel 3.9 contains the Intel driver changes allowing easy RGB Limited range settings which can cause weathered colors in some cases. It is related to the new "Automatic" mode for the "Broadcast RGB" property.<br />
One can force mode e.g. {{ic|xrandr --output <HDMI> --set "Broadcast RGB" "Full"}} (replace {{ic|<HDMI>}} with the appropriate output device, verify by running {{ic|xrandr}}). You can add it into your {{ic |.xprofile}}, make it executable to run the command before it will start the graphical mode.<br />
{{Note|Some TVs can only display colors from 16-255 so setting to Full will cause color clipping in the 0-15 range so it's best to leave it at Automatic which will automatically detect whether it needs to compress the colorspace for your TV.}}<br />
<br />
Also there are other related problems which can be fixed editing GPU registers. More information can be found [http://lists.freedesktop.org/archives/intel-gfx/2012-April/016217.html] and [http://github.com/OpenELEC/OpenELEC.tv/commit/09109e9259eb051f34f771929b6a02635806404c].<br />
<br />
=== Backlight not fully adjusting, or adjusting at all, after resume. ===<br />
<br />
If you are using Intel graphics and have no control over your manufacturer suplied hotkeys for changing screen brightness, try booting the kernel parameter:<br />
acpi_backlight=vendor<br />
<br />
If that doesnt solve the problem, many folks have gotten mileage from either:<br />
acpi_osi=Linux<br />
or<br />
acpi_osi="!Windows 2012"<br />
either in addition to the earlier mentioned parameter, or on its own.<br />
<br />
As of kernel version 3.13, there is also this kernel command line parameter which has been proved useful for some users:<br />
video.use_native_backlight=1<br />
<br />
If neither of those solve your problem, you should edit/create {{ic|/etc/X11/xorg.conf.d/20-intel.conf}} with the following content:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "card0"<br />
Driver "intel"<br />
Option "Backlight" "intel_backlight"<br />
BusID "PCI:0:2:0"<br />
<br />
EndSection}}<br />
<br />
If you are using the SNA acceleration as mentioned above, create the file as follows:<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "card0"<br />
Driver "intel"<br />
Option "AccelMethod" "sna"<br />
Option "Backlight" "intel_backlight"<br />
BusID "PCI:0:2:0"<br />
<br />
EndSection}}<br />
<br />
=== Disabling frame buffer compression ===<br />
<br />
On some cards such as Intel Corporation Mobile 4 Series Chipsets, enabled and forced frame buffer compression results in endless error messages:<br />
<br />
$ dmesg |tail <br />
[ 2360.475430] [drm] not enough stolen space for compressed buffer (need 4325376 bytes), disabling<br />
[ 2360.475437] [drm] hint: you may be able to increase stolen memory size in the BIOS to avoid this<br />
<br />
The solution is to disable frame buffer compression which will slightly increase power consumption. In order to disable it add {{ic|i915.i915_enable_fbc&#61;0}} to the kernel line parameters. More information on the results of disabled compression can be found [http://zinc.canonical.com/~cking/power-benchmarking/background-colour-and-framebuffer-compression/results.txt here].<br />
<br />
=== Corruption/Unresponsiveness in Chromium and Firefox ===<br />
<br />
If you experience corruption or unresponsiveness in Chromium and/or Firefox [https://wiki.archlinux.org/index.php/Intel_Graphics#Choose_acceleration_method set the AccelMethod to "uxa"]<br />
<br />
== See also ==<br />
<br />
* https://01.org/linuxgraphics/documentation (includes a list of supported hardware)<br />
* [[KMS]] - Arch wiki article on kernel mode setting<br />
* [[Xrandr]] - Problems setting the resolution<br />
* Arch Linux forums: [https://bbs.archlinux.org/viewtopic.php?pid=522665#p522665 Intel 945GM, Xorg, Kernel - performance]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=XWiimote&diff=303277XWiimote2014-03-05T22:52:29Z<p>Bluerider: /* Infrared Sources */</p>
<hr />
<div>[[Category:Other hardware]]<br />
This article is about the Nintendo Wii Remote Linux kernel driver. This driver is part of upstream Linux since version 3.1. It is an easy to use drop-in replacement for the older user-space drivers like [[Wiimote|cwiid]].<br />
You can use your Wii Remote for all purposes with this driver, for instance as an [[Xorg|X]] input device or joystick controller for your Linux games.<br />
<br />
{{Note|The XWiimote tools are still experimental. Connecting and managing your Wii Remote works well and there is a driver to use the Wii Remote as X11 input, but extended features may still be missing.}}<br />
<br />
==Prerequisites==<br />
* [[Bluetooth]]<br />
* {{AUR|xwiimote}}<br />
* xwiimote kernel driver<br />
* Wii Remote hardware<br />
<br />
The most important piece required is [[Bluetooth]], this must already be configured and running without the help of this guide. This should be simple enough with any guide found on the [[Bluetooth|Internet]]. Most recent bluez package in Arch Linux includes the wiimote plugin. See [[#BlueZ does not include the wiimote plugin|Troubleshooting BlueZ]] to make BlueZ include the wiimote plugin.<br />
<br />
The user-space utilities are available in the [[AUR]]. You need the {{AUR|xwiimote}} package. There is also a git-package {{AUR|xwiimote-tools-git}} if you want the most recent revision.<br />
<br />
The kernel driver is part of upstream Linux since version 3.1. The module is called {{ic|hid-wiimote}}. If it is not available in your kernel, you need to compile the module yourself. The Arch Linux kernel includes it starting with version 3.1.<br />
<br />
Lastly you will need a Wii Remote, this can include (although, are not required) the Nunchuk and Classic Controller attachments.<br />
<br />
If your kernel does not include the {{ic|hid-wiimote}} module, you can enable it with {{ic|CONFIG_HID_WIIMOTE}}. The module needs {{ic|CONFIG_INPUT_FF_MEMLESS}}, {{ic|CONFIG_LEDS_CLASS}}, {{ic|CONFIG_POWER_SUPPLY}} and {{ic|CONFIG_BT_HIDP}} embedded in your kernel or as modules, previously loaded.<br />
Starting with kernel version 3.3 there is an additional config option {{ic|CONFIG_HID_WIIMOTE_EXT}} which is enabled by default. It controls whether wiimote extensions like Nunchuck and Classic Controller should be supported.<br />
<br />
==Connect the Wii Remote==<br />
<br />
You can connect to your Wii Remote like any other Bluetooth device. See the [[Bluetooth|Bluetooth article]] about information on pairing Bluetooth devices. The Wii Remote does not need special handling anymore. The BlueZ wiimote plugin handles all peculiarities in the background for you.<br />
<br />
The Wii Remote can be put into discoverable mode by pressing the red sync-button behind the battery cover on the back. The Wii Remote will stay in discoverable mode for 20s. You can also hold the 1+2 buttons to put the Wii Remote into discoverable state. However, the first method works more reliably!<br />
<br />
If you are asked for PIN input while bonding the devices, then your BlueZ bluetoothd daemon does not include the wiimote plugin. See [[#BlueZ does not include the wiimote plugin|Troubleshooting BlueZ]] for more information. If this does not help, you can still connect to your wiimote without pairing/bonding (i.e. not using authentication with a PIN). This should work with any BlueZ version. See [[#I cannot connect my wiimote|Troubleshooting Pairing]] if you still cannot connect your wiimote.<br />
<br />
==Device Handling==<br />
<br />
If your Wii Remote is connected, it will appear with several input devices inside {{ic|/dev/input/eventX}}. You can list all Wii Remotes with:<br />
<br />
$ ls /sys/bus/hid/devices<br />
<br />
Then you can get additional device details with:<br />
<br />
$ ls /sys/bus/hid/devices/<devid>/<br />
<br />
The default mapping for the input-keys of the Wii Remotes are not very useful. User-space applications exist that re-map the Wii Remote input to more useful keys/actions [http://github.com/dvdhrm/xwiimote] - available in AUR {{AUR|xwiimote}}. If you installed this package you can test your connected Wii Remotes with the {{ic|xwiishow}} tool:<br />
<br />
This will list all connected Wii Remotes:<br />
<br />
$ xwiishow list<br />
<br />
If this shows a path to a Wii Remote (lets say {{ic|/sys/bus/hid/devices/<did>}}) then you can test the device with:<br />
<br />
$ xwiishow /sys/bus/hid/devices/<did><br />
<br />
Or use the index of the listed device:<br />
<br />
$ xwiishow 1<br />
<br />
This will display a picture of the Wii Remote and notify you if buttons are pressed. You can use the {{ic|'r'}} key to enable/disable the rumble motor. Press {{ic|'q'}} to quit the application. You might need to be root to use these tools.<br />
<br />
===X.Org Input Driver===<br />
<br />
There is an X.Org input driver [http://github.com/dvdhrm/xf86-input-xwiimote] available in AUR {{AUR|xf86-input-xwiimote}} which automatically provides an input device to your X clients. Install it and read the related man-page for more information:<br />
<br />
$ man xorg-xwiimote<br />
<br />
===Infrared Sources===<br />
<br />
The Wii Remote includes an infrared camera. To use this camera as a pointer input device, you need an IR-rack as an infrared source. Possible infrared sources are:<br />
<br />
* Nintendo Wii Sensor Bar<br />
* Wireless sensor bar - check eBay!<br />
* Small candles (should have about 30cm distance)<br />
* Home made sensor bar ([http://doctabu.livejournal.com/64758.html])<br />
<br />
{{Note| xf86-input-xwiimote has support for mouse-emulation via IR using the {{ic|Option "MotionSource" "ir" }}}} <br />
There is currently no user-space application that enables mouse-emulation with the IR-sensor. If you need that, you should consider using the no longer supported [[Wiimote|cwiid]] approach. However, the xwiimote tools are under heavy development and will soon support IR mouse-emulation, too.<br />
<br />
==Troubleshooting==<br />
<br />
===The input mapping is very weird===<br />
<br />
The default mapping maps the Wii Remote keys to the the key-constants which resemble the Wii Remote's buttons best. This mapping is quite useless by default. To get better mappings, use the [[#Device Handling|xwiimote userspace tools]].<br />
<br />
===BlueZ does not include the wiimote plugin===<br />
<br />
Upstream BlueZ includes the ''optional'' wiimote plugin since version 4.96. However, it must be enabled explicitely with {{ic|--enable-wiimote}} during compilation. The archlinux package includes the wiimote plugin since {{ic|bluez-4.96-3}}. If you are unsure whether your package includes the wiimote plugin, use:<br />
<br />
grep wiimote $(which bluetoothd)<br />
<br />
This should say:<br />
<br />
Binary file /usr/sbin/bluetoothd matches<br />
<br />
You probably need to run this as root because the bluetoothd daemon resides in /usr/sbin on archlinux or simply use:<br />
<br />
grep wiimote /usr/sbin/bluetoothd<br />
<br />
Note: with bluez 5.5, this file resides in /usr/lib/bluetooth on archlinux<br />
<br />
If this matches, then your BlueZ includes the wiimote plugin and no more user-interaction is needed. If this does not match, you need to enable it yourself or work without it. If you do not want to compile your own bluez package, then you can use the wiimote without this plugin by connecting without pairing/bonding. For instance, when using {{ic|blueman}} or {{ic|gnome-bluetooth}} you need to select {{ic|"Proceed without pairing"}} when adding a new device.<br />
<br />
If you want to compile the module on your own, then add {{ic|--enable-wiimote}} to your configure flags and proceed as usual. See the bluez PKGBUILD for further information.<br />
<br />
===I cannot connect my wiimote===<br />
<br />
The BlueZ packages includes a special wiimote plugin since version {{ic|4.96}} which handles all Wii Remote peculiarities for you. If you cannot pair your Wii Remote like any other device, then you should try connecting without pairing/bonding (i.e. not using authentication with a PIN). If this still does not work, please report your issue to the upstream developers at [http://www.github.com/dvdhrm/xwiimote/issues XWiimote@GitHub].<br />
<br />
Please always use the red sync-button behind the battery cover on the back of the Wii Remote for troubleshooting. This works more reliably than holding the 1+2 buttons.<br />
<br />
The Auto-Reconnect feature allows the Wii Remote to reconnect to its last connected host when a key is pressed. This means you do not need to connect your Wii Remote manually each time. However, the Auto-Reconnect feature only works if you paired your Wii-Remote. Connecting without the wiimote plugin will not enable Auto-Reconnect.<br />
<br />
===Cannot use Wiimote in Dolphin-emu after pairing with xwiimote===<br />
Dolphin uses its own driver so pressing the resync button on the wiimote while dolphin is running should resync the wiimote to dolphin instead of the xwiimote.<br />
<br />
===My Wii Remote is still not working===<br />
<br />
The XWiimote software stack is actively developed. Please report your problems at [http://www.github.com/dvdhrm/xwiimote/issues XWiimote@GitHub].<br />
<br />
There are also other projects which provide Wii Remote support for linux. See the [[Wiimote|Wii Remote article]] for the cwiid project.<br />
<br />
==See also==<br />
* [[Wiimote]]: Cwiid: An older software stack for linux which provides partial Wii Remote support<br />
* [http://dvdhrm.wordpress.com/2012/02/26/xf86-input-xwiimote-0-2/]: Developer blog about Wii Remotes</div>Blueriderhttps://wiki.archlinux.org/index.php?title=XWiimote&diff=303276XWiimote2014-03-05T22:50:17Z<p>Bluerider: /* Troubleshooting */</p>
<hr />
<div>[[Category:Other hardware]]<br />
This article is about the Nintendo Wii Remote Linux kernel driver. This driver is part of upstream Linux since version 3.1. It is an easy to use drop-in replacement for the older user-space drivers like [[Wiimote|cwiid]].<br />
You can use your Wii Remote for all purposes with this driver, for instance as an [[Xorg|X]] input device or joystick controller for your Linux games.<br />
<br />
{{Note|The XWiimote tools are still experimental. Connecting and managing your Wii Remote works well and there is a driver to use the Wii Remote as X11 input, but extended features may still be missing.}}<br />
<br />
==Prerequisites==<br />
* [[Bluetooth]]<br />
* {{AUR|xwiimote}}<br />
* xwiimote kernel driver<br />
* Wii Remote hardware<br />
<br />
The most important piece required is [[Bluetooth]], this must already be configured and running without the help of this guide. This should be simple enough with any guide found on the [[Bluetooth|Internet]]. Most recent bluez package in Arch Linux includes the wiimote plugin. See [[#BlueZ does not include the wiimote plugin|Troubleshooting BlueZ]] to make BlueZ include the wiimote plugin.<br />
<br />
The user-space utilities are available in the [[AUR]]. You need the {{AUR|xwiimote}} package. There is also a git-package {{AUR|xwiimote-tools-git}} if you want the most recent revision.<br />
<br />
The kernel driver is part of upstream Linux since version 3.1. The module is called {{ic|hid-wiimote}}. If it is not available in your kernel, you need to compile the module yourself. The Arch Linux kernel includes it starting with version 3.1.<br />
<br />
Lastly you will need a Wii Remote, this can include (although, are not required) the Nunchuk and Classic Controller attachments.<br />
<br />
If your kernel does not include the {{ic|hid-wiimote}} module, you can enable it with {{ic|CONFIG_HID_WIIMOTE}}. The module needs {{ic|CONFIG_INPUT_FF_MEMLESS}}, {{ic|CONFIG_LEDS_CLASS}}, {{ic|CONFIG_POWER_SUPPLY}} and {{ic|CONFIG_BT_HIDP}} embedded in your kernel or as modules, previously loaded.<br />
Starting with kernel version 3.3 there is an additional config option {{ic|CONFIG_HID_WIIMOTE_EXT}} which is enabled by default. It controls whether wiimote extensions like Nunchuck and Classic Controller should be supported.<br />
<br />
==Connect the Wii Remote==<br />
<br />
You can connect to your Wii Remote like any other Bluetooth device. See the [[Bluetooth|Bluetooth article]] about information on pairing Bluetooth devices. The Wii Remote does not need special handling anymore. The BlueZ wiimote plugin handles all peculiarities in the background for you.<br />
<br />
The Wii Remote can be put into discoverable mode by pressing the red sync-button behind the battery cover on the back. The Wii Remote will stay in discoverable mode for 20s. You can also hold the 1+2 buttons to put the Wii Remote into discoverable state. However, the first method works more reliably!<br />
<br />
If you are asked for PIN input while bonding the devices, then your BlueZ bluetoothd daemon does not include the wiimote plugin. See [[#BlueZ does not include the wiimote plugin|Troubleshooting BlueZ]] for more information. If this does not help, you can still connect to your wiimote without pairing/bonding (i.e. not using authentication with a PIN). This should work with any BlueZ version. See [[#I cannot connect my wiimote|Troubleshooting Pairing]] if you still cannot connect your wiimote.<br />
<br />
==Device Handling==<br />
<br />
If your Wii Remote is connected, it will appear with several input devices inside {{ic|/dev/input/eventX}}. You can list all Wii Remotes with:<br />
<br />
$ ls /sys/bus/hid/devices<br />
<br />
Then you can get additional device details with:<br />
<br />
$ ls /sys/bus/hid/devices/<devid>/<br />
<br />
The default mapping for the input-keys of the Wii Remotes are not very useful. User-space applications exist that re-map the Wii Remote input to more useful keys/actions [http://github.com/dvdhrm/xwiimote] - available in AUR {{AUR|xwiimote}}. If you installed this package you can test your connected Wii Remotes with the {{ic|xwiishow}} tool:<br />
<br />
This will list all connected Wii Remotes:<br />
<br />
$ xwiishow list<br />
<br />
If this shows a path to a Wii Remote (lets say {{ic|/sys/bus/hid/devices/<did>}}) then you can test the device with:<br />
<br />
$ xwiishow /sys/bus/hid/devices/<did><br />
<br />
Or use the index of the listed device:<br />
<br />
$ xwiishow 1<br />
<br />
This will display a picture of the Wii Remote and notify you if buttons are pressed. You can use the {{ic|'r'}} key to enable/disable the rumble motor. Press {{ic|'q'}} to quit the application. You might need to be root to use these tools.<br />
<br />
===X.Org Input Driver===<br />
<br />
There is an X.Org input driver [http://github.com/dvdhrm/xf86-input-xwiimote] available in AUR {{AUR|xf86-input-xwiimote}} which automatically provides an input device to your X clients. Install it and read the related man-page for more information:<br />
<br />
$ man xorg-xwiimote<br />
<br />
===Infrared Sources===<br />
<br />
The Wii Remote includes an infrared camera. To use this camera as a pointer input device, you need an IR-rack as an infrared source. Possible infrared sources are:<br />
<br />
* Nintendo Wii Sensor Bar<br />
* Wireless sensor bar - check eBay!<br />
* Small candles (should have about 30cm distance)<br />
* Home made sensor bar ([http://doctabu.livejournal.com/64758.html])<br />
<br />
There is currently no user-space application that enables mouse-emulation with the IR-sensor. If you need that, you should consider using the no longer supported [[Wiimote|cwiid]] approach. However, the xwiimote tools are under heavy development and will soon support IR mouse-emulation, too.<br />
<br />
==Troubleshooting==<br />
<br />
===The input mapping is very weird===<br />
<br />
The default mapping maps the Wii Remote keys to the the key-constants which resemble the Wii Remote's buttons best. This mapping is quite useless by default. To get better mappings, use the [[#Device Handling|xwiimote userspace tools]].<br />
<br />
===BlueZ does not include the wiimote plugin===<br />
<br />
Upstream BlueZ includes the ''optional'' wiimote plugin since version 4.96. However, it must be enabled explicitely with {{ic|--enable-wiimote}} during compilation. The archlinux package includes the wiimote plugin since {{ic|bluez-4.96-3}}. If you are unsure whether your package includes the wiimote plugin, use:<br />
<br />
grep wiimote $(which bluetoothd)<br />
<br />
This should say:<br />
<br />
Binary file /usr/sbin/bluetoothd matches<br />
<br />
You probably need to run this as root because the bluetoothd daemon resides in /usr/sbin on archlinux or simply use:<br />
<br />
grep wiimote /usr/sbin/bluetoothd<br />
<br />
Note: with bluez 5.5, this file resides in /usr/lib/bluetooth on archlinux<br />
<br />
If this matches, then your BlueZ includes the wiimote plugin and no more user-interaction is needed. If this does not match, you need to enable it yourself or work without it. If you do not want to compile your own bluez package, then you can use the wiimote without this plugin by connecting without pairing/bonding. For instance, when using {{ic|blueman}} or {{ic|gnome-bluetooth}} you need to select {{ic|"Proceed without pairing"}} when adding a new device.<br />
<br />
If you want to compile the module on your own, then add {{ic|--enable-wiimote}} to your configure flags and proceed as usual. See the bluez PKGBUILD for further information.<br />
<br />
===I cannot connect my wiimote===<br />
<br />
The BlueZ packages includes a special wiimote plugin since version {{ic|4.96}} which handles all Wii Remote peculiarities for you. If you cannot pair your Wii Remote like any other device, then you should try connecting without pairing/bonding (i.e. not using authentication with a PIN). If this still does not work, please report your issue to the upstream developers at [http://www.github.com/dvdhrm/xwiimote/issues XWiimote@GitHub].<br />
<br />
Please always use the red sync-button behind the battery cover on the back of the Wii Remote for troubleshooting. This works more reliably than holding the 1+2 buttons.<br />
<br />
The Auto-Reconnect feature allows the Wii Remote to reconnect to its last connected host when a key is pressed. This means you do not need to connect your Wii Remote manually each time. However, the Auto-Reconnect feature only works if you paired your Wii-Remote. Connecting without the wiimote plugin will not enable Auto-Reconnect.<br />
<br />
===Cannot use Wiimote in Dolphin-emu after pairing with xwiimote===<br />
Dolphin uses its own driver so pressing the resync button on the wiimote while dolphin is running should resync the wiimote to dolphin instead of the xwiimote.<br />
<br />
===My Wii Remote is still not working===<br />
<br />
The XWiimote software stack is actively developed. Please report your problems at [http://www.github.com/dvdhrm/xwiimote/issues XWiimote@GitHub].<br />
<br />
There are also other projects which provide Wii Remote support for linux. See the [[Wiimote|Wii Remote article]] for the cwiid project.<br />
<br />
==See also==<br />
* [[Wiimote]]: Cwiid: An older software stack for linux which provides partial Wii Remote support<br />
* [http://dvdhrm.wordpress.com/2012/02/26/xf86-input-xwiimote-0-2/]: Developer blog about Wii Remotes</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Backlight&diff=303066Backlight2014-03-03T18:33:37Z<p>Bluerider: /* Backlight PWM modulation frequency (Intel i915 only) */</p>
<hr />
<div>[[Category:Laptops]]<br />
[[Category:Power management]]<br />
Screen brightness can often be tricky to control. On many machines, physical hardware switches are missing and software solutions may or may not work well. Make sure to find a working method for your hardware! Screens that are too bright can cause eye strain.<br />
<br />
There are many ways to adjust the screen backlight of a monitor, laptop or integrated panel (such as the iMac) using software, but depending on hardware and model, sometimes only some options are available. This article aims to summarize all possible ways to adjust the backlight.<br />
<br />
== Overview ==<br />
<br />
There are many ways to control brightness. According to this discussion[https://bugs.launchpad.net/ubuntu/+source/xserver-xorg-video-intel/+bug/397617] and this wiki page [https://wiki.ubuntu.com/Kernel/Debugging/Backlight], the control method could be divided into these categories:<br />
* brightness is controlled by vendor-specified hotkey and there is no interface for the OS to adjust the brightness<br />
* brightness is controlled by the OS:<br />
** brightness can be controlled by ACPI<br />
** brightness can be controlled by graphic driver<br />
All methods are exposed to the user through /sys/class/brightness and xrandr/xbacklight can choose one method to control brightness. It is still not very clear which one xbacklight prefers by default.<br />
''See FS#27677 for xbacklight, if you get "No outputs have backlight property."'' There is a temporary fix if xrandr/xbacklight does not choose the right directory in /sys/class/brightness: You can specify the one you want in xorg.conf by setting the "Backlight" option of the Device section to the name of that directory (see http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=651741 at the bottom of the page for details).<br />
* brightness is controlled by HW register through setpci<br />
<br />
== ACPI ==<br />
<br />
It is often possible to adjust the backlight by ACPI. This controls the actual LEDs or cathodes of the screen. When this ACPI option is available, the illumination is controllable using a GUI slider in the Display/Screen system settings or by simple commands on the CLI.<br />
<br />
Different cards might manage this differently. Check {{ic|/sys/class/backlight}} to find out:<br />
{{hc|# ls /sys/class/backlight/|<br />
intel_backlight<br />
}}<br />
<br />
So this particular backlight is managed by an Intel card. It is called {{ic|acpi_video0}} on an ATI card. In the following example, acpi_video0 is used.<br />
<br />
The directory contains the following files and folders:<br />
<br />
actual_brightness brightness max_brightness subsystem/ uevent <br />
bl_power device/ power/ type<br />
<br />
The maximum brightness (often 15) can be found by running {{ic|cat}}:<br />
<br />
{{hc|$ cat /sys/class/backlight/acpi_video0/max_brightness|<br />
15<br />
}}<br />
<br />
Brightness can then be set (as root) with {{ic|echo}}. Obviously you cannot go any higher than your screen's maximum brightness. The values for maximum brightness and brightness in general vary wildly among cards. <br />
<br />
# echo 5 > /sys/class/backlight/acpi_video0/brightness<br />
<br />
Sometimes ACPI does not work well due to different motherboard implementations and ACPI quirks. This include some models with dual graphics (e.g. Nvidia-optimus/Radeon with intel (i915)) and some examples with this problem in notebooks such as Dell Studio, Dell XPS 14/15/17 and some Lenovo series, Kamal Mostafa kernel developer make [https://launchpad.net/~kamalmostafa/+archive/linux-kamal-mjgbacklight patches] for solved this problem included after 3.1 kernel version. Additionally, on Nvidia-optimus laptops, the kernel parameter nomodeset can interfere with the ability to adjust the backlight. You can try adding the following kernel parameters in your bootloader(grub, syslinux...) to adjust ACPI model:<br />
<br />
video.use_native_backlight=1<br />
<br />
{{Note|This kernel setting was added in '''Linux 3.13'''. }}<br />
<br />
or<br />
<br />
acpi_osi=Linux acpi_backlight=vendor<br />
<br />
or<br />
<br />
acpi_osi=Linux acpi_backlight=legacy<br />
''acpi_backlight=vendor will prefer vendor specific driver (e.g. thinkpad_acpi, sony_acpi, etc.) instead of the ACPI video.ko driver.''<br />
<br />
For Lenovo IdeaPad laptops, you may also need to blacklist the {{ic|ideapad_laptop}} module by adding {{ic|blacklist ideapad_laptop}} to {{ic|/etc/modprobe.d/blacklist.conf}}, creating the file if needed. ([http://askubuntu.com/a/304762 Source])<br />
<br />
{{Tip|Also, you can try:<br />
<nowiki><br />
acpi_osi="!Windows 2012" acpi_backlight=vendor # On some new laptops with pre-installed Windows 8 and/or hybrid graphics<br />
acpi_backlight=legacy<br />
acpi_osi=Linux<br />
</nowiki><br />
and all combinations of these lines.<br />
<br />
The first line works on asus G750 notebook (keys don't work, only from {{ic|/sys/class/backlight/asus-nb-wmi/brightness}}. You need to also do<br />
# modprobe asus-nb-wmi<br />
}}<br />
{{Tip|If you have got intel_backlight and a manufacturer backlight (dell, toshiba, etc.) that stops working after suspend, try:<br />
<nowiki>acpi_backlight=vendor</nowiki><br />
and the following X11 quirk ({{ic|/etc/X11/xorg.conf.d/80-backlight.conf}}):<br />
<nowiki><br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "AccelMethod" "sna"<br />
Option "Backlight" "intel_backlight" # use your backlight that works here<br />
Driver "intel"<br />
BusID "PCI:0:2:0"<br />
EndSection</nowiki><br />
}}<br />
<br />
{{Note|Disabling legacy boot on Dell XPS13 breaks backlight support.}}<br />
<br />
== Switching off the backlight ==<br />
<br />
Switching off the backlight (for example when one locks the notebook) can be useful to conserve battery energy. Ideally the following command inside of a graphical session should work:<br />
sleep 1 && xset dpms force off<br />
The backlight should switch on again on mouse movement or keyboard input. If the previous command does not work, there is a chance that {{ic|vbetool}} works. Note, however, that in this case the backlight must be manually activated again. The command is as follows:<br />
vbetool dpms off<br />
To activate the backlight again:<br />
vbetool dpms on<br />
<br />
For example, this can be put to use when closing the notebook lid as outlined in the entry for [[Acpid#Laptop_Monitor_Power_Off|Acipd]].<br />
<br />
== Backlight utilities ==<br />
<br />
=== xbacklight ===<br />
<br />
You can adjust the backlight through the xorg-server command {{ic|xbacklight}}. The utility is provided by the {{Pkg|xorg-xbacklight}} package in [extra].<br />
<br />
A useful demonstration was posted by [http://www.youtube.com/watch?v=_pi3iKMAJcY gotbletu on YouTube]. He suggests the following commands to adjust the backlight:<br />
<br />
* brighten up:<br />
xbacklight -inc 40<br />
<br />
* dim down:<br />
xbacklight -dec 40<br />
<br />
=== xcalib ===<br />
<br />
The package {{AUR|xcalib}} ([http://xcalib.sourceforge.net/ upstream url]) is available in the [[AUR]] and can be used to dim the screen. Again, the user gotbletu posted a demonstration on [http://www.youtube.com/watch?v=A9xsvntT6i4 Youtube]. This program can correct gamma, invert colors and reduce contrast, the latter of which we use in this case:<br />
<br />
* dim down:<br />
xcalib -co 40 -a<br />
<br />
This program uses ICC technology to interact with X11 and while the screen is dimmed, you may find that the mouse cursor is just as bright as before.<br />
<br />
=== redshift ===<br />
<br />
The program [[redshift]] in the official repositories uses {{ic|randr}} to adjust the screen brightness depending on the time of day and your geographic position. It can also do RGB gamma corrections and set color temperatures. As with {{ic|xcalib}}, this is very much a software solution and the look of the mouse cursor is unaffected. To execute a single quick adjustment of the brightness, try something like this:<br />
<br />
redshift -o -l 0:0 -b 0.8 -t 6500:6500<br />
<br />
{{Tip|If your longitude is west or your latitude is south, you should input it as negative.<br />
Example for Berkeley, CA: <br />
redshift-gtk -l 37.8717:-122.2728 <br />
}}<br />
<br />
=== relight ===<br />
<br />
[http://xyne.archlinux.ca/projects/relight relight] is available in [http://xyne.archlinux.ca/repos Xyne's repos] and as package {{AUR|relight}} in the [[AUR]]. The package provides a service to automatically restore previous backlight settings during reboot along using the ACPI method explained above. The package also contains a dialog-based menu for selecting and configuring backlights for different screens.<br />
<br />
=== setpci (use with great care) ===<br />
<br />
It is possible to set the register of the graphic card to adjust the backlight. It means you adjust the backlight by manipulating the hardware directly, which can be risky and generally is not a good idea. Not all of the graphic cards support this method.<br />
<br />
When using this method, you need to use {{ic|lspci}} first to find out where your graphic card is.<br />
# setpci -s 00:02.0 F4.B=0<br />
<br />
=== Calise ===<br />
<br />
The software [http://calise.sourceforge.net/wordpress/ calise] can be found in AUR.<br />
* Stable version: {{AUR|calise}}<br />
* Development version: {{AUR|calise-git}} <br />
<br />
It basically computes ambient brightness, and set screen's correct backlight, simply making captures from the webcam, for laptop without light sensor.<br />
For more information, calise has its own wiki: [http://calise.sourceforge.net/mediawiki/index.php/Main_Page Calise wiki].<br />
<br />
The main features of this program are that it is very precise, very light on resource usage, and with the daemon version (.service file for systemd users available too), it has practically no impact on battery life.<br />
<br />
=== brightd ===<br />
<br />
Macbook-inspired {{AUR|brightd}} automatically dims (but does not put to standby) the screen when there is no user input for some time. A good companion of [[Display Power Management Signaling]] so that the screen does not blank out in a sudden.<br />
<br />
== KDE ==<br />
<br />
[[KDE]] users can adjust the backlight via ''System Settings > Power Management > Power Profiles''.<br />
If you want set backlight before kdm just put in /usr/share/config/kdm/Xsetup :<br />
<br />
xbacklight -inc 10<br />
<br />
== NVIDIA settings ==<br />
<br />
Users of [[NVIDIA|NVIDIA's proprietary drivers]] users can change display brightness via the nvidia-settings utility under "X Server Color Correction." However, note that this has absolutely nothing to do with backlight (intensity), it merely adjusts the color output. (Reducing brightness this way is a power-inefficient last resort when all other options fail; increasing brightness spoils your color output completely, in a way similar to overexposed photos.)<br />
<br />
== Backlight PWM modulation frequency (Intel i915 only) ==<br />
<br />
Laptops with LED backlight are known to have screen flicker sometimes. The reason for this, is that it is hard enough to dim LEDs by limiting direct current flowing through. It is easier to control brightness by switching LEDs on and off fast enough.<br />
<br />
However, frequency of the switching (so-called PWM modulation frequency) is not high enough actually, and some people may notice flicker either explicitly or by feeling headache and eyestrain.<br />
<br />
If you have an Intel i915 GPU, then it may be possible to adjust PWM modulation frequency to eliminate flicker.<br />
<br />
Install {{Pkg|intel-gpu-tools}} from the official repositories. Get value of the register, that determines PWM modulation frequency<br />
<br />
{{hc|# intel_reg_read 0xC8254|<br />
0xC8254 : 0x12281228<br />
}}<br />
<br />
The value returned represents period of PWM modulation. So to increase PWM modulation frequency, value of the register has to be reduced. For example, to double frequency from the previous listing, execute:<br />
<br />
# intel_reg_write 0xC8254 0x09140914<br />
<br />
You can use online calculator to calculate desired value http://devbraindom.blogspot.com/2013/03/eliminate-led-screen-flicker-with-intel.html<br />
<br />
Refer to dedicated topic for details https://bbs.archlinux.org/viewtopic.php?pid=1245913<br />
<br />
== Troubleshooting ==<br />
<br />
=== Backlight fails to adjust on Intel chipsets with Kernel 3.13 ===<br />
Adding the following file helps.<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Driver "intel"<br />
Option "Backlight" "intel_backlight"<br />
<br />
EndSection}}</div>Blueriderhttps://wiki.archlinux.org/index.php?title=MPlayer&diff=292161MPlayer2014-01-09T18:51:35Z<p>Bluerider: /* Troubleshooting */</p>
<hr />
<div>[[Category:Player]]<br />
[[cs:MPlayer]]<br />
[[el:MPlayer]]<br />
[[fr:MPlayer]]<br />
[[it:MPlayer]]<br />
[[ja:MPlayer]]<br />
[[ru:MPlayer]]<br />
[[es:MPlayer]]<br />
[[uk:MPlayer]]<br />
[[zh-CN:MPlayer]]<br />
'''MPlayer''' is a popular movie player for GNU/Linux. It has support for pretty much every video and audio format out there and is hence very versatile, even though most people use it for viewing videos.<br />
<br />
== Installation ==<br />
<br />
Various flavours of MPlayer can be [[pacman|installed]] from the [[official repositories]] or from the [[AUR]]:<br />
* {{Pkg|mplayer}} - Official package.<br />
<br />
Notable variants are:<br />
* {{Pkg|mplayer-vaapi}} - VAAPI-enabled version.<br />
* {{AUR|mplayer-svn}} - Development version.<br />
* {{AUR|mplayer2}} - Fork of MPlayer. with few [http://www.mplayer2.org/differences/ enhancements].<br />
* {{AUR|mplayer2-git}} - Development version of ''mplayer2''.<br />
{{Note|''mplayer2'' development seems to be ceased in favour of [[mpv]], which is focused on speed and quality of development, though this breaks compatibility with old hardware and software. Be aware of its [https://github.com/mpv-player/mpv/blob/master/DOCS/man/en/changes.rst differences] if you want to use it.}}<br />
<br />
== Additional installation tips ==<br />
<br />
=== Frontends/GUIs ===<br />
<br />
* {{App|Deepin Media Player|Rich GTK2/Python interface for the Deepin desktop.|http://www.linuxdeepin.com/|{{AUR|deepin-media-player}}}}<br />
* {{App|GNOME MPlayer|Simple GTK+-based GUI for MPlayer.|http://kdekorte.googlepages.com/gnomemplayer|{{Pkg|gnome-mplayer}}}}<br />
* {{App|KMPlayer|Video player plugin for Konqueror and basic MPlayer/Xine/ffmpeg/ffserver/VDR frontend for KDE.|http://kmplayer.kde.org/|{{AUR|kmplayer}}}}<br />
* {{App|Pymp|PyGTK frontend for MPlayer.|http://jdolan.dyndns.org/trac/wiki/Pymp|{{AUR|pymp}}}}<br />
* {{App|Rosa Media Player|Multimedia player based on SMPlayer with clean and elegant UI.|http://www.rosalab.com/|{{AUR|rosa-media-player}}}}<br />
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.).|http://smplayer.sourceforge.net/|{{Pkg|smplayer}}}}<br />
* {{App|Xt7-Player|Graphical user interface for MPlayer written in Gambas, with a huge list of features.|http://xt7-player.sourceforge.net/xt7forum/|{{AUR|xt7-player}}}}<br />
<br />
=== Browser integration ===<br />
<br />
If you want to let MPlayer control video viewing in your favorite web browser, install one of the following plugins for your browser.<br />
<br />
==== Firefox ====<br />
<br />
A browser plugin is available in the official repositories with the {{Pkg|gecko-mediaplayer}} package.<br />
<br />
{{Note|It depends on {{Pkg|gnome-mplayer}}, which provides a complete frontend to MPlayer.}}<br />
<br />
==== Konqueror ====<br />
<br />
A plugin for Konqueror can be found in the [[AUR]] with the {{AUR|kmplayer}} package.<br />
<br />
{{Note|{{AUR|kmplayer}} also provides a complete frontend to MPlayer.}}<br />
<br />
==== Chromium ====<br />
<br />
The {{Pkg|gecko-mediaplayer}} plugin for Firefox also works in [[Chromium]].<br />
<br />
== Usage ==<br />
<br />
=== Configuration ===<br />
<br />
System-wide configuration is located in {{ic|/etc/mplayer/mplayer.conf}}, whereas the user-local settings are stored in {{ic|~/.mplayer/config}}. The file {{ic|/etc/mplayer/example.conf}} is a good starting point.<br />
<br />
An example configuration:<br />
<br />
{{hc|/etc/mplayer/example.conf|2=<br />
# default configuration that applies to every file<br />
[default]<br />
<br />
# use X11 for video output, use a framebuffer as fallback<br />
vo=xv,directfb<br />
<br />
# use alsa for audio output, choose oss4 as fallback<br />
ao=alsa,oss<br />
<br />
# multithreaded decoding of H264/MPEG-1/2 (valid: 1-8)<br />
lavdopts=threads=2<br />
<br />
# prefer using six channels audio<br />
channels = 6<br />
<br />
# scale the subtitles to the 3% of the screen size<br />
subfont-text-scale = 3<br />
<br />
# never use font config<br />
nofontconfig = 1<br />
<br />
# set the window title using the media filename, when not set with --title.<br />
use-filename-title=yes<br />
<br />
# add black borders so the movies have the same aspect ratio of the monitor<br />
# for wide screen monitors<br />
vf-add=expand=::::1:16/9:16<br />
<br />
# for non wide screen traditional monitors<br />
#vf-add=expand=::::1:4/3:16<br />
<br />
# disable screensaver<br />
heartbeat-cmd="xscreensaver-command -deactivate &" # stop xscreensaver<br />
stop-xscreensaver="yes" # stop gnome-screensaver<br />
<br />
# correct pitch when speed is faster or slower than 1.0<br />
af=scaletempo<br />
<br />
# allow to seek in a file which is still downloading whilst watching it<br />
idx=yes<br />
<br />
# allow to increase the maximal volume<br />
#softvol=1<br />
#softvol-max=600<br />
<br />
# skip displaying some frames to maintain A/V sync on slow systems<br />
framedrop=yes<br />
<br />
# more intense frame dropping (breaks decoding)<br />
#hardframedrop=yes<br />
<br />
# profile for up-mixing two channels audio to six channels<br />
# use -profile 2chto6ch to activate<br />
[2chto6ch]<br />
af-add=pan=6:1:0:.4:0:.6:2:0:1:0:.4:.6:2<br />
<br />
# profile to down-mixing six channels audio to two channels<br />
# use -profile 6chto2ch to activate<br />
[6chto2ch]<br />
af-add=pan=2:0.7:0:0:0.7:0.5:0:0:0.5:0.6:0.6:0:0<br />
<br />
}}<br />
<br />
=== Key bindings ===<br />
<br />
System key bindings are configured via {{ic|/etc/mplayer/input.conf}}. Personal key bindings are stored in {{ic|~/.mplayer/input.conf}}. This is a list of some basic default MPlayer keys. For a complete list of keyboard shortcuts look at {{ic|man mplayer}}.<br />
<br />
{|<br />
! width=85 align=left | Key<br />
! align=left | Description<br />
|-<br />
| {{ic|p}}<br />
| Toggle pause/play.<br />
|-<br />
| {{ic|Space}}<br />
| Toggle pause/play.<br />
|-<br />
|-<br />
| {{ic|Backspace}}<br />
| Return to menu when using dvdnav.<br />
|-<br />
| {{ic|&larr;}}<br />
| Seek backward ten seconds.<br />
|-<br />
| {{ic|&rarr;}}<br />
| Seek forward ten seconds.<br />
|-<br />
| {{ic|&darr;}}<br />
| Seek backward one minute.<br />
|-<br />
| {{ic|&uarr;}}<br />
| Seek forward one minute.<br />
|-<br />
| {{ic|<}}<br />
| Go back in the playlist.<br />
|-<br />
| {{ic|>}}<br />
| Go forward in the playlist.<br />
|-<br />
| {{ic|m}}<br />
| Mute the sound.<br />
|-<br />
| {{ic|0}}<br />
| Volume up.<br />
|-<br />
| {{ic|9}}<br />
| Volume down.<br />
|-<br />
| {{ic|f}}<br />
| Toggle fullscreen mode.<br />
|-<br />
| {{ic|o}}<br />
| Toggle OSD state.<br />
|-<br />
| {{ic|v}}<br />
| Toggle subtitle visibility.<br />
|-<br />
| {{ic|I}}<br />
| Show filename.<br />
|-<br />
| {{ic|1}}, {{ic|2}}<br />
| Adjust contrast.<br />
|-<br />
| {{ic|3}}, {{ic|4}}<br />
| Adjust brightness.<br />
|-<br />
| {{ic|j}}<br />
| Cycle through the available subtitles.<br />
|-<br />
| {{ic|#}}<br />
| Cycle through the available audio tracks.<br />
|}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Automatic resuming from where you left off ===<br />
<br />
To get this behavior, you can install the {{AUR|mplayer-resumer}} package from the [[AUR]]. The package contains a Perl wrapper script for MPlayer which will allow you to autoresume playback from the point it was last stopped.<br />
<br />
To use it, simply call the wrapper script in place of MPlayer:<br />
$ mplayer-resumer ''options'' ''path/to/file''<br />
<br />
If this script is restarted within a short amount of time after closing MPayer (default 5 seconds) then it will delete the file used to keep track of the videos resume position, effectively starting the video from the beginning.<br />
<br />
If the video file to be played is on a read-only filesystem, or otherwise lives in a location that cannot be written to, resume will fail. This is because the current implementation uses a file parallel to the video file to store the timecode.<br />
<br />
=== Enabling VDPAU ===<br />
<br />
For a complete list of NVIDIA VDPAU capable hardware, see [http://en.wikipedia.org/wiki/PureVideo#Table_of_PureVideo_.28HD.29_GPUs this table]. Ensure the {{Pkg|nvidia}} driver is installed and consider one of the following two methods to automatically enable VDPAU for playback.<br />
<br />
For Intel/AMD, you can use {{pkg|libvdpau-va-gl}} — VAAPI backend for VDPAU. For AMD you should also install {{AUR|xvba-video}}. To use it, create:<br />
{{hc|/etc/profile.d/vdpau_vaapi.sh|<br />
#!/bin/sh<br />
export VDPAU_DRIVER&#61;va_gl<br />
}}<br />
and make it executable:<br />
# chmod +x /etc/profile.d/vdpau_vaapi.sh<br />
and reboot or relogin.<br />
<br />
==== Using a configuration file ====<br />
<br />
Append the following to either the system-wide ({{ic|/etc/mplayer/mplayer.conf}}) or user-specific ({{ic|~/.mplayer/config}}) configuration files:<br />
vo=vdpau,<br />
vc=ffh264vdpau,ffmpeg12vdpau,ffodivxvdpau,ffwmv3vdpau,ffvc1vdpau,<br />
<br />
{{Note|The trailing commas are important! They tell MPlayer to fall back on other drivers and codecs should the specified ones not be found.}}<br />
{{Warning|The {{ic|ffodivxvdpau}} codec is only supported by the most recent series of NVIDIA hardware. Consider omitting it based on your specific hardware. See [[NVIDIA#Enabling_Pure_Video_HD_.28VDPAU.2FVAAPI.29|the NVIDIA page]] for more information.}}<br />
<br />
==== Using a wrapper script ====<br />
<br />
The [[AUR]] contains a trivial Bash script called {{AUR|mplayer-vdpau-auto}} that detects which video codec to use and when to use VDPAU as the video output.<br />
<br />
Another simple wrapper is {{AUR|mplayer-vdpau-shell-git}}, which can recover from a VDPAU FATAL error.<br />
This wrapper uses the "-include" option to include a VDPAU configuration, so it will ignore any VDPAU specific settings in your {{ic|~/.mplayer/config}} file.<br />
<br />
=== Translucent video with Radeon cards and Composite enabled ===<br />
<br />
To get translucent video output in X you have to enable textured video in MPlayer:<br />
$ mplayer -vo xv:adaptor=1 ''file''<br />
<br />
Or add the following line to {{ic|~/.mplayer/config}}:<br />
vo=xv:adaptor=1<br />
<br />
You can use {{ic|xvinfo}} to check which video modes your graphic card supports.<br />
<br />
=== Watching streamed video ===<br />
<br />
If you want to play a video stream (e.g an {{ic|ASX}} link) use:<br />
$ mplayer -playlist link-to-stream.asx<br />
The {{ic|-playlist}} option is necessary because these streams are actually playlists and cannot be played without it.<br />
<br />
==== DVD playing ====<br />
<br />
To play a DVD with MPlayer:<br />
<br />
$ mplayer dvd://''N''<br />
<br />
where ''N'' is the desired chapter number. Start at 1 and work up if unsure.<br />
<br />
Mplayer checks {{ic|/dev/dvd}} by default. Tell it to use {{ic|/dev/sr0}} with the {{ic|dvd-device}} option at the command line, or the {{ic|dvd-device}} variable in {{ic|~/.mplayer/config}}.<br />
<br />
To play a DVD image file:<br />
<br />
$ mplayer -dvd-device movie.iso dvd://''N''<br />
<br />
To enable the DVD menu use:<br />
<br />
$ mplayer dvdnav://<br />
<br />
{{Note|You use arrow keys to navigate and the {{ic|Enter}} key to choose.}}<br />
To enable mouse support in DVD menus use:<br />
<br />
$ mplayer -mouse-movements dvdnav://<br />
<br />
To find the audio language, start MPlayer with the {{ic|-v}} switch to output audio IDs. An audio track is selected with {{ic|-aid ''audio_id''}}. Set a default audio language by editing {{ic|~/.mplayer/config}} and adding the line {{ic|1=alang=en}} for English. <br />
<br />
With MPlayer, the DVD could be set to a low volume. To increase the maximum volume to 400%, use {{ic|1=softvol=yes}} and {{ic|1=softvol-max=400}}. The startup volume defaults to 100% of software volume and the global mixer levels will remain untouched. Using the {ic|9}} and {{ic|0}} keys, volume can be adjusted between 0 and 400 percent.<br />
<br />
alang=en<br />
softvol=yes<br />
softvol-max=400<br />
<br />
=== JACK support ===<br />
<br />
To have MPlayer audio output directed to [[JACK]] as its default behavior, edit {{ic|~/.mplayer/config}} and add:<br />
ao=jack<br />
<br />
If you don't have JACK running all the time, you can have MPlayer output to JACK on an as-needed basis by invoking MPlayer from the command line as such:<br />
$ mplayer -ao jack [path/to/file]<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mplayer randomly pauses during playback ===<br />
<br />
Mplayer seems to have an issue with alsa playback; switch to pulseaudio to avoid the random pauses mplayer may experience with video playback.<br />
<br />
=== MPlayer fails to open files with spaces ===<br />
<br />
MPlayer can fail to open a file with spaces (e.g. 'The Movie') by saying that it could not open the file {{ic|file:///''The%20Movie''}} (where all spaces are converted to {{ic|%20}}). This can be fixed by editing {{ic|/usr/share/applications/mplayer.desktop}} to changing the following line from:<br />
Exec=mplayer %U<br />
to:<br />
Exec=mplayer "%F"<br />
<br />
If you use a frontend/GUI for MPlayer, enter its name in {{ic|<nowiki>Exec=gui_name "%F"</nowiki>}}.<br />
<br />
=== SMPlayer: No video issue ===<br />
<br />
SMPlayer may have trouble opening some {{ic|MP4}} (and probably {{ic|FLV}}) videos. If it plays only audio without any video, a possible fix is to add the following lines to your {{ic|~/.mplayer/config}} file:<br />
[extension.mp4]<br />
demuxer=mov<br />
<br />
If problem persists after doing so, it is because SMPlayer is keeping settings for that specific file. Deleting the settings for all the files that SMPlayer is keeping will solve this problem:<br />
$ rm -rf ~/.config/smplayer/file_settings<br />
<br />
=== SMPlayer: fail to resume playback after pause ===<br />
<br />
SMPlayer might stop playing a video after pausing it if your audio output driver is incorrectly set. You can fix this by specifically setting your audio driver. For example, if you use PulseAudio, this can be done by starting MPlayer with the {{ic|-ao pulse}} argument or by adding<br />
the following to your {{ic|~/.mplayer/config}} file:<br />
ao=pulse<br />
<br />
You can also change this from SMPlayer by going to ''Options > Preferences > General > Audio'' and setting the ''Output Driver'' option to ''pulse''.<br />
<br />
=== SMPlayer: no video when using transparency in GNOME ===<br />
<br />
This problem may arise under GNOME when using Compiz to provide transparency: SMPlayer starts with a transparent screen with audio playing, but no video. To fix this, create (as root) a file with the contents:<br />
{{hc|/usr/local/bin/smplayer.helper|<nowiki><br />
export XLIB_SKIP_ARGB_VISUALS=1<br />
exec smplayer.real "$@"<br />
</nowiki>}}<br />
<br />
Then do the following:<br />
# chmod 755 /usr/local/bin/smplayer.helper<br />
# ln -sf /usr/local/bin/smplayer.helper /usr/local/bin/smplayer<br />
<br />
=== SMPlayer: OSD font too big / subtitle text too small ===<br />
<br />
Since SMPlayer 0.8.2.1 (with MPlayer2 20121128-1), the ratio of the subtitle font to the OSD font is very strange. This can result in the OSD text filling the whole screen while the subtitles are very small and unreadable. This problem can be solved by adding:<br />
-subfont-osd-scale 2<br />
or to the extra options passed to MPlayer from SMPlayer. These options are found in ''Options > Preferences > Advanced > Options for MPlayer''. This can also be achieved by adding the following line to {{ic|~/.mplayer/config}}:<br />
subfont-osd-scale=2<br />
<br />
== See also ==<br />
<br />
* [http://www.mplayerhq.hu/ Official MPlayer website]<br />
* [http://www.mplayer2.org/ Official MPlayer2 website]<br />
* [http://wiki.multimedia.cx/index.php?title=MPlayer_FAQ MPlayer FAQ]<br />
* [https://www.youtube.com/watch?v=n4Ul_A0VBVI MPlayer notes]<br />
* [https://help.ubuntu.com/community/MPlayerTips MPlayer tips]<br />
* [http://how-to.wikia.com/wiki/How_to_configure_MPlayer How to configure MPlayer]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Chromium&diff=290619Chromium2013-12-28T03:12:52Z<p>Bluerider: /* Troubleshooting */ Fix chromium sound crackling issue</p>
<hr />
<div>[[de:Chromium]]<br />
[[es:Chromium]]<br />
[[fr:chromium]]<br />
[[it:Chromium]]<br />
[[zh-CN:Chromium]]<br />
[[Category:Web Browser]]<br />
{{Related articles start}}<br />
{{Related|Chromium Tips and Tweaks}}<br />
{{Related|Browser Plugins}}<br />
{{Related|Firefox}}<br />
{{Related|Opera}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Chromium (web browser)|Chromium]] is an open source graphical web browser from Google, based on the [[Wikipedia:WebKit|WebKit]] rendering engine.<br />
<br />
== Installation ==<br />
<br />
The open source project, '''Chromium''', can be [[Pacman|installed]] with the package {{Pkg|chromium}}, available in the [[official repositories]]. <br />
In the [[AUR]] you can also find:<br />
* {{AUR|chromium-dev}} - the development version (beware: compiling Chromium takes at least as long as compiling the Linux kernel!)<br />
* {{AUR|chromium-browser-bin}} - the binary version of the latest Chromium build<br />
<br />
The modified browser, '''Google Chrome''', bundled with Flash Player and PDF Reader, can be installed with the package {{AUR|google-chrome}}, available in the [[AUR]]. <br />
In the [[AUR]] you can also find:<br />
* {{AUR|google-chrome-beta}} - the beta version<br />
* {{AUR|google-chrome-dev}} - the development version<br />
<br />
{{Tip|See these [https://code.google.com/p/chromium/wiki/ChromiumBrowserVsGoogleChrome two] [http://news.softpedia.com/news/Google-Chrome-vs-Chromium-Understanding-Stable-Beta-Dev-Releases-and-Version-No-140060.shtml articles] for an explanation of the differences between Stable/Beta/Dev, as well as Chromium vs. Chrome and the version numbers.}}<br />
<br />
[http://www.srware.net/en/software_srware_iron.php SRWare Iron], a modified Chromium with altered settings to increase privacy and with built-in ad-blocker, can be installed with the package {{AUR|iron-bin}}, available in the [[AUR]].<br />
<br />
== Configuration ==<br />
<br />
=== Set Chromium as default browser ===<br />
<br />
This behaviour is related to [[xdg-open]]: see [[xdg-open#set the default browser]]. For more information about the topic in general, see [[Default Applications]].<br />
<br />
=== File associations ===<br />
<br />
This behaviour is related to [[xdg-open]]: see [[xdg-open#Configuration]]. For more information about the topic in general, see [[Default Applications]].<br />
<br />
=== Font rendering ===<br />
<br />
Chromium (and Google Chrome) will use the [[Font Configuration|settings]] in {{ic|~/.config/fontconfig/fonts.conf}}. For possibly better rendering you may try the following. Create the file if it does not already exist.<br />
<br />
{{hc|~/.config/fontconfig/fonts.conf|<br />
<match target&#61;"font"><br />
<edit mode&#61;"assign" name&#61;"autohint"><bool>true</bool></edit><br />
<edit mode&#61;"assign" name&#61;"hinting"><bool>true</bool></edit><br />
<edit mode&#61;"assign" name&#61;"hintstyle"><const>hintslight</const></edit><br />
</match><br />
}}<br />
<br />
If the fonts are still rendered badly, you can use Xft settings [[X resources|as suggested here]]:<br />
{{hc|~/.Xresources|<br />
[...]<br />
! Xft settings ---------------------------------------------------------------<br />
Xft.dpi: 96<br />
Xft.antialias: true<br />
Xft.rgba: rgb<br />
Xft.hinting: true<br />
Xft.hintstyle: hintslight<br />
[...]<br />
}}<br />
<br />
Then update the X Resources database using:<br />
<br />
$ xrdb -merge ~/.Xresources<br />
<br />
{{Note|These settings will affect any application that uses X Resources for font settings; e.g. [[Rxvt-unicode|rxvt-unicode]].}}<br />
<br />
==== Non-Latin characters ====<br />
<br />
Install needed fonts to correctly display Chinese, Japanese, Korean characters. For examples of recommended fonts for various languages see [[Fonts#Font_packages|Font Packages]].<br />
<br />
For the Arch Wiki, one only needs the {{Pkg|ttf-arphic-uming}} package.<br />
<br />
=== Flash Player plugin ===<br />
<br />
==== Adobe (Netscape plugin API) ====<br />
{{Warning|This version will not be updated (except for security updates), and is stuck at version 11.2. It will be completely disabled in January 2014.[http://blog.chromium.org/2013/09/saying-goodbye-to-our-old-friend-npapi.html]}}<br />
The Adobe Flash plugin can be [[Pacman|installed]] with the package {{Pkg|flashplugin}}, available in the official repositories.<br />
<br />
==== Adobe (Pepper plugin API) ====<br />
<br />
While the classic Flash plugin will not be updated for Linux, an updated Flash Player is included with Google Chrome. It is compatible with Chromium and Iron.<br />
<br />
The easiest way to install '''pepper-flash''' for Chromium is using one of the packages provided in the [[AUR]]:<br />
* {{AUR|chromium-pepper-flash-stable}} for the stable version.<br />
* {{AUR|chromium-pepper-flash}} for a development version.<br />
<br />
{{Note|<br />
* If you have still {{pkg|flashplugin}} installed, in order for Chromium to use this new Pepper Flash plugin, please make sure the plugin location from {{ic|/usr/lib/mozilla/plugins/libflashplayer.so}} is disabled and {{ic|/usr/lib/PepperFlash/libpepflashplayer.so}} is enabled in {{ic|chrome://plugins}}.<br />
* If you use [http://www.srware.net/en/software_srware_iron.php SRWare Iron], and have still {{pkg|flashplugin}} installed and if the Pepper Flash doesn't show up in the plugins list, then disable {{ic|libflashplayer.so}} and start Iron with:<br />
{{bc|1=$ iron --ppapi-flash-path=/usr/lib/PepperFlash/libpepflashplayer.so --ppapi-flash-version=11.9.900.117}}<br />
}}<br />
<br />
=== PDF viewer plugin ===<br />
<br />
There are multiple ways of enabling PDF support in Chromium that are detailed below.<br />
<br />
==== libpdf ====<br />
<br />
'''libpdf''' is Google's own implementation of a PDF renderer included with Google Chrome. It is compatible with Chromium and Iron.<br />
<br />
The easiest way to install '''libpdf''' for Chromium is using one of the packages provided in the [[AUR]]:<br />
* {{AUR|chromium-libpdf-stable}} for the stable version.<br />
* {{AUR|chromium-libpdf}} for a development version.<br />
<br />
Enable the plugin in {{ic|chrome://plugins}}.<br />
<br />
{{Note|To install '''libpdf''' for other Chromium packages, edit the PKGBUILD of {{AUR|chromium-libpdf-stable}} to install {{ic|libpdf.so}} into correct path. For example, to install it for {{AUR|chromium-browser-bin}}, replace <br />
install -m644 opt/google/chrome/libpdf.so "${pkgdir}''/usr/lib/chromium"''<br />
with<br />
install -m644 opt/google/chrome/libpdf.so "${pkgdir}''/opt/chromium-browser"''<br />
}}<br />
<br />
===== Manual installation =====<br />
<br />
To do it manually, download a Google Chrome release that corresponds to the version of Chromium you use:<br />
<br />
$ curl -O https://dl-ssl.google.com/linux/direct/google-chrome-stable_current_i386.deb<br />
$ curl -O https://dl-ssl.google.com/linux/direct/google-chrome-unstable_current_i386.deb<br />
$ curl -O https://dl-ssl.google.com/linux/direct/google-chrome-stable_current_amd64.deb<br />
$ curl -O https://dl-ssl.google.com/linux/direct/google-chrome-unstable_current_amd64.deb<br />
<br />
Extract the deb file with:<br />
$ ar vx ''deb-file''<br />
<br />
Extract LZMA the archive with:<br />
$ tar -xJf ''lzma-file''<br />
<br />
Move {{ic|libpdf.so}} from {{ic|opt/google/chrome/}} to the appropriate directory as stated above. A change of its file permissions and ownership may be necessary (the permission of {{ic|libpdf.so}} should be 755).<br />
<br />
To verify that the installation went correctly: start Chromium, open {{ic|chrome://plugins/}} and check if "Chrome PDF Viewer" is available (it may need to be enabled).<br />
<br />
{{Note|As a new version of Chromium will not update {{ic|libpdf.so}}, it may become incompatible. Thus and with respect to possible security fixes it is advisable to update both at the same time.}}<br />
<br />
==== Using mozplugger ====<br />
<br />
{{Box||See the main article: [[Browser Plugins#MozPlugger]]|#E5E5FF|#FCFCFC}}<br />
<br />
==== Using the KParts plugin ====<br />
<br />
{{Box||See the main article: [[Browser Plugins#kpartsplugin]]|#E5E5FF|#FCFCFC}}<br />
<br />
=== Certificates ===<br />
<br />
Chromium uses [[Nss|NSS]] for the certificate management. Certificates can be managed in {{ic|Settings}} → {{ic|Show advanced settings...}} → {{ic|Manage Certificates...}}.<br />
<br />
== Tips and tricks ==<br />
<br />
{{Box||See the main article: [[Chromium Tips and Tweaks]]|#E5E5FF|#FCFCFC}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Cracking Sound ===<br />
<br />
There have been reports of cracking sound with chromium over hdmi audio. Start chromium with a different audio buffer size to fix the issue:<br />
{{bc|<nowiki><br />
$ chromium --audio-buffer-size=2048<br />
</nowiki>}}<br />
<br />
=== Proxy settings ===<br />
<br />
There have been many situations in which proxy settings do not work properly, especially if set through the KDE interface. A good method as of now is to use Chromium's command-line options, like {{ic|--proxy-pac-url}} and {{ic|--proxy-server}}, to set your proxy.<br />
<br />
=== Default profile ===<br />
<br />
If you cannot get your default profile when you try to run Chromium and get a similar error instead:<br />
{{hc|$ chromium|<br />
[2630:2630:485325611:FATAL:chrome/browser/browser_main.cc(755)] Check failed: profile. <br />
Cannot get default profile. Trace/breakpoint trap<br />
}}<br />
<br />
You have to set the correct owner of the directory {{ic|~/.config/chromium}} as following:<br />
# chown -R ''yourusername'':''yourusergroup'' ~/.config/chromium<br />
<br />
=== WebGL ===<br />
<br />
Sometimes, Chromium will disable WebGL with certain graphics card configurations. This can generally be remedied by typing {{ic|about:flags}} into the URL bar and enabling the WebGL flag. You may also enable WebGL by passing the command line flag {{ic|--enable-webgl}} to Chromium in the terminal.<br />
<br />
There is also the possibility that your graphics card has been blacklisted by Chromium. To override this use the {{ic|--ignore-gpu-blacklist}} flag or go to {{ic|about:flags}} and enable {{ic|Override software rendering list}}.<br />
<br />
=== Google Play and Flash ===<br />
<br />
DRM content on Flash still requires HAL to play. This is readily apparent with Google Play Movies. If one attempts to play a Google Play movie without HAL, they will receive a YouTube-like screen, but the video will not play. See [[Amazon Instant Video]] for information about installing HAL.<br />
<br />
{{Note|It is necessary to use {{Pkg|flashplugin}} since {{AUR|chromium-pepper-flash}} does not work with this method.}}<br />
<br />
=== Force 3D acceleration in Pepper Flash Player and i.g. the browser with radeon driver ===<br />
<br />
To force 3D rendering there is an option "Override software rendering list" in {{ic|chrome://flags}}, also you would have to export video acceleration variables, see [[ATI#Enabling_video_acceleration]]. You could check if it is working in {{ic|chrome://gpu}}.<br />
<br />
== See also ==<br />
<br />
* [http://www.chromium.org/Home Chromium homepage]<br />
* [http://googlechromereleases.blogspot.com Google Chrome release notes]<br />
* [https://chrome.google.com/webstore/category/home Chrome web store]<br />
* [[Wikipedia: Chromium_(web_browser)#Differences_from_Google_Chrome|Differences between Chromium and Google Chrome]]<br />
* [http://peter.sh/experiments/chromium-command-line-switches/ List of Chromium command-line switches]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=FFmpeg&diff=282723FFmpeg2013-11-13T23:46:28Z<p>Bluerider: /* x264: constant rate factor */</p>
<hr />
<div>[[Category:Audio/Video]]<br />
From the project [http://www.ffmpeg.org/ home page]:<br />
:''FFmpeg is a complete, cross-platform solution to record, convert and stream audio and video. It includes libavcodec - the leading audio/video codec library.''<br />
<br />
== Package installation ==<br />
<br />
[[pacman|Install]] {{Pkg|ffmpeg}} from the [[official repositories]].<br />
<br />
Notable variants in the [[AUR]]:<br />
* {{AUR|ffmpeg-git}} – Installs current FFmpeg from git master.<br />
* {{AUR|ffmpeg-full}} – Attempts to enable all supported external libraries.<br />
* {{AUR|ffmbc}} – Fork. Targeted for professional broadcast usage.<br />
* {{AUR|libav-git}} – Fork. The binary it provides is called {{ic|avconv}} instead of {{ic|ffmpeg}}.<br />
<br />
{{Note|These packages should not be considered to be "drop-in" replacements for {{Pkg|ffmpeg}}.}}<br />
<br />
== Encoding examples ==<br />
<br />
=== Screen cast to .webm ===<br />
<br />
Using ''x11grab'' to video grab your display and using ''ALSA'' for sound. First we create lossless raw file {{ic|test.mkv}}.<br />
<br />
$ ffmpeg -f x11grab -r 30 -i :0.0 -f alsa -i hw:0,0 -acodec flac -vcodec ffvhuff test.mkv<br />
<br />
Then we process this {{ic|test.mkv}} file into a smaller {{ic|test.webm}} end product. Complex switches like {{ic|c:a}} and {{ic|c:v}} convert the stream into what's needed for [http://en.wikipedia.org/wiki/WebM WebM].<br />
<br />
$ ffmpeg -y -i test.mkv -c:a libvorbis -q:a 3 -c:v libvpx -b:v 2000k test.webm<br />
<br />
See https://github.com/kaihendry/recordmydesktop2.0/ for a more fleshed out example.<br />
<br />
=== Recording webcam ===<br />
<br />
FFmpeg supports grabbing input from Video4Linux2 devices. The following command will record a video from the webcam, assuming that the webcam is correctly recognized under {{ic|/dev/video0}}:<br />
<br />
$ ffmpeg -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
The above produces a silent video. It is also possible to include audio sources from a microphone. The following command will include a stream from the default [[Advanced Linux Sound Architecture|ALSA]] recording device into the video:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
To use [[PulseAudio]] with an ALSA backend:<br />
<br />
$ ffmpeg -f alsa -i pulse -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
For a higher quality capture, try encoding the output using higher quality codecs:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 -acodec flac \<br />
-vcodec libx264 ''output''.mkv<br />
<br />
=== VOB to any container ===<br />
<br />
Concatenate the desired [[Wikipedia:VOB|VOB]] files into a single VOB file: <br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB<br />
Concatenate and then pipe the output VOB to FFmpeg to use a different format:<br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB | ffmpeg -i ...<br />
<br />
=== x264 lossless ===<br />
<br />
The ''ultrafast'' preset will provide the fastest encoding and is useful for quick capturing (such as screencasting):<br />
$ ffmpeg -i input -vcodec libx264 -preset ultrafast -qp 0 -acodec copy ''output.mkv''<br />
On the opposite end of the preset spectrum is ''veryslow'' and will encode slower than ''ultrafast'' but provide a smaller output file size:<br />
$ ffmpeg -i input -vcodec libx264 -preset veryslow -qp 0 -acodec copy ''output.mkv''<br />
Both examples will provide the same quality output.<br />
<br />
=== Single-pass MPEG-2 (near lossless) ===<br />
<br />
Allow FFmpeg to automatically set DVD standardized parameters. Encode to DVD [[Wikipedia:MPEG-2|MPEG-2]] at a frame rate of 30 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target ntsc-dvd -q:a 0 -q:v 0 ''output''.mpg<br />
<br />
Encode to DVD MPEG-2 at a frame rate of 24 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target film-dvd -q:a 0 -q:v 0 ''output''.mpg<br />
<br />
=== x264: constant rate factor ===<br />
<br />
Used when you want a specific quality output. General usage is to use the highest {{ic|-crf}} value that still provides an acceptable quality. Lower values are higher quality; 0 is lossless, 18 is visually lossless, and 23 is the default value. A sane range is between 18 and 28. Use the slowest {{ic|-preset}} you have patience for. See the [https://ffmpeg.org/trac/ffmpeg/wiki/x264EncodingGuide x264 Encoding Guide] for more information.<br />
$ ffmpeg -i ''video'' -vcodec libx264 -preset slow -crf 22 -acodec libmp3lame -aq 4 ''output''.mkv<br />
{{ic|-tune}} option can be used to [http://forum.doom9.org/showthread.php?t=149394 match the type and content of the of media being encoded].<br />
<br />
=== YouTube ===<br />
<br />
FFmpeg is very useful to encode videos and strip their size before you upload them on YouTube. The following single line of code takes an input file and outputs a mkv container. <br />
<br />
$ ffmpeg -i ''video'' -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy ''output''.mkv<br />
<br />
For more information see the [https://bbs.archlinux.org/viewtopic.php?pid=1200667#p1200667 forums]. You can also create a custom alias {{ic|ytconvert}} which takes the name of the input file as first argument and the name of the .mkv container as second argument. To do so add the following to your {{ic|~/.bashrc}}:<br />
<br />
{{bc|<nowiki><br />
youtubeConvert(){<br />
ffmpeg -i $1 -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy $2.mkv<br />
}<br />
alias ytconvert=youtubeConvert<br />
</nowiki>}}<br />
See also [https://bbs.archlinux.org/viewtopic.php?pid=1200542#p1200542 Arch Linux forum thread].<br />
<br />
=== Two-pass x264 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are recorded during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec libx264 -pass 1 -preset veryslow \<br />
-threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 -f rawvideo -y /dev/null<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.mkv}}):<br />
$ ffmpeg -i ''video''.VOB -acodec libvo-aacenc -ab 256k -ar 96000 -vcodec libx264 \<br />
-pass 2 -preset veryslow -threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 ''video''.mkv<br />
<br />
{{Tip|If you receive {{ic|Unknown encoder 'libvo-aacenc'}} error (given the fact that your ffmpeg is compiled with libvo-aacenc enabled), you may want to try {{ic|-acodec libvo_aacenc}}, an underscore instead of hyphen.}}<br />
<br />
=== Two-pass MPEG-4 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are logged during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec mpeg4 -pass 1 -mbd 2 -trellis 2 -flags +cbp+mv0 \<br />
-pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 -b 3000k \<br />
-f rawvideo -y /dev/null<br />
<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.avi}}):<br />
$ ffmpeg -i ''video''.VOB -acodec copy -vcodec mpeg4 -vtag DX50 -pass 2 -mbd 2 -trellis 2 \<br />
-flags +cbp+mv0 -pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 \<br />
-b 3000k ''video''.avi<br />
* Introducing {{ic|threads}}={{ic|n}}>{{ic|1}} for {{ic|-vcodec mpeg4}} may skew the effects of [[Wikipedia:Motion_estimation|motion estimation]] and lead to [http://ffmpeg.org/faq.html#Why-do-I-see-a-slight-quality-degradation-with-multithreaded-MPEG_002a-encoding_003f reduced video quality] and compression efficiency.<br />
* The two-pass MPEG-4 example above also supports output to the [[Wikipedia:MPEG-4_Part_14|MP4]] container (replace {{ic|.avi}} with {{ic|.mp4}}).<br />
<br />
==== Determining bitrates with fixed output file sizes ====<br />
<br />
* (Desired File Size in MB - Audio File Size in MB) '''x''' 8192 kb/MB '''/''' Length of Media in Seconds (s) '''=''' [[Wikipedia:Bitrate|Bitrate]] in kb/s<br />
:* (3900 MB - 275 MB) = 3625 MB '''x''' 8192 kb/MB '''/''' 8830 s = 3363 kb/s required to achieve an approximate total output file size of 3900 MB<br />
<br />
=== Adding subtitles ===<br />
<br />
See http://trac.ffmpeg.org/wiki/How%20to%20burn%20subtitles%20into%20the%20video<br />
<br />
==== Softsubs to hardsubs ====<br />
<br />
If have a softsubbed video (eg. ASS/SSA subs in a mkv container like most anime) you can 'burn' these subs into a new file to be played on a device which does not support subs or is to weak to display complex subs.<br />
<br />
* Install {{Pkg|mkvtoolnix-cli}} to pull out {{ic|.ass}} files from {{ic|.mkv}} files.<br />
<br />
* Recompile FFmpeg with {{ic|--enable-libass}} if it is not already enabled in your FFmpeg build. See [[ABS]] for easy recompiling.<br />
<br />
* Pull out subs from your file. This command assumes that track #2 is the ASS/SSA track. Use {{ic|mkvinfo}} if it is not.<br />
$ mkvextract tracks ''your file''.mkv 2:''your file''.ass<br />
<br />
* Recode file with ffmpeg. See sections above for suitable options. It is very important to disable sub-recording and enable sub-rendering:<br />
$ ffmpeg ... -sn -vf ass=''subtitles''.ass<br />
<br />
Output is set as *.mp4 since the default Android 4.2 player dislikes *.mkv. (But VLC on Android works with mkv). Example:<br />
$ ffmpeg -i ''video''.mkv -sn -vcodec libx264 -crf 18 -preset slow -vf ass=''subtitles''.ass -acodec copy ''output''.mp4<br />
<br />
=== Volume gain ===<br />
<br />
Change the audio volume in multiples of 256 where '''256 = 100%''' (normal) volume. Additional values such as 400 are also valid options. <br />
-vol 256 = 100%<br />
-vol 512 = 200%<br />
-vol 768 = 300%<br />
-vol 1024 = 400%<br />
-vol 2048 = 800%<br />
<br />
To double the volume '''(512 = 200%)''' of an [[Wikipedia:Mp3|MP3]] file:<br />
$ ffmpeg -i ''file''.mp3 -vol 512 ''louder file''.mp3<br />
<br />
To quadruple the volume '''(1024 = 400%)''' of an [[Wikipedia:Ogg|Ogg]] file:<br />
$ ffmpeg -i ''file''.ogg -vol 1024 ''louder file''.ogg<br />
<br />
Note that gain metadata is only written to the output file. Unlike mp3gain or ogggain, the source sound file is untouched.<br />
<br />
=== Extracting audio ===<br />
<br />
{{hc|$ ffmpeg -i ''video''.mpg|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: ac3, 48000 Hz, stereo, s16, 384 kb/s<br />
Stream #0.2: Audio: ac3, 48000 Hz, 5.1, s16, 448 kb/s<br />
Stream #0.3: Audio: dts, 48000 Hz, 5.1 768 kb/s<br />
...<br />
}}<br />
<br />
Extract the first ({{ic|-map 0:1}}) [[Wikipedia:Dolby_Digital|AC-3]] encoded audio stream exactly as it was multiplexed into the file: <br />
$ ffmpeg -i ''video''.mpg -map 0:1 -acodec copy -vn ''video''.ac3<br />
Convert the third ({{ic|-map 0:3}}) [[Wikipedia:DTS_(sound_system)|DTS]] audio stream to an [[Wikipedia:Advanced_Audio_Coding|AAC]] file with a bitrate of 192 kb/s and a [[Wikipedia:Sampling_rate|sampling rate]] of 96000 Hz:<br />
$ ffmpeg -i ''video''.mpg -map 0:3 -acodec libvo-aacenc -ab 192k -ar 96000 -vn ''output''.aac<br />
{{ic|-vn}} disables the processing of the video stream.<br />
<br />
Extract audio stream with certain time interval: <br />
$ ffmpeg -ss 00:01:25 -t 00:00:05 -i ''video''.mpg -map 0:1 -acodec copy -vn ''output''.ac3<br />
{{ic|-ss}} specifies the start point, and {{ic|-t}} specifies the duration.<br />
<br />
=== Stripping audio ===<br />
<br />
# Copy the first video stream ({{ic|-map 0:0}}) along with the second AC-3 audio stream ({{ic|-map 0:2}}).<br />
# Convert the AC-3 audio stream to two-channel MP3 with a bitrate of 128 kb/s and a sampling rate of 48000 Hz.<br />
$ ffmpeg -i ''video''.mpg -map 0:0 -map 0:2 -vcodec copy -acodec libmp3lame \<br />
-ab 128k -ar 48000 -ac 2 ''video''.mkv<br />
<br />
{{hc|$ ffmpeg -i ''video''.mkv|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: mp3, 48000 Hz, stereo, s16, 128 kb/s<br />
}}<br />
<br />
{{Note|Removing undesired audio streams allows for additional bits to be allocated towards improving video quality.}}<br />
<br />
== Preset files ==<br />
<br />
Populate {{ic|~/.ffmpeg}} with the default [http://ffmpeg.org/ffmpeg-doc.html#SEC13 preset files]: <br />
<br />
$ cp -iR /usr/share/ffmpeg ~/.ffmpeg<br />
<br />
Create new and/or modify the default preset files:<br />
<br />
{{hc|~/.ffmpeg/libavcodec-vhq.ffpreset|2=<br />
vtag=DX50<br />
mbd=2<br />
trellis=2<br />
flags=+cbp+mv0<br />
pre_dia_size=4<br />
dia_size=4<br />
precmp=4<br />
cmp=4<br />
subcmp=4<br />
preme=2<br />
qns=2<br />
}}<br />
<br />
=== Using preset files ===<br />
<br />
Enable the {{ic|-vpre}} option after declaring the desired {{ic|-vcodec}}<br />
<br />
==== libavcodec-vhq.ffpreset ====<br />
<br />
* {{ic|libavcodec}} '''=''' Name of the vcodec/acodec<br />
* {{ic|vhq}} '''=''' Name of specific preset to be called out<br />
* {{ic|ffpreset}} '''=''' FFmpeg preset filetype suffix <br />
<br />
===== Two-pass MPEG-4 (very high quality) =====<br />
<br />
First pass of a multipass (bitrate) ratecontrol transcode:<br />
$ ffmpeg -i ''video''.mpg -an -vcodec mpeg4 -pass 1 -vpre vhq -f rawvideo -y /dev/null<br />
Ratecontrol based on the video statistics logged from the first pass: <br />
$ ffmpeg -i ''video''.mpg -acodec libvorbis -aq 8 -ar 48000 -vcodec mpeg4 \<br />
-pass 2 -vpre vhq -b 3000k ''output''.mp4<br />
<br />
* '''libvorbis quality settings (VBR)'''<br />
:* {{ic|-aq 4}} = 128 kb/s<br />
:* {{ic|-aq 5}} = 160 kb/s<br />
:* {{ic|-aq 6}} = 192 kb/s<br />
:* {{ic|-aq 7}} = 224 kb/s<br />
:* {{ic|-aq 8}} = 256 kb/s<br />
<br />
* [http://www.geocities.jp/aoyoume/aotuv/ aoTuV] is generally preferred over [http://vorbis.com/ libvorbis] provided by [http://www.xiph.org/ Xiph.Org] and is provided by [https://aur.archlinux.org/packages.php?ID=6155 libvorbis-aotuv] in the [[AUR]].<br />
<br />
== Package removal ==<br />
<br />
[[pacman]] will not [[Pacman#Removing_packages|remove]] configuration files outside of the defaults that were created during package installation. This includes user-created preset files.<br />
<br />
== See also ==<br />
<br />
* [http://mewiki.project357.com/wiki/X264_Settings x264 Settings] - MeWiki documentation<br />
* [http://ffmpeg.org/ffmpeg-doc.html FFmpeg documentation] - official documentation<br />
* [http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-x264.html Encoding with the x264 codec] - MEncoder documentation<br />
* [http://avidemux.org/admWiki/doku.php?id=tutorial:h.264 H.264 encoding guide] - Avidemux wiki<br />
* [http://howto-pages.org/ffmpeg/ Using FFmpeg] - Linux how to pages<br />
* [http://ffmpeg.org/general.html#Supported-File-Formats-and-Codecs List] of supported audio and video streams</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Webcam_setup&diff=279608Webcam setup2013-10-24T14:12:44Z<p>Bluerider: /* Microsoft Lifecam Studio/Cinema */</p>
<hr />
<div>[[Category:Imaging]]<br />
[[Category:Other hardware]] <br />
[[ru:Webcam Setup]]<br />
[[zh-CN:Webcam Setup]]<br />
This is a guide to setting up your webcam in Arch Linux.<br />
<br />
== Linux webcam support ==<br />
<br />
Most probably your webcam will work out of the box. In that case you may skip to section [[Webcam_Setup#Webcam configuration]] if you want to configure color, brightness and other parameters. Otherwise follow the steps below.<br />
<br />
== Identify your webcam ==<br />
<br />
Identify the name of your webcam (using, for example, {{Ic|lsusb}}) and find a proper driver. Below is a list of webcams, and what drivers they work with. Click on the link to the right of the device name for information on compiling modules and other information. If you get your webcam to work, add the name of the webcam and the driver you used to the list!<br />
<br />
=== pwc ===<br />
<br />
* Creative Labs Webcam Pro Ex<br />
* Logitech QuickCam Notebook Pro (only the "Pro" models)<br />
* Logitech Quickcam Pro 4000<br />
* Philips ToUCams (not confirmed at the moment, but it is using the pwc driver if I remember correctly)<br />
* Philips SPC900NC<br />
<br />
=== [[qc-usb]] ===<br />
<br />
* Dexxa Webcam<br />
* Labtec Webcam (old model) <br />
* LegoCam<br />
* Logitech Quickcam Express (old model)<br />
* Logitech QuickCam Notebook (not the "Pro" models)<br />
* Logitech Quickcam Web<br />
<br />
=== qc-usb-messenger ===<br />
<br />
* Logitech Quickcam Messenger<br />
* Logitech Quickcam Communicate (for Communicate MP/S5500 or "for Business" see the linux-uvc section below)<br />
<br />
It is now in the community repo.<br />
<br />
{{Note|<br />
* If qc-usb-messenger does not work use the gspca module, by installing the gspcav1 package.<br />
* Now this driver is a module included in kernel 2.6.27.<br />
}}<br />
<br />
=== zr364xx ===<br />
<br />
This driver can be used for many webcams like:<br />
* Aiptek PocketDV 3300<br />
* Creative PC-CAM 880<br />
* Konica Revio 2<br />
* Genius Digital Camera<br />
* Maxell Maxcam PRO DV3<br />
You can find the full list of supported devices [http://royale.zerezo.com/zr364xx/ here]. You can find a PKGBUILD for this driver in the [[Arch User Repository|AUR]].<br />
<br />
=== sn9c102 ===<br />
<br />
* Trust Spacecam series<br />
* Maxell Smartcam (for notebooks): 352x288 max. resolution @ 3fps<br />
<br />
=== gspca ===<br />
<br />
An extensive list of supported webcams is available [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/video4linux/gspca.txt;hb=HEAD].<br />
<br />
{{Note|This driver does not have V4L1 support.}}<br />
<br />
=== stv680 ===<br />
<br />
Many cheap no-name cameras that came out Asia in the last couple of years use the stv680 chipset. Most of these cameras were novelty items (i.e. Pencam, SpyC@m and LegoCam). <br />
* Aiptek PenCam series<br />
* Digitaldream series<br />
* Dolphin Peripherals series<br />
* Lego LegoCam<br />
* Trust SpyC@m series<br />
* Welback Coolcam<br />
<br />
A more-complete list of webcams that use the stv680 chipset is available [http://webcam-osx.sourceforge.net/cameras/index.php?orderBy=controller here].<br />
<br />
=== linux-uvc ===<br />
<br />
* Genius iLook 1321<br />
* Logitech Webcam C250<br />
* Logitech Webcam C270<br />
* Logitech Webcam C600<br />
* Logitech HD Webcam C525<br />
* Logitech Quickcam Pro 5000<br />
* Logitech Quickcam Pro 9000<br />
* Logitech Quickcam Orbit AF<br />
* Logitech Quickcam Orbit MP<br />
* Logitech Quickcam S5500<br />
* Microdia Pavilion Webcam (on MSI PR200)<br />
* Logitech Quickcam Communicate MP/S5500 or "for Business"<br />
* Chicony Electronics CNF7051<br />
<br />
You can find a full list of supported UVC devices [http://linux-uvc.berlios.de/ here].<br />
<br />
As of kernel 2.6.26 linux-uvc is part of the kernel. Just load the uvcvideo module.<br />
<br />
{{Note|<br />
* This driver does not have V4L1 support.<br />
* With WebCam SCB-0385N (usb ID 2232:1005), WebCam SC-0311139N (usb ID 2232:1020) and WebCam SC-03FFL11939N (usb ID 2232:1028), you might need to add some configuration to the module if the usage of the camera makes the system freeze : <br />
{{hc|1=/etc/modprobe.d/uvcvideo.conf|2=options uvcvideo nodrop=1}} }}<br />
<br />
=== ov51x-jpeg ===<br />
<br />
* Sony EyeToy<br />
* Chicony DC-2120 <br />
* Chicony DC-2120 pro<br />
* Trust Spacecam 320<br />
* Hercules Webcam Deluxe <br />
* Hercules Webcam Classic <br />
* Creative Live! Cam Notebook Pro VF0400 <br />
* Creative Live! Cam Vista IM <br />
* Creative Live! Cam Vista IM VF0420 <br />
* Creative Vista Webcam VF0330 <br />
* ASUS webcam Model? <br />
* Philips PCVC820K/00 <br />
* NGS showtime plus <br />
* HP VGA Webcam with Integrated Microphone<br />
<br />
This is a kernel module found in the AUR with some additions to the original driver that provide jpeg decompression.<br />
<br />
For me to get my "Creative Live! Cam Vista IM" working with Skype, I had to add this line to {{ic|/etc/modprobe.d/modprobe.conf}}:<br />
options ov51x-jpeg forceblock=1<br />
<br />
=== r5u870 (Ricoh) ===<br />
<br />
* HP Pavilion Webcam<br />
* HP Webcam 1000<br />
* Sony VAIO VGP-VCCx<br />
<br />
The Ricoh webcam is built into most new Sony laptops.<br />
<br />
Install {{AUR|r5u87x-hg}} (provides firmware too) and run the {{ic|loader}} command.<br />
<br />
=== stk11xx (Syntek) ===<br />
<br />
* Integrated camera in lot of Asus laptops<br />
* Asus A8J, F3S, F5R, F5GL, F9E, VX2S, V1S, A6T<br />
<br />
Just install the {{AUR|stk11xx}} AUR package. It contains the right kernel module.<br />
<br />
== Make sure the module is loaded for your webcam ==<br />
<br />
Add your webcam's [[Kernel modules#Loading|module]] in {{ic|/etc/modules-load.d/webcam.conf}} so it will be loaded into the kernel during init stage bootstrapping.<br />
<br />
If your webcam is USB, the kernel ''should'' automatically load the proper driver. If this is the case, check dmesg after you plug your webcam in. You should see something like this:<br />
<br />
{{hc|<nowiki>$ dmesg|tail</nowiki>|<nowiki><br />
sn9c102: V4L2 driver for SN9C10x PC Camera Controllers v1:1.24a<br />
usb 1-1: SN9C10[12] PC Camera Controller detected (vid/pid 0x0C45/0x600D)<br />
usb 1-1: PAS106B image sensor detected<br />
usb 1-1: Initialization succeeded<br />
usb 1-1: V4L2 device registered as /dev/video0<br />
usb 1-1: Optional device control through 'sysfs' interface ready<br />
usbcore: registered new driver sn9c102<br />
</nowiki>}}<br />
<br />
== Permissions ==<br />
<br />
In order to use your webcam, you need to have permission to use {{ic|/dev/video0}}.<br />
<br />
=== udev ===<br />
<br />
If you use [[udev]], you only need to be in the group ''video''. You can check it with:<br />
$ groups<br />
To add a user to the group run under root:<br />
# gpasswd -a <username> video<br />
Note the next two steps may not be required as they should already be set by [[udev]]<br />
<br />
Set group of device to video:<br />
# chgrp video /dev/video0<br />
Set permissions of the device:<br />
# chmod 660 /dev/video0<br />
<br />
{{Tip|If you need to load webcams in order (i.e. get the /dev/video0..n device order) or set ownership or permissions, take a look at writing rules for [[Udev#Writing udev rules|Writing udev rules]].}}<br />
<br />
=== devfs ===<br />
<br />
Add the following to your {{ic|/etc/devfsd.conf}}. This will give normal users permission to use {{ic|/dev/video0}} (your webcam).<br />
REGISTER video0 PERMISSIONS root.users 0660<br />
<br />
== Webcam configuration ==<br />
<br />
If you want to configure brightness, color and other webcam parameters (e.g. in the case when out-of-the-box colors are too bluish/reddish/greenish) you may use [http://guvcview.berlios.de/ GTK+ UVC Viewer] (guvcview), available in the [[Official Repositories]] as package {{Pkg|guvcview}}. Just install it and launch, and it will present you a list of configurable settings. Changing these settings will affect all applications (e.g. Skype).<br />
<br />
== Get software to use your webcam ==<br />
<br />
Version 2.6.27 of the Linux kernel supports [http://mxhaard.free.fr/spca5xx.html many new webcam drivers]. Legacy Video4Linux API has been dropped, and these drivers now only support Video4Linux version 2. Pixel format decoding has been pushed to user space, since Video4Linux version 2 does not support kernel space decoding. The libv4l library provides userland applications with pixel decoding services and will be used by most programs. Other compatibility layers are also available.<br />
<br />
'''If your device is created but your image looks strange (mine was nearly completely green), you probably need this.'''<br />
<br />
If the application has V4L2 support but no pixelformat support (eg: cheese) then use the following command:<br />
LD_PRELOAD=/usr/lib/libv4l/v4l2convert.so cheese<br />
<br />
If the application only supports the older version of V4L (Skype is the most popular of this kind of software) then use this command:<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
{{Tip|1=You also might want to put a line like the following into {{ic|/etc/profile}} or [[xprofile]] so you do not have to type that long command all the time:<br />
{{bc|1=export LD_PRELOAD=/usr/'$LIB'/libv4l/v4l2convert.so}}<br />
or<br />
{{bc|1=export LD_PRELOAD=/usr/'$LIB'/libv4l/v4l1compat.so}}<br />
}}<br />
<br />
For 32-bit applications (e.g. Skype) within Arch64, install the {{Pkg|lib32-v4l-utils}} package.<br />
<br />
If the webcam works fine on guvcview, but it does not work in Skype, you may also need to set <br />
export XLIB_SKIP_ARGB_VISUALS=1<br />
before starting it.<br />
<br />
=== Cheese ===<br />
<br />
Cheese is the GNOME photo/video taking client. It is similar to Photo Booth in Mac OS X. It is in the official repositories.<br />
<br />
=== GTK+ UVC Viewer (guvcview) ===<br />
<br />
In addition to being a convenient way to configure your webcam, [http://guvcview.berlios.de/ guvcview] also allows capturing (with sound!) and viewing video from devices supported by the Linux UVC driver. Available in the [[official repositories]] as package {{Pkg|guvcview}}. Just install it and launch, and it will present you a list of configurable settings. Changing these settings will affect all applications (e.g. Skype).<br />
<br />
=== Kopete ===<br />
<br />
Kopete is the [[KDE]] instant messaging (IM) client. As of KDE 3.5, it has support for MSN and Yahoo! webcams, but not every cam works yet. It is included in the kdenetwork package.<br />
<br />
=== Kamoso ===<br />
<br />
Application to take pictures and videos out of your webcam for KDE.<br />
Available in the AUR: {{AUR|kamoso}}.<br />
<br />
=== xawtv ===<br />
<br />
This is a basic v4l device viewer, and although it is intended for use with TV tuner cards, it works well with webcams. It will display what your webcam sees in a window. Install it ({{Pkg|xawtv}}) and run it with:<br />
$ xawtv -c /dev/video0<br />
If you are using an nVidia graphic card, and you get an error like<br />
X Error of failed request: XF86DGANoDirectVideoMode<br />
Major opcode of failed request: 139 (XFree86-DGA)<br />
Minor opcode of failed request: 1 (XF86DGAGetVideoLL)<br />
Serial number of failed request: 69<br />
Current serial number in output stream: 69<br />
you should instead run it as:<br />
$ xawtv -nodga<br />
google talk<br />
<br />
=== VLC ===<br />
<br />
[[VLC]] can also be used to view and record your webcam. In VLC's file menu, open the 'Capture Device...' dialog and enter the video and audio device files. Or from the command line, do:<br />
$ vlc v4l:// :v4l-vdev="/dev/video0" :v4l-adev="/dev/audio2"<br />
This will make VLC mirror your webcam. To take stills, simply choose 'Snapshot' in the 'Video' menu. To record the stream, you add a {{ic|--sout}} argument, e.g.<br />
$ vlc v4l:// :v4l-vdev="/dev/video0" :v4l-adev="/dev/audio2" \ <br />
--sout "#transcode{vcodec=mp1v,vb=1024,scale=1,acodec=mpga,ab=192,channels=2}:duplicate{dst=std{access=file,mux=mpeg1,dst=/tmp/test.mpg}}"<br />
<br />
(Obviously a bit overkill with regard to the bit rates but it is fine for testing purposes.) Notice that this will not produce a mirror on the display - in order to see what you are recording, you would need to add the display as a destination to the argument:<br />
... :duplicate{dst=display,dst=std{access= ....<br />
(Though this can tax older hardware somewhat...)<br />
<br />
=== MPlayer ===<br />
<br />
To use [[MPlayer]] to take snapshots from your webcam run this command from the terminal:<br />
$ mplayer tv:// -tv driver=v4l2:width=640:height=480:device=/dev/video0 -fps 15 -vf screenshot<br />
From here you have to press {{ic|s}} to take the snapshot. The snapshot will be saved in your current folder as '''shotXXXX.png'''.<br />
If you want to record continuous video:<br />
$ mencoder tv:// -tv driver=v4l2:width=640:height=480:device=/dev/video0:forceaudio:adevice=/dev/dsp -ovc lavc -oac mp3lame -lameopts cbr:br=64:mode=3 -o ''filename''.avi<br />
Press {{ic|Ctrl+c}} to end the recording.<br />
<br />
=== FFmpeg ===<br />
<br />
See [[FFmpeg#Recording webcam]].<br />
<br />
=== ekiga ===<br />
<br />
This is very similar to Microsoft NetMeeting. <br />
Install the {{pkg|ekiga}} package from the official repositories.<br />
The configuration druid will set everything up for you.<br />
<br />
=== Sonic-snap ===<br />
<br />
Sonic-snap [http://www.stolk.org/sonic-snap/] is a viewer/grabber for sn9c102-based webcams '''only'''.<br />
{{AUR|sonic-snap}} is available in the AUR.<br />
<br />
=== Skype === <br />
<br />
The newest version of [[Skype]] has video support. Check Video Devices in the options for a test image which you can double-click to make full screen. Install the {{pkg|skype}} package.<br />
If you get green/disorted picture with skype read the section [[Webcam_Setup#Get software to use your webcam]] above.<br />
<br />
If your running x86-64 you might actually need to install {{Pkg|lib32-v4l-utils}} and then run skype with<br />
LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype<br />
You can either set an alias for skype, or rename the original skype binary in {{ic|/usr/bin}} and create a text file containing the above option, or you can simply adjust the Command line in the options for the Skype icon in your favourite desktop environment.<br />
<br />
=== Motion ===<br />
<br />
:''Motion is a program that monitors the video signal from cameras. It is able to detect if a significant part of the picture has changed; in other words, it can detect motion.''<br />
<br />
{{Pkg|motion}} can only handle v4l2 devices so if you need to use a camera that only has v4l1 drivers you need to preload v4l1compat.so as previously mentioned. Otherwise you will get loads of errors about motion not able to find a suitable palette.<br />
<br />
{{Tip|If you need to load webcams in order (i.e. get the /dev/video0..n device order) or set ownership or permissions, take a look at writing rules for [[Udev#Writing udev rules|writing udev rules]].}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Microsoft Lifecam Studio/Cinema===<br />
Under certain configurations, the Microsoft lifecam studio/cinema may request too much usb bandwidth and fail [http://www.ideasonboard.org/uvc/#footnote-13 see Uvcvideo FAQ]. In this case try loading the {{ic|uvcvideo}} driver with {{ic|quirks<nowiki>=</nowiki>0x80}}. Add it to {{ic|/etc/modprobe.d/uvcvideo.conf}} :<br />
{{hc|/etc/modprobe.d/uvcvideo.conf|<nowiki><br />
## fix bandwidth issue for lifecam studio/cinema<br />
options uvcvideo quirks=0x80<br />
</nowiki>}}</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Webcam_setup&diff=279607Webcam setup2013-10-24T14:12:30Z<p>Bluerider: /* Troubleshooting */</p>
<hr />
<div>[[Category:Imaging]]<br />
[[Category:Other hardware]] <br />
[[ru:Webcam Setup]]<br />
[[zh-CN:Webcam Setup]]<br />
This is a guide to setting up your webcam in Arch Linux.<br />
<br />
== Linux webcam support ==<br />
<br />
Most probably your webcam will work out of the box. In that case you may skip to section [[Webcam_Setup#Webcam configuration]] if you want to configure color, brightness and other parameters. Otherwise follow the steps below.<br />
<br />
== Identify your webcam ==<br />
<br />
Identify the name of your webcam (using, for example, {{Ic|lsusb}}) and find a proper driver. Below is a list of webcams, and what drivers they work with. Click on the link to the right of the device name for information on compiling modules and other information. If you get your webcam to work, add the name of the webcam and the driver you used to the list!<br />
<br />
=== pwc ===<br />
<br />
* Creative Labs Webcam Pro Ex<br />
* Logitech QuickCam Notebook Pro (only the "Pro" models)<br />
* Logitech Quickcam Pro 4000<br />
* Philips ToUCams (not confirmed at the moment, but it is using the pwc driver if I remember correctly)<br />
* Philips SPC900NC<br />
<br />
=== [[qc-usb]] ===<br />
<br />
* Dexxa Webcam<br />
* Labtec Webcam (old model) <br />
* LegoCam<br />
* Logitech Quickcam Express (old model)<br />
* Logitech QuickCam Notebook (not the "Pro" models)<br />
* Logitech Quickcam Web<br />
<br />
=== qc-usb-messenger ===<br />
<br />
* Logitech Quickcam Messenger<br />
* Logitech Quickcam Communicate (for Communicate MP/S5500 or "for Business" see the linux-uvc section below)<br />
<br />
It is now in the community repo.<br />
<br />
{{Note|<br />
* If qc-usb-messenger does not work use the gspca module, by installing the gspcav1 package.<br />
* Now this driver is a module included in kernel 2.6.27.<br />
}}<br />
<br />
=== zr364xx ===<br />
<br />
This driver can be used for many webcams like:<br />
* Aiptek PocketDV 3300<br />
* Creative PC-CAM 880<br />
* Konica Revio 2<br />
* Genius Digital Camera<br />
* Maxell Maxcam PRO DV3<br />
You can find the full list of supported devices [http://royale.zerezo.com/zr364xx/ here]. You can find a PKGBUILD for this driver in the [[Arch User Repository|AUR]].<br />
<br />
=== sn9c102 ===<br />
<br />
* Trust Spacecam series<br />
* Maxell Smartcam (for notebooks): 352x288 max. resolution @ 3fps<br />
<br />
=== gspca ===<br />
<br />
An extensive list of supported webcams is available [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/video4linux/gspca.txt;hb=HEAD].<br />
<br />
{{Note|This driver does not have V4L1 support.}}<br />
<br />
=== stv680 ===<br />
<br />
Many cheap no-name cameras that came out Asia in the last couple of years use the stv680 chipset. Most of these cameras were novelty items (i.e. Pencam, SpyC@m and LegoCam). <br />
* Aiptek PenCam series<br />
* Digitaldream series<br />
* Dolphin Peripherals series<br />
* Lego LegoCam<br />
* Trust SpyC@m series<br />
* Welback Coolcam<br />
<br />
A more-complete list of webcams that use the stv680 chipset is available [http://webcam-osx.sourceforge.net/cameras/index.php?orderBy=controller here].<br />
<br />
=== linux-uvc ===<br />
<br />
* Genius iLook 1321<br />
* Logitech Webcam C250<br />
* Logitech Webcam C270<br />
* Logitech Webcam C600<br />
* Logitech HD Webcam C525<br />
* Logitech Quickcam Pro 5000<br />
* Logitech Quickcam Pro 9000<br />
* Logitech Quickcam Orbit AF<br />
* Logitech Quickcam Orbit MP<br />
* Logitech Quickcam S5500<br />
* Microdia Pavilion Webcam (on MSI PR200)<br />
* Logitech Quickcam Communicate MP/S5500 or "for Business"<br />
* Chicony Electronics CNF7051<br />
<br />
You can find a full list of supported UVC devices [http://linux-uvc.berlios.de/ here].<br />
<br />
As of kernel 2.6.26 linux-uvc is part of the kernel. Just load the uvcvideo module.<br />
<br />
{{Note|<br />
* This driver does not have V4L1 support.<br />
* With WebCam SCB-0385N (usb ID 2232:1005), WebCam SC-0311139N (usb ID 2232:1020) and WebCam SC-03FFL11939N (usb ID 2232:1028), you might need to add some configuration to the module if the usage of the camera makes the system freeze : <br />
{{hc|1=/etc/modprobe.d/uvcvideo.conf|2=options uvcvideo nodrop=1}} }}<br />
<br />
=== ov51x-jpeg ===<br />
<br />
* Sony EyeToy<br />
* Chicony DC-2120 <br />
* Chicony DC-2120 pro<br />
* Trust Spacecam 320<br />
* Hercules Webcam Deluxe <br />
* Hercules Webcam Classic <br />
* Creative Live! Cam Notebook Pro VF0400 <br />
* Creative Live! Cam Vista IM <br />
* Creative Live! Cam Vista IM VF0420 <br />
* Creative Vista Webcam VF0330 <br />
* ASUS webcam Model? <br />
* Philips PCVC820K/00 <br />
* NGS showtime plus <br />
* HP VGA Webcam with Integrated Microphone<br />
<br />
This is a kernel module found in the AUR with some additions to the original driver that provide jpeg decompression.<br />
<br />
For me to get my "Creative Live! Cam Vista IM" working with Skype, I had to add this line to {{ic|/etc/modprobe.d/modprobe.conf}}:<br />
options ov51x-jpeg forceblock=1<br />
<br />
=== r5u870 (Ricoh) ===<br />
<br />
* HP Pavilion Webcam<br />
* HP Webcam 1000<br />
* Sony VAIO VGP-VCCx<br />
<br />
The Ricoh webcam is built into most new Sony laptops.<br />
<br />
Install {{AUR|r5u87x-hg}} (provides firmware too) and run the {{ic|loader}} command.<br />
<br />
=== stk11xx (Syntek) ===<br />
<br />
* Integrated camera in lot of Asus laptops<br />
* Asus A8J, F3S, F5R, F5GL, F9E, VX2S, V1S, A6T<br />
<br />
Just install the {{AUR|stk11xx}} AUR package. It contains the right kernel module.<br />
<br />
== Make sure the module is loaded for your webcam ==<br />
<br />
Add your webcam's [[Kernel modules#Loading|module]] in {{ic|/etc/modules-load.d/webcam.conf}} so it will be loaded into the kernel during init stage bootstrapping.<br />
<br />
If your webcam is USB, the kernel ''should'' automatically load the proper driver. If this is the case, check dmesg after you plug your webcam in. You should see something like this:<br />
<br />
{{hc|<nowiki>$ dmesg|tail</nowiki>|<nowiki><br />
sn9c102: V4L2 driver for SN9C10x PC Camera Controllers v1:1.24a<br />
usb 1-1: SN9C10[12] PC Camera Controller detected (vid/pid 0x0C45/0x600D)<br />
usb 1-1: PAS106B image sensor detected<br />
usb 1-1: Initialization succeeded<br />
usb 1-1: V4L2 device registered as /dev/video0<br />
usb 1-1: Optional device control through 'sysfs' interface ready<br />
usbcore: registered new driver sn9c102<br />
</nowiki>}}<br />
<br />
== Permissions ==<br />
<br />
In order to use your webcam, you need to have permission to use {{ic|/dev/video0}}.<br />
<br />
=== udev ===<br />
<br />
If you use [[udev]], you only need to be in the group ''video''. You can check it with:<br />
$ groups<br />
To add a user to the group run under root:<br />
# gpasswd -a <username> video<br />
Note the next two steps may not be required as they should already be set by [[udev]]<br />
<br />
Set group of device to video:<br />
# chgrp video /dev/video0<br />
Set permissions of the device:<br />
# chmod 660 /dev/video0<br />
<br />
{{Tip|If you need to load webcams in order (i.e. get the /dev/video0..n device order) or set ownership or permissions, take a look at writing rules for [[Udev#Writing udev rules|Writing udev rules]].}}<br />
<br />
=== devfs ===<br />
<br />
Add the following to your {{ic|/etc/devfsd.conf}}. This will give normal users permission to use {{ic|/dev/video0}} (your webcam).<br />
REGISTER video0 PERMISSIONS root.users 0660<br />
<br />
== Webcam configuration ==<br />
<br />
If you want to configure brightness, color and other webcam parameters (e.g. in the case when out-of-the-box colors are too bluish/reddish/greenish) you may use [http://guvcview.berlios.de/ GTK+ UVC Viewer] (guvcview), available in the [[Official Repositories]] as package {{Pkg|guvcview}}. Just install it and launch, and it will present you a list of configurable settings. Changing these settings will affect all applications (e.g. Skype).<br />
<br />
== Get software to use your webcam ==<br />
<br />
Version 2.6.27 of the Linux kernel supports [http://mxhaard.free.fr/spca5xx.html many new webcam drivers]. Legacy Video4Linux API has been dropped, and these drivers now only support Video4Linux version 2. Pixel format decoding has been pushed to user space, since Video4Linux version 2 does not support kernel space decoding. The libv4l library provides userland applications with pixel decoding services and will be used by most programs. Other compatibility layers are also available.<br />
<br />
'''If your device is created but your image looks strange (mine was nearly completely green), you probably need this.'''<br />
<br />
If the application has V4L2 support but no pixelformat support (eg: cheese) then use the following command:<br />
LD_PRELOAD=/usr/lib/libv4l/v4l2convert.so cheese<br />
<br />
If the application only supports the older version of V4L (Skype is the most popular of this kind of software) then use this command:<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
{{Tip|1=You also might want to put a line like the following into {{ic|/etc/profile}} or [[xprofile]] so you do not have to type that long command all the time:<br />
{{bc|1=export LD_PRELOAD=/usr/'$LIB'/libv4l/v4l2convert.so}}<br />
or<br />
{{bc|1=export LD_PRELOAD=/usr/'$LIB'/libv4l/v4l1compat.so}}<br />
}}<br />
<br />
For 32-bit applications (e.g. Skype) within Arch64, install the {{Pkg|lib32-v4l-utils}} package.<br />
<br />
If the webcam works fine on guvcview, but it does not work in Skype, you may also need to set <br />
export XLIB_SKIP_ARGB_VISUALS=1<br />
before starting it.<br />
<br />
=== Cheese ===<br />
<br />
Cheese is the GNOME photo/video taking client. It is similar to Photo Booth in Mac OS X. It is in the official repositories.<br />
<br />
=== GTK+ UVC Viewer (guvcview) ===<br />
<br />
In addition to being a convenient way to configure your webcam, [http://guvcview.berlios.de/ guvcview] also allows capturing (with sound!) and viewing video from devices supported by the Linux UVC driver. Available in the [[official repositories]] as package {{Pkg|guvcview}}. Just install it and launch, and it will present you a list of configurable settings. Changing these settings will affect all applications (e.g. Skype).<br />
<br />
=== Kopete ===<br />
<br />
Kopete is the [[KDE]] instant messaging (IM) client. As of KDE 3.5, it has support for MSN and Yahoo! webcams, but not every cam works yet. It is included in the kdenetwork package.<br />
<br />
=== Kamoso ===<br />
<br />
Application to take pictures and videos out of your webcam for KDE.<br />
Available in the AUR: {{AUR|kamoso}}.<br />
<br />
=== xawtv ===<br />
<br />
This is a basic v4l device viewer, and although it is intended for use with TV tuner cards, it works well with webcams. It will display what your webcam sees in a window. Install it ({{Pkg|xawtv}}) and run it with:<br />
$ xawtv -c /dev/video0<br />
If you are using an nVidia graphic card, and you get an error like<br />
X Error of failed request: XF86DGANoDirectVideoMode<br />
Major opcode of failed request: 139 (XFree86-DGA)<br />
Minor opcode of failed request: 1 (XF86DGAGetVideoLL)<br />
Serial number of failed request: 69<br />
Current serial number in output stream: 69<br />
you should instead run it as:<br />
$ xawtv -nodga<br />
google talk<br />
<br />
=== VLC ===<br />
<br />
[[VLC]] can also be used to view and record your webcam. In VLC's file menu, open the 'Capture Device...' dialog and enter the video and audio device files. Or from the command line, do:<br />
$ vlc v4l:// :v4l-vdev="/dev/video0" :v4l-adev="/dev/audio2"<br />
This will make VLC mirror your webcam. To take stills, simply choose 'Snapshot' in the 'Video' menu. To record the stream, you add a {{ic|--sout}} argument, e.g.<br />
$ vlc v4l:// :v4l-vdev="/dev/video0" :v4l-adev="/dev/audio2" \ <br />
--sout "#transcode{vcodec=mp1v,vb=1024,scale=1,acodec=mpga,ab=192,channels=2}:duplicate{dst=std{access=file,mux=mpeg1,dst=/tmp/test.mpg}}"<br />
<br />
(Obviously a bit overkill with regard to the bit rates but it is fine for testing purposes.) Notice that this will not produce a mirror on the display - in order to see what you are recording, you would need to add the display as a destination to the argument:<br />
... :duplicate{dst=display,dst=std{access= ....<br />
(Though this can tax older hardware somewhat...)<br />
<br />
=== MPlayer ===<br />
<br />
To use [[MPlayer]] to take snapshots from your webcam run this command from the terminal:<br />
$ mplayer tv:// -tv driver=v4l2:width=640:height=480:device=/dev/video0 -fps 15 -vf screenshot<br />
From here you have to press {{ic|s}} to take the snapshot. The snapshot will be saved in your current folder as '''shotXXXX.png'''.<br />
If you want to record continuous video:<br />
$ mencoder tv:// -tv driver=v4l2:width=640:height=480:device=/dev/video0:forceaudio:adevice=/dev/dsp -ovc lavc -oac mp3lame -lameopts cbr:br=64:mode=3 -o ''filename''.avi<br />
Press {{ic|Ctrl+c}} to end the recording.<br />
<br />
=== FFmpeg ===<br />
<br />
See [[FFmpeg#Recording webcam]].<br />
<br />
=== ekiga ===<br />
<br />
This is very similar to Microsoft NetMeeting. <br />
Install the {{pkg|ekiga}} package from the official repositories.<br />
The configuration druid will set everything up for you.<br />
<br />
=== Sonic-snap ===<br />
<br />
Sonic-snap [http://www.stolk.org/sonic-snap/] is a viewer/grabber for sn9c102-based webcams '''only'''.<br />
{{AUR|sonic-snap}} is available in the AUR.<br />
<br />
=== Skype === <br />
<br />
The newest version of [[Skype]] has video support. Check Video Devices in the options for a test image which you can double-click to make full screen. Install the {{pkg|skype}} package.<br />
If you get green/disorted picture with skype read the section [[Webcam_Setup#Get software to use your webcam]] above.<br />
<br />
If your running x86-64 you might actually need to install {{Pkg|lib32-v4l-utils}} and then run skype with<br />
LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype<br />
You can either set an alias for skype, or rename the original skype binary in {{ic|/usr/bin}} and create a text file containing the above option, or you can simply adjust the Command line in the options for the Skype icon in your favourite desktop environment.<br />
<br />
=== Motion ===<br />
<br />
:''Motion is a program that monitors the video signal from cameras. It is able to detect if a significant part of the picture has changed; in other words, it can detect motion.''<br />
<br />
{{Pkg|motion}} can only handle v4l2 devices so if you need to use a camera that only has v4l1 drivers you need to preload v4l1compat.so as previously mentioned. Otherwise you will get loads of errors about motion not able to find a suitable palette.<br />
<br />
{{Tip|If you need to load webcams in order (i.e. get the /dev/video0..n device order) or set ownership or permissions, take a look at writing rules for [[Udev#Writing udev rules|writing udev rules]].}}<br />
<br />
== Troubleshooting ==<br />
<br />
== Microsoft Lifecam Studio/Cinema==<br />
Under certain configurations, the Microsoft lifecam studio/cinema may request too much usb bandwidth and fail [http://www.ideasonboard.org/uvc/#footnote-13 see Uvcvideo FAQ]. In this case try loading the {{ic|uvcvideo}} driver with {{ic|quirks<nowiki>=</nowiki>0x80}}. Add it to {{ic|/etc/modprobe.d/uvcvideo.conf}} :<br />
{{hc|/etc/modprobe.d/uvcvideo.conf|<nowiki><br />
## fix bandwidth issue for lifecam studio/cinema<br />
options uvcvideo quirks=0x80<br />
</nowiki>}}</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Webcam_setup&diff=279606Webcam setup2013-10-24T14:12:03Z<p>Bluerider: /* Microsoft Lifecam Studio/Cinema */</p>
<hr />
<div>[[Category:Imaging]]<br />
[[Category:Other hardware]] <br />
[[ru:Webcam Setup]]<br />
[[zh-CN:Webcam Setup]]<br />
This is a guide to setting up your webcam in Arch Linux.<br />
<br />
== Linux webcam support ==<br />
<br />
Most probably your webcam will work out of the box. In that case you may skip to section [[Webcam_Setup#Webcam configuration]] if you want to configure color, brightness and other parameters. Otherwise follow the steps below.<br />
<br />
== Identify your webcam ==<br />
<br />
Identify the name of your webcam (using, for example, {{Ic|lsusb}}) and find a proper driver. Below is a list of webcams, and what drivers they work with. Click on the link to the right of the device name for information on compiling modules and other information. If you get your webcam to work, add the name of the webcam and the driver you used to the list!<br />
<br />
=== pwc ===<br />
<br />
* Creative Labs Webcam Pro Ex<br />
* Logitech QuickCam Notebook Pro (only the "Pro" models)<br />
* Logitech Quickcam Pro 4000<br />
* Philips ToUCams (not confirmed at the moment, but it is using the pwc driver if I remember correctly)<br />
* Philips SPC900NC<br />
<br />
=== [[qc-usb]] ===<br />
<br />
* Dexxa Webcam<br />
* Labtec Webcam (old model) <br />
* LegoCam<br />
* Logitech Quickcam Express (old model)<br />
* Logitech QuickCam Notebook (not the "Pro" models)<br />
* Logitech Quickcam Web<br />
<br />
=== qc-usb-messenger ===<br />
<br />
* Logitech Quickcam Messenger<br />
* Logitech Quickcam Communicate (for Communicate MP/S5500 or "for Business" see the linux-uvc section below)<br />
<br />
It is now in the community repo.<br />
<br />
{{Note|<br />
* If qc-usb-messenger does not work use the gspca module, by installing the gspcav1 package.<br />
* Now this driver is a module included in kernel 2.6.27.<br />
}}<br />
<br />
=== zr364xx ===<br />
<br />
This driver can be used for many webcams like:<br />
* Aiptek PocketDV 3300<br />
* Creative PC-CAM 880<br />
* Konica Revio 2<br />
* Genius Digital Camera<br />
* Maxell Maxcam PRO DV3<br />
You can find the full list of supported devices [http://royale.zerezo.com/zr364xx/ here]. You can find a PKGBUILD for this driver in the [[Arch User Repository|AUR]].<br />
<br />
=== sn9c102 ===<br />
<br />
* Trust Spacecam series<br />
* Maxell Smartcam (for notebooks): 352x288 max. resolution @ 3fps<br />
<br />
=== gspca ===<br />
<br />
An extensive list of supported webcams is available [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/video4linux/gspca.txt;hb=HEAD].<br />
<br />
{{Note|This driver does not have V4L1 support.}}<br />
<br />
=== stv680 ===<br />
<br />
Many cheap no-name cameras that came out Asia in the last couple of years use the stv680 chipset. Most of these cameras were novelty items (i.e. Pencam, SpyC@m and LegoCam). <br />
* Aiptek PenCam series<br />
* Digitaldream series<br />
* Dolphin Peripherals series<br />
* Lego LegoCam<br />
* Trust SpyC@m series<br />
* Welback Coolcam<br />
<br />
A more-complete list of webcams that use the stv680 chipset is available [http://webcam-osx.sourceforge.net/cameras/index.php?orderBy=controller here].<br />
<br />
=== linux-uvc ===<br />
<br />
* Genius iLook 1321<br />
* Logitech Webcam C250<br />
* Logitech Webcam C270<br />
* Logitech Webcam C600<br />
* Logitech HD Webcam C525<br />
* Logitech Quickcam Pro 5000<br />
* Logitech Quickcam Pro 9000<br />
* Logitech Quickcam Orbit AF<br />
* Logitech Quickcam Orbit MP<br />
* Logitech Quickcam S5500<br />
* Microdia Pavilion Webcam (on MSI PR200)<br />
* Logitech Quickcam Communicate MP/S5500 or "for Business"<br />
* Chicony Electronics CNF7051<br />
<br />
You can find a full list of supported UVC devices [http://linux-uvc.berlios.de/ here].<br />
<br />
As of kernel 2.6.26 linux-uvc is part of the kernel. Just load the uvcvideo module.<br />
<br />
{{Note|<br />
* This driver does not have V4L1 support.<br />
* With WebCam SCB-0385N (usb ID 2232:1005), WebCam SC-0311139N (usb ID 2232:1020) and WebCam SC-03FFL11939N (usb ID 2232:1028), you might need to add some configuration to the module if the usage of the camera makes the system freeze : <br />
{{hc|1=/etc/modprobe.d/uvcvideo.conf|2=options uvcvideo nodrop=1}} }}<br />
<br />
=== ov51x-jpeg ===<br />
<br />
* Sony EyeToy<br />
* Chicony DC-2120 <br />
* Chicony DC-2120 pro<br />
* Trust Spacecam 320<br />
* Hercules Webcam Deluxe <br />
* Hercules Webcam Classic <br />
* Creative Live! Cam Notebook Pro VF0400 <br />
* Creative Live! Cam Vista IM <br />
* Creative Live! Cam Vista IM VF0420 <br />
* Creative Vista Webcam VF0330 <br />
* ASUS webcam Model? <br />
* Philips PCVC820K/00 <br />
* NGS showtime plus <br />
* HP VGA Webcam with Integrated Microphone<br />
<br />
This is a kernel module found in the AUR with some additions to the original driver that provide jpeg decompression.<br />
<br />
For me to get my "Creative Live! Cam Vista IM" working with Skype, I had to add this line to {{ic|/etc/modprobe.d/modprobe.conf}}:<br />
options ov51x-jpeg forceblock=1<br />
<br />
=== r5u870 (Ricoh) ===<br />
<br />
* HP Pavilion Webcam<br />
* HP Webcam 1000<br />
* Sony VAIO VGP-VCCx<br />
<br />
The Ricoh webcam is built into most new Sony laptops.<br />
<br />
Install {{AUR|r5u87x-hg}} (provides firmware too) and run the {{ic|loader}} command.<br />
<br />
=== stk11xx (Syntek) ===<br />
<br />
* Integrated camera in lot of Asus laptops<br />
* Asus A8J, F3S, F5R, F5GL, F9E, VX2S, V1S, A6T<br />
<br />
Just install the {{AUR|stk11xx}} AUR package. It contains the right kernel module.<br />
<br />
== Make sure the module is loaded for your webcam ==<br />
<br />
Add your webcam's [[Kernel modules#Loading|module]] in {{ic|/etc/modules-load.d/webcam.conf}} so it will be loaded into the kernel during init stage bootstrapping.<br />
<br />
If your webcam is USB, the kernel ''should'' automatically load the proper driver. If this is the case, check dmesg after you plug your webcam in. You should see something like this:<br />
<br />
{{hc|<nowiki>$ dmesg|tail</nowiki>|<nowiki><br />
sn9c102: V4L2 driver for SN9C10x PC Camera Controllers v1:1.24a<br />
usb 1-1: SN9C10[12] PC Camera Controller detected (vid/pid 0x0C45/0x600D)<br />
usb 1-1: PAS106B image sensor detected<br />
usb 1-1: Initialization succeeded<br />
usb 1-1: V4L2 device registered as /dev/video0<br />
usb 1-1: Optional device control through 'sysfs' interface ready<br />
usbcore: registered new driver sn9c102<br />
</nowiki>}}<br />
<br />
== Permissions ==<br />
<br />
In order to use your webcam, you need to have permission to use {{ic|/dev/video0}}.<br />
<br />
=== udev ===<br />
<br />
If you use [[udev]], you only need to be in the group ''video''. You can check it with:<br />
$ groups<br />
To add a user to the group run under root:<br />
# gpasswd -a <username> video<br />
Note the next two steps may not be required as they should already be set by [[udev]]<br />
<br />
Set group of device to video:<br />
# chgrp video /dev/video0<br />
Set permissions of the device:<br />
# chmod 660 /dev/video0<br />
<br />
{{Tip|If you need to load webcams in order (i.e. get the /dev/video0..n device order) or set ownership or permissions, take a look at writing rules for [[Udev#Writing udev rules|Writing udev rules]].}}<br />
<br />
=== devfs ===<br />
<br />
Add the following to your {{ic|/etc/devfsd.conf}}. This will give normal users permission to use {{ic|/dev/video0}} (your webcam).<br />
REGISTER video0 PERMISSIONS root.users 0660<br />
<br />
== Webcam configuration ==<br />
<br />
If you want to configure brightness, color and other webcam parameters (e.g. in the case when out-of-the-box colors are too bluish/reddish/greenish) you may use [http://guvcview.berlios.de/ GTK+ UVC Viewer] (guvcview), available in the [[Official Repositories]] as package {{Pkg|guvcview}}. Just install it and launch, and it will present you a list of configurable settings. Changing these settings will affect all applications (e.g. Skype).<br />
<br />
== Get software to use your webcam ==<br />
<br />
Version 2.6.27 of the Linux kernel supports [http://mxhaard.free.fr/spca5xx.html many new webcam drivers]. Legacy Video4Linux API has been dropped, and these drivers now only support Video4Linux version 2. Pixel format decoding has been pushed to user space, since Video4Linux version 2 does not support kernel space decoding. The libv4l library provides userland applications with pixel decoding services and will be used by most programs. Other compatibility layers are also available.<br />
<br />
'''If your device is created but your image looks strange (mine was nearly completely green), you probably need this.'''<br />
<br />
If the application has V4L2 support but no pixelformat support (eg: cheese) then use the following command:<br />
LD_PRELOAD=/usr/lib/libv4l/v4l2convert.so cheese<br />
<br />
If the application only supports the older version of V4L (Skype is the most popular of this kind of software) then use this command:<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
{{Tip|1=You also might want to put a line like the following into {{ic|/etc/profile}} or [[xprofile]] so you do not have to type that long command all the time:<br />
{{bc|1=export LD_PRELOAD=/usr/'$LIB'/libv4l/v4l2convert.so}}<br />
or<br />
{{bc|1=export LD_PRELOAD=/usr/'$LIB'/libv4l/v4l1compat.so}}<br />
}}<br />
<br />
For 32-bit applications (e.g. Skype) within Arch64, install the {{Pkg|lib32-v4l-utils}} package.<br />
<br />
If the webcam works fine on guvcview, but it does not work in Skype, you may also need to set <br />
export XLIB_SKIP_ARGB_VISUALS=1<br />
before starting it.<br />
<br />
=== Cheese ===<br />
<br />
Cheese is the GNOME photo/video taking client. It is similar to Photo Booth in Mac OS X. It is in the official repositories.<br />
<br />
=== GTK+ UVC Viewer (guvcview) ===<br />
<br />
In addition to being a convenient way to configure your webcam, [http://guvcview.berlios.de/ guvcview] also allows capturing (with sound!) and viewing video from devices supported by the Linux UVC driver. Available in the [[official repositories]] as package {{Pkg|guvcview}}. Just install it and launch, and it will present you a list of configurable settings. Changing these settings will affect all applications (e.g. Skype).<br />
<br />
=== Kopete ===<br />
<br />
Kopete is the [[KDE]] instant messaging (IM) client. As of KDE 3.5, it has support for MSN and Yahoo! webcams, but not every cam works yet. It is included in the kdenetwork package.<br />
<br />
=== Kamoso ===<br />
<br />
Application to take pictures and videos out of your webcam for KDE.<br />
Available in the AUR: {{AUR|kamoso}}.<br />
<br />
=== xawtv ===<br />
<br />
This is a basic v4l device viewer, and although it is intended for use with TV tuner cards, it works well with webcams. It will display what your webcam sees in a window. Install it ({{Pkg|xawtv}}) and run it with:<br />
$ xawtv -c /dev/video0<br />
If you are using an nVidia graphic card, and you get an error like<br />
X Error of failed request: XF86DGANoDirectVideoMode<br />
Major opcode of failed request: 139 (XFree86-DGA)<br />
Minor opcode of failed request: 1 (XF86DGAGetVideoLL)<br />
Serial number of failed request: 69<br />
Current serial number in output stream: 69<br />
you should instead run it as:<br />
$ xawtv -nodga<br />
google talk<br />
<br />
=== VLC ===<br />
<br />
[[VLC]] can also be used to view and record your webcam. In VLC's file menu, open the 'Capture Device...' dialog and enter the video and audio device files. Or from the command line, do:<br />
$ vlc v4l:// :v4l-vdev="/dev/video0" :v4l-adev="/dev/audio2"<br />
This will make VLC mirror your webcam. To take stills, simply choose 'Snapshot' in the 'Video' menu. To record the stream, you add a {{ic|--sout}} argument, e.g.<br />
$ vlc v4l:// :v4l-vdev="/dev/video0" :v4l-adev="/dev/audio2" \ <br />
--sout "#transcode{vcodec=mp1v,vb=1024,scale=1,acodec=mpga,ab=192,channels=2}:duplicate{dst=std{access=file,mux=mpeg1,dst=/tmp/test.mpg}}"<br />
<br />
(Obviously a bit overkill with regard to the bit rates but it is fine for testing purposes.) Notice that this will not produce a mirror on the display - in order to see what you are recording, you would need to add the display as a destination to the argument:<br />
... :duplicate{dst=display,dst=std{access= ....<br />
(Though this can tax older hardware somewhat...)<br />
<br />
=== MPlayer ===<br />
<br />
To use [[MPlayer]] to take snapshots from your webcam run this command from the terminal:<br />
$ mplayer tv:// -tv driver=v4l2:width=640:height=480:device=/dev/video0 -fps 15 -vf screenshot<br />
From here you have to press {{ic|s}} to take the snapshot. The snapshot will be saved in your current folder as '''shotXXXX.png'''.<br />
If you want to record continuous video:<br />
$ mencoder tv:// -tv driver=v4l2:width=640:height=480:device=/dev/video0:forceaudio:adevice=/dev/dsp -ovc lavc -oac mp3lame -lameopts cbr:br=64:mode=3 -o ''filename''.avi<br />
Press {{ic|Ctrl+c}} to end the recording.<br />
<br />
=== FFmpeg ===<br />
<br />
See [[FFmpeg#Recording webcam]].<br />
<br />
=== ekiga ===<br />
<br />
This is very similar to Microsoft NetMeeting. <br />
Install the {{pkg|ekiga}} package from the official repositories.<br />
The configuration druid will set everything up for you.<br />
<br />
=== Sonic-snap ===<br />
<br />
Sonic-snap [http://www.stolk.org/sonic-snap/] is a viewer/grabber for sn9c102-based webcams '''only'''.<br />
{{AUR|sonic-snap}} is available in the AUR.<br />
<br />
=== Skype === <br />
<br />
The newest version of [[Skype]] has video support. Check Video Devices in the options for a test image which you can double-click to make full screen. Install the {{pkg|skype}} package.<br />
If you get green/disorted picture with skype read the section [[Webcam_Setup#Get software to use your webcam]] above.<br />
<br />
If your running x86-64 you might actually need to install {{Pkg|lib32-v4l-utils}} and then run skype with<br />
LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype<br />
You can either set an alias for skype, or rename the original skype binary in {{ic|/usr/bin}} and create a text file containing the above option, or you can simply adjust the Command line in the options for the Skype icon in your favourite desktop environment.<br />
<br />
=== Motion ===<br />
<br />
:''Motion is a program that monitors the video signal from cameras. It is able to detect if a significant part of the picture has changed; in other words, it can detect motion.''<br />
<br />
{{Pkg|motion}} can only handle v4l2 devices so if you need to use a camera that only has v4l1 drivers you need to preload v4l1compat.so as previously mentioned. Otherwise you will get loads of errors about motion not able to find a suitable palette.<br />
<br />
{{Tip|If you need to load webcams in order (i.e. get the /dev/video0..n device order) or set ownership or permissions, take a look at writing rules for [[Udev#Writing udev rules|writing udev rules]].}}<br />
<br />
==== Troubleshooting ====<br />
<br />
== Microsoft Lifecam Studio/Cinema==<br />
Under certain configurations, the Microsoft lifecam studio/cinema may request too much usb bandwidth and fail [http://www.ideasonboard.org/uvc/#footnote-13 see Uvcvideo FAQ]. In this case try loading the {{ic|uvcvideo}} driver with {{ic|quirks<nowiki>=</nowiki>0x80}}. Add it to {{ic|/etc/modprobe.d/uvcvideo.conf}} :<br />
{{hc|/etc/modprobe.d/uvcvideo.conf|<nowiki><br />
## fix bandwidth issue for lifecam studio/cinema<br />
options uvcvideo quirks=0x80<br />
</nowiki>}}</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Webcam_setup&diff=279605Webcam setup2013-10-24T14:11:32Z<p>Bluerider: /* Motion */</p>
<hr />
<div>[[Category:Imaging]]<br />
[[Category:Other hardware]] <br />
[[ru:Webcam Setup]]<br />
[[zh-CN:Webcam Setup]]<br />
This is a guide to setting up your webcam in Arch Linux.<br />
<br />
== Linux webcam support ==<br />
<br />
Most probably your webcam will work out of the box. In that case you may skip to section [[Webcam_Setup#Webcam configuration]] if you want to configure color, brightness and other parameters. Otherwise follow the steps below.<br />
<br />
== Identify your webcam ==<br />
<br />
Identify the name of your webcam (using, for example, {{Ic|lsusb}}) and find a proper driver. Below is a list of webcams, and what drivers they work with. Click on the link to the right of the device name for information on compiling modules and other information. If you get your webcam to work, add the name of the webcam and the driver you used to the list!<br />
<br />
=== pwc ===<br />
<br />
* Creative Labs Webcam Pro Ex<br />
* Logitech QuickCam Notebook Pro (only the "Pro" models)<br />
* Logitech Quickcam Pro 4000<br />
* Philips ToUCams (not confirmed at the moment, but it is using the pwc driver if I remember correctly)<br />
* Philips SPC900NC<br />
<br />
=== [[qc-usb]] ===<br />
<br />
* Dexxa Webcam<br />
* Labtec Webcam (old model) <br />
* LegoCam<br />
* Logitech Quickcam Express (old model)<br />
* Logitech QuickCam Notebook (not the "Pro" models)<br />
* Logitech Quickcam Web<br />
<br />
=== qc-usb-messenger ===<br />
<br />
* Logitech Quickcam Messenger<br />
* Logitech Quickcam Communicate (for Communicate MP/S5500 or "for Business" see the linux-uvc section below)<br />
<br />
It is now in the community repo.<br />
<br />
{{Note|<br />
* If qc-usb-messenger does not work use the gspca module, by installing the gspcav1 package.<br />
* Now this driver is a module included in kernel 2.6.27.<br />
}}<br />
<br />
=== zr364xx ===<br />
<br />
This driver can be used for many webcams like:<br />
* Aiptek PocketDV 3300<br />
* Creative PC-CAM 880<br />
* Konica Revio 2<br />
* Genius Digital Camera<br />
* Maxell Maxcam PRO DV3<br />
You can find the full list of supported devices [http://royale.zerezo.com/zr364xx/ here]. You can find a PKGBUILD for this driver in the [[Arch User Repository|AUR]].<br />
<br />
=== sn9c102 ===<br />
<br />
* Trust Spacecam series<br />
* Maxell Smartcam (for notebooks): 352x288 max. resolution @ 3fps<br />
<br />
=== gspca ===<br />
<br />
An extensive list of supported webcams is available [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/video4linux/gspca.txt;hb=HEAD].<br />
<br />
{{Note|This driver does not have V4L1 support.}}<br />
<br />
=== stv680 ===<br />
<br />
Many cheap no-name cameras that came out Asia in the last couple of years use the stv680 chipset. Most of these cameras were novelty items (i.e. Pencam, SpyC@m and LegoCam). <br />
* Aiptek PenCam series<br />
* Digitaldream series<br />
* Dolphin Peripherals series<br />
* Lego LegoCam<br />
* Trust SpyC@m series<br />
* Welback Coolcam<br />
<br />
A more-complete list of webcams that use the stv680 chipset is available [http://webcam-osx.sourceforge.net/cameras/index.php?orderBy=controller here].<br />
<br />
=== linux-uvc ===<br />
<br />
* Genius iLook 1321<br />
* Logitech Webcam C250<br />
* Logitech Webcam C270<br />
* Logitech Webcam C600<br />
* Logitech HD Webcam C525<br />
* Logitech Quickcam Pro 5000<br />
* Logitech Quickcam Pro 9000<br />
* Logitech Quickcam Orbit AF<br />
* Logitech Quickcam Orbit MP<br />
* Logitech Quickcam S5500<br />
* Microdia Pavilion Webcam (on MSI PR200)<br />
* Logitech Quickcam Communicate MP/S5500 or "for Business"<br />
* Chicony Electronics CNF7051<br />
<br />
You can find a full list of supported UVC devices [http://linux-uvc.berlios.de/ here].<br />
<br />
As of kernel 2.6.26 linux-uvc is part of the kernel. Just load the uvcvideo module.<br />
<br />
{{Note|<br />
* This driver does not have V4L1 support.<br />
* With WebCam SCB-0385N (usb ID 2232:1005), WebCam SC-0311139N (usb ID 2232:1020) and WebCam SC-03FFL11939N (usb ID 2232:1028), you might need to add some configuration to the module if the usage of the camera makes the system freeze : <br />
{{hc|1=/etc/modprobe.d/uvcvideo.conf|2=options uvcvideo nodrop=1}} }}<br />
<br />
=== ov51x-jpeg ===<br />
<br />
* Sony EyeToy<br />
* Chicony DC-2120 <br />
* Chicony DC-2120 pro<br />
* Trust Spacecam 320<br />
* Hercules Webcam Deluxe <br />
* Hercules Webcam Classic <br />
* Creative Live! Cam Notebook Pro VF0400 <br />
* Creative Live! Cam Vista IM <br />
* Creative Live! Cam Vista IM VF0420 <br />
* Creative Vista Webcam VF0330 <br />
* ASUS webcam Model? <br />
* Philips PCVC820K/00 <br />
* NGS showtime plus <br />
* HP VGA Webcam with Integrated Microphone<br />
<br />
This is a kernel module found in the AUR with some additions to the original driver that provide jpeg decompression.<br />
<br />
For me to get my "Creative Live! Cam Vista IM" working with Skype, I had to add this line to {{ic|/etc/modprobe.d/modprobe.conf}}:<br />
options ov51x-jpeg forceblock=1<br />
<br />
=== r5u870 (Ricoh) ===<br />
<br />
* HP Pavilion Webcam<br />
* HP Webcam 1000<br />
* Sony VAIO VGP-VCCx<br />
<br />
The Ricoh webcam is built into most new Sony laptops.<br />
<br />
Install {{AUR|r5u87x-hg}} (provides firmware too) and run the {{ic|loader}} command.<br />
<br />
=== stk11xx (Syntek) ===<br />
<br />
* Integrated camera in lot of Asus laptops<br />
* Asus A8J, F3S, F5R, F5GL, F9E, VX2S, V1S, A6T<br />
<br />
Just install the {{AUR|stk11xx}} AUR package. It contains the right kernel module.<br />
<br />
== Make sure the module is loaded for your webcam ==<br />
<br />
Add your webcam's [[Kernel modules#Loading|module]] in {{ic|/etc/modules-load.d/webcam.conf}} so it will be loaded into the kernel during init stage bootstrapping.<br />
<br />
If your webcam is USB, the kernel ''should'' automatically load the proper driver. If this is the case, check dmesg after you plug your webcam in. You should see something like this:<br />
<br />
{{hc|<nowiki>$ dmesg|tail</nowiki>|<nowiki><br />
sn9c102: V4L2 driver for SN9C10x PC Camera Controllers v1:1.24a<br />
usb 1-1: SN9C10[12] PC Camera Controller detected (vid/pid 0x0C45/0x600D)<br />
usb 1-1: PAS106B image sensor detected<br />
usb 1-1: Initialization succeeded<br />
usb 1-1: V4L2 device registered as /dev/video0<br />
usb 1-1: Optional device control through 'sysfs' interface ready<br />
usbcore: registered new driver sn9c102<br />
</nowiki>}}<br />
<br />
== Permissions ==<br />
<br />
In order to use your webcam, you need to have permission to use {{ic|/dev/video0}}.<br />
<br />
=== udev ===<br />
<br />
If you use [[udev]], you only need to be in the group ''video''. You can check it with:<br />
$ groups<br />
To add a user to the group run under root:<br />
# gpasswd -a <username> video<br />
Note the next two steps may not be required as they should already be set by [[udev]]<br />
<br />
Set group of device to video:<br />
# chgrp video /dev/video0<br />
Set permissions of the device:<br />
# chmod 660 /dev/video0<br />
<br />
{{Tip|If you need to load webcams in order (i.e. get the /dev/video0..n device order) or set ownership or permissions, take a look at writing rules for [[Udev#Writing udev rules|Writing udev rules]].}}<br />
<br />
=== devfs ===<br />
<br />
Add the following to your {{ic|/etc/devfsd.conf}}. This will give normal users permission to use {{ic|/dev/video0}} (your webcam).<br />
REGISTER video0 PERMISSIONS root.users 0660<br />
<br />
== Webcam configuration ==<br />
<br />
If you want to configure brightness, color and other webcam parameters (e.g. in the case when out-of-the-box colors are too bluish/reddish/greenish) you may use [http://guvcview.berlios.de/ GTK+ UVC Viewer] (guvcview), available in the [[Official Repositories]] as package {{Pkg|guvcview}}. Just install it and launch, and it will present you a list of configurable settings. Changing these settings will affect all applications (e.g. Skype).<br />
<br />
== Get software to use your webcam ==<br />
<br />
Version 2.6.27 of the Linux kernel supports [http://mxhaard.free.fr/spca5xx.html many new webcam drivers]. Legacy Video4Linux API has been dropped, and these drivers now only support Video4Linux version 2. Pixel format decoding has been pushed to user space, since Video4Linux version 2 does not support kernel space decoding. The libv4l library provides userland applications with pixel decoding services and will be used by most programs. Other compatibility layers are also available.<br />
<br />
'''If your device is created but your image looks strange (mine was nearly completely green), you probably need this.'''<br />
<br />
If the application has V4L2 support but no pixelformat support (eg: cheese) then use the following command:<br />
LD_PRELOAD=/usr/lib/libv4l/v4l2convert.so cheese<br />
<br />
If the application only supports the older version of V4L (Skype is the most popular of this kind of software) then use this command:<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
{{Tip|1=You also might want to put a line like the following into {{ic|/etc/profile}} or [[xprofile]] so you do not have to type that long command all the time:<br />
{{bc|1=export LD_PRELOAD=/usr/'$LIB'/libv4l/v4l2convert.so}}<br />
or<br />
{{bc|1=export LD_PRELOAD=/usr/'$LIB'/libv4l/v4l1compat.so}}<br />
}}<br />
<br />
For 32-bit applications (e.g. Skype) within Arch64, install the {{Pkg|lib32-v4l-utils}} package.<br />
<br />
If the webcam works fine on guvcview, but it does not work in Skype, you may also need to set <br />
export XLIB_SKIP_ARGB_VISUALS=1<br />
before starting it.<br />
<br />
=== Cheese ===<br />
<br />
Cheese is the GNOME photo/video taking client. It is similar to Photo Booth in Mac OS X. It is in the official repositories.<br />
<br />
=== GTK+ UVC Viewer (guvcview) ===<br />
<br />
In addition to being a convenient way to configure your webcam, [http://guvcview.berlios.de/ guvcview] also allows capturing (with sound!) and viewing video from devices supported by the Linux UVC driver. Available in the [[official repositories]] as package {{Pkg|guvcview}}. Just install it and launch, and it will present you a list of configurable settings. Changing these settings will affect all applications (e.g. Skype).<br />
<br />
=== Kopete ===<br />
<br />
Kopete is the [[KDE]] instant messaging (IM) client. As of KDE 3.5, it has support for MSN and Yahoo! webcams, but not every cam works yet. It is included in the kdenetwork package.<br />
<br />
=== Kamoso ===<br />
<br />
Application to take pictures and videos out of your webcam for KDE.<br />
Available in the AUR: {{AUR|kamoso}}.<br />
<br />
=== xawtv ===<br />
<br />
This is a basic v4l device viewer, and although it is intended for use with TV tuner cards, it works well with webcams. It will display what your webcam sees in a window. Install it ({{Pkg|xawtv}}) and run it with:<br />
$ xawtv -c /dev/video0<br />
If you are using an nVidia graphic card, and you get an error like<br />
X Error of failed request: XF86DGANoDirectVideoMode<br />
Major opcode of failed request: 139 (XFree86-DGA)<br />
Minor opcode of failed request: 1 (XF86DGAGetVideoLL)<br />
Serial number of failed request: 69<br />
Current serial number in output stream: 69<br />
you should instead run it as:<br />
$ xawtv -nodga<br />
google talk<br />
<br />
=== VLC ===<br />
<br />
[[VLC]] can also be used to view and record your webcam. In VLC's file menu, open the 'Capture Device...' dialog and enter the video and audio device files. Or from the command line, do:<br />
$ vlc v4l:// :v4l-vdev="/dev/video0" :v4l-adev="/dev/audio2"<br />
This will make VLC mirror your webcam. To take stills, simply choose 'Snapshot' in the 'Video' menu. To record the stream, you add a {{ic|--sout}} argument, e.g.<br />
$ vlc v4l:// :v4l-vdev="/dev/video0" :v4l-adev="/dev/audio2" \ <br />
--sout "#transcode{vcodec=mp1v,vb=1024,scale=1,acodec=mpga,ab=192,channels=2}:duplicate{dst=std{access=file,mux=mpeg1,dst=/tmp/test.mpg}}"<br />
<br />
(Obviously a bit overkill with regard to the bit rates but it is fine for testing purposes.) Notice that this will not produce a mirror on the display - in order to see what you are recording, you would need to add the display as a destination to the argument:<br />
... :duplicate{dst=display,dst=std{access= ....<br />
(Though this can tax older hardware somewhat...)<br />
<br />
=== MPlayer ===<br />
<br />
To use [[MPlayer]] to take snapshots from your webcam run this command from the terminal:<br />
$ mplayer tv:// -tv driver=v4l2:width=640:height=480:device=/dev/video0 -fps 15 -vf screenshot<br />
From here you have to press {{ic|s}} to take the snapshot. The snapshot will be saved in your current folder as '''shotXXXX.png'''.<br />
If you want to record continuous video:<br />
$ mencoder tv:// -tv driver=v4l2:width=640:height=480:device=/dev/video0:forceaudio:adevice=/dev/dsp -ovc lavc -oac mp3lame -lameopts cbr:br=64:mode=3 -o ''filename''.avi<br />
Press {{ic|Ctrl+c}} to end the recording.<br />
<br />
=== FFmpeg ===<br />
<br />
See [[FFmpeg#Recording webcam]].<br />
<br />
=== ekiga ===<br />
<br />
This is very similar to Microsoft NetMeeting. <br />
Install the {{pkg|ekiga}} package from the official repositories.<br />
The configuration druid will set everything up for you.<br />
<br />
=== Sonic-snap ===<br />
<br />
Sonic-snap [http://www.stolk.org/sonic-snap/] is a viewer/grabber for sn9c102-based webcams '''only'''.<br />
{{AUR|sonic-snap}} is available in the AUR.<br />
<br />
=== Skype === <br />
<br />
The newest version of [[Skype]] has video support. Check Video Devices in the options for a test image which you can double-click to make full screen. Install the {{pkg|skype}} package.<br />
If you get green/disorted picture with skype read the section [[Webcam_Setup#Get software to use your webcam]] above.<br />
<br />
If your running x86-64 you might actually need to install {{Pkg|lib32-v4l-utils}} and then run skype with<br />
LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype<br />
You can either set an alias for skype, or rename the original skype binary in {{ic|/usr/bin}} and create a text file containing the above option, or you can simply adjust the Command line in the options for the Skype icon in your favourite desktop environment.<br />
<br />
=== Motion ===<br />
<br />
:''Motion is a program that monitors the video signal from cameras. It is able to detect if a significant part of the picture has changed; in other words, it can detect motion.''<br />
<br />
{{Pkg|motion}} can only handle v4l2 devices so if you need to use a camera that only has v4l1 drivers you need to preload v4l1compat.so as previously mentioned. Otherwise you will get loads of errors about motion not able to find a suitable palette.<br />
<br />
{{Tip|If you need to load webcams in order (i.e. get the /dev/video0..n device order) or set ownership or permissions, take a look at writing rules for [[Udev#Writing udev rules|writing udev rules]].}}<br />
<br />
==== Troubleshooting ====<br />
<br />
=== Microsoft Lifecam Studio/Cinema===<br />
Under certain configurations, the Microsoft lifecam studio/cinema may request too much usb bandwidth and fail [http://www.ideasonboard.org/uvc/#footnote-13 see Uvcvideo FAQ]. In this case try loading the {{ic|uvcvideo}} driver with {{ic|quirks<nowiki>=</nowiki>0x80}}. Add it to {{ic|/etc/modprobe.d/uvcvideo.conf}} :<br />
{{hc|/etc/modprobe.d/uvcvideo.conf|<nowiki><br />
## fix bandwidth issue for lifecam studio/cinema<br />
options uvcvideo quirks=0x80<br />
</nowiki>}}</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Skype&diff=278446Skype2013-10-12T03:05:17Z<p>Bluerider: /* No incoming video stream */</p>
<hr />
<div>[[bg:Skype]]<br />
[[cs:Skype]]<br />
[[lt:Skype]]<br />
[[ru:Skype]]<br />
[[uk:Skype]]<br />
[[Category:Audio/Video]]<br />
[[Category:Telephony and Voice]]<br />
== Installation ==<br />
<br />
[[pacman|Install]] {{Pkg|skype}} from the [[official repositories]]. If you have a 64-bit system, enable the [[multilib]] repository first as Skype is 32-bit only.<br />
<br />
Running Skype is just as easy. Type {{Ic|skype}} into a terminal or double-click the Skype icon on your desktop or in your DE's application menu.<br />
<br />
== Skype sound ==<br />
<br />
Skype supports [[ALSA]] and [[PulseAudio]]. [[OSS]] is no longer supported.<br />
<br />
=== ALSA ===<br />
<br />
Sound should work out of the box, if not you can select a sound device to use in Skype options. If you have problems with Skype blocking your sound device, you only need to add the following to your {{ic|~/.asoundrc}}<br />
pcm.dmixout {<br />
# Just pass this on to the system dmix<br />
type plug<br />
slave {<br />
pcm "dmix"<br />
}<br />
}<br />
then you can start Skype as normal, go to the audio options and select dmixout as your speaker- and ringingdevice.<br />
<br />
=== PulseAudio ===<br />
<br />
Sound should work out of the box, if not you can select another input using pavucontrol (you may have to install it first).<br />
<br />
If you are on x86_64 and use the multilib {{Pkg|skype}} package, you also need {{Pkg|lib32-libpulse}}.<br />
<br />
=== OSS (Pre-2.0, no longer available) ===<br />
<br />
Option B is preferred over other options.<br />
With option B you can use Skype AND let other programs play sound too.<br />
With option C you can do that too, but option B is way easier to set up.<br />
<br />
You can install the legacy {{Pkg|skype-oss}} from Comunity repo.<br />
<br />
If you need 64x-86x support then download an OSS compatible version from [http://www.mediafire.com/?2ydhmj4yo3i here] and the PKGBUILD form [https://aur.archlinux.org/packages.php?ID=18312 here.] Also install {{Pkg|lib32-libxinerama}}. Finally, run<br />
$ makepkg -s<br />
to create the pacman installable package.<br />
<br />
==== A. With OSS or Kernel OSS emulation for ALSA ====<br />
<br />
Start Skype and make sure no other program is using your soundcard.<br />
If you want to use Skype AND let another program play sound too, look at option B instead.<br />
<br />
==== B. Making ALSA + dMix work for Skype ====<br />
<br />
First of all, we need to install the {{Pkg|alsa-oss}} package with [[pacman]].<br />
<br />
Add the following to {{ic|~/.asoundrc}}. If the file does not exist yet, just create it! (Many thanks to Lorenzo Colitti for figuring this out!)<br />
<br />
# .asoundrc to use skype at the same time as other audio apps like xmms<br />
#<br />
# Successfully tested on an IBM x40 with i810_audio using Linux 2.6.15 and<br />
# Debian unstable with skype 1.2.0.18-API. No sound daemons (asound, esd, etc.)<br />
# running. However, YMMV.<br />
#<br />
# For background, see:<br />
#<br />
# https://bugtrack.alsa-project.org/alsa-bug/view.php?id=1228<br />
# https://bugtrack.alsa-project.org/alsa-bug/view.php?id=1224<br />
#<br />
# (C) 2006-06-03 Lorenzo Colitti - http://www.colitti.com/lorenzo/<br />
# Licensed under the GPLv2 or later<br />
<br />
pcm.skype {<br />
type asym<br />
playback.pcm "skypeout"<br />
capture.pcm "skypein"<br />
}<br />
<br />
pcm.skypein {<br />
# Convert from 8-bit unsigned mono (default format set by aoss when<br />
# /dev/dsp is opened) to 16-bit signed stereo (expected by dsnoop)<br />
#<br />
# We cannot just use a "plug" plugin because although the open will<br />
# succeed, the buffer sizes will be wrong and we will hear no sound at<br />
# all.<br />
type route<br />
slave {<br />
pcm "skypedsnoop"<br />
format S16_LE<br />
}<br />
ttable {<br />
0 {0 0.5}<br />
1 {0 0.5}<br />
}<br />
}<br />
<br />
pcm.skypeout {<br />
# Just pass this on to the system dmix<br />
type plug<br />
slave {<br />
pcm "dmix"<br />
}<br />
}<br />
<br />
pcm.skypedsnoop {<br />
type dsnoop<br />
ipc_key 1133<br />
slave {<br />
# "Magic" buffer values to get skype audio to work<br />
# If these are not set, opening /dev/dsp succeeds but no sound<br />
# will be heard. According to the ALSA developers this is due<br />
# to skype abusing the OSS API.<br />
pcm "hw:0,0"<br />
period_size 256<br />
periods 16<br />
buffer_size 16384<br />
}<br />
bindings {<br />
0 0<br />
}<br />
}<br />
<br />
If you get the error message :<br />
<br />
The dmix plugin supports only playback stream<br />
<br />
then add the following to {{ic|.asoundrc}}:<br />
<br />
pcm.asymed {<br />
type asym<br />
playback.pcm "dmix"<br />
capture.pcm "dsnoop"<br />
}<br />
<br />
pcm.!default {<br />
type plug<br />
slave.pcm "asymed"<br />
}<br />
<br />
<br />
Now run Skype in this way each time you want to use it:<br />
ALSA_OSS_PCM_DEVICE="skype" aoss skype<br />
<br />
Optionally you can make a script to start Skype:<br />
<br />
As root, create the file: {{ic|/usr/bin/askype}}<br />
<br />
# Little script to run Skype correctly using the modified .asoundrc<br />
# See: https://wiki.archlinux.org/index.php/Skype for more information!<br />
#<br />
# Questions/Remarks: profox@debianbox.be<br />
<br />
ALSA_OSS_PCM_DEVICE="skype" aoss skype<br />
<br />
Now make sure every user is able to execute the file:<br />
# chmod a+x /usr/bin/askype<br />
<br />
You can also fix the menu entry so you can start Skype from the your window manager's menu:<br />
<br />
Edit the file: {{ic|/usr/share/applications/skype.desktop}}<br />
<br />
[Desktop Entry]<br />
Name=Skype<br />
Comment=P2P software for high-quality voice communication<br />
Exec=askype<br />
Icon=skype.png<br />
Terminal=0<br />
Type=Application<br />
Encoding=UTF-8<br />
Categories=Network;Application;<br />
<br />
Sometimes it takes a while for Skype to start up but once it is loaded it should work ok!<br />
<br />
==== C. Using OSS emulation with oss2jack ====<br />
<br />
{{AUR|oss2jack}} is another way to have OSS emulation without using ALSA directly. Instead, oss2jack creates a OSS device that forwards everything to JACK (JACK Audio Connection Kit), which in turn mixes, then outputs to the standard ALSA device.<br />
<br />
== Securing Skype ==<br />
<br />
There are a couple of reasons you might want to restrict Skype's access to your computer:<br />
* The skype binary is disguised against decompiling, so nobody is (still) able to reproduce what it really does.<br />
* It produces encrypted traffic even when you are not actively using Skype.<br />
* ...<br />
See [http://www1.cs.columbia.edu/~salman/skype/index.html] for more information.<br />
<br />
=== AppArmor ===<br />
<br />
Follow the instructions [[AppArmor|here]] to set up AppArmor.<br />
<br />
The userland tools for AppArmor come with a collection of example profiles. Skype is amongst them. Copy this to the directory where AppArmor profiles are stored.<br />
# cp -ip /etc/apparmor/profiles/extras/usr.bin.skype /etc/apparmor.d/<br />
<br />
For whatever reason, the profile is not complete. You may wish to modify it further. Here is an example for Skype 4:<br />
<br />
{{bc|#include <tunables/global><br />
/usr/bin/skype {<br />
#include <abstractions/audio><br />
#include <abstractions/consoles><br />
#include <abstractions/dbus-session><br />
#include <abstractions/gnome><br />
#include <abstractions/kde><br />
#include <abstractions/nameservice><br />
#include <abstractions/video><br />
<br />
# Executables<br />
/usr/bin/skype ixmr,<br />
/usr/lib{,32}/skype/skype ixmr,<br />
/usr/bin/xdg-open PUxmr,<br />
<br />
# Configuration files<br />
owner @{HOME}/.Skype/ rw,<br />
owner @{HOME}/.Skype/** krw,<br />
owner @{HOME}/.config/Skype/ rw,<br />
owner @{HOME}/.config/Skype/** krw,<br />
<br />
# Downloads/uploads directory<br />
owner @{HOME}/Public/ rw,<br />
owner @{HOME}/Public/** krw,<br />
<br />
# Libraries<br />
/usr/lib{,32}/libv4l/v4l2convert.so mr,<br />
/usr/share/skype/lib/libQtWebKit.so.4 mr,<br />
<br />
# Shared data<br />
/usr/share/skype/ r,<br />
/usr/share/skype/** r,<br />
<br />
# Devices<br />
/dev/ r,<br />
/dev/video[0-9]* mrw,<br />
<br />
# System information<br />
/etc/machine-id r,<br />
@{PROC}/sys/kernel/{ostype,osrelease} r,<br />
@{PROC}/sys/vm/overcommit_memory r,<br />
@{PROC}/[0-9]*/net/arp r,<br />
owner @{PROC}/[0-9]*/cmdline r,<br />
owner @{PROC}/[0-9]*/status r,<br />
owner @{PROC}/[0-9]*/task/ r,<br />
owner @{PROC}/[0-9]*/task/[0-9]*/stat r,<br />
/sys/devices/system/cpu/ r,<br />
/sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_{cur_freq,max_freq} r,<br />
/sys/devices/pci*/*/usb[0-9]*/*/*/*/modalias r,<br />
/sys/devices/pci*/*/usb[0-9]*/*/*/*/video4linux/video[0-9]*/dev r,<br />
/sys/devices/pci*/*/usb[0-9]*/*/*/{idVendor,idProduct,speed} r,<br />
<br />
# This probably should go to appropriate abstractions<br />
owner @{HOME}/.config/fontconfig/fonts.conf r,<br />
owner @{HOME}/.config/gtk-3.0/bookmarks r,<br />
owner @{HOME}/.config/pulse/cookie krw,<br />
owner @{HOME}/.icons/** r,<br />
owner @{HOME}/.kde/share/config/kioslaverc r,<br />
<br />
# Denials<br />
deny owner @{HOME}/.mozilla/ r,<br />
deny owner @{HOME}/.mozilla/** r,<br />
deny /sys/devices/virtual/dmi/** r,<br />
&#125;}}<br />
<br />
{{Note|This example assumes that Skype is configured to save received files into {{ic|~/Public}}. Feel free to change it to any folder you like.}}<br />
<br />
To use the profile, first be sure {{ic|securityfs}} is mounted,<br />
# mount -t securityfs securityfs /sys/kernel/security<br />
<br />
Load the profile by the command,<br />
# apparmor_parser -r /etc/apparmor.d/usr.bin.skype<br />
<br />
Now you can run Skype restricted but as your own user. Denials are logged in {{ic|messages.log}}.<br />
<br />
=== TOMOYO ===<br />
<br />
Follow the instructions [[TOMOYO_Linux#TOMOYO_Linux_2.x|here]] to install TOMOYO. Please note that this section describes using TOMOYO 2.5.<br />
<br />
During Skype audit it was discovered that Skype reads DMI information and Mozilla profile. To give Skype minimal access to your system using TOMOYO, please follow these steps.<br />
<br />
* Open {{ic|/etc/tomoyo/exception_policy.conf}} file and add these lines:<br />
<br />
{{bc|path_group SKYPE_DIRS /home/\*/.Skype/<br />
path_group SKYPE_DIRS /home/\*/.Skype/\{\*\}/<br />
path_group SKYPE_DIRS /home/\*/.config/Skype/\{\*\}/<br />
path_group SKYPE_DIRS /usr/share/skype/\{\*\}/<br />
path_group SKYPE_DIRS /home/pf/work/tmp/\{\*\}/<br />
path_group SKYPE_FILES /home/\*/.Skype/\{\*\}/\*<br />
path_group SKYPE_FILES /home/\*/.config/Skype/\{\*\}/\*<br />
path_group SKYPE_FILES /usr/share/skype/\{\*\}/\*<br />
path_group SKYPE_FILES /home/pf/work/tmp/\{\*\}/\*<br />
path_group SKYPE_FILES /home/\*/.Skype/\*<br />
path_group SKYPE_FILES /home/\*/.config/Skype/\*<br />
path_group SKYPE_FILES /usr/share/skype/\*<br />
path_group SKYPE_FILES /home/pf/work/tmp/\*<br />
path_group ICONS_DIRS /usr/share/icons/\{\*\}/<br />
path_group ICONS_FILES /usr/share/icons/\{\*\}/\*<br />
path_group ICONS_FILES /usr/share/icons/\*<br />
initialize_domain /usr/bin/skype from any<br />
initialize_domain /usr/lib32/skype/skype from any}}<br />
<br />
Note that {{ic|/home/pf/work/tmp}} folder is only the folder to which Skype will be able to save received files and from which it will be able to send all files. You have to change this folder.<br />
<br />
* Then open {{ic|/etc/tomoyo/domain_policy.conf}} and add the following lines:<br />
<br />
{{bc|<kernel> /usr/bin/skype<br />
use_profile 3<br />
use_group 0<br />
<br />
misc env \*<br />
file read /bin/bash<br />
file read /usr/bin/bash<br />
file read/write /dev/tty<br />
file read /usr/lib/locale/locale-archive<br />
file read /usr/lib/gconv/gconv-modules<br />
file read /usr/bin/skype<br />
file read /usr/lib32/skype/skype<br />
file execute /usr/lib32/skype/skype exec.realpath&#61;"/usr/lib32/skype/skype" exec.argv[0]&#61;"/usr/lib32/skype/skype"<br />
<br />
<kernel> /usr/lib32/skype/skype<br />
use_profile 3<br />
use_group 0<br />
<br />
file append /dev/snd/pcm\*<br />
file chmod /home/\*/.Skype/ 0700<br />
file create /home/\*/.cache/fontconfig/\* 0600-0666<br />
file create /tmp/qtsingleapp-\*-lockfile 0600-0666<br />
file create @SKYPE_FILES 0600-0666<br />
file execute /usr/bin/firefox<br />
file execute /usr/bin/gnome-open<br />
file execute /usr/bin/notify-send<br />
file execute /usr/bin/opera<br />
file execute /usr/bin/xdg-open<br />
file ioctl /dev/snd/\* 0-0xFFFFFFFFFFFFFFFF<br />
file ioctl /dev/video0 0-0xFFFFFFFFFFFFFFFF<br />
file ioctl anon_inode:inotify 0x541B<br />
file ioctl socket:[family&#61;1:type&#61;2:protocol&#61;0] 0x8910<br />
file ioctl socket:[family&#61;1:type&#61;2:protocol&#61;0] 0x8933<br />
file ioctl socket:[family&#61;2:type&#61;1:protocol&#61;6] 0x541B<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x541B<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x8912<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x8927<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x8B01<br />
file link /home/\*/.cache/fontconfig/\* /home/\*/.cache/fontconfig/\*<br />
file mkdir /home/\*/.cache/fontconfig/\* 0600<br />
file mkdir @SKYPE_DIRS 0700-0777<br />
file mksock /tmp/qtsingleapp-\* 0755<br />
file read /dev/urandom<br />
file read /etc/fonts/conf.avail/\*.conf<br />
file read /etc/fonts/conf.d/\*.conf<br />
file read /etc/fonts/fonts.conf<br />
file read /etc/group<br />
file read /etc/host.conf<br />
file read /etc/hosts<br />
file read /etc/machine-id<br />
file read /etc/nsswitch.conf<br />
file read /etc/passwd<br />
file read /etc/resolv.conf<br />
file read /home/\*/.ICEauthority<br />
file read /home/\*/.XCompose<br />
file read /home/\*/.Xauthority<br />
file read /home/\*/.Xdefaults<br />
file read /home/\*/.fontconfig/\*<br />
file read /home/\*/.config/fontconfig/\*<br />
file read /usr/lib/locale/locale-archive<br />
file read /usr/lib32/gconv/UTF-16.so<br />
file read /usr/lib32/gconv/gconv-modules<br />
file read /usr/lib32/libv4l/v4l2convert.so<br />
file read /usr/lib32/qt/plugins/bearer/libq\*bearer.so<br />
file read /usr/lib32/qt/plugins/iconengines/libqsvgicon.so<br />
file read /usr/lib32/qt/plugins/imageformats/libq\*.so<br />
file read /usr/lib32/qt/plugins/inputmethods/libqimsw-multi.so<br />
file read /usr/lib32/skype/skype<br />
file read /usr/share/X11/locale/\*/Compose<br />
file read /usr/share/X11/locale/\*/XLC_LOCALE<br />
file read /usr/share/X11/locale/compose.dir<br />
file read /usr/share/X11/locale/locale.alias<br />
file read /usr/share/X11/locale/locale.dir<br />
file read /usr/share/alsa/alsa.conf<br />
file read /usr/share/alsa/cards/\*.conf<br />
file read /usr/share/alsa/pcm/\*.conf<br />
file read /usr/share/fonts/\*/\*/\*<br />
file read @ICONS_FILES<br />
file read proc:/cpuinfo<br />
file read proc:/stat<br />
file read proc:/sys/kernel/osrelease<br />
file read proc:/sys/kernel/ostype<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/\*/modalias<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/\*/video4linux/video0/dev<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/idProduct<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/idVendor<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/speed<br />
file read sysfs:/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq<br />
file read sysfs:/devices/system/cpu/cpu0/cpufreq/scaling_max_freq<br />
file read sysfs:/devices/system/cpu/online<br />
file read/write /dev/snd/\*<br />
file read/write /dev/video0<br />
file read/write/truncate /home/\*/.config/Trolltech.conf<br />
file read/write/unlink /home/\*/.cache/fontconfig/\*<br />
file read/write/unlink /tmp/qtsingleapp-\*<br />
file read/write/unlink/truncate @SKYPE_FILES<br />
file rename /home/\*/.cache/fontconfig/\* /home/\*/.cache/fontconfig/\*<br />
file rename @SKYPE_DIRS @SKYPE_DIRS<br />
file rename @SKYPE_FILES @SKYPE_FILES<br />
file rmdir @SKYPE_DIRS<br />
misc env \*<br />
network inet dgram bind 0.0.0.0 0-65535<br />
network inet dgram bind 127.0.0.1 0<br />
network inet dgram bind/send 0.0.0.0-255.255.255.255 0-65535<br />
network inet stream bind/listen 0.0.0.0 0-65535<br />
network inet stream connect 0.0.0.0-255.255.255.255 0-65535<br />
network unix stream bind/listen /tmp/qtsingleapp-\*<br />
network unix stream connect /tmp/.ICE-unix/\*<br />
network unix stream connect /tmp/qtsingleapp-\*<br />
network unix stream connect /var/run/dbus/system_bus_socket<br />
network unix stream connect /var/run/nscd/socket<br />
network unix stream connect \000/tmp/.ICE-unix/\*<br />
network unix stream connect \000/tmp/.X11-unix/X0<br />
network unix stream connect \000/tmp/dbus-\*<br />
<br />
<kernel> /usr/lib32/skype/skype /usr/bin/xdg-open<br />
use_profile 0<br />
use_group 0<br />
<br />
<br />
<kernel> /usr/lib32/skype/skype /usr/bin/gnome-open<br />
use_profile 0<br />
use_group 0<br />
<br />
<kernel> /usr/lib32/skype/skype /usr/bin/notify-send<br />
use_profile 0<br />
use_group 0}}<br />
<br />
* After finishing editing reload TOMOYO config files by executing these commands:<br />
<br />
{{bc|# tomoyo-loadpolicy -df </etc/tomoyo/domain_policy.conf<br />
# tomoyo-loadpolicy -ef </etc/tomoyo/exception_policy.conf}}<br />
<br />
Voilà — your Skype is sandboxed now.<br />
<br />
Please note that this config is generated on 64-bit Arch system, and some of your ioctls and library paths may differ from mentioned above. So in order to fine-tune TOMOYO config for your Skype load {{ic|tomoyo-auditd}} daemon:<br />
<br />
# systemctl start tomoyo-auditd<br />
<br />
Then go to {{ic|/var/log/tomoyo}} folder and start watching {{ic|reject_003.log}}:<br />
<br />
tail -f reject_003.log<br />
<br />
The output of this command will show you rejected actions for Skype, so you'll be able to add them to {{ic|domain_policy.conf}} file if needed.<br />
<br />
Detailed guide about TOMOYO configuring can be found [http://tomoyo.sourceforge.jp/2.5/index.html.en here].<br />
<br />
=== Use Skype with special user ===<br />
<br />
Instead of using AppArmor or TOMOYO which require the installation of extra packages, one may prefer to add a special user. This user is only used for running Skype within one's normal environment. This approach restricts Skype to reading only the data of this particular user instead of one's main user. (The new user should not be used for any other thing. Skype only.)<br />
<br />
An AUR package, [https://aur.archlinux.org/packages/skype-restricted/ skype-restricted] exists that will run skype as a separate user ("_skype") cleanly. It's heavily based on the information in this section.<br />
<br />
Optionally, we first add a default group for the skype user. I will call the new user and its default group "skype". The security advantage in keeping the "skype" user in its separate group is that it can be restricted from accessing some places other users are allowed in.<br />
# groupadd skype<br />
Then we have to add the new user:<br />
# useradd<br />
Enter the details for the new user (assumed login name: "skype"). If you created the default "skype" group and want to keep "skype" outside the "users" group, enter "skype" when the wizard asks for the initial group. As additional groups we need "audio,video,pulse-access,pulse-rt".<br />
<br />
Now add the following line to {{ic|/home/skype/.bashrc}}:<br />
export DISPLAY=":0.0"<br />
<br />
At last we define the alias (e.g. in {{ic|~/.bashrc}}):<br />
alias skype='xhost +local: && su skype -c skype'<br />
Now we can start Skype as the newly created user simply by running {{Ic|skype}} from the command line and entering the password of the user skype.<br />
<br />
If you are tired of typing in the skype user's password every time, make sure you installed the [[sudo]] package, run {{Ic|visudo}} then add this line at the bottom:<br />
%wheel ALL=(skype) NOPASSWD: /usr/bin/skype<br />
<br />
And use this alias to launch skype:<br />
alias skype='xhost +local: && sudo -u skype /usr/bin/skype'<br />
<br />
{{Note|If you forget the {{ic|xhost}} command, Skype may fail with a "No protocol specified" error on stdout.}}<br />
<br />
I noticed that the newly created user is able to read some of the files in my home directory because the permissions were a+r, so I changed them manually to a-r u+r and changed umask from 022 to 066.<br />
<br />
In order to restrict user "skype" accessing your external drive mounted in {{ic|/media/data}} for instance, make sure first that "skype" does not belong to group "users" (if you used the default group "skype", everything should be fine), then change the accesses on the mount point:<br />
# chown :users /media/data<br />
# chmod o-rwx /media/data<br />
This way, it is ensured that only the owner (normally "root") and "users" can access the specified directory tree while the others, including "skype", will be forbidden.<br />
<br />
==== Open URLs in your user's browser ====<br />
<br />
When one clicks URL in chat window, skype execute [[xdg-open]] to handle it. By default {{ic|xdg-open}} uses default web browser for skype user environment. In order to open links in your user's browser perform next setup.<br />
<br />
{{Note|<br />
* [[Sudo]] should be installed and properly configured.<br />
* Current example uses [[firefox]] as preferred browser.<br />
* Do not forget to adjust ''your_user'' to proper value.<br />
}}<br />
<br />
Log in as skype user:<br />
$ sudo su - skype<br />
<br />
Create local preferences dir:<br />
$ mkdir -p ~/.local/share/applications<br />
<br />
Create {{ic|/home/skype/.local/share/applications/firefox-sudo.desktop}} file:<br />
[Desktop Entry]<br />
Name=Firefox<br />
Exec=/home/skype/firefox-wrapper %u<br />
Terminal=false<br />
Type=Application<br />
Categories=Network;WebBrowser;<br />
<br />
Set {{ic|firefox-sudo.desktop}} to manage HTTP and HTTPS URLs:<br />
$ xdg-mime default firefox-sudo.desktop x-scheme-handler/http<br />
$ xdg-mime default firefox-sudo.desktop x-scheme-handler/https<br />
<br />
(Optionally) add FTP handler:<br />
$ xdg-mime default firefox-sudo.desktop x-scheme-handler/ftp<br />
<br />
Create {{ic|/home/skype/firefox-wrapper}} script (adjust ''your_user''):<br />
#!/bin/bash<br />
DISPLAY=:0.0 HOME=/home/''your_user'' sudo -u ''your_user'' /usr/lib/firefox/firefox -new-tab $1<br />
<br />
Make it executable:<br />
$ chmod +x ~/firefox-wrapper<br />
<br />
Now as root user open {{ic|/etc/sudoers}}:<br />
# visudo<br />
<br />
And add permission for skype user to exec user's browser (adjust ''your_user''):<br />
skype ALL=(''your_user'') NOPASSWD: /usr/lib/firefox/firefox -new-tab http*, /usr/lib/firefox/firefox -new-tab ftp*<br />
<br />
==== Access received files ====<br />
<br />
By default {{ic|skype}} stores received files with 600 permissions (only owner can access them). One may use [https://www.archlinux.org/packages/?sort=&q=incron incron] to perform automatic permission fix upon downloading.<br />
<br />
{{Note|This example assumes that you configure skype to save received files into {{ic|/home/skype/downloads}}}}<br />
<br />
Make skype home dir and download dir accessible:<br />
# chmod 755 /home/skype /home/skype/downloads<br />
<br />
Install incron with the {{Pkg|incron}} package from the [[official repositories]], and enable and start {{ic|incrond}} [[systemd#Using units|using systemd]].<br />
Open incrontab for root user:<br />
# incrontab -e<br />
<br />
Add incron job:<br />
/home/skype/downloads IN_CREATE chmod 644 $@/$#<br />
<br />
Save changes and exit incrontab editor.<br />
<br />
To test incron in action just enter skype donwload dir and create test file:<br />
# cd /home/skype/downloads<br />
# install -m 600 /dev/null test.txt<br />
# ls -l test.txt<br />
<br />
File permissions should be 644 or -rw-r--r--<br />
<br />
(Optionally) link skype download dir into your home dir:<br />
$ ln -s /home/skype/downloads ~/skype_files<br />
<br />
== Skype plugin for Pidgin ==<br />
<br />
See [[Pidgin#Skype plugin]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Skype crashes immediately ===<br />
<br />
Try creating the directory {{ic|~/.Skype/Logs}}.<br />
<br />
=== Skype crashes shortly after login ===<br />
<br />
If Skype crashes shortly after logging in, changing the rights for {{ic|libpulse.so.0.12.4}} (minor version might differ) and {{ic|libpulse-simple.so.0.0.3}} might fix the issue.[https://bugs.launchpad.net/ubuntu/+source/ia32-libs/+bug/646862/comments/14]<br />
<br />
# cd /usr/lib<br />
# chmod ugo-r libpulse.so.0.12.*<br />
# chmod ugo-r libpulse-simple.so.0.0.3<br />
<br />
64bit users might have to cd to {{ic|/usr/lib32}} instead.<br />
<br />
=== I can receive multiple audio streams, but I can only send one ===<br />
<br />
Skype can send and receive audio and I still hear other sounds playing from other applications, but I cannot record my microphone with other applications. That is because Skype or aoss blocks the audio input for itself.<br />
<br />
=== No video with GSPCA webcams ===<br />
<br />
For i686, install {{Pkg|v4l-utils}}, userspace tools and conversion library for Video 4 Linux, and run Skype with<br />
<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
to start Skype with v4l1 compatibility.<br />
<br />
For x86_64, install {{Pkg|lib32-v4l-utils}} from [multilib] repository and run Skype with<br />
<br />
LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype<br />
<br />
To make it running from DE menus and independent of Skype updates, you can add alias (e.g. in {{ic|~/.bashrc}}):<br />
<br />
alias skype='LD_PRELOAD=/usr/''libxx''/libv4l/v4l1compat.so skype'<br />
<br />
where ''libxx'' should be edited as appropriate.<br />
<br />
=== No video with Compiz ===<br />
<br />
Try launching Skype setting an environment variable like this:<br />
<br />
$ XLIB_SKIP_ARGB_VISUALS=1 skype<br />
<br />
=== Skype does not use my GTK+ theme, even though other Qt apps do ===<br />
<br />
Recent versions of Skype allow you to change the theme via the Options menu. However, selecting the GTK+ option may not work properly. This is probably because you do not have a 32-bit theme engine installed. Try to find the engine your theme uses in the multilib repository or the [[AUR]]. If you have no idea which engine your theme is using, the easiest fix is to install {{AUR|lib32-gtk-engines}}. This does however contain quite a lot of packages, so the best would be to find and install only the needed package.<br />
<br />
{{Note|You may not have to install ''lib32-gtk-engines''. First try if the following steps work for you if you only install ''lib32-gtk2'' and a GTK+2 theme respectively. See also the [https://bbs.archlinux.org/viewtopic.php?pid&#61;1200975#p1200975 forums].}}<br />
<br />
Once installed, it will still not work unless you have a 32-bit version of GConf installed. You could build and install {{AUR|lib32-gconf}} if desired, but there is an easier workaround. First, create or edit {{ic|~/.gtkrc-2.0}} so that it contains the following line:<br />
<br />
$ gtk-theme-name = "''My theme''"<br />
<br />
Replace ''My theme by'' the name of your theme, but leave the quotes. Second, run Skype like this:<br />
<br />
$ export GTK2_RC_FILES="/etc/gtk-2.0/gtkrc:$HOME/.gtkrc-2.0"<br />
$ skype<br />
<br />
The GTK+ theme should now appear correctly. You can make this permanent either by running Skype from a script containing the above 2 lines, or by exporting GTK2_RC_FILES in {{ic|~/.xprofile}} or {{ic|~/.xinitrc}}, depending on how you start X.<br />
<br />
If you cannot change the theme in the Options menu, run Skype using the following command:<br />
<br />
$ /usr/bin/skype --disable-cleanlooks -style GTK<br />
<br />
If you wish menus within desktop environments to load Skype with a GTK+ theme by default then modify the 'Exec' line of {{ic|/usr/share/applications/skype.desktop}} so that it reads:<br />
<br />
$ Exec=/usr/bin/skype --disable-cleanlooks -style GTK<br />
<br />
Similarly if you have set Skype to autostart then modify {{ic|~/.config/autostart/skype.desktop}} in the same way.<br />
<br />
=== The microphone does not work ===<br />
<br />
Run amixer:<br />
<br />
$ amixer<br />
<br />
and check if you have an output for '''Capture''' similar to the one below.<br />
<br />
Simple mixer control 'Capture',0<br />
Capabilities: cvolume cswitch penum<br />
Capture channels: Front Left - Front Right<br />
Limits: Capture 0 - 15<br />
Front Left: Capture 8 [53%] [12.00dB] [on]<br />
Front Right: Capture 8 [53%] [12.00dB] [on]<br />
<br />
If your output is similar, your microphone is working just fine, and the issue is either hardware related (broken microphone) or your volume needs to be checked. If you do not have an output similar to the one above or, more specifically, if both '''Front Left''' and '''Front Right''' are 0% or show an '''[off]''' tag at the end, then your microphone settings need to be rectified.<br />
<br />
In either case, try to run:<br />
<br />
$ alsamixer<br />
<br />
and press {{ic|F5}} to show all channels. Using the arrow keys navigate all the way to the end and increase '''Capture'''. If you do not see a left and right channel for '''Capture''', press the space bar. Doing this turns the left and right channels on. Check that '''Input Source''' is set to the correct value (e.g. ''[Front Mic]''): navigate through the values with up and down arrow keys. If your microphone is an array built into your monitor, or you have a similar setup, make sure to increase the volume for the '''Digital''' column too. If you have multiple microphones, you may have to play around with the '''Mic Jack''' channel to get your desired setting.<br />
<br />
You may want to save your mixer settings with:<br />
<br />
# alsactl -f /var/lib/alsa/asound.state store<br />
<br />
=== No incoming video stream ===<br />
<br />
If skype shows a black square for the video preview, but something else (like {{ic|xawtv -c /dev/video0}}) shows video correctly, you might need to start Skype with:<br />
<br />
export XLIB_SKIP_ARGB_VISUALS=1 && skype<br />
<br />
Another possible workaround is to preload ''v4l1compat.so'':<br />
<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
For my machine this doesn't seem to work; instead I do<br />
{{bc|<nowiki><br />
cd /usr/lib/lib32/libv4l && LD_PRELOAD=v4l1compat.so skype;<br />
</nowiki>|bc}}<br />
<br />
=== Low sound in Skype, but works everywhere else ===<br />
<br />
If you are sure your microphone is configured correctly in ALSA (try recording with a 3rd-party-utility to determine whether it is an ALSA or Skype problem), it is most likely because Skype is controlling your volume levels. Simply disable this feature in the voice settings page in the Skype configuration window.<br />
<br />
This may also help if your microphone input is automatically lowered until 0.<br />
<br />
=== Monster/low-octave "growling" distortion over mic ===<br />
<br />
Some users with newer kernels are experiencing a monster-like growling distortion of their sound stream on the other end of Skype. This can be fixed by creating a dummy ALSA device or by removing {{ic|~/.Skype/shared.xml}}. See https://bbs.archlinux.org/viewtopic.php?pid=819500#p819500 for more information.<br />
<br />
=== Skype can only see PulseAudio, but not ALSA devices ===<br />
<br />
Turn PulseAudio autospawn off and kill PulseAudio:<br />
$ echo "autospawn = no" > ~/.pulse/client.conf<br />
$ killall pulseaudio<br />
And restart Skype.<br />
<br />
=== Crackling/noisy sound (mainly using 64-bit OS) ===<br />
<br />
Edit {{ic|/etc/pulse/default.pa}} and change the following line<br />
<br />
load-module module-udev-detect<br />
<br />
to<br />
<br />
load-module module-udev-detect tsched=0<br />
<br />
See also: [[PulseAudio#Glitches, skips or crackling]].<br />
<br />
=== Problem with Audio Playback on x86_64 ===<br />
<br />
See [[Pulseaudio#Skype (x86_64 only)]], even if you are not using PulseAudio.<br />
<br />
=== Skype sounds stops media player or other sound sources === <br />
<br />
You can try commenting out the following modules in {{ic|/etc/pulse/default.pa}}<br />
#module-cork-music-on-phone<br />
#module-role-cork<br />
<br />
If that does not help, you can try changing flat-volumes to no in {{ic|/etc/pulse/daemon.conf}}.<br />
flat-volumes = no</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Skype&diff=278445Skype2013-10-12T03:05:03Z<p>Bluerider: /* No incoming video stream */</p>
<hr />
<div>[[bg:Skype]]<br />
[[cs:Skype]]<br />
[[lt:Skype]]<br />
[[ru:Skype]]<br />
[[uk:Skype]]<br />
[[Category:Audio/Video]]<br />
[[Category:Telephony and Voice]]<br />
== Installation ==<br />
<br />
[[pacman|Install]] {{Pkg|skype}} from the [[official repositories]]. If you have a 64-bit system, enable the [[multilib]] repository first as Skype is 32-bit only.<br />
<br />
Running Skype is just as easy. Type {{Ic|skype}} into a terminal or double-click the Skype icon on your desktop or in your DE's application menu.<br />
<br />
== Skype sound ==<br />
<br />
Skype supports [[ALSA]] and [[PulseAudio]]. [[OSS]] is no longer supported.<br />
<br />
=== ALSA ===<br />
<br />
Sound should work out of the box, if not you can select a sound device to use in Skype options. If you have problems with Skype blocking your sound device, you only need to add the following to your {{ic|~/.asoundrc}}<br />
pcm.dmixout {<br />
# Just pass this on to the system dmix<br />
type plug<br />
slave {<br />
pcm "dmix"<br />
}<br />
}<br />
then you can start Skype as normal, go to the audio options and select dmixout as your speaker- and ringingdevice.<br />
<br />
=== PulseAudio ===<br />
<br />
Sound should work out of the box, if not you can select another input using pavucontrol (you may have to install it first).<br />
<br />
If you are on x86_64 and use the multilib {{Pkg|skype}} package, you also need {{Pkg|lib32-libpulse}}.<br />
<br />
=== OSS (Pre-2.0, no longer available) ===<br />
<br />
Option B is preferred over other options.<br />
With option B you can use Skype AND let other programs play sound too.<br />
With option C you can do that too, but option B is way easier to set up.<br />
<br />
You can install the legacy {{Pkg|skype-oss}} from Comunity repo.<br />
<br />
If you need 64x-86x support then download an OSS compatible version from [http://www.mediafire.com/?2ydhmj4yo3i here] and the PKGBUILD form [https://aur.archlinux.org/packages.php?ID=18312 here.] Also install {{Pkg|lib32-libxinerama}}. Finally, run<br />
$ makepkg -s<br />
to create the pacman installable package.<br />
<br />
==== A. With OSS or Kernel OSS emulation for ALSA ====<br />
<br />
Start Skype and make sure no other program is using your soundcard.<br />
If you want to use Skype AND let another program play sound too, look at option B instead.<br />
<br />
==== B. Making ALSA + dMix work for Skype ====<br />
<br />
First of all, we need to install the {{Pkg|alsa-oss}} package with [[pacman]].<br />
<br />
Add the following to {{ic|~/.asoundrc}}. If the file does not exist yet, just create it! (Many thanks to Lorenzo Colitti for figuring this out!)<br />
<br />
# .asoundrc to use skype at the same time as other audio apps like xmms<br />
#<br />
# Successfully tested on an IBM x40 with i810_audio using Linux 2.6.15 and<br />
# Debian unstable with skype 1.2.0.18-API. No sound daemons (asound, esd, etc.)<br />
# running. However, YMMV.<br />
#<br />
# For background, see:<br />
#<br />
# https://bugtrack.alsa-project.org/alsa-bug/view.php?id=1228<br />
# https://bugtrack.alsa-project.org/alsa-bug/view.php?id=1224<br />
#<br />
# (C) 2006-06-03 Lorenzo Colitti - http://www.colitti.com/lorenzo/<br />
# Licensed under the GPLv2 or later<br />
<br />
pcm.skype {<br />
type asym<br />
playback.pcm "skypeout"<br />
capture.pcm "skypein"<br />
}<br />
<br />
pcm.skypein {<br />
# Convert from 8-bit unsigned mono (default format set by aoss when<br />
# /dev/dsp is opened) to 16-bit signed stereo (expected by dsnoop)<br />
#<br />
# We cannot just use a "plug" plugin because although the open will<br />
# succeed, the buffer sizes will be wrong and we will hear no sound at<br />
# all.<br />
type route<br />
slave {<br />
pcm "skypedsnoop"<br />
format S16_LE<br />
}<br />
ttable {<br />
0 {0 0.5}<br />
1 {0 0.5}<br />
}<br />
}<br />
<br />
pcm.skypeout {<br />
# Just pass this on to the system dmix<br />
type plug<br />
slave {<br />
pcm "dmix"<br />
}<br />
}<br />
<br />
pcm.skypedsnoop {<br />
type dsnoop<br />
ipc_key 1133<br />
slave {<br />
# "Magic" buffer values to get skype audio to work<br />
# If these are not set, opening /dev/dsp succeeds but no sound<br />
# will be heard. According to the ALSA developers this is due<br />
# to skype abusing the OSS API.<br />
pcm "hw:0,0"<br />
period_size 256<br />
periods 16<br />
buffer_size 16384<br />
}<br />
bindings {<br />
0 0<br />
}<br />
}<br />
<br />
If you get the error message :<br />
<br />
The dmix plugin supports only playback stream<br />
<br />
then add the following to {{ic|.asoundrc}}:<br />
<br />
pcm.asymed {<br />
type asym<br />
playback.pcm "dmix"<br />
capture.pcm "dsnoop"<br />
}<br />
<br />
pcm.!default {<br />
type plug<br />
slave.pcm "asymed"<br />
}<br />
<br />
<br />
Now run Skype in this way each time you want to use it:<br />
ALSA_OSS_PCM_DEVICE="skype" aoss skype<br />
<br />
Optionally you can make a script to start Skype:<br />
<br />
As root, create the file: {{ic|/usr/bin/askype}}<br />
<br />
# Little script to run Skype correctly using the modified .asoundrc<br />
# See: https://wiki.archlinux.org/index.php/Skype for more information!<br />
#<br />
# Questions/Remarks: profox@debianbox.be<br />
<br />
ALSA_OSS_PCM_DEVICE="skype" aoss skype<br />
<br />
Now make sure every user is able to execute the file:<br />
# chmod a+x /usr/bin/askype<br />
<br />
You can also fix the menu entry so you can start Skype from the your window manager's menu:<br />
<br />
Edit the file: {{ic|/usr/share/applications/skype.desktop}}<br />
<br />
[Desktop Entry]<br />
Name=Skype<br />
Comment=P2P software for high-quality voice communication<br />
Exec=askype<br />
Icon=skype.png<br />
Terminal=0<br />
Type=Application<br />
Encoding=UTF-8<br />
Categories=Network;Application;<br />
<br />
Sometimes it takes a while for Skype to start up but once it is loaded it should work ok!<br />
<br />
==== C. Using OSS emulation with oss2jack ====<br />
<br />
{{AUR|oss2jack}} is another way to have OSS emulation without using ALSA directly. Instead, oss2jack creates a OSS device that forwards everything to JACK (JACK Audio Connection Kit), which in turn mixes, then outputs to the standard ALSA device.<br />
<br />
== Securing Skype ==<br />
<br />
There are a couple of reasons you might want to restrict Skype's access to your computer:<br />
* The skype binary is disguised against decompiling, so nobody is (still) able to reproduce what it really does.<br />
* It produces encrypted traffic even when you are not actively using Skype.<br />
* ...<br />
See [http://www1.cs.columbia.edu/~salman/skype/index.html] for more information.<br />
<br />
=== AppArmor ===<br />
<br />
Follow the instructions [[AppArmor|here]] to set up AppArmor.<br />
<br />
The userland tools for AppArmor come with a collection of example profiles. Skype is amongst them. Copy this to the directory where AppArmor profiles are stored.<br />
# cp -ip /etc/apparmor/profiles/extras/usr.bin.skype /etc/apparmor.d/<br />
<br />
For whatever reason, the profile is not complete. You may wish to modify it further. Here is an example for Skype 4:<br />
<br />
{{bc|#include <tunables/global><br />
/usr/bin/skype {<br />
#include <abstractions/audio><br />
#include <abstractions/consoles><br />
#include <abstractions/dbus-session><br />
#include <abstractions/gnome><br />
#include <abstractions/kde><br />
#include <abstractions/nameservice><br />
#include <abstractions/video><br />
<br />
# Executables<br />
/usr/bin/skype ixmr,<br />
/usr/lib{,32}/skype/skype ixmr,<br />
/usr/bin/xdg-open PUxmr,<br />
<br />
# Configuration files<br />
owner @{HOME}/.Skype/ rw,<br />
owner @{HOME}/.Skype/** krw,<br />
owner @{HOME}/.config/Skype/ rw,<br />
owner @{HOME}/.config/Skype/** krw,<br />
<br />
# Downloads/uploads directory<br />
owner @{HOME}/Public/ rw,<br />
owner @{HOME}/Public/** krw,<br />
<br />
# Libraries<br />
/usr/lib{,32}/libv4l/v4l2convert.so mr,<br />
/usr/share/skype/lib/libQtWebKit.so.4 mr,<br />
<br />
# Shared data<br />
/usr/share/skype/ r,<br />
/usr/share/skype/** r,<br />
<br />
# Devices<br />
/dev/ r,<br />
/dev/video[0-9]* mrw,<br />
<br />
# System information<br />
/etc/machine-id r,<br />
@{PROC}/sys/kernel/{ostype,osrelease} r,<br />
@{PROC}/sys/vm/overcommit_memory r,<br />
@{PROC}/[0-9]*/net/arp r,<br />
owner @{PROC}/[0-9]*/cmdline r,<br />
owner @{PROC}/[0-9]*/status r,<br />
owner @{PROC}/[0-9]*/task/ r,<br />
owner @{PROC}/[0-9]*/task/[0-9]*/stat r,<br />
/sys/devices/system/cpu/ r,<br />
/sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_{cur_freq,max_freq} r,<br />
/sys/devices/pci*/*/usb[0-9]*/*/*/*/modalias r,<br />
/sys/devices/pci*/*/usb[0-9]*/*/*/*/video4linux/video[0-9]*/dev r,<br />
/sys/devices/pci*/*/usb[0-9]*/*/*/{idVendor,idProduct,speed} r,<br />
<br />
# This probably should go to appropriate abstractions<br />
owner @{HOME}/.config/fontconfig/fonts.conf r,<br />
owner @{HOME}/.config/gtk-3.0/bookmarks r,<br />
owner @{HOME}/.config/pulse/cookie krw,<br />
owner @{HOME}/.icons/** r,<br />
owner @{HOME}/.kde/share/config/kioslaverc r,<br />
<br />
# Denials<br />
deny owner @{HOME}/.mozilla/ r,<br />
deny owner @{HOME}/.mozilla/** r,<br />
deny /sys/devices/virtual/dmi/** r,<br />
&#125;}}<br />
<br />
{{Note|This example assumes that Skype is configured to save received files into {{ic|~/Public}}. Feel free to change it to any folder you like.}}<br />
<br />
To use the profile, first be sure {{ic|securityfs}} is mounted,<br />
# mount -t securityfs securityfs /sys/kernel/security<br />
<br />
Load the profile by the command,<br />
# apparmor_parser -r /etc/apparmor.d/usr.bin.skype<br />
<br />
Now you can run Skype restricted but as your own user. Denials are logged in {{ic|messages.log}}.<br />
<br />
=== TOMOYO ===<br />
<br />
Follow the instructions [[TOMOYO_Linux#TOMOYO_Linux_2.x|here]] to install TOMOYO. Please note that this section describes using TOMOYO 2.5.<br />
<br />
During Skype audit it was discovered that Skype reads DMI information and Mozilla profile. To give Skype minimal access to your system using TOMOYO, please follow these steps.<br />
<br />
* Open {{ic|/etc/tomoyo/exception_policy.conf}} file and add these lines:<br />
<br />
{{bc|path_group SKYPE_DIRS /home/\*/.Skype/<br />
path_group SKYPE_DIRS /home/\*/.Skype/\{\*\}/<br />
path_group SKYPE_DIRS /home/\*/.config/Skype/\{\*\}/<br />
path_group SKYPE_DIRS /usr/share/skype/\{\*\}/<br />
path_group SKYPE_DIRS /home/pf/work/tmp/\{\*\}/<br />
path_group SKYPE_FILES /home/\*/.Skype/\{\*\}/\*<br />
path_group SKYPE_FILES /home/\*/.config/Skype/\{\*\}/\*<br />
path_group SKYPE_FILES /usr/share/skype/\{\*\}/\*<br />
path_group SKYPE_FILES /home/pf/work/tmp/\{\*\}/\*<br />
path_group SKYPE_FILES /home/\*/.Skype/\*<br />
path_group SKYPE_FILES /home/\*/.config/Skype/\*<br />
path_group SKYPE_FILES /usr/share/skype/\*<br />
path_group SKYPE_FILES /home/pf/work/tmp/\*<br />
path_group ICONS_DIRS /usr/share/icons/\{\*\}/<br />
path_group ICONS_FILES /usr/share/icons/\{\*\}/\*<br />
path_group ICONS_FILES /usr/share/icons/\*<br />
initialize_domain /usr/bin/skype from any<br />
initialize_domain /usr/lib32/skype/skype from any}}<br />
<br />
Note that {{ic|/home/pf/work/tmp}} folder is only the folder to which Skype will be able to save received files and from which it will be able to send all files. You have to change this folder.<br />
<br />
* Then open {{ic|/etc/tomoyo/domain_policy.conf}} and add the following lines:<br />
<br />
{{bc|<kernel> /usr/bin/skype<br />
use_profile 3<br />
use_group 0<br />
<br />
misc env \*<br />
file read /bin/bash<br />
file read /usr/bin/bash<br />
file read/write /dev/tty<br />
file read /usr/lib/locale/locale-archive<br />
file read /usr/lib/gconv/gconv-modules<br />
file read /usr/bin/skype<br />
file read /usr/lib32/skype/skype<br />
file execute /usr/lib32/skype/skype exec.realpath&#61;"/usr/lib32/skype/skype" exec.argv[0]&#61;"/usr/lib32/skype/skype"<br />
<br />
<kernel> /usr/lib32/skype/skype<br />
use_profile 3<br />
use_group 0<br />
<br />
file append /dev/snd/pcm\*<br />
file chmod /home/\*/.Skype/ 0700<br />
file create /home/\*/.cache/fontconfig/\* 0600-0666<br />
file create /tmp/qtsingleapp-\*-lockfile 0600-0666<br />
file create @SKYPE_FILES 0600-0666<br />
file execute /usr/bin/firefox<br />
file execute /usr/bin/gnome-open<br />
file execute /usr/bin/notify-send<br />
file execute /usr/bin/opera<br />
file execute /usr/bin/xdg-open<br />
file ioctl /dev/snd/\* 0-0xFFFFFFFFFFFFFFFF<br />
file ioctl /dev/video0 0-0xFFFFFFFFFFFFFFFF<br />
file ioctl anon_inode:inotify 0x541B<br />
file ioctl socket:[family&#61;1:type&#61;2:protocol&#61;0] 0x8910<br />
file ioctl socket:[family&#61;1:type&#61;2:protocol&#61;0] 0x8933<br />
file ioctl socket:[family&#61;2:type&#61;1:protocol&#61;6] 0x541B<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x541B<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x8912<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x8927<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x8B01<br />
file link /home/\*/.cache/fontconfig/\* /home/\*/.cache/fontconfig/\*<br />
file mkdir /home/\*/.cache/fontconfig/\* 0600<br />
file mkdir @SKYPE_DIRS 0700-0777<br />
file mksock /tmp/qtsingleapp-\* 0755<br />
file read /dev/urandom<br />
file read /etc/fonts/conf.avail/\*.conf<br />
file read /etc/fonts/conf.d/\*.conf<br />
file read /etc/fonts/fonts.conf<br />
file read /etc/group<br />
file read /etc/host.conf<br />
file read /etc/hosts<br />
file read /etc/machine-id<br />
file read /etc/nsswitch.conf<br />
file read /etc/passwd<br />
file read /etc/resolv.conf<br />
file read /home/\*/.ICEauthority<br />
file read /home/\*/.XCompose<br />
file read /home/\*/.Xauthority<br />
file read /home/\*/.Xdefaults<br />
file read /home/\*/.fontconfig/\*<br />
file read /home/\*/.config/fontconfig/\*<br />
file read /usr/lib/locale/locale-archive<br />
file read /usr/lib32/gconv/UTF-16.so<br />
file read /usr/lib32/gconv/gconv-modules<br />
file read /usr/lib32/libv4l/v4l2convert.so<br />
file read /usr/lib32/qt/plugins/bearer/libq\*bearer.so<br />
file read /usr/lib32/qt/plugins/iconengines/libqsvgicon.so<br />
file read /usr/lib32/qt/plugins/imageformats/libq\*.so<br />
file read /usr/lib32/qt/plugins/inputmethods/libqimsw-multi.so<br />
file read /usr/lib32/skype/skype<br />
file read /usr/share/X11/locale/\*/Compose<br />
file read /usr/share/X11/locale/\*/XLC_LOCALE<br />
file read /usr/share/X11/locale/compose.dir<br />
file read /usr/share/X11/locale/locale.alias<br />
file read /usr/share/X11/locale/locale.dir<br />
file read /usr/share/alsa/alsa.conf<br />
file read /usr/share/alsa/cards/\*.conf<br />
file read /usr/share/alsa/pcm/\*.conf<br />
file read /usr/share/fonts/\*/\*/\*<br />
file read @ICONS_FILES<br />
file read proc:/cpuinfo<br />
file read proc:/stat<br />
file read proc:/sys/kernel/osrelease<br />
file read proc:/sys/kernel/ostype<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/\*/modalias<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/\*/video4linux/video0/dev<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/idProduct<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/idVendor<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/speed<br />
file read sysfs:/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq<br />
file read sysfs:/devices/system/cpu/cpu0/cpufreq/scaling_max_freq<br />
file read sysfs:/devices/system/cpu/online<br />
file read/write /dev/snd/\*<br />
file read/write /dev/video0<br />
file read/write/truncate /home/\*/.config/Trolltech.conf<br />
file read/write/unlink /home/\*/.cache/fontconfig/\*<br />
file read/write/unlink /tmp/qtsingleapp-\*<br />
file read/write/unlink/truncate @SKYPE_FILES<br />
file rename /home/\*/.cache/fontconfig/\* /home/\*/.cache/fontconfig/\*<br />
file rename @SKYPE_DIRS @SKYPE_DIRS<br />
file rename @SKYPE_FILES @SKYPE_FILES<br />
file rmdir @SKYPE_DIRS<br />
misc env \*<br />
network inet dgram bind 0.0.0.0 0-65535<br />
network inet dgram bind 127.0.0.1 0<br />
network inet dgram bind/send 0.0.0.0-255.255.255.255 0-65535<br />
network inet stream bind/listen 0.0.0.0 0-65535<br />
network inet stream connect 0.0.0.0-255.255.255.255 0-65535<br />
network unix stream bind/listen /tmp/qtsingleapp-\*<br />
network unix stream connect /tmp/.ICE-unix/\*<br />
network unix stream connect /tmp/qtsingleapp-\*<br />
network unix stream connect /var/run/dbus/system_bus_socket<br />
network unix stream connect /var/run/nscd/socket<br />
network unix stream connect \000/tmp/.ICE-unix/\*<br />
network unix stream connect \000/tmp/.X11-unix/X0<br />
network unix stream connect \000/tmp/dbus-\*<br />
<br />
<kernel> /usr/lib32/skype/skype /usr/bin/xdg-open<br />
use_profile 0<br />
use_group 0<br />
<br />
<br />
<kernel> /usr/lib32/skype/skype /usr/bin/gnome-open<br />
use_profile 0<br />
use_group 0<br />
<br />
<kernel> /usr/lib32/skype/skype /usr/bin/notify-send<br />
use_profile 0<br />
use_group 0}}<br />
<br />
* After finishing editing reload TOMOYO config files by executing these commands:<br />
<br />
{{bc|# tomoyo-loadpolicy -df </etc/tomoyo/domain_policy.conf<br />
# tomoyo-loadpolicy -ef </etc/tomoyo/exception_policy.conf}}<br />
<br />
Voilà — your Skype is sandboxed now.<br />
<br />
Please note that this config is generated on 64-bit Arch system, and some of your ioctls and library paths may differ from mentioned above. So in order to fine-tune TOMOYO config for your Skype load {{ic|tomoyo-auditd}} daemon:<br />
<br />
# systemctl start tomoyo-auditd<br />
<br />
Then go to {{ic|/var/log/tomoyo}} folder and start watching {{ic|reject_003.log}}:<br />
<br />
tail -f reject_003.log<br />
<br />
The output of this command will show you rejected actions for Skype, so you'll be able to add them to {{ic|domain_policy.conf}} file if needed.<br />
<br />
Detailed guide about TOMOYO configuring can be found [http://tomoyo.sourceforge.jp/2.5/index.html.en here].<br />
<br />
=== Use Skype with special user ===<br />
<br />
Instead of using AppArmor or TOMOYO which require the installation of extra packages, one may prefer to add a special user. This user is only used for running Skype within one's normal environment. This approach restricts Skype to reading only the data of this particular user instead of one's main user. (The new user should not be used for any other thing. Skype only.)<br />
<br />
An AUR package, [https://aur.archlinux.org/packages/skype-restricted/ skype-restricted] exists that will run skype as a separate user ("_skype") cleanly. It's heavily based on the information in this section.<br />
<br />
Optionally, we first add a default group for the skype user. I will call the new user and its default group "skype". The security advantage in keeping the "skype" user in its separate group is that it can be restricted from accessing some places other users are allowed in.<br />
# groupadd skype<br />
Then we have to add the new user:<br />
# useradd<br />
Enter the details for the new user (assumed login name: "skype"). If you created the default "skype" group and want to keep "skype" outside the "users" group, enter "skype" when the wizard asks for the initial group. As additional groups we need "audio,video,pulse-access,pulse-rt".<br />
<br />
Now add the following line to {{ic|/home/skype/.bashrc}}:<br />
export DISPLAY=":0.0"<br />
<br />
At last we define the alias (e.g. in {{ic|~/.bashrc}}):<br />
alias skype='xhost +local: && su skype -c skype'<br />
Now we can start Skype as the newly created user simply by running {{Ic|skype}} from the command line and entering the password of the user skype.<br />
<br />
If you are tired of typing in the skype user's password every time, make sure you installed the [[sudo]] package, run {{Ic|visudo}} then add this line at the bottom:<br />
%wheel ALL=(skype) NOPASSWD: /usr/bin/skype<br />
<br />
And use this alias to launch skype:<br />
alias skype='xhost +local: && sudo -u skype /usr/bin/skype'<br />
<br />
{{Note|If you forget the {{ic|xhost}} command, Skype may fail with a "No protocol specified" error on stdout.}}<br />
<br />
I noticed that the newly created user is able to read some of the files in my home directory because the permissions were a+r, so I changed them manually to a-r u+r and changed umask from 022 to 066.<br />
<br />
In order to restrict user "skype" accessing your external drive mounted in {{ic|/media/data}} for instance, make sure first that "skype" does not belong to group "users" (if you used the default group "skype", everything should be fine), then change the accesses on the mount point:<br />
# chown :users /media/data<br />
# chmod o-rwx /media/data<br />
This way, it is ensured that only the owner (normally "root") and "users" can access the specified directory tree while the others, including "skype", will be forbidden.<br />
<br />
==== Open URLs in your user's browser ====<br />
<br />
When one clicks URL in chat window, skype execute [[xdg-open]] to handle it. By default {{ic|xdg-open}} uses default web browser for skype user environment. In order to open links in your user's browser perform next setup.<br />
<br />
{{Note|<br />
* [[Sudo]] should be installed and properly configured.<br />
* Current example uses [[firefox]] as preferred browser.<br />
* Do not forget to adjust ''your_user'' to proper value.<br />
}}<br />
<br />
Log in as skype user:<br />
$ sudo su - skype<br />
<br />
Create local preferences dir:<br />
$ mkdir -p ~/.local/share/applications<br />
<br />
Create {{ic|/home/skype/.local/share/applications/firefox-sudo.desktop}} file:<br />
[Desktop Entry]<br />
Name=Firefox<br />
Exec=/home/skype/firefox-wrapper %u<br />
Terminal=false<br />
Type=Application<br />
Categories=Network;WebBrowser;<br />
<br />
Set {{ic|firefox-sudo.desktop}} to manage HTTP and HTTPS URLs:<br />
$ xdg-mime default firefox-sudo.desktop x-scheme-handler/http<br />
$ xdg-mime default firefox-sudo.desktop x-scheme-handler/https<br />
<br />
(Optionally) add FTP handler:<br />
$ xdg-mime default firefox-sudo.desktop x-scheme-handler/ftp<br />
<br />
Create {{ic|/home/skype/firefox-wrapper}} script (adjust ''your_user''):<br />
#!/bin/bash<br />
DISPLAY=:0.0 HOME=/home/''your_user'' sudo -u ''your_user'' /usr/lib/firefox/firefox -new-tab $1<br />
<br />
Make it executable:<br />
$ chmod +x ~/firefox-wrapper<br />
<br />
Now as root user open {{ic|/etc/sudoers}}:<br />
# visudo<br />
<br />
And add permission for skype user to exec user's browser (adjust ''your_user''):<br />
skype ALL=(''your_user'') NOPASSWD: /usr/lib/firefox/firefox -new-tab http*, /usr/lib/firefox/firefox -new-tab ftp*<br />
<br />
==== Access received files ====<br />
<br />
By default {{ic|skype}} stores received files with 600 permissions (only owner can access them). One may use [https://www.archlinux.org/packages/?sort=&q=incron incron] to perform automatic permission fix upon downloading.<br />
<br />
{{Note|This example assumes that you configure skype to save received files into {{ic|/home/skype/downloads}}}}<br />
<br />
Make skype home dir and download dir accessible:<br />
# chmod 755 /home/skype /home/skype/downloads<br />
<br />
Install incron with the {{Pkg|incron}} package from the [[official repositories]], and enable and start {{ic|incrond}} [[systemd#Using units|using systemd]].<br />
Open incrontab for root user:<br />
# incrontab -e<br />
<br />
Add incron job:<br />
/home/skype/downloads IN_CREATE chmod 644 $@/$#<br />
<br />
Save changes and exit incrontab editor.<br />
<br />
To test incron in action just enter skype donwload dir and create test file:<br />
# cd /home/skype/downloads<br />
# install -m 600 /dev/null test.txt<br />
# ls -l test.txt<br />
<br />
File permissions should be 644 or -rw-r--r--<br />
<br />
(Optionally) link skype download dir into your home dir:<br />
$ ln -s /home/skype/downloads ~/skype_files<br />
<br />
== Skype plugin for Pidgin ==<br />
<br />
See [[Pidgin#Skype plugin]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Skype crashes immediately ===<br />
<br />
Try creating the directory {{ic|~/.Skype/Logs}}.<br />
<br />
=== Skype crashes shortly after login ===<br />
<br />
If Skype crashes shortly after logging in, changing the rights for {{ic|libpulse.so.0.12.4}} (minor version might differ) and {{ic|libpulse-simple.so.0.0.3}} might fix the issue.[https://bugs.launchpad.net/ubuntu/+source/ia32-libs/+bug/646862/comments/14]<br />
<br />
# cd /usr/lib<br />
# chmod ugo-r libpulse.so.0.12.*<br />
# chmod ugo-r libpulse-simple.so.0.0.3<br />
<br />
64bit users might have to cd to {{ic|/usr/lib32}} instead.<br />
<br />
=== I can receive multiple audio streams, but I can only send one ===<br />
<br />
Skype can send and receive audio and I still hear other sounds playing from other applications, but I cannot record my microphone with other applications. That is because Skype or aoss blocks the audio input for itself.<br />
<br />
=== No video with GSPCA webcams ===<br />
<br />
For i686, install {{Pkg|v4l-utils}}, userspace tools and conversion library for Video 4 Linux, and run Skype with<br />
<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
to start Skype with v4l1 compatibility.<br />
<br />
For x86_64, install {{Pkg|lib32-v4l-utils}} from [multilib] repository and run Skype with<br />
<br />
LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype<br />
<br />
To make it running from DE menus and independent of Skype updates, you can add alias (e.g. in {{ic|~/.bashrc}}):<br />
<br />
alias skype='LD_PRELOAD=/usr/''libxx''/libv4l/v4l1compat.so skype'<br />
<br />
where ''libxx'' should be edited as appropriate.<br />
<br />
=== No video with Compiz ===<br />
<br />
Try launching Skype setting an environment variable like this:<br />
<br />
$ XLIB_SKIP_ARGB_VISUALS=1 skype<br />
<br />
=== Skype does not use my GTK+ theme, even though other Qt apps do ===<br />
<br />
Recent versions of Skype allow you to change the theme via the Options menu. However, selecting the GTK+ option may not work properly. This is probably because you do not have a 32-bit theme engine installed. Try to find the engine your theme uses in the multilib repository or the [[AUR]]. If you have no idea which engine your theme is using, the easiest fix is to install {{AUR|lib32-gtk-engines}}. This does however contain quite a lot of packages, so the best would be to find and install only the needed package.<br />
<br />
{{Note|You may not have to install ''lib32-gtk-engines''. First try if the following steps work for you if you only install ''lib32-gtk2'' and a GTK+2 theme respectively. See also the [https://bbs.archlinux.org/viewtopic.php?pid&#61;1200975#p1200975 forums].}}<br />
<br />
Once installed, it will still not work unless you have a 32-bit version of GConf installed. You could build and install {{AUR|lib32-gconf}} if desired, but there is an easier workaround. First, create or edit {{ic|~/.gtkrc-2.0}} so that it contains the following line:<br />
<br />
$ gtk-theme-name = "''My theme''"<br />
<br />
Replace ''My theme by'' the name of your theme, but leave the quotes. Second, run Skype like this:<br />
<br />
$ export GTK2_RC_FILES="/etc/gtk-2.0/gtkrc:$HOME/.gtkrc-2.0"<br />
$ skype<br />
<br />
The GTK+ theme should now appear correctly. You can make this permanent either by running Skype from a script containing the above 2 lines, or by exporting GTK2_RC_FILES in {{ic|~/.xprofile}} or {{ic|~/.xinitrc}}, depending on how you start X.<br />
<br />
If you cannot change the theme in the Options menu, run Skype using the following command:<br />
<br />
$ /usr/bin/skype --disable-cleanlooks -style GTK<br />
<br />
If you wish menus within desktop environments to load Skype with a GTK+ theme by default then modify the 'Exec' line of {{ic|/usr/share/applications/skype.desktop}} so that it reads:<br />
<br />
$ Exec=/usr/bin/skype --disable-cleanlooks -style GTK<br />
<br />
Similarly if you have set Skype to autostart then modify {{ic|~/.config/autostart/skype.desktop}} in the same way.<br />
<br />
=== The microphone does not work ===<br />
<br />
Run amixer:<br />
<br />
$ amixer<br />
<br />
and check if you have an output for '''Capture''' similar to the one below.<br />
<br />
Simple mixer control 'Capture',0<br />
Capabilities: cvolume cswitch penum<br />
Capture channels: Front Left - Front Right<br />
Limits: Capture 0 - 15<br />
Front Left: Capture 8 [53%] [12.00dB] [on]<br />
Front Right: Capture 8 [53%] [12.00dB] [on]<br />
<br />
If your output is similar, your microphone is working just fine, and the issue is either hardware related (broken microphone) or your volume needs to be checked. If you do not have an output similar to the one above or, more specifically, if both '''Front Left''' and '''Front Right''' are 0% or show an '''[off]''' tag at the end, then your microphone settings need to be rectified.<br />
<br />
In either case, try to run:<br />
<br />
$ alsamixer<br />
<br />
and press {{ic|F5}} to show all channels. Using the arrow keys navigate all the way to the end and increase '''Capture'''. If you do not see a left and right channel for '''Capture''', press the space bar. Doing this turns the left and right channels on. Check that '''Input Source''' is set to the correct value (e.g. ''[Front Mic]''): navigate through the values with up and down arrow keys. If your microphone is an array built into your monitor, or you have a similar setup, make sure to increase the volume for the '''Digital''' column too. If you have multiple microphones, you may have to play around with the '''Mic Jack''' channel to get your desired setting.<br />
<br />
You may want to save your mixer settings with:<br />
<br />
# alsactl -f /var/lib/alsa/asound.state store<br />
<br />
=== No incoming video stream ===<br />
<br />
If skype shows a black square for the video preview, but something else (like {{ic|xawtv -c /dev/video0}}) shows video correctly, you might need to start Skype with:<br />
<br />
export XLIB_SKIP_ARGB_VISUALS=1 && skype<br />
<br />
Another possible workaround is to preload ''v4l1compat.so'':<br />
<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
For my machine this doesn't seem to work; instead I do<br />
{{bc|<nowiki><br />
cd /usr/lib/lib32/libv4 l&& LD_PRELOAD=v4l1compat.so skype;<br />
</nowiki>|bc}}<br />
<br />
=== Low sound in Skype, but works everywhere else ===<br />
<br />
If you are sure your microphone is configured correctly in ALSA (try recording with a 3rd-party-utility to determine whether it is an ALSA or Skype problem), it is most likely because Skype is controlling your volume levels. Simply disable this feature in the voice settings page in the Skype configuration window.<br />
<br />
This may also help if your microphone input is automatically lowered until 0.<br />
<br />
=== Monster/low-octave "growling" distortion over mic ===<br />
<br />
Some users with newer kernels are experiencing a monster-like growling distortion of their sound stream on the other end of Skype. This can be fixed by creating a dummy ALSA device or by removing {{ic|~/.Skype/shared.xml}}. See https://bbs.archlinux.org/viewtopic.php?pid=819500#p819500 for more information.<br />
<br />
=== Skype can only see PulseAudio, but not ALSA devices ===<br />
<br />
Turn PulseAudio autospawn off and kill PulseAudio:<br />
$ echo "autospawn = no" > ~/.pulse/client.conf<br />
$ killall pulseaudio<br />
And restart Skype.<br />
<br />
=== Crackling/noisy sound (mainly using 64-bit OS) ===<br />
<br />
Edit {{ic|/etc/pulse/default.pa}} and change the following line<br />
<br />
load-module module-udev-detect<br />
<br />
to<br />
<br />
load-module module-udev-detect tsched=0<br />
<br />
See also: [[PulseAudio#Glitches, skips or crackling]].<br />
<br />
=== Problem with Audio Playback on x86_64 ===<br />
<br />
See [[Pulseaudio#Skype (x86_64 only)]], even if you are not using PulseAudio.<br />
<br />
=== Skype sounds stops media player or other sound sources === <br />
<br />
You can try commenting out the following modules in {{ic|/etc/pulse/default.pa}}<br />
#module-cork-music-on-phone<br />
#module-role-cork<br />
<br />
If that does not help, you can try changing flat-volumes to no in {{ic|/etc/pulse/daemon.conf}}.<br />
flat-volumes = no</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Skype&diff=278444Skype2013-10-12T03:04:36Z<p>Bluerider: /* No incoming video stream */</p>
<hr />
<div>[[bg:Skype]]<br />
[[cs:Skype]]<br />
[[lt:Skype]]<br />
[[ru:Skype]]<br />
[[uk:Skype]]<br />
[[Category:Audio/Video]]<br />
[[Category:Telephony and Voice]]<br />
== Installation ==<br />
<br />
[[pacman|Install]] {{Pkg|skype}} from the [[official repositories]]. If you have a 64-bit system, enable the [[multilib]] repository first as Skype is 32-bit only.<br />
<br />
Running Skype is just as easy. Type {{Ic|skype}} into a terminal or double-click the Skype icon on your desktop or in your DE's application menu.<br />
<br />
== Skype sound ==<br />
<br />
Skype supports [[ALSA]] and [[PulseAudio]]. [[OSS]] is no longer supported.<br />
<br />
=== ALSA ===<br />
<br />
Sound should work out of the box, if not you can select a sound device to use in Skype options. If you have problems with Skype blocking your sound device, you only need to add the following to your {{ic|~/.asoundrc}}<br />
pcm.dmixout {<br />
# Just pass this on to the system dmix<br />
type plug<br />
slave {<br />
pcm "dmix"<br />
}<br />
}<br />
then you can start Skype as normal, go to the audio options and select dmixout as your speaker- and ringingdevice.<br />
<br />
=== PulseAudio ===<br />
<br />
Sound should work out of the box, if not you can select another input using pavucontrol (you may have to install it first).<br />
<br />
If you are on x86_64 and use the multilib {{Pkg|skype}} package, you also need {{Pkg|lib32-libpulse}}.<br />
<br />
=== OSS (Pre-2.0, no longer available) ===<br />
<br />
Option B is preferred over other options.<br />
With option B you can use Skype AND let other programs play sound too.<br />
With option C you can do that too, but option B is way easier to set up.<br />
<br />
You can install the legacy {{Pkg|skype-oss}} from Comunity repo.<br />
<br />
If you need 64x-86x support then download an OSS compatible version from [http://www.mediafire.com/?2ydhmj4yo3i here] and the PKGBUILD form [https://aur.archlinux.org/packages.php?ID=18312 here.] Also install {{Pkg|lib32-libxinerama}}. Finally, run<br />
$ makepkg -s<br />
to create the pacman installable package.<br />
<br />
==== A. With OSS or Kernel OSS emulation for ALSA ====<br />
<br />
Start Skype and make sure no other program is using your soundcard.<br />
If you want to use Skype AND let another program play sound too, look at option B instead.<br />
<br />
==== B. Making ALSA + dMix work for Skype ====<br />
<br />
First of all, we need to install the {{Pkg|alsa-oss}} package with [[pacman]].<br />
<br />
Add the following to {{ic|~/.asoundrc}}. If the file does not exist yet, just create it! (Many thanks to Lorenzo Colitti for figuring this out!)<br />
<br />
# .asoundrc to use skype at the same time as other audio apps like xmms<br />
#<br />
# Successfully tested on an IBM x40 with i810_audio using Linux 2.6.15 and<br />
# Debian unstable with skype 1.2.0.18-API. No sound daemons (asound, esd, etc.)<br />
# running. However, YMMV.<br />
#<br />
# For background, see:<br />
#<br />
# https://bugtrack.alsa-project.org/alsa-bug/view.php?id=1228<br />
# https://bugtrack.alsa-project.org/alsa-bug/view.php?id=1224<br />
#<br />
# (C) 2006-06-03 Lorenzo Colitti - http://www.colitti.com/lorenzo/<br />
# Licensed under the GPLv2 or later<br />
<br />
pcm.skype {<br />
type asym<br />
playback.pcm "skypeout"<br />
capture.pcm "skypein"<br />
}<br />
<br />
pcm.skypein {<br />
# Convert from 8-bit unsigned mono (default format set by aoss when<br />
# /dev/dsp is opened) to 16-bit signed stereo (expected by dsnoop)<br />
#<br />
# We cannot just use a "plug" plugin because although the open will<br />
# succeed, the buffer sizes will be wrong and we will hear no sound at<br />
# all.<br />
type route<br />
slave {<br />
pcm "skypedsnoop"<br />
format S16_LE<br />
}<br />
ttable {<br />
0 {0 0.5}<br />
1 {0 0.5}<br />
}<br />
}<br />
<br />
pcm.skypeout {<br />
# Just pass this on to the system dmix<br />
type plug<br />
slave {<br />
pcm "dmix"<br />
}<br />
}<br />
<br />
pcm.skypedsnoop {<br />
type dsnoop<br />
ipc_key 1133<br />
slave {<br />
# "Magic" buffer values to get skype audio to work<br />
# If these are not set, opening /dev/dsp succeeds but no sound<br />
# will be heard. According to the ALSA developers this is due<br />
# to skype abusing the OSS API.<br />
pcm "hw:0,0"<br />
period_size 256<br />
periods 16<br />
buffer_size 16384<br />
}<br />
bindings {<br />
0 0<br />
}<br />
}<br />
<br />
If you get the error message :<br />
<br />
The dmix plugin supports only playback stream<br />
<br />
then add the following to {{ic|.asoundrc}}:<br />
<br />
pcm.asymed {<br />
type asym<br />
playback.pcm "dmix"<br />
capture.pcm "dsnoop"<br />
}<br />
<br />
pcm.!default {<br />
type plug<br />
slave.pcm "asymed"<br />
}<br />
<br />
<br />
Now run Skype in this way each time you want to use it:<br />
ALSA_OSS_PCM_DEVICE="skype" aoss skype<br />
<br />
Optionally you can make a script to start Skype:<br />
<br />
As root, create the file: {{ic|/usr/bin/askype}}<br />
<br />
# Little script to run Skype correctly using the modified .asoundrc<br />
# See: https://wiki.archlinux.org/index.php/Skype for more information!<br />
#<br />
# Questions/Remarks: profox@debianbox.be<br />
<br />
ALSA_OSS_PCM_DEVICE="skype" aoss skype<br />
<br />
Now make sure every user is able to execute the file:<br />
# chmod a+x /usr/bin/askype<br />
<br />
You can also fix the menu entry so you can start Skype from the your window manager's menu:<br />
<br />
Edit the file: {{ic|/usr/share/applications/skype.desktop}}<br />
<br />
[Desktop Entry]<br />
Name=Skype<br />
Comment=P2P software for high-quality voice communication<br />
Exec=askype<br />
Icon=skype.png<br />
Terminal=0<br />
Type=Application<br />
Encoding=UTF-8<br />
Categories=Network;Application;<br />
<br />
Sometimes it takes a while for Skype to start up but once it is loaded it should work ok!<br />
<br />
==== C. Using OSS emulation with oss2jack ====<br />
<br />
{{AUR|oss2jack}} is another way to have OSS emulation without using ALSA directly. Instead, oss2jack creates a OSS device that forwards everything to JACK (JACK Audio Connection Kit), which in turn mixes, then outputs to the standard ALSA device.<br />
<br />
== Securing Skype ==<br />
<br />
There are a couple of reasons you might want to restrict Skype's access to your computer:<br />
* The skype binary is disguised against decompiling, so nobody is (still) able to reproduce what it really does.<br />
* It produces encrypted traffic even when you are not actively using Skype.<br />
* ...<br />
See [http://www1.cs.columbia.edu/~salman/skype/index.html] for more information.<br />
<br />
=== AppArmor ===<br />
<br />
Follow the instructions [[AppArmor|here]] to set up AppArmor.<br />
<br />
The userland tools for AppArmor come with a collection of example profiles. Skype is amongst them. Copy this to the directory where AppArmor profiles are stored.<br />
# cp -ip /etc/apparmor/profiles/extras/usr.bin.skype /etc/apparmor.d/<br />
<br />
For whatever reason, the profile is not complete. You may wish to modify it further. Here is an example for Skype 4:<br />
<br />
{{bc|#include <tunables/global><br />
/usr/bin/skype {<br />
#include <abstractions/audio><br />
#include <abstractions/consoles><br />
#include <abstractions/dbus-session><br />
#include <abstractions/gnome><br />
#include <abstractions/kde><br />
#include <abstractions/nameservice><br />
#include <abstractions/video><br />
<br />
# Executables<br />
/usr/bin/skype ixmr,<br />
/usr/lib{,32}/skype/skype ixmr,<br />
/usr/bin/xdg-open PUxmr,<br />
<br />
# Configuration files<br />
owner @{HOME}/.Skype/ rw,<br />
owner @{HOME}/.Skype/** krw,<br />
owner @{HOME}/.config/Skype/ rw,<br />
owner @{HOME}/.config/Skype/** krw,<br />
<br />
# Downloads/uploads directory<br />
owner @{HOME}/Public/ rw,<br />
owner @{HOME}/Public/** krw,<br />
<br />
# Libraries<br />
/usr/lib{,32}/libv4l/v4l2convert.so mr,<br />
/usr/share/skype/lib/libQtWebKit.so.4 mr,<br />
<br />
# Shared data<br />
/usr/share/skype/ r,<br />
/usr/share/skype/** r,<br />
<br />
# Devices<br />
/dev/ r,<br />
/dev/video[0-9]* mrw,<br />
<br />
# System information<br />
/etc/machine-id r,<br />
@{PROC}/sys/kernel/{ostype,osrelease} r,<br />
@{PROC}/sys/vm/overcommit_memory r,<br />
@{PROC}/[0-9]*/net/arp r,<br />
owner @{PROC}/[0-9]*/cmdline r,<br />
owner @{PROC}/[0-9]*/status r,<br />
owner @{PROC}/[0-9]*/task/ r,<br />
owner @{PROC}/[0-9]*/task/[0-9]*/stat r,<br />
/sys/devices/system/cpu/ r,<br />
/sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_{cur_freq,max_freq} r,<br />
/sys/devices/pci*/*/usb[0-9]*/*/*/*/modalias r,<br />
/sys/devices/pci*/*/usb[0-9]*/*/*/*/video4linux/video[0-9]*/dev r,<br />
/sys/devices/pci*/*/usb[0-9]*/*/*/{idVendor,idProduct,speed} r,<br />
<br />
# This probably should go to appropriate abstractions<br />
owner @{HOME}/.config/fontconfig/fonts.conf r,<br />
owner @{HOME}/.config/gtk-3.0/bookmarks r,<br />
owner @{HOME}/.config/pulse/cookie krw,<br />
owner @{HOME}/.icons/** r,<br />
owner @{HOME}/.kde/share/config/kioslaverc r,<br />
<br />
# Denials<br />
deny owner @{HOME}/.mozilla/ r,<br />
deny owner @{HOME}/.mozilla/** r,<br />
deny /sys/devices/virtual/dmi/** r,<br />
&#125;}}<br />
<br />
{{Note|This example assumes that Skype is configured to save received files into {{ic|~/Public}}. Feel free to change it to any folder you like.}}<br />
<br />
To use the profile, first be sure {{ic|securityfs}} is mounted,<br />
# mount -t securityfs securityfs /sys/kernel/security<br />
<br />
Load the profile by the command,<br />
# apparmor_parser -r /etc/apparmor.d/usr.bin.skype<br />
<br />
Now you can run Skype restricted but as your own user. Denials are logged in {{ic|messages.log}}.<br />
<br />
=== TOMOYO ===<br />
<br />
Follow the instructions [[TOMOYO_Linux#TOMOYO_Linux_2.x|here]] to install TOMOYO. Please note that this section describes using TOMOYO 2.5.<br />
<br />
During Skype audit it was discovered that Skype reads DMI information and Mozilla profile. To give Skype minimal access to your system using TOMOYO, please follow these steps.<br />
<br />
* Open {{ic|/etc/tomoyo/exception_policy.conf}} file and add these lines:<br />
<br />
{{bc|path_group SKYPE_DIRS /home/\*/.Skype/<br />
path_group SKYPE_DIRS /home/\*/.Skype/\{\*\}/<br />
path_group SKYPE_DIRS /home/\*/.config/Skype/\{\*\}/<br />
path_group SKYPE_DIRS /usr/share/skype/\{\*\}/<br />
path_group SKYPE_DIRS /home/pf/work/tmp/\{\*\}/<br />
path_group SKYPE_FILES /home/\*/.Skype/\{\*\}/\*<br />
path_group SKYPE_FILES /home/\*/.config/Skype/\{\*\}/\*<br />
path_group SKYPE_FILES /usr/share/skype/\{\*\}/\*<br />
path_group SKYPE_FILES /home/pf/work/tmp/\{\*\}/\*<br />
path_group SKYPE_FILES /home/\*/.Skype/\*<br />
path_group SKYPE_FILES /home/\*/.config/Skype/\*<br />
path_group SKYPE_FILES /usr/share/skype/\*<br />
path_group SKYPE_FILES /home/pf/work/tmp/\*<br />
path_group ICONS_DIRS /usr/share/icons/\{\*\}/<br />
path_group ICONS_FILES /usr/share/icons/\{\*\}/\*<br />
path_group ICONS_FILES /usr/share/icons/\*<br />
initialize_domain /usr/bin/skype from any<br />
initialize_domain /usr/lib32/skype/skype from any}}<br />
<br />
Note that {{ic|/home/pf/work/tmp}} folder is only the folder to which Skype will be able to save received files and from which it will be able to send all files. You have to change this folder.<br />
<br />
* Then open {{ic|/etc/tomoyo/domain_policy.conf}} and add the following lines:<br />
<br />
{{bc|<kernel> /usr/bin/skype<br />
use_profile 3<br />
use_group 0<br />
<br />
misc env \*<br />
file read /bin/bash<br />
file read /usr/bin/bash<br />
file read/write /dev/tty<br />
file read /usr/lib/locale/locale-archive<br />
file read /usr/lib/gconv/gconv-modules<br />
file read /usr/bin/skype<br />
file read /usr/lib32/skype/skype<br />
file execute /usr/lib32/skype/skype exec.realpath&#61;"/usr/lib32/skype/skype" exec.argv[0]&#61;"/usr/lib32/skype/skype"<br />
<br />
<kernel> /usr/lib32/skype/skype<br />
use_profile 3<br />
use_group 0<br />
<br />
file append /dev/snd/pcm\*<br />
file chmod /home/\*/.Skype/ 0700<br />
file create /home/\*/.cache/fontconfig/\* 0600-0666<br />
file create /tmp/qtsingleapp-\*-lockfile 0600-0666<br />
file create @SKYPE_FILES 0600-0666<br />
file execute /usr/bin/firefox<br />
file execute /usr/bin/gnome-open<br />
file execute /usr/bin/notify-send<br />
file execute /usr/bin/opera<br />
file execute /usr/bin/xdg-open<br />
file ioctl /dev/snd/\* 0-0xFFFFFFFFFFFFFFFF<br />
file ioctl /dev/video0 0-0xFFFFFFFFFFFFFFFF<br />
file ioctl anon_inode:inotify 0x541B<br />
file ioctl socket:[family&#61;1:type&#61;2:protocol&#61;0] 0x8910<br />
file ioctl socket:[family&#61;1:type&#61;2:protocol&#61;0] 0x8933<br />
file ioctl socket:[family&#61;2:type&#61;1:protocol&#61;6] 0x541B<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x541B<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x8912<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x8927<br />
file ioctl socket:[family&#61;2:type&#61;2:protocol&#61;17] 0x8B01<br />
file link /home/\*/.cache/fontconfig/\* /home/\*/.cache/fontconfig/\*<br />
file mkdir /home/\*/.cache/fontconfig/\* 0600<br />
file mkdir @SKYPE_DIRS 0700-0777<br />
file mksock /tmp/qtsingleapp-\* 0755<br />
file read /dev/urandom<br />
file read /etc/fonts/conf.avail/\*.conf<br />
file read /etc/fonts/conf.d/\*.conf<br />
file read /etc/fonts/fonts.conf<br />
file read /etc/group<br />
file read /etc/host.conf<br />
file read /etc/hosts<br />
file read /etc/machine-id<br />
file read /etc/nsswitch.conf<br />
file read /etc/passwd<br />
file read /etc/resolv.conf<br />
file read /home/\*/.ICEauthority<br />
file read /home/\*/.XCompose<br />
file read /home/\*/.Xauthority<br />
file read /home/\*/.Xdefaults<br />
file read /home/\*/.fontconfig/\*<br />
file read /home/\*/.config/fontconfig/\*<br />
file read /usr/lib/locale/locale-archive<br />
file read /usr/lib32/gconv/UTF-16.so<br />
file read /usr/lib32/gconv/gconv-modules<br />
file read /usr/lib32/libv4l/v4l2convert.so<br />
file read /usr/lib32/qt/plugins/bearer/libq\*bearer.so<br />
file read /usr/lib32/qt/plugins/iconengines/libqsvgicon.so<br />
file read /usr/lib32/qt/plugins/imageformats/libq\*.so<br />
file read /usr/lib32/qt/plugins/inputmethods/libqimsw-multi.so<br />
file read /usr/lib32/skype/skype<br />
file read /usr/share/X11/locale/\*/Compose<br />
file read /usr/share/X11/locale/\*/XLC_LOCALE<br />
file read /usr/share/X11/locale/compose.dir<br />
file read /usr/share/X11/locale/locale.alias<br />
file read /usr/share/X11/locale/locale.dir<br />
file read /usr/share/alsa/alsa.conf<br />
file read /usr/share/alsa/cards/\*.conf<br />
file read /usr/share/alsa/pcm/\*.conf<br />
file read /usr/share/fonts/\*/\*/\*<br />
file read @ICONS_FILES<br />
file read proc:/cpuinfo<br />
file read proc:/stat<br />
file read proc:/sys/kernel/osrelease<br />
file read proc:/sys/kernel/ostype<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/\*/modalias<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/\*/video4linux/video0/dev<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/idProduct<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/idVendor<br />
file read sysfs:/devices/\*/\*/\*/\*/\*/speed<br />
file read sysfs:/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq<br />
file read sysfs:/devices/system/cpu/cpu0/cpufreq/scaling_max_freq<br />
file read sysfs:/devices/system/cpu/online<br />
file read/write /dev/snd/\*<br />
file read/write /dev/video0<br />
file read/write/truncate /home/\*/.config/Trolltech.conf<br />
file read/write/unlink /home/\*/.cache/fontconfig/\*<br />
file read/write/unlink /tmp/qtsingleapp-\*<br />
file read/write/unlink/truncate @SKYPE_FILES<br />
file rename /home/\*/.cache/fontconfig/\* /home/\*/.cache/fontconfig/\*<br />
file rename @SKYPE_DIRS @SKYPE_DIRS<br />
file rename @SKYPE_FILES @SKYPE_FILES<br />
file rmdir @SKYPE_DIRS<br />
misc env \*<br />
network inet dgram bind 0.0.0.0 0-65535<br />
network inet dgram bind 127.0.0.1 0<br />
network inet dgram bind/send 0.0.0.0-255.255.255.255 0-65535<br />
network inet stream bind/listen 0.0.0.0 0-65535<br />
network inet stream connect 0.0.0.0-255.255.255.255 0-65535<br />
network unix stream bind/listen /tmp/qtsingleapp-\*<br />
network unix stream connect /tmp/.ICE-unix/\*<br />
network unix stream connect /tmp/qtsingleapp-\*<br />
network unix stream connect /var/run/dbus/system_bus_socket<br />
network unix stream connect /var/run/nscd/socket<br />
network unix stream connect \000/tmp/.ICE-unix/\*<br />
network unix stream connect \000/tmp/.X11-unix/X0<br />
network unix stream connect \000/tmp/dbus-\*<br />
<br />
<kernel> /usr/lib32/skype/skype /usr/bin/xdg-open<br />
use_profile 0<br />
use_group 0<br />
<br />
<br />
<kernel> /usr/lib32/skype/skype /usr/bin/gnome-open<br />
use_profile 0<br />
use_group 0<br />
<br />
<kernel> /usr/lib32/skype/skype /usr/bin/notify-send<br />
use_profile 0<br />
use_group 0}}<br />
<br />
* After finishing editing reload TOMOYO config files by executing these commands:<br />
<br />
{{bc|# tomoyo-loadpolicy -df </etc/tomoyo/domain_policy.conf<br />
# tomoyo-loadpolicy -ef </etc/tomoyo/exception_policy.conf}}<br />
<br />
Voilà — your Skype is sandboxed now.<br />
<br />
Please note that this config is generated on 64-bit Arch system, and some of your ioctls and library paths may differ from mentioned above. So in order to fine-tune TOMOYO config for your Skype load {{ic|tomoyo-auditd}} daemon:<br />
<br />
# systemctl start tomoyo-auditd<br />
<br />
Then go to {{ic|/var/log/tomoyo}} folder and start watching {{ic|reject_003.log}}:<br />
<br />
tail -f reject_003.log<br />
<br />
The output of this command will show you rejected actions for Skype, so you'll be able to add them to {{ic|domain_policy.conf}} file if needed.<br />
<br />
Detailed guide about TOMOYO configuring can be found [http://tomoyo.sourceforge.jp/2.5/index.html.en here].<br />
<br />
=== Use Skype with special user ===<br />
<br />
Instead of using AppArmor or TOMOYO which require the installation of extra packages, one may prefer to add a special user. This user is only used for running Skype within one's normal environment. This approach restricts Skype to reading only the data of this particular user instead of one's main user. (The new user should not be used for any other thing. Skype only.)<br />
<br />
An AUR package, [https://aur.archlinux.org/packages/skype-restricted/ skype-restricted] exists that will run skype as a separate user ("_skype") cleanly. It's heavily based on the information in this section.<br />
<br />
Optionally, we first add a default group for the skype user. I will call the new user and its default group "skype". The security advantage in keeping the "skype" user in its separate group is that it can be restricted from accessing some places other users are allowed in.<br />
# groupadd skype<br />
Then we have to add the new user:<br />
# useradd<br />
Enter the details for the new user (assumed login name: "skype"). If you created the default "skype" group and want to keep "skype" outside the "users" group, enter "skype" when the wizard asks for the initial group. As additional groups we need "audio,video,pulse-access,pulse-rt".<br />
<br />
Now add the following line to {{ic|/home/skype/.bashrc}}:<br />
export DISPLAY=":0.0"<br />
<br />
At last we define the alias (e.g. in {{ic|~/.bashrc}}):<br />
alias skype='xhost +local: && su skype -c skype'<br />
Now we can start Skype as the newly created user simply by running {{Ic|skype}} from the command line and entering the password of the user skype.<br />
<br />
If you are tired of typing in the skype user's password every time, make sure you installed the [[sudo]] package, run {{Ic|visudo}} then add this line at the bottom:<br />
%wheel ALL=(skype) NOPASSWD: /usr/bin/skype<br />
<br />
And use this alias to launch skype:<br />
alias skype='xhost +local: && sudo -u skype /usr/bin/skype'<br />
<br />
{{Note|If you forget the {{ic|xhost}} command, Skype may fail with a "No protocol specified" error on stdout.}}<br />
<br />
I noticed that the newly created user is able to read some of the files in my home directory because the permissions were a+r, so I changed them manually to a-r u+r and changed umask from 022 to 066.<br />
<br />
In order to restrict user "skype" accessing your external drive mounted in {{ic|/media/data}} for instance, make sure first that "skype" does not belong to group "users" (if you used the default group "skype", everything should be fine), then change the accesses on the mount point:<br />
# chown :users /media/data<br />
# chmod o-rwx /media/data<br />
This way, it is ensured that only the owner (normally "root") and "users" can access the specified directory tree while the others, including "skype", will be forbidden.<br />
<br />
==== Open URLs in your user's browser ====<br />
<br />
When one clicks URL in chat window, skype execute [[xdg-open]] to handle it. By default {{ic|xdg-open}} uses default web browser for skype user environment. In order to open links in your user's browser perform next setup.<br />
<br />
{{Note|<br />
* [[Sudo]] should be installed and properly configured.<br />
* Current example uses [[firefox]] as preferred browser.<br />
* Do not forget to adjust ''your_user'' to proper value.<br />
}}<br />
<br />
Log in as skype user:<br />
$ sudo su - skype<br />
<br />
Create local preferences dir:<br />
$ mkdir -p ~/.local/share/applications<br />
<br />
Create {{ic|/home/skype/.local/share/applications/firefox-sudo.desktop}} file:<br />
[Desktop Entry]<br />
Name=Firefox<br />
Exec=/home/skype/firefox-wrapper %u<br />
Terminal=false<br />
Type=Application<br />
Categories=Network;WebBrowser;<br />
<br />
Set {{ic|firefox-sudo.desktop}} to manage HTTP and HTTPS URLs:<br />
$ xdg-mime default firefox-sudo.desktop x-scheme-handler/http<br />
$ xdg-mime default firefox-sudo.desktop x-scheme-handler/https<br />
<br />
(Optionally) add FTP handler:<br />
$ xdg-mime default firefox-sudo.desktop x-scheme-handler/ftp<br />
<br />
Create {{ic|/home/skype/firefox-wrapper}} script (adjust ''your_user''):<br />
#!/bin/bash<br />
DISPLAY=:0.0 HOME=/home/''your_user'' sudo -u ''your_user'' /usr/lib/firefox/firefox -new-tab $1<br />
<br />
Make it executable:<br />
$ chmod +x ~/firefox-wrapper<br />
<br />
Now as root user open {{ic|/etc/sudoers}}:<br />
# visudo<br />
<br />
And add permission for skype user to exec user's browser (adjust ''your_user''):<br />
skype ALL=(''your_user'') NOPASSWD: /usr/lib/firefox/firefox -new-tab http*, /usr/lib/firefox/firefox -new-tab ftp*<br />
<br />
==== Access received files ====<br />
<br />
By default {{ic|skype}} stores received files with 600 permissions (only owner can access them). One may use [https://www.archlinux.org/packages/?sort=&q=incron incron] to perform automatic permission fix upon downloading.<br />
<br />
{{Note|This example assumes that you configure skype to save received files into {{ic|/home/skype/downloads}}}}<br />
<br />
Make skype home dir and download dir accessible:<br />
# chmod 755 /home/skype /home/skype/downloads<br />
<br />
Install incron with the {{Pkg|incron}} package from the [[official repositories]], and enable and start {{ic|incrond}} [[systemd#Using units|using systemd]].<br />
Open incrontab for root user:<br />
# incrontab -e<br />
<br />
Add incron job:<br />
/home/skype/downloads IN_CREATE chmod 644 $@/$#<br />
<br />
Save changes and exit incrontab editor.<br />
<br />
To test incron in action just enter skype donwload dir and create test file:<br />
# cd /home/skype/downloads<br />
# install -m 600 /dev/null test.txt<br />
# ls -l test.txt<br />
<br />
File permissions should be 644 or -rw-r--r--<br />
<br />
(Optionally) link skype download dir into your home dir:<br />
$ ln -s /home/skype/downloads ~/skype_files<br />
<br />
== Skype plugin for Pidgin ==<br />
<br />
See [[Pidgin#Skype plugin]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Skype crashes immediately ===<br />
<br />
Try creating the directory {{ic|~/.Skype/Logs}}.<br />
<br />
=== Skype crashes shortly after login ===<br />
<br />
If Skype crashes shortly after logging in, changing the rights for {{ic|libpulse.so.0.12.4}} (minor version might differ) and {{ic|libpulse-simple.so.0.0.3}} might fix the issue.[https://bugs.launchpad.net/ubuntu/+source/ia32-libs/+bug/646862/comments/14]<br />
<br />
# cd /usr/lib<br />
# chmod ugo-r libpulse.so.0.12.*<br />
# chmod ugo-r libpulse-simple.so.0.0.3<br />
<br />
64bit users might have to cd to {{ic|/usr/lib32}} instead.<br />
<br />
=== I can receive multiple audio streams, but I can only send one ===<br />
<br />
Skype can send and receive audio and I still hear other sounds playing from other applications, but I cannot record my microphone with other applications. That is because Skype or aoss blocks the audio input for itself.<br />
<br />
=== No video with GSPCA webcams ===<br />
<br />
For i686, install {{Pkg|v4l-utils}}, userspace tools and conversion library for Video 4 Linux, and run Skype with<br />
<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
to start Skype with v4l1 compatibility.<br />
<br />
For x86_64, install {{Pkg|lib32-v4l-utils}} from [multilib] repository and run Skype with<br />
<br />
LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype<br />
<br />
To make it running from DE menus and independent of Skype updates, you can add alias (e.g. in {{ic|~/.bashrc}}):<br />
<br />
alias skype='LD_PRELOAD=/usr/''libxx''/libv4l/v4l1compat.so skype'<br />
<br />
where ''libxx'' should be edited as appropriate.<br />
<br />
=== No video with Compiz ===<br />
<br />
Try launching Skype setting an environment variable like this:<br />
<br />
$ XLIB_SKIP_ARGB_VISUALS=1 skype<br />
<br />
=== Skype does not use my GTK+ theme, even though other Qt apps do ===<br />
<br />
Recent versions of Skype allow you to change the theme via the Options menu. However, selecting the GTK+ option may not work properly. This is probably because you do not have a 32-bit theme engine installed. Try to find the engine your theme uses in the multilib repository or the [[AUR]]. If you have no idea which engine your theme is using, the easiest fix is to install {{AUR|lib32-gtk-engines}}. This does however contain quite a lot of packages, so the best would be to find and install only the needed package.<br />
<br />
{{Note|You may not have to install ''lib32-gtk-engines''. First try if the following steps work for you if you only install ''lib32-gtk2'' and a GTK+2 theme respectively. See also the [https://bbs.archlinux.org/viewtopic.php?pid&#61;1200975#p1200975 forums].}}<br />
<br />
Once installed, it will still not work unless you have a 32-bit version of GConf installed. You could build and install {{AUR|lib32-gconf}} if desired, but there is an easier workaround. First, create or edit {{ic|~/.gtkrc-2.0}} so that it contains the following line:<br />
<br />
$ gtk-theme-name = "''My theme''"<br />
<br />
Replace ''My theme by'' the name of your theme, but leave the quotes. Second, run Skype like this:<br />
<br />
$ export GTK2_RC_FILES="/etc/gtk-2.0/gtkrc:$HOME/.gtkrc-2.0"<br />
$ skype<br />
<br />
The GTK+ theme should now appear correctly. You can make this permanent either by running Skype from a script containing the above 2 lines, or by exporting GTK2_RC_FILES in {{ic|~/.xprofile}} or {{ic|~/.xinitrc}}, depending on how you start X.<br />
<br />
If you cannot change the theme in the Options menu, run Skype using the following command:<br />
<br />
$ /usr/bin/skype --disable-cleanlooks -style GTK<br />
<br />
If you wish menus within desktop environments to load Skype with a GTK+ theme by default then modify the 'Exec' line of {{ic|/usr/share/applications/skype.desktop}} so that it reads:<br />
<br />
$ Exec=/usr/bin/skype --disable-cleanlooks -style GTK<br />
<br />
Similarly if you have set Skype to autostart then modify {{ic|~/.config/autostart/skype.desktop}} in the same way.<br />
<br />
=== The microphone does not work ===<br />
<br />
Run amixer:<br />
<br />
$ amixer<br />
<br />
and check if you have an output for '''Capture''' similar to the one below.<br />
<br />
Simple mixer control 'Capture',0<br />
Capabilities: cvolume cswitch penum<br />
Capture channels: Front Left - Front Right<br />
Limits: Capture 0 - 15<br />
Front Left: Capture 8 [53%] [12.00dB] [on]<br />
Front Right: Capture 8 [53%] [12.00dB] [on]<br />
<br />
If your output is similar, your microphone is working just fine, and the issue is either hardware related (broken microphone) or your volume needs to be checked. If you do not have an output similar to the one above or, more specifically, if both '''Front Left''' and '''Front Right''' are 0% or show an '''[off]''' tag at the end, then your microphone settings need to be rectified.<br />
<br />
In either case, try to run:<br />
<br />
$ alsamixer<br />
<br />
and press {{ic|F5}} to show all channels. Using the arrow keys navigate all the way to the end and increase '''Capture'''. If you do not see a left and right channel for '''Capture''', press the space bar. Doing this turns the left and right channels on. Check that '''Input Source''' is set to the correct value (e.g. ''[Front Mic]''): navigate through the values with up and down arrow keys. If your microphone is an array built into your monitor, or you have a similar setup, make sure to increase the volume for the '''Digital''' column too. If you have multiple microphones, you may have to play around with the '''Mic Jack''' channel to get your desired setting.<br />
<br />
You may want to save your mixer settings with:<br />
<br />
# alsactl -f /var/lib/alsa/asound.state store<br />
<br />
=== No incoming video stream ===<br />
<br />
If skype shows a black square for the video preview, but something else (like {{ic|xawtv -c /dev/video0}}) shows video correctly, you might need to start Skype with:<br />
<br />
export XLIB_SKIP_ARGB_VISUALS=1 && skype<br />
<br />
Another possible workaround is to preload ''v4l1compat.so'':<br />
<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
<br />
For my machine this doesn't seem to work; instead I do<br />
cd /usr/lib/lib32/libv4 l&& LD_PRELOAD=v4l1compat.so skype;<br />
<br />
=== Low sound in Skype, but works everywhere else ===<br />
<br />
If you are sure your microphone is configured correctly in ALSA (try recording with a 3rd-party-utility to determine whether it is an ALSA or Skype problem), it is most likely because Skype is controlling your volume levels. Simply disable this feature in the voice settings page in the Skype configuration window.<br />
<br />
This may also help if your microphone input is automatically lowered until 0.<br />
<br />
=== Monster/low-octave "growling" distortion over mic ===<br />
<br />
Some users with newer kernels are experiencing a monster-like growling distortion of their sound stream on the other end of Skype. This can be fixed by creating a dummy ALSA device or by removing {{ic|~/.Skype/shared.xml}}. See https://bbs.archlinux.org/viewtopic.php?pid=819500#p819500 for more information.<br />
<br />
=== Skype can only see PulseAudio, but not ALSA devices ===<br />
<br />
Turn PulseAudio autospawn off and kill PulseAudio:<br />
$ echo "autospawn = no" > ~/.pulse/client.conf<br />
$ killall pulseaudio<br />
And restart Skype.<br />
<br />
=== Crackling/noisy sound (mainly using 64-bit OS) ===<br />
<br />
Edit {{ic|/etc/pulse/default.pa}} and change the following line<br />
<br />
load-module module-udev-detect<br />
<br />
to<br />
<br />
load-module module-udev-detect tsched=0<br />
<br />
See also: [[PulseAudio#Glitches, skips or crackling]].<br />
<br />
=== Problem with Audio Playback on x86_64 ===<br />
<br />
See [[Pulseaudio#Skype (x86_64 only)]], even if you are not using PulseAudio.<br />
<br />
=== Skype sounds stops media player or other sound sources === <br />
<br />
You can try commenting out the following modules in {{ic|/etc/pulse/default.pa}}<br />
#module-cork-music-on-phone<br />
#module-role-cork<br />
<br />
If that does not help, you can try changing flat-volumes to no in {{ic|/etc/pulse/daemon.conf}}.<br />
flat-volumes = no</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Xfce&diff=278440Xfce2013-10-12T02:02:29Z<p>Bluerider: /* xfce4-power-manager */</p>
<hr />
<div>[[Category:Desktop environments]]<br />
[[cs:Xfce]]<br />
[[de:Xfce]]<br />
[[es:Xfce]]<br />
[[fr:Xfce]]<br />
[[it:Xfce]]<br />
[[ja:Xfce]]<br />
[[pl:Xfce]]<br />
[[ru:Xfce]]<br />
[[tr:Xfce_Masaüstü_Ortamı]]<br />
[[uk:Xfce]]<br />
[[zh-CN:Xfce]]<br />
{{Article summary start}}<br />
{{Article summary text|Xfce is a lightweight desktop environment for Unix-like operating systems. It aims to be fast and lightweight, while still being visually appealing and user friendly. This article covers its installation, configuration, and troubleshooting.}}<br />
{{Article summary text|Xfce uses the [[GTK+]] toolkit.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Graphical user interface overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Thunar}}<br />
{{Article summary wiki|Improve GTK Application Looks}}<br />
{{Article summary wiki|Autostart applications#Graphical}}<br />
{{Article summary end}}<br />
<br />
From [http://www.xfce.org/about/ Xfce - About]:<br />
<br />
:''Xfce embodies the traditional UNIX philosophy of modularity and re-usability. It consists of a number of components that provide the full functionality one can expect of a modern desktop environment. They are packaged separately and you can pick among the available packages to create the optimal personal working environment.''<br />
<br />
Xfce is a Desktop Environment, like [[GNOME]] or [[KDE]]. It contains a suite of apps like a root window app, window manager, file manager, panel, etc. Xfce is written using the GTK2 toolkit, and contains its own development environment (libraries, daemons, etc), similar to other big DEs. Features:<br />
*Lighter on resources than the other major DEs (KDE, GNOME).<br />
*Most settings are exposed via a GUI, Xfce does not try to hide stuff from the user.<br />
*Xfwm has an optional built-in compositor which allows for true transparency and all the benefits of GPU acceleration (minimizes tearing, etc.).<br />
*It works great with multiple monitors.<br />
<br />
==Installation==<br />
<br />
Before starting, make sure you have the [[Xorg|X server]] installed and configured correctly.<br />
<br />
{{Note|Xfce is somewhat modular. That means there is no need for you to run every part, you can pick and choose some of them.}}<br />
<br />
The base Xfce system can be [[pacman|installed]] with the group {{Grp|xfce4}}, available in the [[Official Repositories]]. Pacman will ask you to select the packages to install, but you probably want to get them all by simply pressing {{ic|Enter}}. Additional packages, like panel plugins, notifications, and system tools are available in the {{Grp|xfce4-goodies}} group.<br />
<br />
{{Tip|<br />
* Installing [[Gamin]] (the successor of [[FAM]]) is highly recommended.<br />
* Common tasks such as mounting removable drives and extracting archives can be accomplished with Thunar. If you do not install {{Grp|xfce4-goodies}} but still want these niceties, read the [[Thunar]] page.}}<br />
<br />
== Starting Xfce ==<br />
=== Automatically ===<br />
There are two methods to start Xfce (and in fact, any desktop or window manager) at boot time:<br />
<br />
* Run Xfce through a [[Display Manager]]<br />
* Run Xfce automatically using the {{pkg|xorg-xinit}} method at [[Start X at Login]] combining with [[Automatic login to virtual console ]]<br />
<br />
=== Manually ===<br />
<br />
There are two methods to start Xfce manually:<br />
<br />
* Run {{ic|startxfce4}} directly from the console.<br />
* Configure {{ic|~/.xinitrc}} to {{ic|exec startxfce4}} and then run {{ic|xinit}} or {{ic|startx}} from the console. See [[xinitrc]] for details.<br />
<br />
{{Note|The proper command for launching Xfce is {{ic|startxfce4}}, do not start {{ic|xfce4-session}} directly.}}<br />
<br />
=== Automounting ===<br />
See [[General Troubleshooting#Session permissions]].<br />
<br />
If you have no problems shutting down and rebooting but cannot automount external media and disks, you may need to install {{pkg|gvfs}}. See the [[#Removable Devices|Removable Devices]] section.<br />
<br />
==Tips and tricks==<br />
===Xfconf settings===<br />
Xfconf is XFCE's system for storing configuration options, and most XFCE configuration is done by editing settings in Xfconf (one way or another). There are several ways to modify these settings:<br />
* The most obvious and easiest way is to go to "Settings" in the main menu and select the category you want to customize. However, not all customization options are available this way. <br />
* A less user-friendly but more general way is to go to {{bc|Main menu -> Settings -> Settings Editor}} where you can see and modify all the customization options. Any settings modified here will take effect immediately. The Settings Editor can also be launched from the command line by invoking {{ic|xfce4-settings-editor}}.<br />
* Customization can be done completely from the command line using the program {{ic|xfconf-query}}. See [http://docs.xfce.org/xfce/xfconf/xfconf-query the XFCE online documentation] for more information and examples and the rest of this wiki page for more examples. Settings changed here will take effect immediately.<br />
* The settings are stored in XML files in {{ic|~/.config/xfce4/xfconf/xfce-perchannel-xml/}} which can be edited by hand. However, changes made here will not take effect immediately.<br />
* For more information: [http://docs.xfce.org/xfce/xfconf/start Xfconf documentation]<br />
===Panel===<br />
====Xfce panel background====<br />
Edit {{ic|~/.gtkrc-2.0}}.<br />
Note that you must place the image in the same directory as the configuration, which is {{ic|~/}}. You can not specify the path to the image, or it will not work.<br />
style "panel-background" {<br />
bg_pixmap[NORMAL] = "foo.bar"<br />
bg_pixmap[PRELIGHT] = "foo.bar"<br />
bg_pixmap[ACTIVE] = "foo.bar"<br />
bg_pixmap[SELECTED] = "foo.bar"<br />
bg_pixmap[INSENSITIVE] = "foo.bar"<br />
}<br />
widget_class "*Panel*" style "panel-background"<br />
<br />
==== Menu applet replacement ====<br />
[http://gottcode.org/xfce4-whiskermenu-plugin/ Whisker Menu] is a full-featured replacement for the default Xfce menu applet. Add it to your panel and optionally remove the built-in default menu.<br />
<br />
It is available in the [[Arch User Repository|AUR]] as the {{AUR|xfce4-whiskermenu-plugin}} package.<br />
<br />
==== Removing entries from the System menu====<br />
===== Method 1 =====<br />
With the built-in menu editor, you cannot remove menu entries from the System menu. Here’s how to hide them:<br />
# Open Terminal (Xfce menu > System > Terminal) and go to the {{ic|/usr/share/applications}} folder: {{bc|$ cd /usr/share/applications}}<br />
# This folder should be full of {{ic|.desktop}} files. To see a list type: {{bc|$ ls}}<br />
# Add {{ic|1=NoDisplay=true}} to the {{ic|.desktop}} file. For example, if you want to hide Firefox, type in the terminal: {{bc|1=# echo "NoDisplay=true" >> firefox.desktop}} This command appends the text {{ic|1=NoDisplay=true}} to the end of the {{ic|.desktop}} file.<br />
<br />
===== Method 2 =====<br />
Another method is to copy the entire contents of the global applications directory over to your local applications directory, and then proceed to modify and/or disable unwanted .desktop entries. This will survive application updates that overwrite changes under {{ic|/usr/share/applications/}}.<br />
# In a terminal, copy everything from {{ic|/usr/share/applications}} to {{ic|~/.local/share/applications/}}: {{bc|$ cp /usr/share/applications/* ~/.local/share/applications/}}<br />
# For any entry you wish to hide from the menu, add the {{ic|1=NoDisplay=true}} option: {{bc|1=$ echo "NoDisplay=true" >> ~/.local/share/applications/foo.desktop}}<br />
<br />
You can also edit the application's category by editing the {{ic|.desktop}} file with a text editor and modifying the {{ic|1=Categories=}} line.<br />
<br />
===== Method 3 =====<br />
The third method is the '''cleanest''' and recommended in the [http://wiki.xfce.org/howto/customize-menu Xfce wiki].<br />
<br />
Create the file {{ic|~/.config/menus/xfce-applications.menu}} and copy the following in it:<br />
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"<br />
"http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd"><br />
<br />
<Menu><br />
<Name>Xfce</Name><br />
<MergeFile type="parent">/etc/xdg/menus/xfce-applications.menu</MergeFile><br />
<br />
<Exclude><br />
<Filename>xfce4-run.desktop</Filename><br />
<br />
<Filename>exo-terminal-emulator.desktop</Filename><br />
<Filename>exo-file-manager.desktop</Filename><br />
<Filename>exo-mail-reader.desktop</Filename><br />
<Filename>exo-web-browser.desktop</Filename><br />
<br />
<Filename>xfce4-about.desktop</Filename><br />
<Filename>xfhelp4.desktop</Filename><br />
</Exclude><br />
<br />
<Layout><br />
<Merge type="all"/><br />
<Separator/><br />
<br />
<Menuname>Settings</Menuname><br />
<Separator/><br />
<br />
<Filename>xfce4-session-logout.desktop</Filename><br />
</Layout><br />
<br />
</Menu><br />
<br />
The {{ic|<MergeFile>}} tag includes the default Xfce menu in our file. This is important.<br />
<br />
The {{ic|<Exclude>}} tag excludes applications which we do not want to appear in the menu. Here we excluded some Xfce default shortcuts, but you can exclude {{ic|firefox.desktop}} or any other application.<br />
<br />
The {{ic|<Layout>}} tag defines the layout of the menu. The applications can be organized in folders or however we wish. For more details see the aforementioned Xfce wiki page.<br />
<br />
===== Method 4 =====<br />
Alternatively a tool called [http://www.redsquirrel87.com/XAME.html xame] can be used. XAME is a GUI tool written in Gambas designed specifically for editing menu entires in Xfce, it will NOT work in other DEs. XAME is available in the {{AUR|xame}} package from the [[AUR]]. An alternative to XAME that works quite well with Xfce is {{AUR|menulibre}}.<br />
<br />
==== Missing applications ====<br />
When some applications are installed (for example via [[WINE]]), they may not be listed in {{ic|/usr/share/applications}}. Shortcuts ''might'' be found in the category “Other” in this directory:<br />
{{ic|~/.local/share/applications/wine/}}.<br />
<br />
====Panel autohide delay====<br />
Add this to {{ic|~/.gtkrc-2.0}}.<br />
style "xfce-panel-window-style"<br />
{<br />
# Time in miliseconds before the panel will unhide on an enter event<br />
XfcePanelWindow::popup-delay = 225<br />
<br />
# Time in miliseconds before the panel will hide on a leave event<br />
XfcePanelWindow::popdown-delay = 350<br />
}<br />
class "XfcePanelWindow" style "xfce-panel-window-style"<br />
<br />
====Panel at desktop level====<br />
<br />
If you want a panel at desktop level (i.e., other windows will stack over it) you need a little hack, ensure you have installed the {{pkg|wmctrl}} package from the [[Official Repositories]].<br />
<br />
Create a script in {{ic|~/.config/xfce4/xfce4-fix-panel}} with this content and make it executable (you can use {{ic|chmod 755 xfce4-fix-panel}}).<br />
<br />
#!/bin/bash<br />
set -e<br />
<br />
function getPanelIdImpl() {<br />
# get panel id<br />
PANEL="`wmctrl -l | sed -n -e '/ xfce4-panel$/ s_ .*$__ p' | sed -n -e $1' p'`"<br />
}<br />
<br />
function getPanelId() {<br />
# eventually await the panel to appear<br />
getPanelIdImpl $1<br />
while [ x = x$PANEL ] ;do<br />
sleep 0.5s<br />
getPanelIdImpl $1<br />
done<br />
}<br />
<br />
function putPanelDown() {<br />
PANEL=""<br />
getPanelId $1<br />
wmctrl -i -r $PANEL -b add,below<br />
}<br />
<br />
# call the program with a list of panel numbers as arguments<br />
# for example, xfce4-fix-panel 1 2 3<br />
# for the first three panels<br />
for i in $* ;do<br />
putPanelDown $i<br />
done<br />
<br />
<br />
Once wrote the script, and tested it, you need to auto-execute it at each login. You can use the {{ic|Session and StartUp -> Application Autostart}} gui.<br />
<br />
This passage will put your panels at desktop level, but if your panel is sticking to a border the maximized windows will not stack over it. You can enable this behavior with the following command, fortunately you need to do this only once. (change the $ID with the panel number of interest)<br />
<br />
xfconf-query -c xfce4-panel -p /panels/panel-$ID/disable-struts -n -t bool -s true<br />
<br />
=== Desktop ===<br />
<br />
==== Transparent Background for Icon Titles ====<br />
To change the default white background of desktop icon titles to something more suitable, edit the {{ic|.gtkrc-2.0}} file in your home directory (or create the file if needed) and add the following:<br />
style "xfdesktop-icon-view" {<br />
XfdesktopIconView::label-alpha = 10<br />
base[NORMAL] = "#000000"<br />
base[SELECTED] = "#71B9FF"<br />
base[ACTIVE] = "#71FFAD"<br />
fg[NORMAL] = "#ffffff"<br />
fg[SELECTED] = "#71B9FF"<br />
fg[ACTIVE] = "#71FFAD" }<br />
widget_class "*XfdesktopIconView*" style "xfdesktop-icon-view"<br />
<br />
==== Hide Selected Partitions ====<br />
If you wish to prevent certain partitions or drives appearing on the desktop, you can create a udev rule, for example {{ic|/etc/udev/rules.d/10-local.rules}}:<br />
<br />
KERNEL=="sda1", ENV{UDISKS_PRESENTATION_HIDE}="1"<br />
KERNEL=="sda2", ENV{UDISKS_PRESENTATION_HIDE}="1"<br />
<br />
Would show all partitions with the exception of sda1 and sda2 on your desktop. Notice, if you are using udisk2 the above will not work, due to the UDISKS_PRESENTATION_HIDE no longer being supported, instead you must use UDISKS_IGNORE as follows<br />
<br />
KERNEL=="sda1", ENV{UDISKS_IGNORE}="1"<br />
KERNEL=="sda2", ENV{UDISKS_IGNORE}="1"<br />
<br />
==== Remove Thunar Options from Right-click ====<br />
xfconf-query -c xfce4-desktop -v --create -p /desktop-icons/style -t int -s 0<br />
<br />
==== Kill Window Shortcut ====<br />
Xfce does not support the ''kill window'' shortcut directly, but you can add one with a simple script. Ensure you have the '''xorg-xkill''' package installed.<br />
<br />
Create a script in {{ic|~/.config/xfce4/killwindow.sh}} with this content and make it executable (you can use {{ic|chmod 755 killwindow.sh}}).<br />
<br />
xkill -id "`xprop -root -notype | sed -n '/^_NET_ACTIVE_WINDOW/ s/^.*# *\|\,.*$//g p'`"<br />
<br />
Now associate a shortcut using {{ic|Settings -> Keyboard}} to that script.<br />
<br />
==== Making Keyboard Shortcuts for Frequently Used Applications ====<br />
<br />
<br />
''Keyboard shortcuts'' can be used to access Frequently Used Applications like-<br />
<br />
1.Web Browser<br />
<br />
2.Terminal<br />
<br />
3.File Manager<br />
<br />
4.GParted<br />
<br />
<br />
'''Here's how to do it.'''<br />
<br />
In your panel, Applications -> Settings -> Keyboard.<br />
<br />
Open the Application Shortcuts Tab.<br />
<br />
''To Add a new Shortcut'', click on Add<br />
<br />
<br />
Now need to type in the name of the command.<br />
<br />
For terminal, the command is ''xfce4-terminal''<br />
<br />
<br />
Then need to press the keyboard key(s) to create the shortcut.<br />
<br />
Choose the '''Super(Windows) + t''' key combination for Terminal<br />
<br />
Thats it.<br />
<br />
<br />
''More such shortcuts can be created in a similar manner.''<br />
<br />
These shortcuts can be ''edited'' also by double clicking on them to change the command.<br />
<br />
<br />
'''Some Examples-'''<br />
<br />
<br />
''Web Browser''<br />
<br />
command- <br />
exo-open --launch WebBrowser<br />
<br />
shortcut-<br />
<Super>W<br />
<br />
<br />
''File Manager (Thunar)''<br />
<br />
command- <br />
thunar<br />
<br />
shortcut-<br />
<Super>F<br />
<br />
<br />
''GParted''<br />
<br />
command- <br />
gksudo gparted<br />
<br />
shortcut-<br />
<Super>G<br />
<br />
<br />
See also-<br />
[http://docs.xfce.org/xfce/xfce4-settings/keyboard The XFCE Keyboard Settings]<br />
<br />
=== XFWM4 ===<br />
==== Enabling the Compositor ====<br />
Xfce comes with a builtin compositor adding the option for fancy window effects, shadows and transparency and so on. It can be enabled in the Window Manager Tweaks and works on the fly. No additional settings are needed in your {{ic|/etc/xorg.conf}}. To enable and adjust settings, go to:<br />
<br />
Menu --> Settings --> Window Manager Tweaks<br />
<br />
{{Tip|The built-in compositor for Xfwm (the Xfce window manager) often causes video tearing in applications. If you wish for a lightweight compositor with some minimal effects, consider using [[Compton]].}}<br />
<br />
==== Disable window roll-up ====<br />
xfconf-query -c xfwm4 -p /general/mousewheel_rollup -s false<br />
<br />
==== Toggle Automatic Tiling of Windows at Edge of Screen ====<br />
XFWM4 has the ability to "tile" a window automatically when it is moved to the edge of the screen by resizing it to fill the top half of the screen. (The official XFCE website says this feature is disabled by default in XFCE 4.10, but it seems to be enabled by default on Arch Linux.) This behavior can be enabled or disabled in {{ic|Window Manager Tweaks --> Accessibility --> Automatically tile windows when moving toward the screen edge}}, or:<br />
<br />
xfconf-query -c xfwm4 -p /general/tile_on_move -s false # To disable<br />
xfconf-query -c xfwm4 -p /general/tile_on_move -s true # To enable<br />
<br />
=== Settings Manager Commands ===<br />
There is no official documentation for the commands executed. One must look at {{ic|.desktop}} files {{ic|/usr/share/applications/}} folder. For the people who like to know exactly what is happening, here is a handy list to save the effort:<br />
<br />
xfce4-accessibility-settings<br />
xfce4-power-manager-settings<br />
xfce4-settings-editor<br />
xfdesktop-settings<br />
xfce4-display-settings<br />
xfce4-keyboard-settings<br />
xfce4-mouse-settings<br />
xfce4-session-settings<br />
xfce4-settings-manager<br />
xfce4-appearance-settings<br />
xfwm4-settings<br />
xfwm4-tweaks-settings<br />
xfwm4-workspace-settings<br />
orage -p<br />
<br />
To review all the available setting manager commands run the following in a terminal:<br />
<br />
$ grep '^Exec=' /usr/share/applications/xfce*settings* | sed -e 's_^.*=_ _'<br />
<br />
===Session===<br />
====Custom Startup Applications====<br />
<br />
=====Via the Settings Menu=====<br />
<br />
To launch custom applications when Xfce starts up, click the Applications Menu -> Settings -> Settings Manager and then choose the "Session and Startup" option and click the tab "Application Autostart".<br />
You'll see a list of programs that get launched on startup. To add an entry, click the "Add" button and fill out the form, specifying the path to an executable you want to run.<br />
<br />
=====Startup Script=====<br />
<br />
Alternatively you can use this method, to run a command line script to launch your applications. This includes getting necessary environment variables into the GUI runtime.<br />
<br />
* Copy the file {{ic|/etc/xdg/xfce4/xinitrc}} to {{ic|~/.config/xfce4/}}<br />
* Edit this file. For example, you can add something like this somehwere in the middle:<br />
source $HOME/.bashrc<br />
# start rxvt-unicode server<br />
urxvtd -q -o -f<br />
<br />
====Lock the screen====<br />
To lock an Xfce4 session (through {{ic|xflock4}}) one of {{Pkg|xscreensaver}}, {{Pkg|gnome-screensaver}} or {{Pkg|xlockmore}} packages needs to be installed.<br />
<br />
====Switch between users====<br />
Xfce4 allows this behavior under the 'action buttons' menu item. Currently, [[gdm]], [[Lightdm#User switching under xfce4|lightdm]] and, after slight manual intervention, [[LXDM#Simultaneous users and switching users|lxdm]] provide this functionality.<br />
<br />
==== Manually Modifying XML settings ====<br />
It may be useful, especially when upgrading, to manually edit .xml files in the {{ic|~/.config/xfce4/xfconf/}} folder. For application keyboard shortcuts for example, the file is {{ic|~/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-keyboard-shortcuts.xml}}. It is faster to copy and paste the XML keys that you want rather than using the GUI.<br />
<br />
===Removable Devices===<br />
If you want an icon appearing on your desktop and in Thunar when you plug in external devices, make sure {{Pkg|gvfs}} is installed. You could also need to install {{Pkg|gvfs-afc}} (read [https://bbs.archlinux.org/viewtopic.php?pid=889018 this discussion]). It is also a good idea to install {{Pkg|thunar-volman}} (already included in the {{Grp|xfce4}} base group). Additionally, [[udisks]] and a udisks wrapper are recommended if you want to automount optical and external drives easily.<br />
<br />
===Look and Feel===<br />
====Add themes to XFCE====<br />
1. Go to [http://www.xfce-look.org www.xfce-look.org] and click "Themes" in the left navbar. Look around for a theme you want and click "Download".<br />
<br />
2. Go to the directory where you downloaded the tarball/file and extract it using Squeeze/Xarchiver/CLI.<br />
<br />
3. Move the extracted folder to {{ic|/usr/share/themes}} (for all users) or {{ic|~/.themes}} (for just you). Inside {{ic|/usr/share/themes/abc}}, there is a folder that you create called xfwm4 that will contain whatever files that is included with that theme.<br />
<br />
4. GTK theme is available here:<br />
Menu --> Settings --> Appearance<br />
You select your xfwm theme in:<br />
Menu --> Settings --> Window Manager<br />
<br />
====Taming ugly applications====<br />
You may have noticed that by default, some applications do not follow your chosen theme, or when they do, they do so very poorly, with rather ugly, and sometimes difficult-to-use results. For most applications, this is because they use gtk3 or qt instead of gtk2. For instance, some checkboxes in gtk3's default theme do not look like they are checked, when they are. Archlinux does not (and will not) install any pretty gtk3 or qt themes automatically, in accordance with its minimalist philosophy. You will need to beautify these applications yourself. Luckily, this is very easy to do. Consult [[GTK+#GTK+ 3.x]] for gtk3 and consult [[Uniform Look for Qt and GTK Applications]] for qt.<br />
<br />
==== Cursors ====<br />
Main article: [[X11 Cursors]]<br />
<br />
If you have alternative X cursor themes installed, Xfce can find them with:<br />
Menu --> Settings --> Mouse --> Theme<br />
<br />
==== Icons ====<br />
# First find and download your desired icon pack. Recommended places to download icons from are [http://www.customize.org Customize.org], [http://opendesktop.org Opendesktop.org] and [http://xfce-look.org/ Xfce-look.org]; the [[AUR]] provides several PKGBUILDs for icon packs.<br />
# Go to the directory where you downloaded the icon pack and extract it. Example {{ic|tar -xzf /home/user/downloads/icon-pack.tar.gz}}.<br />
# Move the extracted folder containing the icons to {{ic|~/.icons}} (if only you want to use the icons) or to {{ic|/usr/share/icons}} (if you want all users on the system to make use of the icons), and in the lattter case consider creating a [[PKGBUILD]] for that.<br />
# Optional: run {{ic|gtk-update-icon-cache -f -t ~/.icons/<theme_name>}} to update icon cache<br />
# Switch your icons by going to:<br />
Menu --> Settings --> Appearance --> Icons<br />
<br />
When you have icon theme problems, it is also recommended to install the {{Pkg|hicolor-icon-theme}} package if it was not already installed.<br />
<br />
==== Fonts ====<br />
If you find the standard fonts rather thick and or slightly out of focus open Settings>Appearence click on the Fonts tab and under Hinting: change to Full<br />
<br />
You could also try using a custom DPI setting.<br />
<br />
=== Sound ===<br />
<br />
==== Configuring xfce4-mixer ====<br />
<br />
{{Pkg|xfce4-mixer}} is the GUI mixer app / panel plugin made by the Xfce team. It is part of the xfce4 group, so you probably already have it installed. Xfce 4.6 uses {{Pkg|gstreamer}} as the backend to control volume, so first you have to make gstreamer cooperate with xfce4-mixer. One or more of the gstreamer plugin packages listed as optional dependencies to xfce4-mixer must be installed. Without one of these required plugins packages, the following error arises when clicking on the mixer panel item.<br />
<br />
GStreamer was unable to detect any sound devices. Some sound system specific GStreamer packages may be missing. It may also be a permissions problem.<br />
<br />
(It is probably not a permissions problem. It is no longer required to add audio users to the "audio" group.) Which plugins are needed depends on the hardware. Most people should be fine with {{Pkg|gstreamer0.10-base-plugins}} which can be [[pacman|installed]] from [[Official Repositories]]. <br />
<br />
If the xfce4-mixer panel item was already running before one of the plugins packages was installed, logout and login to see if it worked, or just remove the mixer plugin from the panel and add it again. If that does not work, you might need more or different gstreamer plugins. Try to [[pacman|install]] package {{pkg|gstreamer0.10-good-plugins}} or {{pkg|gstreamer0.10-bad-plugins}}.<br />
<br />
If you had to change the soundcard in the audio mixer, then you should log out and back in to hear sound.<br />
<br />
For further details, for example how to set the default sound card, see [[Advanced Linux Sound Architecture]]. Alternatively you can use [[PulseAudio]] together with {{Pkg|pavucontrol}}.<br />
<br />
==== Xfce4-mixer and OSS4 ====<br />
<br />
If you tried the above section to get {{Pkg|xfce4-mixer}} to work and it does not work at all, then you may have to compile {{pkg|gstreamer0.10-good-plugins}} yourself. Download the PKGBUILD and other files needed from ABS or [https://projects.archlinux.org/svntogit/packages.git/tree/gstreamer0.10-good/repos here], edit the PKGBUILD, add --enable-oss. <br />
<br />
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var \<br />
'''--enable-oss \'''<br />
--disable-static --enable-experimental \<br />
--disable-schemas-install \<br />
--disable-hal \<br />
--with-package-name="GStreamer Good Plugins (Archlinux)" \<br />
--with-package-origin="https://www.archlinux.org/"<br />
<br />
and then run makepkg -i. <br />
<br />
makepkg -i<br />
<br />
Still not working? Try this package in AUR {{AUR|gstreamer0.10-good-plugins-ossv4}}, modify the pkgver to the newest in the PKGBUILD, and it should work.<br />
<br />
Other LINKS: [http://www.4front-tech.com/forum/ OSS forum]<br />
<br />
==== Keyboard Volume Buttons ====<br />
<br />
Go to <br />
Settings --> Keyboard<br />
Click the "Application Shortcuts" tab and add click the "Add" button. Add the following by entering the command, then pressing the corresponding button at the next window:<br />
<br />
===== ALSA =====<br />
For the raise volume button:<br />
amixer set Master 5%+<br />
For the lower volume button:<br />
amixer set Master 5%-<br />
For the mute button:<br />
amixer set Master toggle<br />
<br />
You can also run these commands to set the above commands to the standard XF86Audio keys:<br />
xfconf-query -c xfce4-keyboard-shortcuts -p /commands/custom/XF86AudioRaiseVolume -n -t string -s "amixer set Master 5%+ unmute"<br />
xfconf-query -c xfce4-keyboard-shortcuts -p /commands/custom/XF86AudioLowerVolume -n -t string -s "amixer set Master 5%- unmute"<br />
xfconf-query -c xfce4-keyboard-shortcuts -p /commands/custom/XF86AudioMute -n -t string -s "amixer set Master toggle"<br />
<br />
If {{ic|amixer set Master toggle}} does not work, try the PCM channel ({{ic|amixer set PCM toggle}}) instead.<br />
<br />
The channel must have a "mute" option for the toggle command to work. To check whether or not your Master channel supports toggling mute, run {{ic|alsamixer}} in a terminal and look for the double M's (MM) under the Master channel. If they are not present, then it does not support the mute option. If, for example, you had to change the toggle button to use the PCM channel, make sure to also set the PCM channel as the Mixer Track under Xfce Mixer properties.<br />
<br />
===== OSS =====<br />
Use one of these scripts: http://www.opensound.com/wiki/index.php/Tips_And_Tricks#Using_multimedia_keys_with_OSS<br />
<br />
If using ossvol (recommended), add:<br />
ossvol -i 1<br />
for the volume up button<br />
ossvol -d 1<br />
for the volume down button<br />
ossvol -t<br />
for the mute/unmute button<br />
<br />
===== PulseAudio =====<br />
For the raise volume button:<br />
sh -c "pactl set-sink-mute 0 false ; pactl set-sink-volume 0 +1%"<br />
For the lower volume button:<br />
sh -c "pactl set-sink-mute 0 false ; pactl -- set-sink-volume 0 -1%"<br />
For the mute button:<br />
pactl set-sink-mute 0 toggle<br />
<br />
These settings assume the device you want to control has index 0.<br />
Use {{ic|pactl list sinks short}} to list sinks.<br />
<br />
===== Xfce4-volumed =====<br />
<br />
[https://aur.archlinux.org/packages.php?ID=31693 xfce4-volumed] daemon from the [[AUR]] automatically maps volume keys of your keyboard to Xfce-mixer. Additionally you get OSD through Xfce4-notifyd when changing volume. Xfce4-volumed does not need any configuration and is started automatically with Xfce.<br />
<br />
{{accuracy|reason=There should be a short explanation of what this does and why it fixes the problem (bug?).}}<br />
<br />
If you use pulseaudio and xfce4-volumed unmute does not work, try this:<br />
<br />
$ xfconf-query -c xfce4-mixer -p /active-card -s `xfconf-query -c xfce4-mixer -p /sound-card`<br />
<br />
===== Volumeicon =====<br />
<br />
{{pkg|volumeicon}} is an alternative to xfce4-volumed in the community repo also handling keybindings and notifications through {{pkg|xfce4-notifyd}}.<br />
<br />
===== Extra keyboard keys =====<br />
If you are coming from another distro, you may be interested in enabling extra keys on your keyboard, see [[Extra Keyboard Keys]].<br />
<br />
==== Adding startup/boot sound ====<br />
<br />
Arch does not have a built-in startup sound configuration tool, but there is a workaround by adding the following command to your Application Autostart settings:<br />
<br />
aplay /boot/startupsound.wav<br />
<br />
The file location and filename can be whatever you want, but naming it descriptively and putting it in /boot keeps things tidy.<br />
<br />
=== xdg-open integration (Preferred Applications) ===<br />
<br />
Most applications rely on [[xdg-open]] for opening a preferred application for a given file or URL.<br />
<br />
In order for xdg-open and xdg-settings to detect and integrate with the XFCE desktop environment correctly, you need to [[pacman|install]] the {{Pkg|xorg-xprop}} package.<br />
<br />
If you do not do that, your preferred applications preferences (set by exo-preferred-applications) will not be obeyed.<br />
Installing the package and allowing ''xdg-open'' to detect that you are running XFCE makes it forward all calls to ''exo-open'' instead, which correctly uses all your preferred applications preferences.<br />
<br />
To make sure xdg-open integration is working correctly, ask ''xdg-settings'' for the default web browser and see what the result is:<br />
<br />
# xdg-settings get default-web-browser<br />
<br />
If it replies with:<br />
<br />
xdg-settings: unknown desktop environment<br />
<br />
it means that it has failed to detect XFCE as your desktop environment, which is likely due to a missing {{Pkg|xorg-xprop}} package.<br />
<br />
=== Screenshots ===<br />
<br />
XFCE has its own screenshot tool, {{pkg|xfce4-screenshooter}}. It is part of the {{grp|xfce4-goodies}} group.<br />
<br />
==== Print Screen key ====<br />
<br />
Go to:<br />
<br />
XFCE Menu --> Settings --> Keyboard >>> Application Shortcuts.<br />
<br />
Add the "xfce4-screenshooter -f" command to use the "PrintScreen" key in order to take fullscreen screenshots. See screenshooter's man page for other optional arguments.<br />
<br />
Alternatively, an independent screenshot program like [[Taking a Screenshot#scrot|scrot]] can be used.<br />
<br />
===Terminal color themes or pallets===<br />
Terminal color themes or pallets can be changed in GUI under Appearance tab in Preferences. These are the colors that are available to most console applications like [[Emacs]], [[Vi]] and so on. Their settings are stored individually for each system user in {{ic|~/.config/xfce4/terminal/terminalrc}} file. There are also so many other themes to choose from. Check forums post [[https://bbs.archlinux.org/viewtopic.php?pid=1194644|Terminal Colour Scheme Screenshots]] for hundreds of available choices and themes.<br />
<br />
====Changing default color theme====<br />
XFCE's {{ic|extra/terminal}} package comes with a darker color palette and colored text looks pretty horrid in default black background impeding user readability. Append the following in your terminalrc file for a lighter color theme, that is always visible in darker Terminal backgrounds.<br />
<br />
~/.config/xfce4/terminal/terminalrc<br />
<br />
ColorPalette5=#38d0fcaaf3a9<br />
ColorPalette4=#e013a0a1612f<br />
ColorPalette2=#d456a81b7b42<br />
ColorPalette6=#ffff7062ffff<br />
ColorPalette3=#7ffff7bd7fff<br />
ColorPalette13=#82108210ffff<br />
<br />
====Terminal tango color theme====<br />
To switch to tango color theme, open with your favorite editor<br />
<br />
~/.config/xfce4/terminal/terminalrc<br />
<br />
And add(replace) these lines:<br />
<br />
ColorForeground=White<br />
ColorBackground=#323232323232<br />
ColorPalette1=#2e2e34343636<br />
ColorPalette2=#cccc00000000<br />
ColorPalette3=#4e4e9a9a0606<br />
ColorPalette4=#c4c4a0a00000<br />
ColorPalette5=#34346565a4a4<br />
ColorPalette6=#757550507b7b<br />
ColorPalette7=#060698989a9a<br />
ColorPalette8=#d3d3d7d7cfcf<br />
ColorPalette9=#555557575353<br />
ColorPalette10=#efef29292929<br />
ColorPalette11=#8a8ae2e23434<br />
ColorPalette12=#fcfce9e94f4f<br />
ColorPalette13=#72729f9fcfcf<br />
ColorPalette14=#adad7f7fa8a8<br />
ColorPalette15=#3434e2e2e2e2<br />
ColorPalette16=#eeeeeeeeecec<br />
<br />
=== Colour management ===<br />
xfce4-settings-manager does not yet have any colour management / calibration settings, nor is there any specific XFCE program to characterise your monitor.<br />
<br />
==== Loading a profile ====<br />
If you wish to '''load an icc profile''' (that you have previously created or downloaded) to calibrate your display on startup, you can download {{AUR|xcalib}} from [[AUR]], then open the XFCE4 Settings Manager, click Session and Startup icon, the Autostart tab, and add a new entry where the command is {{ic|/usr/bin/xcalib /path/to/your/profile.icc}}. You still need to tell your applications, which display profile should be used to have the displayed images colour managed.<br />
<br />
Another option is dispwin. Dispwin not only calibrates the display, but also sets the _ICC_PROFILE atom in X so that some applications can use a "system" display profile instead of requiring the user to set the display profile manually (GIMP, Inkscape, darktable, UFRaw, etc.).<br />
<br />
See [[ICC Profiles#Loading ICC Profiles]] for more information.<br />
<br />
==== Creating a profile ====<br />
<br />
If you wish to '''create an icc profile''' for your display (ie. characterising/profiling, e.g. with the ColorHug, or some other colorimeter, or a spectrophotometer, or "by eye"), the simplest option may be to install {{AUR|dispcalGUI}} from [[AUR]]. <br />
<br />
Another option is to install {{pkg|gnome-settings-daemon}} and {{pkg|gnome-color-manager}} (available in extra). In order to start the calibration from the command line, first do {{ic|/usr/lib/gnome-settings-daemon/gnome-settings-daemon &}} (note: this might change your keyboard layout and who knows what else, so probably good to do it on a throwaway account), then {{ic|colormgr get-devices}} and look for the "Device ID" line of your monitor. If this is e.g. "xrandr-Lenovo Group Limited", you start calibration with the command {{ic|gcm-calibrate --device "xrandr-Lenovo Group Limited"}}.<br />
{{Note|1=The reason you need gnome-settings-daemon running is because XFCE does not yet have a session component for colord: https://bugzilla.xfce.org/show_bug.cgi?id=8559}}<br />
<br />
See [[ICC Profiles]] for more information.<br />
<br />
=== Multiple Monitors ===<br />
If you have configured X.org so that your display spans multiple monitors, usually when you login to an '''XFCE''' session, it will appear as if your monitors are simple clones of one another. You can use an '''xrandr''' tool to tweak your setup but if this is not called at an appropriate time in the startup sequence, some functionality may be lost with parts of your display being inaccessible to the mouse pointer.<br />
<br />
A better way is to configure XFCE to match your desired display arrangement. However, at present (xfce-settings 4.10), there is no tool available to assist with configuring multiple monitors directly. <br />
<br />
* The ''Settings -> Display'' tool does allow configuration of screen resolution, rotation and enabling individual monitors; '''warning''': ''using this tool to adjust display settings will reset or lose settings made manually for properties not explicitly offered as buttons in the tool (see below)''.<br />
* The ''Settings -> Settings Editor'' allows manipulation of all configuration items in particular the ''displays'' settings which are saved in the file '''displays.xml''' below<br />
~/.config/xfce4/xfconf/xfce-perchannel-xml<br />
* Alternatively, the ''displays.xml'' can be edited using your favourite editor.<br />
<br />
The main requirement for multiple monitors is their arrangement relative to one another. This can be controlled by setting the '''Position''' properties ('''X''' and '''Y''') to suit; an ''(x,y)'' position of ''0,0'' corresponds to the ''top, left'' position of the monitor array. This is the default position for all monitors and if several monitors are enabled they will appear as a cloned display area extending from this point. <br />
<br />
To extend the display area correctly across both monitors:<br />
<br />
* for side-by-side monitors, set the '''X''' property of the rightmost monitor to equal the width of the left-most monitor<br />
* for above-and-below monitors, set the '''Y''' property of the bottom monitor to equal the height of the upper monitor<br />
* for other arrangements, set the '''X''' and '''Y''' properties of each monitor to correspond to your layout<br />
<br />
Measurements are in ''pixels''. As an example, a pair of monitors with nominal dimensions of ''1920x1080'' which are rotated by 90 and placed side-by-side can be configured with a ''displays.xml'' like this:<br />
<br />
<channel name="displays" version="1.0"><br />
<property name="Default" type="empty"><br />
<property name="VGA-1" type="string" value="Idek Iiyama 23&quot;"><br />
<property name="Active" type="bool" value="true"/><br />
<property name="Resolution" type="string" value="1920x1080"/><br />
<property name="RefreshRate" type="double" value="60.000000"/><br />
<property name="Rotation" type="int" value="90"/><br />
<property name="Reflection" type="string" value="0"/><br />
<property name="Primary" type="bool" value="false"/><br />
<property name="Position" type="empty"><br />
<property name="X" type="int" value="0"/><br />
<property name="Y" type="int" value="0"/><br />
</property><br />
</property><br />
<property name="DVI-0" type="string" value="Digital display"><br />
<property name="Active" type="bool" value="true"/><br />
<property name="Resolution" type="string" value="1920x1080"/><br />
<property name="RefreshRate" type="double" value="60.000000"/><br />
<property name="Rotation" type="int" value="90"/><br />
<property name="Reflection" type="string" value="0"/><br />
<property name="Primary" type="bool" value="false"/><br />
<property name="Position" type="empty"><br />
<property name="X" type="int" value="1080"/><br />
<property name="Y" type="int" value="0"/><br />
</property><br />
</property><br />
</property><br />
</channel><br />
<br />
Usually, editing settings in this way requires a logout/login to action them.<br />
<br />
A new method for configuring multiple monitors will be available in the forthcoming xfce-settings 4.12 release.<br />
<br />
=== XDG User Directories ===<br />
freedesktop.org specifies the "well known" user directories like the desktop folder and the music folder. See [[Xdg user directories]] for detailed info.<br />
<br />
=== SSH Agents ===<br />
By default Xfce 4.10 will try to load gpg-agent or ssh-agent in that order during session initialization. To disable this, create an xfconf key using the following command:<br />
<br />
xfconf-query -c xfce4-session -p /startup/ssh-agent/enabled -n -t bool -s false<br />
<br />
To force using ssh-agent even if gpg-agent is installed, run the following instead:<br />
<br />
xfconf-query -c xfce4-session -p /startup/ssh-agent/type -n -t string -s ssh-agent<br />
<br />
To use [[GNOME Keyring]], simply tick the checkbox ''Launch GNOME services on startup'' in the ''Advanced'' tab of ''Session Manager'' in Xfce's settings. This will also disable gpg-agent and ssh-agent.<br />
<br />
Source: http://docs.xfce.org/xfce/xfce4-session/advanced<br />
<br />
== Troubleshooting ==<br />
=== xfce4-power-manager ===<br />
Power-related [[Wikipedia:Advanced Configuration and Power Interface|ACPI]] events can be configured using [[systemd]] via options from {{ic|/etc/systemd/logind.conf}} to give control to xfce4-power-manager.<br />
<br />
{{hc|/etc/systemd/logind.conf|2=<br />
HandlePowerKey=ignore<br />
HandleSuspendKey=ignore<br />
HandleHibernateKey=ignore<br />
HandleLidSwitch=ignore}}<br />
<br />
This also solves the problem when the computer registers multiple suspend events.<br />
<br />
=== xfce4 keeps blanking display===<br />
Xfce4 (as of 4.12) doesn't seem to respect monitor power settings in {{ic|xfce4-power-manager}}. It attempts to run the screensaver every 10 minutes. You can check this by reading out the output of {{ic|$ xset q}}. Run {{ic|$ xset s noblank}} to stop it. Alternatively add the following configuration file to {{ic|/etc/X11/xorg.conf.d/}} ( I would save it as {{ic|20-noblank.conf}}).<br />
{{bc|<nowiki><br />
Section "ServerFlags"<br />
Option "BlankTime" "0"<br />
EndSection<br />
</nowiki>|bc}}<br />
<br />
=== xfce4-xkb-plugin ===<br />
There is a bug in version {{Pkg|xfce4-xkb-plugin}} ''0.5.4.1-1'' which causes xfce4-xkb-plugin to ''lose keyboard, layout switching and compose key'' settings. As a workaround you may enable ''Use system defaults'' option in keyboard settings. To do so run<br />
xfce4-keyboard-settings<br />
Go to ''Layout'' tab and set the ''Use system defaults'' flag, then reconfigure xfce4-xkb-plugin.<br />
<br />
=== Locales ignored with GDM ===<br />
Add your locale to {{ic|/var/lib/AccountsService/users/$USER}} (replace {{ic|hu_HU.UTF-8}} with your own locale):<br />
[User]<br />
Language=hu_HU.UTF-8<br />
XSession=xfce<br />
You may also do it with sed. Note the backslash before .UTF-8:<br />
# sed -i 's/Language=.*/Language=hu_HU\.UTF-8/' /var/lib/AccountsService/users/$USER<br />
Restart GDM to take effect.<br />
<br />
=== Restore default settings ===<br />
If for any reason you need to revert back to the default settings, try renaming {{ic|~/.config/xfce4-session/}} and {{ic|~/.config/xfce4/}}<br />
<br />
$ mv ~/.config/xfce4-session/ ~/.config/xfce4-session-bak<br />
$ mv ~/.config/xfce4/ ~/.config/xfce4-bak<br />
<br />
Logout and login for changes to take effect. If upon logging in you get an error window with the heading "Unable to load a failsafe session," see the [[Xfce#Session_failure|Session Failure]] section on this page.<br />
<br />
=== NVIDIA and xfce4-sensors-plugin ===<br />
To detect and use sensors of nvidia gpu you need to install {{AUR|libxnvctrl}} and then recompile {{Pkg|xfce4-sensors-plugin}} package.<br />
<br />
=== Session failure ===<br />
If the window manager does not load correctly, you maybe got a session error. Typical symptoms of this can include:<br />
<br />
* the mouse is an X and/or does not appear at all<br />
* window decorations have disappeared and windows cannot be closed<br />
* "Window Manager" settings tool ({{ic|xfwm4-settings}}) will not start, reporting <br />
These settings cannot work with your current window manager (unknown)<br />
* errors being reported by {{ic|slim}} or your login manager like<br />
No window manager registered on screen 0<br />
<br />
Restarting xfce or rebooting your system may resolve the problem but more likely the problem is a corrupt session. Delete the session folder below the {{ic|.cache}} folder:<br />
$ rm -r ~/.cache/sessions/<br />
<br />
=== Preferred Applications preferences have no effect ===<br />
If you have set your preferred applications with ''exo-preferred-applications'', but they do not seem to be taken into consideration, see [[Xfce#xdg-open integration (Preferred Applications)]]<br />
<br />
=== Action Buttons/Missing Icons ===<br />
This happens if icons for some actions (Suspend, Hibernate) are missing from the icon theme, or at least do not have the expected names. First, find out the currently used icon theme in the Settings Manager (→Appearance→Icons). Match this with a subdirectory of {{ic|/usr/share/icons}}. For example, if the icon theme is GNOME, make a note of the directory name {{ic|/usr/share/icons/gnome}}.<br />
<br />
icontheme=/usr/share/icons/gnome<br />
<br />
Make sure that the {{Pkg|xfce4-power-manager}} is installed as this contains the needed icons. Now create symbolic links from the current icon theme into the {{ic|hicolor}} icon theme.<br />
<br />
ln -s /usr/share/icons/hicolor/16x16/actions/xfpm-suspend.png ${icontheme}/16x16/actions/system-suspend.png<br />
ln -s /usr/share/icons/hicolor/16x16/actions/xfpm-hibernate.png ${icontheme}/16x16/actions/system-hibernate.png<br />
ln -s /usr/share/icons/hicolor/22x22/actions/xfpm-suspend.png ${icontheme}/22x22/actions/system-suspend.png<br />
ln -s /usr/share/icons/hicolor/22x22/actions/xfpm-hibernate.png ${icontheme}/22x22/actions/system-hibernate.png<br />
ln -s /usr/share/icons/hicolor/24x24/actions/xfpm-suspend.png ${icontheme}/24x24/actions/system-suspend.png<br />
ln -s /usr/share/icons/hicolor/24x24/actions/xfpm-hibernate.png ${icontheme}/24x24/actions/system-hibernate.png<br />
ln -s /usr/share/icons/hicolor/48x48/actions/xfpm-suspend.png ${icontheme}/48x48/actions/system-suspend.png<br />
ln -s /usr/share/icons/hicolor/48x48/actions/xfpm-hibernate.png ${icontheme}/48x48/actions/system-hibernate.png<br />
<br />
Log out and in again, and you should see icons for all actions.<br />
<br />
=== Enable cedilla ç/Ç instead of ć/Ć ===<br />
When you select the keyboard layout "U.S., alternative international" in Settings --> Keyboard --> Layout to enable accents, the typical combination for the cedilla ' + c results in ć instead of ç.To change this suffice edit files gtk.immodules for gtk-2.0 and immodules.cache for gtk-3.0 in line that contains "cedilla" adding both "en" in the list "az:ca:co:fr:gv:oc:pt:sq:tr:wa" but in alphabetical order, staying that way in /etc/gtk-2.0/gtk.immodules<br />
<br />
"/usr/lib/gtk-2.0/2.10.0/immodules/im-cedilla.so" <br />
"cedilla" "Cedilla" "gtk20" "/usr/share/locale" "az:ca:co:en:fr:gv:oc:pt:sq:tr:wa"<br />
<br />
and this in /usr/lib/gtk-3.0/3.0.0/immodules.cache<br />
<br />
"/usr/lib/gtk-3.0/3.0.0/immodules/im-cedilla.so" <br />
"cedilla" "Cedilla" "gtk30" "/usr/share/locale" "az:ca:co:en:fr:gv:oc:pt:sq:tr:wa"<br />
<br />
Then, do<br />
# echo "export GTK_IM_MODULE=cedilla" >> /etc/environment<br />
<br />
Done. Simply just close and reopen the gtk programs like gedit.<br />
<br />
=== Non ASCII characters when mounting USB sticks ===<br />
A common problem when automounting USB sticks formatted with fat filesystem is the inability to properly show characters as umlauts, ñ, ß, etc. This may be solved by changing the default iocharset to UTF-8, which is easily done adding a line to {{ic|/etc/xdg/xfce4/mount.rc}}:<br />
<br />
[vfat]<br />
uid=<auto><br />
shortname=winnt<br />
'''utf8=true'''<br />
# FreeBSD specific option<br />
longnames=true<br />
flush=true<br />
<br />
Note that when using utf-8, the system will distinct between upper- and lowercases, potentially corrupting your files, so be careful.<br />
<br />
It is possible to mount vfat devices with ''flush'' option, so that when copying to USB sticks data flushes more often, thus making thunar's progress bar to stays up until finished. Adding ''async'' instead will speed up write ops, but make sure to use ''Eject'' option in Thunar to unmount the stick. Globally, mount options for storage devices present at boot can be set in [[fstab]], and for other devices in [[udev]] rules.<br />
<br />
=== Video tearing when Xfwm compositing is enabled ===<br />
This is a known problem. Consider using a standalone compositor like [[Compton]] or [[Xcompmgr]]. Alternatively, you could replace your window manager with something like [[Compiz]] or Kwin ({{aur|kwin-standalone-git}}) which provide their own compositors.<br />
<br />
==See also==<br />
* http://docs.xfce.org/ - The complete documentation.<br />
* [http://www.xfce-look.org/ Xfce-Look] - Themes, wallpapers, and more.<br />
* [http://xfce.wikia.com/wiki/Frequently_Asked_Questions Xfce Wikia] - How to edit the auto generated menu with the menu editor<br />
* [http://wiki.xfce.org Xfce Wiki]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Unified_Extensible_Firmware_Interface&diff=278134Unified Extensible Firmware Interface2013-10-09T17:01:10Z<p>Bluerider: /* EFI System Partition */ Added the ESP label</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 />
{{Article summary start}}<br />
{{Article summary text|An overview of the Unified Extensible Firmware Interface.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Boot process overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|GUID Partition Table}}<br />
{{Article summary wiki|Master Boot Record}}<br />
{{Article summary wiki|Arch Boot Process}}<br />
{{Article summary 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 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|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 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 UEFI Specification version and therefore it is not a standard UEFI firmware.}}<br />
<br />
Before understanding UEFI, it is important to understand how the pre-UEFI (BIOS) systems boot. This is explained in subsequent sections.<br />
<br />
== BIOS ==<br />
<br />
A BIOS or Basic Input-Output System is the very first program (firmware) that is executed once the system is switched on. In most cases it is stored in a flash memory in the motherboard itself and independent of the system storage.<br />
<br />
=== Boot Process under BIOS ===<br />
<br />
# System switched on - Power On Self Test, or POST process<br />
# After POST BIOS initializes the necessary system hardware for booting (disk, keyboard controllers etc.)<br />
# BIOS launches the first 440 bytes (MBR boot code region) of the first disk in the BIOS disk order<br />
# The MBR boot code then takes control from BIOS and launches its next stage code (if any) (mostly bootloader code)<br />
# The launched (2nd stage) code (actual bootloader) then reads its support and config files<br />
# Based on the data in its config files, the bootloader loads the kernel and initramfs into system memory (RAM) and launches the kernel<br />
<br />
=== Multibooting in BIOS ===<br />
<br />
Since very little can be achieved by a program that fits into the 440-byte boot code area, multi-booting using BIOS requires a multi-boot capable bootloader (multi-boot refers to booting multiple operating systems, not to booting a kernel in the Multiboot format specified by the GRUB developers). So usually a common bootloader like [[GRUB]] or [[Syslinux]] or [[LILO]] would be loaded by the BIOS, and it would load an operating system by either chain-loading or directly loading the kernel.<br />
<br />
== UEFI ==<br />
<br />
UEFI has support for reading both the partition table as well as understanding filesystems. Hence it is not limited by 440 byte code limitation (MBR boot code) as in BIOS systems. It does not use the MBR boot code at all.<br />
<br />
The commonly used UEFI firmwares support both MBR and GPT partition table. EFI in Apple-Intel Macs are known to also support Apple Partition Map besides MBR and GPT. Most UEFI firmwares have support for accessing FAT12 (floppy disks), FAT16 and FAT32 filesystems in HDDs and ISO9660 (and UDF) in CD/DVDs. EFI in Apple-Intel Macs can access HFS/HFS+ filesystems also apart from the mentioned ones.<br />
<br />
UEFI does not launch any boot code in the MBR whether it exists or not. Instead it uses a special partition in the partition table called '''EFI SYSTEM PARTITION''' in which files required to be launched by the firmware are stored. Each vendor can store its files under {{ic|<EFI SYSTEM PARTITION>/EFI/<VENDOR NAME>/}} folder and can use the firmware or its shell (UEFI shell) to launch the boot program. An EFI System Partition is usually formatted as FAT32 (mostly) or FAT16.<br />
<br />
Under UEFI, every program whether it is an OS loader or a utility (e.g. a memory testing app or recovery tool), should be a UEFI Application corresponding to the EFI firmware bitness/architecture. The vast majority of UEFI firmwares, including recent Apple Macs, use x86_64 EFI firmware. The only known devices that use IA32 (32-bit) EFI are older (pre 2008) Apple Macs, some recent Intel Cloverfield ultrabooks and some older Intel Server boards are known to operate on Intel EFI 1.10 firmware.<br />
<br />
An x86_64 EFI firmware does not include support for launching 32-bit EFI apps (unlike x86_64 Linux and Windows versions which include such support). Therefore the UEFI application must be compiled for that specific firmware processor bitness/architecture.<br />
<br />
=== 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 bootloader 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 doesn't 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 bootloader 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 />
This limitation is not enforced by Linux kernel itself, but rather depends on how the bootloader is configured. However this 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 of Windows and Linux dual boot in 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 can use only 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 />
==== Apple Macs ==== <br />
<br />
Pre-2008 Macs mostly have i386-efi firmware while >=2008 Macs have mostly x86_64-efi. All Macs capable of running Mac OS X Snow Leopard 64-bit Kernel have x86_64 EFI 1.x firmware. <br />
<br />
To find out the arch of the efi firmware in a Mac, type the following into the Mac OS X terminal:<br />
<br />
ioreg -l -p IODeviceTree | grep firmware-abi<br />
<br />
If the command returns EFI32 then it is IA32 (32-bit) EFI firmware. If it returns EFI64 then it is x86_64 EFI firmware. Most of the Macs do not have UEFI 2.x firmware as Apple's EFI implementation is not fully compliant with UEFI 2.x Specification.<br />
<br />
== Linux Kernel Config options for UEFI ==<br />
<br />
The required Linux Kernel configuration options for UEFI systems are :<br />
<br />
CONFIG_RELOCATABLE=y<br />
CONFIG_EFI=y<br />
CONFIG_EFI_STUB=y<br />
CONFIG_FB_EFI=y<br />
CONFIG_FRAMEBUFFER_CONSOLE=y<br />
<br />
UEFI Runtime Variables Support ('''efivarfs''' filesystem - {{ic|/sys/firmware/efi/efivars}}). This option is important as this is required to manipulate UEFI Runtime Variables using tools like {{ic|/usr/bin/efibootmgr}}. The below config option has been added in kernel 3.10 and above.<br />
<br />
CONFIG_EFIVAR_FS=y<br />
<br />
UEFI Runtime Variables Support (old '''efivars sysfs''' interface - {{ic|/sys/firmware/efi/vars}}). This option should be disabled.<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.<br />
<br />
=== Sample List of UEFI Variables ===<br />
<br />
Sample list of UEFI Variables in a Lenovo Thinkpad E430 3254-DAQ (UEFI 2.3.1, x86_64 firmware, Secure Boot support present):<br />
<br />
{{hc|UEFI Variables List|<nowiki><br />
$ efivar -l<br />
0b7646a4-6b44-4332-8588-c8998117f2ef-BmEssentialVariableNames<br />
0ec1a7f5-4904-40a0-8eab-4bcc4666da45-PbaStatusVar<br />
1054354b-b543-4dfe-558b-a7ad6351c9d8-DptfProtocolSetupVar<br />
1827cfc7-4e61-4273-b796-d35f4b0c88fc-LenovoHiddenSetting<br />
1bad711c-d451-4241-b1f3-8537812e0c70-MeBiosExtensionSetup<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBC<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBL<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOL<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0000<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0001<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0002<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0003<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0004<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0005<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0006<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0007<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0008<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0009<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000A<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000B<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000C<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000D<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000E<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000F<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0010<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0011<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0012<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0013<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0014<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0015<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0016<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0017<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0018<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LenovoConfig<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LenovoSystemConfig<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0000<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0001<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0002<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0003<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0004<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0005<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0006<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LWO<br />
34f73d4d-963e-4c65-b3b3-515e720175d6-SaProtocolSetupVar<br />
3e72b3ad-2b91-424a-ad73-c3270e91ed88-PwdStatusVar<br />
4650c401-93f1-4aeb-b87d-c8204c047dec-SctHotkey<br />
47355e9f-0857-45e1-8a6f-a4f5eda89a77-LocalSecurityVars<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderDeviceIdentifier<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderDevicePartUUID<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderEntriesAuto<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderEntrySelected<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderFirmwareInfo<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderFirmwareType<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderImageIdentifier<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderInfo<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderTimeExecUSec<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderTimeInitUSec<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderTimeMenuUSec<br />
4c19049f-4137-4dd3-9c10-8b97a83ffdfa-MemoryTypeInformation<br />
4c19049f-4137-4dd3-9c10-8b97a83ffdfa-MemoryTypeInformationBackup<br />
4dfbbaab-1392-4fde-abb8-c41cc5ad7d5d-Setup<br />
5e724c0c-5c03-4543-bcb6-c1e23de24136-TpmSaveState<br />
608dc793-15de-4a7f-a0c5-6c29beaf5d23-MemRestoreVariable<br />
6403753b-abde-4da2-aa11-6983ef2a7a69-TpmAcpiData<br />
65827a61-99e2-4f07-a7aa-0b1f98edad39-PlatformOpRomSetup<br />
67c3208e-4fcb-498f-9729-0760bb4109a7-LenovoFlashScratch1<br />
67c3208e-4fcb-498f-9729-0760bb4109a7-LenovoScratchData<br />
67c3208e-4fcb-498f-9729-0760bb4109a7-MailBoxQ<br />
753ab903-444c-41f8-a235-569e8341147e-TcgSetup<br />
7d4adce1-930d-40c7-9cd2-6d2148413dc7-CpuProtocolSetupVar<br />
7da81437-866b-4143-8e08-a25c6ef0fa5b-SaPpiSetupVar<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0000<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0001<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0002<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0003<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0004<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0005<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0006<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0007<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0008<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0009<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000A<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000B<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000C<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000D<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000E<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000F<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0010<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0011<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0012<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0013<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0014<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0015<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0016<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0017<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0018<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-BootCurrent<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-BootOptionSupport<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-BootOrder<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-BootOrderDefault<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ConIn<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ConInDev<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ConOut<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ConOutDev<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-DIAGSPLSHSCRN<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ErrOutDev<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-HDDPWD<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-KEK<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0000<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0001<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0002<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0003<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0004<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0005<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0006<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-LastBootCurrent<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-OsIndications<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-OsIndicationsSupported<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-PlatformLang<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-PlatformLangCodes<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ProtectedBootOptions<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-SecureBoot<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-SetupHotKey<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-SetupMode<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-SimpleBootFlag<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Timeout<br />
955b9041-133a-4bcf-90d1-97e1693c0e30-IEIT<br />
955b9041-133a-4bcf-90d1-97e1693c0e30-SecureBootOption<br />
9da5909e-ef5e-4851-8715-bf9e22b7a600-BGRTLogoIndex<br />
9dab39a4-3f8a-47ac-80c3-400729332c81-FirmwarePerformanceDataTable<br />
a2c1808f-0d4f-4cc9-a619-d1e641d39d49-LenovoSecurityConfig<br />
af9ffd67-ec10-488a-9dfc-6cbf5ee22c2e-AcpiGlobalVariable<br />
c3eeae98-23bf-412b-ab60-efcbb48e1534-SMBIOSELOG000<br />
c3eeae98-23bf-412b-ab60-efcbb48e1534-SMBIOSELOGNUMBER<br />
c3eeae98-23bf-412b-ab60-efcbb48e1534-SMBIOSMEMSIZE<br />
c4975200-64f1-4fb6-9773-f6a9f89d985e-SaPegData<br />
d719b2cb-3d3a-4596-a3bc-dad00e67656f-db<br />
d719b2cb-3d3a-4596-a3bc-dad00e67656f-dbx<br />
e5bbf7be-2417-499b-97db-39f4896391bc-BuildDate<br />
e5bbf7be-2417-499b-97db-39f4896391bc-BuildTime<br />
e6c2f70a-b604-4877-85ba-deec89e117eb-PchInit<br />
e6c2f70a-b604-4877-85ba-deec89e117eb-PchS3Peim<br />
eb704011-1402-11d3-8e77-00a0c969723b-MTC<br />
f9f0b131-f346-4f16-80dd-f941072b3a7d-iFfsData<br />
</nowiki>}}<br />
<br />
=== UEFI Variables Support in Linux Kernel ===<br />
<br />
Linux kernel exposes EFI variables data to userspace via 2 interfaces:<br />
<br />
# efivarfs ({{ic|efivarfs}} kernel module, {{ic|/sys/firmware/efi/efivars}}) that was designed to overcome the limitations of sysfs-efivars interface<br />
# Old sysfs-efivars interface ({{ic|efivars}} kernel module, {{ic|/sys/firmware/efi/vars}}) which has been disabled in from {{pkg|linux}} 3.11<br />
<br />
Efivarfs was introduced in kernel 3.8 and most of its bugs were ironed out in kernel 3.10. <br />
<br />
Running both sysfs-efivars and efivarfs can create inconsistencies in EFI variables data in the kernel and is discouraged. Going forward efivarfs is the recommended way for tools to interact with kernel registered EFI variables. All the UEFI variables related tools in [[official repositories]] support efivarfs as of 18 September 2013.<br />
<br />
==== Inconsistency between efivarfs and sysfs-efivars ====<br />
<br />
Both sysfs-efivars and efivarfs can run simultaneously, but this can cause inconsistency between sysfs-efivars data and efivarfs data, especially if data in both are simultaneously modified. See https://lkml.org/lkml/2013/4/16/473 for more info. Therefore it is advisable to use enable only one interface at a time and disable the other one.<br />
<br />
{{Note|From core/{{pkg|linux}} 3.11 onwards {{ic|efivars}} and {{ic|efi_pstore}} modules are no longer compiled (this change in only in Arch kernel, upstream has not removed sysfs-efivars code). In Arch, only efivarfs is enabled/supported.}}<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}})<br />
# Kernel processor bitness/arch and EFI processor bitness/arch should match<br />
# Kernel should be booted in EFI mode (via EFISTUB or any EFI bootloader, 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 it needs to be mounted manually<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 />
For mounting efivarfs (unless not automatically mounted by systemd during boot), follow:<br />
<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
{{Note|The above command should be run both BEFORE and AFTER '''chroot''', if any.}}<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 />
=== 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|* 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 />
* Upstream efibootmgr http://linux.dell.com/git/efibootmgr.git does not support efivarfs. However vathpela's efibootmgr supports efivarfs and is currently used in official efibootmgr pkg. sysfs-efivars is also completely disabled in official Arch kernel and it supports only efivarfs. This section is written with the assumtion that you are using only efivarfs and vathpela's efibootmgr.<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 />
= UEFI Bootloaders =<br />
<br />
See [[UEFI Bootloaders]] for the main article.<br />
<br />
= EFI System Partition =<br />
<br />
{{Note|Setting the {{ic|boot}} flag by {{ic|parted}} in a MBR partition marks that partition as active, while in a GPT partition it is marked as {{ic|EFI System Partition}}.}}<br />
<br />
{{Note|It is recommended to use always GPT for UEFI boot as some UEFI firmwares do not allow UEFI-MBR boot.}}<br />
<br />
The EFI System Partition is a 512 mb FAT32 physical partition (not LVM or software raid) that is marked as boot (not legacy boot). Initramfs and kernels (~28mb) are stored in the EFI system partition. It is recommended to label the partition "ESP".<br />
<br />
<br />
<br />
{{Note|1=Microsoft documentation noteed 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 = 256 MB.Advanced Format 512e drives are not affected by this limitation, because their emulated sector size is 512 bytes. 512 bytes x 65527 = 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 />
<br />
== GPT partitioned disks ==<br />
<br />
Two choices:<br />
<br />
* Using GNU Parted/GParted: create a FAT32 partition. Set {{ic|boot}} flag on for that partition.<br />
* Using GPT fdisk (aka gdisk): create a partition with partition type {{ic|ef00}}. Then format that partition as FAT32 using {{ic|mkfs.vfat -F32 /dev/<THAT_PARTITION>}}<br />
<br />
If you get the message <code>WARNING: Not enough clusters for a 32 bit FAT!</code>, reduce cluster size with <code>mkfs.vfat -s2 -F32 ...</code> or <code>-s1</code>, otherwise the partition may be unreadable by UEFI.<br />
<br />
== MBR partitioned disks ==<br />
<br />
Two choices:<br />
<br />
* Using GNU Parted/GParted: create FAT32 partition. Change the type code of that partition to {{ic|0xEF}} using fdisk, cfdisk or sfdisk.<br />
* Using fdisk: create a partition with partition type {{ic|0xEF}}. Then format that partition as FAT32 using {{ic|mkfs.vfat -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| Users are recommended to try {{ic|bcfg}} only if {{ic|efibootmgr}} fails to create working boot entries in their system.}}<br />
<br />
{{Note| 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 />
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 />
{{Note|1=The instructions below are specifically for [[Archiso]]/official media; [[Archboot]] preparation is identical, without the filesystem label requirement.}}<br />
<br />
=== In Linux ===<br />
<br />
* [[Beginners_Guide#Prepare_the_storage_drive|First create either a MBR or GPT (recommended) partition table and at least one partition in the USB]] (so it is fine to use an already partitioned USB). {{Note|Using a GPT partition table is recommended as some firmwares don't support booting from MBR devices in full UEFI mode (e.g. Gigabyte).}}<br />
<br />
* Mount the ISO image from the [https://www.archlinux.org/download/ Arch Linux download page].<br />
<br />
# mkdir -p /mnt/{usb,iso}<br />
# mount -o loop archlinux-2013.10.01-dual.iso /mnt/iso<br />
<br />
* Then create a FAT32 filesystem in the partition on the USB (unmount before if necessary) with LABEL as used in the Archiso configuration. Obtain the label from {{ic|/mnt/iso/loader/entries/archiso-x86_64.conf}}; this is used by the {{ic|archiso}} hook in initramfs to identify the udev path to the installation media. {{ic|mkfs.vfat}} is part of package {{Pkg|dosfstools}}. {{Note|The filesystem should be either FAT32 (recommended), FAT16, or FAT12.}}<br />
<br />
# awk 'BEGIN {FS="="} /archisolabel/ {print $3}' /mnt/iso/loader/entries/archiso-x86_64.conf | xargs mkfs.vfat -F32 /dev/sdXY -n<br />
<br />
* Mount the newly created FAT32 USB partition, and copy the contents of the installation media to the USB media.<br />
<br />
# mount /dev/sdXY /mnt/usb<br />
# cp -a /mnt/iso/* /mnt/usb<br />
# sync<br />
# umount /mnt/{usb,iso}<br />
<br />
=== In Windows ===<br />
<br />
{{Note|Do not use any '''Bootable USB Creator utility''' for creating the UEFI bootable USB. Do not use ''dd for Windows'' to dd the ISO to the USB drive.}}<br />
<br />
* Format the USB drive as FAT32. {{Note|The filesystem should be either FAT32 (recommended), FAT16, or FAT12.}}<br />
<br />
* Extracted the ISO (similar to extracting ZIP archive) to the USB drive using [http://7-zip.org/ 7-Zip].<br />
<br />
* Change the '''Volume Label''' of the USB drive to match the LABEL mentioned in {{ic|1=archisolabel=}} part in {{ic|<USB>\loader\entries\archiso-x86_64.conf}} . {{Note|The above step is required for Official ISO (archiso) but not required for [[Archboot]].}}<br />
<br />
== Remove UEFI boot support from ISO ==<br />
<br />
{{Warning|In the event that UEFI+isohybrid El Torito/MBR really causes problems, it would be better to just UEFI boot using the USB stick instructions in the previous section}}<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 />
Rebuild the ISO using {{ic|xorriso}} from {{pkg|libisoburn}}:<br />
<br />
{{bc|1=<nowiki><br />
$ xorriso -as mkisofs -iso-level 3 \<br />
-full-iso9660-filenames\<br />
-volid "ARCH_201212" \<br />
-appid "Arch Linux CD" \<br />
-publisher "Arch Linux <https://www.archlinux.org>" \<br />
-preparer "prepared like a BAWSE" \<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 "~/archiso.iso" "/mnt/iso/"</nowiki>}}<br />
<br />
Burn {{ic|~/archiso.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 won't 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 won't 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 doesn't pretend the UEFI BIOS from starting CSM<br />
<br />
= See also =<br />
<br />
* Wikipedia's page on [http://en.wikipedia.org/wiki/UEFI UEFI]<br />
* Wikipedia's page on [http://en.wikipedia.org/wiki/EFI_System_partition 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://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>Blueriderhttps://wiki.archlinux.org/index.php?title=Unified_Extensible_Firmware_Interface&diff=278133Unified Extensible Firmware Interface2013-10-09T17:00:37Z<p>Bluerider: /* EFI System Partition */ Cut out some verbosity</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 />
{{Article summary start}}<br />
{{Article summary text|An overview of the Unified Extensible Firmware Interface.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Boot process overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|GUID Partition Table}}<br />
{{Article summary wiki|Master Boot Record}}<br />
{{Article summary wiki|Arch Boot Process}}<br />
{{Article summary 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 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|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 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 UEFI Specification version and therefore it is not a standard UEFI firmware.}}<br />
<br />
Before understanding UEFI, it is important to understand how the pre-UEFI (BIOS) systems boot. This is explained in subsequent sections.<br />
<br />
== BIOS ==<br />
<br />
A BIOS or Basic Input-Output System is the very first program (firmware) that is executed once the system is switched on. In most cases it is stored in a flash memory in the motherboard itself and independent of the system storage.<br />
<br />
=== Boot Process under BIOS ===<br />
<br />
# System switched on - Power On Self Test, or POST process<br />
# After POST BIOS initializes the necessary system hardware for booting (disk, keyboard controllers etc.)<br />
# BIOS launches the first 440 bytes (MBR boot code region) of the first disk in the BIOS disk order<br />
# The MBR boot code then takes control from BIOS and launches its next stage code (if any) (mostly bootloader code)<br />
# The launched (2nd stage) code (actual bootloader) then reads its support and config files<br />
# Based on the data in its config files, the bootloader loads the kernel and initramfs into system memory (RAM) and launches the kernel<br />
<br />
=== Multibooting in BIOS ===<br />
<br />
Since very little can be achieved by a program that fits into the 440-byte boot code area, multi-booting using BIOS requires a multi-boot capable bootloader (multi-boot refers to booting multiple operating systems, not to booting a kernel in the Multiboot format specified by the GRUB developers). So usually a common bootloader like [[GRUB]] or [[Syslinux]] or [[LILO]] would be loaded by the BIOS, and it would load an operating system by either chain-loading or directly loading the kernel.<br />
<br />
== UEFI ==<br />
<br />
UEFI has support for reading both the partition table as well as understanding filesystems. Hence it is not limited by 440 byte code limitation (MBR boot code) as in BIOS systems. It does not use the MBR boot code at all.<br />
<br />
The commonly used UEFI firmwares support both MBR and GPT partition table. EFI in Apple-Intel Macs are known to also support Apple Partition Map besides MBR and GPT. Most UEFI firmwares have support for accessing FAT12 (floppy disks), FAT16 and FAT32 filesystems in HDDs and ISO9660 (and UDF) in CD/DVDs. EFI in Apple-Intel Macs can access HFS/HFS+ filesystems also apart from the mentioned ones.<br />
<br />
UEFI does not launch any boot code in the MBR whether it exists or not. Instead it uses a special partition in the partition table called '''EFI SYSTEM PARTITION''' in which files required to be launched by the firmware are stored. Each vendor can store its files under {{ic|<EFI SYSTEM PARTITION>/EFI/<VENDOR NAME>/}} folder and can use the firmware or its shell (UEFI shell) to launch the boot program. An EFI System Partition is usually formatted as FAT32 (mostly) or FAT16.<br />
<br />
Under UEFI, every program whether it is an OS loader or a utility (e.g. a memory testing app or recovery tool), should be a UEFI Application corresponding to the EFI firmware bitness/architecture. The vast majority of UEFI firmwares, including recent Apple Macs, use x86_64 EFI firmware. The only known devices that use IA32 (32-bit) EFI are older (pre 2008) Apple Macs, some recent Intel Cloverfield ultrabooks and some older Intel Server boards are known to operate on Intel EFI 1.10 firmware.<br />
<br />
An x86_64 EFI firmware does not include support for launching 32-bit EFI apps (unlike x86_64 Linux and Windows versions which include such support). Therefore the UEFI application must be compiled for that specific firmware processor bitness/architecture.<br />
<br />
=== 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 bootloader 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 doesn't 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 bootloader 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 />
This limitation is not enforced by Linux kernel itself, but rather depends on how the bootloader is configured. However this 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 of Windows and Linux dual boot in 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 can use only 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 />
==== Apple Macs ==== <br />
<br />
Pre-2008 Macs mostly have i386-efi firmware while >=2008 Macs have mostly x86_64-efi. All Macs capable of running Mac OS X Snow Leopard 64-bit Kernel have x86_64 EFI 1.x firmware. <br />
<br />
To find out the arch of the efi firmware in a Mac, type the following into the Mac OS X terminal:<br />
<br />
ioreg -l -p IODeviceTree | grep firmware-abi<br />
<br />
If the command returns EFI32 then it is IA32 (32-bit) EFI firmware. If it returns EFI64 then it is x86_64 EFI firmware. Most of the Macs do not have UEFI 2.x firmware as Apple's EFI implementation is not fully compliant with UEFI 2.x Specification.<br />
<br />
== Linux Kernel Config options for UEFI ==<br />
<br />
The required Linux Kernel configuration options for UEFI systems are :<br />
<br />
CONFIG_RELOCATABLE=y<br />
CONFIG_EFI=y<br />
CONFIG_EFI_STUB=y<br />
CONFIG_FB_EFI=y<br />
CONFIG_FRAMEBUFFER_CONSOLE=y<br />
<br />
UEFI Runtime Variables Support ('''efivarfs''' filesystem - {{ic|/sys/firmware/efi/efivars}}). This option is important as this is required to manipulate UEFI Runtime Variables using tools like {{ic|/usr/bin/efibootmgr}}. The below config option has been added in kernel 3.10 and above.<br />
<br />
CONFIG_EFIVAR_FS=y<br />
<br />
UEFI Runtime Variables Support (old '''efivars sysfs''' interface - {{ic|/sys/firmware/efi/vars}}). This option should be disabled.<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.<br />
<br />
=== Sample List of UEFI Variables ===<br />
<br />
Sample list of UEFI Variables in a Lenovo Thinkpad E430 3254-DAQ (UEFI 2.3.1, x86_64 firmware, Secure Boot support present):<br />
<br />
{{hc|UEFI Variables List|<nowiki><br />
$ efivar -l<br />
0b7646a4-6b44-4332-8588-c8998117f2ef-BmEssentialVariableNames<br />
0ec1a7f5-4904-40a0-8eab-4bcc4666da45-PbaStatusVar<br />
1054354b-b543-4dfe-558b-a7ad6351c9d8-DptfProtocolSetupVar<br />
1827cfc7-4e61-4273-b796-d35f4b0c88fc-LenovoHiddenSetting<br />
1bad711c-d451-4241-b1f3-8537812e0c70-MeBiosExtensionSetup<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBC<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBL<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOL<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0000<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0001<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0002<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0003<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0004<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0005<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0006<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0007<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0008<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0009<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000A<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000B<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000C<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000D<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000E<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP000F<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0010<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0011<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0012<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0013<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0014<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0015<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0016<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0017<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LBOP0018<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LenovoConfig<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LenovoSystemConfig<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0000<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0001<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0002<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0003<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0004<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0005<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LKOP0006<br />
2a4dc6b7-41f5-45dd-b46f-2dd334c1cf65-LWO<br />
34f73d4d-963e-4c65-b3b3-515e720175d6-SaProtocolSetupVar<br />
3e72b3ad-2b91-424a-ad73-c3270e91ed88-PwdStatusVar<br />
4650c401-93f1-4aeb-b87d-c8204c047dec-SctHotkey<br />
47355e9f-0857-45e1-8a6f-a4f5eda89a77-LocalSecurityVars<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderDeviceIdentifier<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderDevicePartUUID<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderEntriesAuto<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderEntrySelected<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderFirmwareInfo<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderFirmwareType<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderImageIdentifier<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderInfo<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderTimeExecUSec<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderTimeInitUSec<br />
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f-LoaderTimeMenuUSec<br />
4c19049f-4137-4dd3-9c10-8b97a83ffdfa-MemoryTypeInformation<br />
4c19049f-4137-4dd3-9c10-8b97a83ffdfa-MemoryTypeInformationBackup<br />
4dfbbaab-1392-4fde-abb8-c41cc5ad7d5d-Setup<br />
5e724c0c-5c03-4543-bcb6-c1e23de24136-TpmSaveState<br />
608dc793-15de-4a7f-a0c5-6c29beaf5d23-MemRestoreVariable<br />
6403753b-abde-4da2-aa11-6983ef2a7a69-TpmAcpiData<br />
65827a61-99e2-4f07-a7aa-0b1f98edad39-PlatformOpRomSetup<br />
67c3208e-4fcb-498f-9729-0760bb4109a7-LenovoFlashScratch1<br />
67c3208e-4fcb-498f-9729-0760bb4109a7-LenovoScratchData<br />
67c3208e-4fcb-498f-9729-0760bb4109a7-MailBoxQ<br />
753ab903-444c-41f8-a235-569e8341147e-TcgSetup<br />
7d4adce1-930d-40c7-9cd2-6d2148413dc7-CpuProtocolSetupVar<br />
7da81437-866b-4143-8e08-a25c6ef0fa5b-SaPpiSetupVar<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0000<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0001<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0002<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0003<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0004<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0005<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0006<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0007<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0008<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0009<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000A<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000B<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000C<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000D<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000E<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot000F<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0010<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0011<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0012<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0013<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0014<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0015<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0016<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0017<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Boot0018<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-BootCurrent<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-BootOptionSupport<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-BootOrder<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-BootOrderDefault<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ConIn<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ConInDev<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ConOut<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ConOutDev<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-DIAGSPLSHSCRN<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ErrOutDev<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-HDDPWD<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-KEK<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0000<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0001<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0002<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0003<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0004<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0005<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Key0006<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-LastBootCurrent<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-OsIndications<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-OsIndicationsSupported<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-PlatformLang<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-PlatformLangCodes<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-ProtectedBootOptions<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-SecureBoot<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-SetupHotKey<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-SetupMode<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-SimpleBootFlag<br />
8be4df61-93ca-11d2-aa0d-00e098032b8c-Timeout<br />
955b9041-133a-4bcf-90d1-97e1693c0e30-IEIT<br />
955b9041-133a-4bcf-90d1-97e1693c0e30-SecureBootOption<br />
9da5909e-ef5e-4851-8715-bf9e22b7a600-BGRTLogoIndex<br />
9dab39a4-3f8a-47ac-80c3-400729332c81-FirmwarePerformanceDataTable<br />
a2c1808f-0d4f-4cc9-a619-d1e641d39d49-LenovoSecurityConfig<br />
af9ffd67-ec10-488a-9dfc-6cbf5ee22c2e-AcpiGlobalVariable<br />
c3eeae98-23bf-412b-ab60-efcbb48e1534-SMBIOSELOG000<br />
c3eeae98-23bf-412b-ab60-efcbb48e1534-SMBIOSELOGNUMBER<br />
c3eeae98-23bf-412b-ab60-efcbb48e1534-SMBIOSMEMSIZE<br />
c4975200-64f1-4fb6-9773-f6a9f89d985e-SaPegData<br />
d719b2cb-3d3a-4596-a3bc-dad00e67656f-db<br />
d719b2cb-3d3a-4596-a3bc-dad00e67656f-dbx<br />
e5bbf7be-2417-499b-97db-39f4896391bc-BuildDate<br />
e5bbf7be-2417-499b-97db-39f4896391bc-BuildTime<br />
e6c2f70a-b604-4877-85ba-deec89e117eb-PchInit<br />
e6c2f70a-b604-4877-85ba-deec89e117eb-PchS3Peim<br />
eb704011-1402-11d3-8e77-00a0c969723b-MTC<br />
f9f0b131-f346-4f16-80dd-f941072b3a7d-iFfsData<br />
</nowiki>}}<br />
<br />
=== UEFI Variables Support in Linux Kernel ===<br />
<br />
Linux kernel exposes EFI variables data to userspace via 2 interfaces:<br />
<br />
# efivarfs ({{ic|efivarfs}} kernel module, {{ic|/sys/firmware/efi/efivars}}) that was designed to overcome the limitations of sysfs-efivars interface<br />
# Old sysfs-efivars interface ({{ic|efivars}} kernel module, {{ic|/sys/firmware/efi/vars}}) which has been disabled in from {{pkg|linux}} 3.11<br />
<br />
Efivarfs was introduced in kernel 3.8 and most of its bugs were ironed out in kernel 3.10. <br />
<br />
Running both sysfs-efivars and efivarfs can create inconsistencies in EFI variables data in the kernel and is discouraged. Going forward efivarfs is the recommended way for tools to interact with kernel registered EFI variables. All the UEFI variables related tools in [[official repositories]] support efivarfs as of 18 September 2013.<br />
<br />
==== Inconsistency between efivarfs and sysfs-efivars ====<br />
<br />
Both sysfs-efivars and efivarfs can run simultaneously, but this can cause inconsistency between sysfs-efivars data and efivarfs data, especially if data in both are simultaneously modified. See https://lkml.org/lkml/2013/4/16/473 for more info. Therefore it is advisable to use enable only one interface at a time and disable the other one.<br />
<br />
{{Note|From core/{{pkg|linux}} 3.11 onwards {{ic|efivars}} and {{ic|efi_pstore}} modules are no longer compiled (this change in only in Arch kernel, upstream has not removed sysfs-efivars code). In Arch, only efivarfs is enabled/supported.}}<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}})<br />
# Kernel processor bitness/arch and EFI processor bitness/arch should match<br />
# Kernel should be booted in EFI mode (via EFISTUB or any EFI bootloader, 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 it needs to be mounted manually<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 />
For mounting efivarfs (unless not automatically mounted by systemd during boot), follow:<br />
<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
{{Note|The above command should be run both BEFORE and AFTER '''chroot''', if any.}}<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 />
=== 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|* 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 />
* Upstream efibootmgr http://linux.dell.com/git/efibootmgr.git does not support efivarfs. However vathpela's efibootmgr supports efivarfs and is currently used in official efibootmgr pkg. sysfs-efivars is also completely disabled in official Arch kernel and it supports only efivarfs. This section is written with the assumtion that you are using only efivarfs and vathpela's efibootmgr.<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 />
= UEFI Bootloaders =<br />
<br />
See [[UEFI Bootloaders]] for the main article.<br />
<br />
= EFI System Partition =<br />
<br />
{{Note|Setting the {{ic|boot}} flag by {{ic|parted}} in a MBR partition marks that partition as active, while in a GPT partition it is marked as {{ic|EFI System Partition}}.}}<br />
<br />
{{Note|It is recommended to use always GPT for UEFI boot as some UEFI firmwares do not allow UEFI-MBR boot.}}<br />
<br />
The EFI System Partition is a 512 mb FAT32 physical partition (not LVM or software raid) that is marked as boot (not legacy boot). Initramfs and kernels (~28mb) are stored in the EFI system partition.<br />
<br />
<br />
<br />
{{Note|1=Microsoft documentation noteed 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 = 256 MB.Advanced Format 512e drives are not affected by this limitation, because their emulated sector size is 512 bytes. 512 bytes x 65527 = 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 />
<br />
== GPT partitioned disks ==<br />
<br />
Two choices:<br />
<br />
* Using GNU Parted/GParted: create a FAT32 partition. Set {{ic|boot}} flag on for that partition.<br />
* Using GPT fdisk (aka gdisk): create a partition with partition type {{ic|ef00}}. Then format that partition as FAT32 using {{ic|mkfs.vfat -F32 /dev/<THAT_PARTITION>}}<br />
<br />
If you get the message <code>WARNING: Not enough clusters for a 32 bit FAT!</code>, reduce cluster size with <code>mkfs.vfat -s2 -F32 ...</code> or <code>-s1</code>, otherwise the partition may be unreadable by UEFI.<br />
<br />
== MBR partitioned disks ==<br />
<br />
Two choices:<br />
<br />
* Using GNU Parted/GParted: create FAT32 partition. Change the type code of that partition to {{ic|0xEF}} using fdisk, cfdisk or sfdisk.<br />
* Using fdisk: create a partition with partition type {{ic|0xEF}}. Then format that partition as FAT32 using {{ic|mkfs.vfat -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| Users are recommended to try {{ic|bcfg}} only if {{ic|efibootmgr}} fails to create working boot entries in their system.}}<br />
<br />
{{Note| 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 />
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 />
{{Note|1=The instructions below are specifically for [[Archiso]]/official media; [[Archboot]] preparation is identical, without the filesystem label requirement.}}<br />
<br />
=== In Linux ===<br />
<br />
* [[Beginners_Guide#Prepare_the_storage_drive|First create either a MBR or GPT (recommended) partition table and at least one partition in the USB]] (so it is fine to use an already partitioned USB). {{Note|Using a GPT partition table is recommended as some firmwares don't support booting from MBR devices in full UEFI mode (e.g. Gigabyte).}}<br />
<br />
* Mount the ISO image from the [https://www.archlinux.org/download/ Arch Linux download page].<br />
<br />
# mkdir -p /mnt/{usb,iso}<br />
# mount -o loop archlinux-2013.10.01-dual.iso /mnt/iso<br />
<br />
* Then create a FAT32 filesystem in the partition on the USB (unmount before if necessary) with LABEL as used in the Archiso configuration. Obtain the label from {{ic|/mnt/iso/loader/entries/archiso-x86_64.conf}}; this is used by the {{ic|archiso}} hook in initramfs to identify the udev path to the installation media. {{ic|mkfs.vfat}} is part of package {{Pkg|dosfstools}}. {{Note|The filesystem should be either FAT32 (recommended), FAT16, or FAT12.}}<br />
<br />
# awk 'BEGIN {FS="="} /archisolabel/ {print $3}' /mnt/iso/loader/entries/archiso-x86_64.conf | xargs mkfs.vfat -F32 /dev/sdXY -n<br />
<br />
* Mount the newly created FAT32 USB partition, and copy the contents of the installation media to the USB media.<br />
<br />
# mount /dev/sdXY /mnt/usb<br />
# cp -a /mnt/iso/* /mnt/usb<br />
# sync<br />
# umount /mnt/{usb,iso}<br />
<br />
=== In Windows ===<br />
<br />
{{Note|Do not use any '''Bootable USB Creator utility''' for creating the UEFI bootable USB. Do not use ''dd for Windows'' to dd the ISO to the USB drive.}}<br />
<br />
* Format the USB drive as FAT32. {{Note|The filesystem should be either FAT32 (recommended), FAT16, or FAT12.}}<br />
<br />
* Extracted the ISO (similar to extracting ZIP archive) to the USB drive using [http://7-zip.org/ 7-Zip].<br />
<br />
* Change the '''Volume Label''' of the USB drive to match the LABEL mentioned in {{ic|1=archisolabel=}} part in {{ic|<USB>\loader\entries\archiso-x86_64.conf}} . {{Note|The above step is required for Official ISO (archiso) but not required for [[Archboot]].}}<br />
<br />
== Remove UEFI boot support from ISO ==<br />
<br />
{{Warning|In the event that UEFI+isohybrid El Torito/MBR really causes problems, it would be better to just UEFI boot using the USB stick instructions in the previous section}}<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 />
Rebuild the ISO using {{ic|xorriso}} from {{pkg|libisoburn}}:<br />
<br />
{{bc|1=<nowiki><br />
$ xorriso -as mkisofs -iso-level 3 \<br />
-full-iso9660-filenames\<br />
-volid "ARCH_201212" \<br />
-appid "Arch Linux CD" \<br />
-publisher "Arch Linux <https://www.archlinux.org>" \<br />
-preparer "prepared like a BAWSE" \<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 "~/archiso.iso" "/mnt/iso/"</nowiki>}}<br />
<br />
Burn {{ic|~/archiso.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 won't 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 won't 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 doesn't pretend the UEFI BIOS from starting CSM<br />
<br />
= See also =<br />
<br />
* Wikipedia's page on [http://en.wikipedia.org/wiki/UEFI UEFI]<br />
* Wikipedia's page on [http://en.wikipedia.org/wiki/EFI_System_partition 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://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>Blueriderhttps://wiki.archlinux.org/index.php?title=FFmpeg&diff=270567FFmpeg2013-08-10T02:32:15Z<p>Bluerider: /* Single-pass MPEG-2 (near lossless) */ turns out qscale was wrong, its q:a and q:v</p>
<hr />
<div>[[Category:Audio/Video]]<br />
{{Article summary start}}<br />
{{Article summary text|This article attempts to walk users through the installation, usage and configuration of FFmpeg.}}<br />
{{Article summary end}}<br />
<br />
From the project [http://www.ffmpeg.org/ home page]:<br />
:''FFmpeg is a complete, cross-platform solution to record, convert and stream audio and video. It includes libavcodec - the leading audio/video codec library.''<br />
<br />
== Package installation ==<br />
<br />
[[pacman|Install]] {{Pkg|ffmpeg}} from the [[official repositories]].<br />
<br />
Notable variants are:<br />
* {{AUR|ffmpeg-full}} - This version includes all codecs that due to license constraints are not in the official repositoies version, notably, the Fraunhofer AAC codec and the AAC+ codec.<br />
* {{AUR|libav}} - Replacement fork. The binary it provides is called ''avconv'' instead of ''ffmpeg''.<br />
<br />
== Encoding examples ==<br />
<br />
=== Screen cast to .webm ===<br />
<br />
Using ''x11grab'' to video grab your display and using ''ALSA'' for sound. First we create lossless raw file {{ic|test.mkv}}.<br />
<br />
$ ffmpeg -f x11grab -r 30 -i :0.0 -f alsa -i hw:0,0 -acodec flac -vcodec ffvhuff test.mkv<br />
<br />
Then we process this {{ic|test.mkv}} file into a smaller {{ic|test.webm}} end product. Complex switches like {{ic|c:a}} and {{ic|c:v}} convert the stream into what's needed for [http://en.wikipedia.org/wiki/WebM WebM].<br />
<br />
$ ffmpeg -y -i test.mkv -c:a libvorbis -q:a 3 -c:v libvpx -b:v 2000k test.webm<br />
<br />
See https://github.com/kaihendry/recordmydesktop2.0/ for a more fleshed out example.<br />
<br />
=== Recording webcam ===<br />
<br />
FFmpeg supports grabbing input from Video4Linux2 devices. The following command will record a video from the webcam, assuming that the webcam is correctly recognized under {{ic|/dev/video0}}:<br />
<br />
$ ffmpeg -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
The above produces a silent video. It is also possible to include audio sources from a microphone. The following command will include a stream from the default [[Advanced Linux Sound Architecture|ALSA]] recording device into the video:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
To use [[PulseAudio]] with an ALSA backend:<br />
<br />
$ ffmpeg -f alsa -i pulse -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
For a higher quality capture, try encoding the output using higher quality codecs:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 -acodec flac \<br />
-vcodec libx264 ''output''.mkv<br />
<br />
=== VOB to any container ===<br />
<br />
Concatenate the desired [[Wikipedia:VOB|VOB]] files into a single VOB file: <br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB<br />
Concatenate and then pipe the output VOB to FFmpeg to use a different format:<br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB | ffmpeg -i ...<br />
<br />
=== x264 lossless ===<br />
<br />
The ''ultrafast'' preset will provide the fastest encoding and is useful for quick capturing (such as screencasting):<br />
$ ffmpeg -i input -vcodec libx264 -preset ultrafast -qp 0 -acodec copy ''output.mkv''<br />
On the opposite end of the preset spectrum is ''veryslow'' and will encode slower than ''ultrafast'' but provide a smaller output file size:<br />
$ ffmpeg -i input -vcodec libx264 -preset veryslow -qp 0 -acodec copy ''output.mkv''<br />
Both examples will provide the same quality output.<br />
<br />
=== Single-pass MPEG-2 (near lossless) ===<br />
<br />
Allow FFmpeg to automatically set DVD standardized parameters. Encode to DVD [[Wikipedia:MPEG-2|MPEG-2]] at a frame rate of 30 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target ntsc-dvd -q:a 0 -q:v 0 ''output''.mpg<br />
<br />
Encode to DVD MPEG-2 at a frame rate of 24 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target film-dvd -q:a 0 -q:v 0 ''output''.mpg<br />
<br />
=== x264: constant rate factor ===<br />
<br />
Used when you want a specific quality output. General usage is to use the highest {{ic|-crf}} value that still provides an acceptable quality. A sane range is 18-28 and 23 is default. 18 is considered to be visually lossless. Use the slowest {{ic|-preset}} you have patience for. See the [https://ffmpeg.org/trac/ffmpeg/wiki/x264EncodingGuide x264 Encoding Guide] for more information.<br />
$ ffmpeg -i ''video'' -vcodec libx264 -preset slow -crf 22 -acodec libmp3lame -aq 4 ''output''.mkv<br />
{{ic|-tune}} option can be used to [http://forum.doom9.org/showthread.php?t=149394 match the type and content of the of media being encoded].<br />
<br />
=== YouTube ===<br />
<br />
FFmpeg is very useful to encode videos and strip their size before you upload them on YouTube. The following single line of code takes an input file and outputs a mkv container. <br />
<br />
$ ffmpeg -i ''video'' -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy ''output''.mkv<br />
<br />
For more information see the [https://bbs.archlinux.org/viewtopic.php?pid=1200667#p1200667 forums]. You can also create a custom alias {{ic|ytconvert}} which takes the name of the input file as first argument and the name of the .mkv container as second argument. To do so add the following to your {{ic|~/.bashrc}}:<br />
<br />
{{bc|<nowiki><br />
youtubeConvert(){<br />
ffmpeg -i $1 -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy $2.mkv<br />
}<br />
alias ytconvert=youtubeConvert<br />
</nowiki>}}<br />
See also [https://bbs.archlinux.org/viewtopic.php?pid=1200542#p1200542 Arch Linux forum thread].<br />
<br />
=== Two-pass x264 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are recorded during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec libx264 -pass 1 -preset veryslow \<br />
-threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 -f rawvideo -y /dev/null<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.mkv}}):<br />
$ ffmpeg -i ''video''.VOB -acodec libvo-aacenc -ab 256k -ar 96000 -vcodec libx264 \<br />
-pass 2 -preset veryslow -threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 ''video''.mkv<br />
<br />
{{Tip|If you receive {{ic|Unknown encoder 'libvo-aacenc'}} error (given the fact that your ffmpeg is compiled with libvo-aacenc enabled), you may want to try {{ic|-acodec libvo_aacenc}}, an underscore instead of hyphen.}}<br />
<br />
=== Two-pass MPEG-4 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are logged during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec mpeg4 -pass 1 -mbd 2 -trellis 2 -flags +cbp+mv0 \<br />
-pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 -b 3000k \<br />
-f rawvideo -y /dev/null<br />
<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.avi}}):<br />
$ ffmpeg -i ''video''.VOB -acodec copy -vcodec mpeg4 -vtag DX50 -pass 2 -mbd 2 -trellis 2 \<br />
-flags +cbp+mv0 -pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 \<br />
-b 3000k ''video''.avi<br />
* Introducing {{ic|threads}}={{ic|n}}>{{ic|1}} for {{ic|-vcodec mpeg4}} may skew the effects of [[Wikipedia:Motion_estimation|motion estimation]] and lead to [http://ffmpeg.org/faq.html#Why-do-I-see-a-slight-quality-degradation-with-multithreaded-MPEG_002a-encoding_003f reduced video quality] and compression efficiency.<br />
* The two-pass MPEG-4 example above also supports output to the [[Wikipedia:MPEG-4_Part_14|MP4]] container (replace {{ic|.avi}} with {{ic|.mp4}}).<br />
<br />
==== Determining bitrates with fixed output file sizes ====<br />
<br />
* (Desired File Size in MB - Audio File Size in MB) '''x''' 8192 kb/MB '''/''' Length of Media in Seconds (s) '''=''' [[Wikipedia:Bitrate|Bitrate]] in kb/s<br />
:* (3900 MB - 275 MB) = 3625 MB '''x''' 8192 kb/MB '''/''' 8830 s = 3363 kb/s required to achieve an approximate total output file size of 3900 MB<br />
<br />
=== Adding subtitles ===<br />
<br />
See http://trac.ffmpeg.org/wiki/How%20to%20burn%20subtitles%20into%20the%20video<br />
<br />
==== Softsubs to hardsubs ====<br />
<br />
If have a softsubbed video (eg. ASS/SSA subs in a mkv container like most anime) you can 'burn' these subs into a new file to be played on a device which does not support subs or is to weak to display complex subs.<br />
<br />
* Install {{Pkg|mkvtoolnix-cli}} to pull out {{ic|.ass}} files from {{ic|.mkv}} files.<br />
<br />
* Recompile FFmpeg with {{ic|--enable-libass}} if it is not already enabled in your FFmpeg build. See [[ABS]] for easy recompiling.<br />
<br />
* Pull out subs from your file. This command assumes that track #2 is the ASS/SSA track. Use {{ic|mkvinfo}} if it is not.<br />
$ mkvextract tracks ''your file''.mkv 2:''your file''.ass<br />
<br />
* Recode file with ffmpeg. See sections above for suitable options. It is very important to disable sub-recording and enable sub-rendering:<br />
$ ffmpeg ... -sn -vf ass=''subtitles''.ass<br />
<br />
Output is set as *.mp4 since the default Android 4.2 player dislikes *.mkv. (But VLC on Android works with mkv). Example:<br />
$ ffmpeg -i ''video''.mkv -sn -vcodec libx264 -crf 18 -preset slow -vf ass=''subtitles''.ass -acodec copy ''output''.mp4<br />
<br />
=== Volume gain ===<br />
<br />
Change the audio volume in multiples of 256 where '''256 = 100%''' (normal) volume. Additional values such as 400 are also valid options. <br />
-vol 256 = 100%<br />
-vol 512 = 200%<br />
-vol 768 = 300%<br />
-vol 1024 = 400%<br />
-vol 2048 = 800%<br />
<br />
To double the volume '''(512 = 200%)''' of an [[Wikipedia:Mp3|MP3]] file:<br />
$ ffmpeg -i ''file''.mp3 -vol 512 ''louder file''.mp3<br />
<br />
To quadruple the volume '''(1024 = 400%)''' of an [[Wikipedia:Ogg|Ogg]] file:<br />
$ ffmpeg -i ''file''.ogg -vol 1024 ''louder file''.ogg<br />
<br />
Note that gain metadata is only written to the output file. Unlike mp3gain or ogggain, the source sound file is untouched.<br />
<br />
=== Extracting audio ===<br />
<br />
{{hc|$ ffmpeg -i ''video''.mpg|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: ac3, 48000 Hz, stereo, s16, 384 kb/s<br />
Stream #0.2: Audio: ac3, 48000 Hz, 5.1, s16, 448 kb/s<br />
Stream #0.3: Audio: dts, 48000 Hz, 5.1 768 kb/s<br />
...<br />
}}<br />
<br />
Extract the first ({{ic|-map 0:1}}) [[Wikipedia:Dolby_Digital|AC-3]] encoded audio stream exactly as it was multiplexed into the file: <br />
$ ffmpeg -i ''video''.mpg -map 0:1 -acodec copy -vn ''video''.ac3<br />
Convert the third ({{ic|-map 0:3}}) [[Wikipedia:DTS_(sound_system)|DTS]] audio stream to an [[Wikipedia:Advanced_Audio_Coding|AAC]] file with a bitrate of 192 kb/s and a [[Wikipedia:Sampling_rate|sampling rate]] of 96000 Hz:<br />
$ ffmpeg -i ''video''.mpg -map 0:3 -acodec libvo-aacenc -ab 192k -ar 96000 -vn ''output''.aac<br />
{{ic|-vn}} disables the processing of the video stream.<br />
<br />
Extract audio stream with certain time interval: <br />
$ ffmpeg -ss 00:01:25 -t 00:00:05 -i ''video''.mpg -map 0:1 -acodec copy -vn ''output''.ac3<br />
{{ic|-ss}} specifies the start point, and {{ic|-t}} specifies the duration.<br />
<br />
=== Stripping audio ===<br />
<br />
# Copy the first video stream ({{ic|-map 0:0}}) along with the second AC-3 audio stream ({{ic|-map 0:2}}).<br />
# Convert the AC-3 audio stream to two-channel MP3 with a bitrate of 128 kb/s and a sampling rate of 48000 Hz.<br />
$ ffmpeg -i ''video''.mpg -map 0:0 -map 0:2 -vcodec copy -acodec libmp3lame \<br />
-ab 128k -ar 48000 -ac 2 ''video''.mkv<br />
<br />
{{hc|$ ffmpeg -i ''video''.mkv|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: mp3, 48000 Hz, stereo, s16, 128 kb/s<br />
}}<br />
<br />
{{Note|Removing undesired audio streams allows for additional bits to be allocated towards improving video quality.}}<br />
<br />
== Preset files ==<br />
<br />
Populate {{ic|~/.ffmpeg}} with the default [http://ffmpeg.org/ffmpeg-doc.html#SEC13 preset files]: <br />
<br />
$ cp -iR /usr/share/ffmpeg ~/.ffmpeg<br />
<br />
Create new and/or modify the default preset files:<br />
<br />
{{hc|~/.ffmpeg/libavcodec-vhq.ffpreset|2=<br />
vtag=DX50<br />
mbd=2<br />
trellis=2<br />
flags=+cbp+mv0<br />
pre_dia_size=4<br />
dia_size=4<br />
precmp=4<br />
cmp=4<br />
subcmp=4<br />
preme=2<br />
qns=2<br />
}}<br />
<br />
=== Using preset files ===<br />
<br />
Enable the {{ic|-vpre}} option after declaring the desired {{ic|-vcodec}}<br />
<br />
==== libavcodec-vhq.ffpreset ====<br />
<br />
* {{ic|libavcodec}} '''=''' Name of the vcodec/acodec<br />
* {{ic|vhq}} '''=''' Name of specific preset to be called out<br />
* {{ic|ffpreset}} '''=''' FFmpeg preset filetype suffix <br />
<br />
===== Two-pass MPEG-4 (very high quality) =====<br />
<br />
First pass of a multipass (bitrate) ratecontrol transcode:<br />
$ ffmpeg -i ''video''.mpg -an -vcodec mpeg4 -pass 1 -vpre vhq -f rawvideo -y /dev/null<br />
Ratecontrol based on the video statistics logged from the first pass: <br />
$ ffmpeg -i ''video''.mpg -acodec libvorbis -aq 8 -ar 48000 -vcodec mpeg4 \<br />
-pass 2 -vpre vhq -b 3000k ''output''.mp4<br />
<br />
* '''libvorbis quality settings (VBR)'''<br />
:* {{ic|-aq 4}} = 128 kb/s<br />
:* {{ic|-aq 5}} = 160 kb/s<br />
:* {{ic|-aq 6}} = 192 kb/s<br />
:* {{ic|-aq 7}} = 224 kb/s<br />
:* {{ic|-aq 8}} = 256 kb/s<br />
<br />
* [http://www.geocities.jp/aoyoume/aotuv/ aoTuV] is generally preferred over [http://vorbis.com/ libvorbis] provided by [http://www.xiph.org/ Xiph.Org] and is provided by [https://aur.archlinux.org/packages.php?ID=6155 libvorbis-aotuv] in the [[AUR]].<br />
<br />
== Package removal ==<br />
<br />
[[pacman]] will not [[Pacman#Removing_packages|remove]] configuration files outside of the defaults that were created during package installation. This includes user-created preset files.<br />
<br />
== See also ==<br />
<br />
* [http://mewiki.project357.com/wiki/X264_Settings x264 Settings] - MeWiki documentation<br />
* [http://ffmpeg.org/ffmpeg-doc.html FFmpeg documentation] - official documentation<br />
* [http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-x264.html Encoding with the x264 codec] - MEncoder documentation<br />
* [http://avidemux.org/admWiki/doku.php?id=tutorial:h.264 H.264 encoding guide] - Avidemux wiki<br />
* [http://howto-pages.org/ffmpeg/ Using FFmpeg] - Linux how to pages<br />
* [http://ffmpeg.org/general.html#Supported-File-Formats-and-Codecs List] of supported audio and video streams</div>Blueriderhttps://wiki.archlinux.org/index.php?title=FFmpeg&diff=270563FFmpeg2013-08-10T02:15:50Z<p>Bluerider: /* Single-pass MPEG-2 (near lossless) */</p>
<hr />
<div>[[Category:Audio/Video]]<br />
{{Article summary start}}<br />
{{Article summary text|This article attempts to walk users through the installation, usage and configuration of FFmpeg.}}<br />
{{Article summary end}}<br />
<br />
From the project [http://www.ffmpeg.org/ home page]:<br />
:''FFmpeg is a complete, cross-platform solution to record, convert and stream audio and video. It includes libavcodec - the leading audio/video codec library.''<br />
<br />
== Package installation ==<br />
<br />
[[pacman|Install]] {{Pkg|ffmpeg}} from the [[official repositories]].<br />
<br />
Notable variants are:<br />
* {{AUR|ffmpeg-full}} - This version includes all codecs that due to license constraints are not in the official repositoies version, notably, the Fraunhofer AAC codec and the AAC+ codec.<br />
* {{AUR|libav}} - Replacement fork. The binary it provides is called ''avconv'' instead of ''ffmpeg''.<br />
<br />
== Encoding examples ==<br />
<br />
=== Screen cast to .webm ===<br />
<br />
Using ''x11grab'' to video grab your display and using ''ALSA'' for sound. First we create lossless raw file {{ic|test.mkv}}.<br />
<br />
$ ffmpeg -f x11grab -r 30 -i :0.0 -f alsa -i hw:0,0 -acodec flac -vcodec ffvhuff test.mkv<br />
<br />
Then we process this {{ic|test.mkv}} file into a smaller {{ic|test.webm}} end product. Complex switches like {{ic|c:a}} and {{ic|c:v}} convert the stream into what's needed for [http://en.wikipedia.org/wiki/WebM WebM].<br />
<br />
$ ffmpeg -y -i test.mkv -c:a libvorbis -q:a 3 -c:v libvpx -b:v 2000k test.webm<br />
<br />
See https://github.com/kaihendry/recordmydesktop2.0/ for a more fleshed out example.<br />
<br />
=== Recording webcam ===<br />
<br />
FFmpeg supports grabbing input from Video4Linux2 devices. The following command will record a video from the webcam, assuming that the webcam is correctly recognized under {{ic|/dev/video0}}:<br />
<br />
$ ffmpeg -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
The above produces a silent video. It is also possible to include audio sources from a microphone. The following command will include a stream from the default [[Advanced Linux Sound Architecture|ALSA]] recording device into the video:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
To use [[PulseAudio]] with an ALSA backend:<br />
<br />
$ ffmpeg -f alsa -i pulse -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
For a higher quality capture, try encoding the output using higher quality codecs:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 -acodec flac \<br />
-vcodec libx264 ''output''.mkv<br />
<br />
=== VOB to any container ===<br />
<br />
Concatenate the desired [[Wikipedia:VOB|VOB]] files into a single VOB file: <br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB<br />
Concatenate and then pipe the output VOB to FFmpeg to use a different format:<br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB | ffmpeg -i ...<br />
<br />
=== x264 lossless ===<br />
<br />
The ''ultrafast'' preset will provide the fastest encoding and is useful for quick capturing (such as screencasting):<br />
$ ffmpeg -i input -vcodec libx264 -preset ultrafast -qp 0 -acodec copy ''output.mkv''<br />
On the opposite end of the preset spectrum is ''veryslow'' and will encode slower than ''ultrafast'' but provide a smaller output file size:<br />
$ ffmpeg -i input -vcodec libx264 -preset veryslow -qp 0 -acodec copy ''output.mkv''<br />
Both examples will provide the same quality output.<br />
<br />
=== Single-pass MPEG-2 (near lossless) ===<br />
<br />
Allow FFmpeg to automatically set DVD standardized parameters. Encode to DVD [[Wikipedia:MPEG-2|MPEG-2]] at a frame rate of 30 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target ntsc-dvd -qscale 0 ''output''.mpg<br />
<br />
Encode to DVD MPEG-2 at a frame rate of 24 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target film-dvd -qscale 0 ''output''.mpg<br />
<br />
=== x264: constant rate factor ===<br />
<br />
Used when you want a specific quality output. General usage is to use the highest {{ic|-crf}} value that still provides an acceptable quality. A sane range is 18-28 and 23 is default. 18 is considered to be visually lossless. Use the slowest {{ic|-preset}} you have patience for. See the [https://ffmpeg.org/trac/ffmpeg/wiki/x264EncodingGuide x264 Encoding Guide] for more information.<br />
$ ffmpeg -i ''video'' -vcodec libx264 -preset slow -crf 22 -acodec libmp3lame -aq 4 ''output''.mkv<br />
{{ic|-tune}} option can be used to [http://forum.doom9.org/showthread.php?t=149394 match the type and content of the of media being encoded].<br />
<br />
=== YouTube ===<br />
<br />
FFmpeg is very useful to encode videos and strip their size before you upload them on YouTube. The following single line of code takes an input file and outputs a mkv container. <br />
<br />
$ ffmpeg -i ''video'' -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy ''output''.mkv<br />
<br />
For more information see the [https://bbs.archlinux.org/viewtopic.php?pid=1200667#p1200667 forums]. You can also create a custom alias {{ic|ytconvert}} which takes the name of the input file as first argument and the name of the .mkv container as second argument. To do so add the following to your {{ic|~/.bashrc}}:<br />
<br />
{{bc|<nowiki><br />
youtubeConvert(){<br />
ffmpeg -i $1 -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy $2.mkv<br />
}<br />
alias ytconvert=youtubeConvert<br />
</nowiki>}}<br />
See also [https://bbs.archlinux.org/viewtopic.php?pid=1200542#p1200542 Arch Linux forum thread].<br />
<br />
=== Two-pass x264 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are recorded during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec libx264 -pass 1 -preset veryslow \<br />
-threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 -f rawvideo -y /dev/null<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.mkv}}):<br />
$ ffmpeg -i ''video''.VOB -acodec libvo-aacenc -ab 256k -ar 96000 -vcodec libx264 \<br />
-pass 2 -preset veryslow -threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 ''video''.mkv<br />
<br />
{{Tip|If you receive {{ic|Unknown encoder 'libvo-aacenc'}} error (given the fact that your ffmpeg is compiled with libvo-aacenc enabled), you may want to try {{ic|-acodec libvo_aacenc}}, an underscore instead of hyphen.}}<br />
<br />
=== Two-pass MPEG-4 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are logged during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec mpeg4 -pass 1 -mbd 2 -trellis 2 -flags +cbp+mv0 \<br />
-pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 -b 3000k \<br />
-f rawvideo -y /dev/null<br />
<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.avi}}):<br />
$ ffmpeg -i ''video''.VOB -acodec copy -vcodec mpeg4 -vtag DX50 -pass 2 -mbd 2 -trellis 2 \<br />
-flags +cbp+mv0 -pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 \<br />
-b 3000k ''video''.avi<br />
* Introducing {{ic|threads}}={{ic|n}}>{{ic|1}} for {{ic|-vcodec mpeg4}} may skew the effects of [[Wikipedia:Motion_estimation|motion estimation]] and lead to [http://ffmpeg.org/faq.html#Why-do-I-see-a-slight-quality-degradation-with-multithreaded-MPEG_002a-encoding_003f reduced video quality] and compression efficiency.<br />
* The two-pass MPEG-4 example above also supports output to the [[Wikipedia:MPEG-4_Part_14|MP4]] container (replace {{ic|.avi}} with {{ic|.mp4}}).<br />
<br />
==== Determining bitrates with fixed output file sizes ====<br />
<br />
* (Desired File Size in MB - Audio File Size in MB) '''x''' 8192 kb/MB '''/''' Length of Media in Seconds (s) '''=''' [[Wikipedia:Bitrate|Bitrate]] in kb/s<br />
:* (3900 MB - 275 MB) = 3625 MB '''x''' 8192 kb/MB '''/''' 8830 s = 3363 kb/s required to achieve an approximate total output file size of 3900 MB<br />
<br />
=== Adding subtitles ===<br />
<br />
See http://trac.ffmpeg.org/wiki/How%20to%20burn%20subtitles%20into%20the%20video<br />
<br />
==== Softsubs to hardsubs ====<br />
<br />
If have a softsubbed video (eg. ASS/SSA subs in a mkv container like most anime) you can 'burn' these subs into a new file to be played on a device which does not support subs or is to weak to display complex subs.<br />
<br />
* Install {{Pkg|mkvtoolnix-cli}} to pull out {{ic|.ass}} files from {{ic|.mkv}} files.<br />
<br />
* Recompile FFmpeg with {{ic|--enable-libass}} if it is not already enabled in your FFmpeg build. See [[ABS]] for easy recompiling.<br />
<br />
* Pull out subs from your file. This command assumes that track #2 is the ASS/SSA track. Use {{ic|mkvinfo}} if it is not.<br />
$ mkvextract tracks ''your file''.mkv 2:''your file''.ass<br />
<br />
* Recode file with ffmpeg. See sections above for suitable options. It is very important to disable sub-recording and enable sub-rendering:<br />
$ ffmpeg ... -sn -vf ass=''subtitles''.ass<br />
<br />
Output is set as *.mp4 since the default Android 4.2 player dislikes *.mkv. (But VLC on Android works with mkv). Example:<br />
$ ffmpeg -i ''video''.mkv -sn -vcodec libx264 -crf 18 -preset slow -vf ass=''subtitles''.ass -acodec copy ''output''.mp4<br />
<br />
=== Volume gain ===<br />
<br />
Change the audio volume in multiples of 256 where '''256 = 100%''' (normal) volume. Additional values such as 400 are also valid options. <br />
-vol 256 = 100%<br />
-vol 512 = 200%<br />
-vol 768 = 300%<br />
-vol 1024 = 400%<br />
-vol 2048 = 800%<br />
<br />
To double the volume '''(512 = 200%)''' of an [[Wikipedia:Mp3|MP3]] file:<br />
$ ffmpeg -i ''file''.mp3 -vol 512 ''louder file''.mp3<br />
<br />
To quadruple the volume '''(1024 = 400%)''' of an [[Wikipedia:Ogg|Ogg]] file:<br />
$ ffmpeg -i ''file''.ogg -vol 1024 ''louder file''.ogg<br />
<br />
Note that gain metadata is only written to the output file. Unlike mp3gain or ogggain, the source sound file is untouched.<br />
<br />
=== Extracting audio ===<br />
<br />
{{hc|$ ffmpeg -i ''video''.mpg|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: ac3, 48000 Hz, stereo, s16, 384 kb/s<br />
Stream #0.2: Audio: ac3, 48000 Hz, 5.1, s16, 448 kb/s<br />
Stream #0.3: Audio: dts, 48000 Hz, 5.1 768 kb/s<br />
...<br />
}}<br />
<br />
Extract the first ({{ic|-map 0:1}}) [[Wikipedia:Dolby_Digital|AC-3]] encoded audio stream exactly as it was multiplexed into the file: <br />
$ ffmpeg -i ''video''.mpg -map 0:1 -acodec copy -vn ''video''.ac3<br />
Convert the third ({{ic|-map 0:3}}) [[Wikipedia:DTS_(sound_system)|DTS]] audio stream to an [[Wikipedia:Advanced_Audio_Coding|AAC]] file with a bitrate of 192 kb/s and a [[Wikipedia:Sampling_rate|sampling rate]] of 96000 Hz:<br />
$ ffmpeg -i ''video''.mpg -map 0:3 -acodec libvo-aacenc -ab 192k -ar 96000 -vn ''output''.aac<br />
{{ic|-vn}} disables the processing of the video stream.<br />
<br />
Extract audio stream with certain time interval: <br />
$ ffmpeg -ss 00:01:25 -t 00:00:05 -i ''video''.mpg -map 0:1 -acodec copy -vn ''output''.ac3<br />
{{ic|-ss}} specifies the start point, and {{ic|-t}} specifies the duration.<br />
<br />
=== Stripping audio ===<br />
<br />
# Copy the first video stream ({{ic|-map 0:0}}) along with the second AC-3 audio stream ({{ic|-map 0:2}}).<br />
# Convert the AC-3 audio stream to two-channel MP3 with a bitrate of 128 kb/s and a sampling rate of 48000 Hz.<br />
$ ffmpeg -i ''video''.mpg -map 0:0 -map 0:2 -vcodec copy -acodec libmp3lame \<br />
-ab 128k -ar 48000 -ac 2 ''video''.mkv<br />
<br />
{{hc|$ ffmpeg -i ''video''.mkv|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: mp3, 48000 Hz, stereo, s16, 128 kb/s<br />
}}<br />
<br />
{{Note|Removing undesired audio streams allows for additional bits to be allocated towards improving video quality.}}<br />
<br />
== Preset files ==<br />
<br />
Populate {{ic|~/.ffmpeg}} with the default [http://ffmpeg.org/ffmpeg-doc.html#SEC13 preset files]: <br />
<br />
$ cp -iR /usr/share/ffmpeg ~/.ffmpeg<br />
<br />
Create new and/or modify the default preset files:<br />
<br />
{{hc|~/.ffmpeg/libavcodec-vhq.ffpreset|2=<br />
vtag=DX50<br />
mbd=2<br />
trellis=2<br />
flags=+cbp+mv0<br />
pre_dia_size=4<br />
dia_size=4<br />
precmp=4<br />
cmp=4<br />
subcmp=4<br />
preme=2<br />
qns=2<br />
}}<br />
<br />
=== Using preset files ===<br />
<br />
Enable the {{ic|-vpre}} option after declaring the desired {{ic|-vcodec}}<br />
<br />
==== libavcodec-vhq.ffpreset ====<br />
<br />
* {{ic|libavcodec}} '''=''' Name of the vcodec/acodec<br />
* {{ic|vhq}} '''=''' Name of specific preset to be called out<br />
* {{ic|ffpreset}} '''=''' FFmpeg preset filetype suffix <br />
<br />
===== Two-pass MPEG-4 (very high quality) =====<br />
<br />
First pass of a multipass (bitrate) ratecontrol transcode:<br />
$ ffmpeg -i ''video''.mpg -an -vcodec mpeg4 -pass 1 -vpre vhq -f rawvideo -y /dev/null<br />
Ratecontrol based on the video statistics logged from the first pass: <br />
$ ffmpeg -i ''video''.mpg -acodec libvorbis -aq 8 -ar 48000 -vcodec mpeg4 \<br />
-pass 2 -vpre vhq -b 3000k ''output''.mp4<br />
<br />
* '''libvorbis quality settings (VBR)'''<br />
:* {{ic|-aq 4}} = 128 kb/s<br />
:* {{ic|-aq 5}} = 160 kb/s<br />
:* {{ic|-aq 6}} = 192 kb/s<br />
:* {{ic|-aq 7}} = 224 kb/s<br />
:* {{ic|-aq 8}} = 256 kb/s<br />
<br />
* [http://www.geocities.jp/aoyoume/aotuv/ aoTuV] is generally preferred over [http://vorbis.com/ libvorbis] provided by [http://www.xiph.org/ Xiph.Org] and is provided by [https://aur.archlinux.org/packages.php?ID=6155 libvorbis-aotuv] in the [[AUR]].<br />
<br />
== Package removal ==<br />
<br />
[[pacman]] will not [[Pacman#Removing_packages|remove]] configuration files outside of the defaults that were created during package installation. This includes user-created preset files.<br />
<br />
== See also ==<br />
<br />
* [http://mewiki.project357.com/wiki/X264_Settings x264 Settings] - MeWiki documentation<br />
* [http://ffmpeg.org/ffmpeg-doc.html FFmpeg documentation] - official documentation<br />
* [http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-x264.html Encoding with the x264 codec] - MEncoder documentation<br />
* [http://avidemux.org/admWiki/doku.php?id=tutorial:h.264 H.264 encoding guide] - Avidemux wiki<br />
* [http://howto-pages.org/ffmpeg/ Using FFmpeg] - Linux how to pages<br />
* [http://ffmpeg.org/general.html#Supported-File-Formats-and-Codecs List] of supported audio and video streams</div>Blueriderhttps://wiki.archlinux.org/index.php?title=FFmpeg&diff=270562FFmpeg2013-08-10T02:15:35Z<p>Bluerider: /* Single-pass MPEG-2 (near lossless) */</p>
<hr />
<div>[[Category:Audio/Video]]<br />
{{Article summary start}}<br />
{{Article summary text|This article attempts to walk users through the installation, usage and configuration of FFmpeg.}}<br />
{{Article summary end}}<br />
<br />
From the project [http://www.ffmpeg.org/ home page]:<br />
:''FFmpeg is a complete, cross-platform solution to record, convert and stream audio and video. It includes libavcodec - the leading audio/video codec library.''<br />
<br />
== Package installation ==<br />
<br />
[[pacman|Install]] {{Pkg|ffmpeg}} from the [[official repositories]].<br />
<br />
Notable variants are:<br />
* {{AUR|ffmpeg-full}} - This version includes all codecs that due to license constraints are not in the official repositoies version, notably, the Fraunhofer AAC codec and the AAC+ codec.<br />
* {{AUR|libav}} - Replacement fork. The binary it provides is called ''avconv'' instead of ''ffmpeg''.<br />
<br />
== Encoding examples ==<br />
<br />
=== Screen cast to .webm ===<br />
<br />
Using ''x11grab'' to video grab your display and using ''ALSA'' for sound. First we create lossless raw file {{ic|test.mkv}}.<br />
<br />
$ ffmpeg -f x11grab -r 30 -i :0.0 -f alsa -i hw:0,0 -acodec flac -vcodec ffvhuff test.mkv<br />
<br />
Then we process this {{ic|test.mkv}} file into a smaller {{ic|test.webm}} end product. Complex switches like {{ic|c:a}} and {{ic|c:v}} convert the stream into what's needed for [http://en.wikipedia.org/wiki/WebM WebM].<br />
<br />
$ ffmpeg -y -i test.mkv -c:a libvorbis -q:a 3 -c:v libvpx -b:v 2000k test.webm<br />
<br />
See https://github.com/kaihendry/recordmydesktop2.0/ for a more fleshed out example.<br />
<br />
=== Recording webcam ===<br />
<br />
FFmpeg supports grabbing input from Video4Linux2 devices. The following command will record a video from the webcam, assuming that the webcam is correctly recognized under {{ic|/dev/video0}}:<br />
<br />
$ ffmpeg -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
The above produces a silent video. It is also possible to include audio sources from a microphone. The following command will include a stream from the default [[Advanced Linux Sound Architecture|ALSA]] recording device into the video:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
To use [[PulseAudio]] with an ALSA backend:<br />
<br />
$ ffmpeg -f alsa -i pulse -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
For a higher quality capture, try encoding the output using higher quality codecs:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 -acodec flac \<br />
-vcodec libx264 ''output''.mkv<br />
<br />
=== VOB to any container ===<br />
<br />
Concatenate the desired [[Wikipedia:VOB|VOB]] files into a single VOB file: <br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB<br />
Concatenate and then pipe the output VOB to FFmpeg to use a different format:<br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB | ffmpeg -i ...<br />
<br />
=== x264 lossless ===<br />
<br />
The ''ultrafast'' preset will provide the fastest encoding and is useful for quick capturing (such as screencasting):<br />
$ ffmpeg -i input -vcodec libx264 -preset ultrafast -qp 0 -acodec copy ''output.mkv''<br />
On the opposite end of the preset spectrum is ''veryslow'' and will encode slower than ''ultrafast'' but provide a smaller output file size:<br />
$ ffmpeg -i input -vcodec libx264 -preset veryslow -qp 0 -acodec copy ''output.mkv''<br />
Both examples will provide the same quality output.<br />
<br />
=== Single-pass MPEG-2 (near lossless) ===<br />
<br />
Allow FFmpeg to automatically set DVD standardized parameters. Encode to DVD [[Wikipedia:MPEG-2|MPEG-2]] at a frame rate of 30 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target ntsc-dvd -qscale 0 ''output''.mpg<br />
<br />
Encode to DVD MPEG-2 at a frame rate of 24 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target film-dvd -qscale 0''output''.mpg<br />
<br />
=== x264: constant rate factor ===<br />
<br />
Used when you want a specific quality output. General usage is to use the highest {{ic|-crf}} value that still provides an acceptable quality. A sane range is 18-28 and 23 is default. 18 is considered to be visually lossless. Use the slowest {{ic|-preset}} you have patience for. See the [https://ffmpeg.org/trac/ffmpeg/wiki/x264EncodingGuide x264 Encoding Guide] for more information.<br />
$ ffmpeg -i ''video'' -vcodec libx264 -preset slow -crf 22 -acodec libmp3lame -aq 4 ''output''.mkv<br />
{{ic|-tune}} option can be used to [http://forum.doom9.org/showthread.php?t=149394 match the type and content of the of media being encoded].<br />
<br />
=== YouTube ===<br />
<br />
FFmpeg is very useful to encode videos and strip their size before you upload them on YouTube. The following single line of code takes an input file and outputs a mkv container. <br />
<br />
$ ffmpeg -i ''video'' -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy ''output''.mkv<br />
<br />
For more information see the [https://bbs.archlinux.org/viewtopic.php?pid=1200667#p1200667 forums]. You can also create a custom alias {{ic|ytconvert}} which takes the name of the input file as first argument and the name of the .mkv container as second argument. To do so add the following to your {{ic|~/.bashrc}}:<br />
<br />
{{bc|<nowiki><br />
youtubeConvert(){<br />
ffmpeg -i $1 -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy $2.mkv<br />
}<br />
alias ytconvert=youtubeConvert<br />
</nowiki>}}<br />
See also [https://bbs.archlinux.org/viewtopic.php?pid=1200542#p1200542 Arch Linux forum thread].<br />
<br />
=== Two-pass x264 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are recorded during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec libx264 -pass 1 -preset veryslow \<br />
-threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 -f rawvideo -y /dev/null<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.mkv}}):<br />
$ ffmpeg -i ''video''.VOB -acodec libvo-aacenc -ab 256k -ar 96000 -vcodec libx264 \<br />
-pass 2 -preset veryslow -threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 ''video''.mkv<br />
<br />
{{Tip|If you receive {{ic|Unknown encoder 'libvo-aacenc'}} error (given the fact that your ffmpeg is compiled with libvo-aacenc enabled), you may want to try {{ic|-acodec libvo_aacenc}}, an underscore instead of hyphen.}}<br />
<br />
=== Two-pass MPEG-4 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are logged during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec mpeg4 -pass 1 -mbd 2 -trellis 2 -flags +cbp+mv0 \<br />
-pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 -b 3000k \<br />
-f rawvideo -y /dev/null<br />
<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.avi}}):<br />
$ ffmpeg -i ''video''.VOB -acodec copy -vcodec mpeg4 -vtag DX50 -pass 2 -mbd 2 -trellis 2 \<br />
-flags +cbp+mv0 -pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 \<br />
-b 3000k ''video''.avi<br />
* Introducing {{ic|threads}}={{ic|n}}>{{ic|1}} for {{ic|-vcodec mpeg4}} may skew the effects of [[Wikipedia:Motion_estimation|motion estimation]] and lead to [http://ffmpeg.org/faq.html#Why-do-I-see-a-slight-quality-degradation-with-multithreaded-MPEG_002a-encoding_003f reduced video quality] and compression efficiency.<br />
* The two-pass MPEG-4 example above also supports output to the [[Wikipedia:MPEG-4_Part_14|MP4]] container (replace {{ic|.avi}} with {{ic|.mp4}}).<br />
<br />
==== Determining bitrates with fixed output file sizes ====<br />
<br />
* (Desired File Size in MB - Audio File Size in MB) '''x''' 8192 kb/MB '''/''' Length of Media in Seconds (s) '''=''' [[Wikipedia:Bitrate|Bitrate]] in kb/s<br />
:* (3900 MB - 275 MB) = 3625 MB '''x''' 8192 kb/MB '''/''' 8830 s = 3363 kb/s required to achieve an approximate total output file size of 3900 MB<br />
<br />
=== Adding subtitles ===<br />
<br />
See http://trac.ffmpeg.org/wiki/How%20to%20burn%20subtitles%20into%20the%20video<br />
<br />
==== Softsubs to hardsubs ====<br />
<br />
If have a softsubbed video (eg. ASS/SSA subs in a mkv container like most anime) you can 'burn' these subs into a new file to be played on a device which does not support subs or is to weak to display complex subs.<br />
<br />
* Install {{Pkg|mkvtoolnix-cli}} to pull out {{ic|.ass}} files from {{ic|.mkv}} files.<br />
<br />
* Recompile FFmpeg with {{ic|--enable-libass}} if it is not already enabled in your FFmpeg build. See [[ABS]] for easy recompiling.<br />
<br />
* Pull out subs from your file. This command assumes that track #2 is the ASS/SSA track. Use {{ic|mkvinfo}} if it is not.<br />
$ mkvextract tracks ''your file''.mkv 2:''your file''.ass<br />
<br />
* Recode file with ffmpeg. See sections above for suitable options. It is very important to disable sub-recording and enable sub-rendering:<br />
$ ffmpeg ... -sn -vf ass=''subtitles''.ass<br />
<br />
Output is set as *.mp4 since the default Android 4.2 player dislikes *.mkv. (But VLC on Android works with mkv). Example:<br />
$ ffmpeg -i ''video''.mkv -sn -vcodec libx264 -crf 18 -preset slow -vf ass=''subtitles''.ass -acodec copy ''output''.mp4<br />
<br />
=== Volume gain ===<br />
<br />
Change the audio volume in multiples of 256 where '''256 = 100%''' (normal) volume. Additional values such as 400 are also valid options. <br />
-vol 256 = 100%<br />
-vol 512 = 200%<br />
-vol 768 = 300%<br />
-vol 1024 = 400%<br />
-vol 2048 = 800%<br />
<br />
To double the volume '''(512 = 200%)''' of an [[Wikipedia:Mp3|MP3]] file:<br />
$ ffmpeg -i ''file''.mp3 -vol 512 ''louder file''.mp3<br />
<br />
To quadruple the volume '''(1024 = 400%)''' of an [[Wikipedia:Ogg|Ogg]] file:<br />
$ ffmpeg -i ''file''.ogg -vol 1024 ''louder file''.ogg<br />
<br />
Note that gain metadata is only written to the output file. Unlike mp3gain or ogggain, the source sound file is untouched.<br />
<br />
=== Extracting audio ===<br />
<br />
{{hc|$ ffmpeg -i ''video''.mpg|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: ac3, 48000 Hz, stereo, s16, 384 kb/s<br />
Stream #0.2: Audio: ac3, 48000 Hz, 5.1, s16, 448 kb/s<br />
Stream #0.3: Audio: dts, 48000 Hz, 5.1 768 kb/s<br />
...<br />
}}<br />
<br />
Extract the first ({{ic|-map 0:1}}) [[Wikipedia:Dolby_Digital|AC-3]] encoded audio stream exactly as it was multiplexed into the file: <br />
$ ffmpeg -i ''video''.mpg -map 0:1 -acodec copy -vn ''video''.ac3<br />
Convert the third ({{ic|-map 0:3}}) [[Wikipedia:DTS_(sound_system)|DTS]] audio stream to an [[Wikipedia:Advanced_Audio_Coding|AAC]] file with a bitrate of 192 kb/s and a [[Wikipedia:Sampling_rate|sampling rate]] of 96000 Hz:<br />
$ ffmpeg -i ''video''.mpg -map 0:3 -acodec libvo-aacenc -ab 192k -ar 96000 -vn ''output''.aac<br />
{{ic|-vn}} disables the processing of the video stream.<br />
<br />
Extract audio stream with certain time interval: <br />
$ ffmpeg -ss 00:01:25 -t 00:00:05 -i ''video''.mpg -map 0:1 -acodec copy -vn ''output''.ac3<br />
{{ic|-ss}} specifies the start point, and {{ic|-t}} specifies the duration.<br />
<br />
=== Stripping audio ===<br />
<br />
# Copy the first video stream ({{ic|-map 0:0}}) along with the second AC-3 audio stream ({{ic|-map 0:2}}).<br />
# Convert the AC-3 audio stream to two-channel MP3 with a bitrate of 128 kb/s and a sampling rate of 48000 Hz.<br />
$ ffmpeg -i ''video''.mpg -map 0:0 -map 0:2 -vcodec copy -acodec libmp3lame \<br />
-ab 128k -ar 48000 -ac 2 ''video''.mkv<br />
<br />
{{hc|$ ffmpeg -i ''video''.mkv|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: mp3, 48000 Hz, stereo, s16, 128 kb/s<br />
}}<br />
<br />
{{Note|Removing undesired audio streams allows for additional bits to be allocated towards improving video quality.}}<br />
<br />
== Preset files ==<br />
<br />
Populate {{ic|~/.ffmpeg}} with the default [http://ffmpeg.org/ffmpeg-doc.html#SEC13 preset files]: <br />
<br />
$ cp -iR /usr/share/ffmpeg ~/.ffmpeg<br />
<br />
Create new and/or modify the default preset files:<br />
<br />
{{hc|~/.ffmpeg/libavcodec-vhq.ffpreset|2=<br />
vtag=DX50<br />
mbd=2<br />
trellis=2<br />
flags=+cbp+mv0<br />
pre_dia_size=4<br />
dia_size=4<br />
precmp=4<br />
cmp=4<br />
subcmp=4<br />
preme=2<br />
qns=2<br />
}}<br />
<br />
=== Using preset files ===<br />
<br />
Enable the {{ic|-vpre}} option after declaring the desired {{ic|-vcodec}}<br />
<br />
==== libavcodec-vhq.ffpreset ====<br />
<br />
* {{ic|libavcodec}} '''=''' Name of the vcodec/acodec<br />
* {{ic|vhq}} '''=''' Name of specific preset to be called out<br />
* {{ic|ffpreset}} '''=''' FFmpeg preset filetype suffix <br />
<br />
===== Two-pass MPEG-4 (very high quality) =====<br />
<br />
First pass of a multipass (bitrate) ratecontrol transcode:<br />
$ ffmpeg -i ''video''.mpg -an -vcodec mpeg4 -pass 1 -vpre vhq -f rawvideo -y /dev/null<br />
Ratecontrol based on the video statistics logged from the first pass: <br />
$ ffmpeg -i ''video''.mpg -acodec libvorbis -aq 8 -ar 48000 -vcodec mpeg4 \<br />
-pass 2 -vpre vhq -b 3000k ''output''.mp4<br />
<br />
* '''libvorbis quality settings (VBR)'''<br />
:* {{ic|-aq 4}} = 128 kb/s<br />
:* {{ic|-aq 5}} = 160 kb/s<br />
:* {{ic|-aq 6}} = 192 kb/s<br />
:* {{ic|-aq 7}} = 224 kb/s<br />
:* {{ic|-aq 8}} = 256 kb/s<br />
<br />
* [http://www.geocities.jp/aoyoume/aotuv/ aoTuV] is generally preferred over [http://vorbis.com/ libvorbis] provided by [http://www.xiph.org/ Xiph.Org] and is provided by [https://aur.archlinux.org/packages.php?ID=6155 libvorbis-aotuv] in the [[AUR]].<br />
<br />
== Package removal ==<br />
<br />
[[pacman]] will not [[Pacman#Removing_packages|remove]] configuration files outside of the defaults that were created during package installation. This includes user-created preset files.<br />
<br />
== See also ==<br />
<br />
* [http://mewiki.project357.com/wiki/X264_Settings x264 Settings] - MeWiki documentation<br />
* [http://ffmpeg.org/ffmpeg-doc.html FFmpeg documentation] - official documentation<br />
* [http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-x264.html Encoding with the x264 codec] - MEncoder documentation<br />
* [http://avidemux.org/admWiki/doku.php?id=tutorial:h.264 H.264 encoding guide] - Avidemux wiki<br />
* [http://howto-pages.org/ffmpeg/ Using FFmpeg] - Linux how to pages<br />
* [http://ffmpeg.org/general.html#Supported-File-Formats-and-Codecs List] of supported audio and video streams</div>Blueriderhttps://wiki.archlinux.org/index.php?title=FFmpeg&diff=270561FFmpeg2013-08-10T02:15:18Z<p>Bluerider: /* Single-pass MPEG-2 (near lossless) */ -sameq is no longer supported</p>
<hr />
<div>[[Category:Audio/Video]]<br />
{{Article summary start}}<br />
{{Article summary text|This article attempts to walk users through the installation, usage and configuration of FFmpeg.}}<br />
{{Article summary end}}<br />
<br />
From the project [http://www.ffmpeg.org/ home page]:<br />
:''FFmpeg is a complete, cross-platform solution to record, convert and stream audio and video. It includes libavcodec - the leading audio/video codec library.''<br />
<br />
== Package installation ==<br />
<br />
[[pacman|Install]] {{Pkg|ffmpeg}} from the [[official repositories]].<br />
<br />
Notable variants are:<br />
* {{AUR|ffmpeg-full}} - This version includes all codecs that due to license constraints are not in the official repositoies version, notably, the Fraunhofer AAC codec and the AAC+ codec.<br />
* {{AUR|libav}} - Replacement fork. The binary it provides is called ''avconv'' instead of ''ffmpeg''.<br />
<br />
== Encoding examples ==<br />
<br />
=== Screen cast to .webm ===<br />
<br />
Using ''x11grab'' to video grab your display and using ''ALSA'' for sound. First we create lossless raw file {{ic|test.mkv}}.<br />
<br />
$ ffmpeg -f x11grab -r 30 -i :0.0 -f alsa -i hw:0,0 -acodec flac -vcodec ffvhuff test.mkv<br />
<br />
Then we process this {{ic|test.mkv}} file into a smaller {{ic|test.webm}} end product. Complex switches like {{ic|c:a}} and {{ic|c:v}} convert the stream into what's needed for [http://en.wikipedia.org/wiki/WebM WebM].<br />
<br />
$ ffmpeg -y -i test.mkv -c:a libvorbis -q:a 3 -c:v libvpx -b:v 2000k test.webm<br />
<br />
See https://github.com/kaihendry/recordmydesktop2.0/ for a more fleshed out example.<br />
<br />
=== Recording webcam ===<br />
<br />
FFmpeg supports grabbing input from Video4Linux2 devices. The following command will record a video from the webcam, assuming that the webcam is correctly recognized under {{ic|/dev/video0}}:<br />
<br />
$ ffmpeg -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
The above produces a silent video. It is also possible to include audio sources from a microphone. The following command will include a stream from the default [[Advanced Linux Sound Architecture|ALSA]] recording device into the video:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
To use [[PulseAudio]] with an ALSA backend:<br />
<br />
$ ffmpeg -f alsa -i pulse -f v4l2 -s 640x480 -i /dev/video0 ''output''.mpg<br />
<br />
For a higher quality capture, try encoding the output using higher quality codecs:<br />
<br />
$ ffmpeg -f alsa -i default -f v4l2 -s 640x480 -i /dev/video0 -acodec flac \<br />
-vcodec libx264 ''output''.mkv<br />
<br />
=== VOB to any container ===<br />
<br />
Concatenate the desired [[Wikipedia:VOB|VOB]] files into a single VOB file: <br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB<br />
Concatenate and then pipe the output VOB to FFmpeg to use a different format:<br />
$ cat ''video-1''.VOB ''video-2''.VOB ''video-3''.VOB > ''output''.VOB | ffmpeg -i ...<br />
<br />
=== x264 lossless ===<br />
<br />
The ''ultrafast'' preset will provide the fastest encoding and is useful for quick capturing (such as screencasting):<br />
$ ffmpeg -i input -vcodec libx264 -preset ultrafast -qp 0 -acodec copy ''output.mkv''<br />
On the opposite end of the preset spectrum is ''veryslow'' and will encode slower than ''ultrafast'' but provide a smaller output file size:<br />
$ ffmpeg -i input -vcodec libx264 -preset veryslow -qp 0 -acodec copy ''output.mkv''<br />
Both examples will provide the same quality output.<br />
<br />
=== Single-pass MPEG-2 (near lossless) ===<br />
<br />
Allow FFmpeg to automatically set DVD standardized parameters. Encode to DVD [[Wikipedia:MPEG-2|MPEG-2]] at a frame rate of 30 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target ntsc-dvd -sameq ''output''.mpg<br />
<br />
Encode to DVD MPEG-2 at a frame rate of 24 frames/second:<br />
<br />
$ ffmpeg -i ''video''.VOB -target film-dvd -qscale 0''output''.mpg<br />
<br />
=== x264: constant rate factor ===<br />
<br />
Used when you want a specific quality output. General usage is to use the highest {{ic|-crf}} value that still provides an acceptable quality. A sane range is 18-28 and 23 is default. 18 is considered to be visually lossless. Use the slowest {{ic|-preset}} you have patience for. See the [https://ffmpeg.org/trac/ffmpeg/wiki/x264EncodingGuide x264 Encoding Guide] for more information.<br />
$ ffmpeg -i ''video'' -vcodec libx264 -preset slow -crf 22 -acodec libmp3lame -aq 4 ''output''.mkv<br />
{{ic|-tune}} option can be used to [http://forum.doom9.org/showthread.php?t=149394 match the type and content of the of media being encoded].<br />
<br />
=== YouTube ===<br />
<br />
FFmpeg is very useful to encode videos and strip their size before you upload them on YouTube. The following single line of code takes an input file and outputs a mkv container. <br />
<br />
$ ffmpeg -i ''video'' -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy ''output''.mkv<br />
<br />
For more information see the [https://bbs.archlinux.org/viewtopic.php?pid=1200667#p1200667 forums]. You can also create a custom alias {{ic|ytconvert}} which takes the name of the input file as first argument and the name of the .mkv container as second argument. To do so add the following to your {{ic|~/.bashrc}}:<br />
<br />
{{bc|<nowiki><br />
youtubeConvert(){<br />
ffmpeg -i $1 -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -c:a copy $2.mkv<br />
}<br />
alias ytconvert=youtubeConvert<br />
</nowiki>}}<br />
See also [https://bbs.archlinux.org/viewtopic.php?pid=1200542#p1200542 Arch Linux forum thread].<br />
<br />
=== Two-pass x264 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are recorded during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec libx264 -pass 1 -preset veryslow \<br />
-threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 -f rawvideo -y /dev/null<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.mkv}}):<br />
$ ffmpeg -i ''video''.VOB -acodec libvo-aacenc -ab 256k -ar 96000 -vcodec libx264 \<br />
-pass 2 -preset veryslow -threads 0 -b 3000k -x264opts frameref=15:fast_pskip=0 ''video''.mkv<br />
<br />
{{Tip|If you receive {{ic|Unknown encoder 'libvo-aacenc'}} error (given the fact that your ffmpeg is compiled with libvo-aacenc enabled), you may want to try {{ic|-acodec libvo_aacenc}}, an underscore instead of hyphen.}}<br />
<br />
=== Two-pass MPEG-4 (very high-quality) ===<br />
<br />
Audio deactivated as only video statistics are logged during the first of multiple pass runs: <br />
$ ffmpeg -i ''video''.VOB -an -vcodec mpeg4 -pass 1 -mbd 2 -trellis 2 -flags +cbp+mv0 \<br />
-pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 -b 3000k \<br />
-f rawvideo -y /dev/null<br />
<br />
Container format is automatically detected and muxed into from the output file extenstion ({{ic|.avi}}):<br />
$ ffmpeg -i ''video''.VOB -acodec copy -vcodec mpeg4 -vtag DX50 -pass 2 -mbd 2 -trellis 2 \<br />
-flags +cbp+mv0 -pre_dia_size 4 -dia_size 4 -precmp 4 -cmp 4 -subcmp 4 -preme 2 -qns 2 \<br />
-b 3000k ''video''.avi<br />
* Introducing {{ic|threads}}={{ic|n}}>{{ic|1}} for {{ic|-vcodec mpeg4}} may skew the effects of [[Wikipedia:Motion_estimation|motion estimation]] and lead to [http://ffmpeg.org/faq.html#Why-do-I-see-a-slight-quality-degradation-with-multithreaded-MPEG_002a-encoding_003f reduced video quality] and compression efficiency.<br />
* The two-pass MPEG-4 example above also supports output to the [[Wikipedia:MPEG-4_Part_14|MP4]] container (replace {{ic|.avi}} with {{ic|.mp4}}).<br />
<br />
==== Determining bitrates with fixed output file sizes ====<br />
<br />
* (Desired File Size in MB - Audio File Size in MB) '''x''' 8192 kb/MB '''/''' Length of Media in Seconds (s) '''=''' [[Wikipedia:Bitrate|Bitrate]] in kb/s<br />
:* (3900 MB - 275 MB) = 3625 MB '''x''' 8192 kb/MB '''/''' 8830 s = 3363 kb/s required to achieve an approximate total output file size of 3900 MB<br />
<br />
=== Adding subtitles ===<br />
<br />
See http://trac.ffmpeg.org/wiki/How%20to%20burn%20subtitles%20into%20the%20video<br />
<br />
==== Softsubs to hardsubs ====<br />
<br />
If have a softsubbed video (eg. ASS/SSA subs in a mkv container like most anime) you can 'burn' these subs into a new file to be played on a device which does not support subs or is to weak to display complex subs.<br />
<br />
* Install {{Pkg|mkvtoolnix-cli}} to pull out {{ic|.ass}} files from {{ic|.mkv}} files.<br />
<br />
* Recompile FFmpeg with {{ic|--enable-libass}} if it is not already enabled in your FFmpeg build. See [[ABS]] for easy recompiling.<br />
<br />
* Pull out subs from your file. This command assumes that track #2 is the ASS/SSA track. Use {{ic|mkvinfo}} if it is not.<br />
$ mkvextract tracks ''your file''.mkv 2:''your file''.ass<br />
<br />
* Recode file with ffmpeg. See sections above for suitable options. It is very important to disable sub-recording and enable sub-rendering:<br />
$ ffmpeg ... -sn -vf ass=''subtitles''.ass<br />
<br />
Output is set as *.mp4 since the default Android 4.2 player dislikes *.mkv. (But VLC on Android works with mkv). Example:<br />
$ ffmpeg -i ''video''.mkv -sn -vcodec libx264 -crf 18 -preset slow -vf ass=''subtitles''.ass -acodec copy ''output''.mp4<br />
<br />
=== Volume gain ===<br />
<br />
Change the audio volume in multiples of 256 where '''256 = 100%''' (normal) volume. Additional values such as 400 are also valid options. <br />
-vol 256 = 100%<br />
-vol 512 = 200%<br />
-vol 768 = 300%<br />
-vol 1024 = 400%<br />
-vol 2048 = 800%<br />
<br />
To double the volume '''(512 = 200%)''' of an [[Wikipedia:Mp3|MP3]] file:<br />
$ ffmpeg -i ''file''.mp3 -vol 512 ''louder file''.mp3<br />
<br />
To quadruple the volume '''(1024 = 400%)''' of an [[Wikipedia:Ogg|Ogg]] file:<br />
$ ffmpeg -i ''file''.ogg -vol 1024 ''louder file''.ogg<br />
<br />
Note that gain metadata is only written to the output file. Unlike mp3gain or ogggain, the source sound file is untouched.<br />
<br />
=== Extracting audio ===<br />
<br />
{{hc|$ ffmpeg -i ''video''.mpg|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: ac3, 48000 Hz, stereo, s16, 384 kb/s<br />
Stream #0.2: Audio: ac3, 48000 Hz, 5.1, s16, 448 kb/s<br />
Stream #0.3: Audio: dts, 48000 Hz, 5.1 768 kb/s<br />
...<br />
}}<br />
<br />
Extract the first ({{ic|-map 0:1}}) [[Wikipedia:Dolby_Digital|AC-3]] encoded audio stream exactly as it was multiplexed into the file: <br />
$ ffmpeg -i ''video''.mpg -map 0:1 -acodec copy -vn ''video''.ac3<br />
Convert the third ({{ic|-map 0:3}}) [[Wikipedia:DTS_(sound_system)|DTS]] audio stream to an [[Wikipedia:Advanced_Audio_Coding|AAC]] file with a bitrate of 192 kb/s and a [[Wikipedia:Sampling_rate|sampling rate]] of 96000 Hz:<br />
$ ffmpeg -i ''video''.mpg -map 0:3 -acodec libvo-aacenc -ab 192k -ar 96000 -vn ''output''.aac<br />
{{ic|-vn}} disables the processing of the video stream.<br />
<br />
Extract audio stream with certain time interval: <br />
$ ffmpeg -ss 00:01:25 -t 00:00:05 -i ''video''.mpg -map 0:1 -acodec copy -vn ''output''.ac3<br />
{{ic|-ss}} specifies the start point, and {{ic|-t}} specifies the duration.<br />
<br />
=== Stripping audio ===<br />
<br />
# Copy the first video stream ({{ic|-map 0:0}}) along with the second AC-3 audio stream ({{ic|-map 0:2}}).<br />
# Convert the AC-3 audio stream to two-channel MP3 with a bitrate of 128 kb/s and a sampling rate of 48000 Hz.<br />
$ ffmpeg -i ''video''.mpg -map 0:0 -map 0:2 -vcodec copy -acodec libmp3lame \<br />
-ab 128k -ar 48000 -ac 2 ''video''.mkv<br />
<br />
{{hc|$ ffmpeg -i ''video''.mkv|<br />
...<br />
Input #0, avi, from '''video''.mpg':<br />
Duration: 01:58:28.96, start: 0.000000, bitrate: 3000 kb/s<br />
Stream #0.0: Video: mpeg4, yuv420p, 720x480 [PAR 1:1 DAR 16:9], 29.97 tbr, 29.97 tbn, 29.97 tbc<br />
Stream #0.1: Audio: mp3, 48000 Hz, stereo, s16, 128 kb/s<br />
}}<br />
<br />
{{Note|Removing undesired audio streams allows for additional bits to be allocated towards improving video quality.}}<br />
<br />
== Preset files ==<br />
<br />
Populate {{ic|~/.ffmpeg}} with the default [http://ffmpeg.org/ffmpeg-doc.html#SEC13 preset files]: <br />
<br />
$ cp -iR /usr/share/ffmpeg ~/.ffmpeg<br />
<br />
Create new and/or modify the default preset files:<br />
<br />
{{hc|~/.ffmpeg/libavcodec-vhq.ffpreset|2=<br />
vtag=DX50<br />
mbd=2<br />
trellis=2<br />
flags=+cbp+mv0<br />
pre_dia_size=4<br />
dia_size=4<br />
precmp=4<br />
cmp=4<br />
subcmp=4<br />
preme=2<br />
qns=2<br />
}}<br />
<br />
=== Using preset files ===<br />
<br />
Enable the {{ic|-vpre}} option after declaring the desired {{ic|-vcodec}}<br />
<br />
==== libavcodec-vhq.ffpreset ====<br />
<br />
* {{ic|libavcodec}} '''=''' Name of the vcodec/acodec<br />
* {{ic|vhq}} '''=''' Name of specific preset to be called out<br />
* {{ic|ffpreset}} '''=''' FFmpeg preset filetype suffix <br />
<br />
===== Two-pass MPEG-4 (very high quality) =====<br />
<br />
First pass of a multipass (bitrate) ratecontrol transcode:<br />
$ ffmpeg -i ''video''.mpg -an -vcodec mpeg4 -pass 1 -vpre vhq -f rawvideo -y /dev/null<br />
Ratecontrol based on the video statistics logged from the first pass: <br />
$ ffmpeg -i ''video''.mpg -acodec libvorbis -aq 8 -ar 48000 -vcodec mpeg4 \<br />
-pass 2 -vpre vhq -b 3000k ''output''.mp4<br />
<br />
* '''libvorbis quality settings (VBR)'''<br />
:* {{ic|-aq 4}} = 128 kb/s<br />
:* {{ic|-aq 5}} = 160 kb/s<br />
:* {{ic|-aq 6}} = 192 kb/s<br />
:* {{ic|-aq 7}} = 224 kb/s<br />
:* {{ic|-aq 8}} = 256 kb/s<br />
<br />
* [http://www.geocities.jp/aoyoume/aotuv/ aoTuV] is generally preferred over [http://vorbis.com/ libvorbis] provided by [http://www.xiph.org/ Xiph.Org] and is provided by [https://aur.archlinux.org/packages.php?ID=6155 libvorbis-aotuv] in the [[AUR]].<br />
<br />
== Package removal ==<br />
<br />
[[pacman]] will not [[Pacman#Removing_packages|remove]] configuration files outside of the defaults that were created during package installation. This includes user-created preset files.<br />
<br />
== See also ==<br />
<br />
* [http://mewiki.project357.com/wiki/X264_Settings x264 Settings] - MeWiki documentation<br />
* [http://ffmpeg.org/ffmpeg-doc.html FFmpeg documentation] - official documentation<br />
* [http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-x264.html Encoding with the x264 codec] - MEncoder documentation<br />
* [http://avidemux.org/admWiki/doku.php?id=tutorial:h.264 H.264 encoding guide] - Avidemux wiki<br />
* [http://howto-pages.org/ffmpeg/ Using FFmpeg] - Linux how to pages<br />
* [http://ffmpeg.org/general.html#Supported-File-Formats-and-Codecs List] of supported audio and video streams</div>Blueriderhttps://wiki.archlinux.org/index.php?title=GNOME&diff=270439GNOME2013-08-09T02:40:57Z<p>Bluerider: /* Default web browser */</p>
<hr />
<div>[[Category:GNOME| ]]<br />
[[cs:GNOME]]<br />
[[de:GNOME]]<br />
[[es:GNOME]]<br />
[[fr:GNOME]]<br />
[[it:GNOME]]<br />
[[ja:GNOME]]<br />
[[nl:GNOME]]<br />
[[pl:GNOME]]<br />
[[pt:GNOME]]<br />
[[ru:GNOME]]<br />
[[sr:GNOME]]<br />
[[th:GNOME]]<br />
[[tr:Gnome_Masaüstü_Ortamı]]<br />
[[uk:GNOME]]<br />
[[zh-CN:GNOME]]<br />
[[zh-TW:GNOME]]<br />
{{Article summary start}}<br />
{{Article summary text|GNOME 3 provides a modern desktop, rewritten from scratch, using the GTK3+ toolkit.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Graphical user interface overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|GTK+}}<br />
{{Article summary wiki|GDM}}<br />
{{Article summary wiki|Nautilus}}<br />
{{Article summary end}}<br />
<br />
From [http://www.gnome.org/about/ About Us | GNOME]:<br />
<br />
:''The GNOME Project was started in 1997 by two then university students, Miguel de Icaza and Federico Mena. Their aim: to produce a free (as in freedom) [[desktop environment]]. Since then, GNOME has grown into a hugely successful enterprise. Used by millions of people across the world, it is the most popular desktop environment for GNU/Linux and UNIX-type operating systems. The desktop has been utilised in successful, large-scale enterprise and public deployments, and the project’s developer technologies are utilised in a large number of popular mobile devices.''<br />
<br />
== Introduction ==<br />
<br />
GNOME 3 has ''two'' interfaces:<br />
<br />
*'''GNOME Shell''' is the new standard layout using the Mutter window manager. It acts as a composite manager for the desktop, employing hardware graphics acceleration to provide effects aimed at reducing screen clutter.<br />
<br />
*'''Classic mode''' is the successor of the discontinued "fallback mode" starting with GNOME 3.8. It aims at implementing a more traditional desktop interface while using standard GNOME 3 technologies (including graphic acceleration). It does so through the use of pre-activated extensions and parameters (see [http://worldofgnome.org/welcome-to-gnome-3-8-flintstones-mode/ here] for a list) and relies on llvmpipe for graphic acceleration. Hence it consists more of a customized GNOME Shell than a truly distinct mode.<br />
<br />
GNOME-session automatically detects if your computer is incapable of running GNOME Shell and starts Classic mode with llvmpipe when appropriate.<br />
<br />
==Installation==<br />
<br />
GNOME 3 is available in the [[official repositories]] and can be [[pacman|installed]] with two groups of packages:<br />
*{{Grp|gnome}} contains the core desktop environment and applications required for the standard GNOME experience.<br />
<br />
*{{Grp|gnome-extra}} contains various optional tools such as a media player, a calculator, an editor and other non-critical applications that go well with the GNOME desktop. Installing this group is optional.<br />
<br />
Note that installing only {{Grp|gnome-extra}} will not pull the whole {{Grp|gnome}} group by dependencies: if you really want everything you must explicitly install both groups.<br />
<br />
=== Starting GNOME ===<br />
<br />
'''Graphical log-in'''<br />
<br />
For the best desktop integration, login manager '''GDM''' is recommended. Other login managers can be used in place of GDM. Check out the [[Display_Manager|wiki article on display managers]] to learn how desktop environments are started.<br />
<br />
The login manager is a limited process entrusted with duties that impact the system. The [[PolicyKit|PolicyKit wiki article]] addresses the topic of system‑wide access control.<br />
<br />
{{Tip|Refer to the [[GDM]] article for installation and configuration instructions.}}<br />
<br />
'''Starting GNOME manually'''<br />
<br />
If you prefer to start GNOME manually from the console, add the following line to your {{ic|~/.xinitrc}} file:<br />
{{hc|~/.xinitrc|<nowiki><br />
exec gnome-session<br />
</nowiki>}}<br />
<br />
After the {{ic|exec}} command is placed, GNOME can be launched by typing {{ic|startx}}.<br />
<br />
See [[xinitrc]] for details, such as preserving the logind session.<br />
<br />
== Using the shell ==<br />
<br />
=== GNOME cheat sheet ===<br />
<br />
The GNOME web site has a helpful [https://live.gnome.org/GnomeShell/CheatSheet GNOME Shell cheat sheet] explaining task switching, keyboard use, window control, the panel, overview mode, and more.<br />
<br />
=== Restarting the shell ===<br />
<br />
After appearance tweaks you are often asked to restart the GNOME shell. You could log out and log back in, but it is simpler and faster to issue the following keyboard command. Restart the shell by pressing {{Keypress|Alt}} + {{Keypress|F2}} then {{Keypress|r}} then {{Keypress|Enter}}<br />
<br />
=== Shell crashes ===<br />
<br />
Certain tweaks and/or repeated shell restarts may cause the shell to crash when a restart is attempted. In this case, you are informed about the crash and then forced to log out. Some shell changes, such as switching between '''''GNOME Shell''''' and '''''fallback mode,''''' cannot be accomplished via a keyboard restart; you must log out and log back in to effect them.<br />
<br />
It is common sense — but worth repeating — that valuable documents should be saved (and perhaps closed) before attempting a shell restart. It is not strictly necessary; open windows and documents usually remain intact after a shell restart.<br />
<br />
=== Shell freezes ===<br />
<br />
Sometimes shell extensions freeze the GNOME Shell. In this case a possible strategy is to switch to another terminal via {{Keypress|Ctrl+Alt+F2}} through {{Keypress|Ctrl+Alt+F6}}, log in, and restart gnome-shell with:<br />
<br />
# pkill -HUP gnome-shell<br />
<br />
All open applications will still be available after restarting the shell.<br />
<br />
Sometimes, however, merely restarting the shell might not be enough. Then you will have to restart X, losing all work in progress. You can restart X by:<br />
<br />
# pkill X<br />
<br />
The GNOME Shell then restarts automatically.<br />
<br />
If this doesn't work, you can try to restart your login manager. For instance, if you use GDM, try:<br />
<br />
# systemctl restart gdm.service<br />
<br />
{{Tip|You can also use '''htop''' in tty; press ''t'', select the ''gnome-shell'' tree, press ''k'' and send ''SIGKILL''.}}<br />
<br />
== Customizing GNOME appearance ==<br />
<br />
=== Overall appearance ===<br />
<br />
GNOME 3 may have "started from scratch", but like most large software projects it is assembled from parts dating to different eras. There is not '''one''' all-encompassing configuration tool. The new ''Systems Settings'' tool is a big improvement over previous control panels. ''System Settings'' is well-organized, but you may find yourself wishing for more control over system appearance.<br />
<br />
You may be familiar with existing configuration tools: some of these still work; many will not. Some settings are not readily exposed for you to change. Indubitably, many settings will migrate to newer tools and/or become exposed as time progresses and the wider community embraces and extends the latest GNOME desktop.<br />
<br />
==== Gsettings ====<br />
<br />
A new command-line tool {{ic|gsettings}} stores data in a binary format, unlike previous tools using XML text. A tutorial [http://blog.fpmurphy.com/2011/03/customizing-the-gnome-3-shell.html Customizing the GNOME Shell] explores the power of gsettings.<br />
<br />
==== GNOME tweak tool ====<br />
<br />
This graphical tool customizes fonts, themes, titlebar buttons and other settings. {{Pkg|gnome-tweak-tool}} is available from the [[official repositories]].<br />
<br />
==== GTK3 theme via settings.ini ====<br />
<br />
It is possible to set a GTK3 theme via {{ic|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini}} (usually {{ic|~/.config/gtk-3.0/settings.ini}}).<br />
<br />
''Adwaita,'' the default GNOME 3 theme, is a part of {{pkg|gnome-themes-standard}}. Additional GTK3 themes can be found at [http://browse.deviantart.com/customization/skins/linuxutil/desktopenv/gnome/gtk3/ Deviantart web site.] For example:<br />
{{hc|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini|<nowiki><br />
[Settings]<br />
gtk-theme-name = Adwaita<br />
gtk-fallback-icon-theme = gnome<br />
# next option is applicable only if selected theme supports it<br />
gtk-application-prefer-dark-theme = true<br />
# set font name and dimension<br />
gtk-font-name = Sans 10<br />
</nowiki>}}<br />
<br />
It is necessary to [[#Restarting the shell|restart the GNOME shell]] for settings to be applied. More GTK options are found at [http://developer.gnome.org/gtk3/3.0/GtkSettings.html#GtkSettings.properties GNOME developer documentation.]<br />
<br />
==== Icon theme ====<br />
<br />
Using {{pkg|gnome-tweak-tool}} version 3.0.3 and later, you can place any icon theme you wish to use inside {{ic|~/.icons}}.<br />
<br />
Usefully, GNOME 3 is compatible with GNOME 2 icon themes, which means you are not stuck with the default icons. To install a new set of icons, copy your desired icon theme's directory to {{ic|~/.icons}}. As an example:<br />
<br />
$ cp -R /home/user/Desktop/my_icon_theme ~/.icons<br />
<br />
The new theme ''my_icon_theme'' is now selectable using {{ic|gnome-tweak-tool}} under ''interface''.<br />
<br />
Alternatively, you may textually select your icon theme with no need for gnome-tweak-tool. Add the GTK icon theme name to {{ic|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini}}. Please note, not to use "" as your settings would not be recognised then.<br />
<br />
{{hc|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini|<nowiki>... previous lines ...<br />
<br />
gtk-icon-theme-name = my_new_icon_theme</nowiki>}}<br />
<br />
=== Nautilus ===<br />
<br />
''See [[Nautilus]].''<br />
<br />
=== Totem ===<br />
<br />
To play back h.264 videos, you need to install {{Pkg|gst-libav}}<br />
<br />
For more information on gstreamer hardware acceleration, see [[GStreamer#Hardware_Acceleration|Gstreamer: Hardware Acceleration]].<br />
<br />
=== GNOME panel ===<br />
<br />
==== Show date in top bar ====<br />
<br />
By default GNOME displays only the weekday and time in the top bar. This can be changed with the following command. Changes take effect immediately. <br />
<br />
GNOME 3.4.2:<br />
# gsettings set org.gnome.shell.clock show-date true<br />
<br />
GNOME 3.6.2:<br />
# gsettings set org.gnome.desktop.interface clock-show-date true<br />
<br />
==== Always show the "Log Out" entry in the user menu ====<br />
<br />
Since GNOME 3.6, the "Log Out" entry in the user menu is only shown when multiple non-root users are present in the system.<br />
<br />
To always enable this entry, run the following command from a terminal:<br />
<br />
# gsettings set org.gnome.shell always-show-log-out true<br />
<br />
You can also change this in dconf-editor: Navigate to org.gnome.shell, then check the "always-show-log-out" checkbox.<br />
<br />
Then, restart the GNOME shell:<br />
#{{Keypress|Alt+F2}}<br />
#{{Keypress|r}}<br />
#{{Keypress|Enter}}<br />
<br />
==== Hiding icons in the top bar ====<br />
<br />
When doing a GNOME install, some unwanted icons might appear in the panel. These icons can be removed either with GNOME shell extensions or by manually editing the GNOME panel script.<br />
<br />
===== Hiding icons with shell extensions =====<br />
<br />
To remove the accessibility icon, one can use the https://extensions.gnome.org/extension/112/remove-accesibility/. <br />
<br />
The best way to use extensions is installing them from the gnome extensions web page like the one above.<br />
<br />
===== Manually editing the GNOME panel script =====<br />
<br />
For example, to remove the '''universal access icon''', comment out the 'a11y' line in PANEL_ITEM_IMPLEMENTATIONS:<br />
<br />
{{hc|/usr/share/gnome-shell/js/ui/panel.js|<nowiki><br />
const PANEL_ITEM_IMPLEMENTATIONS = {<br />
'activities': ActivitiesButton,<br />
'appMenu': AppMenuButton,<br />
'dateMenu': imports.ui.dateMenu.DateMenuButton,<br />
// 'a11y': imports.ui.status.accessibility.ATIndicator,<br />
'volume': imports.ui.status.volume.Indicator,<br />
'battery': imports.ui.status.power.Indicator,<br />
'lockScreen': imports.ui.status.lockScreenMenu.Indicator,<br />
'keyboard': imports.ui.status.keyboard.InputSourceIndicator,<br />
'powerMenu': imports.gdm.powerMenu.PowerMenuButton,<br />
'userMenu': imports.ui.userMenu.UserMenuButton<br />
};<br />
</nowiki>}}<br />
<br />
Then, save your results and restart the shell:<br />
<br />
#{{Keypress|Alt+F2}}<br />
#{{Keypress|r}}<br />
#{{Keypress|Enter}}<br />
<br />
==== Show battery icon ====<br />
<br />
To show the battery tray icon, [[pacman|install]] {{Pkg|gnome-power-manager}} from the [[Official Repositories|official repositories]].<br />
<br />
==== Disable "Suspend" in the status and gdm menu ====<br />
<br />
A quick way to do it system-wide for GNOME 3.2 is to change line 539 of {{ic|/usr/share/gnome-shell/js/ui/userMenu.js}} and line 103 of {{ic|/usr/share/gnome-shell/js/gdm/powerMenu.js}}. (For GNOME versions prior to 3.2, look at line 153 of {{ic|/usr/share/gnome-shell/js/ui/statusMenu.js}}.) This change takes effect the next time GNOME Shell is started.<br />
<br />
{{hc|/usr/share/gnome-shell/js/ui/userMenu.js|<nowiki><br />
// this._haveSuspend = this._upClient.get_can_suspend(); // Comment this line out.<br />
this._haveSuspend = false; // Use this line instead.<br />
</nowiki>}}<br />
<br />
To accomplish this, paste the following command(s) in your terminal:<br />
GNOME_SHELL=/usr/share/gnome-shell<br />
SCRIPTS=`grep -lr get_can_suspend $GNOME_SHELL/js`<br />
for FILE in $SCRIPTS ; do<br />
sed -r -i -e 's/[^= ]+.get_can_suspend\(\)/false/' "$FILE"<br />
done<br />
<br />
The above change does not persist after a GNOME version update, however. A more perennial solution is to add the code above in some gdm or system startup script (eg: /etc/rc.local), to keep the "suspend" option disabled after updates.<br />
<br />
Alternatively you can install the [[#GNOME shell extensions|GNOME shell extension]] {{ic|alternative status menu}} in package {{Pkg|gnome-shell-extension-alternative-status-menu}}.<br />
<br />
==== Eliminate delay when logging out ====<br />
<br />
The following tweak removes the confirmation dialog and sixty second delay for logging out.<br />
<br />
This dialog normally appears when you log out with the status menu. This tweak affects the '''''Power Off''''' dialog as well. This is not a system-wide change; it affects only the user who enters this command. The change takes effect immediately after entering the command.<br />
<br />
$ gsettings set org.gnome.SessionManager logout-prompt 'false'<br />
<br />
==== Show system monitor ====<br />
<br />
Install the {{AUR|gnome-shell-system-monitor-applet-git}} extension available in the [[AUR]].<br />
<br />
==== Show weather information ====<br />
<br />
Install {{AUR|gnome-shell-extension-weather-git}} from [[AUR]].<br />
<br />
=== Activity view ===<br />
<br />
==== Remove entries from Applications view ====<br />
<br />
Like other desktop environments, GNOME uses .desktop files to populate its Applications view. These text files are in '''{{ic|/usr/share/applications}}'''. It is not possible to edit these files from a folder view ‒ Nautilus does not treat their icons as text files. Use a terminal to display or edit .desktop file entries.<br />
<br />
# ls /usr/share/applications<br />
# nano /usr/share/applications/foo.desktop<br />
<br />
For system wide changes, edit files in '''{{ic|/usr/share/applications}}'''. For local changes, make a copy of ''foo.desktop'' in your home folder.<br />
<br />
$ cp /usr/share/applications/foo.desktop ~/.local/share/applications/<br />
<br />
Edit .desktop files to fit your wishes. <br />
<br />
{{Note|Removing a .desktop file does not uninstall an application, but instead removes its desktop integration: MIME types, shortcuts, and so forth.}}<br />
<br />
The following command appends one line to a .desktop file and hides its associated icon from Applications view:<br />
<br />
$ echo "NoDisplay=true" >> foo.desktop<br />
<br />
==== To Remove Wine Launchers from the Applications menu ====<br />
<br />
Enter {{ic|~/.local/share/applications/wine/Programs/}} and look for the wine application's name. In the directories are the ".desktop" files which configure the launchers. Remove the program directory to easily remove the launchers.<br />
<br />
==== Change application icon size ====<br />
<br />
One awkward selection of the GNOME designers is their choice of large icons for Applications view. This view is painful when working with a small screen containing many large application icons. There is a way to reduce the icon size. It is done by editing the GNOME-Shell theme.<br />
<br />
Edit system files directly (make a backup first) or copy theme files to your local folder and edit these files. <br />
* For the '''default''' theme, edit '''{{ic|/usr/share/gnome-shell/theme/gnome-shell.css}}'''<br />
<br />
* For '''user themes''', edit '''{{ic|/usr/share/themes/<UserTheme>/gnome-shell/gnome-shell.css}}'''<br />
<br />
Edit ''gnome-shell.css'' and replace the following values. Afterward, [[#Restarting_the_shell|restart the GNOME shell.]]<br />
{{hc|gnome-shell.css|<nowiki><br />
...<br />
/* Application Launchers and Grid */<br />
<br />
.icon-grid {<br />
spacing: 18px;<br />
-shell-grid-horizontal-item-size: 82px;<br />
-shell-grid-vertical-item-size: 82px;<br />
}<br />
<br />
.icon-grid .overview-icon {<br />
icon-size: 48px;<br />
}<br />
...<br />
</nowiki>}}<br />
<br />
==== Change dash icon size ====<br />
GNOME's Activities view has a dash on the left hand side, the size of the icons in this dash will scale depending on the amount of icons set to display. The scaling can be manipulated or set to a constant icon size. To do so, edit {{ic|/usr/share/gnome-shell/js/ui/dash.js}}.<br />
<br />
{{hc|dash.js|<nowiki><br />
...<br />
<br />
let iconSizes = [ 16, 22, 24, 32, 48, 64 ];<br />
<br />
...<br />
</nowiki>}}<br />
<br />
==== Change switcher (alt-tab) icon size ====<br />
GNOME comes with a built in task switcher, the size of the icons in this task switcher will scale depending on the amount of icons set to display. The scaling can be manipulated or set to a constant icon size. To do so, edit {{ic|/usr/share/gnome-shell/js/ui/altTab.js}}<br />
<br />
{{hc|altTab.js|<nowiki><br />
...<br />
<br />
const iconSizes = [96, 64, 48, 32, 22];<br />
<br />
...<br />
</nowiki>}}<br />
<br />
==== Change system tray icon size ====<br />
GNOME comes with a built in system tray, visible when the mouse is hovered over the bottom right corner of the screen. The size of the icons in this tray is set to a fixed value of 24. To change this value, edit {{ic|/usr/share/gnome-shell/js/ui/messageTray.js}}<br />
{{hc|messageTray.js|<nowiki><br />
...<br />
<br />
ICON_SIZE: 24,<br />
<br />
...<br />
</nowiki>}}<br />
<br />
==== Disable Activity hot corner hovering ====<br />
<br />
To disable automatic activity view when the hot corner is hovered, edit {{ic|/usr/share/gnome-shell/js/ui/layout.js}} (that was ''panel.js'' in GNOME 3.0.x) :<br />
{{hc|layout.js|<nowiki><br />
this._corner = new Clutter.Rectangle({ name: 'hot-corner',<br />
width: 1,<br />
height: 1,<br />
opacity: 0,<br />
reactive: true });icon-size: 48px;<br />
}<br />
</nowiki>}}<br />
and set {{ic|reactive}} to {{ic|false}}. GNOME Shell needs to be restarted.<br />
<br />
==== Disable Message Tray hovering ====<br />
<br />
The message tray is shown when the mouse hovers at the bottom of the screen for one second. To disable this behavior, comment out the following line in {{ic|/usr/share/gnome-shell/js/ui/messageTray.js}}:<br />
{{hc|messageTray.js|<nowiki><br />
//pointerWatcher.addWatch(TRAY_DWELL_CHECK_INTERVAL, Lang.bind(this, this._checkTrayDwell));<br />
</nowiki>}}<br />
GNOME Shell needs to be restarted. The message tray is still visible in activity view.<br />
<br />
=== Titlebar ===<br />
==== Remove title bar ====<br />
Install [https://extensions.gnome.org/extension/354/maximus/ Maximus] GNOME shell extension.<br />
<br />
It can also have white list / black list of application.<br />
<br />
This extension requires xorg-xprop, install it if you don't have it already.<br />
<br />
{{bc|pacman -S xorg-xprop}}<br />
<br />
More about [[#GNOME shell extensions | GNOME shell extensions]].<br />
<br />
==== Reduce title bar height ====<br />
* ''' global''' - edit {{ic|/usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml}}, search for {{ic|title_vertical_pad}} and and reduce its value to a minimum of {{ic|0}}.<br />
* '''user-only''' - copy {{ic|/usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml}} to {{ic|/home/$USER/.themes/Adwaita/metacity-1/metacity-theme-3.xml}}, search for {{ic|title_vertical_pad}} and reduce its value to a minimum of {{ic|0}}.<br />
<br />
Then [[#Restarting_the_shell|Restart the GNOME shell.]] <br />
<br />
To restore the original values, [[pacman|install]] the package {{Pkg|gnome-themes-standard}} from the [[Official Repositories|official repositories]] or remove {{ic|/home/$USER/.themes/Adwaita/metacity-1/metacity-theme-3.xml}}<br />
<br />
==== Reorder titlebar buttons ====<br />
<br />
At present this setting can be changed through '''dconf-editor.'''<br />
<br />
For example, we move the close and minimize buttons to the left side of the titlebar. Open '''dconf-editor''' and locate the '''''org.gnome.shell.overrides.button_layout''''' key. Change its value to '''{{ic|close,minimize:}}''' (Colon symbol designates the spacer between left side and right side of the titlebar.) Use whichever buttons in whatever order you prefer. You cannot use a button more than once. Also, keep in mind that certain buttons are deprecated. [[#Restarting_the_shell|Restart the shell]] to see your new button arrangement.<br />
<br />
==== Hide titlebar when maximized ====<br />
<br />
# sed -i -r 's|(<frame_geometry name="max")|\1 has_title="false"|' /usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml<br />
<br />
[[#Restarting_the_shell|Restart the GNOME shell.]] After this tweak, you may find it difficult to un-maximize a window when there is no titlebar to grab.<br />
<br />
With suitable keybindings, you should be able to use {{Keypress|Alt+F5}}, {{Keypress|Alt+F10}} or {{Keypress|Alt+Space}} to remedy the situation.<br />
<br />
To prevent {{ic|metacity-theme-3.xml}} from being overwritten each time package {{pkg|gnome-themes-standard}} is upgraded, add its name to {{ic|/etc/pacman.conf}} with {{ic|NoUpgrade}}.<br />
<br />
{{hc|/etc/pacman.conf|<nowiki>... previous lines ...<br />
<br />
# Pacman won't upgrade packages listed in IgnorePkg and members of IgnoreGroup<br />
# IgnorePkg =<br />
# IgnoreGroup =<br />
<br />
NoUpgrade = usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml # Do not add a leading slash to the path<br />
<br />
... more lines ...</nowiki>}}<br />
<br />
To restore original Adwaita theme values, install the {{pkg|gnome-themes-standard}} package.<br />
<br />
=== Login screen ===<br />
{{Merge|GDM|Login managers have their own wiki pages and information should be maintained separately.}}<br />
<br />
==== Login background image ====<br />
<br />
Once session variables have been exported as explained above, you may issue commands to retrieve or set items used by GDM. <br />
<br />
The easiest way to changes all the settings is by launching the Configuration Editor gui with the command<br />
<br />
$ dconf-editor<br />
<br />
The location of each setting is the same as in the command line style of configuration shown below:<br />
<br />
The following is the command-line approach to retrieve or set the file name used for GDM's wallpaper.<br />
{{bc|<nowiki><br />
$ GSETTINGS_BACKEND=dconf gsettings get org.gnome.desktop.background picture-uri<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.background picture-uri 'file:///usr/share/backgrounds/gnome/SundownDunes.jpg'<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.background picture-options 'zoom'<br />
## Possible values: centered, none, scaled, spanned, stretched, wallpaper, zoom</nowiki>}}<br />
{{Note|You must specify a file which user "gdm" has permission to read. GDM cannot read files in your home directory.}}<br />
<br />
An alternative graphical interface to changing themes (gtk3, icons and cursor), the wallpaper and minor other settings of the GDM login screen, you can install {{aur|gdm3setup}} from AUR.<br />
<br />
==== Larger font for login ====<br />
<br />
This tweak enlarges the login font with a scaling factor. It is the same method employed by ''Accessibility Manager'' on the desktop.<br />
<br />
You must [[#Login_screen|export the GDM session variables]] before performing this tweak.<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.interface text-scaling-factor '1.25'<br />
<br />
==== Turning off the sound ====<br />
<br />
This tweak disables the audible feedback heard when the system volume is adjusted (via keyboard) on the login screen. You must first export the GDM session variables.<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.sound event-sounds 'false'<br />
<br />
If the above tweak does not work for you or you are unable to export the GDM session variables, there is always the easiest solution to the "ready sound" problem: mute or lower the sound while in GDM login screen using the media keys (if available) of your keyboard.<br />
<br />
==== Make the power button interactive ====<br />
<br />
The default installation sets the power button to suspend the system. '''''Power off''''' or '''''Show dialog''''' is a better choice. You must first export the GDM session variables as [[#Login_screen|outlined previously.]]<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.settings-daemon.plugins.power button-power 'interactive'<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.settings-daemon.plugins.power button-hibernate 'interactive'<br />
$ gsettings list-recursively org.gnome.settings-daemon.plugins.power<br />
<br />
{{Warning|Please note that the [[Acpid|acpid]] daemon also handle the "power button" an "hibernate button" event. Running both systems at the same time may lead to unexpected behaviour.}}<br />
<br />
==== Prevent suspend when closing the lid ====<br />
<br />
On some systems it happens that your laptop suspends when you are closing the lid despite having set the options ''Laptop lid close action on battery'' and ''Laptop lid close action on AC'' to ''blank''. If this is the case, append the following line to {{ic|/etc/systemd/logind.conf}}:<br />
<br />
HandleLidSwitch=ignore<br />
<br />
==== No reaction on lid close ====<br />
<br />
When configuring the lid close events via [[Systemd#ACPI_power_management]], the settings may seem to have no effect.<br />
If you have an external monitor connected to your laptop, this is default GNOME behaviour. Disconnect the monitor and the settings should work, otherwise your {{ic|/etc/systemd/logind.conf}} may be incorrect.<br />
<br />
==== Change Critical Battery Level Action (for Laptops) ====<br />
<br />
The {{pkg|gnome-power-manager}} gui doesn't have a choice for "do nothing" on laptops at critical battery level. To manually edit this, open the {{pkg|dconf}}-editor -> org -> gnome -> settings-daemon -> plugins -> power. Edit the "critical-battery-action" value to "nothing".<br />
<br />
==== GDM keyboard layout ====<br />
<br />
GDM does not know about your GNOME 3 desktop keyboard settings. To change keyboard settings used by GDM, set your layout using Xorg configuration. Refer to this section of the [[Beginners'_Guide#Non-US_keyboard|Beginner's Guide.]]<br />
<br />
=== Other tips ===<br />
See [[GNOME Tips]].<br />
<br />
== Miscellaneous settings ==<br />
<br />
=== Automatic program launch upon logging in ===<br />
<br />
Specify which programs start automatically after logging in using {{ic|gnome-session-properties}}. This tool is part of the {{Pkg|gnome-session}} package.<br />
<br />
$ gnome-session-properties<br />
<br />
=== Editing applications menu ===<br />
<br />
{{pkg|gnome-menus}} provides ''gmenu-simple-editor'' which can show/hide menu entries.<br />
<br />
{{pkg|alacarte}} provides a more complete menu editor for adding/editing menu entries.<br />
<br />
=== Some 'System Settings' not preserved ===<br />
<br />
GNOME 3 is using [[systemd]] (an init daemon for Linux) with more modern capabilities. Previously GNOME programs were altered to use Arch's init functionalities to gather settings but either the maintenance required to do this or possibly this is because of a transitioning to the new init system (read more about this [https://bbs.archlinux.org/viewtopic.php?pid=1115208#p1115208 here]). Areas that settings will not be preserved are '''Date and Time''' and adding ICC profiles in the '''Color''' menu and possibly others.<br />
<br />
To gain the functionality back, [[systemd]] needs to be installed and the ''gdm.service'' and ''NetworkManager.service'' services need to be enabled.<br />
<br />
=== Inner padding in Gnome Terminal===<br />
To move the terminal output away from the window borders create the stylesheet {{ic|~/.config/gtk-3.0/gtk.css}} with the following setting:<br />
<br />
TerminalScreen {<br />
-VteTerminal-inner-border: 10px 10px 10px 10px;<br />
}<br />
<br />
=== Disable sound effects in Terminal ===<br />
By default the terminal has these annoying sound effects when e.g. pushing the tab button on your keyboard. One solution is to turn off or mute all sound effects in the settings menu of Gnome. However, this will also turn off notification sounds in other application such as Skype. A better solution is to open a terminal, go to Edit -> Profile Preferences -> General and untick '''Terminal bell'''.<br />
<br />
=== Disable blinking cursor in Terminal ===<br />
Since Gnome 3.8 and dconf the key required to modify in order to disable the blinking cursor in the Terminal differs slightly in contrast to the old gconf key. To disable the blinking cursor in Gnome 3.8 use:<br />
<br />
gsettings set org.gnome.desktop.interface cursor-blink false<br />
<br />
=== Make new tabs inherit current directory inn Gnome Terminal (3.8+) ===<br />
In Gnome 3.8, the behaviour of how current directories are tracked has changed. To restore this behaviour, you need to put this in your {{ic|.bashrc}}:<br />
<br />
export PS1='\[$(__vte_ps1)\]'$PS1<br />
<br />
or, for zsh users<br />
<br />
chpwd_functions+=(__vte_ps1)<br />
<br />
=== Move dialog windows ===<br />
The default configuration for dialogs will not allow you to move them which causes problems in some cases. To change this you will need to use gconf-editor and change this setting:<br />
<br />
/desktop/gnome/shell/windows/attach_modal_dialogs<br />
<br />
After the change you will need to restart the shell for it to take affect.<br />
<br />
=== Show context menu icons ===<br />
Some programs do have context menu icons which, however, are disabled by default to show up in Gnome. In order to show them set {{ic| org.gnome.desktop.interface menus-have-icons}} to true.<br />
<br />
=== GNOME shell extensions ===<br />
<br />
GNOME Shell can be customized with extensions. These provide features such as a dock or a widget for changing the theme.<br />
<br />
Many extensions are collected and hosted by [https://extensions.gnome.org/ extensions.gnome.org]. They can be browsed and installed simply activating them in the browser. More information about gnome shell extensions can be found [https://extensions.gnome.org/about/ here].<br />
<br />
See [[#When_an_extension_breaks_GNOME|when an extension breaks GNOME]] for troubleshooting information.<br />
<br />
=== Default file browser/replace Nautilus ===<br />
<br />
You can trick GNOME into using another file browser by editing the {{ic|Exec}} line in {{ic|/usr/share/applications/nautilus.desktop}}. See the correct parameters in the {{ic|.desktop}} file of the file manager of your choice, e.g.:<br />
{{hc|/usr/share/applications/nautilus.desktop|<br />
2=[...]<br />
Exec=thunar %F<br />
OR<br />
Exec=pcmanfm %U<br />
OR<br />
Exec=nemo %U<br />
[...]<br />
}}<br />
<br />
=== Default PDF viewer ===<br />
In some cases when you have installed Inkscape or other graphic programs Evince Document Viewer might no longer be selected as the default PDF application. If it is not available in the '''Open With''' entry which would be the GUI solution, you can use the following user command to make it the default application again.<br />
<br />
xdg-mime default evince.desktop application/pdf<br />
<br />
=== Default terminal ===<br />
<br />
{{ic|gsettings}} (which replaces {{ic|gconftool-2}}) is used to set the default terminal. The setting affects ''nautilus-open-terminal'' (a Nautilus extension).<br />
To make [[rxvt-unicode|urxvt]] the default, run:<br />
<br />
gsettings set org.gnome.desktop.default-applications.terminal exec urxvtc<br />
gsettings set org.gnome.desktop.default-applications.terminal exec-arg "'-e'"<br />
<br />
{{Note|The {{ic|-e}} flag is for executing a command. When ''nautilus-open-terminal'' invokes {{ic|urxvtc}}, it puts a {{ic|cd}} command at the end of the command line so that the new terminal starts in the directory you opened it from. Other terminals will require a different (perhaps empty) {{ic|exec-arg}}.}}<br />
<br />
=== Default Applications ===<br />
<br />
While one can right click any file and set the default applications in 'Preferences', the settings are actually saved in {{ic | $HOME/.local/share/applications/mimeapps.list}} and {{ic| $HOME/.local/share/applications/mimeinfo.cache}}<br />
<br />
=== Default web browser ===<br />
<br />
To configure the web browser used by the AUR package {{AUR|gnome-gmail-notifier}}, open gconf-editor<br />
and edit the {{ic|/desktop/gnome/url-handlers/http/}} key. You may want to change {{ic|https/}}, {{ic|about/}}, and {{ic|unknown/}} keys while you are at it.<br />
<br />
=== Middle mouse button ===<br />
<br />
By default, GNOME 3 disables middle mouse button emulation regardless of [[Xorg]] settings ('''Emulate3Buttons'''). To enable middle mouse button emulation use:<br />
<br />
$ gsettings set org.gnome.settings-daemon.peripherals.mouse middle-button-enabled true<br />
<br />
=== Natural scrolling touchpad ===<br />
<br />
GNOME 3 can be configured to use "natural" two finger scrolling, similar to that used in [http://www.apple.com/au/osx/what-is/gestures.html#gallery-gestures-scroll Mac OSX].<br />
<br />
Go to '''System Settings''' ({{ic|gnome-control-center}}) -> '''Mouse & Touchpad''' and set both '''Two finger scroll''' and '''Content sticks to fingers''' to {{ic|ON}}.<br />
<br />
You can alternatively configure the touchpad from a terminal with {{ic|gsettings}}:<br />
<br />
$ gsettings set org.gnome.settings-daemon.peripherals.touchpad horiz-scroll-enabled true<br />
$ gsettings set org.gnome.settings-daemon.peripherals.touchpad scroll-method two-finger-scrolling<br />
$ gsettings set org.gnome.settings-daemon.peripherals.touchpad natural-scroll true<br />
<br />
=== Display dimming ===<br />
<br />
By default GNOME 3 has a ten second idle timeout to dim the screen regardless of the battery and AC state:<br />
<br />
gsettings get org.gnome.settings-daemon.plugins.power idle-dim-time<br />
<br />
To set a new value type the following<br />
<br />
gsettings set org.gnome.settings-daemon.plugins.power idle-dim-time <int><br />
<br />
where <int> is the value in seconds<br />
<br />
=== Alternate window manager ===<br />
<br />
You can use an alternate window manager with GNOME by [[#Enabling_fallback_mode|forcing fallback mode]] and creating two files:<br />
<br />
{{Note|Xmonad is used as an example, but this works for other window managers.}}<br />
<br />
{{hc|/usr/share/gnome-session/sessions/xmonad.session|<nowiki>[GNOME Session]<br />
Name=Xmonad session<br />
RequiredComponents=gnome-panel;gnome-settings-daemon;<br />
RequiredProviders=windowmanager;notifications;<br />
DefaultProvider-windowmanager=xmonad<br />
DefaultProvider-notifications=notification-daemon</nowiki>}}<br />
<br />
{{hc|/usr/share/xsessions/xmonad-gnome-session.desktop|<nowiki>[Desktop Entry]<br />
Name=Xmonad GNOME<br />
Comment=Tiling window manager<br />
TryExec=/usr/bin/gnome-session<br />
Exec=gnome-session --session=xmonad<br />
Type=XSession</nowiki>}}<br />
<br />
The next time you log in, you should have the ability to choose ''Xmonad GNOME'' as your session.<br />
<br />
If there isn't a .desktop file for the window manager, you'll need to create one. Example for [[wmii]]:<br />
<br />
{{hc|/usr/share/applications/wmii.desktop|<nowiki><br />
[Desktop Entry]<br />
Version=1.0<br />
Type=Application<br />
Name=wmii<br />
TryExec=wmii<br />
Exec=wmii</nowiki>}}<br />
<br />
For more information, see [http://makandra.com/notes/1367-running-the-awesome-window-manager-within-gnome this article on running awesome as the window manager in GNOME].<br />
<br />
== Hidden features ==<br />
<br />
GNOME 3 hides many useful options which you can customize with '''dconf-editor.''' GNOME 3 also supports '''gconf-editor''' for settings that have not yet migrated to dconf.<br />
<br />
=== Changing hotkeys ===<br />
Certain hotkeys cannot be changed directly via Settings -> Keyboard -> Shortcuts. In order to change these keys, use dconf-editor. An example of particular note is the hotkey Alt-Above_Tab. On US keyboards, this is Alt-`: is a hotkey often used in the [[Emacs]] editor. It can be changed by opening dconf-editor and modifying the ''switch-group'' key found in {{ic|org.gnome.desktop.wm.keybindings}}.<br />
<br />
It is possible to manually change the keys via an application's so-called accel map file. Where it is to be found is up to the application: For instance, Thunar's is at ~/.config/Thunar/accels.scm, whereas Nautilus's is located at ~/.config/nautilus/accels and ~/.gnome2/accels/nautilus on old release.<br />
<br />
The file should contain a list of possible hotkeys, each unchanged line commented out with a leading ";" that has to be removed for a change to become active.<br />
For example to replace the hotkey used by Nautilus to move files to the trash folder, change the line :<br />
; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")<br />
to this :<br />
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")<br />
<br />
The file is regenerate regularly so don't waist time on commenting the file. The uncommented line will stay but every comment you may add will be lost.<br />
<br />
==== Nautilus 3.4 and older ====<br />
Firstly, use '''dconf-editor''' to place a checkmark next to {{ic|can-change-accels}} in the key named ''org.gnome.desktop.interface.''<br />
<br />
We will replace the hotkey — a.k.a. keyboard shortcut, keyboard accelerator — used by Nautilus to move files to the trash folder.<br />
The default assignment is a somewhat-awkward {{Keypress|Ctrl+Delete}}.<br />
* Open Nautilus, select any file, and click '''Edit''' on the menu bar.<br />
* Hover over the ''Move to Trash'' menu item.<br />
* While hovering, press {{Keypress|Delete}}. The current accelerator is now unset.<br />
* Press the key that you wish to become the new keyboard accelerator.<br />
* Press {{Keypress|Delete}} to make the new accelerator be the Delete key.<br />
Unless you select a file or folder, ''Move to Trash'' will be grayed-out. Finally, disable {{ic|can-change-accels}} to prevent accidental hotkey changes.<br />
<br />
=== Shutdown via the status menu ===<br />
<br />
Currently, the GNOME designers have hidden the ''Shutdown'' option inside the status menu. To shut down your system with the status menu, click the menu and hold down the {{Keypress|Alt}} key so that the '''''Suspend''''' item changes to '''''Power Off'''''. The subsequent dialog allows you to shut down or restart your system.<br />
<br />
If you disable the Suspend menu item system-wide as described [[#Disable_"Suspend"_in_the_status_menu|elsewhere in this document]] you do not have to go through these motions.<br />
<br />
Another option is to install the ''Alternative Status Menu'' extension. See the section on shell extensions. The alternative menu extension installs a new status menu with a non-hidden '''''Power Off''''' entry.<br />
<br />
=== Screencast recording ===<br />
<br />
Gnome features the built-in possbility to create screencasts easily. Thereby Control+Shift+Alt+R keybinding starts and stops the recording. A red circle is displayed in the bottom right corner of the screen when the recording is in progress. After the recording is finished, a file named 'Screencast from %d%u-%c.webm' is saved in the Videos directory. In order to use the screencast feature you need to have installed the gst plugins which are:<br />
<br />
$ pacman -Qs gst<br />
<br />
=== Modify Keyboard with XkbOptions ===<br />
<br />
Using the '''dconf-editor''', navigate to the key named ''org.gnome.desktop.input-sources.xkb-options'' and add desired XkbOptions (e.g. 'caps:swapescape') to the list.<br />
<br />
See /usr/share/X11/xkb/rules/xorg for all XkbOptions and then /usr/share/X11/xkb/symbols/* for the respective descriptions.<br />
<br />
=== Toggle keyboard layouts ===<br />
Since Gnome does not consider any configuration in {{ic|/etc/X11/conf.d/*.conf}} you have to set the command for layout switching either via the control center with the options ''Switch to previous source'' and ''Switch to next source'' or if you want to use Alt - Shift combination you have to use the Gnome-Tweak-Tool and set ''Typing -> Modifiers-only input sources -> select Alt-shift''. For more information see also the forum [https://bbs.archlinux.org/viewtopic.php?id=152127 thread].<br />
<br />
== Integrated messaging (Empathy) ==<br />
<br />
Empathy, the engine behind integrated messaging, and all system settings based on messaging accounts will not show up unless the {{grp|telepathy}} group of packages or at least one of the backends ({{pkg|telepathy-gabble}}, or {{pkg|telepathy-haze}}, for example) is installed.<br />
<br />
These packages are not included in default Arch GNOME installs. You can install the Telepathy and optionally any backends with:<br />
<br />
# pacman -S telepathy<br />
<br />
Without telepathy, Empathy will not open the account management dialog and can get stuck in this state. If this happens -- even after quitting Empathy cleanly -- the {{ic|/usr/bin/empathy-accounts}} application can remain running and will need to be killed before you can add any new accounts.<br />
<br />
View descriptions of telepathy components on the [http://telepathy.freedesktop.org/wiki/Components Freedesktop.org Telepathy Wiki.]<br />
<br />
== Forcing fallback mode ==<br />
{{Note|1=caution for beginners: using recent gdm and gnome you may not be able to login if you force fallback mode, see [https://bbs.archlinux.org/viewtopic.php?pid=1301932#p1301932 post].}}<br />
<br />
Your session automatically starts in fallback mode when '''gnome-shell''' is not present, or when your hardware cannot handle graphics acceleration — such as running within a virtual machine or running on old hardware.<br />
<br />
If you wish to enable fallback mode while still having '''gnome-shell''' installed, make the following system change:<br />
<br />
Go to '''System Settings''' ({{ic|gnome-control-center}}) -> '''Details''' -> '''Graphics''' and set '''Forced Fallback Mode''' to {{ic|ON}}.<br />
<br />
You can alternatively choose the type of session from a terminal with {{ic|gsettings}}:<br />
<br />
$ gsettings set org.gnome.desktop.session session-name gnome-fallback<br />
<br />
You may want to log out after making the change. You will see the chosen type of session upon your next login.<br />
<br />
To disable the forced-fallback mode change it back to {{ic|gnome}}.<br />
<br />
=== Flashback Session ===<br />
<br />
Since Gnome 3.8, the fallback option is not available any more. One can however force a more classic style via {{pkg|gnome-flashback-session}}. Install the package and select session GnomeFlashback at the GDM login.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Cannot Set Settings in Dconf-Editor ===<br />
<br />
When one cannot set settings in {{pkg|dconf}}, it is possible their dconf user settings are corrupt. In this case it is best to delete the user dconf files in {{bc|<nowiki> .config/dconf/user* </nowiki>}} and set the settings in dconf-editor after.<br />
<br />
=== When an extension breaks GNOME ===<br />
<br />
When enabling shell extensions causes GNOME breakage, you should first remove the ''user-theme'' and ''auto-move-windows'' extensions from their installation directory.<br />
<br />
The installation directory could be one of '''{{ic|~/.local/share/gnome‑shell/extensions,}}''' '''{{ic|/usr/share/gnome‑shell/extensions,}}''' or '''{{ic|/usr/local/share/gnome‑shell/extensions}}'''. Removing these two extension-containing folders may fix the breakage. Otherwise, isolate the problem extension with trial‑and‑error.<br />
<br />
Removing or adding an extension-containing folder to the aforementioned directories removes or adds the corresponding extension to your system. Details on GNOME Shell extensions are available at the [https://live.gnome.org/GnomeShell/Extensions GNOME web site.]<br />
<br />
=== Extensions do not work after GNOME 3 update ===<br />
<br />
Locate the folder where your extensions are installed. It might be '''{{ic|~/.local/share/gnome-shell/extensions}}''' or '''{{ic|/usr/share/gnome-shell/extensions}}'''.<br />
<br />
Edit each occurrence of '''{{ic|metadata.json}}''' which appears in each extension sub-folder. <br />
<br />
{| border="0"<br />
| Insert: || '''{{ic|"shell-version": ["3.6"]}}'''<br />
|-<br />
| Instead of (for example): || '''{{ic|"shell-version": ["3.4"]}}'''<br />
|}<br />
<br />
<br />
'''"3.x"''' indicates the extension works with every Shell version. If it breaks, you'll know to change it back.<br />
<br />
=== The "Windows" key ===<br />
By default, this key is mapped to the "overlay-key" to launch the Overview. You can remove this key mapping to free up your {{ic|Windows Key}} (also called {{ic|Mod4}}), which GNOME calls {{ic|Super_L}}, by utilizing {{ic|gsettings}}.<br />
<br />
Example:<br />
{{ic| gsettings set org.gnome.mutter overlay-key 'Foo';}}.<br />
You can leave out '''Foo''' to simply remove any binding to that function.<br />
<br />
{{Note| GNOME also uses {{ic|Alt+F1}} to launch the Overview.}}<br />
<br />
=== Keyboard Shortcut do not work with only conky running ===<br />
The gnome-shell keyboard shortcuts like {{keypress|Alt+F2}}, {{keypress|Alt+F1}}, and the media key shortcuts do not work if conky is the only program running. However if another application like gedit is running, then the keyboard shortcuts work.<br />
<br />
solution: edit .conkyrc <br />
<br />
own_window yes<br />
own_window_transparent yes<br />
own_window_argb_visual yes<br />
own_window_type dock<br />
own_window_class Conky<br />
own_window_hints undecorated,below,sticky,skip_taskbar,skip_pager<br />
<br />
=== xf86-video-ati driver: flickers from time to time ===<br />
<br />
If you use that driver, your desktop might flicker a lot when you hover the bottom right corner, and also when you start up gdm.<br />
Write the following in your '''{{ic|/etc/X11/xorg.conf.d/20-radeon.conf}}''' and see if it works then:<br />
<br />
Section "Device"<br />
Identifier "Radeon"<br />
Driver "radeon"<br />
Option "EnablePageFlip" "off"<br />
EndSection<br />
<br />
https://wiki.archlinux.org/index.php/Intel_Graphics#Choose_acceleration_method<br />
<br />
=== Intel card: Black Screen, Crashes, or Freezes===<br />
If freezing, crashing, or a black screen occur while using an Intel graphics card, it may help to create {{ic|/etc/X11/xorg.conf.d/20-intel.conf}} with the the following to enable SNA acceleration. More information can be found [https://wiki.archlinux.org/index.php/Intel_Graphics#Choose_acceleration_method here].<br />
<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "AccelMethod" "sna"<br />
EndSection<br />
<br />
=== Window opens behind other windows when using multiple monitors ===<br />
<br />
This is possibly a bug in GNOME Shell which causes new windows to open behind others.<br />
Unchecking "workspaces_only_on_primary" in desktop/gnome/shell/windows using gconf-editor solves this problem.<br />
<br />
=== Multiple monitors and dock extension ===<br />
<br />
If you have multiple monitors configured using Nvidia Twinview, the dock extension may get sandwiched in-between the monitors. You can edit the source of this extension to reposition the dock to a position of your choosing.<br />
<br />
Edit {{ic|/usr/share/gnome-shell/extensions/dock@gnome-shell-extensions.gnome.org/extension.js}} and locate this line in the source:<br />
<br />
this.actor.set_position(primary.width-this._item_size-this._spacing-2, (primary.height-height)/2);<br />
<br />
The first parameter is the X position of the dock display, by subtracting 15 pixels as opposed to 2 pixels from this it correctly positioned on my primary monitor, you can play around with any X,Y coordinate pair to position it correctly.<br />
<br />
this.actor.set_position(primary.width-this._item_size-this._spacing-15, (primary.height-height)/2);<br />
<br />
=== No event sounds for Empathy and other programs ===<br />
<br />
If you are using [[OSS]], you may want to install {{AUR|libcanberra-oss}} from the [[AUR]].<br />
<br />
=== Gnome sets the keyboard layout to USA after every log in === <br />
<br />
See the [[https://bugzilla.redhat.com/show_bug.cgi?id=530452 this]] bug report for more information. It is related to GDM and can be fixed by choosing the correct layout at GDM login startup. However, users who do not use GDM or any login manager but a pure startx approach have to use a workaround. Create the file {{ic|~/.keyboard}} and make it executable {{ic|chmod +x}}:<br />
<br />
# Set the correct keyboard layout after Gnome start<br />
setxkbmap -layout "us,pl" -variant altgr-intl -option "grp:alt_shift_toggle" nodeadkeys<br />
<br />
Now run {{ic|gnome-session-properties}} and add this .keyboard file to the programs run at startup:<br />
<br />
Name: Keyboard layout <br />
Command: /home/username/.keyboard<br />
Comment: Sets the correct keyboard layout after Gnome start<br />
<br />
Further you need to create the executable file {{ic|/etc/pm/sleep.d/90_keyboard}} with the following content in order to run the script on resume from suspend and hibernation.<br />
<br />
#!/bin/bash<br />
case $1 in<br />
resume|thaw)<br />
/home/username/.keyboard<br />
;;<br />
esac<br />
<br />
=== Panels do not respond to right-click in fallback mode ===<br />
<br />
Check Configuration Editor: /apps/metacity/general/mouse_button_modifier. This modifier key ({{Keypress|Alt}}, {{Keypress|Super}}, etc) used for normal windows is also used by panels and their applets.<br />
<br />
=== "Show Desktop" keyboard shortcut does not work ===<br />
<br />
GNOME developers treated the corresponding binding as bug (see https://bugzilla.gnome.org/show_bug.cgi?id=643609) due to Minimization being deprecated. To show the desktop again assign ALT+STRG+D to the following setting:<br />
<br />
System Settings --> Keyboard --> Shortcuts --> Navigation --> Hide all normal windows<br />
<br />
=== Nautilus does not start ===<br />
<br />
# Press {{keypress|Alt+F2}}<br />
# Enter {{ic|gnome-tweak-tool}}<br />
# Select the ''File Manager'' tab.<br />
# Locate option ''Have file manager handle the desktop'' and assure it is toggled '''off'''.<br />
<br />
=== Epiphany does not play Flash videos ===<br />
<br />
Adobe Flash Player is buggy and does not work directly in Epiphany. See [[Epiphany#Flash]] for a workaround involving nspluginwrapper.<br />
<br />
=== Unable to apply stored configuration for monitors ===<br />
<br />
If you encounter this message try to disable the xrandr gnome-settings-daemon plugin :<br />
<br />
$ dconf write /org/gnome/settings-daemon/plugins/xrandr/active false<br />
<br />
=== Lock button fails to re-enable touchpad ===<br />
<br />
Some laptops have a touchpad lock button that disables the touchpad so that users can type without worrying about touching the touchpad. It appears currently that although GNOME can lock the touchpad by pressing this button, it cannot unlock it. If the touchpad gets locked you can do the following to unlock it.<br />
# Start a terminal. You can do this by pressing {{keypress|Alt+F2}}, then typing {{ic|gnome-terminal}} followed by pressing {{keypress|Enter}}.<br />
# Type in the following command<br />
$ xinput set-prop "SynPS/2 Synaptics TouchPad" "Device Enabled" 1<br />
<br />
=== Unable to connect to secured Wi-Fi networks ===<br />
<br />
You can see the network connections listing, but choosing an encrypted network fails to show a dialog for key entry. You may need to [[pacman|install]] {{Pkg|network-manager-applet}}. See [[NetworkManager#GNOME|GNOME NetworkManager setup]].<br />
<br />
=== "Any command has been defined 33" ===<br />
<br />
When you press the {{Keypress|Print Screen}} key (sometimes labeled {{Keypress|PrntScr}} or {{Keypress|PrtSc}}) to take a screenshot, and you got "Any command has been defined 33", [[pacman|install]] {{Pkg|metacity}}.<br />
<br />
=== GDM and GNOME use X11 cursors ===<br />
<br />
To fix this problem, become root and put the following into {{ic|/usr/share/icons/default/index.theme}} (creating the directory {{ic|/usr/share/icons/default}} if necessary):<br />
{{hc|/usr/share/icons/default/index.theme|<nowiki><br />
[Icon Theme]<br />
Inherits=Adwaita<br />
</nowiki>}}<br />
<br />
Note: Instead of "Adwaita", you can choose another cursor theme (e.g. Human).<br />
Alternatively, you can install {{AUR|gnome-cursors-fix}} from the [[AUR]].<br />
<br />
=== Tracker & Documents don't list any local files ===<br />
<br />
In order for Tracker (and, therefore, Documents) to detect your local files, they must be stored in directories that it knows of. If your documents are contained in one of the usual XDG standard directories (i.e. "Documents" or "Music"), you should install [https://www.archlinux.org/packages/extra/x86_64/xdg-user-dirs/ xdg-user-dirs] and run:<br />
<br />
# xdg-user-dirs-update<br />
<br />
This will create all of the usual XDG home directories if they don't already exist and it will create the config file definining these directories that Tracker and Documents depend upon.<br />
<br />
=== Passwords are not remembered ===<br />
<br />
If you get a password prompt every time you login, and you find password are not saved, you might need to create/set a default keyring:<br />
<br />
$ pacman -S seahorse<br />
<br />
Open "Passwords and Keys" from the menu or run "seahorse". Select View > By Keyring. If there is no keyring in the left column (it will be marked with a lock icon), go to File > New > Password Keyring and give it a nice name. You will be asked to enter a password. If you do not give it a password it will be unlocked automatically even when using autologin, but passwords will not be stored securely. Finally, right-click on the keyring you just created and select "Set as default".<br />
<br />
=== Windows can't be modified with Alt-Key + Mouse-Button ===<br />
<br />
Change the dconf-setting "org.gnome.desktop.wm.preferences.mouse-button-modifier" from <Super> back to <Alt>. It is not possible to change this with ''System Settings'' > "Keyboard" > "Shortcuts", you will find there only the regular keybindings. The developers of GNOME decided to change this from 3.4 to 3.6 because of this bug report https://bugzilla.gnome.org/show_bug.cgi?id=607797<br />
<br />
=== Gnome-shell 3.8.x fails to load with a black screen + cursor ===<br />
<br />
If you have a non-UTF8 language enabled, Gnome 3 can fail to load. Disable non-UTF-8 locales and perform a locale-gen until this is resolved.<br />
For more information see this bug report: https://bugzilla.gnome.org/show_bug.cgi?id=698952<br />
<br />
== External links ==<br />
* [http://www.gnome.org/ The Official Website of GNOME]<br />
* [http://extensions.gnome.org/ Extensions for GNOME-shell]<br />
* Themes, icons, and backgrounds:<br />
** [http://art.gnome.org/ GNOME Art]<br />
** [http://www.gnome-look.org/ GNOME Look]<br />
* GTK/GNOME programs:<br />
** [http://www.gnomefiles.org/ GNOME Files]<br />
** [http://www.gnome.org/projects/ GNOME Project Listing]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Intel_graphics&diff=268835Intel graphics2013-07-30T16:54:12Z<p>Bluerider: /* Weathered colors (colorspace problem) */</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X Server]]<br />
[[cs:Intel]]<br />
[[es:Intel]]<br />
[[fr:Intel]]<br />
[[hu:Intel]]<br />
[[it:Intel]]<br />
[[ja:Intel Graphics]]<br />
[[pl:Intel]]<br />
[[ru:Intel]]<br />
[[zh-CN:Intel Graphics]]<br />
[[zh-TW:Intel]]<br />
{{Article summary start}}<br />
{{Article summary text|Information on Intel graphics cards/chipsets and the ''intel'' video driver.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Intel GMA3600}}<br />
{{Article summary wiki|Poulsbo}}<br />
{{Article summary wiki|Xorg}}<br />
{{Article summary end}}<br />
<br />
Since Intel provides and supports open source drivers, Intel graphics are now essentially plug-and-play.<br />
<br />
For a comprehensive list of Intel GPU models and corresponding chipsets and CPUs, see [[Wikipedia:Comparison of Intel graphics processing units|this comparison on Wikipedia]].<br />
<br />
{{Note|PowerVR-based graphics ([[Poulsbo|GMA 500]] and [[Intel GMA3600|GMA 3600]] series) are not supported by open source drivers.}}<br />
<br />
== Installation ==<br />
<br />
Prerequisite: [[Xorg]].<br />
<br />
[[pacman|Install]] the {{Pkg|xf86-video-intel}} package which is available in the [[Official Repositories|official repositories]]. It provides the DDX driver for 2D acceleration and an [[XvMC]] driver for video decoding on older GPUs. It pulls in {{Pkg|intel-dri}} as a dependency, providing the DRI driver for 3D acceleration.<br />
<br />
Hardware accelerated video decoding/encoding on newer GPUs is possible through the [[VA-API]] driver provided by {{Pkg|libva-intel-driver}} package also, available in the official repositories.<br />
<br />
{{Note|User ''may'' need to install {{Pkg|lib32-intel-dri}} in 64-bit systems to use 3D acceleration in 32-bit programs.}}<br />
<br />
== Configuration ==<br />
<br />
There is no need for any kind of configuration to get the X.Org running (an {{ic|xorg.conf}} is unneeded, but needs to be configured correctly if present).<br />
<br />
For the list of options, type {{ic|man intel}}.<br />
<br />
== KMS (Kernel Mode Setting) ==<br />
<br />
{{Tip|If you have problems with the resolution, check [[Kernel_Mode_Setting#Forcing_modes_and_EDID|this page]].}}<br />
<br />
[[KMS]] is required in order to run X and a desktop environment such as [[GNOME]], [[KDE]], [[Xfce]], [[LXDE]], etc. KMS is supported by Intel chipsets that use the i915 DRM driver and is enabled by default as of kernel v2.6.32. Versions 2.10 and newer of the {{Pkg|xf86-video-intel}} driver no longer support UMS (except for the very old 810 chipset family), making the use of KMS mandatory<sup>[https://www.archlinux.org/news/484/]</sup>. KMS is typically initialized after the kernel is bootstrapped. It is possible, however, to enable KMS during bootstrap itself, allowing the entire boot process to run at the native resolution.<br />
<br />
{{Note|Users '''must''' remove any deprecated references to {{ic|vga}} or {{ic|nomodeset}} from boot configuration.}}<br />
<br />
To proceed, add the {{ic|i915}} module to the {{ic|MODULES}} line in {{ic|/etc/mkinitcpio.conf}}:<br />
<br />
MODULES="'''i915'''"<br />
<br />
If you are using a custom EDID file, you should embed it into initramfs as well:<br />
<br />
{{hc|/etc/mkinitcpio.conf|<br />
2=FILES="/lib/firmware/edid/your_edid.bin"}}<br />
<br />
Now, regenerate the initramfs:<br />
<br />
# mkinitcpio -p linux<br />
<br />
and reboot the system. Everything should work now.<br />
<br />
== Module-based Powersaving Options ==<br />
<br />
The '''i915''' kernel module allows for configuration via {{ic|/etc/modprobe.d/i915.conf}} wherein users can define powersavings options. A listing of options is available via the following command:<br />
<br />
$ modinfo i915 | grep power<br />
<br />
An example {{ic|/etc/modprobe.d/i915.conf}}:<br />
options i915 i915_enable_rc6=7 i915_enable_fbc=1 lvds_downclock=1<br />
<br />
== Tips and tricks ==<br />
<br />
=== Choose acceleration method ===<br />
*UXA - (Unified Acceleration Architecture) is the mature backend that was introduced to support the GEM driver model.<br />
*SNA - (Sandybridge's New Acceleration) is the faster successor for hardware supporting it.<br />
<br />
The default method is UXA, which is more stable but slower than SNA. SNA has improved performance, but still considered experimental. Check benchmarks done by Phoronix [http://www.phoronix.com/scan.php?page=news_item&px=MTEzOTE]. These can be found [http://www.phoronix.com/scan.php?page=article&item=intel_glamor_first&num=1 here for Sandy Bridge] and [http://www.phoronix.com/scan.php?page=article&item=intel_ivy_glamor&num=1 here for Ivy Bridge]. UXA is still a solid option, if experiencing trouble with SNA. If you are having trouble with UXA though you might have better luck with SNA.<br />
<br />
To use the new SNA method, create {{ic|/etc/X11/xorg.conf.d/20-intel.conf}} with the following content:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "AccelMethod" "sna"<br />
EndSection}}<br />
<br />
=== Setting scaling mode ===<br />
<br />
This can be useful for some full screen applications:<br />
<br />
$ xrandr --output LVDS1 --set PANEL_FITTING param<br />
<br />
where {{ic|param}} can be:<br />
<br />
* {{ic|center}}: resolution will be kept exactly as defined, no scaling will be made,<br />
* {{ic|full}}: scale the resolution so it uses the entire screen or<br />
* {{ic|full_aspect}}: scale the resolution to the maximum possible but keep the aspect ratio.<br />
<br />
If it does not work, try:<br />
<br />
$ xrandr --output LVDS1 --set "scaling mode" param<br />
<br />
where {{ic|param}} is one of {{ic|"Full"}}, {{ic|"Center"}} or {{ic|"Full aspect"}}.<br />
<br />
=== KMS Issue: console is limited to small area ===<br />
<br />
One of the low-resolution video ports may be enabled on boot which is causing the terminal to utilize a small area of the screen. To fix, explicitly disable the port with an i915 module setting with {{ic|1=video=SVIDEO-1:d}} in the kernel command line parameter in the bootloader. See [[Kernel parameters]] for more info.<br />
<br />
If that does not work, try disabling TV1 or VGA1 instead of SVIDEO-1.<br />
<br />
=== H.264 decoding on GMA 4500 ===<br />
<br />
The {{Pkg|libva-intel-driver}} package provides MPEG-2 decoding only for GMA 4500 series GPUs. The H.264 decoding support is maintained in a separated g45-h264 branch, which can be used by installing {{AUR|libva-driver-intel-g45-h264}} package, available in the [[Arch User Repository]]. Note however that this support is experimental and not currently in active development. Using the VA-API with this driver on a GMA 4500 series GPU will offload the CPU but may not result in as smooth a playback as non-accelerated playback. Tests using mplayer showed that using vaapi to play back an H.264 encoded 1080p video halved the CPU load (compared to the XV overlay) but resulted in very choppy playback, while 720p worked reasonably well [https://bbs.archlinux.org/viewtopic.php?id=150550]. This is echoed by other experiences [http://www.emmolution.org/?p=192&cpage=1#comment-12292].<br />
<br />
=== Setting gamma and brightness ===<br />
<br />
Intel offers no way to adjust these at the driver level. Luckily these can be set with {{ic|xgamma}} and {{ic|xrandr}}.<br />
<br />
Gamma can be set with:<br />
<br />
$ xgamma -gamma 1.0<br />
<br />
or:<br />
<br />
$ xrandr --output VGA1 --gamma 1.0:1.0:1.0<br />
<br />
Brightness can be set with:<br />
<br />
$ xrandr --output VGA1 --brightness 1.0<br />
<br />
== Troubleshooting ==<br />
<br />
=== Blank screen during boot, when "Loading modules" ===<br />
<br />
If using "late start" KMS and the screen goes blank when "Loading modules", it may help to add {{ic|i915}} and {{ic|intel_agp}} to the initramfs. See [[Intel#KMS (Kernel Mode Setting)|the above]] KMS section.<br />
<br />
Alternatively, appending the following [[Kernel parameters|kernel parameter]] seems to work as well:<br />
<br />
video=SVIDEO-1:d<br />
<br />
=== Tear-free video ===<br />
<br />
If using the SNA acceleration method, ablate video tearing by adding the following to the {{ic|Device}} section of {{ic|/etc/X11/xorg.conf.d/20-intel.conf}}:<br />
<br />
Option "TearFree" "true"<br />
<br />
{{Note|This option may not work when {{ic|SwapbuffersWait}} is {{ic|false}}.}}<br />
<br />
=== X freeze/crash with intel driver ===<br />
<br />
Some issues with X crashing, GPU hanging, or problems with X freezing, can be fixed by disabling the GPU usage with the {{ic|NoAccel}} option:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "NoAccel" "True"<br />
EndSection}}<br />
<br />
Alternatively, try to disable the 3D acceleration only with the {{ic|DRI}} option:<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "DRI" "False"<br />
EndSection}}<br />
<br />
If you experience crashes and have<br />
<br />
Option "TearFree" "true"<br />
Option "AccelMethod" "sna"<br />
<br />
in your config file, in most cases these can be fixed by adding<br />
<br />
i915.semaphores=1<br />
<br />
to your boot parameters.<br />
<br />
=== Adding undetected resolutions ===<br />
<br />
This issue is covered on the [[Xrandr#Adding_undetected_resolutions|Xrandr page]].<br />
<br />
=== Slowness after an upgrade to libGL 9 and Intel-DRI 9 ===<br />
<br />
[https://wiki.archlinux.org/index.php/Downgrading_Packages#ARM Downgrade] to Intel-DRI 8 and libGL 8.<br />
<br />
=== Black textures in video games ===<br />
<br />
Users experiencing black textures in video games may find a solution by enabling S3TC texture compression support. <br />
It can be enabled through {{Pkg|driconf}} or by installing {{Pkg|libtxc_dxtn}}.<br />
<br />
This "issue" will be fixed very soon in the [http://www.phoronix.com/scan.php?page=news_item&px=MTIwOTg newer drivers].<br />
<br />
Read more about S3TC at: <br />
* http://dri.freedesktop.org/wiki/S3TC<br />
* http://en.wikipedia.org/wiki/S3_Texture_Compression<br />
<br />
One of the games that is affected by this issue is [http://www.phoronix.com/scan.php?page=article&item=unigine_oilrush_gold&num=2 Oil Rush] and World of Warcraft using Wine.<br />
<br />
=== Weathered colors (colorspace problem) ===<br />
<br />
{{Note|This problem is related to the changes in the kernel 3.9. This problem still remains in kernel 3.10}}<br />
Kernel 3.9 contains the Intel driver changes allowing easy RGB Limited range settings which can cause weathered colors in some cases. It is related to the new "Automatic" mode for the "Broadcast RGB" property.<br />
One can force mode e.g. {{ic|xrandr --output HDMI1 --set "Broadcast RGB" "Full"}} using apropriate output device if other than HDMI1.<br />
{{Note|Some TVs can only display colors from 16-255 so setting to Full will cause color clipping in the 0-15 range so it's best to leave it at Automatic which will automatically detect whether it needs to compress the colorspace for your TV.}}<br />
<br />
Also there are other related problems which can be fixed editing GPU registers. More information can be found [http://lists.freedesktop.org/archives/intel-gfx/2012-April/016217.html] and [http://github.com/OpenELEC/OpenELEC.tv/commit/09109e9259eb051f34f771929b6a02635806404c].<br />
<br />
==== Fix weathered colors on startup (colorspace problem) ====<br />
<br />
Add {{ic|xrandr -output <HDMI> --set 'Broadcast RGB' 'Full'}} using the appropriate output device if it isn't HDMI (verify with {{ic|$ xrandr}} to the user's .xprofile and make the .xprofile executable.<br />
<br />
=== Backlight not fully adjusting, or adjusting at all after resume. ===<br />
<br />
If you are using Intel graphics and have no control over your manufacturer suplied hotkeys for changing screen brightness, try booting the kernel parameter:<br />
<br />
acpi_backlight=vendor<br />
<br />
If that doesnt solve the problem, many folks have gotten mileage from either:<br />
<br />
acpi_osi=Linux<br />
<br />
or<br />
<br />
acpi_osi="!Windows 2012"<br />
<br />
in addition to the earlier mentioned parameter.<br />
<br />
If neither of those solve your problem, you should edit/create {{ic|/etc/X11/xorg.conf.d/20-intel.conf}} with the following content:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "card0"<br />
Driver "intel"<br />
Option "Backlight" "intel_backlight"<br />
BusID "PCI:0:2:0"<br />
<br />
EndSection}}<br />
<br />
If you are using the SNA acceleration as mentioned above, create the file as follows:<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "card0"<br />
Driver "intel"<br />
Option "AccelMethod" "sna"<br />
Option "Backlight" "intel_backlight"<br />
BusID "PCI:0:2:0"<br />
<br />
EndSection}}<br />
<br />
== See also ==<br />
<br />
* https://01.org/linuxgraphics/documentation (includes a list of supported hardware)<br />
* [[KMS]] - Arch wiki article on kernel mode setting<br />
* [[Xrandr]] - Problems setting the resolution<br />
* Arch Linux forums: [https://bbs.archlinux.org/viewtopic.php?pid=522665#p522665 Intel 945GM, Xorg, Kernel - performance]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=UEFI_Bootloaders&diff=268670UEFI Bootloaders2013-07-29T05:03:46Z<p>Bluerider: /* Systemd Automation */ Modified refind-update automation script to match upstream change from /usr/lib/refind to /usr/share/refind. WHY DO THE DIRECTORY AND NAMES KEEP CHANGING?</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[zh-CN:UEFI Bootloaders]]<br />
This page contains info about various [[UEFI]] Bootloaders capable of booting Linux kernel. It is recommended to read the [[UEFI]] and [[GPT]] pages before reading this page. The following [[Boot Loader|bootloaders]] are explained here:<br />
<br />
== Linux Kernel EFISTUB ==<br />
{{Warning|1=A bug has been noticed where booting EFISTUB can fail depending on kernel version and motherboard model. See [https://bbs.archlinux.org/viewtopic.php?id=156670&p=1] for more information.}}<br />
<br />
Linux (Kernel >= 3.3) supports {{ic|EFISTUB (EFI BOOT STUB)}} booting. It is enabled by default on Arch Linux kernels or can be activated by setting {{ic|CONFIG_EFI_STUB&#61;y}} in the Kernel configuration (see [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/x86/efi-stub.txt;hb=HEAD The EFI Boot Stub] for more information).<br />
<br />
A single EFISTUB kernel is not capable of launching other kernels, hence each EFISTUB Kernel + Initramfs pair requires a separate boot menu entry. It is recommended to use a UEFI Boot Manager to manage multiple kernels.<br />
<br />
=== Setting up EFISTUB ===<br />
<br />
#[https://wiki.archlinux.org/index.php/Unified_Extensible_Firmware_Interface#EFI_System_Partition Create a FAT32 UEFI System Partition]<br />
# Mount the UEFI System Partition at {{ic|/boot/efi}} with {{ic|# mount <UEFI Partition> /boot/efi}} if you're going to be using GRUB2, or at {{ic|/boot}} with {{ic|# mount <UEFI Partition> /boot}} if you're going to be using Gummiboot or rEFInd. Gummiboot cannot boot across partitions, and will never have such capability due to its nature, so it's paramount that you mount the UEFI System Partition at /boot for use with Gummiboot so that the kernel and initramfs lie on the same partition as the bootmanager. {{note| On some machines, when using rEFInd, it works fine when mounting the UEFI partition in {{ic|/boot/efi}}}}<br />
# Create {{ic|/boot/efi/EFI/arch/}} directory with {{ic|# mkdir /boot/efi/EFI/arch/}}<br />
# Copy the following files from source to destination<br />
{| border="1"<br />
!Boot File Source!!UEFI Destination<br />
|-<br />
| /boot/vmlinuz-linux || /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
|-<br />
| /boot/initramfs-linux.img || /boot/efi/EFI/arch/initramfs-arch.img<br />
|-<br />
| /boot/initramfs-linux-fallback.img || /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
|}<br />
{{note| As of {{Pkg|refind-efi}} 0.2.7, you don't need to copy these files, since refind will automatically detect them}}<br />
<br />
=== Sync EFISTUB Kernel ===<br />
{{Warning|The EFISTUB Kernel must be updated each time the kernel is updated (follow step 4 in [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Setting_up_EFISTUB Setting up EFISTUB]. Failure to do so will result in failure to boot. Alternatively one can automatically update the EFISTUB kernel using one of the following methods:}}<br />
<br />
{{Note| As of [https://www.archlinux.org/packages/extra/any/refind-efi/ refind-efi 0.2.7], refind automatically detects kernels in {{ic|/boot}}. They do not have to be renamed to have a {{ic|.efi}} extension either. Hence, the following sync scripts aren't needed if using [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Using_rEFInd refind]. You do need to install an EFI driver to read the Linux filesystem on which the kernel is stored, though. See [http://www.rodsbooks.com/refind/drivers.html]. Briefly, if the /boot is within an ext4 filesystem and the kernel is x64 architecture, you may run "mkdir -p /boot/efi/EFI/refind/drivers; cp /usr/share/refind/drivers_x64/ext4_x64.efi /boot/efi/EFI/refind/drivers" to install ext4 filesystem driver for 64 bit kernel so that the kernel can be located by the rEFInd.}}<br />
<br />
==== Systemd ====<br />
[[Systemd]] features event triggered tasks. In this particular case, the ability to detect a change in path is used to sync the EFISTUB kernel and initramfs files when they are updated in {{ic|boot}}.<br />
<br />
<br />
{{Warning|Since mkinitcpio takes time to build the kernel stub and the initramfs. It is possible for the following systemd services to copy older kernel stubs and initramfs instead of the new ones. To reduce the chance of this error, it is better to bind the efistub copying service to check if the initramfs-linux-fallback.img was changed (since it is the last thing built by mkinitcpio).}}<br />
{{Tip|Save the following script as {{ic|/usr/lib/systemd/system/efistub-update.path}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Copy EFISTUB Kernel to UEFISYS Partition<br />
<br />
[Path]<br />
PathChanged=/boot/initramfs-linux-fallback.img<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Tip|Save the following script as {{ic|/usr/lib/systemd/system/efistub-update.service}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Copy EFISTUB Kernel to UEFISYS Partition<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/cp -f /boot/vmlinuz-linux /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
ExecStart=/usr/bin/cp -f /boot/initramfs-linux.img /boot/efi/EFI/arch/initramfs-arch.img<br />
ExecStart=/usr/bin/cp -f /boot/initramfs-linux-fallback.img /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
</nowiki>}}<br />
<br />
{{Tip|Enable these services with<br />
{{bc|<nowiki><br />
# systemctl enable efistub-update.path<br />
</nowiki>}}}}<br />
<br />
==== Incron ====<br />
{{Pkg|incron}} can run a script to sync the EFISTUB Kernel after updates<br />
<br />
{{Tip|Save the following script as {{ic|/usr/local/bin/efistub-update.sh}}}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
/usr/bin/cp -f /boot/vmlinuz-linux /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
/usr/bin/cp -f /boot/initramfs-linux.img /boot/efi/EFI/arch/initramfs-arch.img<br />
/usr/bin/cp -f /boot/initramfs-linux-fallback.img /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
</nowiki>}}<br />
<br />
{{Tip|Save the following script as {{ic|/etc/incron.d/efistub-update.conf}}}}<br />
{{Note|The first parameter {{ic|/boot/initramfs-linux-fallback.img}} is the file to watch. The second parameter {{ic|IN_CLOSE_WRITE}} is the action to watch for. The third parameter {{ic|/usr/local/bin/efistub-update.sh}} is the script to execute.}}<br />
{{bc|<nowiki><br />
/boot/initramfs-linux-fallback.img IN_CLOSE_WRITE /usr/local/bin/efistub-update.sh<br />
</nowiki>}}<br />
<br />
{{Tip|In order to use this method, incron must be activated, if it is not run<br />
{{bc|<nowiki><br />
# systemctl enable incrond.service<br />
</nowiki>}}}}<br />
<br />
==== Mkinitcpio hook ====<br />
Mkinitcpio can generate a hook that does not need a system level daemon to function. It spawns a background process which waits for the generation of {{ic|vm-linuz}}, {{ic|initramfs-linux.img}}, and {{ic|initramfs-linux-fallback.img}}; then follows step 4 in [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Setting_up_EFISTUB Setting up EFISTUB]<br />
<br />
{{Tip|Save the following script as {{ic|/usr/lib/initcpio/install/efistub-update}}}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
<br />
build() {<br />
/root/watch.sh &<br />
}<br />
<br />
help() {<br />
cat <<HELPEOF<br />
This hook waits for mkinitcpio to finish and copies the finished ramdisk and kernel to the ESP<br />
HELPEOF<br />
}<br />
</nowiki>}}<br />
<br />
{{Tip|Save the following script as {{ic|/root/watch.sh}} and make it executable}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
<br />
while [[ -d "/proc/$PPID" ]]; do<br />
sleep 1<br />
done<br />
<br />
/usr/bin/cp -f /boot/vmlinuz-linux /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
/usr/bin/cp -f /boot/initramfs-linux.img /boot/efi/EFI/arch/initramfs-arch.img<br />
/usr/bin/cp -f /boot/initramfs-linux-fallback.img /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
<br />
echo "Synced kernel with ESP"<br />
</nowiki>}}<br />
<br />
{{Tip|Add {{ic|efistub-update}} to the list of hooks in {{ic|/etc/mkinitcpio.conf}}}}<br />
<br />
{{Note| As of [https://www.archlinux.org/packages/extra/any/refind-efi/ refind-efi 0.2.7], refind automatically detects kernels in {{ic|/boot}}. They do not have to be renamed to have a {{ic|.efi}} extension either. Hence, the following sync scripts aren't needed if using [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Using_rEFInd refind]. You do need to isntall an EFI driver to read the Linux filesystem on which the kernel is stored, though.}}<br />
<br />
=== Booting EFISTUB ===<br />
<br />
{{Warning|Linux Kernel EFISTUB booting uses {{ic|\}} instead of {{ic|/}} and should be relative to the UEFI System Partition's root. For example, if the initramfs is located in {{ic|/boot/efi/EFI/arch/initramfs-linux.img}}, the corresponding UEFI formatted line would be {{ic|\EFI\arch\initramfs-linux.img}}. Failure to convert the options will lead to a system hang without any error message from the firmware or kernel.<br />
{{Note| Support of initrd path name with {{ic|/}} in EFISTUB booting has been added in [https://patchwork.kernel.org/patch/1899361/ mainline 3.9-rc1] and [http://lwn.net/Articles/541002/ stable 3.8.2]. Leading {{ic|/}} can be ignored but the path still has to be full path. Example: {{ic|initrd&#61;EFI/arch/initramfs-linux.img}} }}<br />
}}<br />
<br />
<br />
<br />
One can boot the EFISTUB kernel using one of the following ways :<br />
<br />
==== Using rEFInd ====<br />
<br />
rEFInd is a fork of rEFIt Boot Manager (used in Intel Macs) by Rod Smith (author of GPT-fdisk). rEFInd fixes many issues in rEFIt with respect to non-Mac UEFI booting and also has support for booting EFISTUB kernels and contains some features specific to them.<br />
{{Tip|If you're new to EFISTUB and/or rEFInd, you need to read [http://www.rodsbooks.com/refind/linux.html The rEFInd Boot Manager: Methods of Booting Linux] before going any further. This section illustrates only one possible use-case which is not suitable for all configurations.}}<br />
# Install {{Pkg|refind-efi}} package with {{ic|# pacman -S refind-efi}}<br />
# Copy the following files from their source directory to their destination<br />
{{Note|1=<arch> is the bit architecture of the system. Run {{ic|$ uname -m}} to get the architecture. Replace <arch> with "ia32" for 32 bit systems, and <arch> with "x64" for 64 bit systems.}}<br />
{| border="1"<br />
!rEFInd File Source!!UEFI Destination<br />
|-<br />
| /usr/share/refind/refind_<arch>.efi || /boot/efi/EFI/refind/refind_<arch>.efi<br />
|-<br />
| /usr/share/refind/refind.conf-sample || /boot/efi/EFI/refind/refind.conf<br />
|-<br />
| /usr/share/refind/icons || /boot/efi/EFI/refind/icons<br />
|-<br />
| /usr/share/refind/drivers_<arch> || /boot/efi/EFI/refind/drivers<br />
|}<br />
<br />
{{Tip|Refind's configuration file is located in {{ic|/boot/efi/EFI/refind/refind.conf}}. The file is well commented.}}<br />
<br />
As of {{Pkg|refind-efi}} 0.2.7, refind can auto-detect kernels in {{ic|/boot}}, if there are UEFI drivers for the filesystem used by /boot partition (or / partition if no separate /boot is used) in the ESP, and are loaded by rEFInd. This is enabled in the default configuration in {{ic|refind.conf}} (you may need to include the PATH to the drivers folders in the ESP). Copy your {{ic|/usr/share/refind/refind_linux.conf-sample}} to {{ic|/boot/refind_linux.conf}}. You may pass kernel specific commands in this file. <br />
<br />
Edit the {{ic|refind_linux.conf}} configuration file to be similar to the template below. Replace the string after PARTUUID with your root's PARTUUID<br />
<br />
{{Note|1=Please notice the [https://bbs.archlinux.org/viewtopic.php?pid=1286972 difference] between the standard UUID and the PARTUUID shown by {{ic|$ ls -l /dev/disk/by-partuuid/}}}}<br />
{{hc|refind_linux.conf|<nowiki><br />
"Boot with defaults" "root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 ro rootfstype=ext4 add_efi_memmap systemd.unit=graphical.target"<br />
"Boot to Terminal" "root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 ro rootfstype=ext4 add_efi_memmap systemd.unit=multi-user.target"</nowiki>}}<br />
<br />
{{Tip|Each line of {{ic|refind_linux.conf}} is displayed as a submenu by rEFInd. Access the submenu with "+" or "insert" keys.}}<br />
<br />
{{Tip|In non-Mac systems, create an entry for rEFInd using [[UEFI#efibootmgr|efibootmgr]] where sdX is the UEFI disk, and Y is the UEFI partition number. Run :<br />
{{bc|<nowiki><br />
# modprobe efivars<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_<arch>.efi -L "rEFInd" <br />
</nowiki>}}}}<br />
<br />
===== Systemd Automation =====<br />
<br />
{{Tip|To automate the process of copying refind files and updating the nvram (if needed) use the following script}}<br />
<br />
{{Note|Save this script as {{ic|/usr/lib/systemd/scripts/refind_name_patchv2}}}}<br />
{{Tip|If you want to change the directory that refind is installed in the UEFISYS partition, just change the value of $refind_dir in the script}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
## COPYRIGHT 2013 : MARK E. LEE (BLUERIDER) : mlee24@binghamton.edu; mark@markelee.com<br />
<br />
## LOG<br />
## 1/17/2013 : Version 2 of refind_name_patch is released<br />
## : Supports long subdirectory location for refind<br />
## : Updates nvram when needed<br />
## : 10% speed boost<br />
## 7/15/2013 : Changed arch to match 32-bit (ia32) and 64-bit (x64) naming scheme<br />
## : Changed directory copying in update-efi-dir to copy tools and drivers directories explicitly<br />
## : Changed efibootmgr writing code to be more concise and added (-w) to write the entry as per dusktreader's excellent guide : https://docs.google.com/document/d/1pvgm3BprpXoadsQi38FxqMOCUZhcSqFhZ26FZBkmn9I/edit<br />
## : Function to check if NVRAM boot entry was already listed was fixed to use awk and an if then clause<br />
## : ref_bin_escape was modified from : ref_bin_escape=${ref_bin//\//\\\\} to remove extra backslashes (error does not show up when using cmdline)<br />
## 7/29/2013 : Changed location of tools,drivers, and binary directory to match capricious upstream move to /usr/share/refind<br />
<br />
function main () { ## main insertion function<br />
declare -r refind_dir="/boot/efi/EFI/refind"; ## set the refind directory<br />
arch=$(uname -m | awk -F'_' '{if ($1 == "x86") {print "x"$2} else if ($1 == "i686") {print "ia32"}}') && ## get bit architecture<br />
update-efi-dir; ## updates or creates the refind directory<br />
update-efi-nvram; ## updates nvram if needed<br />
}<br />
<br />
function update-efi-dir () { ## setup the refind directory<br />
if [ ! -d $refind_dir ]; then ## check if refind directory exists<br />
echo "Couldn't find $refind_dir";<br />
mkdir $refind_dir && ## make the refind directory if needed<br />
echo "Made $refind_dir";<br />
fi;<br />
if [ "$arch" ]; then ## check if anything was stored in $arch<br />
cp -r /usr/share/refind/{refind_$arch.efi,keys,images,icons,fonts,docs,{tools,drivers}_$arch} $refind_dir/ && ## update the bins and dirs<br />
echo "Updated binaries and directory files for refind at $refind_dir";<br />
else<br />
echo "Failed to detect an x86 architecture";<br />
exit;<br />
fi;<br />
}<br />
<br />
function update-efi-nvram () { ## update the nvram with efibootmgr<br />
declare -r ref_bin=${refind_dir/\/boot\/efi}/refind_$arch.efi; ## get path of refind binary (without /boot/efi)<br />
declare -r ref_bin_escape=${ref_bin//\//\\}; ## insert escape characters into $ref_bin<br />
modprobe efivars && ## grab the efi variables for efibootmgr<br />
[ "$(efibootmgr -v | awk "/${ref_bin_escape//\\/\\\\}/")" ] && ( ## check if boot entry is in nvram \<br />
echo "Found boot entry, no need to update nvram";<br />
) || ( ## if boot entry is not in nvram; add it<br />
declare -r esp=$(mount -l | awk '/ESP/ {print $1}') && ## get ESP partition<br />
efibootmgr -cgw -d ${esp:0:8} -p ${esp:8} -L "rEFInd" -l $ref_bin_escape && ## update nvram<br />
echo "<br />
Updated nvram with entry rEFInd to boot $ref_bin<br />
Did not copy configuration files, please move refind.conf to $refind_dir/";<br />
)<br />
}<br />
main; ## run the main insertion function<br />
</nowiki>}}<br />
<br />
{{Note| As of [https://www.archlinux.org/packages/extra/any/refind-efi/ refind-efi 0.2.7], refind automatically detects kernels in {{ic|/boot}}. They do not have to be renamed to have a {{ic|.efi}} extension either. Hence, the following sync scripts aren't needed if using [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Using_rEFInd refind]. You do need to isntall an EFI driver to read the Linux filesystem on which the kernel is stored, though.}}<br />
<br />
{{Note|Save the following service file as {{ic|/usr/lib/systemd/system/refind_update.path}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Update rEFInd bootloader files<br />
<br />
[Path]<br />
PathChanged=/usr/share/refind/refind_<arch>.efi<br />
Unit=refind_update.service<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|Save the following service file as {{ic|/usr/lib/systemd/system/refind_update.service}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Update rEFInd directories, binaries, and nvram<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/bash /usr/lib/systemd/scripts/refind_name_patchv2<br />
RemainAfterExit=no<br />
</nowiki>}}<br />
<br />
{{Tip|Enable the systemd path unit by running :<br />
{{bc|<nowiki><br />
# systemctl enable refind_update.path<br />
</nowiki>}}}}<br />
<br />
===== Apple Macs =====<br />
<br />
In case of Apple Macs, try {{AUR|mactel-boot}} for an experimental "bless" utility for Linux. If that does not work, use "bless" form within OSX to set rEFInd as default bootloader. Assuming UEFISYS partition is mounted at {{ic|/mnt/efi}} within OSX, do<br />
<br />
$ sudo bless --setBoot --folder /mnt/efi/EFI/refind --file /mnt/efi/EFI/refind/refind_x64.efi<br />
<br />
===== VirtualBox =====<br />
<br />
In case of VirtualBox, see [[VirtualBox#Using_Arch_under_Virtualbox_EFI_mode]].<br />
<br />
==== Using gummiboot ====<br />
<br />
[[Gummiboot]] is a UEFI Boot Manager which provides a nice menu for EFISTUB Kernels. It is available in [extra] as {{Pkg|gummiboot}}. See https://wiki.archlinux.org/index.php/Gummiboot for more info.<br />
<br />
==== Using UEFI Shell ====<br />
<br />
It is possible to launch EFISTUB kernel form UEFI Shell as if it is a normal UEFI application. In this case the kernel parameters are passed as normal parameters to the launched EFISTUB kernel file.<br />
<br />
> fs0:<br />
> cd \EFI\arch<br />
> vmlinuz-arch.efi root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 ro rootfstype=ext4 add_efi_memmap initrd=EFI/arch/initramfs-arch.img<br />
<br />
You can also write a simple {{ic|archlinux.nsh}} file with your boot parameters and put it in your UEFI System Partition, then run it with:<br />
<br />
fs0:<br />
archlinux<br />
<br />
Example Script:<br />
<br />
echo -on<br />
\EFI\arch\vmlinuz-arch.efi root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 rootfstype=ext4 add_efi_memmap initrd=EFI/arch/initramfs-arch.img<br />
<br />
This way you can specify UUID's without needing to remember the name or type out 20-30 characters.<br />
<br />
==== Using efibootmgr entry ====<br />
<br />
{{Warning|1=Some kernel and efibootmgr combinations do not work [https://bugs.archlinux.org/task/34641]. You will be able to delete but not create boot entries.}}<br />
<br />
{{Note|Some UEFI firmwares may not support embedding command line parameters to uefi applications in the boot entries.}}<br />
<br />
It is possible to directly embed the kernel parameters within the boot entry created by efibootmgr. This means that in your BIOS/UEFI you will be able to select Arch Linux directly in the default boot order, and on startup it will boot into Arch directly without any kind of boot selection GUI.<br />
<br />
# modprobe efivars<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/arch/vmlinuz-arch.efi -L "Arch Linux (EFISTUB)" -u "$(cat /proc/cmdline)"<br />
<br />
It is a good idea to run<br />
<br />
# efibootmgr -v<br />
<br />
to verify that the resulting entry is correct. You should also consider reordering the boot options ({{ic|efibootmgr -o}}) to place the Arch entry last, which could make the system easier to recover if it fails.<br />
<br />
More info about efibootmgr at [[UEFI#efibootmgr]]. Forum post https://bbs.archlinux.org/viewtopic.php?pid=1090040#p1090040 .<br />
<br />
== GRUB 2.xx ==<br />
<br />
GRUB 2.x contains its own filesystem drivers and does not rely on the firmware to access the files. It can directly read files from {{ic|/boot}} and does not require the kernel and initramfs files to be in the UEFISYS partition. Detailed information at [[GRUB#UEFI_systems_2]]. For bzr development version try AUR package - {{AUR|grub-bzr}}.<br />
<br />
== SYSLINUX 6.xx ==<br />
<br />
Install {{Pkg|syslinux}} (from [testing]) or {{AUR|syslinux-firmware-git}} AUR package and copy {{ic|/usr/lib/syslinux/efi64/*}} to {{ic|$esp/EFI/syslinux/}} ({{ic|$esp}} is the mountpoint of UEFISYS partition) ({{ic|efi64}} is for x86_64 UEFI firmwares, replace with {{ic|efi32}} for ia32 UEFI firmwares), and then create a boot entry using efibootmgr in the firmware boot manager.<br />
<br />
== ELILO ==<br />
<br />
ELILO is the UEFI version of LILO Boot Loader. It was originally created for Intel Itanium systems which supported only EFI (precursor to UEFI). It is the oldest UEFI bootloader for Linux. It is still in development but happens at a very slow pace. Upstream provided compiled binaries are available at http://sourceforge.net/projects/elilo/ . Elilo config file {{ic|elilo.conf}} is similar to [[LILO]]'s config file. AUR package - {{AUR|elilo-efi}}.<br />
<br />
== EFILINUX ==<br />
<br />
EFILINUX is the precursor to Kernel EFISTUB support. It can be used to boot kernel that do not support EFISTUB (mainly LTS kernels). It is not necessary to use efilinux if the kernel supports EFISTUB. <br />
<br />
It is available in the [extra] as {{Pkg|efilinux-efi}}. Upstream sources are at https://git.kernel.org/cgit/boot/efilinux/efilinux.git/ and the usage instructions are at http://thread.gmane.org/gmane.linux.kernel/1172645 and http://article.gmane.org/gmane.linux.kernel/1175060 .<br />
<br />
== See also ==<br />
<br />
* [http://www.rodsbooks.com/efi-bootloaders/ Rod Smith - Managing EFI Boot Loaders for Linux]<br />
* [http://www.rodsbooks.com/refind/ Rod Smith - rEFInd, a fork or rEFIt]<br />
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/x86/efi-stub.txt;hb=HEAD Linux Kernel Documentation on EFISTUB]<br />
* [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=commitdiff;h=291f36325f9f252bd76ef5f603995f37e453fc60;hp=55839d515495e766605d7aaabd9c2758370a8d27 Linux Kernel EFISTUB Git Commit]<br />
* [http://www.rodsbooks.com/efi-bootloaders/efistub.html Rod Smith's page on EFISTUB]<br />
* [http://www.rodsbooks.com/refind/linux.html rEFInd Documentation for booting EFISTUB Kernels]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=ASUS_Eee_PC_T101MT&diff=266825ASUS Eee PC T101MT2013-07-17T17:04:53Z<p>Bluerider: /* Rotating the touch screen */ Fixed the counter clockwise rotation script : awk prints $6 instead of $5</p>
<hr />
<div>[[Category:ASUS]]<br />
{| style="float:right; border: 1px solid #000;" <br />
| '''Device''' || '''Status''' || '''Information'''<br />
|- <br />
| Graphics || style="color:green" | '''Working''' || Intel GMA 3150<br />
|- <br />
| Ethernet || style="color:green" | '''Working''' || <br />
|-<br />
| Wireless || style="color:green" | '''Working''' || <br />
|-<br />
| Audio || style="color:green" | '''Working''' || <br />
|-<br />
| Camera || style="color:green" | '''Working''' || 3.0.0<br />
|-<br />
| Card Reader || style="color:green" | '''Working''' || <br />
|-<br />
| Function Keys || style="color:yellow" | '''Working''' || <br />
|-<br />
| Suspend2RAM || style="color:yellow" | '''Working''' ||<br />
|-<br />
| Hibernate || style="color:red" | '''Not working''' || <br />
|-<br />
| Touchscreen || style="color:green" | '''Working''' || 3.0.0<br />
|-<br />
| Multi-Touch || style="color:yellow" | '''Working''' ||<br />
|}<br />
<br />
== Installing Arch ==<br />
<br />
This wiki page supplements these pages: '''[[Beginners Guide]]''', the '''[[Official Arch Linux Install Guide|Official Install Guide]]''', and '''[[Installing Arch Linux on the Asus EEE PC]]'''. Please refer to those guides ''first'' before following the eeepc-specific pointers on this page.<br />
<br />
===Following the Beginners Guide===<br />
<br />
Graphics, Ethernet, Wireless, Audio and the Card Reader work "out of the box". <br />
<br />
===Camera===<br />
<br />
Is working fine with Ekiga<br />
<br />
If Skype displays the image upside-down<br><br />
to fix this use command:<br />
<br />
for x86_x64<br />
{{bc|<nowiki><br />
LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype<br />
</nowiki>}}<br />
for i686<br />
{{bc|<nowiki><br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype<br />
</nowiki>}}<br />
<br />
To make this happen automatically just create a script named skyp (or anything you want it to be)<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
<br />
#get the architecture of the system<br />
arch=`uname -m`<br />
<br />
#corrects upside down webcam in skype<br />
case $arch in<br />
x86_64)<br />
LD_PRELOAD=/usr/lib32/libv4l/v4l1compat.so skype;<br />
;;<br />
i686)<br />
LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so skype;<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
Save this script as "skyp" and '#chmod +x skyp'. Move this script to '/usr/bin/' with '#mv skyp /usr/bin/'. From now on typing in skyp should load skype with the proper webcam orientation.<br />
<br />
===Function Keys===<br />
<br />
Suspend-, Brightness- and Audiokeys work. Others may need special configuration.<br />
My Suspendkey was executing the suspend from KDE and from the acpi Interface. I disabled the KDE event, and now Suspend works.<br />
<br />
In openbox, editting ~/.config/rc.xml and appending (under <keyboard>); this was taken from https://wiki.archlinux.org/index.php/Openbox:<br />
<br />
{{bc|<nowiki><br />
<!-- Keybindings for audio control --><br />
<keybind key="XF86AudioRaiseVolume"><br />
<action name="Execute"><br />
<command>amixer set Master 5%+ unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioLowerVolume"><br />
<action name="Execute"><br />
<command>amixer set Master 5%- unmute</command><br />
</action><br />
</keybind><br />
<keybind key="XF86AudioMute"><br />
<action name="Execute"><br />
<command>amixer set Master toggle</command><br />
</action><br />
</keybind><br />
</nowiki>}}<br />
<br />
will make the audio keys work if alsa is installed.<br />
<br />
===Installing OpenBox===<br />
<br />
OpenBox can be installed by issuing #pacman -S openbox. Follow the instructions on screen to copy the openbox scripts to '~/.config/openbox/'.<br />
<br />
==Rotating the touch screen==<br />
Editing the openbox rc.xml file in '~/.config/openbox/rc.xml' will allow configuration of the Express Gate button. Open a terminal and run $xev (non-root) to find out the key associated with the Express Gate button (just click it while in xev). For my system it was key 248 (0xF8) in hexadecimal. Edit your ~/.config/openbox/rc.xml to include the following code under <keyboard>:<br />
<br />
{{bc|<nowiki><br />
<!-- Keybindings for express gate button --> <br />
<keybind key="0xF8"><br />
<action name="ShowMenu"><br />
<menu>root-menu</menu><br />
</action><br />
</keybind><br />
</nowiki>}}<br />
<br />
This will bind the express gate key to show the openbox menu whenever clicked.<br />
<br />
To rotate the screen, use the following script (note the following script can also be bound to the expressgate button itself to generate rotations (bypass any menu):<br />
<br />
** As of evdev 2.7.3-1, this script no longer properly rotates the touchscreen axes.<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
<br />
## script to rotate touch screens<br />
## will include support for rotating specific monitors<br />
<br />
###############################################<br />
# #<br />
# Touch_rotate for Asus T101mt #<br />
# written by Mark Lee #<br />
# #<br />
###############################################<br />
<br />
function main () { ## main insertion function<br />
args=("$@"); ## store the arguments in an array<br />
check-arg; ## read and check the arguments<br />
resolve-rotate; ## resolve the rotation<br />
rotate-screen; ## rotate the screen<br />
}<br />
<br />
function help-man () { ## print the help manual<br />
echo "<br />
where options are:<br />
[usage]: touch_rotate [options]<br />
<br />
-r or -rotate | rotate the screen; ex. -r right<br />
| <left,right,normal,upside-down><br />
-c or -counter-clockwise | rotate the screen counter clockwise<br />
-m or -monitor | set the monitor to rotate; ex. -m native<br />
| <primary,external><br />
-i or -id | set the id of the touch screen device<br />
--help | print this help screen<br />
<br />
Examples:<br />
touch_rotate -m native -r right<br />
<br />
Press "Ctrl-C" to exit any time<br />
"<br />
}<br />
<br />
function check-arg () { ## read and check console arguments<br />
for ((i = 0; i <= ${#args}; i++)); do ## loop for all arguments passed<br />
case ${args[$i]} in ## parse each argument<br />
-c|-C|-counter-clockwise)<br />
counter="yes"; ## toggle to rotate counter clockwise<br />
;; <br />
-r|-R|-rotate|-Rotate)<br />
rot="${args[$[i + 1]]}"; ## set the new rotation<br />
;;<br />
-m|-M|-monitor|-Monitor)<br />
mon="${args[$[i + 1]]}"; ## set the monitor to control<br />
;;<br />
-i|-I|-id)<br />
id="$id"; ## set the id of the device<br />
;;<br />
-help|--help|/?) ## help menu<br />
help-man; ## print the help menu<br />
exit; ## exit the script<br />
;;<br />
-*) ## for all other options<br />
echo "Unrecognized option: ${args[$i]}"<br />
help-man; ## print the help menu<br />
;;<br />
esac;<br />
done;<br />
if [ -z "$mon" ]; then ## check if monitor was specified<br />
mon="primary"; ## set the monitor to be the primary monitor<br />
fi;<br />
if [ "$mon" == "primary" ]; then<br />
mon="$(xrandr | awk '$2~/^connected/ {print $1}')"; ## set the monitor to be the connected monitor<br />
fi;<br />
if [ "$counter" == "yes" ]; then ## if user wants to rotate counter clockwise<br />
rot=$(xrandr -q --verbose | awk "/$mon/ {print \$6}"); ## capture the current rotation<br />
resolve-rotate; ## convert the current rotation to an integer<br />
rot=$[$[int_rot + 1] % 4]; ## increment the rotation by one and divide by four<br />
fi;<br />
if [ -z "$rot" ]; then ## check if a rotation was specified<br />
echo "Which orientation do you want your display to be?";<br />
select rot in normal left upside-down right; do ## print menu of possible rotations<br />
break; ## break the loop<br />
done;<br />
fi;<br />
if [ -z "$id" ]; then ## if the id of the device is not specified<br />
id=$(xinput -list | awk '/MultiTouch/ {print $6}' | awk -F'=' '{print $2}'); ## get the id of the touch screen<br />
fi;<br />
}<br />
<br />
function resolve-rotate () { ## resolve the touch screen matrix<br />
case $rot in<br />
normal|0)<br />
int_rot=0;<br />
rot_mat="1 0 0 0 1 0"<br />
;;<br />
left|1)<br />
int_rot=1;<br />
rot_mat="0 -1 1 1 0 0"<br />
;;<br />
inverted|upside-down|2)<br />
int_rot=2;<br />
rot_mat="-1 0 1 0 -1 1"<br />
;;<br />
right|3)<br />
int_rot=3;<br />
rot_mat="0 1 0 -1 0 1"<br />
;;<br />
esac;<br />
}<br />
<br />
<br />
## touch cursor jumps around when in any other orientation than normal<br />
function rotate-screen () { ## rotate the touch screen<br />
xrandr -o $int_rot; ## rotate the display screen<br />
xinput set-float-prop $id "Coordinate Transformation Matrix" $rot_mat 0 0 1; ## rotate the touch screen<br />
}<br />
<br />
main $@; ## call the main function and pass console arguments<br />
<br />
</nowiki>}}<br />
<br />
Edit '~/.config/openbox/menu.xml' to include the following code:<br />
<br />
{{bc|<nowiki><br />
<menu id="root-menu-773645" label="Rotate Screen"><br />
<item label="Normal"><br />
<action name="Execute"><br />
<execute><br />
touch_rotate normal<br />
</execute><br />
</action><br />
</item><br />
<item label="Right"><br />
<action name="Execute"><br />
<execute><br />
touch_rotate right<br />
</execute><br />
</action><br />
</item><br />
<item label="Upside Down"><br />
<action name="Execute"><br />
<execute><br />
touch_rotate upside-down<br />
</execute><br />
</action><br />
</item><br />
<item label="Left"><br />
<action name="Execute"><br />
<execute><br />
touch_rotate left<br />
</execute><br />
</action><br />
</item><br />
</nowiki>}}<br />
<br />
You can edit the position of this piece of code (if you know XML) or just add it in somewhere before the last line '</openbox_menu>' of the script. Change the position by using obmenu (GUI interface for editing openbox menu).<br />
<br />
===Xbindkeys===<br />
<br />
Install xbindkeys with {{ic|pacman -S xbindkeys}} and run{{ic|xbindkeys --default >~/.xbindkeysrc}}. Press the express gate button to determine the key code. Copy the resultant output to xbindkeysrc. Change "No command" to "touch_rotate".<br />
<br />
Launch xbindkeys in gnome3 via gnome-session-properties. Add it as a launcher app (xbindkeys).<br />
<br />
===On Screen Keyboard===<br />
<br />
Install kvkbd with from the Arch user repository (if using packer : packer -S kvkbd). Make sure you have some sort of system tray (I used tint2) and edit '~/.config/openbox/autostart' to include the following statement:<br />
{{bc|<br />
kvkbd &<br />
}}<br />
This will start up kvkbd everytime openbox starts up. Once kvkbd is started up it will appear in the system tray, simply clicking the icon in the tray will pop out the virtual keyboard.<br />
<br />
===Suspend2RAM===<br />
<br />
Touchscreen is not working afterwards.<br />
<br />
It will work after you reload hid_multitouch kernel module:<br />
{{bc|<nowiki><br />
# rmmod hid_multitouch<br />
# modprobe hid_multitouch<br />
</nowiki>}}<br />
<br />
As a workaround, you can add the following line to the file '/etc/pm/config.d/modules':<br />
<br />
{{bc|<nowiki><br />
SUSPEND_MODULES="hid_multitouch"<br />
</nowiki>}}<br />
<br />
This way the kernel module will be explicitly unloaded before suspend.<br />
<br />
If you are using twofing you also need to restart it:<br />
{{bc|<nowiki><br />
$ killall twofing<br />
$ twofing --wait<br />
</nowiki>}}<br />
<br />
[http://www.pc-freak.net/blog/setting-script-to-be-executed-before-and-after-suspend-and-resume-in-hibernate-on-debian-squeeze/ This instruction may be useful for solving this problem]<br />
<br />
===Hibernate===<br />
<br />
Not Working.<br />
<br />
===Multi-Touch===<br />
<br />
Modern kernels out-of-the-box support multitouch in our devises, but not Xorg. In Ubuntu there is some Xorg patches for a multitouch support and utouch (ginn) for multitouch gestures, but in other linux distributives you can use twofing. You can find utouch packages in AUR, but they are untested on our device.<br />
<br />
But you can use twofing experimental daemon to use some gestures.<br />
<br />
While we are waiting someone to build AUR packages, we can install it from sources. Get the latest git version [https://aur.archlinux.org/packages.php?ID=55306 here]. <br />
<br />
After this, you must fix '''/etc/udev/rules.d/70-touchscreen-egalax.rules''' file. Replace custom touchscreen code rule to following:<br />
<br />
{{bc|<nowiki><br />
SUBSYSTEMS=="usb",ACTION=="add",KERNEL=="event*",ATTRS{idProduct}=="0186",SYMLINK+="twofingtouch",RUN+="/bin/chmod a+r /dev/twofingtouch"<br />
</nowiki>}}<br />
Replace idProduct variable to idProduct of latest model touchscreen ID. To to check it, try this<br />
{{bc|<nowiki><br />
lsusb | grep "ASUS Comp"</nowiki>}}<br />
Then, create symlink to touchscreen device:<br />
{{bc|<nowiki><br />
ln -s /dev/input/mouse1 /dev/twofingtouch<br />
</nowiki>}}<br />
<br />
Add 'twofing --wait' command to start with user session.<br />
You can read more about it [https://help.ubuntu.com/community/T101MT#Experimental_Two-Finger_Touch_Daemon here].<br />
It works on all linux distributives with actual hid_multitouch module.<br />
<br />
==Brightness==<br />
With some Eee PC's, the brightness setting are either too low, or are sometimes a little inconstant or arbitrary (cycling high/low/completely off).<br />
If you have issues with this, issue this command to fix it:<br />
<br />
And regenerate the grub2 file:<br />
# setpci -s 00:02.0 f4.b=80<br />
<br />
The 80 represents the highest brightness level in hexadecimal, which can be replaced with up to FF if desired. 80 is about half, being approximately the same brightness range as windows or grub.<br />
<br />
This is not perminent, so it can be added to rc.local:<br />
<br />
{{hc|/etc/rc.d/rc.local|2=<br />
#!/bin/sh<br />
<br />
...<br />
<br />
setpci -s 00:02.0 f4.b=80<br />
}}<br />
<br />
==Hardware==<br />
<br />
For N450 versions:<br />
{{bc|<br />
$ lspci<br />
00:00.0 Host bridge: Intel Corporation Pineview DMI Bridge<br />
00:02.0 VGA compatible controller: Intel Corporation Pineview Integrated Graphics Controller<br />
00:02.1 Display controller: Intel Corporation Pineview Integrated Graphics Controller<br />
00:1b.0 Audio device: Intel Corporation 82801G (ICH7 Family) High Definition Audio Controller (rev 02)<br />
00:1c.0 PCI bridge: Intel Corporation 82801G (ICH7 Family) PCI Express Port 1 (rev 02)<br />
00:1c.1 PCI bridge: Intel Corporation 82801G (ICH7 Family) PCI Express Port 2 (rev 02)<br />
00:1c.3 PCI bridge: Intel Corporation 82801G (ICH7 Family) PCI Express Port 4 (rev 02)<br />
00:1d.0 USB Controller: Intel Corporation 82801G (ICH7 Family) USB UHCI Controller #1 (rev 02)<br />
00:1d.1 USB Controller: Intel Corporation 82801G (ICH7 Family) USB UHCI Controller #2 (rev 02)<br />
00:1d.2 USB Controller: Intel Corporation 82801G (ICH7 Family) USB UHCI Controller #3 (rev 02)<br />
00:1d.3 USB Controller: Intel Corporation 82801G (ICH7 Family) USB UHCI Controller #4 (rev 02)<br />
00:1d.7 USB Controller: Intel Corporation 82801G (ICH7 Family) USB2 EHCI Controller (rev 02)<br />
00:1e.0 PCI bridge: Intel Corporation 82801 Mobile PCI Bridge (rev e2)<br />
00:1f.0 ISA bridge: Intel Corporation Tigerpoint LPC Controller (rev 02)<br />
00:1f.2 SATA controller: Intel Corporation 82801GR/GH (ICH7 Family) SATA AHCI Controller (rev 02)<br />
01:00.0 Ethernet controller: Atheros Communications Atheros AR8132 / L1c Gigabit Ethernet Adapter (rev c0)<br />
02:00.0 Network controller: Atheros Communications Inc. AR9285 Wireless Network Adapter (PCI-Express) (rev 01)<br />
}}<br />
<br />
For N570 versions:<br />
{{bc|<br />
00:00.0 Host bridge: Intel Corporation N10 Family DMI Bridge (rev 02)<br />
00:02.0 VGA compatible controller: Intel Corporation N10 Family Integrated Graphics Controller (rev 02)<br />
00:02.1 Display controller: Intel Corporation N10 Family Integrated Graphics Controller (rev 02)<br />
00:1b.0 Audio device: Intel Corporation N10/ICH 7 Family High Definition Audio Controller (rev 02)<br />
00:1c.0 PCI bridge: Intel Corporation N10/ICH 7 Family PCI Express Port 1 (rev 02)<br />
00:1c.1 PCI bridge: Intel Corporation N10/ICH 7 Family PCI Express Port 2 (rev 02)<br />
00:1c.3 PCI bridge: Intel Corporation N10/ICH 7 Family PCI Express Port 4 (rev 02)<br />
00:1d.0 USB Controller: Intel Corporation N10/ICH 7 Family USB UHCI Controller #1 (rev 02)<br />
00:1d.1 USB Controller: Intel Corporation N10/ICH 7 Family USB UHCI Controller #2 (rev 02)<br />
00:1d.2 USB Controller: Intel Corporation N10/ICH 7 Family USB UHCI Controller #3 (rev 02)<br />
00:1d.3 USB Controller: Intel Corporation N10/ICH 7 Family USB UHCI Controller #4 (rev 02)<br />
00:1d.7 USB Controller: Intel Corporation N10/ICH 7 Family USB2 EHCI Controller (rev 02)<br />
00:1e.0 PCI bridge: Intel Corporation 82801 Mobile PCI Bridge (rev e2)<br />
00:1f.0 ISA bridge: Intel Corporation NM10 Family LPC Controller (rev 02)<br />
00:1f.2 SATA controller: Intel Corporation N10/ICH7 Family SATA AHCI Controller (rev 02)<br />
01:00.0 Ethernet controller: Atheros Communications AR8132 Fast Ethernet (rev c0)<br />
02:00.0 Network controller: Atheros Communications Inc. AR9285 Wireless Network Adapter (PCI-Express) (rev 01)<br />
}}<br />
<br />
==More Resources==<br />
* [[Asus Eee PC]] General Guide for EEE PCs on Arch<br />
* [http://ubuntuforums.org/showthread.php?t=1468376 Ubuntu T101MT Howto]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=UEFI_Bootloaders&diff=266672UEFI Bootloaders2013-07-16T22:12:32Z<p>Bluerider: /* Systemd Automation */</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[zh-CN:UEFI Bootloaders]]<br />
This page contains info about various [[UEFI]] Bootloaders capable of booting Linux kernel. It is recommended to read the [[UEFI]] and [[GPT]] pages before reading this page. The following [[Boot Loader|bootloaders]] are explained here:<br />
<br />
== Linux Kernel EFISTUB ==<br />
{{Warning|1=A bug has been noticed where booting EFISTUB can fail depending on kernel version and motherboard model. See [https://bbs.archlinux.org/viewtopic.php?id=156670&p=1] for more information.}}<br />
<br />
Linux (Kernel >= 3.3) supports {{ic|EFISTUB (EFI BOOT STUB)}} booting. It is enabled by default on Arch Linux kernels or can be activated by setting {{ic|CONFIG_EFI_STUB&#61;y}} in the Kernel configuration (see [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/x86/efi-stub.txt;hb=HEAD The EFI Boot Stub] for more information).<br />
<br />
A single EFISTUB kernel is not capable of launching other kernels, hence each EFISTUB Kernel + Initramfs pair requires a separate boot menu entry. It is recommended to use a UEFI Boot Manager to manage multiple kernels.<br />
<br />
=== Setting up EFISTUB ===<br />
<br />
#[https://wiki.archlinux.org/index.php/Unified_Extensible_Firmware_Interface#EFI_System_Partition Create a FAT32 UEFI System Partition]<br />
# Mount the UEFI System Partition at {{ic|/boot/efi}} with {{ic|# mount <UEFI Partition> /boot/efi}} if you're going to be using GRUB2, or at {{ic|/boot}} with {{ic|# mount <UEFI Partition> /boot}} if you're going to be using Gummiboot or rEFInd. Gummiboot cannot boot across partitions, and will never have such capability due to its nature, so it's paramount that you mount the UEFI System Partition at /boot for use with Gummiboot so that the kernel and initramfs lie on the same partition as the bootmanager. {{note| On some machines, when using rEFInd, it works fine when mounting the UEFI partition in {{ic|/boot/efi}}}}<br />
# Create {{ic|/boot/efi/EFI/arch/}} directory with {{ic|# mkdir /boot/efi/EFI/arch/}}<br />
# Copy the following files from source to destination<br />
{| border="1"<br />
!Boot File Source!!UEFI Destination<br />
|-<br />
| /boot/vmlinuz-linux || /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
|-<br />
| /boot/initramfs-linux.img || /boot/efi/EFI/arch/initramfs-arch.img<br />
|-<br />
| /boot/initramfs-linux-fallback.img || /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
|}<br />
{{note| As of {{Pkg|refind-efi}} 0.2.7, you don't need to copy these files, since refind will automatically detect them}}<br />
<br />
=== Sync EFISTUB Kernel ===<br />
{{Warning|The EFISTUB Kernel must be updated each time the kernel is updated (follow step 4 in [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Setting_up_EFISTUB Setting up EFISTUB]. Failure to do so will result in failure to boot. Alternatively one can automatically update the EFISTUB kernel using one of the following methods:}}<br />
<br />
{{Note| As of [https://www.archlinux.org/packages/extra/any/refind-efi/ refind-efi 0.2.7], refind automatically detects kernels in {{ic|/boot}}. They do not have to be renamed to have a {{ic|.efi}} extension either. Hence, the following sync scripts aren't needed if using [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Using_rEFInd refind]. You do need to install an EFI driver to read the Linux filesystem on which the kernel is stored, though. See [http://www.rodsbooks.com/refind/drivers.html]. Briefly, if the /boot is within an ext4 filesystem and the kernel is x64 architecture, you may run "mkdir -p /boot/efi/EFI/refind/drivers; cp /usr/lib/refind/drivers_x64/ext4_x64.efi /boot/efi/EFI/refind/drivers" to install ext4 filesystem driver for 64 bit kernel so that the kernel can be located by the rEFInd.}}<br />
<br />
==== Systemd ====<br />
[[Systemd]] features event triggered tasks. In this particular case, the ability to detect a change in path is used to sync the EFISTUB kernel and initramfs files when they are updated in {{ic|boot}}.<br />
<br />
<br />
{{Warning|Since mkinitcpio takes time to build the kernel stub and the initramfs. It is possible for the following systemd services to copy older kernel stubs and initramfs instead of the new ones. To reduce the chance of this error, it is better to bind the efistub copying service to check if the initramfs-linux-fallback.img was changed (since it is the last thing built by mkinitcpio).}}<br />
{{Tip|Save the following script as {{ic|/usr/lib/systemd/system/efistub-update.path}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Copy EFISTUB Kernel to UEFISYS Partition<br />
<br />
[Path]<br />
PathChanged=/boot/initramfs-linux-fallback.img<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Tip|Save the following script as {{ic|/usr/lib/systemd/system/efistub-update.service}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Copy EFISTUB Kernel to UEFISYS Partition<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/cp -f /boot/vmlinuz-linux /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
ExecStart=/usr/bin/cp -f /boot/initramfs-linux.img /boot/efi/EFI/arch/initramfs-arch.img<br />
ExecStart=/usr/bin/cp -f /boot/initramfs-linux-fallback.img /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
</nowiki>}}<br />
<br />
{{Tip|Enable these services with<br />
{{bc|<nowiki><br />
# systemctl enable efistub-update.path<br />
</nowiki>}}}}<br />
<br />
==== Incron ====<br />
{{Pkg|incron}} can run a script to sync the EFISTUB Kernel after updates<br />
<br />
{{Tip|Save the following script as {{ic|/usr/local/bin/efistub-update.sh}}}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
/usr/bin/cp -f /boot/vmlinuz-linux /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
/usr/bin/cp -f /boot/initramfs-linux.img /boot/efi/EFI/arch/initramfs-arch.img<br />
/usr/bin/cp -f /boot/initramfs-linux-fallback.img /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
</nowiki>}}<br />
<br />
{{Tip|Save the following script as {{ic|/etc/incron.d/efistub-update.conf}}}}<br />
{{Note|The first parameter {{ic|/boot/initramfs-linux-fallback.img}} is the file to watch. The second parameter {{ic|IN_CLOSE_WRITE}} is the action to watch for. The third parameter {{ic|/usr/local/bin/efistub-update.sh}} is the script to execute.}}<br />
{{bc|<nowiki><br />
/boot/initramfs-linux-fallback.img IN_CLOSE_WRITE /usr/local/bin/efistub-update.sh<br />
</nowiki>}}<br />
<br />
{{Tip|In order to use this method, incron must be activated, if it is not run<br />
{{bc|<nowiki><br />
# systemctl enable incrond.service<br />
</nowiki>}}}}<br />
<br />
==== Mkinitcpio hook ====<br />
Mkinitcpio can generate a hook that does not need a system level daemon to function. It spawns a background process which waits for the generation of {{ic|vm-linuz}}, {{ic|initramfs-linux.img}}, and {{ic|initramfs-linux-fallback.img}}; then follows step 4 in [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Setting_up_EFISTUB Setting up EFISTUB]<br />
<br />
{{Tip|Save the following script as {{ic|/usr/lib/initcpio/install/efistub-update}}}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
<br />
build() {<br />
/root/watch.sh &<br />
}<br />
<br />
help() {<br />
cat <<HELPEOF<br />
This hook waits for mkinitcpio to finish and copies the finished ramdisk and kernel to the ESP<br />
HELPEOF<br />
}<br />
</nowiki>}}<br />
<br />
{{Tip|Save the following script as {{ic|/root/watch.sh}} and make it executable}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
<br />
while [[ -d "/proc/$PPID" ]]; do<br />
sleep 1<br />
done<br />
<br />
/usr/bin/cp -f /boot/vmlinuz-linux /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
/usr/bin/cp -f /boot/initramfs-linux.img /boot/efi/EFI/arch/initramfs-arch.img<br />
/usr/bin/cp -f /boot/initramfs-linux-fallback.img /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
<br />
echo "Synced kernel with ESP"<br />
</nowiki>}}<br />
<br />
{{Tip|Add {{ic|efistub-update}} to the list of hooks in {{ic|/etc/mkinitcpio.conf}}}}<br />
<br />
{{Note| As of [https://www.archlinux.org/packages/extra/any/refind-efi/ refind-efi 0.2.7], refind automatically detects kernels in {{ic|/boot}}. They do not have to be renamed to have a {{ic|.efi}} extension either. Hence, the following sync scripts aren't needed if using [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Using_rEFInd refind]. You do need to isntall an EFI driver to read the Linux filesystem on which the kernel is stored, though.}}<br />
<br />
=== Booting EFISTUB ===<br />
<br />
{{Warning|Linux Kernel EFISTUB booting uses {{ic|\}} instead of {{ic|/}} and should be relative to the UEFI System Partition's root. For example, if the initramfs is located in {{ic|/boot/efi/EFI/arch/initramfs-linux.img}}, the corresponding UEFI formatted line would be {{ic|\EFI\arch\initramfs-linux.img}}. Failure to convert the options will lead to a system hang without any error message from the firmware or kernel.<br />
{{Note| Support of initrd path name with {{ic|/}} in EFISTUB booting has been added in [https://patchwork.kernel.org/patch/1899361/ mainline 3.9-rc1] and [http://lwn.net/Articles/541002/ stable 3.8.2]. Leading {{ic|/}} can be ignored but the path still has to be full path. Example: {{ic|initrd&#61;EFI/arch/initramfs-linux.img}} }}<br />
}}<br />
<br />
<br />
<br />
One can boot the EFISTUB kernel using one of the following ways :<br />
<br />
==== Using rEFInd ====<br />
<br />
rEFInd is a fork of rEFIt Boot Manager (used in Intel Macs) by Rod Smith (author of GPT-fdisk). rEFInd fixes many issues in rEFIt with respect to non-Mac UEFI booting and also has support for booting EFISTUB kernels and contains some features specific to them.<br />
{{Tip|If you're new to EFISTUB and/or rEFInd, you need to read [http://www.rodsbooks.com/refind/linux.html The rEFInd Boot Manager: Methods of Booting Linux] before going any further. This section illustrates only one possible use-case which is not suitable for all configurations.}}<br />
# Install {{Pkg|refind-efi}} package with {{ic|# pacman -S refind-efi}}<br />
# Copy the following files from their source directory to their destination<br />
{{Note|1=<arch> is the bit architecture of the system. Run {{ic|$ uname -m}} to get the architecture. Replace <arch> with "ia32" for 32 bit systems, and <arch> with "x64" for 64 bit systems.}}<br />
{| border="1"<br />
!rEFInd File Source!!UEFI Destination<br />
|-<br />
| /usr/lib/refind/refind_<arch>.efi || /boot/efi/EFI/refind/refind_<arch>.efi<br />
|-<br />
| /usr/lib/refind/config/refind.conf || /boot/efi/EFI/refind/refind.conf<br />
|-<br />
| /usr/share/refind/icons || /boot/efi/EFI/refind/icons<br />
|-<br />
| /usr/lib/refind/drivers_<arch> || /boot/efi/EFI/refind/drivers<br />
|}<br />
<br />
{{Tip|Refind's configuration file is located in {{ic|/boot/efi/EFI/refind/refind.conf}}. The file is well commented.}}<br />
<br />
As of {{Pkg|refind-efi}} 0.2.7, refind can auto-detect kernels in {{ic|/boot}}, if there are UEFI drivers for the filesystem used by /boot partition (or / partition if no separate /boot is used) in the ESP, and are loaded by rEFInd. This is enabled in the default configuration in {{ic|refind.conf}} (you may need to include the PATH to the drivers folders in the ESP). Copy your {{ic|/usr/lib/refind/config/refind_linux.conf}} to {{ic|/boot/refind_linux.conf}}. You may pass kernel specific commands in this file. <br />
<br />
Edit the {{ic|refind_linux.conf}} configuration file to be similar to the template below. Replace the string after PARTUUID with your root's PARTUUID<br />
<br />
{{Note|1=Please notice the [https://bbs.archlinux.org/viewtopic.php?pid=1286972 difference] between the standard UUID and the PARTUUID shown by {{ic|$ ls -l /dev/disk/by-partuuid/}}}}<br />
{{hc|refind_linux.conf|<nowiki><br />
"Boot with defaults" "root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 ro rootfstype=ext4 add_efi_memmap systemd.unit=graphical.target"<br />
"Boot to Terminal" "root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 ro rootfstype=ext4 add_efi_memmap systemd.unit=multi-user.target"</nowiki>}}<br />
<br />
{{Tip|Each line of {{ic|refind_linux.conf}} is displayed as a submenu by rEFInd. Access the submenu with "+" or "insert" keys.}}<br />
<br />
{{Tip|In non-Mac systems, create an entry for rEFInd using [[UEFI#efibootmgr|efibootmgr]] where sdX is the UEFI disk, and Y is the UEFI partition number. Run :<br />
{{bc|<nowiki><br />
# modprobe efivars<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_<arch>.efi -L "rEFInd" <br />
</nowiki>}}}}<br />
<br />
===== Systemd Automation =====<br />
<br />
{{Tip|To automate the process of copying refind files and updating the nvram (if needed) use the following script}}<br />
<br />
{{Note|Save this script as {{ic|/usr/lib/systemd/scripts/refind_name_patchv2}}}}<br />
{{Tip|If you want to change the directory that refind is installed in the UEFISYS partition, just change the value of $refind_dir in the script}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
## COPYRIGHT 2013 : MARK E. LEE (BLUERIDER) : mlee24@binghamton.edu; mark@markelee.com<br />
<br />
## LOG<br />
## 1/17/2013 : Version 2 of refind_name_patch is released<br />
## : Supports long subdirectory location for refind<br />
## : Updates nvram when needed<br />
## : 10% speed boost<br />
## 7/15/2013 : Changed arch to match 32-bit (ia32) and 64-bit (x64) naming scheme<br />
## : Changed directory copying in update-efi-dir to copy tools and drivers directories explicitly<br />
## : Changed efibootmgr writing code to be more concise and added (-w) to write the entry as per dusktreader's excellent guide : https://docs.google.com/document/d/1pvgm3BprpXoadsQi38FxqMOCUZhcSqFhZ26FZBkmn9I/edit<br />
## : Function to check if NVRAM boot entry was already listed was fixed to use awk and an if then clause<br />
## : ref_bin_escape was modified from : ref_bin_escape=${ref_bin//\//\\\\} to remove extra backslashes (error does not show up when using cmdline)<br />
<br />
function main () { ## main insertion function<br />
declare -r refind_dir="/boot/efi/EFI/refind"; ## set the refind directory<br />
arch=$(uname -m | awk -F'_' '{if ($1 == "x86") {print "x"$2} else if ($1 == "i686") {print "ia32"}}') && ## get bit architecture<br />
update-efi-dir; ## updates or creates the refind directory<br />
update-efi-nvram; ## updates nvram if needed<br />
}<br />
<br />
function update-efi-dir () { ## setup the refind directory<br />
if [ ! -d $refind_dir ]; then ## check if refind directory exists<br />
echo "Couldn't find $refind_dir";<br />
mkdir $refind_dir && ## make the refind directory if needed<br />
echo "Made $refind_dir";<br />
fi;<br />
if [ "$arch" ]; then ## check if anything was stored in $arch<br />
cp -r /usr/{share/refind/*,lib/refind/{refind_$arch.efi,{tools,drivers}_$arch}} $refind_dir/ && ## update the bins and dirs<br />
echo "Updated binaries and directory files for refind at $refind_dir";<br />
else<br />
echo "Failed to detect an x86 architecture";<br />
exit;<br />
fi;<br />
}<br />
<br />
function update-efi-nvram () { ## update the nvram with efibootmgr<br />
declare -r ref_bin=${refind_dir/\/boot\/efi}/refind_$arch.efi; ## get path of refind binary (without /boot/efi)<br />
declare -r ref_bin_escape=${ref_bin//\//\\}; ## insert escape characters into $ref_bin<br />
modprobe efivars && ## grab the efi variables for efibootmgr<br />
[ "$(efibootmgr -v | awk "/${ref_bin_escape//\\/\\\\}/")" ] && ( ## check if boot entry is in nvram \<br />
echo "Found boot entry, no need to update nvram";<br />
) || ( ## if boot entry is not in nvram; add it<br />
declare -r esp=$(mount -l | awk '/ESP/ {print $1}') && ## get ESP partition<br />
efibootmgr -cgw -d ${esp:0:8} -p ${esp:8} -L "rEFInd" -l $ref_bin_escape && ## update nvram<br />
echo "<br />
Updated nvram with entry rEFInd to boot $ref_bin<br />
Did not copy configuration files, please move refind.conf to $refind_dir/";<br />
)<br />
}<br />
main; ## run the main insertion function<br />
</nowiki>}}<br />
<br />
{{Note| As of [https://www.archlinux.org/packages/extra/any/refind-efi/ refind-efi 0.2.7], refind automatically detects kernels in {{ic|/boot}}. They do not have to be renamed to have a {{ic|.efi}} extension either. Hence, the following sync scripts aren't needed if using [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Using_rEFInd refind]. You do need to isntall an EFI driver to read the Linux filesystem on which the kernel is stored, though.}}<br />
<br />
{{Note|Save the following service file as {{ic|/usr/lib/systemd/system/refind_update.path}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Update rEFInd bootloader files<br />
<br />
[Path]<br />
PathChanged=/usr/lib/refind/refind_<arch>.efi<br />
Unit=refind_update.service<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|Save the following service file as {{ic|/usr/lib/systemd/system/refind_update.service}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Update rEFInd directories, binaries, and nvram<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/bash /usr/lib/systemd/scripts/refind_name_patchv2<br />
RemainAfterExit=no<br />
</nowiki>}}<br />
<br />
{{Tip|Enable the systemd path unit by running :<br />
{{bc|<nowiki><br />
# systemctl enable refind_update.path<br />
</nowiki>}}}}<br />
<br />
===== Apple Macs =====<br />
<br />
In case of Apple Macs, try {{AUR|mactel-boot}} for an experimental "bless" utility for Linux. If that does not work, use "bless" form within OSX to set rEFInd as default bootloader. Assuming UEFISYS partition is mounted at {{ic|/mnt/efi}} within OSX, do<br />
<br />
$ sudo bless --setBoot --folder /mnt/efi/EFI/refind --file /mnt/efi/EFI/refind/refind_x64.efi<br />
<br />
===== VirtualBox =====<br />
<br />
In case of VirtualBox, see [[VirtualBox#Using_Arch_under_Virtualbox_EFI_mode]].<br />
<br />
==== Using gummiboot ====<br />
<br />
[[Gummiboot]] is a UEFI Boot Manager which provides a nice menu for EFISTUB Kernels. It is available in [extra] as {{Pkg|gummiboot}}. See https://wiki.archlinux.org/index.php/Gummiboot for more info.<br />
<br />
==== Using UEFI Shell ====<br />
<br />
It is possible to launch EFISTUB kernel form UEFI Shell as if it is a normal UEFI application. In this case the kernel parameters are passed as normal parameters to the launched EFISTUB kernel file.<br />
<br />
> fs0:<br />
> cd \EFI\arch<br />
> vmlinuz-arch.efi root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 ro rootfstype=ext4 add_efi_memmap initrd=EFI/arch/initramfs-arch.img<br />
<br />
You can also write a simple {{ic|archlinux.nsh}} file with your boot parameters and put it in your UEFI System Partition, then run it with:<br />
<br />
fs0:<br />
archlinux<br />
<br />
Example Script:<br />
<br />
echo -on<br />
\EFI\arch\vmlinuz-arch.efi root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 rootfstype=ext4 add_efi_memmap initrd=EFI/arch/initramfs-arch.img<br />
<br />
This way you can specify UUID's without needing to remember the name or type out 20-30 characters.<br />
<br />
==== Using efibootmgr entry ====<br />
<br />
{{Warning|1=Some kernel and efibootmgr combinations do not work [https://bugs.archlinux.org/task/34641]. You will be able to delete but not create boot entries.}}<br />
<br />
{{Note|Some UEFI firmwares may not support embedding command line parameters to uefi applications in the boot entries.}}<br />
<br />
It is possible to directly embed the kernel parameters within the boot entry created by efibootmgr. This means that in your BIOS/UEFI you will be able to select Arch Linux directly in the default boot order, and on startup it will boot into Arch directly without any kind of boot selection GUI.<br />
<br />
# modprobe efivars<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/arch/vmlinuz-arch.efi -L "Arch Linux (EFISTUB)" -u "$(cat /proc/cmdline)"<br />
<br />
It is a good idea to run<br />
<br />
# efibootmgr -v<br />
<br />
to verify that the resulting entry is correct. You should also consider reordering the boot options ({{ic|efibootmgr -o}}) to place the Arch entry last, which could make the system easier to recover if it fails.<br />
<br />
More info about efibootmgr at [[UEFI#efibootmgr]]. Forum post https://bbs.archlinux.org/viewtopic.php?pid=1090040#p1090040 .<br />
<br />
== GRUB 2.xx ==<br />
<br />
GRUB 2.x contains its own filesystem drivers and does not rely on the firmware to access the files. It can directly read files from {{ic|/boot}} and does not require the kernel and initramfs files to be in the UEFISYS partition. Detailed information at [[GRUB#UEFI_systems_2]]. For bzr development version try AUR package - {{AUR|grub-bzr}}.<br />
<br />
== SYSLINUX 6.xx ==<br />
<br />
Install {{Pkg|syslinux}} (from [testing]) or {{AUR|syslinux-firmware-git}} AUR package and copy {{ic|/usr/lib/syslinux/efi64/*}} to {{ic|$esp/EFI/syslinux/}} ({{ic|$esp}} is the mountpoint of UEFISYS partition) ({{ic|efi64}} is for x86_64 UEFI firmwares, replace with {{ic|efi32}} for ia32 UEFI firmwares), and then create a boot entry using efibootmgr in the firmware boot manager.<br />
<br />
== ELILO ==<br />
<br />
ELILO is the UEFI version of LILO Boot Loader. It was originally created for Intel Itanium systems which supported only EFI (precursor to UEFI). It is the oldest UEFI bootloader for Linux. It is still in development but happens at a very slow pace. Upstream provided compiled binaries are available at http://sourceforge.net/projects/elilo/ . Elilo config file {{ic|elilo.conf}} is similar to [[LILO]]'s config file. AUR package - {{AUR|elilo-efi}}.<br />
<br />
== EFILINUX ==<br />
<br />
EFILINUX is the precursor to Kernel EFISTUB support. It can be used to boot kernel that do not support EFISTUB (mainly LTS kernels). It is not necessary to use efilinux if the kernel supports EFISTUB. <br />
<br />
It is available in the [extra] as {{Pkg|efilinux-efi}}. Upstream sources are at https://git.kernel.org/cgit/boot/efilinux/efilinux.git/ and the usage instructions are at http://thread.gmane.org/gmane.linux.kernel/1172645 and http://article.gmane.org/gmane.linux.kernel/1175060 .<br />
<br />
== See also ==<br />
<br />
* [http://www.rodsbooks.com/efi-bootloaders/ Rod Smith - Managing EFI Boot Loaders for Linux]<br />
* [http://www.rodsbooks.com/refind/ Rod Smith - rEFInd, a fork or rEFIt]<br />
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/x86/efi-stub.txt;hb=HEAD Linux Kernel Documentation on EFISTUB]<br />
* [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=commitdiff;h=291f36325f9f252bd76ef5f603995f37e453fc60;hp=55839d515495e766605d7aaabd9c2758370a8d27 Linux Kernel EFISTUB Git Commit]<br />
* [http://www.rodsbooks.com/efi-bootloaders/efistub.html Rod Smith's page on EFISTUB]<br />
* [http://www.rodsbooks.com/refind/linux.html rEFInd Documentation for booting EFISTUB Kernels]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=UEFI_Bootloaders&diff=266450UEFI Bootloaders2013-07-15T19:51:27Z<p>Bluerider: /* Systemd Automation */ Update to refind crashed my system, I looked closely and found directories had changed (yet again) without being notified. I did an overhaul of the script I used to automate the updating process and tested it.</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[zh-CN:UEFI Bootloaders]]<br />
This page contains info about various [[UEFI]] Bootloaders capable of booting Linux kernel. It is recommended to read the [[UEFI]] and [[GPT]] pages before reading this page. The following [[Boot Loader|bootloaders]] are explained here:<br />
<br />
== Linux Kernel EFISTUB ==<br />
{{Warning|1=A bug has been noticed where booting EFISTUB can fail depending on kernel version and motherboard model. See [https://bbs.archlinux.org/viewtopic.php?id=156670&p=1] for more information.}}<br />
<br />
Linux (Kernel >= 3.3) supports {{ic|EFISTUB (EFI BOOT STUB)}} booting. It is enabled by default on Arch Linux kernels or can be activated by setting {{ic|CONFIG_EFI_STUB&#61;y}} in the Kernel configuration (see [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/x86/efi-stub.txt;hb=HEAD The EFI Boot Stub] for more information).<br />
<br />
A single EFISTUB kernel is not capable of launching other kernels, hence each EFISTUB Kernel + Initramfs pair requires a separate boot menu entry. It is recommended to use a UEFI Boot Manager to manage multiple kernels.<br />
<br />
=== Setting up EFISTUB ===<br />
<br />
#[https://wiki.archlinux.org/index.php/Unified_Extensible_Firmware_Interface#EFI_System_Partition Create a FAT32 UEFI System Partition]<br />
# Mount the UEFI System Partition at {{ic|/boot/efi}} with {{ic|# mount <UEFI Partition> /boot/efi}} if you're going to be using GRUB2, or at {{ic|/boot}} with {{ic|# mount <UEFI Partition> /boot}} if you're going to be using Gummiboot or rEFInd. Gummiboot cannot boot across partitions, and will never have such capability due to its nature, so it's paramount that you mount the UEFI System Partition at /boot for use with Gummiboot so that the kernel and initramfs lie on the same partition as the bootmanager. {{note| On some machines, when using rEFInd, it works fine when mounting the UEFI partition in {{ic|/boot/efi}}}}<br />
# Create {{ic|/boot/efi/EFI/arch/}} directory with {{ic|# mkdir /boot/efi/EFI/arch/}}<br />
# Copy the following files from source to destination<br />
{| border="1"<br />
!Boot File Source!!UEFI Destination<br />
|-<br />
| /boot/vmlinuz-linux || /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
|-<br />
| /boot/initramfs-linux.img || /boot/efi/EFI/arch/initramfs-arch.img<br />
|-<br />
| /boot/initramfs-linux-fallback.img || /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
|}<br />
{{note| As of {{Pkg|refind-efi}} 0.2.7, you don't need to copy these files, since refind will automatically detect them}}<br />
<br />
=== Sync EFISTUB Kernel ===<br />
{{Warning|The EFISTUB Kernel must be updated each time the kernel is updated (follow step 4 in [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Setting_up_EFISTUB Setting up EFISTUB]. Failure to do so will result in failure to boot. Alternatively one can automatically update the EFISTUB kernel using one of the following methods:}}<br />
<br />
{{Note| As of [https://www.archlinux.org/packages/extra/any/refind-efi/ refind-efi 0.2.7], refind automatically detects kernels in {{ic|/boot}}. They do not have to be renamed to have a {{ic|.efi}} extension either. Hence, the following sync scripts aren't needed if using [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Using_rEFInd refind]. You do need to install an EFI driver to read the Linux filesystem on which the kernel is stored, though. See [http://www.rodsbooks.com/refind/drivers.html]. Briefly, if the /boot is within an ext4 filesystem and the kernel is x64 architecture, you may run "mkdir -p /boot/efi/EFI/refind/drivers; cp /usr/lib/refind/drivers_x64/ext4_x64.efi /boot/efi/EFI/refind/drivers" to install ext4 filesystem driver for 64 bit kernel so that the kernel can be located by the rEFInd.}}<br />
<br />
==== Systemd ====<br />
[[Systemd]] features event triggered tasks. In this particular case, the ability to detect a change in path is used to sync the EFISTUB kernel and initramfs files when they are updated in {{ic|boot}}.<br />
<br />
<br />
{{Warning|Since mkinitcpio takes time to build the kernel stub and the initramfs. It is possible for the following systemd services to copy older kernel stubs and initramfs instead of the new ones. To reduce the chance of this error, it is better to bind the efistub copying service to check if the initramfs-linux-fallback.img was changed (since it is the last thing built by mkinitcpio).}}<br />
{{Tip|Save the following script as {{ic|/usr/lib/systemd/system/efistub-update.path}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Copy EFISTUB Kernel to UEFISYS Partition<br />
<br />
[Path]<br />
PathChanged=/boot/initramfs-linux-fallback.img<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Tip|Save the following script as {{ic|/usr/lib/systemd/system/efistub-update.service}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Copy EFISTUB Kernel to UEFISYS Partition<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/cp -f /boot/vmlinuz-linux /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
ExecStart=/usr/bin/cp -f /boot/initramfs-linux.img /boot/efi/EFI/arch/initramfs-arch.img<br />
ExecStart=/usr/bin/cp -f /boot/initramfs-linux-fallback.img /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
</nowiki>}}<br />
<br />
{{Tip|Enable these services with<br />
{{bc|<nowiki><br />
# systemctl enable efistub-update.path<br />
</nowiki>}}}}<br />
<br />
==== Incron ====<br />
{{Pkg|incron}} can run a script to sync the EFISTUB Kernel after updates<br />
<br />
{{Tip|Save the following script as {{ic|/usr/local/bin/efistub-update.sh}}}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
/usr/bin/cp -f /boot/vmlinuz-linux /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
/usr/bin/cp -f /boot/initramfs-linux.img /boot/efi/EFI/arch/initramfs-arch.img<br />
/usr/bin/cp -f /boot/initramfs-linux-fallback.img /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
</nowiki>}}<br />
<br />
{{Tip|Save the following script as {{ic|/etc/incron.d/efistub-update.conf}}}}<br />
{{Note|The first parameter {{ic|/boot/initramfs-linux-fallback.img}} is the file to watch. The second parameter {{ic|IN_CLOSE_WRITE}} is the action to watch for. The third parameter {{ic|/usr/local/bin/efistub-update.sh}} is the script to execute.}}<br />
{{bc|<nowiki><br />
/boot/initramfs-linux-fallback.img IN_CLOSE_WRITE /usr/local/bin/efistub-update.sh<br />
</nowiki>}}<br />
<br />
{{Tip|In order to use this method, incron must be activated, if it is not run<br />
{{bc|<nowiki><br />
# systemctl enable incrond.service<br />
</nowiki>}}}}<br />
<br />
==== Mkinitcpio hook ====<br />
Mkinitcpio can generate a hook that does not need a system level daemon to function. It spawns a background process which waits for the generation of {{ic|vm-linuz}}, {{ic|initramfs-linux.img}}, and {{ic|initramfs-linux-fallback.img}}; then follows step 4 in [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Setting_up_EFISTUB Setting up EFISTUB]<br />
<br />
{{Tip|Save the following script as {{ic|/usr/lib/initcpio/install/efistub-update}}}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
<br />
build() {<br />
/root/watch.sh &<br />
}<br />
<br />
help() {<br />
cat <<HELPEOF<br />
This hook waits for mkinitcpio to finish and copies the finished ramdisk and kernel to the ESP<br />
HELPEOF<br />
}<br />
</nowiki>}}<br />
<br />
{{Tip|Save the following script as {{ic|/root/watch.sh}} and make it executable}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
<br />
while [[ -d "/proc/$PPID" ]]; do<br />
sleep 1<br />
done<br />
<br />
/usr/bin/cp -f /boot/vmlinuz-linux /boot/efi/EFI/arch/vmlinuz-arch.efi<br />
/usr/bin/cp -f /boot/initramfs-linux.img /boot/efi/EFI/arch/initramfs-arch.img<br />
/usr/bin/cp -f /boot/initramfs-linux-fallback.img /boot/efi/EFI/arch/initramfs-arch-fallback.img<br />
<br />
echo "Synced kernel with ESP"<br />
</nowiki>}}<br />
<br />
{{Tip|Add {{ic|efistub-update}} to the list of hooks in {{ic|/etc/mkinitcpio.conf}}}}<br />
<br />
{{Note| As of [https://www.archlinux.org/packages/extra/any/refind-efi/ refind-efi 0.2.7], refind automatically detects kernels in {{ic|/boot}}. They do not have to be renamed to have a {{ic|.efi}} extension either. Hence, the following sync scripts aren't needed if using [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Using_rEFInd refind]. You do need to isntall an EFI driver to read the Linux filesystem on which the kernel is stored, though.}}<br />
<br />
=== Booting EFISTUB ===<br />
<br />
{{Warning|Linux Kernel EFISTUB booting uses {{ic|\}} instead of {{ic|/}} and should be relative to the UEFI System Partition's root. For example, if the initramfs is located in {{ic|/boot/efi/EFI/arch/initramfs-linux.img}}, the corresponding UEFI formatted line would be {{ic|\EFI\arch\initramfs-linux.img}}. Failure to convert the options will lead to a system hang without any error message from the firmware or kernel.<br />
{{Note| Support of initrd path name with {{ic|/}} in EFISTUB booting has been added in [https://patchwork.kernel.org/patch/1899361/ mainline 3.9-rc1] and [http://lwn.net/Articles/541002/ stable 3.8.2]. Leading {{ic|/}} can be ignored but the path still has to be full path. Example: {{ic|initrd&#61;EFI/arch/initramfs-linux.img}} }}<br />
}}<br />
<br />
<br />
<br />
One can boot the EFISTUB kernel using one of the following ways :<br />
<br />
==== Using rEFInd ====<br />
<br />
rEFInd is a fork of rEFIt Boot Manager (used in Intel Macs) by Rod Smith (author of GPT-fdisk). rEFInd fixes many issues in rEFIt with respect to non-Mac UEFI booting and also has support for booting EFISTUB kernels and contains some features specific to them.<br />
{{Tip|If you're new to EFISTUB and/or rEFInd, you need to read [http://www.rodsbooks.com/refind/linux.html The rEFInd Boot Manager: Methods of Booting Linux] before going any further. This section illustrates only one possible use-case which is not suitable for all configurations.}}<br />
# Install {{Pkg|refind-efi}} package with {{ic|# pacman -S refind-efi}}<br />
# Copy the following files from their source directory to their destination<br />
{{Note|1=<arch> is the bit architecture of the system. Run {{ic|$ uname -m}} to get the architecture. Replace <arch> with "ia32" for 32 bit systems, and <arch> with "x64" for 64 bit systems.}}<br />
{| border="1"<br />
!rEFInd File Source!!UEFI Destination<br />
|-<br />
| /usr/lib/refind/refind_<arch>.efi || /boot/efi/EFI/refind/refind_<arch>.efi<br />
|-<br />
| /usr/lib/refind/config/refind.conf || /boot/efi/EFI/refind/refind.conf<br />
|-<br />
| /usr/share/refind/icons || /boot/efi/EFI/refind/icons<br />
|-<br />
| /usr/lib/refind/drivers_<arch> || /boot/efi/EFI/refind/drivers<br />
|}<br />
<br />
{{Tip|Refind's configuration file is located in {{ic|/boot/efi/EFI/refind/refind.conf}}. The file is well commented.}}<br />
<br />
As of {{Pkg|refind-efi}} 0.2.7, refind can auto-detect kernels in {{ic|/boot}}, if there are UEFI drivers for the filesystem used by /boot partition (or / partition if no separate /boot is used) in the ESP, and are loaded by rEFInd. This is enabled in the default configuration in {{ic|refind.conf}} (you may need to include the PATH to the drivers folders in the ESP). Copy your {{ic|/usr/lib/refind/config/refind_linux.conf}} to {{ic|/boot/refind_linux.conf}}. You may pass kernel specific commands in this file. <br />
<br />
Edit the {{ic|refind_linux.conf}} configuration file to be similar to the template below. Replace the string after PARTUUID with your root's PARTUUID<br />
<br />
{{Note|1=Please notice the [https://bbs.archlinux.org/viewtopic.php?pid=1286972 difference] between the standard UUID and the PARTUUID shown by {{ic|$ ls -l /dev/disk/by-partuuid/}}}}<br />
{{hc|refind_linux.conf|<nowiki><br />
"Boot with defaults" "root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 ro rootfstype=ext4 add_efi_memmap systemd.unit=graphical.target"<br />
"Boot to Terminal" "root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 ro rootfstype=ext4 add_efi_memmap systemd.unit=multi-user.target"</nowiki>}}<br />
<br />
{{Tip|Each line of {{ic|refind_linux.conf}} is displayed as a submenu by rEFInd. Access the submenu with "+" or "insert" keys.}}<br />
<br />
{{Tip|In non-Mac systems, create an entry for rEFInd using [[UEFI#efibootmgr|efibootmgr]] where sdX is the UEFI disk, and Y is the UEFI partition number. Run :<br />
{{bc|<nowiki><br />
# modprobe efivars<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_<arch>.efi -L "rEFInd" <br />
</nowiki>}}}}<br />
<br />
===== Systemd Automation =====<br />
<br />
{{Tip|To automate the process of copying refind files and updating the nvram (if needed) use the following script}}<br />
<br />
{{Note|Save this script as {{ic|/usr/lib/systemd/scripts/refind_name_patchv2}}}}<br />
{{Tip|If you want to change the directory that refind is installed in the UEFISYS partition, just change the value of $refind_dir in the script}}<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
## COPYRIGHT 2013 : MARK E. LEE (BLUERIDER) : mlee24@binghamton.edu; mark@markelee.com<br />
<br />
## LOG<br />
## 1/17/2013 : Version 2 of refind_name_patch is released<br />
## : Supports long subdirectory location for refind<br />
## : Updates nvram when needed<br />
## : 10% speed boost<br />
## 7/15/2013 : Changed arch to match 32-bit (ia32) and 64-bit (x64) naming scheme<br />
## : Changed directory copying in update-efi-dir to copy tools and drivers directories explicitly<br />
## : Changed efibootmgr writing code to be more concise and added (-w) to write the entry as per dusktreader's excellent guide : https://docs.google.com/document/d/1pvgm3BprpXoadsQi38FxqMOCUZhcSqFhZ26FZBkmn9I/edit<br />
<br />
function main () { ## main insertion function<br />
declare -r refind_dir="/boot/efi/EFI/refind"; ## set the refind directory<br />
arch=$(uname -m | awk -F'_' '{if ($1 == "x86") {print "x"$2} else if ($1 == "i686") {print "ia32"}}') && ## get bit architecture<br />
update-efi-dir; ## updates or creates the refind directory<br />
update-efi-nvram; ## updates nvram if needed<br />
}<br />
<br />
function update-efi-dir () { ## setup the refind directory<br />
if [ ! -d $refind_dir ]; then ## check if refind directory exists<br />
echo "Couldn't find $refind_dir";<br />
mkdir $refind_dir && ## make the refind directory if needed<br />
echo "Made $refind_dir";<br />
fi;<br />
if [ "$arch" ]; then ## check if anything was stored in $arch<br />
cp -r /usr/{share/refind/*,lib/refind/{refind_$arch.efi,{tools,drivers}_$arch}} $refind_dir/ && ## update the bins and dirs<br />
echo "Updated binaries and directory files for refind at $refind_dir";<br />
else<br />
echo "Failed to detect an x86 architecture";<br />
exit;<br />
fi;<br />
}<br />
<br />
function update-efi-nvram () { ## update the nvram with efibootmgr<br />
declare -r ref_bin=${refind_dir/\/boot\/efi}/refind_$arch.efi; ## get path of refind binary (without /boot/efi)<br />
declare -r ref_bin_escape=${ref_bin//\//\\\\}; ## insert escape characters into $ref_bin<br />
modprobe efivars && ## grab the efi variables for efibootmgr<br />
efibootmgr -v | grep $ref_bin_escape && ( ## check if boot entry is in nvram<br />
echo "Found boot entry, no need to update nvram";<br />
) || ( ## if boot entry is not in nvram; add it<br />
declare -r esp=$(mount -l | awk '/ESP/ {print $1}') && ## get ESP partition<br />
efibootmgr -cgw -d ${esp:0:8} -p ${esp:8} -L "rEFInd" -l $ref_bin_escape && ## update nvram<br />
echo "<br />
Updated nvram with entry rEFInd to boot $ref_bin<br />
Did not copy configuration files, please move refind.conf to $refind_dir/";<br />
)<br />
}<br />
<br />
main; ## run the main insertion function<br />
</nowiki>}}<br />
<br />
{{Note| As of [https://www.archlinux.org/packages/extra/any/refind-efi/ refind-efi 0.2.7], refind automatically detects kernels in {{ic|/boot}}. They do not have to be renamed to have a {{ic|.efi}} extension either. Hence, the following sync scripts aren't needed if using [https://wiki.archlinux.org/index.php/UEFI_Bootloaders#Using_rEFInd refind]. You do need to isntall an EFI driver to read the Linux filesystem on which the kernel is stored, though.}}<br />
<br />
{{Note|Save the following service file as {{ic|/usr/lib/systemd/system/refind_update.path}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Update rEFInd bootloader files<br />
<br />
[Path]<br />
PathChanged=/usr/lib/refind/refind_<arch>.efi<br />
Unit=refind_update.service<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|Save the following service file as {{ic|/usr/lib/systemd/system/refind_update.service}}}}<br />
{{bc|<nowiki><br />
[Unit]<br />
Description=Update rEFInd directories, binaries, and nvram<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/bash /usr/lib/systemd/scripts/refind_name_patchv2<br />
RemainAfterExit=no<br />
</nowiki>}}<br />
<br />
{{Tip|Enable the systemd path unit by running :<br />
{{bc|<nowiki><br />
# systemctl enable refind_update.path<br />
</nowiki>}}}}<br />
<br />
===== Apple Macs =====<br />
<br />
In case of Apple Macs, try {{AUR|mactel-boot}} for an experimental "bless" utility for Linux. If that does not work, use "bless" form within OSX to set rEFInd as default bootloader. Assuming UEFISYS partition is mounted at {{ic|/mnt/efi}} within OSX, do<br />
<br />
$ sudo bless --setBoot --folder /mnt/efi/EFI/refind --file /mnt/efi/EFI/refind/refind_x64.efi<br />
<br />
===== VirtualBox =====<br />
<br />
In case of VirtualBox, see [[VirtualBox#Using_Arch_under_Virtualbox_EFI_mode]].<br />
<br />
==== Using gummiboot ====<br />
<br />
[[Gummiboot]] is a UEFI Boot Manager which provides a nice menu for EFISTUB Kernels. It is available in [extra] as {{Pkg|gummiboot}}. See https://wiki.archlinux.org/index.php/Gummiboot for more info.<br />
<br />
==== Using UEFI Shell ====<br />
<br />
It is possible to launch EFISTUB kernel form UEFI Shell as if it is a normal UEFI application. In this case the kernel parameters are passed as normal parameters to the launched EFISTUB kernel file.<br />
<br />
> fs0:<br />
> cd \EFI\arch<br />
> vmlinuz-arch.efi root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 ro rootfstype=ext4 add_efi_memmap initrd=EFI/arch/initramfs-arch.img<br />
<br />
You can also write a simple {{ic|archlinux.nsh}} file with your boot parameters and put it in your UEFI System Partition, then run it with:<br />
<br />
fs0:<br />
archlinux<br />
<br />
Example Script:<br />
<br />
echo -on<br />
\EFI\arch\vmlinuz-arch.efi root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 rootfstype=ext4 add_efi_memmap initrd=EFI/arch/initramfs-arch.img<br />
<br />
This way you can specify UUID's without needing to remember the name or type out 20-30 characters.<br />
<br />
==== Using efibootmgr entry ====<br />
<br />
{{Warning|1=Some kernel and efibootmgr combinations do not work [https://bugs.archlinux.org/task/34641]. You will be able to delete but not create boot entries.}}<br />
<br />
{{Note|Some UEFI firmwares may not support embedding command line parameters to uefi applications in the boot entries.}}<br />
<br />
It is possible to directly embed the kernel parameters within the boot entry created by efibootmgr. This means that in your BIOS/UEFI you will be able to select Arch Linux directly in the default boot order, and on startup it will boot into Arch directly without any kind of boot selection GUI.<br />
<br />
# modprobe efivars<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/arch/vmlinuz-arch.efi -L "Arch Linux (EFISTUB)" -u "$(cat /proc/cmdline)"<br />
<br />
It is a good idea to run<br />
<br />
# efibootmgr -v<br />
<br />
to verify that the resulting entry is correct. You should also consider reordering the boot options ({{ic|efibootmgr -o}}) to place the Arch entry last, which could make the system easier to recover if it fails.<br />
<br />
More info about efibootmgr at [[UEFI#efibootmgr]]. Forum post https://bbs.archlinux.org/viewtopic.php?pid=1090040#p1090040 .<br />
<br />
== GRUB 2.xx ==<br />
<br />
GRUB 2.x contains its own filesystem drivers and does not rely on the firmware to access the files. It can directly read files from {{ic|/boot}} and does not require the kernel and initramfs files to be in the UEFISYS partition. Detailed information at [[GRUB#UEFI_systems_2]]. For bzr development version try AUR package - {{AUR|grub-bzr}}.<br />
<br />
== SYSLINUX 6.xx ==<br />
<br />
Install {{Pkg|syslinux}} (from [testing]) or {{AUR|syslinux-firmware-git}} AUR package and copy {{ic|/usr/lib/syslinux/efi64/*}} to {{ic|$esp/EFI/syslinux/}} ({{ic|$esp}} is the mountpoint of UEFISYS partition) ({{ic|efi64}} is for x86_64 UEFI firmwares, replace with {{ic|efi32}} for ia32 UEFI firmwares), and then create a boot entry using efibootmgr in the firmware boot manager.<br />
<br />
== ELILO ==<br />
<br />
ELILO is the UEFI version of LILO Boot Loader. It was originally created for Intel Itanium systems which supported only EFI (precursor to UEFI). It is the oldest UEFI bootloader for Linux. It is still in development but happens at a very slow pace. Upstream provided compiled binaries are available at http://sourceforge.net/projects/elilo/ . Elilo config file {{ic|elilo.conf}} is similar to [[LILO]]'s config file. AUR package - {{AUR|elilo-efi}}.<br />
<br />
== EFILINUX ==<br />
<br />
EFILINUX is the precursor to Kernel EFISTUB support. It can be used to boot kernel that do not support EFISTUB (mainly LTS kernels). It is not necessary to use efilinux if the kernel supports EFISTUB. <br />
<br />
It is available in the [extra] as {{Pkg|efilinux-efi}}. Upstream sources are at https://git.kernel.org/cgit/boot/efilinux/efilinux.git/ and the usage instructions are at http://thread.gmane.org/gmane.linux.kernel/1172645 and http://article.gmane.org/gmane.linux.kernel/1175060 .<br />
<br />
== See also ==<br />
<br />
* [http://www.rodsbooks.com/efi-bootloaders/ Rod Smith - Managing EFI Boot Loaders for Linux]<br />
* [http://www.rodsbooks.com/refind/ Rod Smith - rEFInd, a fork or rEFIt]<br />
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/x86/efi-stub.txt;hb=HEAD Linux Kernel Documentation on EFISTUB]<br />
* [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=commitdiff;h=291f36325f9f252bd76ef5f603995f37e453fc60;hp=55839d515495e766605d7aaabd9c2758370a8d27 Linux Kernel EFISTUB Git Commit]<br />
* [http://www.rodsbooks.com/efi-bootloaders/efistub.html Rod Smith's page on EFISTUB]<br />
* [http://www.rodsbooks.com/refind/linux.html rEFInd Documentation for booting EFISTUB Kernels]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=GNOME&diff=265731GNOME2013-07-10T16:10:42Z<p>Bluerider: /* Troubleshooting */</p>
<hr />
<div>[[Category:GNOME| ]]<br />
[[cs:GNOME]]<br />
[[de:GNOME]]<br />
[[es:GNOME]]<br />
[[fr:GNOME]]<br />
[[it:GNOME]]<br />
[[ja:GNOME]]<br />
[[nl:GNOME]]<br />
[[pl:GNOME]]<br />
[[pt:GNOME]]<br />
[[ru:GNOME]]<br />
[[sr:GNOME]]<br />
[[th:GNOME]]<br />
[[tr:Gnome_Masaüstü_Ortamı]]<br />
[[uk:GNOME]]<br />
[[zh-CN:GNOME]]<br />
[[zh-TW:GNOME]]<br />
{{Article summary start}}<br />
{{Article summary text|GNOME 3 provides a modern desktop, rewritten from scratch, using the GTK3+ toolkit.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Graphical user interface overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|GTK+}}<br />
{{Article summary wiki|GDM}}<br />
{{Article summary wiki|Nautilus}}<br />
{{Article summary end}}<br />
<br />
From [http://www.gnome.org/about/ About Us | GNOME]:<br />
<br />
:''The GNOME Project was started in 1997 by two then university students, Miguel de Icaza and Federico Mena. Their aim: to produce a free (as in freedom) [[desktop environment]]. Since then, GNOME has grown into a hugely successful enterprise. Used by millions of people across the world, it is the most popular desktop environment for GNU/Linux and UNIX-type operating systems. The desktop has been utilised in successful, large-scale enterprise and public deployments, and the project’s developer technologies are utilised in a large number of popular mobile devices.''<br />
<br />
== Introduction ==<br />
<br />
GNOME 3 has ''two'' interfaces:<br />
<br />
*'''GNOME Shell''' is the new standard layout using the Mutter window manager. It acts as a composite manager for the desktop, employing hardware graphics acceleration to provide effects aimed at reducing screen clutter.<br />
<br />
*'''Classic mode''' is the successor of the discontinued "fallback mode" starting with GNOME 3.8. It aims at implementing a more traditional desktop interface while using standard GNOME 3 technologies (including graphic acceleration). It does so through the use of pre-activated extensions and parameters (see [http://worldofgnome.org/welcome-to-gnome-3-8-flintstones-mode/ here] for a list) and relies on llvmpipe for graphic acceleration. Hence it consists more of a customized GNOME Shell than a truly distinct mode.<br />
<br />
GNOME-session automatically detects if your computer is incapable of running GNOME Shell and starts Classic mode with llvmpipe when appropriate.<br />
<br />
==Installation==<br />
<br />
GNOME 3 is available in the [[official repositories]] and can be [[pacman|installed]] with two groups of packages:<br />
*{{Grp|gnome}} contains the core desktop environment and applications required for the standard GNOME experience.<br />
<br />
*{{Grp|gnome-extra}} contains various optional tools such as a media player, a calculator, an editor and other non-critical applications that go well with the GNOME desktop. Installing this group is optional.<br />
<br />
Note that installing only {{Grp|gnome-extra}} will not pull the whole {{Grp|gnome}} group by dependencies: if you really want everything you must explicitly install both groups.<br />
<br />
=== Starting GNOME ===<br />
<br />
'''Graphical log-in'''<br />
<br />
For the best desktop integration, login manager '''GDM''' is recommended. Other login managers can be used in place of GDM. Check out the [[Display_Manager|wiki article on display managers]] to learn how desktop environments are started.<br />
<br />
The login manager is a limited process entrusted with duties that impact the system. The [[PolicyKit|PolicyKit wiki article]] addresses the topic of system‑wide access control.<br />
<br />
{{Tip|Refer to the [[GDM]] article for installation and configuration instructions.}}<br />
<br />
'''Starting GNOME manually'''<br />
<br />
If you prefer to start GNOME manually from the console, add the following line to your {{ic|~/.xinitrc}} file:<br />
{{hc|~/.xinitrc|<nowiki><br />
exec gnome-session<br />
</nowiki>}}<br />
<br />
After the {{ic|exec}} command is placed, GNOME can be launched by typing {{ic|startx}}.<br />
<br />
See [[xinitrc]] for details, such as preserving the logind (and/or consolekit) session.<br />
<br />
== Using the shell ==<br />
<br />
=== GNOME cheat sheet ===<br />
<br />
The GNOME web site has a helpful [https://live.gnome.org/GnomeShell/CheatSheet GNOME Shell cheat sheet] explaining task switching, keyboard use, window control, the panel, overview mode, and more.<br />
<br />
=== Restarting the shell ===<br />
<br />
After appearance tweaks you are often asked to restart the GNOME shell. You could log out and log back in, but it is simpler and faster to issue the following keyboard command. Restart the shell by pressing {{Keypress|Alt}} + {{Keypress|F2}} then {{Keypress|r}} then {{Keypress|Enter}}<br />
<br />
=== Shell crashes ===<br />
<br />
Certain tweaks and/or repeated shell restarts may cause the shell to crash when a restart is attempted. In this case, you are informed about the crash and then forced to log out. Some shell changes, such as switching between '''''GNOME Shell''''' and '''''fallback mode,''''' cannot be accomplished via a keyboard restart; you must log out and log back in to effect them.<br />
<br />
It is common sense — but worth repeating — that valuable documents should be saved (and perhaps closed) before attempting a shell restart. It is not strictly necessary; open windows and documents usually remain intact after a shell restart.<br />
<br />
=== Shell freezes ===<br />
<br />
Sometimes shell extensions freeze the GNOME Shell. In this case a possible strategy is to switch to another terminal via {{Keypress|Ctrl+Alt+F2}} through {{Keypress|Ctrl+Alt+F6}}, log in, and restart gnome-shell with:<br />
<br />
# pkill -HUP gnome-shell<br />
<br />
All open applications will still be available after restarting the shell.<br />
<br />
Sometimes, however, merely restarting the shell might not be enough. Then you will have to restart X, losing all work in progress. You can restart X by:<br />
<br />
# pkill X<br />
<br />
The GNOME Shell then restarts automatically.<br />
<br />
If this doesn't work, you can try to restart your login manager. For instance, if you use GDM, try:<br />
<br />
# systemctl restart gdm.service<br />
<br />
{{Tip|You can also use '''htop''' in tty; press ''t'', select the ''gnome-shell'' tree, press ''k'' and send ''SIGKILL''.}}<br />
<br />
== Customizing GNOME appearance ==<br />
<br />
=== Overall appearance ===<br />
<br />
GNOME 3 may have "started from scratch", but like most large software projects it is assembled from parts dating to different eras. There is not '''one''' all-encompassing configuration tool. The new ''Systems Settings'' tool is a big improvement over previous control panels. ''System Settings'' is well-organized, but you may find yourself wishing for more control over system appearance.<br />
<br />
You may be familiar with existing configuration tools: some of these still work; many will not. Some settings are not readily exposed for you to change. Indubitably, many settings will migrate to newer tools and/or become exposed as time progresses and the wider community embraces and extends the latest GNOME desktop.<br />
<br />
==== Gsettings ====<br />
<br />
A new command-line tool '''gsettings''' stores data in a binary format, unlike previous tools using XML text. A tutorial [http://blog.fpmurphy.com/2011/03/customizing-the-gnome-3-shell.html Customizing the GNOME Shell] explores the power of gsettings.<br />
<br />
==== GNOME tweak tool ====<br />
<br />
This graphical tool customizes fonts, themes, titlebar buttons and other settings. <br />
<br />
# pacman -S gnome-tweak-tool<br />
<br />
==== GTK3 theme via settings.ini ====<br />
<br />
Like {{ic|~/.gtkrc-2.0}} with GTK2+, it is possible to set a GTK3 theme via {{ic|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini}}.<br />
<br />
Variable {{ic|$XDG_CONFIG_HOME}} is usually set to {{ic|~/.config}}<br />
<br />
''Adwaita,'' the default GNOME 3 theme, is a part of {{pkg|gnome-themes-standard}}. Additional GTK3 themes can be found at [http://browse.deviantart.com/customization/skins/linuxutil/desktopenv/gnome/gtk3/ Deviantart web site.] For example:<br />
{{hc|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini|<nowiki><br />
[Settings]<br />
gtk-theme-name = Adwaita<br />
gtk-fallback-icon-theme = gnome<br />
# next option is applicable only if selected theme supports it<br />
gtk-application-prefer-dark-theme = true<br />
# set font name and dimension<br />
gtk-font-name = Sans 10<br />
</nowiki>}}<br />
<br />
It is necessary to [[#Restarting_the_shell|restart the GNOME shell]] for settings to be applied. More GTK options are found at [http://developer.gnome.org/gtk3/3.0/GtkSettings.html#GtkSettings.properties GNOME developer documentation.]<br />
<br />
==== Icon theme ====<br />
<br />
Using {{pkg|gnome-tweak-tool}} version 3.0.3 and later, you can place any icon theme you wish to use inside {{ic|~/.icons}}.<br />
<br />
Usefully, GNOME 3 is compatible with GNOME 2 icon themes, which means you are not stuck with the default icons. To install a new set of icons, copy your desired icon theme's directory to {{ic|~/.icons}}. As an example:<br />
<br />
$ cp -R /home/user/Desktop/my_icon_theme ~/.icons<br />
<br />
The new theme ''my_icon_theme'' is now selectable using {{ic|gnome-tweak-tool}} under ''interface''.<br />
<br />
Alternatively, you may textually select your icon theme with no need for gnome-tweak-tool. Add the GTK icon theme name to {{ic|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini}}. Please note, not to use "" as your settings would not be recognised then.<br />
<br />
{{hc|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini|<nowiki>... previous lines ...<br />
<br />
gtk-icon-theme-name = my_new_icon_theme</nowiki>}}<br />
<br />
=== Nautilus ===<br />
<br />
''See [[Nautilus]].''<br />
<br />
=== Totem ===<br />
<br />
To play back h.264 videos, you need to install {{Pkg|gst-libav}}<br />
<br />
For more information on gstreamer hardware acceleration, see [[GStreamer#Hardware_Acceleration|Gstreamer: Hardware Acceleration]].<br />
<br />
=== GNOME panel ===<br />
<br />
==== Show date in top bar ====<br />
<br />
By default GNOME displays only the weekday and time in the top bar. This can be changed with the following command. Changes take effect immediately. <br />
<br />
GNOME 3.4.2:<br />
# gsettings set org.gnome.shell.clock show-date true<br />
<br />
GNOME 3.6.2:<br />
# gsettings set org.gnome.desktop.interface clock-show-date true<br />
<br />
==== Always show the "Log Out" entry in the user menu ====<br />
<br />
Since GNOME 3.6, the "Log Out" entry in the user menu is only shown when multiple non-root users are present in the system.<br />
<br />
To always enable this entry, run the following command from a terminal:<br />
<br />
# gsettings set org.gnome.shell always-show-log-out true<br />
<br />
You can also change this in dconf-editor: Navigate to org.gnome.shell, then check the "always-show-log-out" checkbox.<br />
<br />
Then, restart the GNOME shell:<br />
#{{Keypress|Alt+F2}}<br />
#{{Keypress|r}}<br />
#{{Keypress|Enter}}<br />
<br />
==== Hiding icons in the top bar ====<br />
<br />
When doing a GNOME install, some unwanted icons might appear in the panel. These icons can be removed either with GNOME shell extensions or by manually editing the GNOME panel script.<br />
<br />
===== Hiding icons with shell extensions =====<br />
<br />
To remove the accessibility icon, one can use the https://extensions.gnome.org/extension/112/remove-accesibility/. <br />
<br />
The best way to use extensions is installing them from the gnome extensions web page like the one above.<br />
<br />
===== Manually editing the GNOME panel script =====<br />
<br />
For example, to remove the '''universal access icon''', comment out the 'a11y' line in PANEL_ITEM_IMPLEMENTATIONS:<br />
<br />
{{hc|/usr/share/gnome-shell/js/ui/panel.js|<nowiki><br />
const PANEL_ITEM_IMPLEMENTATIONS = {<br />
'activities': ActivitiesButton,<br />
'appMenu': AppMenuButton,<br />
'dateMenu': imports.ui.dateMenu.DateMenuButton,<br />
// 'a11y': imports.ui.status.accessibility.ATIndicator,<br />
'volume': imports.ui.status.volume.Indicator,<br />
'battery': imports.ui.status.power.Indicator,<br />
'lockScreen': imports.ui.status.lockScreenMenu.Indicator,<br />
'keyboard': imports.ui.status.keyboard.InputSourceIndicator,<br />
'powerMenu': imports.gdm.powerMenu.PowerMenuButton,<br />
'userMenu': imports.ui.userMenu.UserMenuButton<br />
};<br />
</nowiki>}}<br />
<br />
Then, save your results and restart the shell:<br />
<br />
#{{Keypress|Alt+F2}}<br />
#{{Keypress|r}}<br />
#{{Keypress|Enter}}<br />
<br />
==== Show battery icon ====<br />
<br />
To show the battery tray icon, [[pacman|install]] {{Pkg|gnome-power-manager}} from the [[Official Repositories|official repositories]].<br />
<br />
==== Disable "Suspend" in the status and gdm menu ====<br />
<br />
A quick way to do it system-wide for GNOME 3.2 is to change line 539 of {{ic|/usr/share/gnome-shell/js/ui/userMenu.js}} and line 103 of {{ic|/usr/share/gnome-shell/js/gdm/powerMenu.js}}. (For GNOME versions prior to 3.2, look at line 153 of {{ic|/usr/share/gnome-shell/js/ui/statusMenu.js}}.) This change takes effect the next time GNOME Shell is started.<br />
<br />
{{hc|/usr/share/gnome-shell/js/ui/userMenu.js|<nowiki><br />
// this._haveSuspend = this._upClient.get_can_suspend(); // Comment this line out.<br />
this._haveSuspend = false; // Use this line instead.<br />
</nowiki>}}<br />
<br />
To accomplish this, paste the following command(s) in your terminal:<br />
GNOME_SHELL=/usr/share/gnome-shell<br />
SCRIPTS=`grep -lr get_can_suspend $GNOME_SHELL/js`<br />
for FILE in $SCRIPTS ; do<br />
sed -r -i -e 's/[^= ]+.get_can_suspend\(\)/false/' "$FILE"<br />
done<br />
<br />
The above change does not persist after a GNOME version update, however. A more perennial solution is to add the code above in some gdm or system startup script (eg: /etc/rc.local), to keep the "suspend" option disabled after updates.<br />
<br />
Alternatively you can install the [[#GNOME shell extensions|GNOME shell extension]] {{ic|alternative status menu}} in package {{Pkg|gnome-shell-extension-alternative-status-menu}}.<br />
<br />
==== Eliminate delay when logging out ====<br />
<br />
The following tweak removes the confirmation dialog and sixty second delay for logging out.<br />
<br />
This dialog normally appears when you log out with the status menu. This tweak affects the '''''Power Off''''' dialog as well. This is not a system-wide change; it affects only the user who enters this command. The change takes effect immediately after entering the command.<br />
<br />
$ gsettings set org.gnome.SessionManager logout-prompt 'false'<br />
<br />
==== Show system monitor ====<br />
<br />
Install the {{AUR|gnome-shell-system-monitor-applet-git}} extension available in the [[AUR]].<br />
<br />
==== Show weather information ====<br />
<br />
Install {{AUR|gnome-shell-extension-weather-git}} from [[AUR]].<br />
<br />
=== Activity view ===<br />
<br />
==== Remove entries from Applications view ====<br />
<br />
Like other desktop environments, GNOME uses .desktop files to populate its Applications view. These text files are in '''{{ic|/usr/share/applications}}'''. It is not possible to edit these files from a folder view ‒ Nautilus does not treat their icons as text files. Use a terminal to display or edit .desktop file entries.<br />
<br />
# ls /usr/share/applications<br />
# nano /usr/share/applications/foo.desktop<br />
<br />
For system wide changes, edit files in '''{{ic|/usr/share/applications}}'''. For local changes, make a copy of ''foo.desktop'' in your home folder.<br />
<br />
$ cp /usr/share/applications/foo.desktop ~/.local/share/applications/<br />
<br />
Edit .desktop files to fit your wishes. <br />
<br />
{{Note|Removing a .desktop file does not uninstall an application, but instead removes its desktop integration: MIME types, shortcuts, and so forth.}}<br />
<br />
The following command appends one line to a .desktop file and hides its associated icon from Applications view:<br />
<br />
$ echo "NoDisplay=true" >> foo.desktop<br />
<br />
==== To Remove Wine Launchers from the Applications menu ====<br />
<br />
Enter {{ic|~/.local/share/applications/wine/Programs/}} and look for the wine application's name. In the directories are the ".desktop" files which configure the launchers. Remove the program directory to easily remove the launchers.<br />
<br />
==== Change application icon size ====<br />
<br />
One awkward selection of the GNOME designers is their choice of large icons for Applications view. This view is painful when working with a small screen containing many large application icons. There is a way to reduce the icon size. It is done by editing the GNOME-Shell theme.<br />
<br />
Edit system files directly (make a backup first) or copy theme files to your local folder and edit these files. <br />
* For the '''default''' theme, edit '''{{ic|/usr/share/gnome-shell/theme/gnome-shell.css}}'''<br />
<br />
* For '''user themes''', edit '''{{ic|/usr/share/themes/<UserTheme>/gnome-shell/gnome-shell.css}}'''<br />
<br />
Edit ''gnome-shell.css'' and replace the following values. Afterward, [[#Restarting_the_shell|restart the GNOME shell.]]<br />
{{hc|gnome-shell.css|<nowiki><br />
...<br />
/* Application Launchers and Grid */<br />
<br />
.icon-grid {<br />
spacing: 18px;<br />
-shell-grid-horizontal-item-size: 82px;<br />
-shell-grid-vertical-item-size: 82px;<br />
}<br />
<br />
.icon-grid .overview-icon {<br />
icon-size: 48px;<br />
}<br />
...<br />
</nowiki>}}<br />
<br />
==== Change dash icon size ====<br />
GNOME's Activities view has a dash on the left hand side, the size of the icons in this dash will scale depending on the amount of icons set to display. The scaling can be manipulated or set to a constant icon size. To do so, edit {{ic|/usr/share/gnome-shell/js/ui/dash.js}}.<br />
<br />
{{hc|dash.js|<nowiki><br />
...<br />
<br />
let iconSizes = [ 16, 22, 24, 32, 48, 64 ];<br />
<br />
...<br />
</nowiki>}}<br />
<br />
==== Change switcher (alt-tab) icon size ====<br />
GNOME comes with a built in task switcher, the size of the icons in this task switcher will scale depending on the amount of icons set to display. The scaling can be manipulated or set to a constant icon size. To do so, edit {{ic|/usr/share/gnome-shell/js/ui/altTab.js}}<br />
<br />
{{hc|altTab.js|<nowiki><br />
...<br />
<br />
const iconSizes = [96, 64, 48, 32, 22];<br />
<br />
...<br />
</nowiki>}}<br />
<br />
==== Change system tray icon size ====<br />
GNOME comes with a built in system tray, visible when the mouse is hovered over the bottom right corner of the screen. The size of the icons in this tray is set to a fixed value of 24. To change this value, edit {{ic|/usr/share/gnome-shell/js/ui/messageTray.js}}<br />
{{hc|messageTray.js|<nowiki><br />
...<br />
<br />
ICON_SIZE: 24,<br />
<br />
...<br />
</nowiki>}}<br />
<br />
==== Disable Activity hot corner hovering ====<br />
<br />
To disable automatic activity view when the hot corner is hovered, edit {{ic|/usr/share/gnome-shell/js/ui/layout.js}} (that was ''panel.js'' in GNOME 3.0.x) :<br />
{{hc|layout.js|<nowiki><br />
this._corner = new Clutter.Rectangle({ name: 'hot-corner',<br />
width: 1,<br />
height: 1,<br />
opacity: 0,<br />
reactive: true });icon-size: 48px;<br />
}<br />
</nowiki>}}<br />
and set {{ic|reactive}} to {{ic|false}}. GNOME Shell needs to be restarted.<br />
<br />
==== Disable Message Tray hovering ====<br />
<br />
The message tray is shown when the mouse hovers at the bottom of the screen for one second. To disable this behavior, comment out the following line in {{ic|/usr/share/gnome-shell/js/ui/messageTray.js}}:<br />
{{hc|messageTray.js|<nowiki><br />
//pointerWatcher.addWatch(TRAY_DWELL_CHECK_INTERVAL, Lang.bind(this, this._checkTrayDwell));<br />
</nowiki>}}<br />
GNOME Shell needs to be restarted. The message tray is still visible in activity view.<br />
<br />
=== Titlebar ===<br />
==== Remove title bar ====<br />
Install [https://extensions.gnome.org/extension/354/maximus/ Maximus] GNOME shell extension.<br />
<br />
It can also have white list / black list of application.<br />
<br />
This extension requires xorg-xprop, install it if you don't have it already.<br />
<br />
{{bc|pacman -S xorg-xprop}}<br />
<br />
More about [[#GNOME shell extensions | GNOME shell extensions]].<br />
<br />
==== Reduce title bar height ====<br />
* ''' global''' - edit {{ic|/usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml}}, search for {{ic|title_vertical_pad}} and and reduce its value to a minimum of {{ic|0}}.<br />
* '''user-only''' - copy {{ic|/usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml}} to {{ic|/home/$USER/.themes/Adwaita/metacity-1/metacity-theme-3.xml}}, search for {{ic|title_vertical_pad}} and reduce its value to a minimum of {{ic|0}}.<br />
<br />
Then [[#Restarting_the_shell|Restart the GNOME shell.]] <br />
<br />
To restore the original values, [[pacman|install]] the package {{Pkg|gnome-themes-standard}} from the [[Official Repositories|official repositories]] or remove {{ic|/home/$USER/.themes/Adwaita/metacity-1/metacity-theme-3.xml}}<br />
<br />
==== Reorder titlebar buttons ====<br />
<br />
At present this setting can be changed through '''dconf-editor.'''<br />
<br />
For example, we move the close and minimize buttons to the left side of the titlebar. Open '''dconf-editor''' and locate the '''''org.gnome.shell.overrides.button_layout''''' key. Change its value to '''{{ic|close,minimize:}}''' (Colon symbol designates the spacer between left side and right side of the titlebar.) Use whichever buttons in whatever order you prefer. You cannot use a button more than once. Also, keep in mind that certain buttons are deprecated. [[#Restarting_the_shell|Restart the shell]] to see your new button arrangement.<br />
<br />
==== Hide titlebar when maximized ====<br />
<br />
# sed -i -r 's|(<frame_geometry name="max")|\1 has_title="false"|' /usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml<br />
<br />
[[#Restarting_the_shell|Restart the GNOME shell.]] After this tweak, you may find it difficult to un-maximize a window when there is no titlebar to grab.<br />
<br />
With suitable keybindings, you should be able to use {{Keypress|Alt+F5}}, {{Keypress|Alt+F10}} or {{Keypress|Alt+Space}} to remedy the situation.<br />
<br />
To prevent {{ic|metacity-theme-3.xml}} from being overwritten each time package {{pkg|gnome-themes-standard}} is upgraded, add its name to {{ic|/etc/pacman.conf}} with {{ic|NoUpgrade}}.<br />
<br />
{{hc|/etc/pacman.conf|<nowiki>... previous lines ...<br />
<br />
# Pacman won't upgrade packages listed in IgnorePkg and members of IgnoreGroup<br />
# IgnorePkg =<br />
# IgnoreGroup =<br />
<br />
NoUpgrade = usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml # Do not add a leading slash to the path<br />
<br />
... more lines ...</nowiki>}}<br />
<br />
To restore original Adwaita theme values, install the {{pkg|gnome-themes-standard}} package.<br />
<br />
=== Login screen ===<br />
{{Merge|GDM|Login managers have their own wiki pages and information should be maintained separately.}}<br />
To modify characteristics of the login screen (GDM, the GNOME display manager) the following lines can be executed. The first command allows all users, including "gdm", to access X settings (albeit temporarily). This command creates a temporary vulnerability, so be advised. The second command opens a bash session with the credentials of user "gdm". {{Note|For exposition, user gdm's terminal prompt is shown as '''$'''. In actuality, it shows something like -bash-4.2$.}}<br />
<br />
# xhost +<br />
# su - gdm -s /bin/bash<br />
$ dbus-launch<br />
<br />
The third command prints DBUS_SESSION_BUS_ADDRESS and DBUS_SESSION_BUS_PID. We must export these variables. Either manually export the below two variables shown in the output of dbus-launch like this:<br />
<br />
$ export DBUS_SESSION_BUS_ADDRESS=unix:abstract=/tmp/dbus-Jb433gMQHS,guid=fc14d4bf3d000e38276a5a2200000d38<br />
$ export DBUS_SESSION_BUS_PID=4283<br />
<br />
Or use the follow command:<br />
<br />
$ `dbus-launch | sed "s/^/export /"`<br />
<br />
Check to see if dconf-service is running and if not, start it like this<br />
<br />
$ /usr/lib/dconf/dconf-service &<br />
<br />
==== Login background image ====<br />
<br />
Once session variables have been exported as explained above, you may issue commands to retrieve or set items used by GDM. <br />
<br />
The easiest way to changes all the settings is by launching the Configuration Editor gui with the command<br />
<br />
$ dconf-editor<br />
<br />
The location of each setting is the same as in the command line style of configuration shown below:<br />
<br />
The following is the command-line approach to retrieve or set the file name used for GDM's wallpaper.<br />
{{bc|<nowiki><br />
$ GSETTINGS_BACKEND=dconf gsettings get org.gnome.desktop.background picture-uri<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.background picture-uri 'file:///usr/share/backgrounds/gnome/SundownDunes.jpg'<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.background picture-options 'zoom'<br />
## Possible values: centered, none, scaled, spanned, stretched, wallpaper, zoom</nowiki>}}<br />
{{Note|You must specify a file which user "gdm" has permission to read. GDM cannot read files in your home directory.}}<br />
<br />
An alternative graphical interface to changing themes (gtk3, icons and cursor), the wallpaper and minor other settings of the GDM login screen, you can install {{aur|gdm3setup}} from AUR.<br />
<br />
==== Larger font for login ====<br />
<br />
This tweak enlarges the login font with a scaling factor. It is the same method employed by ''Accessibility Manager'' on the desktop.<br />
<br />
You must [[#Login_screen|export the GDM session variables]] before performing this tweak.<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.interface text-scaling-factor '1.25'<br />
<br />
==== Turning off the sound ====<br />
<br />
This tweak disables the audible feedback heard when the system volume is adjusted (via keyboard) on the login screen. You must first export the GDM session variables.<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.sound event-sounds 'false'<br />
<br />
If the above tweak does not work for you or you are unable to export the GDM session variables, there is always the easiest solution to the "ready sound" problem: mute or lower the sound while in GDM login screen using the media keys (if available) of your keyboard.<br />
<br />
==== Make the power button interactive ====<br />
<br />
The default installation sets the power button to suspend the system. '''''Power off''''' or '''''Show dialog''''' is a better choice. You must first export the GDM session variables as [[#Login_screen|outlined previously.]]<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.settings-daemon.plugins.power button-power 'interactive'<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.settings-daemon.plugins.power button-hibernate 'interactive'<br />
$ gsettings list-recursively org.gnome.settings-daemon.plugins.power<br />
<br />
{{Warning|Please note that the [[Acpid|acpid]] daemon also handle the "power button" an "hibernate button" event. Running both systems at the same time may lead to unexpected behaviour.}}<br />
<br />
==== Prevent suspend when closing the lid ====<br />
<br />
On some systems it happens that your laptop suspends when you are closing the lid despite having set the options ''Laptop lid close action on battery'' and ''Laptop lid close action on AC'' to ''blank''. If this is the case, append the following line to {{ic|/etc/systemd/logind.conf}}:<br />
<br />
HandleLidSwitch=ignore<br />
<br />
==== No reaction on lid close ====<br />
<br />
When configuring the lid close events via [[Systemd#ACPI_power_management]], the settings may seem to have no effect.<br />
If you have an external monitor connected to your laptop, this is default GNOME behaviour. Disconnect the monitor and the settings should work, otherwise your {{ic|/etc/systemd/logind.conf}} may be incorrect.<br />
<br />
==== Change Critical Battery Level Action (for Laptops) ====<br />
<br />
The {{pkg|gnome-power-manager}} gui doesn't have a choice for "do nothing" on laptops at critical battery level. To manually edit this, open the {{pkg|dconf}}-editor -> org -> gnome -> settings-daemon -> plugins -> power. Edit the "critical-battery-action" value to "nothing".<br />
<br />
==== GDM keyboard layout ====<br />
<br />
GDM does not know about your GNOME 3 desktop keyboard settings. To change keyboard settings used by GDM, set your layout using Xorg configuration. Refer to this section of the [[Beginners'_Guide#Non-US_keyboard|Beginner's Guide.]]<br />
<br />
=== Other tips ===<br />
See [[GNOME Tips]].<br />
<br />
== Miscellaneous settings ==<br />
<br />
=== Automatic program launch upon logging in ===<br />
<br />
Specify which programs start automatically after logging in using {{ic|gnome-session-properties}}. This tool is part of the {{Pkg|gnome-session}} package.<br />
<br />
$ gnome-session-properties<br />
<br />
=== Editing applications menu ===<br />
<br />
{{pkg|gnome-menus}} provides ''gmenu-simple-editor'' which can show/hide menu entries.<br />
<br />
{{pkg|alacarte}} provides a more complete menu editor for adding/editing menu entries.<br />
<br />
=== Some 'System Settings' not preserved ===<br />
<br />
GNOME 3 is using [[systemd]] (an init daemon for Linux) with more modern capabilities. Previously GNOME programs were altered to use Arch's init functionalities to gather settings but either the maintenance required to do this or possibly this is because of a transitioning to the new init system (read more about this [https://bbs.archlinux.org/viewtopic.php?pid=1115208#p1115208 here]). Areas that settings will not be preserved are '''Date and Time''' and adding ICC profiles in the '''Color''' menu and possibly others.<br />
<br />
To gain the functionality back, [[systemd]] needs to be installed and the ''gdm.service'' and ''NetworkManager.service'' services need to be enabled.<br />
<br />
=== Inner padding in Gnome Terminal===<br />
To move the terminal output away from the window borders create the stylesheet {{ic|~/.config/gtk-3.0/gtk.css}} with the following setting:<br />
<br />
TerminalScreen {<br />
-VteTerminal-inner-border: 10px 10px 10px 10px;<br />
}<br />
<br />
=== Disable sound effects in Terminal ===<br />
By default the terminal has these annoying sound effects when e.g. pushing the tab button on your keyboard. One solution is to turn off or mute all sound effects in the settings menu of Gnome. However, this will also turn off notification sounds in other application such as Skype. A better solution is to open a terminal, go to Edit -> Profile Preferences -> General and untick '''Terminal bell'''.<br />
<br />
=== Disable blinking cursor in Terminal ===<br />
Since Gnome 3.8 and dconf the key required to modify in order to disable the blinking cursor in the Terminal differs slightly in contrast to the old gconf key. To disable the blinking cursor in Gnome 3.8 use:<br />
<br />
gsettings set org.gnome.desktop.interface cursor-blink false<br />
<br />
=== Make new tabs inherit current directory inn Gnome Terminal (3.8+) ===<br />
In Gnome 3.8, the behaviour of how current directories are tracked has changed. To restore this behaviour, you need to put this in your {{ic|.bashrc}}:<br />
<br />
export PS1='\[$(__vte_ps1)\]'$PS1<br />
<br />
or, for zsh users<br />
<br />
chpwd_functions+=(__vte_ps1)<br />
<br />
=== Move dialog windows ===<br />
The default configuration for dialogs will not allow you to move them which causes problems in some cases. To change this you will need to use gconf-editor and change this setting:<br />
<br />
/desktop/gnome/shell/windows/attach_modal_dialogs<br />
<br />
After the change you will need to restart the shell for it to take affect.<br />
<br />
=== Show context menu icons ===<br />
Some programs do have context menu icons which, however, are disabled by default to show up in Gnome. In order to show them set {{ic| org.gnome.desktop.interface menus-have-icons}} to true.<br />
<br />
=== GNOME shell extensions ===<br />
<br />
GNOME Shell can be customized with extensions. These provide features such as a dock or a widget for changing the theme.<br />
<br />
Many extensions are collected and hosted by [https://extensions.gnome.org/ extensions.gnome.org]. They can be browsed and installed simply activating them in the browser. More information about gnome shell extensions can be found [https://extensions.gnome.org/about/ here].<br />
<br />
See [[#When_an_extension_breaks_GNOME|when an extension breaks GNOME]] for troubleshooting information.<br />
<br />
=== Default file browser/replace Nautilus ===<br />
<br />
You can trick GNOME into using another file browser by editing the {{ic|Exec}} line in {{ic|/usr/share/applications/nautilus.desktop}}. See the correct parameters in the {{ic|.desktop}} file of the file manager of your choice, e.g.:<br />
{{hc|/usr/share/applications/nautilus.desktop|<br />
2=[...]<br />
Exec=thunar %F<br />
OR<br />
Exec=pcmanfm %U<br />
OR<br />
Exec=nemo %U<br />
[...]<br />
}}<br />
<br />
=== Default PDF viewer ===<br />
In some cases when you have installed Inkscape or other graphic programs Evince Document Viewer might no longer be selected as the default PDF application. If it is not available in the '''Open With''' entry which would be the GUI solution, you can use the following user command to make it the default application again.<br />
<br />
xdg-mime default evince.desktop application/pdf<br />
<br />
=== Default terminal ===<br />
<br />
{{ic|gsettings}} (which replaces {{ic|gconftool-2}}) is used to set the default terminal. The setting affects ''nautilus-open-terminal'' (a Nautilus extension).<br />
To make [[rxvt-unicode|urxvt]] the default, run:<br />
<br />
gsettings set org.gnome.desktop.default-applications.terminal exec urxvtc<br />
gsettings set org.gnome.desktop.default-applications.terminal exec-arg "'-e'"<br />
<br />
{{Note|The {{ic|-e}} flag is for executing a command. When ''nautilus-open-terminal'' invokes {{ic|urxvtc}}, it puts a {{ic|cd}} command at the end of the command line so that the new terminal starts in the directory you opened it from. Other terminals will require a different (perhaps empty) {{ic|exec-arg}}.}}<br />
<br />
=== Default web browser ===<br />
<br />
To configure the web browser used by the AUR package {{AUR|gnome-gmail-notifier}}, open gconf-editor<br />
and edit the {{ic|/desktop/gnome/url-handlers/http/}} key. You may want to change {{ic|https/}}, {{ic|about/}}, and {{ic|unknown/}} keys while you are at it.<br />
<br />
=== Middle mouse button ===<br />
<br />
By default, GNOME 3 disables middle mouse button emulation regardless of [[Xorg]] settings ('''Emulate3Buttons'''). To enable middle mouse button emulation use:<br />
<br />
$ gsettings set org.gnome.settings-daemon.peripherals.mouse middle-button-enabled true<br />
<br />
=== Natural scrolling touchpad ===<br />
<br />
GNOME 3 can be configured to use "natural" two finger scrolling, similar to that used in [http://www.apple.com/au/osx/what-is/gestures.html#gallery-gestures-scroll Mac OSX].<br />
<br />
Go to '''System Settings''' ({{ic|gnome-control-center}}) -> '''Mouse & Touchpad''' and set both '''Two finger scroll''' and '''Content sticks to fingers''' to {{ic|ON}}.<br />
<br />
You can alternatively configure the touchpad from a terminal with {{ic|gsettings}}:<br />
<br />
$ gsettings set org.gnome.settings-daemon.peripherals.touchpad horiz-scroll-enabled true<br />
$ gsettings set org.gnome.settings-daemon.peripherals.touchpad scroll-method two-finger-scrolling<br />
$ gsettings set org.gnome.settings-daemon.peripherals.touchpad natural-scroll true<br />
<br />
=== Display dimming ===<br />
<br />
By default GNOME 3 has a ten second idle timeout to dim the screen regardless of the battery and AC state:<br />
<br />
gsettings get org.gnome.settings-daemon.plugins.power idle-dim-time<br />
<br />
To set a new value type the following<br />
<br />
gsettings set org.gnome.settings-daemon.plugins.power idle-dim-time <int><br />
<br />
where <int> is the value in seconds<br />
<br />
=== Alternate window manager ===<br />
<br />
You can use an alternate window manager with GNOME by [[#Enabling_fallback_mode|forcing fallback mode]] and creating two files:<br />
<br />
{{Note|Xmonad is used as an example, but this works for other window managers.}}<br />
<br />
{{hc|/usr/share/gnome-session/sessions/xmonad.session|<nowiki>[GNOME Session]<br />
Name=Xmonad session<br />
RequiredComponents=gnome-panel;gnome-settings-daemon;<br />
RequiredProviders=windowmanager;notifications;<br />
DefaultProvider-windowmanager=xmonad<br />
DefaultProvider-notifications=notification-daemon</nowiki>}}<br />
<br />
{{hc|/usr/share/xsessions/xmonad-gnome-session.desktop|<nowiki>[Desktop Entry]<br />
Name=Xmonad GNOME<br />
Comment=Tiling window manager<br />
TryExec=/usr/bin/gnome-session<br />
Exec=gnome-session --session=xmonad<br />
Type=XSession</nowiki>}}<br />
<br />
The next time you log in, you should have the ability to choose ''Xmonad GNOME'' as your session.<br />
<br />
If there isn't a .desktop file for the window manager, you'll need to create one. Example for [[wmii]]:<br />
<br />
{{hc|/usr/share/applications/wmii.desktop|<nowiki><br />
[Desktop Entry]<br />
Version=1.0<br />
Type=Application<br />
Name=wmii<br />
TryExec=wmii<br />
Exec=wmii</nowiki>}}<br />
<br />
For more information, see [http://makandra.com/notes/1367-running-the-awesome-window-manager-within-gnome this article on running awesome as the window manager in GNOME].<br />
<br />
== Hidden features ==<br />
<br />
GNOME 3 hides many useful options which you can customize with '''dconf-editor.''' GNOME 3 also supports '''gconf-editor''' for settings that have not yet migrated to dconf.<br />
<br />
=== Changing hotkeys ===<br />
Certain hotkeys cannot be changed directly via Settings -> Keyboard -> Shortcuts. In order to change these keys, use dconf-editor. An example of particular note is the hotkey Alt-Above_Tab. On US keyboards, this is Alt-`: is a hotkey often used in the [[Emacs]] editor. It can be changed by opening dconf-editor and modifying the ''switch-group'' key found in {{ic|org.gnome.desktop.wm.keybindings}}.<br />
<br />
It is possible to manually change the keys via an application's so-called accel map file. Where it is to be found is up to the application: For instance, Thunar's is at ~/.config/Thunar/accels.scm, whereas Nautilus's is located at ~/.config/nautilus/accels and ~/.gnome2/accels/nautilus on old release.<br />
<br />
The file should contain a list of possible hotkeys, each unchanged line commented out with a leading ";" that has to be removed for a change to become active.<br />
For example to replace the hotkey used by Nautilus to move files to the trash folder, change the line :<br />
; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")<br />
to this :<br />
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")<br />
<br />
The file is regenerate regularly so don't waist time on commenting the file. The uncommented line will stay but every comment you may add will be lost.<br />
<br />
==== Nautilus 3.4 and older ====<br />
Firstly, use '''dconf-editor''' to place a checkmark next to {{ic|can-change-accels}} in the key named ''org.gnome.desktop.interface.''<br />
<br />
We will replace the hotkey — a.k.a. keyboard shortcut, keyboard accelerator — used by Nautilus to move files to the trash folder.<br />
The default assignment is a somewhat-awkward {{Keypress|Ctrl+Delete}}.<br />
* Open Nautilus, select any file, and click '''Edit''' on the menu bar.<br />
* Hover over the ''Move to Trash'' menu item.<br />
* While hovering, press {{Keypress|Delete}}. The current accelerator is now unset.<br />
* Press the key that you wish to become the new keyboard accelerator.<br />
* Press {{Keypress|Delete}} to make the new accelerator be the Delete key.<br />
Unless you select a file or folder, ''Move to Trash'' will be grayed-out. Finally, disable {{ic|can-change-accels}} to prevent accidental hotkey changes.<br />
<br />
=== Shutdown via the status menu ===<br />
<br />
Currently, the GNOME designers have hidden the ''Shutdown'' option inside the status menu. To shut down your system with the status menu, click the menu and hold down the {{Keypress|Alt}} key so that the '''''Suspend''''' item changes to '''''Power Off'''''. The subsequent dialog allows you to shut down or restart your system.<br />
<br />
If you disable the Suspend menu item system-wide as described [[#Disable_"Suspend"_in_the_status_menu|elsewhere in this document]] you do not have to go through these motions.<br />
<br />
Another option is to install the ''Alternative Status Menu'' extension. See the section on shell extensions. The alternative menu extension installs a new status menu with a non-hidden '''''Power Off''''' entry.<br />
<br />
=== Screencast recording ===<br />
<br />
Gnome features the built-in possbility to create screencasts easily. Thereby Control+Shift+Alt+R keybinding starts and stops the recording. A red circle is displayed in the bottom right corner of the screen when the recording is in progress. After the recording is finished, a file named 'Screencast from %d%u-%c.webm' is saved in the Videos directory. In order to use the screencast feature you need to have installed the gst plugins which are:<br />
<br />
$ pacman -Qs gst<br />
<br />
=== Modify Keyboard with XkbOptions ===<br />
<br />
Using the '''dconf-editor''', navigate to the key named ''org.gnome.desktop.input-sources.xkb-options'' and add desired XkbOptions (e.g. 'caps:swapescape') to the list.<br />
<br />
See /usr/share/X11/xkb/rules/xorg for all XkbOptions and then /usr/share/X11/xkb/symbols/* for the respective descriptions.<br />
<br />
=== Toggle keyboard layouts ===<br />
Since Gnome does not consider any configuration in {{ic|/etc/X11/conf.d/*.conf}} you have to set the command for layout switching either via the control center with the options ''Switch to previous source'' and ''Switch to next source'' or if you want to use Alt - Shift combination you have to use the Gnome-Tweak-Tool and set ''Typing -> Modifiers-only input sources -> select Alt-shift''. For more information see also the forum [https://bbs.archlinux.org/viewtopic.php?id=152127 thread].<br />
<br />
== Integrated messaging (Empathy) ==<br />
<br />
Empathy, the engine behind integrated messaging, and all system settings based on messaging accounts will not show up unless the {{grp|telepathy}} group of packages or at least one of the backends ({{pkg|telepathy-gabble}}, or {{pkg|telepathy-haze}}, for example) is installed.<br />
<br />
These packages are not included in default Arch GNOME installs. You can install the Telepathy and optionally any backends with:<br />
<br />
# pacman -S telepathy<br />
<br />
Without telepathy, Empathy will not open the account management dialog and can get stuck in this state. If this happens -- even after quitting Empathy cleanly -- the {{ic|/usr/bin/empathy-accounts}} application can remain running and will need to be killed before you can add any new accounts.<br />
<br />
View descriptions of telepathy components on the [http://telepathy.freedesktop.org/wiki/Components Freedesktop.org Telepathy Wiki.]<br />
<br />
== Forcing fallback mode ==<br />
<br />
Your session automatically starts in fallback mode when '''gnome-shell''' is not present, or when your hardware cannot handle graphics acceleration — such as running within a virtual machine or running on old hardware.<br />
<br />
If you wish to enable fallback mode while still having '''gnome-shell''' installed, make the following system change:<br />
<br />
Go to '''System Settings''' ({{ic|gnome-control-center}}) -> '''Details''' -> '''Graphics''' and set '''Forced Fallback Mode''' to {{ic|ON}}.<br />
<br />
You can alternatively choose the type of session from a terminal with {{ic|gsettings}}:<br />
<br />
$ gsettings set org.gnome.desktop.session session-name gnome-fallback<br />
<br />
You may want to log out after making the change. You will see the chosen type of session upon your next login.<br />
<br />
To disable the forced-fallback mode change it back to {{ic|gnome}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Cannot Set Settings in Dconf-Editor ===<br />
<br />
When one cannot set settings in {{pkg|dconf}}, it is possible their dconf user settings are corrupt. In this case it is best to delete the user dconf files in {{bc|<nowiki> .config/dconf/user* </nowiki>}} and set the settings in dconf-editor after.<br />
<br />
=== When an extension breaks GNOME ===<br />
<br />
When enabling shell extensions causes GNOME breakage, you should first remove the ''user-theme'' and ''auto-move-windows'' extensions from their installation directory.<br />
<br />
The installation directory could be one of '''{{ic|~/.local/share/gnome‑shell/extensions,}}''' '''{{ic|/usr/share/gnome‑shell/extensions,}}''' or '''{{ic|/usr/local/share/gnome‑shell/extensions}}'''. Removing these two extension-containing folders may fix the breakage. Otherwise, isolate the problem extension with trial‑and‑error.<br />
<br />
Removing or adding an extension-containing folder to the aforementioned directories removes or adds the corresponding extension to your system. Details on GNOME Shell extensions are available at the [https://live.gnome.org/GnomeShell/Extensions GNOME web site.]<br />
<br />
=== Extensions do not work after GNOME 3 update ===<br />
<br />
Locate the folder where your extensions are installed. It might be '''{{ic|~/.local/share/gnome-shell/extensions}}''' or '''{{ic|/usr/share/gnome-shell/extensions}}'''.<br />
<br />
Edit each occurrence of '''{{ic|metadata.json}}''' which appears in each extension sub-folder. <br />
<br />
{| border="0"<br />
| Insert: || '''{{ic|"shell-version": ["3.6"]}}'''<br />
|-<br />
| Instead of (for example): || '''{{ic|"shell-version": ["3.4"]}}'''<br />
|}<br />
<br />
<br />
'''"3.x"''' indicates the extension works with every Shell version. If it breaks, you'll know to change it back.<br />
<br />
=== The "Windows" key ===<br />
By default, this key is mapped to the "overlay-key" to launch the Overview. You can remove this key mapping to free up your {{ic|Windows Key}} (also called {{ic|Mod4}}), which GNOME calls {{ic|Super_L}}, by utilizing {{ic|gsettings}}.<br />
<br />
Example:<br />
{{ic| gsettings set org.gnome.mutter overlay-key 'Foo';}}.<br />
You can leave out '''Foo''' to simply remove any binding to that function.<br />
<br />
{{Note| GNOME also uses {{ic|Alt+F1}} to launch the Overview.}}<br />
<br />
=== Keyboard Shortcut do not work with only conky running ===<br />
The gnome-shell keyboard shortcuts like {{keypress|Alt+F2}}, {{keypress|Alt+F1}}, and the media key shortcuts do not work if conky is the only program running. However if another application like gedit is running, then the keyboard shortcuts work.<br />
<br />
solution: edit .conkyrc <br />
<br />
own_window yes<br />
own_window_transparent yes<br />
own_window_argb_visual yes<br />
own_window_type dock<br />
own_window_class Conky<br />
own_window_hints undecorated,below,sticky,skip_taskbar,skip_pager<br />
<br />
=== xf86-video-ati driver: flickers from time to time ===<br />
<br />
If you use that driver, your desktop might flicker a lot when you hover the bottom right corner, and also when you start up gdm.<br />
Write the following in your '''{{ic|/etc/X11/xorg.conf.d/20-radeon.conf}}''' and see if it works then:<br />
<br />
Section "Device"<br />
Identifier "Radeon"<br />
Driver "radeon"<br />
Option "EnablePageFlip" "off"<br />
EndSection<br />
<br />
https://wiki.archlinux.org/index.php/Intel_Graphics#Choose_acceleration_method<br />
<br />
=== Intel card: Black Screen, Crashes, or Freezes===<br />
If freezing, crashing, or a black screen occur while using an Intel graphics card, it may help to create {{ic|/etc/X11/xorg.conf.d/20-intel.conf}} with the the following to enable SNA acceleration. More information can be found [https://wiki.archlinux.org/index.php/Intel_Graphics#Choose_acceleration_method here].<br />
<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "AccelMethod" "sna"<br />
EndSection<br />
<br />
=== Window opens behind other windows when using multiple monitors ===<br />
<br />
This is possibly a bug in GNOME Shell which causes new windows to open behind others.<br />
Unchecking "workspaces_only_on_primary" in desktop/gnome/shell/windows using gconf-editor solves this problem.<br />
<br />
=== Multiple monitors and dock extension ===<br />
<br />
If you have multiple monitors configured using Nvidia Twinview, the dock extension may get sandwiched in-between the monitors. You can edit the source of this extension to reposition the dock to a position of your choosing.<br />
<br />
Edit {{ic|/usr/share/gnome-shell/extensions/dock@gnome-shell-extensions.gnome.org/extension.js}} and locate this line in the source:<br />
<br />
this.actor.set_position(primary.width-this._item_size-this._spacing-2, (primary.height-height)/2);<br />
<br />
The first parameter is the X position of the dock display, by subtracting 15 pixels as opposed to 2 pixels from this it correctly positioned on my primary monitor, you can play around with any X,Y coordinate pair to position it correctly.<br />
<br />
this.actor.set_position(primary.width-this._item_size-this._spacing-15, (primary.height-height)/2);<br />
<br />
=== No event sounds for Empathy and other programs ===<br />
<br />
If you are using [[OSS]], you may want to install {{AUR|libcanberra-oss}} from the [[AUR]].<br />
<br />
=== Gnome sets the keyboard layout to USA after every log in === <br />
<br />
See the [[https://bugzilla.redhat.com/show_bug.cgi?id=530452 this]] bug report for more information. It is related to GDM and can be fixed by choosing the correct layout at GDM login startup. However, users who do not use GDM or any login manager but a pure startx approach have to use a workaround. Create the file {{ic|~/.keyboard}} and make it executable {{ic|chmod +x}}:<br />
<br />
# Set the correct keyboard layout after Gnome start<br />
setxkbmap -layout "us,pl" -variant altgr-intl -option "grp:alt_shift_toggle" nodeadkeys<br />
<br />
Now run {{ic|gnome-session-properties}} and add this .keyboard file to the programs run at startup:<br />
<br />
Name: Keyboard layout <br />
Command: /home/username/.keyboard<br />
Comment: Sets the correct keyboard layout after Gnome start<br />
<br />
Further you need to create the executable file {{ic|/etc/pm/sleep.d/90_keyboard}} with the following content in order to run the script on resume from suspend and hibernation.<br />
<br />
#!/bin/bash<br />
case $1 in<br />
resume|thaw)<br />
/home/username/.keyboard<br />
;;<br />
esac<br />
<br />
=== Panels do not respond to right-click in fallback mode ===<br />
<br />
Check Configuration Editor: /apps/metacity/general/mouse_button_modifier. This modifier key ({{Keypress|Alt}}, {{Keypress|Super}}, etc) used for normal windows is also used by panels and their applets.<br />
<br />
=== "Show Desktop" keyboard shortcut does not work ===<br />
<br />
GNOME developers treated the corresponding binding as bug (see https://bugzilla.gnome.org/show_bug.cgi?id=643609) due to Minimization being deprecated. To show the desktop again assign ALT+STRG+D to the following setting:<br />
<br />
System Settings --> Keyboard --> Shortcuts --> Navigation --> Hide all normal windows<br />
<br />
=== Nautilus does not start ===<br />
<br />
# Press {{keypress|Alt+F2}}<br />
# Enter {{ic|gnome-tweak-tool}}<br />
# Select the ''File Manager'' tab.<br />
# Locate option ''Have file manager handle the desktop'' and assure it is toggled '''off'''.<br />
<br />
=== Epiphany does not play Flash videos ===<br />
<br />
Adobe Flash Player is buggy and does not work directly in Epiphany. See [[Epiphany#Flash]] for a workaround involving nspluginwrapper.<br />
<br />
=== Unable to apply stored configuration for monitors ===<br />
<br />
If you encounter this message try to disable the xrandr gnome-settings-daemon plugin :<br />
<br />
$ dconf write /org/gnome/settings-daemon/plugins/xrandr/active false<br />
<br />
=== Lock button fails to re-enable touchpad ===<br />
<br />
Some laptops have a touchpad lock button that disables the touchpad so that users can type without worrying about touching the touchpad. It appears currently that although GNOME can lock the touchpad by pressing this button, it cannot unlock it. If the touchpad gets locked you can do the following to unlock it.<br />
# Start a terminal. You can do this by pressing {{keypress|Alt+F2}}, then typing {{ic|gnome-terminal}} followed by pressing {{keypress|Enter}}.<br />
# Type in the following command<br />
$ xinput set-prop "SynPS/2 Synaptics TouchPad" "Device Enabled" 1<br />
<br />
=== Unable to connect to secured Wi-Fi networks ===<br />
<br />
You can see the network connections listing, but choosing an encrypted network fails to show a dialog for key entry. You may need to [[pacman|install]] {{Pkg|network-manager-applet}}. See [[NetworkManager#GNOME|GNOME NetworkManager setup]].<br />
<br />
=== "Any command has been defined 33" ===<br />
<br />
When you press the {{Keypress|Print Screen}} key (sometimes labeled {{Keypress|PrntScr}} or {{Keypress|PrtSc}}) to take a screenshot, and you got "Any command has been defined 33", [[pacman|install]] {{Pkg|metacity}}.<br />
<br />
=== GDM and GNOME use X11 cursors ===<br />
<br />
To fix this problem, become root and put the following into {{ic|/usr/share/icons/default/index.theme}} (creating the directory {{ic|/usr/share/icons/default}} if necessary):<br />
{{hc|/usr/share/icons/default/index.theme|<nowiki><br />
[Icon Theme]<br />
Inherits=Adwaita<br />
</nowiki>}}<br />
<br />
Note: Instead of "Adwaita", you can choose another cursor theme (e.g. Human).<br />
Alternatively, you can install {{AUR|gnome-cursors-fix}} from the [[AUR]].<br />
<br />
=== Tracker & Documents don't list any local files ===<br />
<br />
In order for Tracker (and, therefore, Documents) to detect your local files, they must be stored in directories that it knows of. If your documents are contained in one of the usual XDG standard directories (i.e. "Documents" or "Music"), you should install [https://www.archlinux.org/packages/extra/x86_64/xdg-user-dirs/ xdg-user-dirs] and run:<br />
<br />
# xdg-user-dirs-update<br />
<br />
This will create all of the usual XDG home directories if they don't already exist and it will create the config file definining these directories that Tracker and Documents depend upon.<br />
<br />
=== Passwords are not remembered ===<br />
<br />
If you get a password prompt every time you login, and you find password are not saved, you might need to create/set a default keyring:<br />
<br />
$ pacman -S seahorse<br />
<br />
Open "Passwords and Keys" from the menu or run "seahorse". Select View > By Keyring. If there is no keyring in the left column (it will be marked with a lock icon), go to File > New > Password Keyring and give it a nice name. You will be asked to enter a password. If you do not give it a password it will be unlocked automatically even when using autologin, but passwords will not be stored securely. Finally, right-click on the keyring you just created and select "Set as default".<br />
<br />
=== Windows can't be modified with Alt-Key + Mouse-Button ===<br />
<br />
Change the dconf-setting "org.gnome.desktop.wm.preferences.mouse-button-modifier" from <Super> back to <Alt>. It is not possible to change this with ''System Settings'' > "Keyboard" > "Shortcuts", you will find there only the regular keybindings. The developers of GNOME decided to change this from 3.4 to 3.6 because of this bug report https://bugzilla.gnome.org/show_bug.cgi?id=607797<br />
<br />
=== Gnome-shell 3.8.x fails to load with a black screen + cursor ===<br />
<br />
If you have a non-UTF8 language enabled, Gnome 3 can fail to load. Disable non-UTF-8 locales and perform a locale-gen until this is resolved.<br />
For more information see this bug report: https://bugzilla.gnome.org/show_bug.cgi?id=698952<br />
<br />
== External links ==<br />
* [http://www.gnome.org/ The Official Website of GNOME]<br />
* [http://extensions.gnome.org/ Extensions for GNOME-shell]<br />
* Themes, icons, and backgrounds:<br />
** [http://art.gnome.org/ GNOME Art]<br />
** [http://www.gnome-look.org/ GNOME Look]<br />
* GTK/GNOME programs:<br />
** [http://www.gnomefiles.org/ GNOME Files]<br />
** [http://www.gnome.org/projects/ GNOME Project Listing]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=GNOME&diff=254537GNOME2013-04-18T17:46:36Z<p>Bluerider: /* Prevent suspend when closing the lid */</p>
<hr />
<div>[[Category:Desktop environments]]<br />
[[cs:GNOME]]<br />
[[de:GNOME]]<br />
[[es:GNOME]]<br />
[[fr:GNOME]]<br />
[[it:GNOME]]<br />
[[nl:GNOME]]<br />
[[pl:GNOME]]<br />
[[pt:GNOME]]<br />
[[ru:GNOME]]<br />
[[sr:GNOME]]<br />
[[th:GNOME]]<br />
[[tr:Gnome_Masaüstü_Ortamı]]<br />
[[uk:GNOME]]<br />
[[zh-CN:GNOME]]<br />
[[zh-TW:GNOME]]<br />
{{Article summary start}}<br />
{{Article summary text|GNOME 3 provides a modern desktop, rewritten from scratch, using the GTK3+ toolkit.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Graphical user interface overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|GTK+}}<br />
{{Article summary wiki|GDM}}<br />
{{Article summary wiki|Nautilus}}<br />
{{Article summary end}}<br />
<br />
From [http://www.gnome.org/about/ About Us | GNOME]:<br />
<br />
:''The GNOME Project was started in 1997 by two then university students, Miguel de Icaza and Federico Mena. Their aim: to produce a free (as in freedom) [[desktop environment]]. Since then, GNOME has grown into a hugely successful enterprise. Used by millions of people across the world, it is the most popular desktop environment for GNU/Linux and UNIX-type operating systems. The desktop has been utilised in successful, large-scale enterprise and public deployments, and the project’s developer technologies are utilised in a large number of popular mobile devices.''<br />
<br />
== Introduction ==<br />
<br />
GNOME 3 has ''two'' interfaces:<br />
<br />
*'''GNOME Shell''' is the new standard layout using the Mutter window manager. It acts as a composite manager for the desktop, employing hardware graphics acceleration to provide effects aimed at reducing screen clutter.<br />
<br />
*'''fallback mode''' (known as "classic mode" to some) is similar to GNOME 2, it uses gnome-panel and Metacity instead of gnome-shell/Mutter. No hardware acceleration is required to run fallback mode.<br />
<br />
GNOME-session automatically detects if your computer is incapable of running GNOME Shell and starts fallback mode when appropriate. When you are on fallback mode you can still replace GNOME's default window manager with your preferred one.<br />
<br />
==Installation==<br />
<br />
GNOME 3 is available in the [[official repositories]] and can be [[pacman|installed]] with two groups of packages:<br />
*{{Grp|gnome}} contains the core desktop environment and applications required for the standard GNOME experience.<br />
<br />
*{{Grp|gnome-extra}} contains various optional tools such as a media player, a calculator, an editor and other non-critical applications that go well with the GNOME desktop. Installing this group is optional.<br />
<br />
Note that installing only {{Grp|gnome-extra}} will not pull the whole {{Grp|gnome}} group by dependencies: if you really want everything you must explicitly install both groups.<br />
<br />
=== Starting GNOME ===<br />
<br />
'''Graphical log-in'''<br />
<br />
For the best desktop integration, login manager '''GDM''' is recommended. Other login managers can be used in place of GDM. Check out the [[Display_Manager|wiki article on display managers]] to learn how desktop environments are started.<br />
<br />
The login manager is a limited process entrusted with duties that impact the system. The [[PolicyKit|PolicyKit wiki article]] addresses the topic of system‑wide access control.<br />
<br />
{{Tip|Refer to the [[GDM]] article for installation and configuration instructions.}}<br />
<br />
'''Starting GNOME manually'''<br />
<br />
If you prefer to start GNOME manually from the console, add the following line to your {{ic|~/.xinitrc}} file:<br />
{{hc|~/.xinitrc|<nowiki><br />
exec gnome-session<br />
</nowiki>}}<br />
<br />
After the {{ic|exec}} command is placed, GNOME can be launched by typing {{ic|startx}}.<br />
<br />
See [[xinitrc]] for details, such as preserving the logind (and/or consolekit) session.<br />
<br />
== Using the shell ==<br />
<br />
=== GNOME cheat sheet ===<br />
<br />
The GNOME web site has a helpful [https://live.gnome.org/GnomeShell/CheatSheet GNOME Shell cheat sheet] explaining task switching, keyboard use, window control, the panel, overview mode, and more.<br />
<br />
=== Restarting the shell ===<br />
<br />
After appearance tweaks you are often asked to restart the GNOME shell. You could log out and log back in, but it is simpler and faster to issue the following keyboard command. Restart the shell by pressing {{Keypress|Alt}} + {{Keypress|F2}} then {{Keypress|r}} then {{Keypress|Enter}}<br />
<br />
=== Shell crashes ===<br />
<br />
Certain tweaks and/or repeated shell restarts may cause the shell to crash when a restart is attempted. In this case, you are informed about the crash and then forced to log out. Some shell changes, such as switching between '''''GNOME Shell''''' and '''''fallback mode,''''' cannot be accomplished via a keyboard restart; you must log out and log back in to effect them.<br />
<br />
It is common sense — but worth repeating — that valuable documents should be saved (and perhaps closed) before attempting a shell restart. It is not strictly necessary; open windows and documents usually remain intact after a shell restart.<br />
<br />
=== Shell freezes ===<br />
<br />
Sometimes shell extensions freeze the GNOME Shell. In this case a possible strategy is to switch to another terminal via {{Keypress|Ctrl+Alt+F2}} through {{Keypress|Ctrl+Alt+F6}}, log in, and restart gnome-shell with:<br />
<br />
# pkill -HUP gnome-shell<br />
<br />
All open applications will still be available after restarting the shell.<br />
<br />
Sometimes, however, merely restarting the shell might not be enough. Then you will have to restart X, losing all work in progress. You can restart X by:<br />
<br />
# pkill X<br />
<br />
The GNOME Shell then restarts automatically.<br />
<br />
If this doesn't work, you can try to restart your login manager. For instance, if you use GDM, try:<br />
<br />
# systemctl restart gdm.service<br />
<br />
{{Tip|You can also use '''htop''' in tty; press ''t'', select the ''gnome-shell'' tree, press ''k'' and send ''SIGKILL''.}}<br />
<br />
== Customizing GNOME appearance ==<br />
<br />
=== Overall appearance ===<br />
<br />
GNOME 3 may have "started from scratch", but like most large software projects it is assembled from parts dating to different eras. There is not '''one''' all-encompassing configuration tool. The new ''Systems Settings'' tool is a big improvement over previous control panels. ''System Settings'' is well-organized, but you may find yourself wishing for more control over system appearance.<br />
<br />
You may be familiar with existing configuration tools: some of these still work; many will not. Some settings are not readily exposed for you to change. Indubitably, many settings will migrate to newer tools and/or become exposed as time progresses and the wider community embraces and extends the latest GNOME desktop.<br />
<br />
==== Gsettings ====<br />
<br />
A new command-line tool '''gsettings''' stores data in a binary format, unlike previous tools using XML text. A tutorial [http://blog.fpmurphy.com/2011/03/customizing-the-gnome-3-shell.html Customizing the GNOME Shell] explores the power of gsettings.<br />
<br />
==== GNOME tweak tool ====<br />
<br />
This graphical tool customizes fonts, themes, titlebar buttons and other settings. <br />
<br />
# pacman -S gnome-tweak-tool<br />
<br />
==== GTK3 theme via settings.ini ====<br />
<br />
Like {{ic|~/.gtkrc-2.0}} with GTK2+, it is possible to set a GTK3 theme via {{ic|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini}}.<br />
<br />
Variable {{ic|$XDG_CONFIG_HOME}} is usually set to {{ic|~/.config}}<br />
<br />
''Adwaita,'' the default GNOME 3 theme, is a part of {{pkg|gnome-themes-standard}}. Additional GTK3 themes can be found at [http://browse.deviantart.com/customization/skins/linuxutil/desktopenv/gnome/gtk3/ Deviantart web site.] For example:<br />
{{hc|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini|<nowiki><br />
[Settings]<br />
gtk-theme-name = Adwaita<br />
gtk-fallback-icon-theme = gnome<br />
# next option is applicable only if selected theme supports it<br />
gtk-application-prefer-dark-theme = true<br />
# set font name and dimension<br />
gtk-font-name = Sans 10<br />
</nowiki>}}<br />
<br />
It is necessary to [[#Restarting_the_shell|restart the GNOME shell]] for settings to be applied. More GTK options are found at [http://developer.gnome.org/gtk3/3.0/GtkSettings.html#GtkSettings.properties GNOME developer documentation.]<br />
<br />
==== Icon theme ====<br />
<br />
Using {{pkg|gnome-tweak-tool}} version 3.0.3 and later, you can place any icon theme you wish to use inside {{ic|~/.icons}}.<br />
<br />
Usefully, GNOME 3 is compatible with GNOME 2 icon themes, which means you are not stuck with the default icons. To install a new set of icons, copy your desired icon theme's directory to {{ic|~/.icons}}. As an example:<br />
<br />
$ cp -R /home/user/Desktop/my_icon_theme ~/.icons<br />
<br />
The new theme ''my_icon_theme'' is now selectable using {{ic|gnome-tweak-tool}} under ''interface''.<br />
<br />
Alternatively, you may textually select your icon theme with no need for gnome-tweak-tool. Add the GTK icon theme name to {{ic|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini}}. Please note, not to use "" as your settings would not be recognised then.<br />
<br />
{{hc|${XDG_CONFIG_HOME}/gtk-3.0/settings.ini|<nowiki>... previous lines ...<br />
<br />
gtk-icon-theme-name = my_new_icon_theme</nowiki>}}<br />
<br />
=== Nautilus ===<br />
<br />
''See [[Nautilus]].''<br />
<br />
=== Totem ===<br />
<br />
To play back h.264 videos, you need to install {{Pkg|gst-libav}}<br />
<br />
For more information on gstreamer hardware acceleration, see [[GStreamer#Hardware_Acceleration|Gstreamer: Hardware Acceleration]].<br />
<br />
=== GNOME panel ===<br />
<br />
==== Show date in top bar ====<br />
<br />
By default GNOME displays only the weekday and time in the top bar. This can be changed with the following command. Changes take effect immediately. <br />
<br />
GNOME 3.4.2:<br />
# gsettings set org.gnome.shell.clock show-date true<br />
<br />
GNOME 3.6.2:<br />
# gsettings set org.gnome.desktop.interface clock-show-date true<br />
<br />
==== Always show the "Log Out" entry in the user menu ====<br />
<br />
Since GNOME 3.6, the "Log Out" entry in the user menu is only shown when multiple non-root users are present in the system.<br />
<br />
To always enable this entry, run the following command from a terminal:<br />
<br />
# gsettings set org.gnome.shell always-show-log-out true<br />
<br />
You can also change this in dconf-editor: Navigate to org.gnome.shell, then check the "always-show-log-out" checkbox.<br />
<br />
Then, restart the GNOME shell:<br />
#{{Keypress|Alt+F2}}<br />
#{{Keypress|r}}<br />
#{{Keypress|Enter}}<br />
<br />
==== Hiding icons in the top bar ====<br />
<br />
When doing a GNOME install, some unwanted icons might appear in the panel. These icons can be removed either with GNOME shell extensions or by manually editing the GNOME panel script.<br />
<br />
===== Hiding icons with shell extensions =====<br />
<br />
To remove the accessibility icon, one can use the https://extensions.gnome.org/extension/112/remove-accesibility/. <br />
<br />
The best way to use extensions is installing them from the gnome extensions web page like the one above.<br />
<br />
===== Manually editing the GNOME panel script =====<br />
<br />
For example, to remove the '''universal access icon''', comment out the 'a11y' line in PANEL_ITEM_IMPLEMENTATIONS:<br />
<br />
{{hc|/usr/share/gnome-shell/js/ui/panel.js|<nowiki><br />
const PANEL_ITEM_IMPLEMENTATIONS = {<br />
'activities': ActivitiesButton,<br />
'appMenu': AppMenuButton,<br />
'dateMenu': imports.ui.dateMenu.DateMenuButton,<br />
// 'a11y': imports.ui.status.accessibility.ATIndicator,<br />
'volume': imports.ui.status.volume.Indicator,<br />
'battery': imports.ui.status.power.Indicator,<br />
'lockScreen': imports.ui.status.lockScreenMenu.Indicator,<br />
'keyboard': imports.ui.status.keyboard.InputSourceIndicator,<br />
'powerMenu': imports.gdm.powerMenu.PowerMenuButton,<br />
'userMenu': imports.ui.userMenu.UserMenuButton<br />
};<br />
</nowiki>}}<br />
<br />
Then, save your results and restart the shell:<br />
<br />
#{{Keypress|Alt+F2}}<br />
#{{Keypress|r}}<br />
#{{Keypress|Enter}}<br />
<br />
==== Show battery icon ====<br />
<br />
To show the battery tray icon, [[pacman|install]] {{Pkg|gnome-power-manager}} from the [[Official Repositories|official repositories]].<br />
<br />
==== Disable "Suspend" in the status and gdm menu ====<br />
<br />
A quick way to do it system-wide for GNOME 3.2 is to change line 539 of {{ic|/usr/share/gnome-shell/js/ui/userMenu.js}} and line 103 of {{ic|/usr/share/gnome-shell/js/gdm/powerMenu.js}}. (For GNOME versions prior to 3.2, look at line 153 of {{ic|/usr/share/gnome-shell/js/ui/statusMenu.js}}.) This change takes effect the next time GNOME Shell is started.<br />
<br />
{{hc|/usr/share/gnome-shell/js/ui/userMenu.js|<nowiki><br />
// this._haveSuspend = this._upClient.get_can_suspend(); // Comment this line out.<br />
this._haveSuspend = false; // Use this line instead.<br />
</nowiki>}}<br />
<br />
To accomplish this, paste the following command(s) in your terminal:<br />
GNOME_SHELL=/usr/share/gnome-shell<br />
SCRIPTS=`grep -lr get_can_suspend $GNOME_SHELL/js`<br />
for FILE in $SCRIPTS ; do<br />
sed -r -i -e 's/[^= ]+.get_can_suspend\(\)/false/' "$FILE"<br />
done<br />
<br />
The above change does not persist after a GNOME version update, however. A more perennial solution is to add the code above in some gdm or system startup script (eg: /etc/rc.local), to keep the "suspend" option disabled after updates.<br />
<br />
Alternatively you can install the [[#GNOME shell extensions|GNOME shell extension]] {{ic|alternative status menu}} in package {{Pkg|gnome-shell-extension-alternative-status-menu}}.<br />
<br />
==== Eliminate delay when logging out ====<br />
<br />
The following tweak removes the confirmation dialog and sixty second delay for logging out.<br />
<br />
This dialog normally appears when you log out with the status menu. This tweak affects the '''''Power Off''''' dialog as well. This is not a system-wide change; it affects only the user who enters this command. The change takes effect immediately after entering the command.<br />
<br />
$ gsettings set org.gnome.SessionManager logout-prompt 'false'<br />
<br />
==== Show system monitor ====<br />
<br />
Install the {{AUR|gnome-shell-system-monitor-applet-git}} extension available in the [[AUR]].<br />
<br />
==== Show weather information ====<br />
<br />
Install {{AUR|gnome-shell-extension-weather-git}} from [[AUR]].<br />
<br />
=== Activity view ===<br />
<br />
==== Remove entries from Applications view ====<br />
<br />
Like other desktop environments, GNOME uses .desktop files to populate its Applications view. These text files are in '''{{ic|/usr/share/applications}}'''. It is not possible to edit these files from a folder view ‒ Nautilus does not treat their icons as text files. Use a terminal to display or edit .desktop file entries.<br />
<br />
# ls /usr/share/applications<br />
# nano /usr/share/applications/foo.desktop<br />
<br />
For system wide changes, edit files in '''{{ic|/usr/share/applications}}'''. For local changes, make a copy of ''foo.desktop'' in your home folder.<br />
<br />
$ cp /usr/share/applications/foo.desktop ~/.local/share/applications/<br />
<br />
Edit .desktop files to fit your wishes. <br />
<br />
{{Note|Removing a .desktop file does not uninstall an application, but instead removes its desktop integration: MIME types, shortcuts, and so forth.}}<br />
<br />
The following command appends one line to a .desktop file and hides its associated icon from Applications view:<br />
<br />
$ echo "NoDisplay=true" >> foo.desktop<br />
<br />
==== To Remove Wine Launchers from the Applications menu ====<br />
<br />
Enter {{ic|~/.local/share/applications/wine/Programs/}} and look for the wine application's name. In the directories are the ".desktop" files which configure the launchers. Remove the program directory to easily remove the launchers.<br />
<br />
==== Change application icon size ====<br />
<br />
One awkward selection of the GNOME designers is their choice of large icons for Applications view. This view is painful when working with a small screen containing many large application icons. There is a way to reduce the icon size. It is done by editing the GNOME-Shell theme.<br />
<br />
Edit system files directly (make a backup first) or copy theme files to your local folder and edit these files. <br />
* For the '''default''' theme, edit '''{{ic|/usr/share/gnome-shell/theme/gnome-shell.css}}'''<br />
<br />
* For '''user themes''', edit '''{{ic|/usr/share/themes/<UserTheme>/gnome-shell/gnome-shell.css}}'''<br />
<br />
Edit ''gnome-shell.css'' and replace the following values. Afterward, [[#Restarting_the_shell|restart the GNOME shell.]]<br />
{{hc|gnome-shell.css|<nowiki><br />
...<br />
/* Application Launchers and Grid */<br />
<br />
.icon-grid {<br />
spacing: 18px;<br />
-shell-grid-horizontal-item-size: 82px;<br />
-shell-grid-vertical-item-size: 82px;<br />
}<br />
<br />
.icon-grid .overview-icon {<br />
icon-size: 48px;<br />
}<br />
...<br />
</nowiki>}}<br />
<br />
==== Change dash icon size ====<br />
GNOME's Activities view has a dash on the left hand side, the size of the icons in this dash will scale depending on the amount of icons set to display. The scaling can be manipulated or set to a constant icon size. To do so, edit {{ic|/usr/share/gnome-shell/js/ui/dash.js}}.<br />
<br />
{{hc|dash.js|<nowiki><br />
...<br />
<br />
let iconSizes = [ 16, 22, 24, 32, 48, 64 ];<br />
<br />
...<br />
</nowiki>}}<br />
<br />
==== Change switcher (alt-tab) icon size ====<br />
GNOME comes with a built in task switcher, the size of the icons in this task switcher will scale depending on the amount of icons set to display. The scaling can be manipulated or set to a constant icon size. To do so, edit {{ic|/usr/share/gnome-shell/js/ui/altTab.js}}<br />
<br />
{{hc|altTab.js|<nowiki><br />
...<br />
<br />
const iconSizes = [96, 64, 48, 32, 22];<br />
<br />
...<br />
</nowiki>}}<br />
<br />
==== Change system tray icon size ====<br />
GNOME comes with a built in system tray, visible when the mouse is hovered over the bottom right corner of the screen. The size of the icons in this tray is set to a fixed value of 24. To change this value, edit {{ic|/usr/share/gnome-shell/js/ui/messageTray.js}}<br />
{{hc|messageTray.js|<nowiki><br />
...<br />
<br />
ICON_SIZE: 24,<br />
<br />
...<br />
</nowiki>}}<br />
<br />
==== Disable Activity hot corner hovering ====<br />
<br />
To disable automatic activity view when the hot corner is hovered, edit {{ic|/usr/share/gnome-shell/js/ui/layout.js}} (that was ''panel.js'' in GNOME 3.0.x) :<br />
{{hc|layout.js|<nowiki><br />
this._corner = new Clutter.Rectangle({ name: 'hot-corner',<br />
width: 1,<br />
height: 1,<br />
opacity: 0,<br />
reactive: true });icon-size: 48px;<br />
}<br />
</nowiki>}}<br />
and set {{ic|reactive}} to {{ic|false}}. GNOME Shell needs to be restarted.<br />
<br />
==== Disable Message Tray hovering ====<br />
<br />
The message tray is shown when the mouse hovers at the bottom of the screen for one second. To disable this behavior, comment out the following line in {{ic|/usr/share/gnome-shell/js/ui/messageTray.js}}:<br />
{{hc|messageTray.js|<nowiki><br />
//pointerWatcher.addWatch(TRAY_DWELL_CHECK_INTERVAL, Lang.bind(this, this._checkTrayDwell));<br />
</nowiki>}}<br />
GNOME Shell needs to be restarted. The message tray is still visible in activity view.<br />
<br />
=== Titlebar ===<br />
==== Remove title bar ====<br />
Install [https://extensions.gnome.org/extension/354/maximus/ Maximus] GNOME shell extension.<br />
<br />
It can also have white list / black list of application.<br />
<br />
This extension requires xorg-xprop, install it if you don't have it already.<br />
<br />
{{bc|pacman -S xorg-xprop}}<br />
<br />
More about [[#GNOME shell extensions | GNOME shell extensions]].<br />
<br />
==== Reduce title bar height ====<br />
* ''' global''' - edit {{ic|/usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml}}, search for {{ic|title_vertical_pad}} and and reduce its value to a minimum of {{ic|0}}.<br />
* '''user-only''' - copy {{ic|/usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml}} to {{ic|/home/$USER/.themes/Adwaita/metacity-1/metacity-theme-3.xml}}, search for {{ic|title_vertical_pad}} and reduce its value to a minimum of {{ic|0}}.<br />
<br />
Then [[#Restarting_the_shell|Restart the GNOME shell.]] <br />
<br />
To restore the original values, [[pacman|install]] the package {{Pkg|gnome-themes-standard}} from the [[Official Repositories|official repositories]] or remove {{ic|/home/$USER/.themes/Adwaita/metacity-1/metacity-theme-3.xml}}<br />
<br />
==== Reorder titlebar buttons ====<br />
<br />
At present this setting can be changed through '''dconf-editor.'''<br />
<br />
For example, we move the close and minimize buttons to the left side of the titlebar. Open '''dconf-editor''' and locate the '''''org.gnome.shell.overrides.button_layout''''' key. Change its value to '''{{ic|close,minimize:}}''' (Colon symbol designates the spacer between left side and right side of the titlebar.) Use whichever buttons in whatever order you prefer. You cannot use a button more than once. Also, keep in mind that certain buttons are deprecated. [[#Restarting_the_shell|Restart the shell]] to see your new button arrangement.<br />
<br />
==== Hide titlebar when maximized ====<br />
<br />
# sed -i -r 's|(<frame_geometry name="max")|\1 has_title="false"|' /usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml<br />
<br />
[[#Restarting_the_shell|Restart the GNOME shell.]] After this tweak, you may find it difficult to un-maximize a window when there is no titlebar to grab.<br />
<br />
With suitable keybindings, you should be able to use {{Keypress|Alt+F5}}, {{Keypress|Alt+F10}} or {{Keypress|Alt+Space}} to remedy the situation.<br />
<br />
To prevent {{ic|metacity-theme-3.xml}} from being overwritten each time package {{pkg|gnome-themes-standard}} is upgraded, add its name to {{ic|/etc/pacman.conf}} with {{ic|NoUpgrade}}.<br />
<br />
{{hc|/etc/pacman.conf|<nowiki>... previous lines ...<br />
<br />
# Pacman won't upgrade packages listed in IgnorePkg and members of IgnoreGroup<br />
# IgnorePkg =<br />
# IgnoreGroup =<br />
<br />
NoUpgrade = usr/share/themes/Adwaita/metacity-1/metacity-theme-3.xml # Do not add a leading slash to the path<br />
<br />
... more lines ...</nowiki>}}<br />
<br />
To restore original Adwaita theme values, install the {{pkg|gnome-themes-standard}} package.<br />
<br />
=== Login screen ===<br />
{{Merge|GDM|Login managers have their own wiki pages and information should be maintained separately.}}<br />
To modify characteristics of the login screen (GDM, the GNOME display manager) the following lines can be executed. The first command allows all users, including "gdm", to access X settings (albeit temporarily). This command creates a temporary vulnerability, so be advised. The second command opens a bash session with the credentials of user "gdm". {{Note|For exposition, user gdm's terminal prompt is shown as '''$'''. In actuality, it shows something like -bash-4.2$.}}<br />
<br />
# xhost +<br />
# su - gdm -s /bin/bash<br />
$ dbus-launch<br />
<br />
The third command prints DBUS_SESSION_BUS_ADDRESS and DBUS_SESSION_BUS_PID. We must export these variables. Either manually export the below two variables shown in the output of dbus-launch like this:<br />
<br />
$ export DBUS_SESSION_BUS_ADDRESS=unix:abstract=/tmp/dbus-Jb433gMQHS,guid=fc14d4bf3d000e38276a5a2200000d38<br />
$ export DBUS_SESSION_BUS_PID=4283<br />
<br />
Or use the follow command:<br />
<br />
$ `dbus-launch | sed "s/^/export /"`<br />
<br />
Check to see if dconf-service is running and if not, start it like this<br />
<br />
$ /usr/lib/dconf/dconf-service &<br />
<br />
==== Login background image ====<br />
<br />
Once session variables have been exported as explained above, you may issue commands to retrieve or set items used by GDM. <br />
<br />
The easiest way to changes all the settings is by launching the Configuration Editor gui with the command<br />
<br />
$ dconf-editor<br />
<br />
The location of each setting is the same as in the command line style of configuration shown below:<br />
<br />
The following is the command-line approach to retrieve or set the file name used for GDM's wallpaper.<br />
{{bc|<nowiki><br />
$ GSETTINGS_BACKEND=dconf gsettings get org.gnome.desktop.background picture-uri<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.background picture-uri 'file:///usr/share/backgrounds/gnome/SundownDunes.jpg'<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.background picture-options 'zoom'<br />
## Possible values: centered, none, scaled, spanned, stretched, wallpaper, zoom</nowiki>}}<br />
{{Note|You must specify a file which user "gdm" has permission to read. GDM cannot read files in your home directory.}}<br />
<br />
An alternative graphical interface to changing themes (gtk3, icons and cursor), the wallpaper and minor other settings of the GDM login screen, you can install {{aur|gdm3setup}} from AUR.<br />
<br />
==== Larger font for login ====<br />
<br />
This tweak enlarges the login font with a scaling factor. It is the same method employed by ''Accessibility Manager'' on the desktop.<br />
<br />
You must [[#Login_screen|export the GDM session variables]] before performing this tweak.<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.interface text-scaling-factor '1.25'<br />
<br />
==== Turning off the sound ====<br />
<br />
This tweak disables the audible feedback heard when the system volume is adjusted (via keyboard) on the login screen. You must first export the GDM session variables.<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.desktop.sound event-sounds 'false'<br />
<br />
If the above tweak does not work for you or you are unable to export the GDM session variables, there is always the easiest solution to the "ready sound" problem: mute or lower the sound while in GDM login screen using the media keys (if available) of your keyboard.<br />
<br />
==== Make the power button interactive ====<br />
<br />
The default installation sets the power button to suspend the system. '''''Power off''''' or '''''Show dialog''''' is a better choice. You must first export the GDM session variables as [[#Login_screen|outlined previously.]]<br />
<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.settings-daemon.plugins.power button-power 'interactive'<br />
$ GSETTINGS_BACKEND=dconf gsettings set org.gnome.settings-daemon.plugins.power button-hibernate 'interactive'<br />
$ gsettings list-recursively org.gnome.settings-daemon.plugins.power<br />
<br />
{{Warning|Please note that the [[Acpid|acpid]] daemon also handle the "power button" an "hibernate button" event. Running both systems at the same time may lead to unexpected behaviour.}}<br />
<br />
==== Prevent suspend when closing the lid ====<br />
<br />
On some systems it happens that your laptop suspends when you are closing the lid despite having set the options ''Laptop lid close action on battery'' and ''Laptop lid close action on AC'' to ''blank''. If this is the case, append the following line to {{ic|/etc/systemd/logind.conf}}:<br />
<br />
HandleLidSwitch=ignore<br />
<br />
==== Change Critical Battery Level Action (for Laptops) ====<br />
<br />
The {{pkg|gnome-power-manager}} gui doesn't have a choice for "do nothing" on laptops at critical battery level. To manually edit this, open the {{pkg|dconf}}-editor -> org -> gnome -> settings-daemon -> plugins -> power. Edit the "critical-battery-action" value to "nothing".<br />
<br />
==== GDM keyboard layout ====<br />
<br />
GDM does not know about your GNOME 3 desktop keyboard settings. To change keyboard settings used by GDM, set your layout using Xorg configuration. Refer to this section of the [[Beginners'_Guide#Non-US_keyboard|Beginner's Guide.]]<br />
<br />
=== Other tips ===<br />
See [[GNOME Tips]].<br />
<br />
== Miscellaneous settings ==<br />
<br />
=== Automatic program launch upon logging in ===<br />
<br />
Specify which programs start automatically after logging in using {{ic|gnome-session-properties}}. This tool is part of the {{Pkg|gnome-session}} package.<br />
<br />
$ gnome-session-properties<br />
<br />
=== Editing applications menu ===<br />
<br />
{{pkg|gnome-menus}} provides ''gmenu-simple-editor'' which can show/hide menu entries.<br />
<br />
{{pkg|alacarte}} provides a more complete menu editor for adding/editing menu entries.<br />
<br />
=== Some 'System Settings' not preserved ===<br />
<br />
GNOME 3 is using [[systemd]] (an init daemon for Linux) with more modern capabilities. Previously GNOME programs were altered to use Arch's init functionalities to gather settings but either the maintenance required to do this or possibly this is because of a transitioning to the new init system (read more about this [https://bbs.archlinux.org/viewtopic.php?pid=1115208#p1115208 here]). Areas that settings will not be preserved are '''Date and Time''' and adding ICC profiles in the '''Color''' menu and possibly others.<br />
<br />
To gain the functionality back, [[systemd]] needs to be installed and the ''gdm.service'' and ''NetworkManager.service'' services need to be enabled.<br />
<br />
=== Disable sound effects in Terminal ===<br />
By default the terminal has these annoying sound effects when e.g. pushing the tab button on your keyboard. One solution is to turn off or mute all sound effects in the settings menu of Gnome. However, this will also turn off notification sounds in other application such as Skype. A better solution is to open a terminal, go to Edit -> Profile Preferences -> General and untick '''Terminal bell'''.<br />
<br />
=== Move dialog windows ===<br />
The default configuration for dialogs will not allow you to move them which causes problems in some cases. To change this you will need to use gconf-editor and change this setting:<br />
<br />
/desktop/gnome/shell/windows/attach_modal_dialogs<br />
<br />
After the change you will need to restart the shell for it to take affect.<br />
<br />
=== GNOME shell extensions ===<br />
<br />
GNOME Shell can be customized with extensions. These provide features such as a dock or a widget for changing the theme.<br />
<br />
Many extensions are collected and hosted by [https://extensions.gnome.org/ extensions.gnome.org]. They can be browsed and installed simply activating them in the browser. More information about gnome shell extensions can be found [https://extensions.gnome.org/about/ here].<br />
<br />
See [[#When_an_extension_breaks_GNOME|when an extension breaks GNOME]] for troubleshooting information.<br />
<br />
=== Default file browser/replace Nautilus ===<br />
<br />
You can trick GNOME into using another file browser by editing the {{ic|Exec}} line in {{ic|/usr/share/applications/nautilus.desktop}}. See the correct parameters in the {{ic|.desktop}} file of the file manager of your choice, e.g.:<br />
{{hc|/usr/share/applications/nautilus.desktop|<br />
2=[...]<br />
Exec=thunar %F<br />
OR<br />
Exec=pcmanfm %U<br />
OR<br />
Exec=nemo %U<br />
[...]<br />
}}<br />
<br />
=== Default PDF viewer ===<br />
In some cases when you have installed Inkscape or other graphic programs Evince Document Viewer might no longer be selected as the default PDF application. If it is not available in the '''Open With''' entry which would be the GUI solution, you can use the following user command to make it the default application again.<br />
<br />
xdg-mime default evince.desktop application/pdf<br />
<br />
=== Default terminal ===<br />
<br />
{{ic|gsettings}} (which replaces {{ic|gconftool-2}}) is used to set the default terminal. The setting affects ''nautilus-open-terminal'' (a Nautilus extension).<br />
To make [[rxvt-unicode|urxvt]] the default, run:<br />
<br />
gsettings set org.gnome.desktop.default-applications.terminal exec urxvtc<br />
gsettings set org.gnome.desktop.default-applications.terminal exec-arg "'-e'"<br />
<br />
{{Note|The {{ic|-e}} flag is for executing a command. When ''nautilus-open-terminal'' invokes {{ic|urxvtc}}, it puts a {{ic|cd}} command at the end of the command line so that the new terminal starts in the directory you opened it from. Other terminals will require a different (perhaps empty) {{ic|exec-arg}}.}}<br />
<br />
=== Middle mouse button ===<br />
<br />
By default, GNOME 3 disables middle mouse button emulation regardless of [[Xorg]] settings ('''Emulate3Buttons'''). To enable middle mouse button emulation use:<br />
<br />
$ gsettings set org.gnome.settings-daemon.peripherals.mouse middle-button-enabled true<br />
<br />
=== Display dimming ===<br />
<br />
By default GNOME 3 has a ten second idle timeout to dim the screen regardless of the battery and AC state:<br />
<br />
gsettings get org.gnome.settings-daemon.plugins.power idle-dim-time<br />
<br />
To set a new value type the following<br />
<br />
gsettings set org.gnome.settings-daemon.plugins.power idle-dim-time <int><br />
<br />
where <int> is the value in seconds<br />
<br />
=== Alternate window manager ===<br />
<br />
You can use an alternate window manager with GNOME by [[#Enabling_fallback_mode|forcing fallback mode]] and creating two files:<br />
<br />
{{Note|Xmonad is used as an example, but this works for other window managers.}}<br />
<br />
{{hc|/usr/share/gnome-session/sessions/xmonad.session|<nowiki>[GNOME Session]<br />
Name=Xmonad session<br />
RequiredComponents=gnome-panel;gnome-settings-daemon;<br />
RequiredProviders=windowmanager;notifications;<br />
DefaultProvider-windowmanager=xmonad<br />
DefaultProvider-notifications=notification-daemon</nowiki>}}<br />
<br />
{{hc|/usr/share/xsessions/xmonad-gnome-session.desktop|<nowiki>[Desktop Entry]<br />
Name=Xmonad GNOME<br />
Comment=Tiling window manager<br />
TryExec=/usr/bin/gnome-session<br />
Exec=gnome-session --session=xmonad<br />
Type=XSession</nowiki>}}<br />
<br />
The next time you log in, you should have the ability to choose ''Xmonad GNOME'' as your session.<br />
<br />
If there isn't a .desktop file for the window manager, you'll need to create one. Example for [[wmii]]:<br />
<br />
{{hc|/usr/share/applications/wmii.desktop|<nowiki><br />
[Desktop Entry]<br />
Version=1.0<br />
Type=Application<br />
Name=wmii<br />
TryExec=wmii<br />
Exec=wmii</nowiki>}}<br />
<br />
For more information, see [http://makandra.com/notes/1367-running-the-awesome-window-manager-within-gnome this article on running awesome as the window manager in GNOME].<br />
<br />
== Hidden features ==<br />
<br />
GNOME 3 hides many useful options which you can customize with '''dconf-editor.''' GNOME 3 also supports '''gconf-editor''' for settings that have not yet migrated to dconf.<br />
<br />
=== Changing hotkeys ===<br />
It is possible to manually change the keys via an application's so-called accel map file. Where it is to be found is up to the application: For instance, Thunar's is at ~/.config/Thunar/accels.scm, whereas Nautilus's is located at ~/.config/nautilus/accels and ~/.gnome2/accels/nautilus on old release.<br />
<br />
The file should contain a list of possible hotkeys, each unchanged line commented out with a leading ";" that has to be removed for a change to become active.<br />
For example to replace the hotkey used by Nautilus to move files to the trash folder, change the line :<br />
; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")<br />
to this :<br />
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")<br />
<br />
The file is regenerate regularly so don't waist time on commenting the file. The uncommented line will stay but every comment you may add will be lost.<br />
<br />
==== Nautilus 3.4 and older ====<br />
Firstly, use '''dconf-editor''' to place a checkmark next to {{ic|can-change-accels}} in the key named ''org.gnome.desktop.interface.''<br />
<br />
We will replace the hotkey — a.k.a. keyboard shortcut, keyboard accelerator — used by Nautilus to move files to the trash folder.<br />
The default assignment is a somewhat-awkward {{Keypress|Ctrl+Delete}}.<br />
* Open Nautilus, select any file, and click '''Edit''' on the menu bar.<br />
* Hover over the ''Move to Trash'' menu item.<br />
* While hovering, press {{Keypress|Delete}}. The current accelerator is now unset.<br />
* Press the key that you wish to become the new keyboard accelerator.<br />
* Press {{Keypress|Delete}} to make the new accelerator be the Delete key.<br />
Unless you select a file or folder, ''Move to Trash'' will be grayed-out. Finally, disable {{ic|can-change-accels}} to prevent accidental hotkey changes.<br />
<br />
=== Shutdown via the status menu ===<br />
<br />
Currently, the GNOME designers have hidden the ''Shutdown'' option inside the status menu. To shut down your system with the status menu, click the menu and hold down the {{Keypress|Alt}} key so that the '''''Suspend''''' item changes to '''''Power Off'''''. The subsequent dialog allows you to shut down or restart your system.<br />
<br />
If you disable the Suspend menu item system-wide as described [[#Disable_"Suspend"_in_the_status_menu|elsewhere in this document]] you do not have to go through these motions.<br />
<br />
Another option is to install the ''Alternative Status Menu'' extension. See the section on shell extensions. The alternative menu extension installs a new status menu with a non-hidden '''''Power Off''''' entry.<br />
<br />
=== Modify Keyboard with XkbOptions ===<br />
<br />
Using the '''dconf-editor''', navigate to the key named ''org.gnome.desktop.input-sources.xkb-options'' and add desired XkbOptions (e.g. 'caps:swapescape') to the list.<br />
<br />
See /usr/share/X11/xkb/rules/xorg for all XkbOptions and then /usr/share/X11/xkb/symbols/* for the respective descriptions.<br />
<br />
=== Toggle keyboard layouts ===<br />
Since Gnome does not consider any configuration in {{ic|/etc/X11/conf.d/*.conf}} you have to set the command for layout switching either via the control center with the options ''Switch to previous source'' and ''Switch to next source'' or if you want to use Alt - Shift combination you have to use the Gnome-Tweak-Tool and set ''Typing -> Modifiers-only input sources -> select Alt-shift''. For more information see also the forum [https://bbs.archlinux.org/viewtopic.php?id=152127 thread].<br />
<br />
== Integrated messaging (Empathy) ==<br />
<br />
Empathy, the engine behind integrated messaging, and all system settings based on messaging accounts will not show up unless the {{grp|telepathy}} group of packages or at least one of the backends ({{pkg|telepathy-gabble}}, or {{pkg|telepathy-haze}}, for example) is installed.<br />
<br />
These packages are not included in default Arch GNOME installs. You can install the Telepathy and optionally any backends with:<br />
<br />
# pacman -S telepathy<br />
<br />
Without telepathy, Empathy will not open the account management dialog and can get stuck in this state. If this happens -- even after quitting Empathy cleanly -- the {{ic|/usr/bin/empathy-accounts}} application can remain running and will need to be killed before you can add any new accounts.<br />
<br />
View descriptions of telepathy components on the [http://telepathy.freedesktop.org/wiki/Components Freedesktop.org Telepathy Wiki.]<br />
<br />
== Forcing fallback mode ==<br />
<br />
Your session automatically starts in fallback mode when '''gnome-shell''' is not present, or when your hardware cannot handle graphics acceleration — such as running within a virtual machine or running on old hardware.<br />
<br />
If you wish to enable fallback mode while still having '''gnome-shell''' installed, make the following system change:<br />
<br />
Go to '''System Settings''' ({{ic|gnome-control-center}}) -> '''Details''' -> '''Graphics''' and set '''Forced Fallback Mode''' to {{ic|ON}}.<br />
<br />
You can alternatively choose the type of session from a terminal with {{ic|gsettings}}:<br />
<br />
$ gsettings set org.gnome.desktop.session session-name gnome-fallback<br />
<br />
You may want to log out after making the change. You will see the chosen type of session upon your next login.<br />
<br />
To disable the forced-fallback mode change it back to {{ic|gnome}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== When an extension breaks GNOME ===<br />
<br />
When enabling shell extensions causes GNOME breakage, you should first remove the ''user-theme'' and ''auto-move-windows'' extensions from their installation directory.<br />
<br />
The installation directory could be one of '''{{ic|~/.local/share/gnome‑shell/extensions,}}''' '''{{ic|/usr/share/gnome‑shell/extensions,}}''' or '''{{ic|/usr/local/share/gnome‑shell/extensions}}'''. Removing these two extension-containing folders may fix the breakage. Otherwise, isolate the problem extension with trial‑and‑error.<br />
<br />
Removing or adding an extension-containing folder to the aforementioned directories removes or adds the corresponding extension to your system. Details on GNOME Shell extensions are available at the [https://live.gnome.org/GnomeShell/Extensions GNOME web site.]<br />
<br />
=== Extensions do not work after GNOME 3 update ===<br />
<br />
Locate the folder where your extensions are installed. It might be '''{{ic|~/.local/share/gnome-shell/extensions}}''' or '''{{ic|/usr/share/gnome-shell/extensions}}'''.<br />
<br />
Edit each occurrence of '''{{ic|metadata.json}}''' which appears in each extension sub-folder. <br />
<br />
{| border="0"<br />
| Insert: || '''{{ic|"shell-version": ["3.6"]}}'''<br />
|-<br />
| Instead of (for example): || '''{{ic|"shell-version": ["3.4"]}}'''<br />
|}<br />
<br />
<br />
'''"3.x"''' indicates the extension works with every Shell version. If it breaks, you'll know to change it back.<br />
<br />
=== The "Windows" key ===<br />
By default, this key is mapped to the "overlay-key" to launch the Overview. You can remove this key mapping to free up your {{ic|Windows Key}} (also called {{ic|Mod4}}), which GNOME calls {{ic|Super_L}}, by utilizing {{ic|gsettings}}.<br />
<br />
Example:<br />
{{ic| gsettings set org.gnome.mutter overlay-key 'Foo';}}.<br />
You can leave out '''Foo''' to simply remove any binding to that function.<br />
<br />
{{Note| GNOME also uses {{ic|Alt+F1}} to launch the Overview.}}<br />
<br />
=== Keyboard Shortcut do not work with only conky running ===<br />
The gnome-shell keyboard shortcuts like {{keypress|Alt+F2}}, {{keypress|Alt+F1}}, and the media key shortcuts do not work if conky is the only program running. However if another application like gedit is running, then the keyboard shortcuts work.<br />
<br />
solution: edit .conkyrc <br />
<br />
own_window yes<br />
own_window_transparent yes<br />
own_window_argb_visual yes<br />
own_window_type dock<br />
own_window_class Conky<br />
own_window_hints undecorated,below,sticky,skip_taskbar,skip_pager<br />
<br />
=== xf86-video-ati driver: flickers from time to time ===<br />
<br />
If you use that driver, your desktop might flicker a lot when you hover the bottom right corner, and also when you start up gdm.<br />
Write the following in your '''{{ic|/etc/X11/xorg.conf.d/20-radeon.conf}}''' and see if it works then:<br />
<br />
Section "Device"<br />
Identifier "Radeon"<br />
Driver "radeon"<br />
Option "EnablePageFlip" "off"<br />
EndSection<br />
<br />
=== Window opens behind other windows when using multiple monitors ===<br />
<br />
This is possibly a bug in GNOME Shell which causes new windows to open behind others.<br />
Unchecking "workspaces_only_on_primary" in desktop/gnome/shell/windows using gconf-editor solves this problem.<br />
<br />
=== Multiple monitors and dock extension ===<br />
<br />
If you have multiple monitors configured using Nvidia Twinview, the dock extension may get sandwiched in-between the monitors. You can edit the source of this extension to reposition the dock to a position of your choosing.<br />
<br />
Edit {{ic|/usr/share/gnome-shell/extensions/dock@gnome-shell-extensions.gnome.org/extension.js}} and locate this line in the source:<br />
<br />
this.actor.set_position(primary.width-this._item_size-this._spacing-2, (primary.height-height)/2);<br />
<br />
The first parameter is the X position of the dock display, by subtracting 15 pixels as opposed to 2 pixels from this it correctly positioned on my primary monitor, you can play around with any X,Y coordinate pair to position it correctly.<br />
<br />
this.actor.set_position(primary.width-this._item_size-this._spacing-15, (primary.height-height)/2);<br />
<br />
=== No event sounds for Empathy and other programs ===<br />
<br />
If you are using [[OSS]], you may want to install {{AUR|libcanberra-oss}} from the [[AUR]].<br />
<br />
=== Gnome sets the keyboard layout to USA after every log in === <br />
<br />
See the [[https://bugzilla.redhat.com/show_bug.cgi?id=530452 this]] bug report for more information. It is related to GDM and can be fixed by choosing the correct layout at GDM login startup. However, users who do not use GDM or any login manager but a pure startx approach have to use a workaround. Create the file {{ic|~/.keyboard}} and make it executable {{ic|chmod +x}}:<br />
<br />
# Set the correct keyboard layout after Gnome start<br />
setxkbmap -layout "us,pl" -variant altgr-intl -option "grp:alt_shift_toggle" nodeadkeys<br />
<br />
Now run {{ic|gnome-session-properties}} and add this .keyboard file to the programs run at startup:<br />
<br />
Name: Keyboard layout <br />
Command: /home/username/.keyboard<br />
Comment: Sets the correct keyboard layout after Gnome start<br />
<br />
Further you need to create the executable file {{ic|/etc/pm/sleep.d/90_keyboard}} with the following content in order to run the script on resume from suspend and hibernation.<br />
<br />
#!/bin/bash<br />
case $1 in<br />
resume|thaw)<br />
/home/username/.keyboard<br />
;;<br />
esac<br />
<br />
=== Panels do not respond to right-click in fallback mode ===<br />
<br />
Check Configuration Editor: /apps/metacity/general/mouse_button_modifier. This modifier key ({{Keypress|Alt}}, {{Keypress|Super}}, etc) used for normal windows is also used by panels and their applets.<br />
<br />
=== "Show Desktop" keyboard shortcut does not work ===<br />
<br />
GNOME developers treated the corresponding binding as bug (see https://bugzilla.gnome.org/show_bug.cgi?id=643609) due to Minimization being deprecated. To show the desktop again assign ALT+STRG+D to the following setting:<br />
<br />
System Settings --> Keyboard --> Shortcuts --> Navigation --> Hide all normal windows<br />
<br />
=== Nautilus does not start ===<br />
<br />
# Press {{keypress|Alt+F2}}<br />
# Enter {{ic|gnome-tweak-tool}}<br />
# Select the ''File Manager'' tab.<br />
# Locate option ''Have file manager handle the desktop'' and assure it is toggled '''off'''.<br />
<br />
=== Epiphany does not play Flash videos ===<br />
<br />
Adobe Flash Player is buggy and does not work directly in Epiphany. See [[Epiphany#Flash]] for a workaround involving nspluginwrapper.<br />
<br />
=== Unable to apply stored configuration for monitors ===<br />
<br />
If you encounter this message try to disable the xrandr gnome-settings-daemon plugin :<br />
<br />
$ dconf write /org/gnome/settings-daemon/plugins/xrandr/active false<br />
<br />
=== Lock button fails to re-enable touchpad ===<br />
<br />
Some laptops have a touchpad lock button that disables the touchpad so that users can type without worrying about touching the touchpad. It appears currently that although GNOME can lock the touchpad by pressing this button, it cannot unlock it. If the touchpad gets locked you can do the following to unlock it.<br />
# Start a terminal. You can do this by pressing {{keypress|Alt+F2}}, then typing {{ic|gnome-terminal}} followed by pressing {{keypress|Enter}}.<br />
# Type in the following command<br />
$ xinput set-prop "SynPS/2 Synaptics TouchPad" "Device Enabled" 1<br />
<br />
=== Unable to connect to secured Wi-Fi networks ===<br />
<br />
You can see the network connections listing, but choosing an encrypted network fails to show a dialog for key entry. You may need to [[pacman|install]] {{Pkg|network-manager-applet}}. See [[NetworkManager#GNOME|GNOME NetworkManager setup]].<br />
<br />
=== "Any command has been defined 33" ===<br />
<br />
When you press the {{Keypress|Print Screen}} key (sometimes labeled {{Keypress|PrntScr}} or {{Keypress|PrtSc}}) to take a screenshot, and you got "Any command has been defined 33", [[pacman|install]] {{Pkg|metacity}}.<br />
<br />
=== GDM and GNOME use X11 cursors ===<br />
<br />
To fix this issue, become root and put the following into {{ic|/usr/share/icons/default/index.theme}} (creating the directory {{ic|/usr/share/icons/default}} if necessary):<br />
{{hc|/usr/share/icons/default/index.theme|<nowiki><br />
[Icon Theme]<br />
Inherits=Adwaita<br />
</nowiki>}}<br />
<br />
Note: Instead of "Adwaita", you can choose another cursor theme (e.g. Human).<br />
Alternatively, you can install {{AUR|gnome-cursors-fix}} from the [[AUR]].<br />
<br />
=== Tracker & Documents don't list any local files ===<br />
<br />
In order for Tracker (and, therefore, Documents) to detect your local files, they must be stored in directories that it knows of. If your documents are contained in one of the usual XDG standard directories (i.e. "Documents" or "Music"), you should install [https://www.archlinux.org/packages/extra/x86_64/xdg-user-dirs/ xdg-user-dirs] and run:<br />
<br />
# xdg-user-dirs-update<br />
<br />
This will create all of the usual XDG home directories if they don't already exist and it will create the config file definining these directories that Tracker and Documents depend upon.<br />
<br />
=== Passwords are not remembered ===<br />
<br />
If you get a password prompt every time you login, and you find password are not saved, you might need to create/set a default keyring:<br />
<br />
$ pacman -S seahorse<br />
<br />
Open "Passwords and Keys" from the menu or run "seahorse". Select View > By Keyring. If there is no keyring in the left column (it will be marked with a lock icon), go to File > New > Password Keyring and give it a nice name. You will be asked to enter a password. If you do not give it a password it will be unlocked automatically even when using autologin, but passwords will not be stored securely. Finally, right-click on the keyring you just created and select "Set as default".<br />
<br />
=== Windows can't be modified with Alt-Key + Mouse-Button ===<br />
<br />
Change the dconf-setting "org.gnome.desktop.wm.preferences.mouse-button-modifier" from <Super> back to <Alt>. It is not possible to change this with ''System Settings'' > "Keyboard" > "Shortcuts", you will find there only the regular keybindings. The developers of GNOME decided to change this from 3.4 to 3.6 because of this bug report https://bugzilla.gnome.org/show_bug.cgi?id=607797<br />
<br />
== External links ==<br />
* [http://www.gnome.org/ The Official Website of GNOME]<br />
* [http://extensions.gnome.org/ Extensions for GNOME-shell]<br />
* Themes, icons, and backgrounds:<br />
** [http://art.gnome.org/ GNOME Art]<br />
** [http://www.gnome-look.org/ GNOME Look]<br />
* GTK/GNOME programs:<br />
** [http://www.gnomefiles.org/ GNOME Files]<br />
** [http://www.gnome.org/projects/ GNOME Project Listing]</div>Blueriderhttps://wiki.archlinux.org/index.php?title=QEMU&diff=249867QEMU2013-03-08T04:02:22Z<p>Bluerider: /* KVM method (hardware virtualization) */</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Virtualization]]<br />
[[de:Qemu]]<br />
[[es:Qemu]]<br />
[[fr:Qemu]]<br />
[[zh-CN:QEMU]]<br />
From the [http://wiki.qemu.org/Main_Page QEMU about page],<br />
<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 own PC). By using dynamic translation, it achieves very good performance.<br />
<br />
When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU. QEMU supports virtualization when executing under the Xen hypervisor or using the KVM kernel module in Linux. When using KVM, QEMU can virtualize x86, server and embedded PowerPC, and S390 guests.<br />
<br />
== Installing QEMU ==<br />
<br />
Install {{Pkg|qemu}} from the [[Official Repositories|official repositories]]. {{ic|qemu-kvm}} has been fully merged with upstream {{pkg|qemu}} starting with version 1.3.0, so the {{ic|qemu-kvm}} package is gone.<br />
<br />
You can use KVM with the {{Pkg|qemu}} package, if supported by your processor and kernel, provided that you start QEMU with the {{ic|-enable-kvm}} argument.<br />
<br />
== Creating a hard disk image==<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 may simply contain the literal contents, byte for byte, of the hard disk. This is usually called ''raw'' format, and it provides the least I/O overhead, although the images may take up a large amount of space.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' that can save enormous amounts of space by only allocating 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.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. The following command creates a 4GB image named {{ic|myimage.qcow2}} in the qcow2 format:<br />
$ qemu-img create -f qcow2 myimage.qcow2 4G<br />
<br />
You may use {{ic|-f raw}} to create a raw disk instead, although you can also do so simply by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.<br />
<br />
== Preparing the installation media ==<br />
<br />
To install an operating system into your disk image, you need the installation media (e.g. CD-ROM, floppy, or ISO image) for the operating system.<br />
<br />
{{Tip|If you would like to run an Arch Linux virtual machine, you can install it using the [https://www.archlinux.org/download/ official installation media for Arch Linux]. It is also possible to set up an Arch Linux virtual machine without the installation media, provided that your host machine is running Arch Linux, although this is more difficult; it is detailed [[Creating Arch Linux disk image#Install Arch Linux in a disk image without the installation media|here]].}}<br />
<br />
The installation media should not be mounted because QEMU accesses the media directly. Also, if using physical media (e.g. CD-ROM or floppy), 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:<br />
# dd if=/dev/cdrom of=mycdimg.iso<br />
<br />
Do the same for floppy drives:<br />
# dd if=/dev/fd of=myfloppy.img<br />
<br />
== Installing the operating system==<br />
<br />
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 />
This is the first time you will need to start the emulator. By default, QEMU will show the virtual machine's video output in a window. <br />
One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it press {{Keypress|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 />
=== Standard method (software emulation)===<br />
<br />
On i386 systems, to install from a bootable ISO file as CD-ROM, run QEMU with:<br />
$ qemu -cdrom <iso_image> -boot d <qemu_image><br />
<br />
On x86_64 systems:<br />
$ qemu-system-x86_64 -cdrom <iso_image> -boot d <qemu_image><br />
<br />
See the parameters in {{ic|qemu --help}} for 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, for example on i386:<br />
<br />
$ qemu <qemu_image><br />
<br />
{{Tip|By default only 128MB of memory is assigned to the machine, the amount of memory can be adjusted with the -m switch, for example {{ic|-m 512}}.}}<br />
<br />
=== KVM method (hardware virtualization) ===<br />
<br />
<br />
KVM, short for Kernel-based Virtual Machine, is a full virtualization solution for Linux on x86 hardware containing virtualization extensions (Intel VT or AMD-V). It relies on the kernel modules {{ic|kvm}} and either {{ic|kvm-intel}} or {{ic|kvm-amd}}. KVM interfaces via {{ic|/dev/kvm}}, which requires users to be part of the {{ic|kvm}} group. <br />
<br />
For 32 bit systems : <br />
The command to use with the standard {{Pkg|qemu}} package is:<br />
$ qemu -enable-kvm<br />
<br />
For 64 bit systems:<br />
The command to use with the standard {{Pkg|qemu}} package is:<br />
$ qemu-system-x86_64 -enable-kvm<br />
<br />
There is a dedicated [[KVM]] wiki page with more detailed information and instructions.<br />
<br />
{{Note|If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{Keypress|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 {{Keypress|Ctrl-Alt-1}} to go back to the virtual machine.}}<br />
<br />
== Overlay images ==<br />
<br />
A good idea is to use overlay images. This way you can a create hard disk image once and tell QEMU to store changes in an external file.<br />
This makes it easy to revert the virtual machine's disk to a previous state.<br />
<br />
To create an overlay image, type:<br />
$<nowiki> qemu-img create -b [[base_image]] -f qcow2 [[overlay_image]]</nowiki><br />
<br />
After that you can run qemu with:<br />
$ qemu [overlay_image]<br />
<br />
or if you are on a x86_64 system:<br />
$ qemu-system-x86_64 [overlay_image]<br />
<br />
and the original image will be left untouched. One hitch, the base image cannot be renamed or moved, the overlay remembers the base's full path.<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]], [[Samba|SMB]], NBD, HTTP, [[Very Secure FTP Daemon|FTP]], or [[Secure Shell|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 [[Samba|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 />
{{Note|QEMU's "built-in" SMB server is currently (as of qemu-1.0.1-1) broken because it does not specify the {{ic|state_directory}} option in the {{ic|smb.conf}} file it writes. This issue is fixed in upstream QEMU.}}<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] with an automatically generated configuration file 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 isn't 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 />
$ qemu [hd_image] -net nic -net user,smb=/path/to/shared/dir<br />
<br />
where {{ic|/path/to/shared/dir}} 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 />
=== 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 could occur, unless you had mounted the partitions read-only.}}<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 />
# mount -o loop,offset=32256 [hd_image] [tmp_dir]<br />
<br />
The {{ic|<nowiki>offset=32256</nowiki>}} 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 [hd_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 />
* Unload the loop [[Kernel modules|module]].<br />
# modprobe -r loop<br />
* Load the loop [[Kernel modules|module]] with the {{ic|max_part}} parameter set.<br />
# modprobe loop max_part=15<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|<nowiki>max_part=15</nowiki>}} every time, or you can put {{ic|<nowiki>loop.max_part=15</nowiki>}} 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 />
# losetup -f [os_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 />
# mount /dev/loop0p1 [tmp_dir]<br />
<br />
==== With kpartx ====<br />
<br />
'''kpartx''' from the {{Pkg|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a /dev/loop0<br />
<br />
=== Mounting qcow2 image ===<br />
You may mount 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 filesystem 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|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 />
<br />
{{Warning|You must not mount a filesystem on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.}}<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 filesystem and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[Kernels|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 filesystem as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
$ qemu -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 filesystem 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 />
==== 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 filesystem 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 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 filesystem on it you wish to make part of a QEMU disk image. First, you create some small file to hold the MBR:<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 />
# losetup -f /path/to/mbr<br />
<br />
Let's 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 />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hdaN<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/hdaN}} 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 />
# fdisk /dev/md0<br />
<br />
Press {{Keypress|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 {{Keypress|R}} to return to the main menu. <br />
<br />
Press {{Keypress|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hdaN}}. 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 -hdc /dev/md0 [...]<br />
<br />
You can of course safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hdaN}} partition contains the necessary tools.<br />
<br />
==Networking==<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. This only works with the TCP and UDP protocols, so ICMP, including {{ic|ping}}, will not work. <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, or attaching guests to virtual LANs 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 />
==== Basic idea ====<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 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 />
==== Bridge virtual machines to external network ====<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as 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 />
{{Warning|Beware that since your virtual machines will appear directly on the external network, this may expose them to attack. Depending on what resources your virtual machines have access to, you may need to take all the precautions you normally would take in securing a computer to secure your virtual machines.}}<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 .<br />
<br />
* Make sure that the following packages are installed:<br />
**{{Pkg|bridge-utils}} (provides {{ic|brctl}}, to manipulate bridges)<br />
**{{Pkg|uml_utilities}} (provides {{ic|tunctl}}, to manipulate taps)<br />
<br />
* Enable IPv4 forwarding:<br />
{{bc|<nowiki><br />
sysctl net.ipv4.ip_forward=1<br />
</nowiki>}}<br />
To make the change permanent, change {{ic|<nowiki>net.ipv4.ip_forward = 0</nowiki>}} to {{ic|<nowiki>net.ipv4.ip_forward = 1</nowiki>}} in {{ic|<nowiki>/etc/sysctl.conf</nowiki>}}.<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 netcfg]] for details.<br />
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 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 /sbin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/sbin/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 root:kvm 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /sbin/ip link set $1 down<br />
sudo /usr/sbin/brctl delif br0 $1<br />
sudo /sbin/ip link delete dev $1<br />
</nowiki>}}<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/sbin/ip,/sbin/modprobe,/usr/sbin/brctl,/usr/bin/tunctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
* Make sure the user(s) wishing to use this new functionality are in the {{ic|kvm}} group. Exit and log in again if necessary.<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=`whoami`<br />
IFACE=$(sudo tunctl -b -u $USERID)<br />
<br />
# This line creates a random mac address. The downside is the dhcp server will assign a different ip 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 an static mac address. The benefit is that the dhcp server will assign the same ip.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo tunctl -d $IFACE &> /dev/null<br />
</nowiki>}}<br />
Then to launch a VM, do something like this<br />
{{bc|<br />
$ run-qemu -hda myvm.img -m 512 -vga std<br />
}}<br />
<br />
* If you cannot get a DHCP address in the host, it might be because [[Iptables|iptables]] are up by default in the bridge. In that case (from http://www.linux-kvm.org/page/Networking ):<br />
# cd /proc/sys/net/bridge<br />
# ls<br />
bridge-nf-call-arptables bridge-nf-call-iptables<br />
bridge-nf-call-ip6tables bridge-nf-filter-vlan-tagged<br />
# for f in bridge-nf-*; do echo 0 > $f; done<br />
<br />
And if you still cannot get networking to work, see: [[Linux_Containers#Bridge_device_setup]].<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. eth0) is also connected to the bridge, then the virtual machines will be able to talk to each other and the physical host. 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 />
You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the 172.20.0.1/16 subnet with [[Dnsmasq]] as the DHCP server:<br />
<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.20.0.2,172.20.255.254<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[Iptables|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 />
==== 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 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 />
To solve this problem, the last 8 digits of the link-level address of the virtual NICs should be randomized, as in the script above, to make sure that each virtual machine has a unique link-level address.<br />
<br />
=== Networking with VDE2 ===<br />
==== What is VDE? ====<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. Your 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 />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[Official Repositories|official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module ([[Kernel modules|see here for more info]]):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group kvm<br />
<br />
This line creates the switch, creates tap0, "plugs" it, and allows the users of the group {{ic|kvm}} 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 -net nic -net vde -hda ...<br />
<br />
Configure your guest as you would do in a physical network. We gave them static addresses and let them access the WAN using IP forwarding and masquerading on our host:<br />
<br />
# echo "1" > /proc/sys/net/ipv4/ip_forward<br />
# iptables -t nat -A POSTROUTING -s 192.168.100.0/24 -o eth0 -j MASQUERADE<br />
<br />
==== Startup scripts ====<br />
<br />
===== systemd =====<br />
<br />
Example of script to put in {{ic|/usr/lib/systemd/scripts/}}<br />
<br />
{{hc|/usr/lib/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 />
<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 kvm<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 to put in {{ic|/usr/lib/systemd/system/}}<br />
<br />
{{hc|/usr/lib/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/lib/systemd/scripts/qemu-network-env start<br />
ExecStop=/usr/lib/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
After that you can enable the service if you want to start this at boot time<br />
# systemctl enable qemu-network-env<br />
<br />
If you want to start it (you can replace start by stop or restart)<br />
# systemctl start qemu-network-env<br />
<br />
====Alternative method====<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 kvm<br />
<br />
# slirpvde --dhcp --daemon<br />
<br />
Then to start the vm with a connection to the network of the host:<br />
<br />
$ kvm -net nic,macaddr=52:54:00:00:EE:03 -net vde whatever.qcow<br />
<br />
=== Improving networking performance ===<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde, since 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. To do this, add a {{ic|<nowiki>model=virtio</nowiki>}} flag to the {{ic|-net nic}} option:<br />
<br />
-net nic,model=virtio<br />
<br />
This will only work if the guest machine has a driver for virtio network devices. Linux does, and the required driver ('''virtio_net''') is included with Arch Linux, but there is no guarantee that virtio networking will work with arbitrary operating systems. There do exist [[#Virtio drivers for Windows|virtio drivers for Windows]], but you need to install them manually.<br />
<br />
== Graphics ==<br />
QEMU can use the following different graphic outputs: std, cirrus, vmware, qxl, xenfs and vnc.<br />
With the {{ic|vnc}} option you can run your guest standalone and connect to it via VNC. Other options are using {{ic|std}}, {{ic|vmware}}, {{ic|cirrus}}.<br />
<br />
===std===<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels.<br />
<br />
===vmware===<br />
Although it is a bit buggy, it performs better than std and cirrus. On the guest, install the VMware drivers. For Arch Linux guests:<br />
# pacman -S xf86-video-vmware xf86-input-vmmouse<br />
<br />
===none===<br />
<br />
If you do not want to see the graphical output from your virtual machine because you will be accessing it entirely through the network or serial port, you can run QEMU with the {{ic|-nographic}} option.<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization progrems 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 />
* virt-manager (part of [[libvirt]])<br />
* {{Pkg|qemu-launcher}}<br />
* qemulator (AUR)<br />
* {{Pkg|qtemu}}<br />
<br />
== Windows-specific notes ==<br />
=== Choosing a Windows version ===<br />
<br />
QEMU can run any version of Windows. However, 98, Me and XP will run at quite a low speed. You should choose either Windows 95 or Windows 2000. Surprisingly, 2000 seems to run faster than 98. The fastest one is 95, which can from time to time make you forget that you are running an emulator :)<br />
<br />
If you own both Win95 and Win98/WinME, then 98lite (from http://www.litepc.com) might be worth trying. It decouples Internet Explorer from operating system and replaces it with original Windows 95 Explorer. It also enables you to do a minimal Windows installation, without all the bloat you normally cannot disable. This might be the best option, because you get the smallest, fastest and most stable Windows this way.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
=== Windows 95 boot floppy ===<br />
<br />
If you are using the Windows 95 boot floppy, choosing SAMSUNG as the type of CD-ROM seems to work.<br />
<br />
=== Windows 2000 installation bug ===<br />
<br />
There are problems when installing Windows 2000. Windows setup will generate a lot of edb*.log files, one after the other containing nothing but blank spaces in {{ic|C:\WINNT\SECURITY}} which quickly fill the virtual hard disk. A workaround is to open a Windows command prompt as early as possible during setup (by pressing {{Keypress|Shift+F10}}) which will allow you to remove these log files as they appear by typing:<br />
del %windir%\security\*.log<br />
<br />
{{Note|According to the official QEMU website, "Windows 2000 has a bug which gives a disk full problem during its installation. When installing it, use the {{ic|-win2k-hack}} QEMU option to enable a specific workaround. After Windows 2000 is installed, you no longer need this option (this option slows down the IDE transfers)."}}<br />
<br />
=== Optimizing Windows 9X CPU usage ===<br />
<br />
Windows 9X uses an idle loop instead of the HLT (halt) instruction. Consequently, the emulator will consume all CPU resources when running Windows 9X guests &mdash; even if no work is being done. This only applies to DOS and DOS-based Windows versions (3.X, 95/98/ME) &mdash; NT-based and later Windows versions are not affected.<br />
<br />
To resolve this issue, install [http://www.benchtest.com/rain.html Rain], [http://www.benchtest.com/wfp.html Waterfall] or [http://www.benchtest.com/cpuidle.html CpuIdle] in the Windows 9X guest. (Rain might be preferred because it does only what is needed &mdash; replacing the idle loop with the HLT instruction &mdash; and nothing more.)<br />
<br />
See [https://forums.virtualbox.org/viewtopic.php?f=28&t=9918 Tutorial: Windows 95/98 guest OSes] for more information.<br />
<br />
===Remote Desktop Protocol===<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 />
$ qemu -nographic -net user,hostfwd=tcp::5555-:3389<br />
Then connect with either rdesktop or freerdp to the guest, for example:<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
=== Windows virtio drivers ===<br />
<br />
You can use [http://wiki.libvirt.org/page/Virtio virtio] devices with Windows if you install the [http://www.linux-kvm.org/page/WindowsGuestDrivers/Download_Drivers virtio guest drivers] for Windows.<br />
<br />
== General problems ==<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<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 />
{{bc|<br />
qemu -k [keymap] [disk_image]<br />
}}<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 KVM if possible : add {{ic|1=-machine type=pc,accel=kvm}} to the qemu start command you use.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128MiB 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 1024MiB of memory.<br />
* If the host machine has multiple CPUs, assign the guest more CPUs using the {{ic|-smp}} option.<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU. If you don't do this, it may be trying to emulate a more generic CPU.<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 -net nic,model=virtio -net tap,if=tap0,script=no -drive file=mydisk.raw,media=disk,if=virtio<br />
* [[#Tap networking with QEMU|Use TAP devices]] instead of user-mode networking.<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's filesystem. For example, you can mount an [[Ext4|ext4 filesystem]] with the option {{ic|<nowiki>barrier=0</nowiki>}}. You should read the documentation for any options that you change, since sometimes performance-enhancing options for filesystems come at the cost of data integrity.<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 />
==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 />
To run QEMU VMs on boot, you can use following rc-script and config.<br />
<br />
{| border="1"<br />
|+ Config file options<br />
|-<br />
| QEMU_MACHINES || List of VMs to start<br />
|-<br />
| qemu_${vm}_type || 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. qemu-system-arm images with qemu_my_arm_vm_type="system-arm". If not specified, {{ic|/usr/bin/qemu}} will be used.<br />
|-<br />
| qemu_${vm} || QEMU command line to start with. Will always be prepended with {{ic|-name ${vm} -pidfile /var/run/qemu/${vm}.pid -daemonize -nographic}}.<br />
|-<br />
| qemu_${vm}_haltcmd || Command to shutdown 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 />
| qemu_${vm}_haltcmd_wait || How much time to wait for safe VM shutdown. Default is 30 seconds. rc-script will kill qemu process after this timeout.<br />
|}<br />
<br />
Config file example:<br />
{{hc|/etc/conf.d/qemu.conf|<nowiki><br />
# VMs that should be started on boot<br />
# use the ! prefix to disable starting/stopping a VM<br />
QEMU_MACHINES=(vm1 vm2)<br />
<br />
# NOTE: following options will be prepended to qemu_${vm}<br />
# -name ${vm} -pidfile /var/run/qemu/${vm}.pid -daemonize -nographic<br />
<br />
qemu_vm1_type="system-x86_64"<br />
<br />
qemu_vm1="-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 />
qemu_vm1_haltcmd="echo 'system_powerdown' | nc.openbsd localhost 7100" # or netcat/ncat<br />
<br />
# You can use other ways to shutdown your VM correctly<br />
#qemu_vm1_haltcmd="ssh powermanager@vm1 sudo poweroff"<br />
<br />
# By default rc-script will wait 30 seconds before killing VM. Here you can change this timeout.<br />
#qemu_vm1_haltcmd_wait="30"<br />
<br />
qemu_vm2="-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 />
qemu_vm2_haltcmd="echo 'system_powerdown' | nc.openbsd localhost 7101"<br />
</nowiki>}}<br />
<br />
rc-script:<br />
{{hc|/etc/rc.d/qemu|<nowiki><br />
#!/bin/bash<br />
. /etc/rc.conf<br />
. /etc/rc.d/functions<br />
<br />
[ -f /etc/conf.d/qemu.conf ] && source /etc/conf.d/qemu.conf<br />
<br />
PIDDIR=/var/run/qemu<br />
QEMU_DEFAULT_FLAGS='-name ${vm} -pidfile ${PIDDIR}/${vm}.pid -daemonize -nographic'<br />
QEMU_HALTCMD_WAIT=30<br />
<br />
case "$1" in<br />
start)<br />
[ -d "${PIDDIR}" ] || mkdir -p "${PIDDIR}"<br />
for vm in "${QEMU_MACHINES[@]}"; do<br />
if [ "${vm}" = "${vm#!}" ]; then<br />
stat_busy "Starting QEMU VM: ${vm}"<br />
eval vm_cmdline="\$qemu_${vm}"<br />
eval vm_type="\$qemu_${vm}_type"<br />
<br />
if [ -n "${vm_type}" ]; then<br />
vm_cmd="/usr/bin/qemu-${vm_type}"<br />
else<br />
vm_cmd='/usr/bin/qemu'<br />
fi<br />
<br />
eval "qemu_flags=\"${QEMU_DEFAULT_FLAGS}\""<br />
<br />
${vm_cmd} ${qemu_flags} ${vm_cmdline} >/dev/null<br />
if [ $? -gt 0 ]; then<br />
stat_fail<br />
else<br />
stat_done<br />
fi<br />
fi<br />
done<br />
add_daemon qemu<br />
;;<br />
<br />
stop)<br />
for vm in "${QEMU_MACHINES[@]}"; do<br />
if [ "${vm}" = "${vm#!}" ]; then<br />
# check pidfile presence and permissions<br />
if [ ! -r "${PIDDIR}/${vm}.pid" ]; then<br />
continue<br />
fi<br />
<br />
stat_busy "Stopping QEMU VM: ${vm}"<br />
<br />
eval vm_haltcmd="\$qemu_${vm}_haltcmd"<br />
eval vm_haltcmd_wait="\$qemu_${vm}_haltcmd_wait"<br />
vm_haltcmd_wait=${vm_haltcmd_wait:-${QEMU_HALTCMD_WAIT}}<br />
vm_pid=$(cat ${PIDDIR}/${vm}.pid)<br />
<br />
# check process existence<br />
if ! kill -0 ${vm_pid} 2>/dev/null; then<br />
stat_done<br />
rm -f "${PIDDIR}/${vm}.pid"<br />
continue<br />
fi<br />
<br />
# Try to shutdown VM safely<br />
_vm_running='yes'<br />
if [ -n "${vm_haltcmd}" ]; then<br />
eval ${vm_haltcmd} >/dev/null<br />
<br />
_w=0<br />
while [ "${_w}" -lt "${vm_haltcmd_wait}" ]; do<br />
sleep 1<br />
if ! kill -0 ${vm_pid} 2>/dev/null; then<br />
# no such process<br />
_vm_running=''<br />
break<br />
fi<br />
_w=$((_w + 1))<br />
done<br />
<br />
else<br />
# No haltcmd - kill VM unsafely<br />
_vm_running='yes'<br />
fi<br />
<br />
if [ -n "${_vm_running}" ]; then<br />
# kill VM unsafely<br />
kill ${vm_pid} 2>/dev/null<br />
sleep 1<br />
fi<br />
<br />
# report status<br />
if kill -0 ${vm_pid} 2>/dev/null; then<br />
# VM is still alive<br />
#kill -9 ${vm_pid}<br />
stat_fail<br />
else<br />
stat_done<br />
fi<br />
<br />
# remove pidfile<br />
rm -f "${PIDDIR}/${vm}.pid"<br />
fi<br />
done<br />
rm_daemon qemu<br />
;;<br />
<br />
restart)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
<br />
*)<br />
echo "usage: $0 {start|stop|restart}"<br />
<br />
esac<br />
</nowiki>}}<br />
<br />
== Spice support ==<br />
<br />
The 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. [http://spice-space.org/ Spice project homepage]<br />
<br />
The official QEMU package is built without Spice support. To build your version with Spice enabled you need to have the [[Arch Build System]] on your system.<br />
<br />
Install {{aur|spice}} from the [[Arch User Repository|AUR]] first.<br />
<br />
Then update ABS on your system to the latest version and copy {{ic|/var/abs/extra/qemu}} to somewhere (here we use {{ic|~/temp/}} as an example) you like:<br />
$ sudo abs<br />
$ cp -r /var/abs/extra/qemu ~/temp<br />
<br />
Go to your copy of the package folder (here {{ic|~/temp/qemu}} and add {{ic|--enable-spice}} after {{ic|.configure}} in the build() function of the [[PKGBUILD]]:<br />
$ cd ~/temp/qemu<br />
$ sed -i "s/\.\/configure/& --enable-spice/g" PKGBUILD<br />
<br />
Then build and install the package:<br />
$ makepkg -i<br />
<br />
==See also==<br />
*[http://qemu.org Official QEMU website]<br />
*[http://www.linux-kvm.org Official KVM website]<br />
*[http://en.wikibooks.org/wiki/QEMU QEMU Wikibook]<br />
*''[http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU]'' by AlienBOB<br />
*''[http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army]'' by Falconindy</div>Blueriderhttps://wiki.archlinux.org/index.php?title=QEMU&diff=249866QEMU2013-03-08T03:59:16Z<p>Bluerider: /* KVM method (hardware virtualization) */</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Virtualization]]<br />
[[de:Qemu]]<br />
[[es:Qemu]]<br />
[[fr:Qemu]]<br />
[[zh-CN:QEMU]]<br />
From the [http://wiki.qemu.org/Main_Page QEMU about page],<br />
<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 own PC). By using dynamic translation, it achieves very good performance.<br />
<br />
When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU. QEMU supports virtualization when executing under the Xen hypervisor or using the KVM kernel module in Linux. When using KVM, QEMU can virtualize x86, server and embedded PowerPC, and S390 guests.<br />
<br />
== Installing QEMU ==<br />
<br />
Install {{Pkg|qemu}} from the [[Official Repositories|official repositories]]. {{ic|qemu-kvm}} has been fully merged with upstream {{pkg|qemu}} starting with version 1.3.0, so the {{ic|qemu-kvm}} package is gone.<br />
<br />
You can use KVM with the {{Pkg|qemu}} package, if supported by your processor and kernel, provided that you start QEMU with the {{ic|-enable-kvm}} argument.<br />
<br />
== Creating a hard disk image==<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 may simply contain the literal contents, byte for byte, of the hard disk. This is usually called ''raw'' format, and it provides the least I/O overhead, although the images may take up a large amount of space.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' that can save enormous amounts of space by only allocating 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.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. The following command creates a 4GB image named {{ic|myimage.qcow2}} in the qcow2 format:<br />
$ qemu-img create -f qcow2 myimage.qcow2 4G<br />
<br />
You may use {{ic|-f raw}} to create a raw disk instead, although you can also do so simply by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.<br />
<br />
== Preparing the installation media ==<br />
<br />
To install an operating system into your disk image, you need the installation media (e.g. CD-ROM, floppy, or ISO image) for the operating system.<br />
<br />
{{Tip|If you would like to run an Arch Linux virtual machine, you can install it using the [https://www.archlinux.org/download/ official installation media for Arch Linux]. It is also possible to set up an Arch Linux virtual machine without the installation media, provided that your host machine is running Arch Linux, although this is more difficult; it is detailed [[Creating Arch Linux disk image#Install Arch Linux in a disk image without the installation media|here]].}}<br />
<br />
The installation media should not be mounted because QEMU accesses the media directly. Also, if using physical media (e.g. CD-ROM or floppy), 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:<br />
# dd if=/dev/cdrom of=mycdimg.iso<br />
<br />
Do the same for floppy drives:<br />
# dd if=/dev/fd of=myfloppy.img<br />
<br />
== Installing the operating system==<br />
<br />
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 />
This is the first time you will need to start the emulator. By default, QEMU will show the virtual machine's video output in a window. <br />
One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it press {{Keypress|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 />
=== Standard method (software emulation)===<br />
<br />
On i386 systems, to install from a bootable ISO file as CD-ROM, run QEMU with:<br />
$ qemu -cdrom <iso_image> -boot d <qemu_image><br />
<br />
On x86_64 systems:<br />
$ qemu-system-x86_64 -cdrom <iso_image> -boot d <qemu_image><br />
<br />
See the parameters in {{ic|qemu --help}} for 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, for example on i386:<br />
<br />
$ qemu <qemu_image><br />
<br />
{{Tip|By default only 128MB of memory is assigned to the machine, the amount of memory can be adjusted with the -m switch, for example {{ic|-m 512}}.}}<br />
<br />
=== KVM method (hardware virtualization) ===<br />
<br />
<br />
KVM, short for Kernel-based Virtual Machine, is a full virtualization solution for Linux on x86 hardware containing virtualization extensions (Intel VT or AMD-V). It relies on the kernel modules {{ic|kvm}} and either {{ic|kvm-intel}} or {{ic|kvm-amd}}. KVM interfaces via {{ic|/dev/kvm}}, which requires users to be part of the {{ic|kvm}} group. <br />
<br />
For 32 bit systems : <br />
The command to use with the standard {{Pkg|qemu}} package is:<br />
$ qemu -enable-kvm<br />
<br />
For 64 bit systems:<br />
The command to use with the standard {{Pkg|qemu}} package is:<br />
$ qemu-system-x86_64 --enable-kvm<br />
<br />
There is a dedicated [[KVM]] wiki page with more detailed information and instructions.<br />
<br />
{{Note|If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{Keypress|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 {{Keypress|Ctrl-Alt-1}} to go back to the virtual machine.}}<br />
<br />
== Overlay images ==<br />
<br />
A good idea is to use overlay images. This way you can a create hard disk image once and tell QEMU to store changes in an external file.<br />
This makes it easy to revert the virtual machine's disk to a previous state.<br />
<br />
To create an overlay image, type:<br />
$<nowiki> qemu-img create -b [[base_image]] -f qcow2 [[overlay_image]]</nowiki><br />
<br />
After that you can run qemu with:<br />
$ qemu [overlay_image]<br />
<br />
or if you are on a x86_64 system:<br />
$ qemu-system-x86_64 [overlay_image]<br />
<br />
and the original image will be left untouched. One hitch, the base image cannot be renamed or moved, the overlay remembers the base's full path.<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]], [[Samba|SMB]], NBD, HTTP, [[Very Secure FTP Daemon|FTP]], or [[Secure Shell|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 [[Samba|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 />
{{Note|QEMU's "built-in" SMB server is currently (as of qemu-1.0.1-1) broken because it does not specify the {{ic|state_directory}} option in the {{ic|smb.conf}} file it writes. This issue is fixed in upstream QEMU.}}<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] with an automatically generated configuration file 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 isn't 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 />
$ qemu [hd_image] -net nic -net user,smb=/path/to/shared/dir<br />
<br />
where {{ic|/path/to/shared/dir}} 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 />
=== 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 could occur, unless you had mounted the partitions read-only.}}<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 />
# mount -o loop,offset=32256 [hd_image] [tmp_dir]<br />
<br />
The {{ic|<nowiki>offset=32256</nowiki>}} 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 [hd_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 />
* Unload the loop [[Kernel modules|module]].<br />
# modprobe -r loop<br />
* Load the loop [[Kernel modules|module]] with the {{ic|max_part}} parameter set.<br />
# modprobe loop max_part=15<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|<nowiki>max_part=15</nowiki>}} every time, or you can put {{ic|<nowiki>loop.max_part=15</nowiki>}} 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 />
# losetup -f [os_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 />
# mount /dev/loop0p1 [tmp_dir]<br />
<br />
==== With kpartx ====<br />
<br />
'''kpartx''' from the {{Pkg|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a /dev/loop0<br />
<br />
=== Mounting qcow2 image ===<br />
You may mount 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 filesystem 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|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 />
<br />
{{Warning|You must not mount a filesystem on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.}}<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 filesystem and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[Kernels|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 filesystem as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
$ qemu -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 filesystem 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 />
==== 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 filesystem 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 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 filesystem on it you wish to make part of a QEMU disk image. First, you create some small file to hold the MBR:<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 />
# losetup -f /path/to/mbr<br />
<br />
Let's 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 />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hdaN<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/hdaN}} 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 />
# fdisk /dev/md0<br />
<br />
Press {{Keypress|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 {{Keypress|R}} to return to the main menu. <br />
<br />
Press {{Keypress|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hdaN}}. 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 -hdc /dev/md0 [...]<br />
<br />
You can of course safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hdaN}} partition contains the necessary tools.<br />
<br />
==Networking==<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. This only works with the TCP and UDP protocols, so ICMP, including {{ic|ping}}, will not work. <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, or attaching guests to virtual LANs 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 />
==== Basic idea ====<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 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 />
==== Bridge virtual machines to external network ====<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as 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 />
{{Warning|Beware that since your virtual machines will appear directly on the external network, this may expose them to attack. Depending on what resources your virtual machines have access to, you may need to take all the precautions you normally would take in securing a computer to secure your virtual machines.}}<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 .<br />
<br />
* Make sure that the following packages are installed:<br />
**{{Pkg|bridge-utils}} (provides {{ic|brctl}}, to manipulate bridges)<br />
**{{Pkg|uml_utilities}} (provides {{ic|tunctl}}, to manipulate taps)<br />
<br />
* Enable IPv4 forwarding:<br />
{{bc|<nowiki><br />
sysctl net.ipv4.ip_forward=1<br />
</nowiki>}}<br />
To make the change permanent, change {{ic|<nowiki>net.ipv4.ip_forward = 0</nowiki>}} to {{ic|<nowiki>net.ipv4.ip_forward = 1</nowiki>}} in {{ic|<nowiki>/etc/sysctl.conf</nowiki>}}.<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 netcfg]] for details.<br />
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 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 /sbin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/sbin/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 root:kvm 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /sbin/ip link set $1 down<br />
sudo /usr/sbin/brctl delif br0 $1<br />
sudo /sbin/ip link delete dev $1<br />
</nowiki>}}<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/sbin/ip,/sbin/modprobe,/usr/sbin/brctl,/usr/bin/tunctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
* Make sure the user(s) wishing to use this new functionality are in the {{ic|kvm}} group. Exit and log in again if necessary.<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=`whoami`<br />
IFACE=$(sudo tunctl -b -u $USERID)<br />
<br />
# This line creates a random mac address. The downside is the dhcp server will assign a different ip 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 an static mac address. The benefit is that the dhcp server will assign the same ip.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo tunctl -d $IFACE &> /dev/null<br />
</nowiki>}}<br />
Then to launch a VM, do something like this<br />
{{bc|<br />
$ run-qemu -hda myvm.img -m 512 -vga std<br />
}}<br />
<br />
* If you cannot get a DHCP address in the host, it might be because [[Iptables|iptables]] are up by default in the bridge. In that case (from http://www.linux-kvm.org/page/Networking ):<br />
# cd /proc/sys/net/bridge<br />
# ls<br />
bridge-nf-call-arptables bridge-nf-call-iptables<br />
bridge-nf-call-ip6tables bridge-nf-filter-vlan-tagged<br />
# for f in bridge-nf-*; do echo 0 > $f; done<br />
<br />
And if you still cannot get networking to work, see: [[Linux_Containers#Bridge_device_setup]].<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. eth0) is also connected to the bridge, then the virtual machines will be able to talk to each other and the physical host. 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 />
You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the 172.20.0.1/16 subnet with [[Dnsmasq]] as the DHCP server:<br />
<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.20.0.2,172.20.255.254<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[Iptables|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 />
==== 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 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 />
To solve this problem, the last 8 digits of the link-level address of the virtual NICs should be randomized, as in the script above, to make sure that each virtual machine has a unique link-level address.<br />
<br />
=== Networking with VDE2 ===<br />
==== What is VDE? ====<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. Your 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 />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[Official Repositories|official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module ([[Kernel modules|see here for more info]]):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group kvm<br />
<br />
This line creates the switch, creates tap0, "plugs" it, and allows the users of the group {{ic|kvm}} 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 -net nic -net vde -hda ...<br />
<br />
Configure your guest as you would do in a physical network. We gave them static addresses and let them access the WAN using IP forwarding and masquerading on our host:<br />
<br />
# echo "1" > /proc/sys/net/ipv4/ip_forward<br />
# iptables -t nat -A POSTROUTING -s 192.168.100.0/24 -o eth0 -j MASQUERADE<br />
<br />
==== Startup scripts ====<br />
<br />
===== systemd =====<br />
<br />
Example of script to put in {{ic|/usr/lib/systemd/scripts/}}<br />
<br />
{{hc|/usr/lib/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 />
<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 kvm<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 to put in {{ic|/usr/lib/systemd/system/}}<br />
<br />
{{hc|/usr/lib/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/lib/systemd/scripts/qemu-network-env start<br />
ExecStop=/usr/lib/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
After that you can enable the service if you want to start this at boot time<br />
# systemctl enable qemu-network-env<br />
<br />
If you want to start it (you can replace start by stop or restart)<br />
# systemctl start qemu-network-env<br />
<br />
====Alternative method====<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 kvm<br />
<br />
# slirpvde --dhcp --daemon<br />
<br />
Then to start the vm with a connection to the network of the host:<br />
<br />
$ kvm -net nic,macaddr=52:54:00:00:EE:03 -net vde whatever.qcow<br />
<br />
=== Improving networking performance ===<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde, since 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. To do this, add a {{ic|<nowiki>model=virtio</nowiki>}} flag to the {{ic|-net nic}} option:<br />
<br />
-net nic,model=virtio<br />
<br />
This will only work if the guest machine has a driver for virtio network devices. Linux does, and the required driver ('''virtio_net''') is included with Arch Linux, but there is no guarantee that virtio networking will work with arbitrary operating systems. There do exist [[#Virtio drivers for Windows|virtio drivers for Windows]], but you need to install them manually.<br />
<br />
== Graphics ==<br />
QEMU can use the following different graphic outputs: std, cirrus, vmware, qxl, xenfs and vnc.<br />
With the {{ic|vnc}} option you can run your guest standalone and connect to it via VNC. Other options are using {{ic|std}}, {{ic|vmware}}, {{ic|cirrus}}.<br />
<br />
===std===<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels.<br />
<br />
===vmware===<br />
Although it is a bit buggy, it performs better than std and cirrus. On the guest, install the VMware drivers. For Arch Linux guests:<br />
# pacman -S xf86-video-vmware xf86-input-vmmouse<br />
<br />
===none===<br />
<br />
If you do not want to see the graphical output from your virtual machine because you will be accessing it entirely through the network or serial port, you can run QEMU with the {{ic|-nographic}} option.<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization progrems 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 />
* virt-manager (part of [[libvirt]])<br />
* {{Pkg|qemu-launcher}}<br />
* qemulator (AUR)<br />
* {{Pkg|qtemu}}<br />
<br />
== Windows-specific notes ==<br />
=== Choosing a Windows version ===<br />
<br />
QEMU can run any version of Windows. However, 98, Me and XP will run at quite a low speed. You should choose either Windows 95 or Windows 2000. Surprisingly, 2000 seems to run faster than 98. The fastest one is 95, which can from time to time make you forget that you are running an emulator :)<br />
<br />
If you own both Win95 and Win98/WinME, then 98lite (from http://www.litepc.com) might be worth trying. It decouples Internet Explorer from operating system and replaces it with original Windows 95 Explorer. It also enables you to do a minimal Windows installation, without all the bloat you normally cannot disable. This might be the best option, because you get the smallest, fastest and most stable Windows this way.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
=== Windows 95 boot floppy ===<br />
<br />
If you are using the Windows 95 boot floppy, choosing SAMSUNG as the type of CD-ROM seems to work.<br />
<br />
=== Windows 2000 installation bug ===<br />
<br />
There are problems when installing Windows 2000. Windows setup will generate a lot of edb*.log files, one after the other containing nothing but blank spaces in {{ic|C:\WINNT\SECURITY}} which quickly fill the virtual hard disk. A workaround is to open a Windows command prompt as early as possible during setup (by pressing {{Keypress|Shift+F10}}) which will allow you to remove these log files as they appear by typing:<br />
del %windir%\security\*.log<br />
<br />
{{Note|According to the official QEMU website, "Windows 2000 has a bug which gives a disk full problem during its installation. When installing it, use the {{ic|-win2k-hack}} QEMU option to enable a specific workaround. After Windows 2000 is installed, you no longer need this option (this option slows down the IDE transfers)."}}<br />
<br />
=== Optimizing Windows 9X CPU usage ===<br />
<br />
Windows 9X uses an idle loop instead of the HLT (halt) instruction. Consequently, the emulator will consume all CPU resources when running Windows 9X guests &mdash; even if no work is being done. This only applies to DOS and DOS-based Windows versions (3.X, 95/98/ME) &mdash; NT-based and later Windows versions are not affected.<br />
<br />
To resolve this issue, install [http://www.benchtest.com/rain.html Rain], [http://www.benchtest.com/wfp.html Waterfall] or [http://www.benchtest.com/cpuidle.html CpuIdle] in the Windows 9X guest. (Rain might be preferred because it does only what is needed &mdash; replacing the idle loop with the HLT instruction &mdash; and nothing more.)<br />
<br />
See [https://forums.virtualbox.org/viewtopic.php?f=28&t=9918 Tutorial: Windows 95/98 guest OSes] for more information.<br />
<br />
===Remote Desktop Protocol===<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 />
$ qemu -nographic -net user,hostfwd=tcp::5555-:3389<br />
Then connect with either rdesktop or freerdp to the guest, for example:<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
=== Windows virtio drivers ===<br />
<br />
You can use [http://wiki.libvirt.org/page/Virtio virtio] devices with Windows if you install the [http://www.linux-kvm.org/page/WindowsGuestDrivers/Download_Drivers virtio guest drivers] for Windows.<br />
<br />
== General problems ==<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<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 />
{{bc|<br />
qemu -k [keymap] [disk_image]<br />
}}<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 KVM if possible : add {{ic|1=-machine type=pc,accel=kvm}} to the qemu start command you use.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128MiB 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 1024MiB of memory.<br />
* If the host machine has multiple CPUs, assign the guest more CPUs using the {{ic|-smp}} option.<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU. If you don't do this, it may be trying to emulate a more generic CPU.<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 -net nic,model=virtio -net tap,if=tap0,script=no -drive file=mydisk.raw,media=disk,if=virtio<br />
* [[#Tap networking with QEMU|Use TAP devices]] instead of user-mode networking.<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's filesystem. For example, you can mount an [[Ext4|ext4 filesystem]] with the option {{ic|<nowiki>barrier=0</nowiki>}}. You should read the documentation for any options that you change, since sometimes performance-enhancing options for filesystems come at the cost of data integrity.<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 />
==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 />
To run QEMU VMs on boot, you can use following rc-script and config.<br />
<br />
{| border="1"<br />
|+ Config file options<br />
|-<br />
| QEMU_MACHINES || List of VMs to start<br />
|-<br />
| qemu_${vm}_type || 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. qemu-system-arm images with qemu_my_arm_vm_type="system-arm". If not specified, {{ic|/usr/bin/qemu}} will be used.<br />
|-<br />
| qemu_${vm} || QEMU command line to start with. Will always be prepended with {{ic|-name ${vm} -pidfile /var/run/qemu/${vm}.pid -daemonize -nographic}}.<br />
|-<br />
| qemu_${vm}_haltcmd || Command to shutdown 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 />
| qemu_${vm}_haltcmd_wait || How much time to wait for safe VM shutdown. Default is 30 seconds. rc-script will kill qemu process after this timeout.<br />
|}<br />
<br />
Config file example:<br />
{{hc|/etc/conf.d/qemu.conf|<nowiki><br />
# VMs that should be started on boot<br />
# use the ! prefix to disable starting/stopping a VM<br />
QEMU_MACHINES=(vm1 vm2)<br />
<br />
# NOTE: following options will be prepended to qemu_${vm}<br />
# -name ${vm} -pidfile /var/run/qemu/${vm}.pid -daemonize -nographic<br />
<br />
qemu_vm1_type="system-x86_64"<br />
<br />
qemu_vm1="-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 />
qemu_vm1_haltcmd="echo 'system_powerdown' | nc.openbsd localhost 7100" # or netcat/ncat<br />
<br />
# You can use other ways to shutdown your VM correctly<br />
#qemu_vm1_haltcmd="ssh powermanager@vm1 sudo poweroff"<br />
<br />
# By default rc-script will wait 30 seconds before killing VM. Here you can change this timeout.<br />
#qemu_vm1_haltcmd_wait="30"<br />
<br />
qemu_vm2="-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 />
qemu_vm2_haltcmd="echo 'system_powerdown' | nc.openbsd localhost 7101"<br />
</nowiki>}}<br />
<br />
rc-script:<br />
{{hc|/etc/rc.d/qemu|<nowiki><br />
#!/bin/bash<br />
. /etc/rc.conf<br />
. /etc/rc.d/functions<br />
<br />
[ -f /etc/conf.d/qemu.conf ] && source /etc/conf.d/qemu.conf<br />
<br />
PIDDIR=/var/run/qemu<br />
QEMU_DEFAULT_FLAGS='-name ${vm} -pidfile ${PIDDIR}/${vm}.pid -daemonize -nographic'<br />
QEMU_HALTCMD_WAIT=30<br />
<br />
case "$1" in<br />
start)<br />
[ -d "${PIDDIR}" ] || mkdir -p "${PIDDIR}"<br />
for vm in "${QEMU_MACHINES[@]}"; do<br />
if [ "${vm}" = "${vm#!}" ]; then<br />
stat_busy "Starting QEMU VM: ${vm}"<br />
eval vm_cmdline="\$qemu_${vm}"<br />
eval vm_type="\$qemu_${vm}_type"<br />
<br />
if [ -n "${vm_type}" ]; then<br />
vm_cmd="/usr/bin/qemu-${vm_type}"<br />
else<br />
vm_cmd='/usr/bin/qemu'<br />
fi<br />
<br />
eval "qemu_flags=\"${QEMU_DEFAULT_FLAGS}\""<br />
<br />
${vm_cmd} ${qemu_flags} ${vm_cmdline} >/dev/null<br />
if [ $? -gt 0 ]; then<br />
stat_fail<br />
else<br />
stat_done<br />
fi<br />
fi<br />
done<br />
add_daemon qemu<br />
;;<br />
<br />
stop)<br />
for vm in "${QEMU_MACHINES[@]}"; do<br />
if [ "${vm}" = "${vm#!}" ]; then<br />
# check pidfile presence and permissions<br />
if [ ! -r "${PIDDIR}/${vm}.pid" ]; then<br />
continue<br />
fi<br />
<br />
stat_busy "Stopping QEMU VM: ${vm}"<br />
<br />
eval vm_haltcmd="\$qemu_${vm}_haltcmd"<br />
eval vm_haltcmd_wait="\$qemu_${vm}_haltcmd_wait"<br />
vm_haltcmd_wait=${vm_haltcmd_wait:-${QEMU_HALTCMD_WAIT}}<br />
vm_pid=$(cat ${PIDDIR}/${vm}.pid)<br />
<br />
# check process existence<br />
if ! kill -0 ${vm_pid} 2>/dev/null; then<br />
stat_done<br />
rm -f "${PIDDIR}/${vm}.pid"<br />
continue<br />
fi<br />
<br />
# Try to shutdown VM safely<br />
_vm_running='yes'<br />
if [ -n "${vm_haltcmd}" ]; then<br />
eval ${vm_haltcmd} >/dev/null<br />
<br />
_w=0<br />
while [ "${_w}" -lt "${vm_haltcmd_wait}" ]; do<br />
sleep 1<br />
if ! kill -0 ${vm_pid} 2>/dev/null; then<br />
# no such process<br />
_vm_running=''<br />
break<br />
fi<br />
_w=$((_w + 1))<br />
done<br />
<br />
else<br />
# No haltcmd - kill VM unsafely<br />
_vm_running='yes'<br />
fi<br />
<br />
if [ -n "${_vm_running}" ]; then<br />
# kill VM unsafely<br />
kill ${vm_pid} 2>/dev/null<br />
sleep 1<br />
fi<br />
<br />
# report status<br />
if kill -0 ${vm_pid} 2>/dev/null; then<br />
# VM is still alive<br />
#kill -9 ${vm_pid}<br />
stat_fail<br />
else<br />
stat_done<br />
fi<br />
<br />
# remove pidfile<br />
rm -f "${PIDDIR}/${vm}.pid"<br />
fi<br />
done<br />
rm_daemon qemu<br />
;;<br />
<br />
restart)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
<br />
*)<br />
echo "usage: $0 {start|stop|restart}"<br />
<br />
esac<br />
</nowiki>}}<br />
<br />
== Spice support ==<br />
<br />
The 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. [http://spice-space.org/ Spice project homepage]<br />
<br />
The official QEMU package is built without Spice support. To build your version with Spice enabled you need to have the [[Arch Build System]] on your system.<br />
<br />
Install {{aur|spice}} from the [[Arch User Repository|AUR]] first.<br />
<br />
Then update ABS on your system to the latest version and copy {{ic|/var/abs/extra/qemu}} to somewhere (here we use {{ic|~/temp/}} as an example) you like:<br />
$ sudo abs<br />
$ cp -r /var/abs/extra/qemu ~/temp<br />
<br />
Go to your copy of the package folder (here {{ic|~/temp/qemu}} and add {{ic|--enable-spice}} after {{ic|.configure}} in the build() function of the [[PKGBUILD]]:<br />
$ cd ~/temp/qemu<br />
$ sed -i "s/\.\/configure/& --enable-spice/g" PKGBUILD<br />
<br />
Then build and install the package:<br />
$ makepkg -i<br />
<br />
==See also==<br />
*[http://qemu.org Official QEMU website]<br />
*[http://www.linux-kvm.org Official KVM website]<br />
*[http://en.wikibooks.org/wiki/QEMU QEMU Wikibook]<br />
*''[http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU]'' by AlienBOB<br />
*''[http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army]'' by Falconindy</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Fsck&diff=249519Fsck2013-03-05T23:44:10Z<p>Bluerider: /* Repair damaged blocks interactively */</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:File systems]]<br />
[[ru:Fsck]]<br />
{{Article summary start}}<br />
{{Article summary text|Information on how to use fsck.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Ext4}}<br />
{{Article summary wiki|Btrfs}}<br />
{{Article summary wiki|fstab}}<br />
{{Article summary end}}<br />
<br />
[[Wikipedia:Fsck|fsck]] stands for ''"file system check"'' and it is used to check and optionally repair one or more Linux file systems. Normally, the fsck program will try to handle filesystems on different physical disk drives in parallel to reduce the total amount of time needed to check all of the filesystems (see: {{ic|man fsck}}).<br />
<br />
The [[Arch Boot Process|Arch Linux boot process]] conveniently takes care of the fsck procedure for you and will check all relevant partitions on your drive(s) automatically on every boot. Hence, there is usually no need to resort to the command-line unless necessary.<br />
<br />
== Checking ==<br />
<br />
The filesystem can be checked by creating a {{ic|forcefsck}} file on the partition you wish to check later. For example, for the root partition it would be:<br />
<br />
# touch /forcefsck<br />
<br />
When you're ready, reboot and fsck will do the rest. And don't worry, this file will be removed automatically when the process is finished.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Cancelling the process ===<br />
{{Accuracy|Doesn't work. Tried adding {{ic|1=FILES="/etc/e2fsck.conf"}} to [[mkinitcpio.conf]] and rebuilding the initramfs images, but still nothing. ''--DSpider, 12 January 2013''}}<br />
<br />
To cancel a running fsck check during boot time, create the following file:<br />
<br />
{{hc|/etc/e2fsck.conf|2=<br />
[options]<br />
allow_cancellation = true<br />
}}<br />
<br />
Now you should be able to cancel it with {{Keypress|Ctrl+C}}.<br />
<br />
=== Attempt to repair damaged blocks ===<br />
<br />
To automatically repair damaged portions, run:<br />
<br />
{{Warning|This will not ask if you want to repair it, as the answer is '''Yes''' when you run it.}}<br />
<br />
# fsck -a<br />
<br />
=== Repair damaged blocks interactively ===<br />
{{Tip|This is useful for when file on the boot partition have changed, and the journal failed to properly update. In this case, unmount the boot partition, and run the following code:}}<br />
To repair damaged portions, run :<br />
{{bc|<nowiki><br />
# fsck -r <drive></nowiki><br />
}}<br />
<br />
=== Changing the check frequency ===<br />
<br />
By default, fsck checks a filesystem every 30 boots (counted individually for each partition). To change the frequency of checking, run:<br />
<br />
# tune2fs -c 20 /dev/sda1<br />
<br />
In this example, {{ic|20}} is the number of boots between two checks.<br />
<br />
Note that {{ic|1}} would make it scan at every boot, while {{ic|0}} would stop scanning altogether.<br />
<br />
{{Tip|If you wish to see the frequency number and the current mount count for a specific partition, use:<br />
# dumpe2fs -h /dev/sda1 <nowiki>|</nowiki> grep -i 'mount count'<br />
}}<br />
<br />
=== fstab options ===<br />
<br />
[[fstab]] is a system configuration file and is used to tell the Linux kernel which partitions (file systems) to mount and where on the file system tree.<br />
<br />
A typical {{ic|/etc/fstab}} entry may look like this:<br />
<br />
/dev/sda1 / ext4 defaults 0 '''1'''<br />
/dev/sda2 /other ext4 defaults 0 '''2'''<br />
/dev/sda3 /win ntfs-3g defaults 0 '''0'''<br />
<br />
The 6th column (in bold) is the fsck option.<br />
<br />
* 0 = Do not check.<br />
* 1 = First file system (partition) to check; {{ic|/}} (root partition) should be set to 1.<br />
* 2 = All other filesystems to be checked.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Can't run fsck on a separate /usr partition ===<br />
<br />
# Make sure you have the required [https://wiki.archlinux.org/index.php/Mkinitcpio#.2Fusr_as_a_separate_partition hooks] in {{ic|/etc/mkinitcpio.conf}} and that you remembered to re-generate your initramfs image after editing this file. <br />
# Make sure that the bootloader has {{ic|ro}} on the "APPEND" line in {{ic|/boot/syslinux/syslinux.cfg}} (for Syslinux). GRUB doesn't need one; it is added automatically when you generate a .cfg. For an explanation as to why you ''need'' "ro", see [https://bbs.archlinux.org/viewtopic.php?pid=1114554#p1114554 this] post. <br />
# Check your [[fstab]]! Only the root partition needs "1" at the end, everything else should have either "2" or "0". Carefully inspect it for other typos, as well.<br />
<br />
=== ext2fs : no external journal ===<br />
<br />
There are times (due to power failure) in which an ext(3/4) file system can corrupt beyond normal repair. Normally, there will be a prompt from fsck indicating that it cannot find an external journal. In this case, run the following commands:<br />
<br />
{{bc|<nowiki><br />
# umount <directory>; ## unmount the partition based on its directory<br />
# tune2fs -j /dev/<partition>; ## write a new journal to the partition<br />
# fsck -p /dev/<partition>; ## run an fsck to repair the partition<br />
</nowiki><br />
}}</div>Blueriderhttps://wiki.archlinux.org/index.php?title=Fsck&diff=249518Fsck2013-03-05T23:43:43Z<p>Bluerider: /* Attempt to repair damaged blocks */</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:File systems]]<br />
[[ru:Fsck]]<br />
{{Article summary start}}<br />
{{Article summary text|Information on how to use fsck.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Ext4}}<br />
{{Article summary wiki|Btrfs}}<br />
{{Article summary wiki|fstab}}<br />
{{Article summary end}}<br />
<br />
[[Wikipedia:Fsck|fsck]] stands for ''"file system check"'' and it is used to check and optionally repair one or more Linux file systems. Normally, the fsck program will try to handle filesystems on different physical disk drives in parallel to reduce the total amount of time needed to check all of the filesystems (see: {{ic|man fsck}}).<br />
<br />
The [[Arch Boot Process|Arch Linux boot process]] conveniently takes care of the fsck procedure for you and will check all relevant partitions on your drive(s) automatically on every boot. Hence, there is usually no need to resort to the command-line unless necessary.<br />
<br />
== Checking ==<br />
<br />
The filesystem can be checked by creating a {{ic|forcefsck}} file on the partition you wish to check later. For example, for the root partition it would be:<br />
<br />
# touch /forcefsck<br />
<br />
When you're ready, reboot and fsck will do the rest. And don't worry, this file will be removed automatically when the process is finished.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Cancelling the process ===<br />
{{Accuracy|Doesn't work. Tried adding {{ic|1=FILES="/etc/e2fsck.conf"}} to [[mkinitcpio.conf]] and rebuilding the initramfs images, but still nothing. ''--DSpider, 12 January 2013''}}<br />
<br />
To cancel a running fsck check during boot time, create the following file:<br />
<br />
{{hc|/etc/e2fsck.conf|2=<br />
[options]<br />
allow_cancellation = true<br />
}}<br />
<br />
Now you should be able to cancel it with {{Keypress|Ctrl+C}}.<br />
<br />
=== Attempt to repair damaged blocks ===<br />
<br />
To automatically repair damaged portions, run:<br />
<br />
{{Warning|This will not ask if you want to repair it, as the answer is '''Yes''' when you run it.}}<br />
<br />
# fsck -a<br />
<br />
=== Repair damaged blocks interactively ===<br />
{{Tip|This is useful for when file on the boot partition have changed, and the journal failed to properly update. In this case, unmount the boot partition, and run the following code:}}<br />
To repair damaged portions, run :<br />
{{bc|<nowiki><br />
# fsck -r <drive><br />
</nowiki><br />
}}<br />
<br />
=== Changing the check frequency ===<br />
<br />
By default, fsck checks a filesystem every 30 boots (counted individually for each partition). To change the frequency of checking, run:<br />
<br />
# tune2fs -c 20 /dev/sda1<br />
<br />
In this example, {{ic|20}} is the number of boots between two checks.<br />
<br />
Note that {{ic|1}} would make it scan at every boot, while {{ic|0}} would stop scanning altogether.<br />
<br />
{{Tip|If you wish to see the frequency number and the current mount count for a specific partition, use:<br />
# dumpe2fs -h /dev/sda1 <nowiki>|</nowiki> grep -i 'mount count'<br />
}}<br />
<br />
=== fstab options ===<br />
<br />
[[fstab]] is a system configuration file and is used to tell the Linux kernel which partitions (file systems) to mount and where on the file system tree.<br />
<br />
A typical {{ic|/etc/fstab}} entry may look like this:<br />
<br />
/dev/sda1 / ext4 defaults 0 '''1'''<br />
/dev/sda2 /other ext4 defaults 0 '''2'''<br />
/dev/sda3 /win ntfs-3g defaults 0 '''0'''<br />
<br />
The 6th column (in bold) is the fsck option.<br />
<br />
* 0 = Do not check.<br />
* 1 = First file system (partition) to check; {{ic|/}} (root partition) should be set to 1.<br />
* 2 = All other filesystems to be checked.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Can't run fsck on a separate /usr partition ===<br />
<br />
# Make sure you have the required [https://wiki.archlinux.org/index.php/Mkinitcpio#.2Fusr_as_a_separate_partition hooks] in {{ic|/etc/mkinitcpio.conf}} and that you remembered to re-generate your initramfs image after editing this file. <br />
# Make sure that the bootloader has {{ic|ro}} on the "APPEND" line in {{ic|/boot/syslinux/syslinux.cfg}} (for Syslinux). GRUB doesn't need one; it is added automatically when you generate a .cfg. For an explanation as to why you ''need'' "ro", see [https://bbs.archlinux.org/viewtopic.php?pid=1114554#p1114554 this] post. <br />
# Check your [[fstab]]! Only the root partition needs "1" at the end, everything else should have either "2" or "0". Carefully inspect it for other typos, as well.<br />
<br />
=== ext2fs : no external journal ===<br />
<br />
There are times (due to power failure) in which an ext(3/4) file system can corrupt beyond normal repair. Normally, there will be a prompt from fsck indicating that it cannot find an external journal. In this case, run the following commands:<br />
<br />
{{bc|<nowiki><br />
# umount <directory>; ## unmount the partition based on its directory<br />
# tune2fs -j /dev/<partition>; ## write a new journal to the partition<br />
# fsck -p /dev/<partition>; ## run an fsck to repair the partition<br />
</nowiki><br />
}}</div>Bluerider