https://wiki.archlinux.org/api.php?action=feedcontributions&user=Bricewge&feedformat=atomArchWiki - User contributions [en]2024-03-28T13:33:30ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Cursor_themes&diff=529067Cursor themes2018-07-07T15:23:44Z<p>Bricewge: /* Change X shaped default cursor */ replace dead link</p>
<hr />
<div>[[Category:X server]]<br />
[[es:Cursor themes]]<br />
[[it:Cursor themes]]<br />
[[ja:カーソルテーマ]]<br />
[[pt:Cursor themes]]<br />
[[ru:Cursor themes]]<br />
[[zh-hans:Cursor themes]]<br />
<br />
The display server is accompanied by a ''cursor theme'' that helps various aspects of GUI navigation and manipulation. The display server includes a cursor theme, however, other cursor themes can be installed and selected.<br />
<br />
== Installation ==<br />
<br />
Installation can be done with a package, or downloaded and extracted to an appropriate directory.<br />
<br />
=== Packages ===<br />
<br />
Cursors themes are available in the:<br />
<br />
* [[Official repositories]] — [https://www.archlinux.org/packages/?sort=&q=xcursor-&maintainer=&last_update=&flagged=&limit=50 "xcursor-" search].<br />
* [[AUR]] — [https://aur.archlinux.org/packages.php?O=0&L=0&C=17&K=cursor&SeB=nd&SB=n&SO=a&PP=50&do_Search=Go "cursor" search].<br />
<br />
=== Manually ===<br />
<br />
If a cursor theme is not available in the official repositories or the AUR, it can be added manually. A number of websites exist where cursor themes can be downloaded. Once downloaded, they need to be put in the ''icons'' directory (as cursors have the ability to be bundled with icon themes).<br />
<br />
Some websites that have cursor themes:<br />
<br />
* [https://www.gnome-look.org/browse/cat/107/ord/latest/ GNOME Look]<br />
* [http://www.customize.org/list/xcursors Customize.org]<br />
* [http://www.deviantart.com/browse/all/customization/skins/linuxutil/x11cursors/ Deviant Art]<br />
<br />
For ''user-specific'' installation, use the {{ic|~/.icons/}} directory. Extract them with this command that will work for most archives:<br />
<br />
$ bsdtar xvf foobar-cursor-theme.tar.gz --directory ~/.icons<br />
<br />
The cursor theme directory structure is {{ic|theme-name/cursors}}, for example: {{ic|~/.icons/''theme''/cursors/}}; make sure the extracted files follow this structure.<br />
<br />
{{Note|For ''system-wide'' installation the {{ic|/usr/share/icons}} directory is used. Direct extraction to this directory is usually discouraged as files here are not tracked by [[pacman]]; it is recommended to create a [[PKGBUILD|package]] for the cursor theme instead.}}<br />
<br />
Already installed cursor themes can be viewed with the command:<br />
<br />
find /usr/share/icons ~/.icons -type d -name "cursors"<br />
<br />
If the package includes an {{ic|index.theme}} file, check if there is an "Inherits" line inside. If yes, check whether the inherited theme also exists on the system (rename if needed).<br />
<br />
== Configuration ==<br />
<br />
There are various ways to set the cursor theme.<br />
<br />
=== XDG specification ===<br />
<br />
This method applies to both [[X11]] and [[Wayland]] cursor themes. <br />
<br />
For ''user-specific'' configuration, create or edit {{ic|~/.icons/default/index.theme}}; for ''system-wide'' configuration, one can edit {{ic|/usr/share/icons/default/index.theme}}.<br />
<br />
The {{ic|Inherits}} option in the {{ic|[icon theme]}} section must be set to the xcursor theme directory name {{ic|''cursor_theme_name''}}, for example {{ic|xcursor-breeze-snow}}:<br />
<br />
{{hc|~/.icons/default/index.theme|2=<br />
[icon theme] <br />
Inherits=''cursor_theme_name''}}<br />
<br />
You should then edit {{ic|~/.config/gtk-3.0/settings.ini}}, replacing the {{ic|''cursor_theme_name''}} with the chosen one: <br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|2=<br />
[Settings]<br />
gtk-cursor-theme-name=''cursor_theme_name''}}<br />
<br />
Re-login for the changes to take effect.<br />
<br />
=== LXAppearance ===<br />
<br />
[[LXDE#Cursors|LXAppearance]] sets the default cursor by creating an {{ic|~/.icons/default/index.theme}} file: if you edited that file manually, LXAppearance will overwrite it. Remember to also edit {{ic|~/.config/gtk-3.0/settings.ini}} manually as specified in [[#XDG specification]], because applications like Firefox use this setting instead.<br />
<br />
=== Desktop environments ===<br />
<br />
[[Desktop environments]] use the [http://standards.freedesktop.org/xsettings-spec/xsettings-spec-0.5.html XSETTINGS protocol], typically implemented through a settings daemon. While this allows to change the cursor on-the-fly, the applied theme may be inconsistent across applications. See [[#XDG specification]] to change the cursor theme manually.<br />
<br />
==== GNOME ====<br />
<br />
To change the theme in [[GNOME]], use {{Pkg|gnome-tweaks}} or set the configuration directly with:<br />
<br />
gsettings set org.gnome.desktop.interface cursor-theme ''cursor_theme_name''<br />
<br />
Change the cursor size with (depending on the theme, sizes are 24, 32, 48, 64):<br />
<br />
gsettings set org.gnome.desktop.interface cursor-size ''cursor_theme_size''<br />
<br />
==== MATE ====<br />
<br />
In MATE one can use mate-control-center or gsettings. To change the theme:<br />
<br />
gsettings set org.mate.peripherals-mouse cursor-theme ''cursor_theme_name''<br />
<br />
To change the size:<br />
<br />
gsettings set org.mate.peripherals-mouse ''theme-size''<br />
<br />
==== XFCE ====<br />
<br />
To change the xcursor theme, use:<br />
<br />
xfconf-query --channel xsettings --property /Gtk/CursorThemeName --set ''cursor_theme_name''<br />
<br />
To change the size:<br />
<br />
xfconf-query --channel xsettings --property /Gtk/CursorThemeSize --set ''cursor_theme_size''<br />
<br />
=== X resources ===<br />
<br />
To locally name a cursor theme, add to the {{ic|~/.Xresources}} file:<br />
<br />
Xcursor.theme: cursor-theme<br />
<br />
To have the cursor theme properly loaded it will need to be done so by the window manager; if it does not, it can be forced to load prior the window manager by putting the following command in {{ic|~/.xinitrc}} or [[.xprofile]] (depending on ones personal setup):<br />
<br />
$ xrdb ~/.Xresources<br />
<br />
Optionally, add this line to {{ic|~/.Xresources}} if your cursor theme supports multiple sizes:<br />
<br />
Xcursor.size: 16<br />
<br />
{{Tip|32, 48 or 64 may also be good size.}}<br />
<br />
If in doubt over supported cursor sizes, start X without this setting and let it choose the cursor size automatically. (Refer to your window manager documentation for details.)<br />
<br />
=== Environment variable ===<br />
<br />
You can use an [[environment variable]] to set a theme for a single application to try it out temporarily, for example:<br />
<br />
$ XCURSOR_THEME=SomeThemeName xclock<br />
<br />
XCURSOR_SIZE is optional if your cursor theme supports multiple sizes.<br />
<br />
=== Display managers ===<br />
<br />
Cursor theme can usually be set within a display manager, but keep in mind the cursor theme may not carry over to the user session. <br />
<br />
==== GDM ====<br />
<br />
See [[GDM#Changing the cursor theme]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Create links to missing cursors ===<br />
<br />
Applications may keep using the default cursors when a theme lacks some cursors. This can be corrected by adding links to the missing cursors. For example:<br />
<br />
$ cd ~/.icons/''theme''/cursors/<br />
$ ln -s right_ptr arrow<br />
$ ln -s cross crosshair<br />
$ ln -s right_ptr draft_large<br />
$ ln -s right_ptr draft_small<br />
$ ln -s cross plus<br />
$ ln -s left_ptr top_left_arrow<br />
$ ln -s cross tcross<br />
$ ln -s hand hand1<br />
$ ln -s hand hand2<br />
$ ln -s left_side left_tee<br />
$ ln -s left_ptr ul_angle<br />
$ ln -s left_ptr ur_angle<br />
$ ln -s left_ptr_watch 08e8e1c95fe2fc01f976f1e063a24ccd<br />
<br />
If the above does not solve the problem, look in {{ic|/usr/share/icons/whiteglass/cursors}} for additional cursors your theme may be missing, and create links for these as well.<br />
<br />
{{Tip|You can also remove unwanted cursors. To for example remove the "watch" cursor:<br />
<br />
$ cd ~/.icons/''theme''/cursors/<br />
$ rm watch left_ptr_watch<br />
$ ln -s left_ptr watch<br />
$ ln -s left_ptr left_ptr_watch<br />
}}<br />
<br />
=== Supplying missing cursors ===<br />
<br />
Some programs set their own custom cursors which you may want to override. A common example of this is rdesktop, which connects to a Microsoft Windows computer and uses the cursors obtained from the remote machine, which can often be difficult to see due to protocol limitations yielding poor conversion quality.<br />
<br />
This can be resolved by replacing these cursors with ones from the same (or another) cursor theme. In order to do this, the '''hash''' of the image must be obtained. This is done by setting the {{ic|XCURSOR_DISCOVER}} environment variable prior to launching the application that sets these cursors:<br />
<br />
$ XCURSOR_DISCOVER=1 rdesktop ...<br />
<br />
The first time (and only the first time) the cursor is set, some details will be displayed, like this:<br />
<br />
Cursor image name: 24020000002800000528000084810000<br />
...<br />
Cursor image name: 7bf1cc07d310bf080118007e08fc30ff<br />
...<br />
Cursor hash 24020000002800000528000084810000 returns 0x0<br />
<br />
When Xcursor looks for missing cursors, the search path includes {{ic|~/.icons/default/cursors}} so this is where an image can be placed for Xcursor to find. First, create this directory if it does not already exist:<br />
<br />
$ mkdir -p ~/.icons/default/cursors<br />
<br />
Then link the hash to the target image. Here we are using the {{ic|left_ptr}} image from the {{ic|Vanilla-DMZ}} cursor theme:<br />
<br />
$ ln -s /usr/share/icons/Vanilla-DMZ/cursors/left_ptr ~/.icons/default/cursors/24020000002800000528000084810000<br />
<br />
The change will be visible as soon as the application is restarted. No special method of launching the application is required.<br />
<br />
==== rdesktop ====<br />
<br />
Here are some common Microsoft Windows cursors that rdesktop uses when connecting to a remote machine running Windows 7. Unfortunately animated cursors are difficult to override as they are sent frame-by-frame, so one mapping will be needed for every frame!<br />
<br />
$ ln -s /usr/share/icons/$THEME/cursors/xterm ~/.icons/default/cursors/00000000017e000002fc000000000000<br />
$ ln -s /usr/share/icons/$THEME/cursors/right_ptr ~/.icons/default/cursors/00000093000010860000631100006609<br />
$ ln -s /usr/share/icons/$THEME/cursors/plus ~/.icons/default/cursors/01e00000201c00004038000080300000<br />
$ ln -s /usr/share/icons/$THEME/cursors/left_ptr ~/.icons/default/cursors/24020000002800000528000084810000<br />
$ ln -s /usr/share/icons/$THEME/cursors/left_ptr_watch ~/.icons/default/cursors/6ce0180090108e0005814700a0021400<br />
$ ln -s /usr/share/icons/$THEME/cursors/hand ~/.icons/default/cursors/d2201000a2c622004385440041308800<br />
$ ln -s /usr/share/icons/$THEME/cursors/watch ~/.icons/default/cursors/fc618c00da110f0034fd0e004e082400<br />
<br />
=== Change X shaped default cursor ===<br />
<br />
The default X shaped Xcursor appears in window managers that do not set the default cursor to left_ptr or in window managers using XCB (like [[awesome]]) instead of Xlib.<br />
<br />
To fix this simply add the following to your {{ic|~/.xinitrc}} , xsession or window managers startup configuration if possible (for example bspwm's bspwmrc). <br />
$ xsetroot -cursor_name left_ptr<br />
<br />
The list of cursor styles is in [https://tronche.com/gui/x/xlib/appendix/b/ appendix B] of the X protocol.<br />
<br />
=== .Xdefaults ===<br />
<br />
If you have conflicting cursors then it might be because a different cursor has been set in the {{ic|~/.Xdefaults}} file.<br />
<br />
== See also ==<br />
<br />
* [http://www.x.org/releases/current/doc/man/man3/Xcursor.3.xhtml man Xcursor] — For more information about cursors in X (supported directories, formats, compatibility, etc.).</div>Bricewgehttps://wiki.archlinux.org/index.php?title=Dm-crypt/System_configuration&diff=448768Dm-crypt/System configuration2016-08-30T15:58:20Z<p>Bricewge: /* mkinitcpio */ add where to set the keymap</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Encryption]]<br />
[[Category:File systems]]<br />
[[ja:Dm-crypt/システム設定]]<br />
{{Expansion|Aggregate here all the generic information on system configuration from the other sub-articles of [[Dm-crypt]].}}<br />
Back to [[Dm-crypt]].<br />
<br />
{{Tip|If in need to remotely unlock root or other early-boot filesystems (headless machine, distant servers...), follow the specific instructions from [[Dm-crypt/Specialties#Remote_unlocking_of_the_root_.28or_other.29_partition|Dm-crypt/Specialties#Remote unlocking of encrypted root]].}}<br />
<br />
== mkinitcpio ==<br />
When encrypting a system it is necessary to regenerate the initial ramdisk after properly configuring [[mkinitcpio]]. Depending on the particular scenarios, a subset of the following hooks will have to be enabled:<br />
<br />
* {{ic|encrypt}}: always needed when encrypting the root partition, or a partition that needs to be mounted ''before'' root. It is not needed in all the other cases, as system initialization scripts like {{ic|/etc/crypttab}} take care of unlocking other encrypted partitions. This hook must be placed ''after'' the {{ic|udev}} hook, if that is used.<br />
* {{ic|shutdown}}: deprecated, not necessary [https://mailman.archlinux.org/pipermail/arch-dev-public/2013-December/025742.html anymore]. <br />
* {{ic|keymap}}: provides support for foreign keymaps for typing encryption passwords; it must come ''before'' the {{ic|encrypt}} hook. Setting your keymap is done in [[keymap#Persistent_configuration|{{ic|/etc/vconsole.conf}}]].<br />
* {{ic|keyboard}}: needed to make USB keyboards work in early userspace.<br />
* {{ic|usbinput}}: deprecated, but can be given a try in case {{ic|keyboard}} does not work.<br />
<br />
Other hooks needed should be clear from other manual steps followed during the installation of the system.<br />
<br />
== Boot loader ==<br />
In order to enable booting an encrypted root partition, a subset of the following kernel parameters need to be set: see [[kernel parameters]] for instructions specific to your [[boot loader]]. <br />
<br />
For example using [[GRUB#Root partition|GRUB]] the relevant parameters are best added to {{ic|/etc/default/grub}} before generating the boot configuration. See also [[GRUB#Warning when installing in chroot]] as another point to be aware of when installing the GRUB loader. <br />
<br />
{{Expansion|Users of the {{ic|sd-encrypt}} hook require other kernel parameters. A subsection for it should be added. ({{Bug|36265}} is resolved, so the limitations it posed are gone).}}<br />
<br />
=== cryptdevice ===<br />
This parameter will make the system prompt for the passphrase to unlock the device containing the encrypted root on a cold boot. It is parsed by the {{ic|encrypt}} hook to identify which device contains the encrypted system:<br />
<br />
cryptdevice=''device'':''dmname''<br />
<br />
* {{ic|''device''}} is the path to the raw encrypted device. Usage of [[Persistent block device naming]] is advisable.<br />
* {{ic|''dmname''}} is the '''d'''evice-'''m'''apper name given to the device after decryption, which will be available as {{ic|/dev/mapper/''dmname''}}.<br />
* If a LVM contains the [[Dm-crypt/Encrypting_an_entire_system#LUKS_on_LVM|encrypted root]], the LVM gets activated first and the volume group containing the logical volume of the encrypted root serves as ''device''. It is then followed by the respective volume group to be mapped to root. The parameter follows the form of {{ic|cryptdevice<nowiki>=</nowiki>''/dev/vgname/lvname'':''dmname''}}.<br />
<br />
{{Note|When using systemd & sd-encrypt hooks, use {{ic|''luks.uuid''}} instead of cryptdevice, see ''systemd-cryptsetup-generator(8)''.}}<br />
<br />
=== root ===<br />
<br />
The {{ic|1=root=}} parameter specifies the {{ic|''device''}} of the actual (decrypted) root file system:<br />
<br />
root=''device''<br />
<br />
* If the file system is formatted directly on the decrypted device file this will be {{ic|/dev/mapper/''dmname''}}.<br />
* If a LVM gets activated first and contains an [[Dm-crypt/Encrypting_an_entire_system#LUKS_on_LVM|encrypted logical rootvolume]], the above form applies as well. <br />
* If the root file system is contained in a logical volume of a fully [[encrypted LVM]], the device mapper for it will be in the general form of {{ic|root<nowiki>=</nowiki>/dev/mapper/''volumegroup''-''logicalvolume''}}.<br />
<br />
{{Tip|This parameter is not needed to be specified manually when using [[GRUB]]. Executing ''grub-mkconfig'' is meant to determine the correct UUID of the decrypted root filesystem and specify it in the generated {{ic|grub.cfg}} automatically.}}<br />
<br />
=== resume ===<br />
resume=''device''<br />
<br />
* {{ic|''device''}} is the device file of the decrypted (swap) filesystem used for suspend2disk. If swap is on a separate partition, it will be in the form of {{ic|/dev/mapper/swap}}. See also [[Dm-crypt/Swap encryption]].<br />
<br />
=== cryptkey ===<br />
<br />
This parameter is required by the {{ic|''encrypt''}} hook for reading a keyfile to unlock the {{ic|''cryptdevice''}}. It can have three parameter sets, depending on whether the keyfile exists as a file in a particular device, a bitstream starting on a specific location, or a file in the initramfs. <br />
<br />
For a file in a device the format is:<br />
<br />
cryptkey=''device'':''fstype'':''path''<br />
<br />
* {{ic|''device''}} is the raw block device where the key exists.<br />
* {{ic|''fstype''}} is the filesystem type of {{ic|''device''}} (or auto).<br />
* {{ic|''path''}} is the absolute path of the keyfile within the device.<br />
<br />
Example: {{ic|1=cryptkey=/dev/usbstick:vfat:/secretkey}}<br />
<br />
For a bitstream on a device the key's location is specified with the following: <br />
<br />
cryptkey=''device'':''offset'':''size'' <br />
<br />
Example: {{ic|1=cryptkey=/dev/sdZ:0:512}} reads a 512 bit keyfile starting at the beginning of the device. <br />
<br />
For a file [[mkinitcpio#BINARIES and FILES|included]] in the initramfs the format is[https://projects.archlinux.org/svntogit/packages.git/tree/trunk/encrypt_hook?h=packages/cryptsetup#n14]:<br />
<br />
cryptkey=rootfs:''path''<br />
<br />
Example: {{ic|1=cryptkey=rootfs:/secretkey}}<br />
<br />
Also note that if {{ic|cryptkey}} is not specified, it defaults to {{ic|/crypto_keyfile.bin}} (in the initramfs).[https://projects.archlinux.org/svntogit/packages.git/tree/trunk/encrypt_hook?h=packages/cryptsetup#n8]<br />
<br />
See also [[Dm-crypt/Device encryption#Keyfiles]].<br />
<br />
=== crypto ===<br />
This parameter is specific to pass ''dm-crypt'' plain mode options to the ''encrypt'' hook. <br />
<br />
It takes the form<br />
{{bc|<nowiki>crypto=</nowiki><hash>:<cipher>:<keysize>:<offset>:<skip>}}<br />
<br />
The arguments relate directly to the ''cryptsetup'' options. See [[Dm-crypt/Device encryption#Encryption options for plain mode]].<br />
<br />
For a disk encrypted with just ''plain'' default options, the {{ic|crypto}} arguments must be specified, but each entry can be left blank: <br />
{{bc|<nowiki>crypto=::::</nowiki>}}<br />
A specific example of arguments is <br />
{{bc|<nowiki>crypto=sha512:twofish-xts-plain64:512:0:</nowiki>}}<br />
<br />
== crypttab ==<br />
The {{ic|/etc/crypttab}} (encrypted device table) file is similar to the [[fstab]] file and contains a list of encrypted devices to be unlocked during system boot up. This file can be used for automatically mounting encrypted swap devices or secondary file systems.<br />
<br />
{{ic|crypttab}} is read ''before'' {{ic|fstab}}, so that dm-crypt containers can be unlocked before the file system inside is mounted. Note that {{ic|crypttab}} is read ''after'' the system has booted up, therefore it is not a replacement for unlocking encrypted partitions by using [[#mkinitcpio|mkinitcpio]] hooks and [[#Boot loader|boot loader options]] as in the case of [[Dm-crypt/Encrypting an entire system|encrypting the root partition]]. {{ic|crypttab}} processing at boot time is made by the {{ic|systemd-cryptsetup-generator}} automatically.<br />
<br />
See the {{ic|crypttab}} [http://linux.die.net/man/5/crypttab man page] for details, read below for some examples, and the [[#Mounting at boot time]] section for instructions on how to use UUIDs to mount an encrypted device. <br />
<br />
{{Warning|There are issues with [[systemd]] when processing {{ic|crypttab}} entries for ''dm-crypt'' [[Dm-crypt/Device_encryption#Encryption options for plain mode|plain mode]] ({{ic|--type plain}}) devices: <br />
<br />
* For {{ic|--type plain}} devices with a keyfile, it is necessary to add the {{ic|1=hash=plain}} option to crypttab due to a [https://bugs.freedesktop.org/show_bug.cgi?id&#61;52630 systemd incompatibility]. '''Do not''' use {{ic|systemd-cryptsetup}} manually for device creation to work around it.<br />
<br />
* It may be further required to add the {{ic|plain}} option explicitly to force {{ic|systemd-cryptsetup}} to recognize a {{ic|--type plain}}) device at boot. [https://github.com/systemd/systemd/issues/442 GitHub issue in question.]}}<br />
<br />
{{hc|/etc/crypttab|<nowiki><br />
# Example crypttab file. Fields are: name, underlying device, passphrase, cryptsetup options.<br />
<br />
# Mount /dev/lvm/swap re-encrypting it with a fresh key each reboot<br />
swap /dev/lvm/swap /dev/urandom swap,cipher=aes-xts-plain64,size=256<br />
<br />
# Mount /dev/lvm/tmp as /dev/mapper/tmp using plain dm-crypt with a random passphrase, making its contents unrecoverable after it is dismounted.<br />
tmp /dev/lvm/tmp /dev/urandom tmp,cipher=aes-xts-plain64,size=256 <br />
<br />
# Mount /dev/lvm/home as /dev/mapper/home using LUKS, and prompt for the passphrase at boot time.<br />
home /dev/lvm/home<br />
<br />
# Mount /dev/sdb1 as /dev/mapper/backup using LUKS, with a passphrase stored in a file.<br />
backup /dev/sdb1 /home/alice/backup.key<br />
</nowiki>}}<br />
<br />
=== Mounting at boot time ===<br />
<br />
If you want to mount an encrypted drive at boot time, enter the device's UUID in {{ic|/etc/crypttab}}. You get the UUID (partition) by using the command {{ic|lsblk -f}} and adding it to {{ic|crypttab}} in the form:<br />
<br />
{{hc|/etc/crypttab|<nowiki><br />
externaldrive UUID=2f9a8428-ac69-478a-88a2-4aa458565431 none luks,timeout=180<br />
</nowiki>}}<br />
<br />
The first parameter is your preferred device mapper's name for the encrypted drive. The option {{ic|none}} will trigger a prompt during boot to type the passphrase for unlocking the partition. The {{ic|timeout}} option defines a timeout in seconds for entering the decryption password during boot.<br />
<br />
A [[Dm-crypt/Device_encryption#Keyfiles|keyfile]] can also be set up and referenced instead of {{ic|none}}. This results in an automatic unlocking, if the keyfile is accessible during boot. Since LUKS offers the option to have multiple keys, the chosen option can also be changed later.<br />
<br />
Use the device mapper's name you've defined in {{ic|/etc/crypttab}} in {{ic|/etc/fstab}} as follows:<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
/dev/mapper/externaldrive /mnt/backup ext4 defaults,errors=remount-ro 0 2<br />
</nowiki>}}<br />
<br />
Since {{ic|/dev/mapper/externaldrive}} already is the result of a unique partition mapping, there is no need to specify an UUID for it. In any case, the mapper with the filesystem will have a different UUID than the partition it is encrypted in.<br />
<br />
==== Mounting a stacked blockdevice ==== <br />
<br />
The systemd generators also automatically process stacked block devices at boot. <br />
<br />
For example, you can create a [[RAID]] setup, use cryptsetup on it and create an [[LVM]] logical volume with respective filesystem inside the encrypted block device. A resulting: <br />
{{hc|$ lsblk -f|<br />
─sdXX linux_raid_member <br />
│ └─md0 crypto_LUKS <br />
│ └─cryptedbackup LVM2_member <br />
│ └─vgraid-lvraid ext4 /mnt/backup<br />
└─sdYY linux_raid_member <br />
└─md0 crypto_LUKS <br />
└─cryptedbackup LVM2_member <br />
└─vgraid-lvraid ext4 /mnt/backup<br />
}}<br />
will ask for the passphrase and mount automatically at boot. <br />
<br />
Given you specify the correct corresponding crypttab (e.g. UUID for the {{ic|crypto_LUKS}} device) and fstab ({{ic|/dev/mapper/vgraid-lvraid}}) entries, there is no need to add additional mkinitcpio hooks/configuration, because {{ic|/etc/crypttab}} processing applies to non-root mounts only. One exception is when the {{ic|mdadm_udev}} hook is used ''already'' (e.g. for the root device). In this case {{ic|/etc/madadm.conf}} and the initramfs need updating to achieve the correct root raid is picked first.</div>Bricewgehttps://wiki.archlinux.org/index.php?title=OpenVPN&diff=435695OpenVPN2016-05-20T00:06:15Z<p>Bricewge: /* DNS */ fix issue as discussed here: https://github.com/masterkorp/openvpn-update-resolv-conf/issues/15#issuecomment-212401186</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[de:OpenVPN]]<br />
[[ru:OpenVPN]]<br />
[[zh-CN:OpenVPN]]<br />
{{Related articles start}}<br />
{{Related|OpenVPN in Linux containers}}<br />
{{Related articles end}}<br />
<br />
This article describes a basic installation and configuration of [http://openvpn.net OpenVPN], suitable for private and small business use. For more detailed information, please see the [https://community.openvpn.net/openvpn/wiki/Openvpn23ManPage OpenVPN 2.3 man page] and the [http://openvpn.net/index.php/open-source/documentation OpenVPN documentation]. OpenVPN is a robust and highly flexible [[Wikipedia:VPN|VPN]] daemon. It supports [[Wikipedia:SSL/TLS|SSL/TLS]] security, [[Wikipedia:Bridging_(networking)|Ethernet bridging]], [[Wikipedia:Transmission_Control_Protocol|TCP]] or [[Wikipedia:User_Datagram_Protocol|UDP]] [[Wikipedia:Tunneling_protocol|tunnel transport]] through [[Wikipedia:Proxy_server|proxies]] or [[Wikipedia:Network address translation|NAT]]. Additionally it has support for dynamic IP addresses and [[Wikipedia:Dynamic_Host_Configuration_Protocol|DHCP]], scalability to hundreds or thousands of users, and portability to most major OS platforms.<br />
<br />
OpenVPN is tightly bound to the [http://www.openssl.org OpenSSL] library, and derives much of its crypto capabilities from it. It supports conventional encryption using a [[Wikipedia:Pre-shared_key|pre-shared secret key]] (Static Key mode) or [[Wikipedia:Public_key|public key security]] ([[Wikipedia:SSL/TLS|SSL/TLS]] mode) using client & server certificates. Additionally it supports unencrypted TCP/UDP tunnels.<br />
<br />
OpenVPN is designed to work with the [[Wikipedia:TUN/TAP|TUN/TAP]] virtual networking interface that exists on most platforms. Overall, it aims to offer many of the key features of [[Wikipedia:Ipsec|IPSec]] but with a relatively lightweight footprint. OpenVPN was written by James Yonan and is published under the [[Wikipedia:GNU General Public License|GNU General Public License (GPL)]].<br />
<br />
== Install OpenVPN ==<br />
<br />
[[Install]] the {{Pkg|openvpn}} package.<br />
<br />
{{Note|The software contained in this package supports both server and client mode, so install it on all machines that need to create VPN connections.}}<br />
<br />
== Kernel configuration ==<br />
<br />
OpenVPN requires TUN/TAP support, which is already configured in the default kernel. If you build your own kernel, make sure to enable the {{ic|tun}} module as below: <br />
<br />
{{hc|Kernel config file|<br />
Device Drivers<br />
--> Network device support<br />
[M] Universal TUN/TAP device driver support}}<br />
<br />
Read [[Kernel modules]] for more information.<br />
<br />
== Connect to a VPN provided by a third party ==<br />
<br />
To connect to a VPN service provided by a third party, most of the following can most likely be ignored, especially regarding server setup. Most likely you will want to begin with [[#The client configuration file]] and skip ahead to [[#Starting OpenVPN]] after that. Use the certificates and instructions given by your provider, for instance see: [[Airvpn]].<br />
<br />
{{Note|Most free VPN providers will (often only) offer [[PPTP server|PPTP]], which is drastically easier to setup and configure, but is [http://poptop.sourceforge.net/dox/protocol-security.phtml not secure].}}<br />
<br />
== Create a Public Key Infrastructure (PKI) from scratch ==<br />
<br />
If you are setting up OpenVPN from scratch, you will need to create a [[Wikipedia:Public key infrastructure|Public Key Infrastructure (PKI)]].<br />
<br />
Create the needed certificates and keys using the [[easy-rsa]] scripts.<br />
<br />
The final step of the key creation process is to copy the files needed to the correct machines through a secure channel.<br />
<br />
{{Note|The rest of this article assumes that the keys and certificates are placed in {{ic|/etc/openvpn}}.}}<br />
<br />
The public ca.crt certificate is needed on all servers and clients. The private ca.key key is secret and only needed on the key generating machine.<br />
<br />
A server needs server.crt, dh2048.pem (public), server.key, and ta.key (private).<br />
<br />
A client needs client.crt (public), client.key, and ta.key (private).<br />
<br />
== A basic L3 IP routing configuration ==<br />
<br />
{{Note|Unless otherwise explicitly stated, the rest of this article assumes this basic configuration.}}<br />
<br />
OpenVPN is an extremely versatile piece of software and many configurations are possible, in fact machines can be both "servers" and "clients", blurring the distinction between server and client.<br />
<br />
What really distinguishes a server from a client (apart from the type of certificate used) is the configuration file itself. The OpenVPN daemon start-up script reads all the .conf configuration files it finds in {{ic|/etc/openvpn}} on start-up and acts accordingly. If it finds more than one configuration file, it will start one OpenVPN process per configuration file.<br />
<br />
This article explains how to set up a server named elmer and a client that connects to it named bugs. More servers and clients can easily be added by creating more key/certificate pairs and adding more server and client configuration files.<br />
<br />
The OpenVPN package comes with a collection of example configuration files for different purposes. The sample server and client configuration files make an ideal starting point for a basic OpenVPN setup with the following features:<br />
<br />
* Uses [[Wikipedia:Public key infrastructure|Public Key Infrastructure (PKI)]] for authentication.<br />
* Creates a VPN using a virtual TUN network interface (OSI L3 IP routing).<br />
* Listens for client connections on UDP port 1194 (OpenVPN's [[Wikipedia:Port_number|official IANA port number]]).<br />
* Distributes virtual addresses to connecting clients from the 10.8.0.0/24 subnet.<br />
<br />
For more advanced configurations, please see the official [http://openvpn.net/index.php/manuals/427-openvpn-22.html OpenVPN 2.2 man page] and the [http://openvpn.net/index.php/open-source/documentation OpenVPN documentation].<br />
<br />
=== The server configuration file ===<br />
<br />
Copy the example server configuration file to {{ic|/etc/openvpn/server.conf}}:<br />
<br />
# cp /usr/share/openvpn/examples/server.conf /etc/openvpn/server.conf<br />
<br />
Edit the following:<br />
<br />
* The {{ic|ca}}, {{ic|cert}}, {{ic|key}}, and {{ic|dh}} parameters to reflect the path and names of the keys and certificates. Specifying the paths will allow you to run the OpenVPN executable from any directory for testing purposes.<br />
* Enable the SSL/TLS HMAC handshake protection. '''Note the use of the parameter 0 for a server'''.<br />
* It is recommended to run OpenVPN with reduced privileges once it has initialized. Do this by uncommenting the {{ic|user}} and {{ic|group}} directives.<br />
<br />
{{hc|/etc/openvpn/server.conf|<br />
ca /etc/openvpn/ca.crt<br />
cert /etc/openvpn/elmer.crt<br />
key /etc/openvpn/elmer.key<br />
<br />
dh /etc/openvpn/dh2048.pem<br />
.<br />
.<br />
tls-auth /etc/openvpn/ta.key '''0'''<br />
.<br />
.<br />
user nobody<br />
group nobody<br />
}}<br />
<br />
{{Note|Note that if the server is behind a firewall or a NAT translating router, you will have to forward the OpenVPN UDP port (1194) to the server.}}<br />
<br />
=== The client configuration file ===<br />
<br />
Copy the example client configuration file to {{ic|/etc/openvpn/client.conf}}:<br />
<br />
# cp /usr/share/openvpn/examples/client.conf /etc/openvpn/client.conf<br />
<br />
Edit the following:<br />
<br />
* The {{ic|remote}} directive to reflect either the server's [[Wikipedia:Fully qualified domain name|Fully Qualified Domain Name]], hostname (as known to the client), or its IP address.<br />
* Uncomment the {{ic|user}} and {{ic|group}} directives to drop privileges.<br />
* The {{ic|ca}}, {{ic|cert}}, and {{ic|key}} parameters to reflect the path and names of the keys and certificates.<br />
* Enable the SSL/TLS HMAC handshake protection. '''Note the use of the parameter 1 for a client'''.<br />
<br />
{{hc|/etc/openvpn/client.conf|<br />
remote elmer.acmecorp.org 1194<br />
.<br />
.<br />
user nobody<br />
group nobody<br />
ca /etc/openvpn/ca.crt<br />
cert /etc/openvpn/bugs.crt<br />
key /etc/openvpn/bugs.key<br />
.<br />
.<br />
tls-auth /etc/openvpn/ta.key '''1'''<br />
}}<br />
<br />
==== Drop root privileges after connecting ====<br />
<br />
Using the options {{ic|user nobody}} and {{ic|group nobody}} in the configuration file makes ''openvpn'' drop its privileges after establishing the connection. The downside is that upon VPN disconnect the daemon is unable to delete its set network routes again. If one wants to limit transmitting traffic without the VPN connection, this may be advantageous. However, it requires manual action to delete the routes and will, hence, often be undesired. For this case the [https://openvpn.net/index.php/open-source/documentation/howto.html#security OpenVPN howto] explains how to create an unprivileged user mode and wrapper script to have the routes restored automatically. <br />
<br />
Further, it is possible to let OpenVPN start as a non-privileged user in the first place, without ever running as root, see [https://community.openvpn.net/openvpn/wiki/UnprivilegedUser this OpenVPN wiki page].<br />
<br />
=== Testing the OpenVPN configuration ===<br />
<br />
Run {{ic|# openvpn /etc/openvpn/server.conf}} on the server, and {{ic|# openvpn /etc/openvpn/client.conf}} on the client. You should see something similar to this:<br />
<br />
{{hc|# openvpn /etc/openvpn/server.conf|2=<br />
Wed Dec 28 14:41:26 2011 OpenVPN 2.2.1 x86_64-unknown-linux-gnu [SSL] [LZO2] [EPOLL] [eurephia] built on Aug 13 2011<br />
Wed Dec 28 14:41:26 2011 NOTE: OpenVPN 2.1 requires '--script-security 2' or higher to call user-defined scripts or executables<br />
Wed Dec 28 14:41:26 2011 Diffie-Hellman initialized with 2048 bit key<br />
.<br />
.<br />
Wed Dec 28 14:41:54 2011 bugs/95.126.136.73:48904 MULTI: primary virtual IP for bugs/95.126.136.73:48904: 10.8.0.6<br />
Wed Dec 28 14:41:57 2011 bugs/95.126.136.73:48904 PUSH: Received control message: 'PUSH_REQUEST'<br />
Wed Dec 28 14:41:57 2011 bugs/95.126.136.73:48904 SENT CONTROL [bugs]: 'PUSH_REPLY,route 10.8.0.1,topology net30,ping 10,ping-restart 120,ifconfig 10.8.0.6 10.8.0.5' (status=1)<br />
}}<br />
<br />
{{hc|# openvpn /etc/openvpn/client.conf|2=<br />
Wed Dec 28 14:41:50 2011 OpenVPN 2.2.1 i686-pc-linux-gnu [SSL] [LZO2] [EPOLL] [eurephia] built on Aug 13 2011<br />
Wed Dec 28 14:41:50 2011 NOTE: OpenVPN 2.1 requires '--script-security 2' or higher to call user-defined scripts or executables<br />
Wed Dec 28 14:41:50 2011 LZO compression initialized<br />
.<br />
.<br />
Wed Dec 28 14:41:57 2011 GID set to nobody<br />
Wed Dec 28 14:41:57 2011 UID set to nobody<br />
Wed Dec 28 14:41:57 2011 Initialization Sequence Completed<br />
}}<br />
<br />
On the server, find the IP address assigned to the tunX device:<br />
<br />
{{hc|# ip addr show|2=<br />
.<br />
.<br />
40: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN qlen 100<br />
link/none<br />
inet 10.8.0.1 peer 10.8.0.2/32 scope global tun0<br />
}}<br />
<br />
Here we see that the server end of the tunnel has been given the IP address 10.8.0.1.<br />
<br />
Do the same on the client:<br />
<br />
{{hc|# ip addr show|2=<br />
.<br />
.<br />
37: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN qlen 100<br />
link/none<br />
inet 10.8.0.6 peer 10.8.0.5/32 scope global tun0<br />
}}<br />
<br />
And the client side has been given the IP address 10.8.0.6.<br />
<br />
Now try pinging the interfaces.<br />
<br />
On the server:<br />
<br />
{{hc|# ping -c3 10.8.0.6|2=<br />
PING 10.8.0.6 (10.8.0.6) 56(84) bytes of data.<br />
64 bytes from 10.8.0.6: icmp_req=1 ttl=64 time=238 ms<br />
64 bytes from 10.8.0.6: icmp_req=2 ttl=64 time=237 ms<br />
64 bytes from 10.8.0.6: icmp_req=3 ttl=64 time=205 ms<br />
<br />
--- 10.8.0.6 ping statistics ---<br />
3 packets transmitted, 3 received, 0% packet loss, time 2002ms<br />
rtt min/avg/max/mdev = 205.862/227.266/238.788/15.160 ms<br />
}}<br />
<br />
On the client:<br />
<br />
{{hc|# ping -c3 10.8.0.1|2=<br />
PING 10.8.0.1 (10.8.0.1) 56(84) bytes of data.<br />
64 bytes from 10.8.0.1: icmp_req=1 ttl=64 time=158 ms<br />
64 bytes from 10.8.0.1: icmp_req=2 ttl=64 time=158 ms<br />
64 bytes from 10.8.0.1: icmp_req=3 ttl=64 time=157 ms<br />
<br />
--- 10.8.0.1 ping statistics ---<br />
3 packets transmitted, 3 received, 0% packet loss, time 2001ms<br />
rtt min/avg/max/mdev = 157.426/158.278/158.940/0.711 ms<br />
}}<br />
<br />
You now have a working OpenVPN installation, and your client (bugs) will be able to use services on the server (elmer), and vice versa.<br />
<br />
{{Note|If using a firewall, make sure that IP packets on the TUN device are not blocked.}}<br />
<br />
=== Configure the MTU with Fragment and MSS ===<br />
<br />
{{Note|If you do not configure MTU, then you will notice that small packets like ping and DNS will work, however web browsing will not work.}}<br />
<br />
Now it is time to configure the maximum segment size (MSS). In order to do this we need to discover what is the smallest MTU along the path between the client and server. In order to do this you can ping the server and disable fragmentation. Then specify the max packet size.<br />
<br />
{{Accuracy|Output is different - I do not see anything like {{ic|...Frag needed and DF set...}}}}<br />
<br />
{{hc|# ping -c5 -M do -s 1500 elmer.acmecorp.org|2=<br />
PING elmer.acmecorp.org (99.88.77.66) 1500(1528) bytes of data.<br />
From 1.2.3.4 (99.88.77.66) icmp_seq=1 Frag needed and DF set (mtu = 576)<br />
From 1.2.3.4 (99.88.77.66) icmp_seq=1 Frag needed and DF set (mtu = 576)<br />
From 1.2.3.4 (99.88.77.66) icmp_seq=1 Frag needed and DF set (mtu = 576)<br />
From 1.2.3.4 (99.88.77.66) icmp_seq=1 Frag needed and DF set (mtu = 576)<br />
From 1.2.3.4 (99.88.77.66) icmp_seq=1 Frag needed and DF set (mtu = 576)<br />
<br />
--- core.myrelay.net ping statistics ---<br />
0 packets transmitted, 0 received, +5 errors<br />
}}<br />
<br />
We received an ICMP message telling us the MTU is 576 bytes. The means we need to fragment the UDP packets smaller then 576 bytes to allow for some UDP overhead.<br />
<br />
{{hc|# ping -c5 -M do -s 548 elmer.acmecorp.org|2=<br />
PING elmer.acmecorp.org (99.88.77.66) 548(576) bytes of data.<br />
556 bytes from 99.88.77.66: icmp_seq=1 ttl=48 time=206 ms<br />
556 bytes from 99.88.77.66: icmp_seq=2 ttl=48 time=224 ms<br />
556 bytes from 99.88.77.66: icmp_seq=3 ttl=48 time=206 ms<br />
556 bytes from 99.88.77.66: icmp_seq=4 ttl=48 time=207 ms<br />
556 bytes from 99.88.77.66: icmp_seq=5 ttl=48 time=208 ms<br />
<br />
--- myrelay.net ping statistics ---<br />
5 packets transmitted, 5 received, 0% packet loss, time 4001ms<br />
rtt min/avg/max/mdev = 206.027/210.603/224.158/6.832 ms<br />
}}<br />
<br />
After some trial and error..., we discover that we need to fragment packets on 548 bytes. In order to do this we specify this fragment size in the configuration and instruct OpenVPN to fix the Maximum Segment Size (MSS).<br />
<br />
{{hc|/etc/openvpn/client.conf|<br />
remote elmer.acmecorp.org 1194<br />
.<br />
.<br />
fragment 548<br />
mssfix 548<br />
.<br />
.<br />
user nobody<br />
group nobody<br />
.<br />
.<br />
ca /etc/openvpn/ca.crt<br />
cert /etc/openvpn/bugs.crt<br />
key /etc/openvpn/bugs.key<br />
.<br />
.<br />
tls-auth /etc/openvpn/ta.key '''1'''<br />
}}<br />
<br />
We also need to tell the server about the fragmentation. Note that "mssfix" is NOT needed in the server configuration.<br />
<br />
{{Note|Clients that do not support the 'fragment' directive (e.g. OpenELEC, [https://forums.openvpn.net/topic13201.html#p31156 iOS app]) are not able to connect to a server that uses the 'fragment' directive. To support such clients, skip this section and configure the clients with the 'mtu-test' directive described below.}}<br />
<br />
{{hc|/etc/openvpn/server.conf|<br />
ca /etc/openvpn/ca.crt<br />
cert /etc/openvpn/elmer.crt<br />
key /etc/openvpn/elmer.key<br />
<br />
dh /etc/openvpn/dh2048.pem<br />
.<br />
.<br />
tls-auth /etc/openvpn/ta.key '''0'''<br />
.<br />
.<br />
user nobody<br />
group nobody<br />
.<br />
.<br />
fragment 548<br />
}}<br />
<br />
{{Note|The following will add about 3 minutes to OpenVPN start time. It is advisable to configure the fragment size unless your client is a laptop that will be connecting over many different networks and the bottle neck is on the client side.}}<br />
<br />
You can also allow OpenVPN to do this for you by having OpenVPN do the ping testing every time the client connects to the VPN. Be patient, since your client may not inform you about the test being run and the connection may appear as nonfunctional until finished.<br />
{{hc|/etc/openvpn/client.conf|<br />
remote elmer.acmecorp.org 1194<br />
.<br />
.<br />
mtu-test<br />
.<br />
.<br />
user nobody<br />
group nobody<br />
.<br />
.<br />
ca /etc/openvpn/ca.crt<br />
cert /etc/openvpn/bugs.crt<br />
key /etc/openvpn/bugs.key<br />
.<br />
.<br />
tls-auth /etc/openvpn/ta.key '''1'''<br />
}}<br />
<br />
=== IPv6 ===<br />
==== Connect to the server via IPv6 ====<br />
<br />
In order to enable Dual Stack for OpenVPN, you have to change {{ic|proto udp}} to {{ic|proto udp6}} in both server.conf and client.conf. Afterwards both IPv4 and IPv6 are enabled.<br />
<br />
==== Provide IPv6 inside the tunnel ====<br />
<br />
In order to provide IPv6 inside the tunnel, you need to have a IPv6 prefix routed to your OpenVPN server. Either set up a static route on your gateway (if you have a static block assigned), or use a DHCPv6 client to get a prefix with DHCPv6 Prefix delegation (see [[IPv6#Prefix delegation (DHCPv6-PD)|IPv6 Prefix delegation]] for details). You can also use a unique local address from the address block fc00::/7. Both methods have advantages and disadvantages:<br />
<br />
* Many ISPs only provide dynamically changing IPv6 prefixes. OpenVPN does not support prefix changes, so you need to change your server.conf every time the prefix is changed (Maybe can be automated with a script).<br />
* ULA addresses are not routed to the Internet, and setting up NAT is not as straightforward as with IPv4. So you cannot route the entire traffic over the tunnel. If you only want to connect two sites via IPv6, without the need to connect to the Internet over the tunnel, the ULA addresses may be easier to use.<br />
<br />
After you have received a prefix (a /64 is recommended), append the following to the server.conf:<br />
<br />
server-ipv6 2001:db8:0:123::/64<br />
<br />
This is the IPv6 equivalent to the default 10.8.0.0/24 network of OpenVPN and needs to be taken from the DHCPv6 client. Or use for example fd00:1234::/64.<br />
<br />
If you want to push a route to your home network (192.168.1.0/24 equivalent), also append:<br />
<br />
push "route-ipv6 2001:db8:0:abc::/64"<br />
<br />
OpenVPN does not yet include DHCPv6, so there is no method to e.g. push DNS server over IPv6. This needs to be done with IPv4. The [https://community.openvpn.net/openvpn/wiki/IPv6 OpenVPN Wiki] provides some other configuration options.<br />
<br />
== Starting OpenVPN ==<br />
<br />
=== Manual startup ===<br />
<br />
To troubleshoot a VPN connection, start the client's daemon manually with {{ic|openvpn /etc/openvpn/client.conf}} as root. The server can be started the same way using its own configuration file (e.g., {{ic|openvpn /etc/openvpn/server.conf}}).<br />
<br />
=== systemd service configuration ===<br />
<br />
To start OpenVPN automatically at system boot, either for a client or for a server, [[enable]] {{ic|openvpn@''<configuration>''.service}} on the applicable machine.<br />
<br />
For example, if the client configuration file is {{ic|/etc/openvpn/client.conf}}, the service name is {{ic|openvpn@client.service}}. Or, if the server configuration file is {{ic|/etc/openvpn/server.conf}}, the service name is {{ic|openvpn@server.service}}.<br />
<br />
=== Letting NetworkManager start a connection ===<br />
<br />
On a client you might not always need to run a VPN tunnel and/or only want to establish it for a specific NetworkManager connection. This can be done by adding a script to {{ic|/etc/NetworkManager/dispatcher.d/}}. In the following example "Provider" is the name of the NetworkManager connection:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/10-openvpn|2=<br />
#!/bin/bash<br />
<br />
case "$2" in<br />
up)<br />
if [ "$CONNECTION_ID" == "Provider" ]; then<br />
systemctl start openvpn@client<br />
fi<br />
;;<br />
down)<br />
systemctl stop openvpn@client<br />
;;<br />
esac}}<br />
<br />
See [[NetworkManager#Network services with NetworkManager dispatcher]] for more details.<br />
<br />
=== Gnome configuration ===<br />
<br />
If you would like to connect a client to an OpenVPN server through Gnome's built-in network configuration do the following. First, install {{ic|networkmanager-openvpn}}. Then go to the Settings menu and choose Network. Click the plus sign to add a new connection and choose VPN. From there you can choose OpenVPN and manually enter the settings. You can also choose to import [[#The client configuration file]], if you have already created one. Yet, be aware NetworkManager does not show error messages for options it does not import. To connect to the VPN simply turn the connection on and check the options are applied as you configured (e.g. via {{ic|journalctl -b --u NetworkManager}}).<br />
<br />
== Routing all client traffic through the server ==<br />
<br />
{{Note|There are potential pitfalls when routing all traffic through a VPN server. Refer to [http://openvpn.net/index.php/open-source/documentation/howto.html#redirect the OpenVPN documenation on this topic] for more information.}}<br />
<br />
By default only traffic directly to and from an OpenVPN server passes through the VPN. To have all traffic, including web traffic, pass through the VPN do the following. First add the following to your server's configuration file (i.e., {{ic|/etc/openvpn/server.conf}}) [http://openvpn.net/index.php/open-source/documentation/howto.html#redirect]:<br />
<br />
push "redirect-gateway def1 bypass-dhcp"<br />
push "dhcp-option DNS 10.8.0.1"<br />
<br />
Change {{ic|10.8.0.1}} to your preferred DNS IP address.<br />
<br />
If you have problems with non responsive DNS after connecting to server, install [[BIND]] as simple DNS forwarder and push the IP address of the OpenVPN server as DNS to clients.<br />
<br />
Additionally, if you want to allow clients to be able to reach other (private) subnets behind the server, you may want to use the {{ic|push "route <address pool> <subnet>"}} option:<br />
<br />
push "route 172.10.142.0 255.255.255.0"<br />
push "route 172.20.142.0 255.255.255.0"<br />
<br />
After setting up your configuration file, you need to [[Internet_sharing#Enable_packet_forwarding|enable packet forwarding]] on the server. Additionally, your server's firewall will need to be set up to allow VPN traffic through it, which is described below for both [[ufw]] and [[iptables]].<br />
<br />
=== Firewall configuration ===<br />
<br />
==== ufw ====<br />
<br />
In order to configure your ufw settings for VPN traffic first add the following to {{ic|/etc/default/ufw}}:<br />
<br />
{{hc|/etc/default/ufw|2=<br />
DEFAULT_FORWARD_POLICY="ACCEPT"<br />
}}<br />
<br />
Now change {{ic|/etc/ufw/before.rules}}, and add the following code after the header and before the "*filter" line. Do not forget to change the IP/subnet mask to match the one in {{ic|/etc/openvpn/server.conf}}. The adapter ID in the example is generically called {{ic|eth0}} so edit it for your system accordingly.<br />
<br />
{{hc|/etc/ufw/before.rules|2=<br />
# NAT (Network Address Translation) table rules<br />
*nat<br />
:POSTROUTING ACCEPT [0:0]<br />
<br />
# Allow traffic from clients to eth0<br />
-A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE<br />
<br />
# do not delete the "COMMIT" line or the NAT table rules above will not be processed<br />
COMMIT<br />
}}<br />
<br />
Open OpenVPN port 1194:<br />
<br />
# ufw allow 1194<br />
<br />
Lastly, reload UFW:<br />
<br />
# ufw reload<br />
<br />
==== iptables ====<br />
<br />
In order to allow VPN traffic through your iptables firewall of your server, first create an iptables rule for NAT forwarding [http://openvpn.net/index.php/open-source/documentation/howto.html#redirect] on the server, assuming the interface you want to forward to is named {{ic|eth0}}:<br />
<br />
iptables -t nat -A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE<br />
<br />
If you have difficulty pinging the server through the VPN, you may need to add explicit rules to open up TUN/TAP interfaces to all traffic. If that is the case, do the following [https://community.openvpn.net/openvpn/wiki/255-qconnection-initiated-with-xxxxq-but-i-cannot-ping-the-server-through-the-vpn]:<br />
<br />
{{Warning|There are security implications for the following rules if you do not trust all clients which connect to the server. Refer to the [https://community.openvpn.net/openvpn/wiki/255-qconnection-initiated-with-xxxxq-but-i-cannot-ping-the-server-through-the-vpn OpenVPN documentation on this topic] for more details.}}<br />
<br />
iptables -A INPUT -i tun+ -j ACCEPT<br />
iptables -A FORWARD -i tun+ -j ACCEPT<br />
iptables -A INPUT -i tap+ -j ACCEPT<br />
iptables -A FORWARD -i tap+ -j ACCEPT<br />
<br />
Additionally be sure to accept connections from the OpenVPN port (default 1194) and through the physical interface.<br />
<br />
When you are satisfied make the changes permanent as shown in [[iptables#Configuration and usage]].<br />
<br />
=== Prevent leaks if vpn goes down ===<br />
<br />
The idea is simple: prevent all traffic through our default interface (enp3s0 for example) and only allow tun0.<br />
If the openvpn connection drops, your computer will lose its internet access and therefore, avoid your programs to continue connecting through an insecure network adapter.<br />
<br />
Be sure to set up a script to restart openvpn if it goes down if you do not want to manually restart it.<br />
<br />
==== ufw ====<br />
<br />
# Default policies<br />
ufw default deny incoming<br />
ufw default deny outgoing<br />
<br />
# Openvpn interface (adjust interface accordingly to your configuration)<br />
ufw allow in on tun0<br />
ufw allow out on tun0<br />
<br />
# Local Network (adjust ip accordingly to your configuration)<br />
ufw allow in on enp3s0 from 192.168.1.0/24<br />
ufw allow out on enp3s0 to 192.168.1.0/24<br />
<br />
# Openvpn (adjust port accordingly to your configuration)<br />
ufw allow out on enp3s0 to any port 1194<br />
ufw allow in on enp3s0 from any port 1194<br />
<br />
{{Warning| DNS '''will not''' work '''unless''' you run your own dns server like [[BIND]]<br />
Otherwise, you will need to allow dns leak. '''Be sure to trust your dns server!'''<br />
# DNS<br />
ufw allow in from any to any port 53<br />
ufw allow out from any to any port 53<br />
}}<br />
<br />
== L3 IPv4 routing==<br />
<br />
This section describes how to connect client/server LANs to each other using L3 IPv4 routing.<br />
<br />
=== Prerequisites for routing a LAN ===<br />
<br />
For a host to be able to forward IPv4 packets between the LAN and VPN, it must be able to forward the packets between its NIC and its tun/tap device. See [[Internet sharing#Enable packet forwarding]] for configuration details.<br />
<br />
==== Routing tables ====<br />
<br />
{{Accuracy|Investigate if a routing protocol like RIP, QUAGGA, BIRD, etc can be used}}<br />
<br />
By default, all IP packets on a LAN addressed to a different subnet get sent to the default gateway. If the LAN/VPN gateway is also the default gateway, there is no problem and the packets get properly forwarded. If not, the gateway has no way of knowing where to send the packets. There are a couple of solutions to this problem.<br />
<br />
* Add a static route to the default gateway routing the VPN subnet to the LAN/VPN gateway's IP address.<br />
* Add a static route on each host on the LAN that needs to send IP packets back to the VPN.<br />
* Use [[iptables]]' NAT feature on the LAN/VPN gateway to masquerade the incoming VPN IP packets.<br />
<br />
=== Connect the server LAN to a client ===<br />
<br />
The server is on a LAN using the 10.66.0.0/24 subnet. To inform the client about the available subnet, add a push directive to the server configuration file:{{hc|/etc/openvpn/server.conf|push "route 10.66.0.0 255.255.255.0"}}<br />
<br />
{{Note|To route more LANs from the server to the client, add more push directives to the server configuration file, but keep in mind that the server side LANs will need to know how to route to the client.<br />
}}<br />
<br />
=== Connect the client LAN to a server ===<br />
<br />
Prerequisites:<br />
<br />
* Any subnets used on the client side, must be unique and not in use on the server or by any other client. In this example we will use 192.168.4.0/24 for the clients LAN.<br />
* Each client's certificate has a unique Common Name, in this case bugs.<br />
* The server may not use the duplicate-cn directive in its config file.<br />
<br />
Create a client configuration directory on the server. It will be searched for a file named the same as the client's common name, and the directives will be applied to the client when it connects.<br />
<br />
# mkdir -p /etc/openvpn/ccd<br />
<br />
Create a file in the client configuration directory called bugs, containing the {{ic|iroute 192.168.4.0 255.255.255.0}} directive. It tells the server what subnet should be routed to the client:<br />
<br />
{{hc|/etc/openvpn/ccd/bugs|iroute 192.168.4.0 255.255.255.0}}<br />
<br />
Add the client-config-dir and the {{ic|route 192.168.4.0 255.255.255.0}} directive to the server configuration file. It tells the server what subnet should be routed from the tun device to the server LAN:<br />
<br />
{{hc|/etc/openvpn/server.conf|<br />
client-config-dir ccd<br />
route 192.168.4.0 255.255.255.0<br />
}}<br />
<br />
{{Note|To route more LANs from the client to the server, add more iroute and route directives to the appropriate configuration files, but keep in mind that the client side LANs will need to know how to route to the server.<br />
}}<br />
<br />
=== Connect both the client and server LANs ===<br />
<br />
Combine the two previous sections:<br />
<br />
{{hc|/etc/openvpn/server.conf|<br />
push "route 10.66.0.0 255.255.255.0"<br />
.<br />
.<br />
client-config-dir ccd<br />
route 192.168.4.0 255.255.255.0<br />
}}<br />
<br />
{{hc|/etc/openvpn/ccd/bugs|iroute 192.168.4.0 255.255.255.0}}<br />
<br />
{{Note|Remember to make sure that all the LANs or the needed hosts can route to all the destinations.}}<br />
<br />
=== Connect clients and client LANs ===<br />
<br />
By default clients will not see each other. To allow IP packets to flow between clients and/or client LANs, add a client-to-client directive to the server configuration file: {{hc|/etc/openvpn/server.conf|client-to-client}}<br />
<br />
In order for another client or client LAN to see a specific client LAN, you will need to add a push directive for each client subnet to the server configuration file (this will make the server announce the available subnet(s) to other clients):<br />
<br />
{{hc|/etc/openvpn/server.conf|<br />
client-to-client<br />
push "route 192.168.4.0 255.255.255.0"<br />
push "route 192.168.5.0 255.255.255.0"<br />
.<br />
.<br />
}}<br />
<br />
{{Note|As always, make sure that the routing is properly configured.}}<br />
<br />
== DNS ==<br />
<br />
The DNS servers used by the system are defined in {{ic|/etc/resolv.conf}}. Traditionally, this file is the responsibility of whichever program deals with connecting the system to the network (e.g. Wicd, NetworkManager, etc...) However, OpenVPN will need to modify this file if you want to be able to resolve names on the remote side. To achieve this in a sensible way, install {{pkg|openresolv}}, which makes it possible for more than one program to modify {{ic|resolv.conf}} without stepping on each-other's toes.<br />
<br />
Before continuing, test openresolv by restarting your network connection and ensuring that {{ic|resolv.conf}} states that it was generated by ''resolvconf'', and that your DNS resolution still works as before. You should not need to configure openresolv; it should be automatically detected and used by your network system.<br />
<br />
For Linux, OpenVPN can send DNS host information, but expects an external process to act on it. This can be done with a [https://github.com/masterkorp/openvpn-update-resolv-conf openvpn-update-resolv-conf] script, which can be saved for example at {{ic|/etc/openvpn/update-resolv-conf}} and make it executable with [[chmod]]. There is also an AUR package: {{AUR|openvpn-update-resolv-conf}} which will take care of the script installation for you.<br />
<br />
Once the script is installed add lines like the following into your OpenVPN client configuration file:<br />
<br />
script-security 2<br />
setenv PATH /usr/bin<br />
up /etc/openvpn/update-resolv-conf<br />
down /etc/openvpn/update-resolv-conf<br />
<br />
Now, when your launch your OpenVPN connection, you should find that your resolv.conf file is updated accordingly, and also returns to normal when your close the connection.<br />
<br />
{{Accuracy|The above does not work on shutdown when following [[#Drop root privileges after connecting]].|Talk:OpenVPN#Using resolvconf with user nobody}}<br />
<br />
== L2 Ethernet bridging ==<br />
<br />
{{Expansion|Please add a well thought out section on L2 bridging.}}<br />
<br />
For now see: [[OpenVPN Bridge]]<br />
<br />
== Troubleshooting ==<br />
<br />
=== Resolve issues ===<br />
<br />
If you are having resolve issues when starting your profile:<br />
{{hc|# journalctl _SYSTEMD_UNIT&#61;openvpn@''profile''.service|<br />
RESOLVE: Cannot resolve host address: example.com: Name or service not known<br />
}}<br />
<br />
{{Accuracy|1=Ordering "After=network.target" does not work universally. See [http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget/ network.target]. Further, not the original unit in {{ic|/usr/lib}} should be modified but a copy, cross-referencing [[Systemd#Editing provided units]].}}<br />
Then, '''only if your network setup can be started before OpenVPN''', you should force OpenVPN to wait for the network by adding {{ic|1=Requires=network.target}} and {{ic|1=After=network.target}} to the OpenVPN systemd service file:<br />
{{hc|/usr/lib/systemd/system/openvpn@.service|<nowiki><br />
[Unit]<br />
Description=OpenVPN connection to %i<br />
Requires=network.target<br />
After=network.target<br />
...</nowiki><br />
}}<br />
Do not forget to run {{ic|systemctl daemon-reload}} and [[restart]] {{ic|openvpn@''profile''.service}}.<br />
<br />
=== Client daemon not restarting after suspend ===<br />
<br />
If you put your client system to sleep, and on resume openvpn does not restart, resulting in broken connectivity, create the following file:<br />
<br />
{{hc|/usr/lib/systemd/system-sleep/vpn.sh|2=<br />
#!/bin/sh<br />
if [ "$1" == "pre" ]<br />
then<br />
killall openvpn<br />
fi<br />
}}<br />
<br />
Make it executable {{ic|chmod a+x /usr/lib/systemd/system-sleep/vpn.sh}}<br />
<br />
{{hc|/etc/systemd/system/openvpn@.service.d/restart.conf|2=<br />
[Service]<br />
Restart=always<br />
}}<br />
<br />
=== Connection drops out after some time of inactivity ===<br />
<br />
If the VPN-Connection drops some seconds after it stopped transmitting data and, even though it states it is connected, no data can be transmitted through the tunnel, try adding a {{ic|keepalive}}directive to the server's configuration:<br />
<br />
{{hc|/etc/openvpn/server.conf|<br />
.<br />
.<br />
keepalive 10 120<br />
.<br />
.<br />
}}<br />
<br />
In this case the server will send ping-like messages to all of its clients every {{ic|10}} seconds, thus keeping the tunnel up.<br />
If the server does not receive a response within {{ic|120}} seconds from a specific client, it will assume this client is down.<br />
<br />
A small ping-interval can increase the stability of the tunnel, but will also cause slightly higher traffic. Depending on your connection, also try lower intervals than 10 seconds.<br />
<br />
== See Also ==<br />
* [https://openvpn.net/index.php/open-source.html OpenVPN Official Site]<br />
* [[Airvpn]]</div>Bricewgehttps://wiki.archlinux.org/index.php?title=Systemd-nspawn&diff=411191Systemd-nspawn2015-12-07T17:20:26Z<p>Bricewge: /* use host networking */ Fix the accuracy of the section</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Virtualization]]<br />
[[ja:Systemd-nspawn]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|Linux Containers}}<br />
{{Related|systemd-networkd}}<br />
{{Related|Docker}}<br />
{{Related|Lxc-systemd}}<br />
{{Related articles end}}<br />
<br />
''systemd-nspawn'' is like the [[chroot]] command, but it is a ''chroot on steroids''.<br />
<br />
''systemd-nspawn'' may be used to run a command or OS in a light-weight namespace container. It is more powerful than [[chroot]] since it fully virtualizes the file system hierarchy, as well as the process tree, the various IPC subsystems and the host and domain name.<br />
<br />
''systemd-nspawn'' limits access to various kernel interfaces in the container to read-only, such as {{ic|/sys}}, {{ic|/proc/sys}} or {{ic|/sys/fs/selinux}}. Network interfaces and the system clock may not be changed from within the container. Device nodes may not be created. The host system cannot be rebooted and kernel modules may not be loaded from within the container.<br />
<br />
This mechanism differs from [[Lxc-systemd]] or [[Libvirt]]-lxc, as it is a much simpler tool to configure.<br />
<br />
== Installation ==<br />
<br />
''systemd-nspawn'' is part of and packaged with {{Pkg|systemd}}. <br />
<br />
== Examples ==<br />
<br />
=== Create and boot a minimal Arch Linux distribution in a container ===<br />
<br />
First install {{Pkg|arch-install-scripts}}.<br />
<br />
Next, create a directory to hold the container. In this example we will use {{ic|~/MyContainer}}. <br />
<br />
Next, we use pacstrap to install a basic arch-system into the container. At minimum we need to install the {{Grp|base}} group. <br />
<br />
# pacstrap -i -c -d ~/MyContainer base [additional pkgs/groups]<br />
<br />
{{Tip|The {{ic|-i}} option will '''avoid''' auto-confirmation of package selection. As you do not need to install the Linux kernel in the container, you can remove it from the package list selection to save space. See [[Pacman#Usage]].}}<br />
<br />
{{Note|The package {{Pkg|linux-firmware}} required by {{Pkg|linux}} which is included in the {{Grp|base}} group and it isn't necessary to run the container, causes some issues to {{ic|systemd-tmpfiles-setup.service}} during the booting process with {{ic|systemd-nspawn}}. It's possible to install the {{Grp|base}} group but excluding the {{Pkg|linux}} package and its dependencies when building the container with {{ic|# pacstrap -i -c -d ~/MyContainer base --ignore linux [additional pkgs/groups]}}. The {{ic|--ignore}} flag will be simply passed to {{Pkg|pacman}}. See the next bug report for more information: https://bugs.archlinux.org/task/46591.}}<br />
<br />
Once your installation is finished, boot into the container:<br />
<br />
# systemd-nspawn -b -D ~/MyContainer -n<br />
<br />
The {{ic|-b}} option will boot the container (i.e. run {{ic|systemd}} as PID=1), instead of just running a shell. {{ic|-D}} specifies the directory that becomes the container's root directory and {{ic|-n}} will set up a private network between host and container.<br />
<br />
After the container starts, log in as "root" with no password.<br />
<br />
The container can be powered off by running {{ic|poweroff}} from within the container. From the host, containers can be controlled by the [[#machinectl|machinectl]] tool.<br />
<br />
{{Note|To terminate the ''session'' from within the container, hold {{ic|Ctrl}} and rapidly press {{ic|]}} three times. Non US keyboard will use {{ic|%}} instead of {{ic|]}}}}<br />
<br />
=== Enable Container on boot ===<br />
<br />
If you want to use a container frequently, you can have systemd start it on boot. First you have to enable the {{ic|systemd}} target {{ic|machines.target}}<br />
<br />
# systemctl enable machines.target<br />
<br />
then you can<br />
<br />
# mv ~/MyContainer /var/lib/machines/MyContainer<br />
# systemctl enable systemd-nspawn@MyContainer.service<br />
# systemctl start systemd-nspawn@MyContainer.service<br />
<br />
{{Note| ''systemd-nspawn@.service'' is a template unit that expects nspawn containers to be under {{ic|/var/lib/machines}}.}} <br />
<br />
{{Tip|<br />
* Instead of moving your container, as above, you can just ''symlink'' it to where it is expected to be,<br />
# ln -s ~/MyContainer /var/lib/machines/MyContainer<br />
* To customize the startup of a container, [[systemd#Editing_provided_unit_files|edit]] the {{ic|systemd-nspawn@''MyContainer''}} unit instance. See {{ic|systemd-nspawn(1)}} for all options.<br />
}}<br />
<br />
=== Building and Testing packages ===<br />
<br />
{{Expansion| Please share how systemd-nspawn fits into your build environment}}<br />
<br />
== Management ==<br />
<br />
=== machinectl ===<br />
<br />
Managing your containers is essentially done with the {{ic|machinectl}} command. See {{ic|machinectl(1)}} for more detail then listed here.<br />
<br />
Examples:<br />
<br />
* Spawn a new shell inside a running container: {{bc|$ machinectl login MyContainer}}<br />
* Show detailed information about a container: {{bc|$ machinectl status MyContainer}}<br />
* Reboot a container: {{bc|$ machinectl reboot MyContainer}}<br />
* Poweroff a container: {{bc|$ machinectl poweroff MyContainer}}<br />
<br />
{{Tip|Poweroff and reboot operations can be performed from within a container session using the ''systemctl'' {{ic|poweroff}} or {{ic|reboot}} commands.}}<br />
<br />
=== systemd toolchain ===<br />
<br />
Much of the core systemd toolchain has been updated to work with containers. Tools that do usually provide a {{ic|1=-M, --machine=}} option which will take a container name as argument.<br />
<br />
Examples:<br />
<br />
* See journal logs for a particular machine: {{bc| $ journalctl -M MyContainer}}<br />
* Show control group contents: {{bc|$ systemd-cgls -M MyContainer}}<br />
* See startup time of container: {{bc|$ systemd-analyze -M MyContainer}}<br />
* For an overview of resource usage: {{bc|$ systemd-cgtop}}<br />
<br />
== Tips ==<br />
<br />
=== X environment ===<br />
<br />
See [[Xhost]] and [[Change root#Run graphical applications from chroot]].<br />
<br />
You will need to set the {{ic|DISPLAY}} environment variable inside your container session to connect to the external X server.<br />
<br />
X stores some required files in the {{ic|/tmp}} directory. In order for your container to display anything, it needs access to those files. To do so, append the {{ic|--bind<nowiki>=</nowiki>/tmp/.X11-unix:/tmp/.X11-unix}} option when starting the container.<br />
<br />
=== Run Firefox inside an nspawn container ===<br />
<br />
See [[Firefox tweaks#Run Firefox inside an nspawn container|Firefox tweaks]].<br />
<br />
=== Networking ===<br />
<br />
{{Style}}<br />
<br />
Note the canonical [[systemd-networkd]] host and container .network files are from https://github.com/systemd/systemd/tree/master/network<br />
<br />
You need to set up the container .network manually after pacstrapping and {{ic|# systemctl enable [[systemd-networkd]]}} (your dhcp client) with systemd-nspawn's -n switch to ensure a virtual Ethernet link is setup. Don't forget to set up DNS, e.g. by either 1) edit your container's {{ic|/etc/resolv.conf}} by adding your DNS server's IP address, or have 2) [[systemd-resolved]] manage {{ic|/etc/resolv.conf}} for you.<br />
<br />
See [[systemd-networkd#Usage with containers]] for more complex examples.<br />
<br />
==== nsswitch.conf ====<br />
<br />
{{Merge|systemd-networkd}}<br />
<br />
To make it easier to connect to a container from the host, you can enable local DNS resolution for container names. In {{ic|/etc/nsswitch.conf}}, add {{ic|mymachines}} to the {{ic|hosts:}} section, e.g.<br />
<br />
hosts: files mymachines dns myhostname<br />
<br />
Then, any DNS lookup for hostname {{ic|foo}} on the host will first consult {{ic|/etc/hosts}}, then the names of local containers, then upstream DNS etc.<br />
<br />
==== use host networking ====<br />
<br />
To disable private networking used by containers started with {{ic|machinectl start MyContainer}} edit the configuration of {{ic|systemd-nspawn@.service}} with {{ic|systemctl edit systemd-nspawn@.service}}. And set the {{ic|1=ExecStart=}} option without the {{ic|--network-veth|}} parameter unlike the original service:<br />
<br />
{{hc|/etc/systemd/system/systemd-nspawn@.service.d/override.conf|<nowiki><br />
ExecStart=/usr/bin/systemd-nspawn --quiet --keep-unit --boot --link-journal=try-guest --machine=%I<br />
</nowiki>}}<br />
<br />
The newly started containers will use the hosts networking.<br />
<br />
==== Virtual Ethernet interfaces ====<br />
<br />
If a container is started with {{ic|systemd-nspawn ... -n}}, systemd will automatically create one virtual Ethernet interface on the host, and one in the container, connected by a virtual Ethernet cable.<br />
<br />
If the name of the container is {{ic|foo}}, the name of the virtual Ethernet interface on the host is {{ic|ve-foo}}. The name of the virtual Ethernet interface in the container is always {{ic|host0}}.<br />
<br />
When examining the interfaces with {{ic|ip link}}, interface names will be shown with a suffix, such as {{ic|ve-foo@if2}} and {{ic|host0@if9}}. The {{ic|@ifN}} is not actually part of the name of the interface; instead, {{ic|ip link}} appends this information to indicate which "slot" the virtual Ethernet cable connects to on the other end.<br />
<br />
For example, a host virtual Ethernet interface shown as {{ic|ve-foo@if2}} will connect to container {{ic|foo}}, and inside the container to the second network interface -- the one shown with index 2 when running {{ic|ip link}} inside the container. Similarly, in the container, the interface named {{ic|host0@if9}} will connect to the 9th slot on the host.<br />
<br />
=== Running on a non-systemd system ===<br />
<br />
See [[Init#systemd-nspawn]].<br />
<br />
==Troubleshooting ==<br />
<br />
=== root login fails ===<br />
<br />
If you get the following error when you try to login (i.e. using {{ic|machinectl login <name>}}):<br />
<br />
arch-nspawn login: root<br />
Login incorrect<br />
<br />
And {{ic|journalctl}} shows:<br />
<br />
pam_securetty(login:auth): access denied: tty 'pts/0' is not secure !<br />
<br />
Add {{ic|pts/0}} to the list of terminal names in {{ic|/etc/securetty}} on the '''container''' filesystem, see [http://unix.stackexchange.com/questions/41840/effect-of-entries-in-etc-securetty/41939#41939]. You can also opt to delete {{ic|/etc/securetty}} on the '''container''' to allow always root to login, see [https://github.com/systemd/systemd/issues/852].<br />
<br />
== See also ==<br />
<br />
* [http://www.freedesktop.org/software/systemd/man/machinectl.html machinectl man page]<br />
* [http://www.freedesktop.org/software/systemd/man/systemd-nspawn.html systemd-nspawn man page]<br />
* [http://lwn.net/Articles/572957/ Creating containers with systemd-nspawn]<br />
* [https://www.youtube.com/results?search_query=systemd-nspawn&aq=f Presentation by Lennart Pottering on systemd-nspawn]<br />
* [http://dabase.com/e/12009/ Running Firefox in a systemd-nspawn container]</div>Bricewgehttps://wiki.archlinux.org/index.php?title=Termite&diff=410843Termite2015-12-03T23:56:28Z<p>Bricewge: removed "Ctrl-T not working" part as it isn't related to termite</p>
<hr />
<div>[[Category:Terminal emulators]]<br />
[[ja:Termite]]<br />
[https://www.github.com/thestinger/termite Termite] is a minimal [[:Category:Terminal emulators|terminal emulator]] designed for use with tiling [[window manager]]s. It is a ''modal'' application, similar to [[Vim]], with an insert mode and command mode where keybindings have different functions. Termite is based on the [https://developer.gnome.org/vte/unstable/ VTE] library.<br />
<br />
The configuration file allows to change colors and set some options. Termite supports transparency along with both the 256 color and true color (16 million colors) palettes. It has a similar look and feel to [[urxvt]].<br />
<br />
== Installation ==<br />
<br />
Install the {{Pkg|termite}} package, or {{AUR|termite-git}} for the development version.<br />
<br />
== Usage ==<br />
<br />
Termite starts in insert mode by default. Text may be selected using the mouse, or by using command-mode keys. In insert mode, {{ic|Ctrl-Shift-c}} is used to copy selected text to the [[X]] clipboard, {{ic|Ctrl-Shift-v}} to paste. {{ic|Ctrl-tab}} starts scrollback completion, and {{ic|Ctrl-Shift-up}} / {{ic|Ctrl-Shift-down}} scroll the screen up or down.<br />
<br />
{{ic|Ctrl-Shift-space}} enters command-mode. Many commands are borrowed from [[Vim]], for example {{ic|v}} for visual mode, {{ic|Shift-v}} for visual line mode, {{ic|Ctrl-v}} for visual block mode, {{ic|y}} to copy ("yank") selected text, {{ic|/}} and {{ic|?}} for searching, {{ic|w}}, {{ic|b}}, {{ic|^}}, {{ic|$}} for movement, and {{ic|Escape}} to go back to insert mode.<br />
<br />
== Configuration ==<br />
Termite looks for configuration files in {{ic|$XDG_CONFIG_HOME/termite/config}}, {{ic|~/.config/termite/config}}, {{ic|$XDG_CONFIG_DIRS/termite/config}} and {{ic|/etc/xdg/termite.cfg}}. The configuration file is used to change options such as font, colors, window hints, etc. The configuration file is in ''ini'' format, with three sections: ''options'', ''colors'', and ''hints''.<br />
<br />
=== Font ===<br />
Fonts are specified in the format {{ic|1=font=<font_name> <font_size>}} under the ''options'' section. {{ic|<font_name>}} is specified according to [[fontconfig]], not [[X Logical Font Description|Xft]]. Use {{ic|fc-list}} to see which fonts are available on the system (see also [[Font configuration#Font paths]]).<br />
<br />
{{hc|~/.config/termite/config|2=<br />
[options]<br />
font = Monospace 9<br />
font = Terminus (TTF) 8<br />
font = Droid Sans Mono 8}}<br />
<br />
=== Colors ===<br />
Colors consist of either a 24-bit hex value (e.g. {{ic|#4a32b1}}), or an rgba vector (e.g. {{ic|rgba(16, 32, 64, 0.5)}}). Valid properties for colors are {{ic|foreground}}, {{ic|foreground_bold}}, {{ic|foreground_dim}}, {{ic|background}}, {{ic|cursor}}, and {{ic|colorN}} (where N is an integer from zero through 254; used to assign a 24-bit color value to terminal colorN).<br />
<br />
{{hc|~/.config/termite/config|2=<br />
[colors]<br />
foreground = #dcdccc<br />
background = #3f3f3f}}<br />
<br />
== Transparency ==<br />
As of version 9, Termite supports true transparency via color definitions that specify an alpha channel value [https://github.com/thestinger/termite/issues/191]. This requires a compositor to be running, such as [[Compton]] or {{pkg|xcompmgr}}. Most compositors do not require special configuration for Termite to use transparency.<br />
<br />
{{hc|~/.config/termite/config|2=<br />
[colors]<br />
background = rgba(63, 63, 63, 0.8)<br />
}}<br />
<br />
{{Note|In [[i3]], in stacked/tabbed layout, this shows all windows "stacked" on top of each other, in the order they were most recently in the foreground, rather than showing the desktop (the root window) directly behind Termite. This is due to i3 reordering windows rather than hiding invisible windows in tiling mode. You can configure your compositor to make windows with {{ic|1=_NET_WM_STATE=_NET_WM_STATE_HIDDEN}} fully transparent to solve this. For example, for compton use<br />
{{hc|head=~/.compton.conf|output=opacity-rule = [<br />
"0:_NET_WM_STATE@:32a *= '_NET_WM_STATE_HIDDEN'"<br />
];}}<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Colored ls output ===<br />
<br />
{{Deletion|1=This bug should have been [http://git.savannah.gnu.org/gitweb/?p=coreutils.git;a=commitdiff;h=a960c31 fixed] on 2015-10-02, and be available with the next {{Pkg|coreutils}} release.|section=Colored ls output}}<br />
<br />
For colored {{ic|ls}} output it is necessary to use a custom LS_COLORS [[environment variable]], which can be set with a {{ic|dircolors}} file. Generate one with:<br />
<br />
$ dircolors -p > ~/.dircolors<br />
<br />
Then edit {{ic|~/.dircolors}} file, and append<br />
<br />
TERM xterm-termite<br />
<br />
to the end of the list of terminals, and save the file.<br />
<br />
For [[Bash]] in {{ic|~/.bashrc}} and [[Zsh]] in {{ic|~/.zshrc}}, add:<br />
<br />
eval $(dircolors ~/.dircolors)<br />
<br />
and restart the terminal. For [[fish]], add <br />
<br />
eval (dircolors -c ~/.dircolors | sed 's/>&\/dev\/null$//')<br />
<br />
to {{ic|~/.config/fish/config.fish}} and relogin or reload the config via:<br />
<br />
. ~/.config/fish/config.fish<br />
<br />
<br />
== See also ==<br />
<br />
* [https://github.com/thestinger/termite/blob/master/README.rst Termite readme]</div>Bricewgehttps://wiki.archlinux.org/index.php?title=VDPAU&diff=381129VDPAU2015-07-06T12:13:41Z<p>Bricewge: /* Configuration */ tweak</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X Server]]<br />
[[ru:VDPAU]]<br />
[[ja:VDPAU]]<br />
[[zh-CN:VDPAU]]<br />
{{Related articles start}}<br />
{{Related|VA-API}}<br />
{{Related|XvMC}}<br />
{{Related articles end}}<br />
<br />
'''[http://http.download.nvidia.com/XFree86/vdpau/doxygen/html/ Video Decode and Presentation API for Unix]''' is an open source library and API to offload portions of the video decoding process and video post-processing to the GPU video-hardware.<br />
<br />
== Supported hardware ==<br />
<br />
'''Open source drivers:'''<br />
<br />
* [[ATI|AMD]] Radeon 9500 and newer GPUs are supported by the {{Pkg|mesa-vdpau}} package, available in the [[official repositories]].<br />
* [[Intel]] GMA 4500 series and newer GPUs are supported by the {{Pkg|libvdpau-va-gl}} package together with the {{pkg|libva-intel-driver}}.<br />
* [[Nouveau|NVIDIA]] GeForce 8 series and newer GPUs are supported by the {{Pkg|mesa-vdpau}} package, available in the official repositories. It [http://nouveau.freedesktop.org/wiki/VideoAcceleration/#firmware requires] the {{AUR|nouveau-fw}} package, which contains the required firmware to operate that is presently extracted from the NVIDIA binary driver.<br />
<br />
'''Proprietary drivers:'''<br />
<br />
* [[AMD Catalyst|AMD]] Radeon HD 4000 series and newer GPUs are supported by the {{Pkg|libvdpau-va-gl}} package (available in the official repositories) together with the {{AUR|libva-xvba-driver}} package. It uses the {{AUR|catalyst-utils}} driver for Radeon HD 5000 series and newer, and {{AUR|catalyst-total-hd234k}} for Radeon HD 4000 series.<br />
* [[NVIDIA]] GeForce 400 series and newer GPUs are supported by the {{Pkg|nvidia-utils}} package, available in the official repositories.<br />
** GeForce 8/9 and GeForce 100-300 series are supported by the {{Pkg|nvidia-340xx-utils}} package.<br />
<br />
=== Supported formats ===<br />
<br />
{| class="wikitable" style="width: 100%"<br />
! <br />
! colspan="3" | Open source<br />
! colspan="2" | Proprietary<br />
|-<br />
! <br />
! AMD<br />
! Intel<br />
! Nvidia<br />
! AMD<br />
! Nvidia<br />
|-<br />
| MPEG2 decoding<br />
| Radeon 9500 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 8 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 8 and newer<br />
|-<br />
| MPEG4 decoding<br />
| Radeon HD 6000 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 200 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 200 and newer<br />
|-<br />
| H.264 decoding<br />
| Radeon HD 4000 and newer<br />
| GMA 4500<sup>1</sup>, Ironlake Graphics and newer<br />
| GeForce 8 and newer<br />
| Radeon HD 4000 and newer<br />
| GeForce 8 and newer<br />
|-<br />
| H.265 decoding<br />
| <center>—</center><br />
| <center>—<sup>2</sup></center><br />
| <center>—</center><br />
| <center>—<sup>2</sup></center><br />
| GeForce 900<sup>4</sup> and newer<br />
|-<br />
| VC1 decoding<br />
| Radeon HD 4000 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 8<sup>3</sup> and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 8<sup>3</sup> and newer<br />
|}<br />
<br />
* <sup>1</sup> Supported by the {{AUR|libva-intel-driver-g45-h264}} package, which is available in the AUR. See [[Intel graphics#H.264 decoding on GMA 4500]] for instructions and caveats.<br />
* <sup>2</sup> As of version 0.3, the VA GL driver doesn't support any other hardware decoder than H.264.<br />
* <sup>3</sup> [[Wikipedia:Nvidia PureVideo|Except]] GeForce 8800 Ultra, 8800 GTX, 8800 GTS (320/640 MB).<br />
* <sup>4</sup> Except GeForce GTX 970 and GTX 980.<br />
<br />
In order to check what features are supported by your GPU, run the following command, which is provided by the {{Pkg|vdpauinfo}} package:<br />
<br />
$ vdpauinfo<br />
<br />
=== Configuration ===<br />
<br />
The environment variable {{ic|VDPAU_DRIVER}} determines the driver file used. You can enable the [[environment variable]] [[Environment variables#Globally|globally]] or [[Environment variables#Per_user|locally per user]].<br />
<br />
The correct driver name depends on your setup:<br />
<br />
* For Intel Graphics or AMD Catalyst you need to set it to {{ic|va_gl}}.<br />
* For the open source AMD/ATI driver, you need to set it to the proper driver version depending on your GPU.<br />
<br />
You can determine the driver name by running:<br />
{{hc|$ grep -i vdpau ~/.local/share/xorg/Xorg.0.log|<br />
(II) RADEON(0): [DRI2] VDPAU driver: r300<br />
}}<br />
In which case you want to set {{ic|1=VDPAU_DRIVER=r300}}.<br />
<br />
==== Hybrid graphics ====<br />
<br />
For hybrid setups (both NVIDIA and AMD), it may be necessary to set following environment variable:<br />
<br />
$ export DRI_PRIME=1<br />
<br />
For more information, see the [[PRIME]] wiki page.<br />
<br />
== Supported software ==<br />
<br />
* {{App|Adobe Flash Player|see [[Browser plugins#Adobe Flash Player]].||{{Pkg|flashplugin}}}}<br />
* {{App|[[MPlayer]] or [http://www.mplayer2.org/ mplayer2]|see [[MPlayer#Enabling VDPAU]].|| {{Pkg|mplayer}} {{Aur|mplayer2}}}}<br />
* {{App|gnome-mplayer|To enable hardware acceleration: ''Edit > Preferences > Player'', then set Video Output to {{ic|vdpau}}.||{{Pkg|gnome-mplayer}}}}<br />
* {{App|[[SMplayer]]|To enable hardware acceleration: ''Options > Preferences > General > Video'', then set Output driver to {{ic|vdpau}}.||{{Pkg|smplayer}}}}<br />
* {{App|bomi|Hardware acceleration can be enabled: ''Preferences > Video > Hardware acceleration''.|https://bomi-player.github.io|{{Aur|bomi}} {{Aur|bomi-git}}}}<br />
* {{App|[[Mpv]]|see [[Mpv#Hardware Decoding]].||{{Pkg|mpv}}}}<br />
* {{App|[[VLC media player]]|see [[VLC media player#Hardware acceleration support]].||{{Pkg|vlc}}}}</div>Bricewgehttps://wiki.archlinux.org/index.php?title=VDPAU&diff=381128VDPAU2015-07-06T12:08:06Z<p>Bricewge: /* Configuration */ Fix wiki links</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X Server]]<br />
[[ru:VDPAU]]<br />
[[ja:VDPAU]]<br />
[[zh-CN:VDPAU]]<br />
{{Related articles start}}<br />
{{Related|VA-API}}<br />
{{Related|XvMC}}<br />
{{Related articles end}}<br />
<br />
'''[http://http.download.nvidia.com/XFree86/vdpau/doxygen/html/ Video Decode and Presentation API for Unix]''' is an open source library and API to offload portions of the video decoding process and video post-processing to the GPU video-hardware.<br />
<br />
== Supported hardware ==<br />
<br />
'''Open source drivers:'''<br />
<br />
* [[ATI|AMD]] Radeon 9500 and newer GPUs are supported by the {{Pkg|mesa-vdpau}} package, available in the [[official repositories]].<br />
* [[Intel]] GMA 4500 series and newer GPUs are supported by the {{Pkg|libvdpau-va-gl}} package together with the {{pkg|libva-intel-driver}}.<br />
* [[Nouveau|NVIDIA]] GeForce 8 series and newer GPUs are supported by the {{Pkg|mesa-vdpau}} package, available in the official repositories. It [http://nouveau.freedesktop.org/wiki/VideoAcceleration/#firmware requires] the {{AUR|nouveau-fw}} package, which contains the required firmware to operate that is presently extracted from the NVIDIA binary driver.<br />
<br />
'''Proprietary drivers:'''<br />
<br />
* [[AMD Catalyst|AMD]] Radeon HD 4000 series and newer GPUs are supported by the {{Pkg|libvdpau-va-gl}} package (available in the official repositories) together with the {{AUR|libva-xvba-driver}} package. It uses the {{AUR|catalyst-utils}} driver for Radeon HD 5000 series and newer, and {{AUR|catalyst-total-hd234k}} for Radeon HD 4000 series.<br />
* [[NVIDIA]] GeForce 400 series and newer GPUs are supported by the {{Pkg|nvidia-utils}} package, available in the official repositories.<br />
** GeForce 8/9 and GeForce 100-300 series are supported by the {{Pkg|nvidia-340xx-utils}} package.<br />
<br />
=== Supported formats ===<br />
<br />
{| class="wikitable" style="width: 100%"<br />
! <br />
! colspan="3" | Open source<br />
! colspan="2" | Proprietary<br />
|-<br />
! <br />
! AMD<br />
! Intel<br />
! Nvidia<br />
! AMD<br />
! Nvidia<br />
|-<br />
| MPEG2 decoding<br />
| Radeon 9500 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 8 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 8 and newer<br />
|-<br />
| MPEG4 decoding<br />
| Radeon HD 6000 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 200 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 200 and newer<br />
|-<br />
| H.264 decoding<br />
| Radeon HD 4000 and newer<br />
| GMA 4500<sup>1</sup>, Ironlake Graphics and newer<br />
| GeForce 8 and newer<br />
| Radeon HD 4000 and newer<br />
| GeForce 8 and newer<br />
|-<br />
| H.265 decoding<br />
| <center>—</center><br />
| <center>—<sup>2</sup></center><br />
| <center>—</center><br />
| <center>—<sup>2</sup></center><br />
| GeForce 900<sup>4</sup> and newer<br />
|-<br />
| VC1 decoding<br />
| Radeon HD 4000 and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 8<sup>3</sup> and newer<br />
| <center>—<sup>2</sup></center><br />
| GeForce 8<sup>3</sup> and newer<br />
|}<br />
<br />
* <sup>1</sup> Supported by the {{AUR|libva-intel-driver-g45-h264}} package, which is available in the AUR. See [[Intel graphics#H.264 decoding on GMA 4500]] for instructions and caveats.<br />
* <sup>2</sup> As of version 0.3, the VA GL driver doesn't support any other hardware decoder than H.264.<br />
* <sup>3</sup> [[Wikipedia:Nvidia PureVideo|Except]] GeForce 8800 Ultra, 8800 GTX, 8800 GTS (320/640 MB).<br />
* <sup>4</sup> Except GeForce GTX 970 and GTX 980.<br />
<br />
In order to check what features are supported by your GPU, run the following command, which is provided by the {{Pkg|vdpauinfo}} package:<br />
<br />
$ vdpauinfo<br />
<br />
=== Configuration ===<br />
<br />
The environment variable {{ic|VDPAU_DRIVER}} determines the driver file used. You can enable the [[environment variable]] [[Environment variables#Globally|globally]] or [[Environment variables#Per_user|locally per user]].<br />
<br />
The correct driver name depends on your setup:<br />
<br />
* For Intel Graphics or AMD Catalyst you need to set it to {{ic|va_gl}}.<br />
* For the open source AMD/ATI driver, you need to set it to the proper driver version depending on your GPU. You can determine the driver name by running<br />
<br />
{{hc|$ grep -i vdpau ~/.local/share/xorg/Xorg.0.log|<br />
(II) RADEON(0): [DRI2] VDPAU driver: r300<br />
}}<br />
<br />
in which case you want to set {{ic|1=VDPAU_DRIVER=r300}}<br />
<br />
==== Hybrid graphics ====<br />
<br />
For hybrid setups (both NVIDIA and AMD), it may be necessary to set following environment variable:<br />
<br />
$ export DRI_PRIME=1<br />
<br />
For more information, see the [[PRIME]] wiki page.<br />
<br />
== Supported software ==<br />
<br />
* {{App|Adobe Flash Player|see [[Browser plugins#Adobe Flash Player]].||{{Pkg|flashplugin}}}}<br />
* {{App|[[MPlayer]] or [http://www.mplayer2.org/ mplayer2]|see [[MPlayer#Enabling VDPAU]].|| {{Pkg|mplayer}} {{Aur|mplayer2}}}}<br />
* {{App|gnome-mplayer|To enable hardware acceleration: ''Edit > Preferences > Player'', then set Video Output to {{ic|vdpau}}.||{{Pkg|gnome-mplayer}}}}<br />
* {{App|[[SMplayer]]|To enable hardware acceleration: ''Options > Preferences > General > Video'', then set Output driver to {{ic|vdpau}}.||{{Pkg|smplayer}}}}<br />
* {{App|bomi|Hardware acceleration can be enabled: ''Preferences > Video > Hardware acceleration''.|https://bomi-player.github.io|{{Aur|bomi}} {{Aur|bomi-git}}}}<br />
* {{App|[[Mpv]]|see [[Mpv#Hardware Decoding]].||{{Pkg|mpv}}}}<br />
* {{App|[[VLC media player]]|see [[VLC media player#Hardware acceleration support]].||{{Pkg|vlc}}}}</div>Bricewgehttps://wiki.archlinux.org/index.php?title=Emacs&diff=365055Emacs2015-03-11T17:25:30Z<p>Bricewge: added systemd syntax highlighting extensions</p>
<hr />
<div>[[Category:Development]]<br />
[[Category:Text editors]]<br />
[[de:Emacs]]<br />
[[fr:Emacs]]<br />
[[ja:Emacs]]<br />
[[sr:Emacs]]<br />
[[zh-CN:Emacs]]<br />
[[Wikipedia:Emacs|Emacs]] is an extensible, customizable, self-documenting real-time display editor. At the core of Emacs lies an [[Wikipedia:Emacs Lisp|Emacs Lisp]] interpreter, the language in which the majority of Emacs' built-in functionality and extensions are implemented. GTK is the default X toolkit used as of GNU Emacs 22, though it functions equally well within a CLI environment. The text-editing capabilities of Emacs are often compared to that of [[vim]].<br />
<br />
== Installation ==<br />
<br />
Emacs comes in several variants (sometimes referred to as ''emacsen''). The most common of these is [http://www.gnu.org/software/emacs/ GNU Emacs].<br />
<br />
[[pacman|Install]] {{Pkg|emacs}}, available in the [[official repositories]]. If you usually work in a terminal, you may prefer the {{Pkg|emacs-nox}} variant without GTK+ (nor sound and other fancy stuff).<br />
Be aware that the text version comes with some drawbacks: it supports less colors and less features for font handling (size change in live, various sizes in one document, and so on). Besides, emacs-nox has some limitation with advanced features like the Speedbar or GUD (the debugging environment), and is somewhat slower when handling complex faces (a "face" is the visual appearance of text in Emacs).<br />
<br />
If you want to fully enjoy all the extended features of Emacs without installing a daunting amount of dependencies, you can use the PKGBUILD to customize your needs. Using anything else than {{ic|gtk3}} you can get rid of gconf. Image and sound support can be disabled as well. Run {{ic|./configure --help}} in Emacs source folder to list all available options.<br />
{{hc|PKGBUILD|<nowiki><br />
# ...<br />
./configure --prefix=/usr --sysconfdir=/etc --libexecdir=/usr/lib \<br />
--localstatedir=/var --with-x-toolkit=gtk2 --with-xft \<br />
--without-gconf --without-sound<br />
# ...<br />
</nowiki>}}<br />
<br />
Another common variant is {{Pkg|xemacs}}.<br />
<br />
== Running Emacs ==<br />
<br />
Before launching emacs, you should know how to close it (especially if you run it in a terminal): use the<br />
{{ic|Ctrl+x}}{{ic|Ctrl+c}} key sequence.<br />
<br />
=== Normal way ===<br />
<br />
To start Emacs run:<br />
<br />
$ emacs<br />
<br />
or, to use it from the console:<br />
<br />
$ emacs -nw<br />
<br />
or, for fast loading (no .emacs) and editing within CLI:<br />
<br />
$ emacs -Q -nw<br />
<br />
If you installed the nox version, 'emacs' and 'emacs -nw' will be the same.<br />
<br />
A file name can also be provided to open that file immediately:<br />
<br />
$ emacs filename.txt<br />
<br />
=== No Colors ===<br />
<br />
By default, Emacs starts with a color theme showing hyperlinks in dark blue. To start Emacs without any color theme or scheme:<br />
<br />
$ emacs -nw --color=no<br />
<br />
This will cause all text to appear in white color only.<br />
<br />
=== As a daemon ===<br />
<br />
{{Style|For most purposes this could be described in two sentences}}<br />
<br />
Emacs can take some time to start since it has to load the {{ic|.emacs}} file each time. Besides, you may want to access the same files from different instances. Since version 23, Emacs is able to run as a daemon to which users can connect. To run Emacs as a daemon:<br />
<br />
$ emacs --daemon<br />
<br />
You are likely to start the daemon at startup time and to connect a window to the daemon. Besides, it is possible to connect ''both'' graphical and console clients to the daemon at the same time and make the GUI to start quickly.<br />
<br />
If you want to connect to the daemon simply use the following command (note that it will start a graphical client if called in a graphical environment or a console client if called in a console like a tty):<br />
<br />
$ emacsclient<br />
<br />
If you merely want a console client despite being in a graphical environment then use:<br />
<br />
$ emacsclient -t<br />
<br />
Furthermore, you can add the {{ic|-a ""}} parameter.<br />
Now, the first time you call the command, it will start emacs as a daemon, so that it remains running in background and so improving startup times for future calls (and to remember buffers as well).<br />
<br />
If you start the client from a terminal or another program, you may want not to wait for it to return, so that you can continue using the calling program and even close it without closing the Emacs client.<br />
To do so, start the client with the {{ic|-n}} ({{ic|--no-wait}}) parameter:<br />
<br />
$ emacsclient -nc<br />
<br />
Note that some programs such as Mutt or Git (for commit messages) wait for the editor to finish, so you cannot use the {{ic|-n}} parameter.<br />
If your default editor is set to use it, you will have to specify an alternate editor (''e.g.'' {{ic|emacsclient -a "" -t}}) for those programs.<br />
<br />
You could use the following shell configuration:<br />
<br />
{{bc|1=<br />
alias em='emacsclient -nc -a ""'<br />
alias emc='emacsclient -t -a ""'<br />
EDITOR='emacsclient -a ""'<br />
}}<br />
but it has some caveats: many program will fail to load the external editor because of the spaces in the command.<br />
<br />
A more convenient and reliable solution is to write your own script:<br />
{{hc|/usr/local/bin/em|<nowiki><br />
#!/bin/sh<br />
if [ -z "$DISPLAY" ]; then<br />
IS_GRAPHICAL=true<br />
else<br />
IS_GRAPHICAL=$(emacs --batch -Q --eval='(if (fboundp '"'"'tool-bar-mode) (message "true") (message "false"))' 2>&1)<br />
fi<br />
<br />
if $IS_GRAPHICAL; then<br />
emacsclient -a "" -nc "$@"<br />
else<br />
emacsclient -a "" -t "$@"<br />
fi<br />
</nowiki>}}<br />
then make it executable:<br />
# chmod 755 /usr/local/bin/em<br />
<br />
Now 'em' will work just as expected. Setting the {{ic|EDITOR}} environment variable to the aforementionned script should suffice to make the client be your defaut editor.<br />
<br />
==== Alternative method ====<br />
<br />
You may find that typing "em filename.c" could be easily mistyped as "rm filename.c", so you may prefer to use "emc" (read "emacs client") instead of "em". Non-X Emacs should be used when emc is called from terminal, whether you are in X or not. Another thing, Emacs daemon also complains about the "long standing Gtk bug". That bug can be avoid by telling the Emacs daemon that there is no DISPLAY. So, here is another alternative:<br />
<br />
{{hc|/usr/local/bin/emc|<nowiki><br />
#!/bin/sh<br />
ps aux | grep 'emacs *--daemon' || DISPLAY='' emacs --daemon -nw --no-splash<br />
<br />
if [ "x$1" = "x-nw" ]; then<br />
exec emacsclient "$@"<br />
else<br />
exec emacsclient -nc "$@"<br />
fi<br />
</nowiki>}}<br />
<br />
And create an alias in the interactive shell script<br />
<br />
{{hc|$HOME/.zshrc or $HOME/.bashrc|<nowiki><br />
[ -f $HOME/.aliases ] && . ~/.aliases<br />
</nowiki>}}<br />
<br />
{{hc|$HOME/.aliases|<nowiki><br />
alias emc='emc -nw'<br />
</nowiki>}}<br />
<br />
On desktop environments (such as [[GNOME]], [[KDE]] or [[Xfce]]), if you want to tell it to use {{ic|emacsclient -c}} instead of {{ic|emacs %f}} when opening a new file, make a local copy of {{ic|/usr/share/applications/emacs.desktop}}:<br />
<br />
{{hc|/usr/local/share/applications/emacs.desktop|<br />
## This line has been commented out:<br />
#Exec&#61;emacs %f<br />
<br />
## For this line<br />
Exec&#61;emacsclient -c<br />
<br />
## or, if using the preceeding script, uncomment this line instead<br />
#Exec&#61;em<br />
}}<br />
<br />
This way, a client will be called each time you open up a file and so be very fast!<br />
<br />
=== As a systemd unit ===<br />
<br />
The old system unit method had some caveats. It gave a limited shell environment which restricted shell calls, so we'll be using a user unit, which tends to work a lot better than naively calling ''emacs --daemon''.<br />
<br />
Create a systemd unit for emacs:<br />
{{hc|~/.config/systemd/user/emacs.service|<nowiki><br />
[Unit]<br />
Description=Emacs: the extensible, self-documenting text editor<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/emacs --daemon<br />
ExecStop=/usr/bin/emacsclient --eval "(kill-emacs)"<br />
Restart=always<br />
<br />
[Install]<br />
WantedBy=default.target<br />
</nowiki>}}<br />
<br />
You need to enable the unit so that it gets started on every boot (note - DO ''NOT'' run these commands as root - we want them for our user, not for the root user):<br />
<br />
$ systemctl --user enable emacs<br />
<br />
To actually use the unit, either reboot or start the unit manually:<br />
<br />
$ systemctl --user start emacs<br />
<br />
== Quick Start ==<br />
<br />
Although Emacs is complex, it will not take long to begin to understand the benefits which the level of customization and extensibility bring. Furthermore, the comprehensive variety of extensions already available allows it to be transformed into a powerful environment for almost any form of text-editing.<br />
<br />
Emacs has an excellent built-in tutorial which can be accessed by clicking the first link on the splash screen; by selecting ''Help->Emacs Tutorial'' from the menu or by pressing 'F1' followed by 't'. This page is designed to be an additional resource for getting started with Emacs.<br />
<br />
Emacs also includes a set of reference cards, useful for beginners and experts alike, see {{ic|/usr/share/emacs/<version>/etc/refcards/}} (substitute <version> for your version of emacs).<br />
<br />
=== Basic terminology and convention ===<br />
<br />
Emacs uses some terminology and conventions which may seem unusual at first and will be introduced where appropriate. However, there is some terminology which should be introduced before-hand, as it is fundamental to working with Emacs.<br />
<br />
The one piece of terminology which must be introduced early is the concept of ''buffers''. A buffer is a representation of data within Emacs. For example, when a file is opened in Emacs, that file is read from disk and its contents stored in a buffer, which allows it to be edited and saved back to disk later. Buffers are not limited to text, and can also contain images and widgets. Work is in progress to allow buffers to even display applications! Another way to think of it: data available on disk is referred to as a 'file', whereas data available in Emacs is referred to as a 'buffer'.<br />
<br />
The convention for key sequences in Emacs may be unfamiliar. Namely:<br />
<br />
'''C-x''' refers to Control-x<br />
<br />
'''M-x''' refers to Meta-x<br />
<br />
{{Note|'Meta' corresponds to the Alt key in most cases. Alternatively, the Esc key can be used.}}<br />
<br />
For example, to exit Emacs use the following key sequence: '''C-x C-c'''. This can be read as "Hold Control and press 'x'. Release. Hold Control and press 'c'." Although Emacs provides a menu bar, it is recommended practise to focus on learning the key sequences. This guide will refer to keybindings with the convention used in Emacs from now on.<br />
<br />
=== Movement ===<br />
<br />
Cursor movement is very similar to other graphical editors. The mouse and arrow keys can be used to change the position of the cursor (referred to as ''point'' in Emacs). The standard movement commands performed by the arrow keys also have more accessible bindings in Emacs. To move forward one character, use '''C-f''' and to move one character backward, '''C-b'''. '''C-n''' and '''C-p''' can be used to move to the next and previous lines, respectively. Again, it is generally recommended to use these key-sequences in preference to the mouse and/or arrow keys.<br />
<br />
As might be expected, Emacs provides more advanced movement commands, including moving by word and sentence. '''M-f''' moves forward one word and '''M-b''' will move point one word backward. Similarly, '''M-e''' moves point one sentence forward and '''M-a''' one sentence backward.<br />
<br />
Until now, all of the movement commands introduced have been relative to point. '''M-<''' can be used to move point to the beginning of the buffer, with its counterpart, '''M->''', moving to the end of the buffer. To move point to a specific line number, use '''M-g g'''. '''M-g g''' will prompt for the desired line number. Also, to move to the start or end of the current line, use '''C-a''' or '''C-e''', respectively.<br />
<br />
{{Note|Keybindings for these commands, or indeed any command, may differ ''slightly'' depending on which modes are currently active. However, it is unusual for the replacement command not to provide equivalent functionality. See [[Emacs#Modes|Modes]] for more information.}}<br />
<br />
=== Files and buffers ===<br />
<br />
Emacs provides a series of commands to act upon files, the most common of which will be detailed here. '''C-x C-f''' is used to open a file (this command is called 'find-file' in Emacs). Should the file specified not exist, Emacs will open an empty buffer. Saving a buffer will create the file with the buffer's contents. '''C-x C-s''' can be used to save a buffer. To save a buffer with a different filename, use '''C-x C-w''' (this is a mnemonic for the command 'write-file'), which will prompt for the new filename before writing it to disk. It is also possible to ensure all buffers are saved with '''C-x s''', which, should a buffer be modified since its last save, a prompt will be displayed asking which action to take.<br />
<br />
{{Note|'''C-x C-f''' does not read the file from disk again if a buffer corresponding to the file is still opened. To re-read the file from disk, (1) kill the buffer ('''C-x k''') first, then open the file ('''C-x C-f'''); or (2) use '''M-x revert-buffer''' to revert to data on disk; or (3) use '''C-x C-v''' to load that file to the current buffer; or (4) use '''C-x RET r RET''' to reload the file with the same coding.}}<br />
<br />
Many interactive commands such as "find-file" or "write-file" prompt for input in the bottom-most line of the Emacs window. This line is referred to as the ''minibuffer''. The minibuffer supports many basic editing commands as well as tab-completion similar to that which is available in many *nix shells. '''<TAB>''' can be pressed twice in succession to display a list of completions, and if desired, the mouse can be also be used to select a completion from that list. Completion in the minibuffer is available for many forms of input including commands and filenames.<br />
<br />
The minibuffer also provides a history feature. The previous items entered for a command can be recalled using the '''Up Arrow''' or '''M-p'''.<br />
<br />
To exit the minibuffer at any time, press '''C-g'''.<br />
<br />
After opening several files, a way to switch between them is needed. Opening a file corresponding to a buffer already available in Emacs, will cause Emacs to switch to that buffer. But this is not the most effective way. Emacs provides '''C-x b''', which prompts for the new buffer to be displayed (tab-completion is available here). By entering the name of a buffer which does not exist, a new buffer with that name will be created.<br />
<br />
{{Note|To switch to the previous buffer use '''C-x b <RET>''', as the previous buffer is the default.}}<br />
<br />
A list of all open buffers can be displayed using '''C-x C-b'''. Should a buffer no longer be required, it can be removed with '''C-x k'''.<br />
<br />
=== Editing ===<br />
<br />
Many editing commands exist within Emacs. Perhaps the most important command which has not yet been introduced is 'undo', which can be performed via '''C-_''' or '''C-/'''. Movement commands generally also have a corresponding delete command. For example, '''M-<backspace>''' can be used to delete a word backwards, and {{ic|M-d}} to delete a word forwards. To delete to the end of the line, or the end of the sentence, use {{ic|C-k}} or {{ic|M-k}}, respectively.<br />
<br />
It is a rule-of-thumb that no line be allowed to exceed 80 characters. This aids readability, especially in cases where the line wraps at the edge of a window. Automatically inserting (or removing) line separator(s) is known as ''filling'' in Emacs. A paragraph can be filled using {{ic|M-q}}.<br />
<br />
Characters and words can be transposed using {{ic|C-t}} and {{ic|M-t}}, respectively. For example: {{ic|Hello World!}} to {{ic|World! Hello}}.<br />
<br />
The case of words is also readily adjustable. {{ic|M-l}} downcases a word from point ({{ic|HELLO}} to {{ic|hello}}); {{ic|M-u}} upcases a word from point ({{ic|hello}} to {{ic|HELLO}}) and {{ic|M-c}} capitalizes the first character of a word from point while downcasing the remainder ({{ic|hElLo}} to {{ic|Hello}}).<br />
<br />
=== Killing, yanking and regions ===<br />
<br />
A region is a section of text between two positions. One of those positions is referred to as ''mark'', and the other is point. '''C-<SPC>''' is used to set the position of mark, after which point can be moved to create a region. Within GNU Emacs 23.1 onwards, this region is visible by default. There are a number of commands which act upon regions, among the most commonly used are ''killing'' commands.<br />
<br />
In Emacs, cut and paste are referred to as ''kill'' and ''yank'', respectively. Many commands which delete more than one character (including many of those in the above section, such as '''C-k''' and '''M-d''') actually cut the text and append it to what is known as the ''kill-ring''. The kill-ring is simply a list of killed text. The kill-ring stores up to the last 60 kills by default. Successive kills are concatenated and stored at the head of the list.<br />
<br />
'''C-w''' and '''M-w''' can be used to kill and copy a region, respectively.<br />
<br />
To insert killed text into a buffer (known as 'yanking'), use '''C-y'''. '''C-y''' can be used multiple times in succession to yank text repeatedly. As mentioned, previous kills are stored in a list, however '''C-y''' only retrieves the first of them. The earlier kills can be accessed via '''M-y'''. This will remove the text inserted by 'yank' initially, replacing it with the text killed earlier. '''M-y''' must be used immediately following '''C-y''' and can be used in many times succession to cycle through the kill-ring.<br />
<br />
=== Search and replace ===<br />
<br />
Searching for a string is common practise in text-editing. This can be performed using '''C-s''' (to search forward) or '''C-r''' (to search backward). These commands prompt for the string for which to search. Searching is performed incrementally, and so it will match the next (or previous) occurrence as you type. To move to the next or previous match, press '''C-s''' or '''C-r''' again, respectively. Once a match has been found, '''<RET>''' can be used to end the search. Alternatively, should you wish to return to the location you initiated the search, use '''C-g'''.<br />
<br />
Once a search is completed (i.e., was not aborted with '''C-g''' or similar), the string which was searched for will be the default for any following search. To make use of this, press '''C-s C-s''' or '''C-r C-r''' to search forward or backward again, respectively.<br />
<br />
I-search has some useful commands. Use '''M-e''' to edit the search field. Use<br />
'''M-c''' to toggle case-sensitive matching.<br />
<br />
Regular Expression searches behave identically to the searching described above except for the command to initiate the search. Use '''C-M-s''' or '''C-M-r''' to initiate a regexp search forward or backward, respectively. Once a Regular Expression search has commenced, '''C-s''' and '''C-r''' can be used to search forward or backward, just as with string searches.<br />
<br />
In addition to searching, it is also possible to perform string and regular expression replacement (via '''M-%''' and '''C-M-%''', respectively). Prompts are provided for both the initial and replacement text, and then another prompt for the action to perform on the highlighted match. Although many options are available (the full list is available by pressing '''?'''), the most commonly used are '''y''', to perform replacement, '''n''', to skip this match, and '''!''' to replace this, and all following matches.<br />
<br />
=== Prefix arguments ===<br />
<br />
'''C-u''' corresponds to the 'universal-argument' command. Providing a 'universal-argument' is a way to provide more information to a command (this information is referred to as a 'prefix argument'). For instance<br />
<br />
C-u 80 %<br />
<br />
will insert a line of percent signs. Or<br />
<br />
C-u 4 M-d<br />
<br />
Will delete 4 words. In this case, we provided the amount of words desired to the command invoked by '''M-d'''.<br />
<br />
You can make it a little quicker by using the equivalent '''M-<number>''' as universal argument.<br />
<br />
M-80 %<br />
<br />
=== Indentation ===<br />
<br />
Indentation is usually performed with either '''<TAB>''', to indent a single line, or with '''C-M-\''', to indent a region. If the region is active (''i.e.'' highlighted), then '''<TAB>''' will also indent region.<br />
<br />
Exactly how text is indented usually depends on the ''major-mode'' which is active. Major-modes often define indentation styles specialising in indenting a certain type of text. (See [[Emacs#Modes|Modes]] for more information.)<br />
<br />
In some cases, a suitable major-mode may not exist for a file type, in which case, manual indentation may be necessary. Create a region (see [[Emacs#Killing, yanking and regions|Killing, yanking and regions]]) then perform indentation with '''C-u <n> C-x <TAB>''' (where '<n>' is the number of columns which the text within the region should be indented). For example:<br />
<br />
Increase the region's indentation by four columns:<br />
<br />
C-u 4 C-x <TAB><br />
<br />
Decrease the region's indentation by two columns.<br />
<br />
C-u -2 C-x <TAB><br />
<br />
=== Windows and frames ===<br />
<br />
Emacs is designed for convenient editing of many files at a time. This is achieved by dividing the Emacs interface into three levels. Namely, buffers, which have already been introduced, as well as ''windows'' and ''frames''.<br />
<br />
A ''window'' is a viewport used for displaying a buffer. A window can display only one buffer at a time, however one buffer can be displayed in many windows. Beneath each window exists a ''mode-line'', which displays information for that buffer.<br />
<br />
A ''frame'' is an Emacs "window" (in standard terminology. i.e., 'window' in the sense of the modern desktop paradigm) which contains a title bar, menu bar and one or more 'windows' (in Emacs terminology. i.e., the above definition of 'window').<br />
<br />
From now on the definition of these terms as they exist in Emacs will be used.<br />
<br />
To split the window horizontally or vertically use '''C-x 2''' or '''C-x 3''', respectively. This has the effect of creating another window in the current frame. To cycle between multiple windows, use '''C-x o'''.<br />
<br />
The opposite of splitting a window, is deleting it. To delete the current window, use '''C-x 0''' and '''C-x 1''' to delete all windows except the current.<br />
<br />
As with windows, it is also possible to create and delete frames. '''C-x 5 2''' creates a frame. With '''C-x 5 0''' to delete the current frame and '''C-x 5 1''' to delete all except the current frame.<br />
<br />
{{Note|These commands do not affect buffers. For example, deleting a window does not kill the buffer it displays.}}<br />
<br />
=== Modes ===<br />
<br />
An Emacs mode is an extension written in Emacs Lisp that controls the behaviour of the buffer it is attached to. Usually it provides indentation, syntax highlighting and keybindings for editing that form of text. Sophisticated modes can turn Emacs into a full-fledged IDE (Integrated Development Environment). Emacs will generally use a file's extension to determine which mode should be loaded.<br />
<br />
Useful modes for editing shell scripts are sh-mode, line-number-mode and column-number-mode. They can be used in parallel and are invoked by:<br />
<br />
'''M-x sh-mode <RET>'''<br />
<br />
'''M-x column-number-mode <RET>'''<br />
<br />
line-number-mode is enabled by default, though, it can be toggled on/off by issuing the command again:<br />
<br />
'''M-x line-number-mode <RET>'''<br />
<br />
sh-mode is a ''major-mode''. Major-modes adjust Emacs, and often also provide a specialised set of commands, for editing a particular type of text. Only one major-mode can be active in each buffer. In addition to syntax highlighting, and indentation support, sh-mode defines several commands to help write shell scripts. The following shows a few of those commands:<br />
<br />
'''C-c (''' Insert a function definition<br />
<br />
'''C-c C-f''' Insert a 'for' loop<br />
<br />
'''C-c TAB''' Insert an 'if' statement<br />
<br />
'''C-c C-w''' Insert a 'while' loop<br />
<br />
'''C-c C-l''' Insert an indexed loop from 1 to n<br />
<br />
'line-number-mode' and 'column-number-mode', are ''minor-modes''. Minor-modes can be used to extend a major-mode and any number of minor-modes can be enabled at once.<br />
<br />
== Tips and tricks ==<br />
<br />
While the previous sections has given an overview of the basic editing commands available, it has not given an indication of the possibilities of Emacs. This section will cover some more advanced techniques and functionality.<br />
<br />
We cannot cover everything as it would be too long. So this section will only serve as a ''demo'' for some dazzling features of Emacs.<br />
<br />
See [[#Documentation|Documentation]] to get access to more in-depth detail about all features.<br />
<br />
=== TRAMP ===<br />
<br />
TRAMP (Transparent Remote Access, Multiple Protocols) is an extension which, as its name suggests, provides transparent access to remote files across a number of protocols. When prompted for a filename, entering a specific form will invoke TRAMP. Some examples:<br />
<br />
To prompt for the root password before opening /etc/hosts with root permissions:<br />
<br />
C-x C-f /su::/etc/hosts<br />
<br />
To connect to 'myhost' as 'myuser' via SSH and open the file ~/example.txt:<br />
<br />
C-x C-f /ssh:myuser@myhost:~/example.txt<br />
<br />
The path for TRAMP is typically of the form '/[protocol]:[[user@]host]:<file>'. TRAMP supports much more than the examples above might indicate. For more information refer to the TRAMP info manual, which is distributed with Emacs.<br />
<br />
=== Keyboard macros and registers ===<br />
<br />
This section will provide a practical demonstration of the use of a couple of more powerful editing features. Namely, ''keyboard macros'' and ''registers''.<br />
<br />
The aim will be to produce a listing of a series of characters and their corresponding position in this list. While it is possible to format each of them by hand, this would be slow and error-prone. Alternatively, some of Emacs' more powerful editing functionality could be leveraged. Before describing a solution, some details behind the techniques which will be used follow.<br />
<br />
The first feature which will be introduced is ''registers''. Registers are used to store and retrieve a variety of data types ranging from numbers to window configurations. Each register is given a name of a single character: this character is used to access the register.<br />
<br />
The other which will be demonstrated is ''keyboard macros''. A keyboard macro stores a sequence of commands so they can be easily repeated later. These changes will now be performed step-by-step.<br />
<br />
Starting with a buffer containing our set of characters:<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz<br />
<br />
Prepare a register by invoking the `number-to-register' command ('''C-x r n''') then storing the number '0' in register 'k':<br />
<br />
C-x r n k<br />
<br />
With point at the beginning of the buffer, start a keyboard macro ('''C-x (''') and begin to format the characters:<br />
<br />
C-x ( C-f M-4 .<br />
<br />
Insert ('''C-x r i''') and increment ('''C-x r +''') the register 'k'. The prefix argument ('''C-u''') is used to leave point positioned after the inserted text:<br />
<br />
C-u C-x r i k C-x r + k<br />
<br />
Complete the formatting by inserting a newline. Emacs can then repeat that process, beginning from the point where we started defining the keyboard macro, for the rest of the characters. '''C-x e''' completes then invokes the keyboard macro. The prefix argument, '''M-0''', causes the macro to repeat until it comes across an error. In this case it aborts once it reaches the end of the buffer.<br />
<br />
<RET> M-0 C-x e<br />
<br />
The result:<br />
<br />
A....0<br />
B....1<br />
C....2<br />
[...]<br />
x....49<br />
y....50<br />
z....51<br />
<br />
If you want to save your macro for later use, you must give it a name and save it to your configuration file:<br />
name-last-kbd-macro <br />
insert-kbd-macro<br />
<br />
All defined macros are stored in the macro ring. To cycle between macros, use<br />
'''C-x C-k C-n''' next macro<br />
'''C-x C-k C-p''' previous macro<br />
<br />
You can also use registers to save virtually anything.<br />
<br />
'''C-x r SPC''' Copy current point (position) to register<br />
'''C-x r w''' Copy current window configuration to register.<br />
'''C-x r j''' Restore register.<br />
<br />
So if you often work with windows side by side, for different project, you can save the configuration for the different projects and easily switch from one view to the other.<br />
<br />
You can list used registers with the '''list-registers''' command.<br />
<br />
=== Regular expressions ===<br />
<br />
From the Emacs Manual: "A regular expression, or ''regexp'' for short, is a pattern that denotes a (possibly infinite) set of strings." This section will not go into any detail regarding regular expressions themselves (as there is simply too much to cover). It will however provide a quick demonstration of their power. See [http://www.gnu.org/software/emacs/manual/html_node/elisp/Regular-Expressions.html#Regular-Expressions Regular Expressions] section in the Emacs Manual for further reading.<br />
<br />
Given the same scenario presented above: A list of characters which are to be formatted to represent their respective position in the list. (see [[Emacs#Keyboard macros and registers|Keyboard macros and registers]]). Again, starting with a buffer containing.<br />
<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz<br />
<br />
At the beginning of the buffer, use '''C-M-%''' (if the key-sequence is difficult to perform, it may be more comfortable to use '''M-x query-replace-regexp'''). At the prompt:<br />
\(.\)<br />
which simply matches one character. Then, when prompted for the replacement:<br />
\1....\#^J<br />
{{Note|'^J' represents where a newline should be placed, it should not be entered into the prompt. The newline must instead be inserted literally using '''C-q C-j'''.}}<br />
The replacement expression reads: "Insert the matched text between the first set of parentheses (in this case, a single character), followed by 4 periods then insert an automatically incremented number followed by a newline.<br />
<br />
Finally, press '''!''' to apply this across the entire buffer. All of the formatting that was performed in the previous section was performed with a single regexp replacement.<br />
<br />
=== Rectangular selections ===<br />
<br />
A very powerful feature you may expect from advanced text editors is the possibility to select and edit text in a rectangular area.<br />
<br />
This also works in Emacs. Select your text as usual with '''C-SPC'''. Now you can use several rectangular command.<br />
<br />
'''C-x r t''' Replace rectangle with text.<br />
'''C-x r k''' Kill (and save in kill-ring) rectangle.<br />
'''C-x r y''' Yank rectangle.<br />
'''C-x r o''' Blank out rectangle.<br />
<br />
Note that the command will not affect text outside the rectangle, even though it is highlighted. <br />
<br />
=== Bookmarks ===<br />
<br />
Emacs can remember a list of visited files.<br />
<br />
'''C-x r m''' Add current buffer to bookmarks.<br />
'''C-x r b''' Open a buffer from bookmarks.<br />
'''C-x r l''' List bookmarks.<br />
<br />
=== Elisp interpreter ===<br />
<br />
Evaluate an elisp expression using '''eval-last-sexp''' ('''C-x C-e'''). Emacs always spawns a '''*scratch*''' buffer when started. It will not be saved to disk, feel free to add any text / code you want. It is especially useful for elisp evaluation. Note that this buffer starts using '''lisp-interaction-mode''' by default.<br />
<br />
Alternatively, Emacs provides a top-level elisp interpreter with the '''ielm''' command.<br />
<br />
=== Smart window switch ===<br />
<br />
The traditional window switch with '''C-x o''' can be cumbersome to use in the long run.<br />
The '''windmove''' commands provide a more convenient way to do this. All you have to do is to hold down {{ic|Shift}} while pointing at a window with the arrow keys.<br />
<br />
To activate the windmove keys, use the following in your configuration file:<br />
<br />
{{hc|~/.emacs|<br />
(when (fboundp 'windmove-default-keybindings)<br />
(windmove-default-keybindings))<br />
}}<br />
<br />
=== Shell calls ===<br />
<br />
Use '''M-!''' to call an external command. Use a prefix argument ('''C-u M-!''') to output the result to current buffer at point.<br />
<br />
You can use '''M-|''' on a region to use it as input for a command. For instance<br />
<br />
'''C-u M-| sort -u RET'''<br />
<br />
will sort region, remove duplicates and replace the region with the result.<br />
<br />
=== Shell buffers ===<br />
<br />
You can spawn a shell buffer and execute commands just like you would do in any terminal.<br />
A classic shell buffer can be spawned with the '''shell''' command.<br />
<br />
Emacs features a very powerful shell entirely written in Emacs Lisp, the '''eshell'''. The major advantage over shells like csh or zsh is that the native shell language is elisp itself. So you can use all advanced feature of elisp for your shell functions.<br />
<br />
=== Show matching parentheses ===<br />
<br />
You can use the '''show-paren''' mode.<br />
By default, there’s a small delay before showing a matching parenthesis. Set the '''show-paren-delay''' to 0 to deactivate it.<br />
<br />
{{hc|~/.emacs|<br />
(show-paren-mode 1)<br />
(setq show-paren-delay 0)<br />
}}<br />
<br />
=== Spell checking ===<br />
<br />
You can choose the dictionary with<br />
'''M-x ispell-change-dictionary'''<br />
<br />
To check a single work use '''M-$'''.<br />
You can start checking the whole buffer with<br />
'''M-x ispell-buffer'''<br />
<br />
You can enable on-the-fly spell checking by enabling the '''flyspell-mode'''. For source code files you can restrict the mode to comments by using the '''flyspell-prog-mode''' instead. You will also need the ''aspell'' package for spelling in Emacs. There are corresponding packages for each language, so for English, you'd also want ''aspell-en'' (as well as ''aspell'').<br />
<br />
=== Tables ===<br />
<br />
Emacs comes with some powerful functions to handle and generate tables for various languages. Let's show an example.<br />
<br />
Fruits Quantity<br />
Apples 5<br />
Melons 2<br />
<br />
Now select the previous content in a region, and run<br />
table-capture<br />
<br />
Use two spaces for the column delimiter, and a line break ('''C-q C-j''') for the row delimiter.<br />
This will lead to the following result.<br />
<br />
+------+--------+<br />
|Fruits|Quantity|<br />
+------+--------+<br />
|Apples|5 |<br />
+------+--------+<br />
|Melons|2 |<br />
+------+--------+<br />
<br />
You can revert back the operation with <br />
table-release<br />
There is a lot of handy ''table-*'' functions, like ''table-insert-row'', ''table-span-cell'', ''table-widen-cell'', etc.<br />
<br />
Finally, the ultimate purpose of the ''table'' functions is to convert it to the desired markup language.<br />
Use the ''table-generate-source'' for that.<br />
For LaTeX, the previous table would result in<br />
<br />
% This LaTeX table template is generated by emacs 24.2.1<br />
\begin{tabular}{|l|l|}<br />
\hline<br />
Fruits & Quantity \\<br />
\hline<br />
Apples & 5 \\<br />
\hline<br />
Melons & 2 \\<br />
\hline<br />
\end{tabular}<br />
<br />
Using the table mode you can also do some spreadsheet work like sum on rows and columns, but you will quickly find it limited. Besides it is quite slow. Have a look at the [[#Agenda, spreadsheet and document authoring|org-mode]] for much more powerful possibilities.<br />
<br />
=== Agenda, spreadsheet and document authoring ===<br />
<br />
Emacs can offer powerful office features thanks to the famous and powerful [http://orgmode.org/ Org mode]. This mode is part of the standard Emacs distribution.<br />
<br />
Org mode is originally a powerful TODO and Agenda agent, but has quickly evolved to a much wider set of features.<br />
There is simply too much to tell about Org that we cannot aford even to skim over all the features. So we will only whet your appetite with a few exemples.<br />
<br />
Open a new file TODO.org file, Org mode should be loaded. If not, switch to it with '''M-x org-mode'''.<br />
{{hc|TODO.org|<br />
* First entry<br />
** Subentry<br />
Some comments<br />
*** Subsubentry<br />
* Second entry<br />
- List item 1<br />
- List item 2<br />
}}<br />
<br />
Now a few useful bindings.<br />
* '''TAB''' to cycle-fold current entry.<br />
* '''S-TAB''' to cycle-fold all entries.<br />
* '''M-RET''' to start a new item on the same level as the current one.<br />
* '''M-<left>''' and '''M-<right>''' to change level.<br />
* '''M-<up>''' and '''M-<down>''' to move item together with all its subsections.<br />
* '''S-<left>''' and '''S-<right>''' to change status. On list items it will change the item style.<br />
* '''S-<up>''' and '''S-<down>''' to change priority.<br />
* '''C-c ^''' to sort all subentries of the current entry.<br />
* '''C-c .''' to add a timestamp to the current entry. Use {{ic|Shift}} and arrows to skip days or weeks. Use the mouse on the calendar or press {{ic|Enter}} on a specific day to choose it.<br />
<br />
The spreadsheet features are very comprehensive. Let's give an excerpt from the manual:<br />
<br />
{{bc|<nowiki><br />
Finally, just to whet your appetite for what can be done with the<br />
fantastic `calc.el' package, here is a table that computes the Taylor<br />
series of degree `n' at location `x' for a couple of functions.<br />
<br />
|---+-------------+---+-----+--------------------------------------|<br />
| | Func | n | x | Result |<br />
|---+-------------+---+-----+--------------------------------------|<br />
| # | exp(x) | 1 | x | 1 + x |<br />
| # | exp(x) | 2 | x | 1 + x + x^2 / 2 |<br />
| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |<br />
| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |<br />
| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |<br />
| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |<br />
|---+-------------+---+-----+--------------------------------------|<br />
#+TBLFM: $5=taylor($2,$4,$3);n3<br />
</nowiki>}}<br />
Org mode recognizes a table when the pipe '''|''' is the first non-whitespace character on line. In the previous text, no line was drawn. This is done automatically when '''TAB''' is pressed after an entry or the '''|-''' sequence. The result column was not written by hand neither, it is computed from the calc formula on the last line. Use '''C-u C-c C-c''' to recompute all values in a table.<br />
<br />
There is also some handy row and column manipulation bindings like those for the TODO file. {{ic|Alt}} plus arrows will move columns and arrows.<br />
<br />
For more in-depth details, refer to the official manual: '''C-h i m Org mode RET'''.<br />
<br />
=== Refactoring and smart completion ===<br />
<br />
If you are looking for popular programming features found in most IDE (such as Eclipse), the [http://cedet.sourceforge.net/semantic.shtml Semantic] tool will do the job. It is part of Emacs standard distribution. Currently C, C++, Scheme, Javascript, Java, HTML, and Make are well supported. You can find a table on the current support state on the [http://cedet.sourceforge.net/languagesupport.shtml CEDET page].<br />
<br />
Open a file in your favorite programming language supported by Semantic and turn on the Semantic minor mode with<br />
M-x semantic-mode<br />
Semantic will work for a few seconds parsing the libraries included from your file (in C that would mostly be the standard library for instance).<br />
<br />
==== Features ====<br />
<br />
Once done, you can start using the great Semantic features:<br />
;Smart completion<br />
Press '''C-c , SPC''' to complete a symbol at point. If it is an argument, it will check for type correctness.<br />
<br />
;Jump to symbol<br />
Press '''C-c , j''' to prompt for a symbol and jump to its definition. You can use auto-completion with '''TAB'''. Use a capital '''J''' to search for symbol accross files.<br />
<br />
;List symbol calls<br />
Press '''C-c , g''' to prompt for a symbol and list the places where it is being referred to. You can use '''n''' and '''p''' to navigate through the resulting entries. Press '''RET''' to toggle details, and '''RET''' again on a reference to jump to it. Use a capital '''G''' in the first command to work across files.<br />
<br />
;Refactoring<br />
First list use of the symbol you want to refactor with the aforementioned command. Now press '''(''' to start defining a macro on the symbol. This is actually much more powerful than refactoring since you can apply any function to the symbol and even act on its surrounding symbols. Press '''C-x )''' to finish the macro and '''E''' to call it.<br />
<br />
;Describe symbol<br />
Call the following function to display details on a symbol.<br />
semantic-ia-show-summary<br />
This can be very useful for complexe data structures and function prototypes. There is no binding by default.<br />
<br />
==== Configuration ====<br />
<br />
Here follows a sample configuration for use of Semantic with all supported programming languages: an example binding and a display configuration.<br />
;; Semantic with ghost display (allows M-n and M-p to browse completion).<br />
(semantic-mode 1)<br />
(define-key my-keys-minor-mode-map (kbd "C-c , d") 'semantic-ia-show-summary)<br />
(setq semantic-complete-inline-analyzer-displayor-class 'semantic-displayor-ghost)<br />
<br />
You can also add some specialization for a specific language. Here for C:<br />
(add-hook<br />
'c-mode-hook<br />
(lambda ()<br />
(local-set-key (kbd "M-TAB") 'semantic-complete-analyze-inline)<br />
(local-set-key "." 'semantic-complete-self-insert)<br />
(local-set-key ">" 'semantic-complete-self-insert)))<br />
<br />
==== Further reading ====<br />
<br />
You can access the info manual directly from Emacs: '''C-h i m Semantic RET'''.<br />
<br />
=== Using Emacs as git mergetool ===<br />
<br />
By default, Git provides support for using Emacs' Emerge mode as a merge tool. However you may prefer the Ediff mode. Unfortunately this mode is not supported by git for technical reasons. There is still a way to use it by evaluating some elisp code upon emacs call.<br />
<br />
{{hc|.gitconfig|<nowiki><br />
[mergetool.ediff]<br />
cmd = emacs --eval \" (progn (defun ediff-write-merge-buffer () (let ((file ediff-merge-store-file)) (set-buffer ediff-buffer-C) (write-region (point-min) (point-max) file) (message \\\"Merge buffer saved in: %s\\\" file) (set-buffer-modified-p nil) (sit-for 1))) (setq ediff-quit-hook 'kill-emacs ediff-quit-merge-hook 'ediff-write-merge-buffer) (ediff-merge-files-with-ancestor \\\"$LOCAL\\\" \\\"$REMOTE\\\" \\\"$BASE\\\" nil \\\"$MERGED\\\"))\" <br />
<br />
[merge]<br />
tool = ediff<br />
</nowiki>}}<br />
<br />
Note that the command has to be on a single line.<br />
In the above example, we launch a new instance of Emacs. You might want to use emacsclient for quicker startup; it is not recommended though since the Ediff call is not really clean: it could mess with your current Emacs session.<br />
<br />
If you want an instant startup you can use the '''-q''' parameter. If you want to launch Emacs quickly while preserving at least a part of your configuration, you can call Emacs with<br />
emacs -q -l ~/.emacs-light<br />
where the light configuration file loads only what you need for Ediff.<br />
<br />
See [http://kerneltrap.org/mailarchive/git/2007/7/1/250424 kerneltrap.org] and [http://stackoverflow.com/questions/1817370/using-ediff-as-git-mergetool stackoverflow] for more details on this trick and the Ediff issue.<br />
<br />
=== Using Caps Lock as Control key ===<br />
<br />
Some users like this behavior to avoid the so-called 'emacs pinky'. If you want to try it on X, just run <br />
<br />
$ setxkbmap -option 'ctrl:nocaps'<br />
<br />
Alternatively, to '''swap''' these keys, run<br />
<br />
$ setxkbmap -option 'ctrl:swapcaps'<br />
<br />
To set this permanently, consider adding it to your {{ic|.xinitrc}} file. <br />
<br />
Now, if you ever need to upcase an region, just use the default {{ic|C-x C-u}} keybinding, which calls the {{ic|upcase-region}} function.<br />
<br />
See [http://ergoemacs.org/emacs/swap_CapsLock_Ctrl.html] for an alternative approach.<br />
<br />
== Customization ==<br />
<br />
Emacs can configured by editing {{ic|~/.emacs}} or using '''M-x customize'''. This section will focus on editing {{ic|~/.emacs}} by hand, and provide some example customizations to demonstrate commonly-configured aspects of Emacs. The customize command provides a simple interface to make adjustments, though it may become restricting as you grow more familiar with Emacs.<br />
<br />
All of the examples here can be performed while Emacs is running. To evaluate the expression within Emacs, use:<br />
<br />
'''C-M-x''' with point anywhere within the expression.<br />
<br />
or<br />
<br />
'''C-x C-e''' with point following the last ')'<br />
<br />
For some users, typing 'yes' and 'no' in prompts can quickly become tiring. To instead use the 'y' and 'n' keys at these prompts:<br />
<br />
(defalias 'yes-or-no-p 'y-or-n-p)<br />
<br />
To stop the cursor blinking, use:<br />
<br />
(blink-cursor-mode -1)<br />
<br />
Similarly, to enable column-number-mode, as discussed in the previous section:<br />
<br />
(column-number-mode 1)<br />
<br />
The similarities between the previous two commands are not a coincidence: blink-cursor-mode and column-number-mode are both minor-modes. As a rule, minor-modes can be enabled given positive argument or disabled with a negative argument. Should the argument be omitted, the minor-mode will be toggled on/off.<br />
<br />
Here are some more examples of minor-modes. The following will disable the scroll bars, menu-bar and tool-bar, respectively.<br />
<br />
(scroll-bar-mode -1)<br />
(menu-bar-mode -1)<br />
(tool-bar-mode -1)<br />
<br />
The variable, 'auto-mode-alist', can be modified to change the major-mode used by default for certain file names. The following example will make the default major-mode for '.tut' and '.req' files 'text-mode'.<br />
<br />
(setq auto-mode-alist<br />
(append<br />
'(("\\.tut$" . text-mode)<br />
("\\.req$" . text-mode))<br />
auto-mode-alist))<br />
<br />
Settings can also be applied on a per-mode basis. A common method for this is to add a function to a ''hook''. For example, to force indentation to use spaces instead of tabs, but only in text-mode:<br />
<br />
(add-hook 'text-mode-hook (lambda () (setq indent-tabs-mode nil)))<br />
<br />
Similarly, to only use spaces for indentation everywhere:<br />
<br />
(setq-default indent-tabs-mode nil)<br />
<br />
Keybindings can be adjusted in two ways. The first of which is 'define-key'. 'define-key' creates a keybinding for a command but only in one mode. The example below will make '''F8''' delete any whitespace from the end of each line of a 'text-mode' buffer:<br />
<br />
(define-key text-mode-map (kbd "<f8>") 'delete-trailing-whitespace)<br />
<br />
The other method is 'global-set-key'. This is used to bind a key to a command everywhere. To bind 'query-replace-regexp' ('''C-M-%''') to '<f7>'.<br />
<br />
(global-set-key (kbd "<f7>") 'query-replace-regexp)<br />
<br />
Binding a command to an alternate key does not replace any existing bindings. Which is to say, 'query-replace-regexp' would be bound to both '''F7''' and '''C-M-%''' after the above example.<br />
<br />
Almost anything within Emacs can be configured. Browsing through the [http://emacswiki.org/ Emacs Wiki] should give a solid place to start.<br />
<br />
=== Multiplexing emacs and emacsclient ===<br />
<br />
To open the new file in the same {{ic|emacs-session}} its use needs use to use {{ic|emacsclient}}. {{ic|emacs}} command can be itself warpped to do the smarter job to open the file if the session exists.<br />
<br />
To start session you need to {{ic|start-server}}. This snippet will create server in first session of emacs. Add this to your {{ic|emacs}} configuration file.<br />
{{hc|.emacs or .emacs.d/init.el|<br />
(require 'server)<br />
(unless (server-running-p)<br />
(server-start))<br />
}}<br />
<br />
Shell alias method is not adequate for this since you also need to pass variables or start the independent session of your own. Add this to the {{ic|.bashrc}} or any rc file of your shell. This will make your {{ic|$ emacs}} command behave like emacsclient if the argument is passed.<br />
<br />
<nowiki><br />
function emacs {<br />
if [[ $# -eq 0 ]]; then<br />
/usr/bin/emacs # "emacs" is function, will cause recursion<br />
return<br />
fi<br />
args=($*)<br />
for ((i=0; i <= ${#args}; i++)); do<br />
local a=${args[i]}<br />
# NOTE: -c for creating new frame<br />
if [[ ${a:0:1} == '-' && ${a} != '-c' ]]; then<br />
/usr/bin/emacs ${args[*]}<br />
return<br />
fi<br />
done<br />
setsid emacsclient -n -a /usr/bin/emacs ${args[*]}<br />
} </nowiki><br />
<br />
If you want to run the it in new session just do {{ic|emacs <file> -}}.<br />
<br />
=== Multiple configurations ===<br />
<br />
You can use several configurations and tell Emacs to load one or the other.<br />
<br />
For example, let's define two configuration files.<br />
<br />
{{hc|.emacs|<br />
(load "~/.emacs.d/main" nil t)<br />
(load "~/.emacs.d/functions" nil t)<br />
(load "~/.emacs.d/modes" nil t)<br />
(load "~/.emacs.d/plugins" nil t)<br />
(load "~/.emacs.d/theme" nil t)<br />
}}<br />
<br />
This is the full configuration we load for the daemon. But the ''plugins'' file is huge and slow to load. If we want to spaqn a new Emacs instance that does not need the ''plutings'' features, it can be cumbersome to load it everytime in the long time.<br />
<br />
{{hc|.emacs-light|<br />
(load "~/.emacs.d/main" nil t)<br />
(load "~/.emacs.d/functions" nil t)<br />
(load "~/.emacs.d/modes" nil t)<br />
(load "~/.emacs.d/theme" nil t)<br />
}}<br />
<br />
And now we launch Emacs with<br />
emacs -q -l ~/.emacs-light<br />
You can create an alias to ease the call.<br />
<br />
=== Loading extensions ===<br />
<br />
You can load extensions using the ''require'' function. For instance<br />
(require 'mediawiki)<br />
<br />
If you try using the same configuration file on a machine where mediawiki is not installed, Emacs will primpt for an error. Besides, all extension-specific code would be parsed for nothing.<br />
<br />
The trick is to test the return value of ''require'':<br />
<br />
(if (require 'mediawiki nil t)<br />
(progn<br />
(setq mediawiki-site-alist '(<br />
("ArchLinux" "https://wiki.archlinux.org/" "UserName" "" "Main Page")<br />
)<br />
)<br />
(setq mediawiki-mode-hook<br />
(lambda ()<br />
(visual-line-mode 1)<br />
(turn-off-auto-fill)<br />
))<br />
)) <br />
<br />
=== Local and custom variables ===<br />
<br />
You can define variables in your configuration file that can be later one modified locally for a file.<br />
<br />
(defcustom my-compiler "gcc" "Some documentation")<br />
<br />
Now in any file you can define local variables in two ways:<br />
* On the very first line, write<br />
// -*- my-compiler:g++; mode:c++ -*-<br />
* If you cannot (or do not want to) write this on the first line, you can put it at the end:<br />
// Local Variables:<br />
// my-compiler: g++<br />
// mode: c++<br />
// End:<br />
<br />
Note that the beginning characters need to be comments for the current language, that's why here we used two backslashes for C++. For Elisp you would use<br />
;; -*- mode:emacs-lisp -*-<br />
<br />
There is two functions that may help you in defining the variables: ''add-file-local-variable'' and ''add-file-local-variable-prop-line''.<br />
<br />
Finally, custom variable are considered insecure by default. If you try to open a file that contains local variable redefining insecure custom variables, Emacs will ask you for confirmation.<br />
<br />
If you know what you are doing, you can declare the variable as secure, thus removing the Emacs prompt for confirmation. You need to specify a predicate that any new value has to verify so that it can be considered safe.<br />
<br />
(defcustom my-compiler "gcc" "Some documentation" :safe 'stringp)<br />
<br />
In the previous example, if you attempt to set anything else than a string, Emacs will consider it insecure.<br />
<br />
=== Custom colors and theme ===<br />
<br />
Colors can be easily customized using the ''face'' facility.<br />
(set-face-background 'region "color-17")<br />
(set-face-foreground 'region "white")<br />
(set-face-bold-p 'font-lock-builtin-face t ) <br />
<br />
You can have let Emacs tell you the name of the face where the point is. Use the ''customize-face'' function for that. The facility will show you how to set colors, bold, underline, etc.<br />
<br />
Emacs in console can handle 256 colors, but you will have to use an appropriate terminal for that. For instance URxvt has support for 256 colors. You can use the ''list-colors-display'' for a comprehensive list of supported colors. This is highly terminal-dependent.<br />
<br />
=== SyncTeX support ===<br />
<br />
Emacs is definitely one of the most powerful LaTeX editor. This is mostly due to the fact you can adapt or create a LaTeX mode to fit your needs best.<br />
<br />
Still, there might be some challenges, like SyncTeX support. First you need to make sure your TeX distribution has it. If you installed TeX Live manually, you may need to install the ''synctex'' package.<br />
# umask 022 && tlmgr install synctex<br />
<br />
SyncTeX support is viewer-dependent. Here we will use Zathura as an example, so the code needs to be adapted if you want to use another PDF viewer.<br />
<br />
(defcustom tex-my-viewer "zathura --fork -s -x \"emacsclient --eval '(progn (switch-to-buffer (file-name-nondirectory \"'\"'\"%{input}\"'\"'\")) (goto-line %{line}))'\"" <br />
"PDF Viewer for TeX documents. You may want to fork the viewer<br />
so that it detects when the same document is launched twice, and<br />
persists when Emacs gets closed.<br />
<br />
Simple command:<br />
<br />
zathura --fork<br />
<br />
We can use<br />
<br />
emacsclient --eval '(progn (switch-to-buffer (file-name-nondirectory \"%{input}\")) (goto-line %{line}))'<br />
<br />
to reverse-search a pdf using SyncTeX. Note that the quotes and double-quotes matter and must be escaped appropriately."<br />
:safe 'stringp)<br />
<br />
Here we define our custom variable. If you are using AucTeX or Emacs default LaTeX-mode, you will have to set the viewer accordingly.<br />
<br />
Now open a LaTeX source file with Emacs, compile the document, and launch the viewer. Zathura will spawn. If you press {{ic|Ctrl+Left click}} Emacs should place the point at the corresponding position.<br />
<br />
=== Syntax Highlighting for Systemd Files ===<br />
<br />
You can simply tell emacs to colour systemd files (services, timer, etc.), by adding this to your init file:<br />
<br />
(add-to-list 'auto-mode-alist '("\\.service\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.timer\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.target\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.mount\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.automount\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.slice\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.socket\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.path\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.netdev\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.network\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.link\\'" . conf-unix-mode))<br />
(add-to-list 'auto-mode-alist '("\\.automount\\'" . conf-unix-mode))<br />
<br />
== Documentation ==<br />
<br />
You may find yourself overwhelmed by the amount of Emacs features. You may find it difficult to know how to use Emacs Lisp to customize your favorite modes, or even to create your own modes / packages. Thankfully Emacs takes a strong point to auto-documenting everything: its internals, current configuration, bindings, etc. Almost everything is documented.<br />
<br />
=== Contextual help ===<br />
<br />
Emacs is self-documenting by design. As such, a great deal of information is available to determine the name of a specific command or its keybinding, for example. The following is a listing of some of the most helpful of these:<br />
<br />
'''C-h a''' Find a command matching a description.<br />
<br />
'''C-h b''' List all active keybindings.<br />
<br />
'''C-h f''' Describe the given function.<br />
<br />
'''C-h k''' Find which command a key is bound to.<br />
<br />
'''C-h m''' Display information regarding the currently active modes.<br />
<br />
'''C-h t''' Start the Emacs tutorial.<br />
<br />
'''C-h v''' Describe the given variable.<br />
<br />
'''C-h w''' Find which key(s) a command is bound to.<br />
<br />
=== The manuals ===<br />
<br />
If you really want to master Emacs, the most recommanded source of documentation remains the official manuals:<br />
* Emacs: the complete Emacs user manual.<br />
* Emacs FAQ.<br />
* Emacs Lisp Intro: if you never used any programming language before.<br />
* Elisp: if you are already familiar with a programming language.<br />
<br />
You can access it as PDFs from [http://www.gnu.org/software/emacs/manual/ GNU.org] or directly from Emacs itself thanks to the embedded 'info' reader: '''C-h i'''. Press '''m''' to choose a book.<br />
<br />
Some users prefer to read books using 'info' because of its convenient shortcuts, its paragraphs adapting to window width and the font adapted to current screen resolution. Some find it less irritating to the eyes. Finally you can easily copy content from the book to any Emacs buffer, and you can even execute Lisp code snippets directly from the examples.<br />
<br />
You may want to read the '''Info''' book to know more about it: '''C-h i m info <RET>'''.<br />
Press '''?''' while in info mode for a quick list of shortcuts.<br />
<br />
== Extensions ==<br />
<br />
Emacs includes hundreds of modes, libraries and other extensions, with many more available to further Emacs' capabilities. Most of these come with instructions detailing any changes needed to be made in {{ic|~/.emacs}}. These instructions are generally found in the comment block at the beginning of an elisp source file, or in a README (or similar), should the extension consist of multiple source files.<br />
<br />
A number of popular extensions are available as packages in the 'community' repository, and more still, via [[AUR]]. The name of such packages have a 'emacs-' prefix (for example, emacs-lua-mode). In many cases, the changes which need to be made in {{ic|~/.emacs}} are shown during the installation of the package.<br />
<br />
Should instructions describing how to activate a specific extension not be available in the aforementioned location(s), check for a corresponding page in the [http://emacswiki.org/ Emacs Wiki], which will almost certainly provide an example configuration. The Emacs Wiki is also an excellent resource for discovering even more extensions.<br />
<br />
You can also use the [http://tromey.com/elpa/ Emacs Lisp Package Archive (ELPA)] to automatically install packages. See the website for instructions. ELPA is included with Emacs 24 (the newest version of Emacs); it is an accepted part of the Emacs ecosystem. Also, check out the [http://marmalade-repo.org/ Marmalade] and [http://melpa.milkbox.net/ MELPA] repos.<br />
<br />
{{Tip|Use {{ic|M-x list-packages}} to get a list of available packages for installation.}}<br />
<br />
=== Emacs MediaWiki ===<br />
Since we are at it, you may be a contributor to Arch Linux Wiki, or any Mediawiki-based website. Then emacs will become your best friend thanks to the [[Emacs Mediawiki]] extension. Check the dedicated page for more details.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Colored output issues ===<br />
<br />
By default, the Emacs shell will show raw escape sequences used to print colors. In other words, it will display strange symbols in place of the desired colored output.<br />
<br />
Including the following into {{ic|~/.emacs}} amends the problem:<br />
(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)<br />
<br />
=== Menus appear empty ===<br />
<br />
A bug exists in GNU Emacs 23.1 (using the GTK toolkit) which may cause some menus to appear empty. This appears to be fixed in Emacs' CVS trunk. The corresponding [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=550541 Debian bug report] contains a workaround.<br />
<br />
=== Problems displaying characters in X Windows ===<br />
<br />
If when you start emacs in X windows all the characters in the main window are white boxes with black borders (the ones you see if you try to view characters for which you do not have the correct font installed), you need to install {{Pkg|xorg-fonts-75dpi}} and/or {{Pkg|xorg-fonts-100dpi}} and restart X windows.<br />
<br />
=== Slow startup ===<br />
<br />
Slow startup times are often caused by one of two things.<br />
<br />
To determine which it might be, run Emacs with:<br />
<br />
$ emacs -q<br />
<br />
If Emacs still starts slowly, refer to [[Emacs#Incorrect network configuration|Incorrect network configuration]]. If not, it is almost certainly a [[Emacs#Init file loads slowly|problem in your .emacs]].<br />
<br />
* Mistakes, particularly in /etc/hosts, will often result in a 5+ second delay when starting Emacs. Refer to '[[Configuring_network#Set_the_hostname|set the hostname]]' in the network configuration guide for information.<br />
<br />
* A simple way to search for the cause is to comment-out (i.e., prefix lines with ';') suspect sections of your {{ic|~/.emacs}} (or {{ic|~/.emacs.d/init.el}}) then start Emacs again to see if there's any change. Keep in mind use of "require" and "load" can slow the startup down, especially when used with larger extensions. They should, as a rule, only be used when their target is either: needed once Emacs starts or provides little more than "autoloads" for an extension. Otherwise, use the 'autoload function directly. For example, instead of:<br />
<br />
(require 'anything)<br />
<br />
you might use:<br />
<br />
(autoload 'anything "anything" "Select anything" t)<br />
<br />
=== Incorrect network configuration ===<br />
<br />
If<br />
<br />
$ emacs -q<br />
<br />
starts slowly for you, there may be an issue with your network configuration. To see if this is the case, you may need to monitor any network packets sent from your computer (using a program like Wireshark) to see if there is any strange behavior. For example, if you see DNS errors, than you may need to add<br />
<br />
127.0.0.1 localhost HOSTNAME<br />
<br />
to {{ic|/etc/hosts}}, where HOSTNAME is the hostname obtained by running<br />
<br />
$ hostname<br />
<br />
=== Cannot open load file: ... ===<br />
<br />
The most common cause of this error is the 'load-path' variable not including the path to the directory within which the extension is located. To solve this, add the appropriate path to the list to be searched prior to attempting to load the extension:<br />
<br />
(add-to-list 'load-path "/path/to/directory/")<br />
<br />
When attempting to use packages for extensions and Emacs has been configured with a prefix other than '/usr', the load-path will need to be updated. Place the following in {{ic|~/.emacs}} prior to the instructions provided by the package:<br />
<br />
(add-to-list 'load-path "/usr/share/emacs/site-lisp")<br />
<br />
If compiling Emacs by hand, keep in mind that the default prefix is '/usr/local'.<br />
<br />
=== Dead-accent keys problem: '<dead-acute> is undefined' ===<br />
<br />
Searching about this bug on Google, we find this link:<br />
http://lists.gnu.org/archive/html/help-gnu-emacs/2009-05/msg00167.html<br />
<br />
Explaining the problem: in recent versions of<br />
b72<br />
Emacs, the normal way to use accent keys doesn't work as expected. Trying to accent a word like 'fiancé' will produce the message above.<br />
<br />
A way to solve it is just put the line above on your startup file, {{ic|~/.emacs}}:<br />
<br />
(require 'iso-transl)<br />
<br />
And no, it isn't a bug, but a feature of new Emacs versions. Reading the subsequent messages about it on the mail list, we found it (http://lists.gnu.org/archive/html/help-gnu-emacs/2009-05/msg00179.html):<br />
<br />
:''It seems that nothing is loaded automatically because there is a choice betwee iso-transl and iso-acc. Both seem to provide an input method with C-x 8 or Alt-<accent> prefix, but what you and I are doing is just pressing a dead key (^, ´, `, ~, ¨) for the accent and then another key to "compose" the accented character. And there is no Alt key used in this! And according to documentation it seems be appropriate for 8-bit encodings, so it should be pretty useless in UTF-8. I reported this bug when it was introduced, but the bug seems to be<br />
a3b<br />
classified as a feature ... Maybe it's just because the file is auto-loaded though pretty useless. ''<br />
<br />
=== C-M-% and some other bindings do not work in emacs nox ===<br />
<br />
This is because terminals are more limited than Xorg. Some terminals may handle more bindings than other, though. Two solutions:<br />
* either use the graphical version,<br />
* or change the binding to a supported one.<br />
<br />
Example:<br />
{{hc|.emacs|<br />
(global-set-key (kbd "C-M-y") 'query-replace-regexp)<br />
}}<br />
<br />
=== Emacs client gets stuck when switching back to it ===<br />
<br />
If you are using Emacs daemon, then you should know that input is blocking. If one Emacs instance is in the minibuffer (after an '''M-x''' for instance), then all other instance will wait for it to finish. Press '''C-g''' to cancel any input to make sure this Emacs session is not blocking.<br />
<br />
=== Emacs-nox output gets messy ===<br />
<br />
When working in a terminal, the color, indentation, or anything related to the output might become crazy. This is (probably?) because Emacs was sent a special character at some point which may conflict with the current terminal.<br />
There is not much to be done but restarting emacs. If someone has a workaround or a more detailed explanation on the issue, feel free to contribute.<br />
<br />
Graphical Emacs does not suffer from this issue.<br />
<br />
=== Shift + Arrow keys not working in emacs within tmux ===<br />
<br />
First you must enable xterm-keys in your [[tmux]] config.<br />
{{hc|.tmux.conf|<br />
setw -g xterm-keys on<br />
}}<br />
<br />
But, this will break other key combinations. To fix them, put the following in your emacs config.<br />
{{hc|.emacs|<br />
;; handle tmux's xterm-keys<br />
;; put the following line in your ~/.tmux.conf:<br />
;; setw -g xterm-keys on<br />
(if (getenv "TMUX")<br />
(progn<br />
(let ((x 2) (tkey ""))<br />
(while (<&#61; x 8)<br />
;; shift<br />
(if (&#61; x 2)<br />
(setq tkey "S-"))<br />
;; alt<br />
(if (&#61; x 3)<br />
(setq tkey "M-"))<br />
;; alt + shift<br />
(if (&#61; x 4)<br />
(setq tkey "M-S-"))<br />
;; ctrl<br />
(if (&#61; x 5)<br />
(setq tkey "C-"))<br />
;; ctrl + shift<br />
(if (&#61; x 6)<br />
(setq tkey "C-S-"))<br />
;; ctrl + alt<br />
(if (&#61; x 7)<br />
(setq tkey "C-M-"))<br />
;; ctrl + alt + shift<br />
(if (&#61; x 8)<br />
(setq tkey "C-M-S-"))<br />
<br />
;; arrows<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d A" x)) (kbd (format "%s<up>" tkey)))<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d B" x)) (kbd (format "%s<down>" tkey)))<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d C" x)) (kbd (format "%s<right>" tkey)))<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d D" x)) (kbd (format "%s<left>" tkey)))<br />
;; home<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d H" x)) (kbd (format "%s<home>" tkey)))<br />
;; end<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d F" x)) (kbd (format "%s<end>" tkey)))<br />
;; page up<br />
(define-key key-translation-map (kbd (format "M-[ 5 ; %d ~" x)) (kbd (format "%s<prior>" tkey)))<br />
;; page down<br />
(define-key key-translation-map (kbd (format "M-[ 6 ; %d ~" x)) (kbd (format "%s<next>" tkey)))<br />
;; insert<br />
(define-key key-translation-map (kbd (format "M-[ 2 ; %d ~" x)) (kbd (format "%s<delete>" tkey)))<br />
;; delete<br />
(define-key key-translation-map (kbd (format "M-[ 3 ; %d ~" x)) (kbd (format "%s<delete>" tkey)))<br />
;; f1<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d P" x)) (kbd (format "%s<f1>" tkey)))<br />
;; f2<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d Q" x)) (kbd (format "%s<f2>" tkey)))<br />
;; f3<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d R" x)) (kbd (format "%s<f3>" tkey)))<br />
;; f4<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d S" x)) (kbd (format "%s<f4>" tkey)))<br />
;; f5<br />
(define-key key-translation-map (kbd (format "M-[ 15 ; %d ~" x)) (kbd (format "%s<f5>" tkey)))<br />
;; f6<br />
(define-key key-translation-map (kbd (format "M-[ 17 ; %d ~" x)) (kbd (format "%s<f6>" tkey)))<br />
;; f7<br />
(define-key key-translation-map (kbd (format "M-[ 18 ; %d ~" x)) (kbd (format "%s<f7>" tkey)))<br />
;; f8<br />
(define-key key-translation-map (kbd (format "M-[ 19 ; %d ~" x)) (kbd (format "%s<f8>" tkey)))<br />
;; f9<br />
(define-key key-translation-map (kbd (format "M-[ 20 ; %d ~" x)) (kbd (format "%s<f9>" tkey)))<br />
;; f10<br />
(define-key key-translation-map (kbd (format "M-[ 21 ; %d ~" x)) (kbd (format "%s<f10>" tkey)))<br />
;; f11<br />
(define-key key-translation-map (kbd (format "M-[ 23 ; %d ~" x)) (kbd (format "%s<f11>" tkey)))<br />
;; f12<br />
(define-key key-translation-map (kbd (format "M-[ 24 ; %d ~" x)) (kbd (format "%s<f12>" tkey)))<br />
;; f13<br />
(define-key key-translation-map (kbd (format "M-[ 25 ; %d ~" x)) (kbd (format "%s<f13>" tkey)))<br />
;; f14<br />
(define-key key-translation-map (kbd (format "M-[ 26 ; %d ~" x)) (kbd (format "%s<f14>" tkey)))<br />
;; f15<br />
(define-key key-translation-map (kbd (format "M-[ 28 ; %d ~" x)) (kbd (format "%s<f15>" tkey)))<br />
;; f16<br />
(define-key key-translation-map (kbd (format "M-[ 29 ; %d ~" x)) (kbd (format "%s<f16>" tkey)))<br />
;; f17<br />
(define-key key-translation-map (kbd (format "M-[ 31 ; %d ~" x)) (kbd (format "%s<f17>" tkey)))<br />
;; f18<br />
(define-key key-translation-map (kbd (format "M-[ 32 ; %d ~" x)) (kbd (format "%s<f18>" tkey)))<br />
;; f19<br />
(define-key key-translation-map (kbd (format "M-[ 33 ; %d ~" x)) (kbd (format "%s<f19>" tkey)))<br />
;; f20<br />
(define-key key-translation-map (kbd (format "M-[ 34 ; %d ~" x)) (kbd (format "%s<f20>" tkey)))<br />
<br />
(setq x (+ x 1))<br />
))<br />
)<br />
)<br />
}}<br />
<br />
=== Improper window resizing in KDE ===<br />
KDE users may observe that the Emacs window does not resize properly, but rather, the resized portion<br />
is transparent and mouse clicks are sent to the underlying window. To correct this behavior, change<br />
KDE's GTK3 theme to something other than oxygen-gtk. For instance, use the Emacs theme which is included with {{Pkg|gtk3}}.<br />
<br />
== Alternatives ==<br />
<br />
There are numerous implementations of Emacs. GNU/Emacs is probably the most popular.<br />
<br />
Lightweight Emacs compatible alternatives can be found either in Arch repositories or in [[AUR]].<br />
<br />
=== mg ===<br />
<br />
mg (originally called MicroGnuEmacs) is a lightweight implementation of Emacs written in C.<br />
<br />
{{Pkg|mg}} is available in the [[official repositories]], but it is also possible to download its source from its upstream [http://homepage.boetes.org/software/mg/ page]. Beware mg has no UTF-8 support.<br />
<br />
=== zile ===<br />
<br />
According to the official web [https://www.gnu.org/software/zile/ page] "GNU Zile is a lightweight Emacs clone. Zile is short for Zile Is Lossy Emacs. Zile has been written to be as similar as possible to Emacs; every Emacs user should feel at home.". Zile has no UTF-8 support.<br />
<br />
{{Pkg|zile}} can be found in the official repositories.<br />
<br />
the latest tarballs can be found in official GNU [http://ftp.sh.cvut.cz/MIRRORS/gnu/pub/gnu/zile/ mirrors].<br />
<br />
=== uemacs ===<br />
<br />
Micro-emacs version customized by Linus Torvalds. Available as {{AUR|uemacs-git}} in the [[AUR]].<br />
<br />
== See also ==<br />
<br />
* [http://www.gnu.org/software/emacs/ GNU Emacs home page]<br />
* [http://www.gnu.org/software/emacs/manual/emacs.html GNU Emacs manual]<br />
* [http://www.emacswiki.org/cgi-bin/wiki/ Emacs Wiki]<br />
* [http://wikemacs.org WikEmacs - a more readable, but less complete Emacs wiki]<br />
* [http://www2.lib.uchicago.edu/keith/tcl-course/emacs-tutorial.html Useful introduction to Emacs and its shortcuts]<br />
* [https://d0edfcdc0ccc1cd13cdab5eb986fb92e8660dbef.googledrive.com/host/0B6LMD0u8OhYYZEotN2QyR1hwR1k/ The Church of Emacs (via Google drive)]<br />
* [http://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf Official reference card]</div>Bricewgehttps://wiki.archlinux.org/index.php?title=OfflineIMAP&diff=356248OfflineIMAP2015-01-11T12:31:55Z<p>Bricewge: /* systemd Service */ Revert Require statment</p>
<hr />
<div>[[Category:Email clients]]<br />
{{Related articles start}}<br />
{{Related|isync}}<br />
{{Related|notmuch}}<br />
{{Related|msmtp}}<br />
{{Related articles end}}<br />
<br />
[http://offlineimap.org/ OfflineIMAP] is a Python utility to sync mail from IMAP servers. It does not work with the POP3 protocol or mbox, and is usually paired with a MUA such as [[Mutt]].<br />
<br />
==Installing==<br />
<br />
Install {{pkg|offlineimap}} from the [[official repositories]]. For a development version, install {{AUR|offlineimap-git}} from [[AUR]].<br />
<br />
==Configuring==<br />
<br />
Offlineimap is distributed with two default configuration files, which are both located in {{ic|/usr/share/offlineimap/}}. {{ic|offlineimap.conf}} contains every setting and is thorougly documented. Alternatively, {{ic|offlineimap.conf.minimal}} is not commented and only contains a small number of settings (see: [[#Minimal|Minimal]]).<br />
<br />
Copy one of the default configuration files to {{ic|~/.offlineimaprc}}.<br />
<br />
{{note|Writing a comment after an option/value on the same line is invalid syntax, hence take care that comments are placed on their own separate line.}}<br />
<br />
===Minimal===<br />
<br />
The following file is a commented version of {{ic|offlineimap.conf.minimal}}.<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
[general]<br />
# List of accounts to be synced, separated by a comma.<br />
accounts = main<br />
<br />
[Account main]<br />
# Identifier for the local repository; e.g. the maildir to be synced via IMAP.<br />
localrepository = main-local<br />
# Identifier for the remote repository; i.e. the actual IMAP, usually non-local.<br />
remoterepository = main-remote<br />
# Status cache. Default is plain, which eventually becomes huge and slow.<br />
status_backend = sqlite<br />
<br />
[Repository main-local]<br />
# Currently, offlineimap only supports maildir and IMAP for local repositories.<br />
type = Maildir<br />
# Where should the mail be placed?<br />
localfolders = ~/Maildir<br />
<br />
[Repository main-remote]<br />
# Remote repos can be IMAP or Gmail, the latter being a preconfigured IMAP.<br />
type = IMAP<br />
remotehost = host.domain.tld<br />
remoteuser = username<br />
</nowiki>}}<br />
<br />
==Usage==<br />
<br />
Before running offlineimap, create any parent directories that were allocated to local repositories:<br />
$ mkdir ~/Maildir<br />
<br />
Now, run the program:<br />
$ offlineimap<br />
<br />
Mail accounts will now be synced. If anything goes wrong, take a closer look at the error messages. OfflineIMAP is usually very verbose about problems; partly because the developers did not bother with taking away tracebacks from the final product.<br />
<br />
==Miscellaneous==<br />
<br />
===Running offlineimap in the background===<br />
<br />
Most other mail transfer agents assume that the user will be using the tool as a [[daemon]] by making the program sync periodically by default. In offlineimap, there are a few settings that control backgrounded tasks.<br />
<br />
Confusingly, they are spread thin all-over the configuration file:<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
# In the general section<br />
[general]<br />
# Controls how many accounts may be synced simultaneously<br />
maxsyncaccounts = 1<br />
<br />
# In the account identifier<br />
[Account main]<br />
# Minutes between syncs<br />
autorefresh = 5<br />
# Number of quick-syncs between autorefreshes. Quick-syncs do not update if the<br />
# only changes were to IMAP flags<br />
quick = 10<br />
<br />
# In the remote repository identifier<br />
[Repository main-remote]<br />
# Instead of closing the connection once a sync is complete, offlineimap will<br />
# send empty data to the server to hold the connection open. A value of 60<br />
# attempts to hold the connection for a minute between syncs (both quick and<br />
# autorefresh).This setting has no effect if autorefresh and holdconnectionopen<br />
# are not both set.<br />
keepalive = 60<br />
# OfflineIMAP normally closes IMAP server connections between refreshes if<br />
# the global option autorefresh is specified. If you wish it to keep the<br />
# connection open, set this to true. This setting has no effect if autorefresh<br />
# is not set.<br />
holdconnectionopen = yes<br />
</nowiki>}}<br />
<br />
====systemd Service====<br />
<br />
# Configure background jobs as shown in [[#Running offlineimap in the background]].<br />
# Writing a systemd service runnable as a user.<br />
<br />
{{hc|/etc/systemd/system/offlineimap@.service|<nowiki><br />
[Unit]<br />
Description=Start offlineimap as a daemon<br />
Requires=network-online.target<br />
After=network.target<br />
<br />
[Service]<br />
User=%i<br />
ExecStart=/usr/bin/offlineimap<br />
KillSignal=SIGUSR2<br />
Restart=always<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|If your configuration involves [[D-Bus]] operations, e.g. [[#Gnome keyring]], you should adapt this service for systemd user instance as described in [[systemd/User]] instead of using it directly. This approach is necessary to set the {{ic|DBUS_SESSION_BUS_ADDRESS}} variable correctly.}}<br />
<br />
===Automatic mutt mailbox generation===<br />
<br />
[[Mutt]] cannot be simply pointed to an IMAP or maildir directory and be expected to guess which subdirectories happen to be the mailboxes, yet offlineimap can generate a muttrc fragment containing the mailboxes that it syncs.<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
[mbnames]<br />
enabled = yes<br />
filename = ~/.mutt/mailboxes<br />
header = "mailboxes "<br />
peritem = "+%(accountname)s/%(foldername)s"<br />
sep = " "<br />
footer = "\n"<br />
</nowiki>}}<br />
<br />
Then add the following lines to {{ic|~/.mutt/muttrc}}.<br />
<br />
{{hc|~/.mutt/muttrc|<nowiki><br />
# IMAP: offlineimap<br />
set folder = "~/Mail"<br />
source ~/.mutt/mailboxes<br />
set spoolfile = "+account/INBOX"<br />
set record = "+account/Sent\ Items"<br />
set postponed = "+account/Drafts"<br />
</nowiki>}}<br />
<br />
{{ic|account}} is the name you have given to your IMAP account in {{ic|~/.offlineimaprc}}.<br />
<br />
===Gmail configuration===<br />
<br />
This remote repository is configured specifically for Gmail support, substituting folder names in uppercase for lowercase, among other small additions. Keep in mind that this configuration does not sync the ''All Mail'' folder, since it is usually unnecessary and skipping it prevents bandwidth costs:<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
[Repository gmail-remote]<br />
type = Gmail<br />
remoteuser = user@gmail.com<br />
remotepass = password<br />
nametrans = lambda foldername: re.sub ('^\[gmail\]', 'bak',<br />
re.sub ('sent_mail', 'sent',<br />
re.sub ('starred', 'flagged',<br />
re.sub (' ', '_', foldername.lower()))))<br />
folderfilter = lambda foldername: foldername not in '[Gmail]/All Mail'<br />
# Necessary as of OfflineIMAP 6.5.4<br />
sslcacertfile = /etc/ssl/certs/ca-certificates.crt<br />
</nowiki>}}<br />
<br />
{{Note|<br />
* If you have Gmail set to another language, the folder names may appear translated too, e.g. "verzonden_berichten" instead of "sent_mail".<br />
* After version 6.3.5, offlineimap also creates remote folders to match your local ones. Thus you may need a nametrans rule for your local repository too that reverses the effects of this nametrans rule.<br />
* As of 1 October 2012 gmail SSL certificate fingerprint is not always the same. This prevents from using {{ic|cert_fingerprint}} and makes the {{ic|sslcacertfile}} way a better solution for the SSL verification (see [[OfflineIMAP#SSL fingerprint does not match]]).<br />
}}<br />
<br />
===Not having to enter the password all the time===<br />
<br />
====.netrc====<br />
<br />
Add the following lines to your {{ic|~/.netrc}}:<br />
<br />
machine hostname.tld<br />
login [your username]<br />
password [your password]<br />
<br />
Do not forget to give the file appropriate rights like 600 or 700:<br />
$ chmod 600 ~/.netrc<br />
<br />
====Gnome keyring====<br />
<br />
In configuration for remote repositories the remoteusereval/remotepasseval fields can be set to custom python code that evaluates to the username/password. The code can be a call to a function defined in a Python script pointed to by 'pythonfile' config field. Create {{ic|~/.offlineimap.py}} according to either of the two options below and use it in the configuration:<br />
<br />
{{bc|<nowiki><br />
[general]<br />
pythonfile = ~/.offlineimap.py<br />
<br />
[Repository examplerepo]<br />
type = IMAP<br />
remotehost = mail.example.com<br />
remoteusereval = get_username("examplerepo")<br />
remotepasseval = get_password("examplerepo")<br />
</nowiki>}}<br />
<br />
===== Option 1: using gnomekeyring Python module =====<br />
<br />
{{hc|~/.offlineimap.py|<nowiki><br />
#!/usr/bin/python<br />
<br />
import gnomekeyring as gkey<br />
<br />
def set_credentials(repo, user, pw):<br />
KEYRING_NAME = "offlineimap"<br />
attrs = { "repo": repo, "user": user }<br />
keyring = gkey.get_default_keyring_sync()<br />
gkey.item_create_sync(keyring, gkey.ITEM_NETWORK_PASSWORD,<br />
KEYRING_NAME, attrs, pw, True)<br />
<br />
def get_credentials(repo):<br />
keyring = gkey.get_default_keyring_sync()<br />
attrs = {"repo": repo}<br />
items = gkey.find_items_sync(gkey.ITEM_NETWORK_PASSWORD, attrs)<br />
return (items[0].attributes["user"], items[0].secret)<br />
<br />
def get_username(repo):<br />
return get_credentials(repo)[0]<br />
def get_password(repo):<br />
return get_credentials(repo)[1]<br />
<br />
if __name__ == "__main__":<br />
import sys<br />
import os<br />
import getpass<br />
if len(sys.argv) != 3:<br />
print "Usage: %s <repository> <username>" \<br />
% (os.path.basename(sys.argv[0]))<br />
sys.exit(0)<br />
repo, username = sys.argv[1:]<br />
password = getpass.getpass("Enter password for user '%s': " % username)<br />
password_confirmation = getpass.getpass("Confirm password: ")<br />
if password != password_confirmation:<br />
print "Error: password confirmation does not match"<br />
sys.exit(1)<br />
set_credentials(repo, username, password)<br />
</nowiki>}}<br />
<br />
To set the credentials, run this script from a shell.<br />
<br />
===== Option 2: using {{AUR|gnome-keyring-query}} tool =====<br />
<br />
{{hc|~/.offlineimap.py|<nowiki><br />
#!/usb/bin/python<br />
# executes gnome-keyring-query get passwd<br />
# and returns the output<br />
<br />
import locale<br />
from subprocess import Popen, PIPE<br />
<br />
encoding = locale.getdefaultlocale()[1]<br />
<br />
def get_password(p):<br />
(out, err) = Popen(["gnome-keyring-query", "get", p], stdout=PIPE).communicate()<br />
return out.decode(encoding).strip()<br />
</nowiki>}}<br />
<br />
====python2-keyring====<br />
<br />
There is a general solution that should work for any keyring. Install [http://pypi.python.org/pypi/keyring python2-keyring] from [[AUR]], then change your ~/.offlineimaprc to say something like:<br />
<br />
{{bc|<nowiki><br />
[general]<br />
pythonfile = /home/user/offlineimap.py<br />
...<br />
[Repository RemoteEmail]<br />
remoteuser = username@host.net<br />
remotepasseval = keyring.get_password("offlineimap","username@host.net")<br />
...<br />
</nowiki>}}<br />
<br />
and somewhere in ~/offlineimap.py add {{ic|import keyring}}. Now all you have to do is set your password, like so:<br />
<br />
{{bc|$ python2 <br />
>>> import keyring<br />
>>> keyring.set_password("offlineimap","username@host.net", "MYPASSWORD")}}<br />
<br />
and it will grab the password from your (kwallet/gnome-) keyring instead of having to keep it in plaintext or enter it each time.<br />
<br />
====Emacs EasyPG====<br />
<br />
See http://www.emacswiki.org/emacs/OfflineIMAP#toc2<br />
<br />
====KeePass / KeePassX====<br />
<br />
Install {{AUR|python2-keepass-git}} from the AUR, then add the following to your offlineimap.py file:<br />
<br />
{{bc|<nowiki><br />
#!/usr/bin/python2<br />
import os, getpass<br />
from keepass import kpdb<br />
<br />
def get_keepass_pw(dbpath, title="", username=""):<br />
if os.path.isfile(dbpath):<br />
db = kpdb.Database(dbpath, getpass.getpass("Master password for '" + dbpath + "': "))<br />
for entry in db.entries:<br />
if (entry.title == title) and (entry.username == username):<br />
return entry.password<br />
else:<br />
print "Error: '" + dbpath + "' does not exist."<br />
return<br />
<br />
</nowiki>}}<br />
(Credit to aki--aki: https://gist.github.com/aki--aki/5180359)<br />
<br />
Next, edit your ~/.offlineimaprc:<br />
<br />
{{bc|<nowiki><br />
[general]<br />
# VVV Set this path correctly VVV<br />
pythonfile = /home/user/offlineimap.py<br />
...<br />
[Repository RemoteEmail]<br />
remoteuser = username@host.net<br />
# Set the DB path as well as the title and username of the specific entry you'd like to use.<br />
# This will prompt you on STDIN at runtime for the kdb master password.<br />
remotepasseval = get_keepass_pw("/path/to/database.kdb", title="<entry title>", username="<entry username>")<br />
...<br />
</nowiki>}}<br />
<br />
Note that as-is, this does not support KDBs with keyfiles, only KDBs with password-only auth.<br />
<br />
===Kerberos authentication===<br />
<br />
Install {{AUR|python2-kerberos}} from [[AUR]] and do not specify remotepass in your .offlineimaprc. <br />
OfflineImap figure out the reset all if have a valid Kerberos TGT. <br />
If you have 'maxconnections', it will fail for some connection. Comment 'maxconnections' out will solve this problem.<br />
<br />
==Troubleshooting==<br />
<br />
===Overriding UI and autorefresh settings===<br />
<br />
For the sake of troubleshooting, it is sometimes convenient to launch offlineimap with a more verbose UI, no background syncs and perhaps even a debug level:<br />
$ offlineimap [ -o ] [ -d <debug_type> ] [ -u <ui> ]<br />
;-o<br />
:Disable autorefresh, keepalive, etc.<br />
<br />
;-d <debug_type><br />
:Where ''<debug_type>'' is one of {{Ic|imap}}, {{Ic|maildir}} or {{Ic|thread}}. Debugging imap and maildir are, by far, the most useful.<br />
<br />
;-u <ui><br />
:Where ''<ui>'' is one of {{Ic|CURSES.BLINKENLIGHTS}}, {{Ic|TTY.TTYUI}}, {{Ic|NONINTERACTIVE.BASIC}}, {{Ic|NONINTERACTIVE.QUIET}} or {{Ic|MACHINE.MACHINEUI}}. TTY.TTYUI is sufficient for debugging purposes.<br />
<br />
{{Note|More recent versions use the following for <ui>: {{Ic|blinkenlights}}, {{Ic|ttyui}}, {{Ic|basic}}, {{Ic|quiet}} or {{Ic|machineui}}.}}<br />
<br />
===Folder could not be created===<br />
<br />
In version 6.5.3, offlineimap gained the ability to create folders in the remote repository, as described [http://comments.gmane.org/gmane.mail.imap.offlineimap.general/4784 here].<br />
<br />
This can lead to errors of the following form when using {{Ic|nametrans}} on the remote repository:<br />
ERROR: Creating folder bar on repository foo-remote<br />
Folder 'bar'[foo-remote] could not be created. Server responded: ('NO', ['[ALREADYEXISTS] Duplicate folder name bar (Failure)'])<br />
<br />
The solution is to provide an inverse {{Ic|nametrans}} lambda for the local repository, e.g.<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
[Repository foo-local]<br />
nametrans = lambda foldername: foldername.replace('bar', 'BAR')<br />
<br />
[Repository foo-remote]<br />
nametrans = lambda foldername: foldername.replace('BAR', 'bar')<br />
</nowiki>}}<br />
<br />
* For working out the correct inverse mapping. the output of {{Ic|offlineimap --info}} should help.<br />
* After updating the mapping, it may be necessary to remove all of the folders under {{Ic|$HOME/.offlineimap/}} for the affected accounts.<br />
<br />
===SSL fingerprint does not match===<br />
<br />
ERROR: Server SSL fingerprint 'keykeykey' for hostname 'example.com' does not match configured fingerprint. Please verify and set 'cert_fingerprint' accordingly if not set yet.<br />
<br />
To solve this, add to {{ic|~/.offlineimaprc}} (in the same section as {{ic|1=ssl = yes}}) one of the following:<br />
* either add {{ic|cert_fingerprint}}, with the certificate fingerprint of the remote server. This checks whether the remote server certificate matches the given fingerprint.<br />
cert_fingerprint = keykeykey<br />
* or add {{ic|sslcacertfile}} with the path to the system CA certificates file. Needs {{Pkg|ca-certificates}} installed. This validates the remote ssl certificate chain against the Certification Authorities in that file.<br />
sslcacertfile = /etc/ssl/certs/ca-certificates.crt<br />
<br />
== See also ==<br />
<br />
* [http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project Official OfflineIMAP mailing list]<br />
* [http://roland.entierement.nu/blog/2010/09/08/gnus-dovecot-offlineimap-search-a-howto.html Gnus, Dovecot, OfflineIMAP, search: a HOWTO]<br />
* [http://pbrisbin.com/posts/mutt_gmail_offlineimap/ Mutt + Gmail + Offlineimap] - An outline of brisbin's simple gmail/mutt setup using cron to keep offlineimap syncing.</div>Bricewgehttps://wiki.archlinux.org/index.php?title=OfflineIMAP&diff=356182OfflineIMAP2015-01-10T22:42:45Z<p>Bricewge: /* systemd Service */ Fix the Require statment</p>
<hr />
<div>[[Category:Email clients]]<br />
{{Related articles start}}<br />
{{Related|isync}}<br />
{{Related|notmuch}}<br />
{{Related|msmtp}}<br />
{{Related articles end}}<br />
<br />
[http://offlineimap.org/ OfflineIMAP] is a Python utility to sync mail from IMAP servers. It does not work with the POP3 protocol or mbox, and is usually paired with a MUA such as [[Mutt]].<br />
<br />
==Installing==<br />
<br />
Install {{pkg|offlineimap}} from the [[official repositories]]. For a development version, install {{AUR|offlineimap-git}} from [[AUR]].<br />
<br />
==Configuring==<br />
<br />
Offlineimap is distributed with two default configuration files, which are both located in {{ic|/usr/share/offlineimap/}}. {{ic|offlineimap.conf}} contains every setting and is thorougly documented. Alternatively, {{ic|offlineimap.conf.minimal}} is not commented and only contains a small number of settings (see: [[#Minimal|Minimal]]).<br />
<br />
Copy one of the default configuration files to {{ic|~/.offlineimaprc}}.<br />
<br />
{{note|Writing a comment after an option/value on the same line is invalid syntax, hence take care that comments are placed on their own separate line.}}<br />
<br />
===Minimal===<br />
<br />
The following file is a commented version of {{ic|offlineimap.conf.minimal}}.<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
[general]<br />
# List of accounts to be synced, separated by a comma.<br />
accounts = main<br />
<br />
[Account main]<br />
# Identifier for the local repository; e.g. the maildir to be synced via IMAP.<br />
localrepository = main-local<br />
# Identifier for the remote repository; i.e. the actual IMAP, usually non-local.<br />
remoterepository = main-remote<br />
# Status cache. Default is plain, which eventually becomes huge and slow.<br />
status_backend = sqlite<br />
<br />
[Repository main-local]<br />
# Currently, offlineimap only supports maildir and IMAP for local repositories.<br />
type = Maildir<br />
# Where should the mail be placed?<br />
localfolders = ~/Maildir<br />
<br />
[Repository main-remote]<br />
# Remote repos can be IMAP or Gmail, the latter being a preconfigured IMAP.<br />
type = IMAP<br />
remotehost = host.domain.tld<br />
remoteuser = username<br />
</nowiki>}}<br />
<br />
==Usage==<br />
<br />
Before running offlineimap, create any parent directories that were allocated to local repositories:<br />
$ mkdir ~/Maildir<br />
<br />
Now, run the program:<br />
$ offlineimap<br />
<br />
Mail accounts will now be synced. If anything goes wrong, take a closer look at the error messages. OfflineIMAP is usually very verbose about problems; partly because the developers did not bother with taking away tracebacks from the final product.<br />
<br />
==Miscellaneous==<br />
<br />
===Running offlineimap in the background===<br />
<br />
Most other mail transfer agents assume that the user will be using the tool as a [[daemon]] by making the program sync periodically by default. In offlineimap, there are a few settings that control backgrounded tasks.<br />
<br />
Confusingly, they are spread thin all-over the configuration file:<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
# In the general section<br />
[general]<br />
# Controls how many accounts may be synced simultaneously<br />
maxsyncaccounts = 1<br />
<br />
# In the account identifier<br />
[Account main]<br />
# Minutes between syncs<br />
autorefresh = 5<br />
# Number of quick-syncs between autorefreshes. Quick-syncs do not update if the<br />
# only changes were to IMAP flags<br />
quick = 10<br />
<br />
# In the remote repository identifier<br />
[Repository main-remote]<br />
# Instead of closing the connection once a sync is complete, offlineimap will<br />
# send empty data to the server to hold the connection open. A value of 60<br />
# attempts to hold the connection for a minute between syncs (both quick and<br />
# autorefresh).This setting has no effect if autorefresh and holdconnectionopen<br />
# are not both set.<br />
keepalive = 60<br />
# OfflineIMAP normally closes IMAP server connections between refreshes if<br />
# the global option autorefresh is specified. If you wish it to keep the<br />
# connection open, set this to true. This setting has no effect if autorefresh<br />
# is not set.<br />
holdconnectionopen = yes<br />
</nowiki>}}<br />
<br />
====systemd Service====<br />
<br />
# Configure background jobs as shown in [[#Running offlineimap in the background]].<br />
# Writing a systemd service runnable as a user.<br />
<br />
{{hc|/etc/systemd/system/offlineimap@.service|<nowiki><br />
[Unit]<br />
Description=Start offlineimap as a daemon<br />
Require=network-online.target<br />
After=network.target<br />
<br />
[Service]<br />
User=%i<br />
ExecStart=/usr/bin/offlineimap<br />
KillSignal=SIGUSR2<br />
Restart=always<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|If your configuration involves [[D-Bus]] operations, e.g. [[#Gnome keyring]], you should adapt this service for systemd user instance as described in [[systemd/User]] instead of using it directly. This approach is necessary to set the {{ic|DBUS_SESSION_BUS_ADDRESS}} variable correctly.}}<br />
<br />
===Automatic mutt mailbox generation===<br />
<br />
[[Mutt]] cannot be simply pointed to an IMAP or maildir directory and be expected to guess which subdirectories happen to be the mailboxes, yet offlineimap can generate a muttrc fragment containing the mailboxes that it syncs.<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
[mbnames]<br />
enabled = yes<br />
filename = ~/.mutt/mailboxes<br />
header = "mailboxes "<br />
peritem = "+%(accountname)s/%(foldername)s"<br />
sep = " "<br />
footer = "\n"<br />
</nowiki>}}<br />
<br />
Then add the following lines to {{ic|~/.mutt/muttrc}}.<br />
<br />
{{hc|~/.mutt/muttrc|<nowiki><br />
# IMAP: offlineimap<br />
set folder = "~/Mail"<br />
source ~/.mutt/mailboxes<br />
set spoolfile = "+account/INBOX"<br />
set record = "+account/Sent\ Items"<br />
set postponed = "+account/Drafts"<br />
</nowiki>}}<br />
<br />
{{ic|account}} is the name you have given to your IMAP account in {{ic|~/.offlineimaprc}}.<br />
<br />
===Gmail configuration===<br />
<br />
This remote repository is configured specifically for Gmail support, substituting folder names in uppercase for lowercase, among other small additions. Keep in mind that this configuration does not sync the ''All Mail'' folder, since it is usually unnecessary and skipping it prevents bandwidth costs:<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
[Repository gmail-remote]<br />
type = Gmail<br />
remoteuser = user@gmail.com<br />
remotepass = password<br />
nametrans = lambda foldername: re.sub ('^\[gmail\]', 'bak',<br />
re.sub ('sent_mail', 'sent',<br />
re.sub ('starred', 'flagged',<br />
re.sub (' ', '_', foldername.lower()))))<br />
folderfilter = lambda foldername: foldername not in '[Gmail]/All Mail'<br />
# Necessary as of OfflineIMAP 6.5.4<br />
sslcacertfile = /etc/ssl/certs/ca-certificates.crt<br />
</nowiki>}}<br />
<br />
{{Note|<br />
* If you have Gmail set to another language, the folder names may appear translated too, e.g. "verzonden_berichten" instead of "sent_mail".<br />
* After version 6.3.5, offlineimap also creates remote folders to match your local ones. Thus you may need a nametrans rule for your local repository too that reverses the effects of this nametrans rule.<br />
* As of 1 October 2012 gmail SSL certificate fingerprint is not always the same. This prevents from using {{ic|cert_fingerprint}} and makes the {{ic|sslcacertfile}} way a better solution for the SSL verification (see [[OfflineIMAP#SSL fingerprint does not match]]).<br />
}}<br />
<br />
===Not having to enter the password all the time===<br />
<br />
====.netrc====<br />
<br />
Add the following lines to your {{ic|~/.netrc}}:<br />
<br />
machine hostname.tld<br />
login [your username]<br />
password [your password]<br />
<br />
Do not forget to give the file appropriate rights like 600 or 700:<br />
$ chmod 600 ~/.netrc<br />
<br />
====Gnome keyring====<br />
<br />
In configuration for remote repositories the remoteusereval/remotepasseval fields can be set to custom python code that evaluates to the username/password. The code can be a call to a function defined in a Python script pointed to by 'pythonfile' config field. Create {{ic|~/.offlineimap.py}} according to either of the two options below and use it in the configuration:<br />
<br />
{{bc|<nowiki><br />
[general]<br />
pythonfile = ~/.offlineimap.py<br />
<br />
[Repository examplerepo]<br />
type = IMAP<br />
remotehost = mail.example.com<br />
remoteusereval = get_username("examplerepo")<br />
remotepasseval = get_password("examplerepo")<br />
</nowiki>}}<br />
<br />
===== Option 1: using gnomekeyring Python module =====<br />
<br />
{{hc|~/.offlineimap.py|<nowiki><br />
#!/usr/bin/python<br />
<br />
import gnomekeyring as gkey<br />
<br />
def set_credentials(repo, user, pw):<br />
KEYRING_NAME = "offlineimap"<br />
attrs = { "repo": repo, "user": user }<br />
keyring = gkey.get_default_keyring_sync()<br />
gkey.item_create_sync(keyring, gkey.ITEM_NETWORK_PASSWORD,<br />
KEYRING_NAME, attrs, pw, True)<br />
<br />
def get_credentials(repo):<br />
keyring = gkey.get_default_keyring_sync()<br />
attrs = {"repo": repo}<br />
items = gkey.find_items_sync(gkey.ITEM_NETWORK_PASSWORD, attrs)<br />
return (items[0].attributes["user"], items[0].secret)<br />
<br />
def get_username(repo):<br />
return get_credentials(repo)[0]<br />
def get_password(repo):<br />
return get_credentials(repo)[1]<br />
<br />
if __name__ == "__main__":<br />
import sys<br />
import os<br />
import getpass<br />
if len(sys.argv) != 3:<br />
print "Usage: %s <repository> <username>" \<br />
% (os.path.basename(sys.argv[0]))<br />
sys.exit(0)<br />
repo, username = sys.argv[1:]<br />
password = getpass.getpass("Enter password for user '%s': " % username)<br />
password_confirmation = getpass.getpass("Confirm password: ")<br />
if password != password_confirmation:<br />
print "Error: password confirmation does not match"<br />
sys.exit(1)<br />
set_credentials(repo, username, password)<br />
</nowiki>}}<br />
<br />
To set the credentials, run this script from a shell.<br />
<br />
===== Option 2: using {{AUR|gnome-keyring-query}} tool =====<br />
<br />
{{hc|~/.offlineimap.py|<nowiki><br />
#!/usb/bin/python<br />
# executes gnome-keyring-query get passwd<br />
# and returns the output<br />
<br />
import locale<br />
from subprocess import Popen, PIPE<br />
<br />
encoding = locale.getdefaultlocale()[1]<br />
<br />
def get_password(p):<br />
(out, err) = Popen(["gnome-keyring-query", "get", p], stdout=PIPE).communicate()<br />
return out.decode(encoding).strip()<br />
</nowiki>}}<br />
<br />
====python2-keyring====<br />
<br />
There is a general solution that should work for any keyring. Install [http://pypi.python.org/pypi/keyring python2-keyring] from [[AUR]], then change your ~/.offlineimaprc to say something like:<br />
<br />
{{bc|<nowiki><br />
[general]<br />
pythonfile = /home/user/offlineimap.py<br />
...<br />
[Repository RemoteEmail]<br />
remoteuser = username@host.net<br />
remotepasseval = keyring.get_password("offlineimap","username@host.net")<br />
...<br />
</nowiki>}}<br />
<br />
and somewhere in ~/offlineimap.py add {{ic|import keyring}}. Now all you have to do is set your password, like so:<br />
<br />
{{bc|$ python2 <br />
>>> import keyring<br />
>>> keyring.set_password("offlineimap","username@host.net", "MYPASSWORD")}}<br />
<br />
and it will grab the password from your (kwallet/gnome-) keyring instead of having to keep it in plaintext or enter it each time.<br />
<br />
====Emacs EasyPG====<br />
<br />
See http://www.emacswiki.org/emacs/OfflineIMAP#toc2<br />
<br />
====KeePass / KeePassX====<br />
<br />
Install {{AUR|python2-keepass-git}} from the AUR, then add the following to your offlineimap.py file:<br />
<br />
{{bc|<nowiki><br />
#!/usr/bin/python2<br />
import os, getpass<br />
from keepass import kpdb<br />
<br />
def get_keepass_pw(dbpath, title="", username=""):<br />
if os.path.isfile(dbpath):<br />
db = kpdb.Database(dbpath, getpass.getpass("Master password for '" + dbpath + "': "))<br />
for entry in db.entries:<br />
if (entry.title == title) and (entry.username == username):<br />
return entry.password<br />
else:<br />
print "Error: '" + dbpath + "' does not exist."<br />
return<br />
<br />
</nowiki>}}<br />
(Credit to aki--aki: https://gist.github.com/aki--aki/5180359)<br />
<br />
Next, edit your ~/.offlineimaprc:<br />
<br />
{{bc|<nowiki><br />
[general]<br />
# VVV Set this path correctly VVV<br />
pythonfile = /home/user/offlineimap.py<br />
...<br />
[Repository RemoteEmail]<br />
remoteuser = username@host.net<br />
# Set the DB path as well as the title and username of the specific entry you'd like to use.<br />
# This will prompt you on STDIN at runtime for the kdb master password.<br />
remotepasseval = get_keepass_pw("/path/to/database.kdb", title="<entry title>", username="<entry username>")<br />
...<br />
</nowiki>}}<br />
<br />
Note that as-is, this does not support KDBs with keyfiles, only KDBs with password-only auth.<br />
<br />
===Kerberos authentication===<br />
<br />
Install {{AUR|python2-kerberos}} from [[AUR]] and do not specify remotepass in your .offlineimaprc. <br />
OfflineImap figure out the reset all if have a valid Kerberos TGT. <br />
If you have 'maxconnections', it will fail for some connection. Comment 'maxconnections' out will solve this problem.<br />
<br />
==Troubleshooting==<br />
<br />
===Overriding UI and autorefresh settings===<br />
<br />
For the sake of troubleshooting, it is sometimes convenient to launch offlineimap with a more verbose UI, no background syncs and perhaps even a debug level:<br />
$ offlineimap [ -o ] [ -d <debug_type> ] [ -u <ui> ]<br />
;-o<br />
:Disable autorefresh, keepalive, etc.<br />
<br />
;-d <debug_type><br />
:Where ''<debug_type>'' is one of {{Ic|imap}}, {{Ic|maildir}} or {{Ic|thread}}. Debugging imap and maildir are, by far, the most useful.<br />
<br />
;-u <ui><br />
:Where ''<ui>'' is one of {{Ic|CURSES.BLINKENLIGHTS}}, {{Ic|TTY.TTYUI}}, {{Ic|NONINTERACTIVE.BASIC}}, {{Ic|NONINTERACTIVE.QUIET}} or {{Ic|MACHINE.MACHINEUI}}. TTY.TTYUI is sufficient for debugging purposes.<br />
<br />
{{Note|More recent versions use the following for <ui>: {{Ic|blinkenlights}}, {{Ic|ttyui}}, {{Ic|basic}}, {{Ic|quiet}} or {{Ic|machineui}}.}}<br />
<br />
===Folder could not be created===<br />
<br />
In version 6.5.3, offlineimap gained the ability to create folders in the remote repository, as described [http://comments.gmane.org/gmane.mail.imap.offlineimap.general/4784 here].<br />
<br />
This can lead to errors of the following form when using {{Ic|nametrans}} on the remote repository:<br />
ERROR: Creating folder bar on repository foo-remote<br />
Folder 'bar'[foo-remote] could not be created. Server responded: ('NO', ['[ALREADYEXISTS] Duplicate folder name bar (Failure)'])<br />
<br />
The solution is to provide an inverse {{Ic|nametrans}} lambda for the local repository, e.g.<br />
<br />
{{hc|~/.offlineimaprc|<nowiki><br />
[Repository foo-local]<br />
nametrans = lambda foldername: foldername.replace('bar', 'BAR')<br />
<br />
[Repository foo-remote]<br />
nametrans = lambda foldername: foldername.replace('BAR', 'bar')<br />
</nowiki>}}<br />
<br />
* For working out the correct inverse mapping. the output of {{Ic|offlineimap --info}} should help.<br />
* After updating the mapping, it may be necessary to remove all of the folders under {{Ic|$HOME/.offlineimap/}} for the affected accounts.<br />
<br />
===SSL fingerprint does not match===<br />
<br />
ERROR: Server SSL fingerprint 'keykeykey' for hostname 'example.com' does not match configured fingerprint. Please verify and set 'cert_fingerprint' accordingly if not set yet.<br />
<br />
To solve this, add to {{ic|~/.offlineimaprc}} (in the same section as {{ic|1=ssl = yes}}) one of the following:<br />
* either add {{ic|cert_fingerprint}}, with the certificate fingerprint of the remote server. This checks whether the remote server certificate matches the given fingerprint.<br />
cert_fingerprint = keykeykey<br />
* or add {{ic|sslcacertfile}} with the path to the system CA certificates file. Needs {{Pkg|ca-certificates}} installed. This validates the remote ssl certificate chain against the Certification Authorities in that file.<br />
sslcacertfile = /etc/ssl/certs/ca-certificates.crt<br />
<br />
== See also ==<br />
<br />
* [http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project Official OfflineIMAP mailing list]<br />
* [http://roland.entierement.nu/blog/2010/09/08/gnus-dovecot-offlineimap-search-a-howto.html Gnus, Dovecot, OfflineIMAP, search: a HOWTO]<br />
* [http://pbrisbin.com/posts/mutt_gmail_offlineimap/ Mutt + Gmail + Offlineimap] - An outline of brisbin's simple gmail/mutt setup using cron to keep offlineimap syncing.</div>Bricewgehttps://wiki.archlinux.org/index.php?title=REFInd&diff=355722REFInd2015-01-07T09:53:43Z<p>Bricewge: /* For kernels automatically detected by rEFInd */ Fix the path for refind_linux.conf-sample</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[ja:REFInd]]<br />
[[zh-CN:REFInd]]<br />
{{Related articles start}}<br />
{{Related|Arch boot process}}<br />
{{Related|Boot loaders}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related articles end}}<br />
{{Lowercase title}}<br />
rEFInd is a [[UEFI]] boot manager. It is a fork of the no-longer-maintained [http://refit.sourceforge.net/ rEFIt] and fixes many issues with respect to non-Mac UEFI booting. It is designed to be platform-neutral and to simplify booting multiple OSes.<br />
<br />
== Installation ==<br />
<br />
Install {{pkg|refind-efi}} from the [[Official repositories]]. <br />
<br />
=== Scripted configuration ===<br />
<br />
rEFInd includes the {{ic|/usr/bin/refind-install}} script to simplify the process of setting rEFInd as your default EFI boot entry. The script has several options for handling differing setups and UEFI implementations, but for many systems it should be sufficient to simply run<br />
<br />
# refind-install<br />
<br />
{{warning|Due to a [http://sourceforge.net/p/refind/discussion/general/thread/44d17e7f/ bug], the script will fail if you booted from the live media and the ESP is mounted to {{ic|/boot}}. You will get an an erroneous message that the UEFI partition isn't correctly formatted. You can edit {{ic|/usr/bin/refind-install}} to fix this. Find the function {{ic|FindMountedESP()}}, and add the {{ic|-w}} option to the command {{ic|grep "$InstallDir" /etc/mtab}} (e.g. {{ic|grep -w "$InstallDir" /etc/mtab}}).}}<br />
<br />
This will attempt to find and mount your [[UEFI#EFI_System_Partition|ESP]], copy rEFInd's files to {{ic|/EFI/refind/}} on the ESP, and add rEFInd as the default EFI boot entry using [[UEFI#efibootmgr]]. A variant of this command that should work on a wider variety of systems - by installing rEFInd to the default boot path {{ic|/EFI/BOOT/BOOT*.EFI}} - is the following (where '''/dev/sdXY''' is the partition of your ESP):<br />
<br />
# refind-install --usedefault '''/dev/sdXY''' --alldrivers<br />
<br />
Read the comments in the install script for an explanation of each option.<br />
<br />
After installing rEFInd's files to the ESP, verify that rEFInd has created {{ic|refind_linux.conf}} containing the required kernel parameters (e.g. {{ic|1=root=}}) in the same directory as your kernel. If it has not created this file, you will need to set up [[#Passing kernel parameters]] manually or you will most likely get a kernel panic on your next boot.<br />
<br />
By default, rEFInd will scan all of your drives (that it has drivers for) and add a boot entry for each EFI bootloader it finds, which should include your kernel (since Arch enables [[EFISTUB]] by default). So you may have a bootable system at this point.<br />
<br />
{{tip|It's always a good idea to edit the default config {{ic|/EFI/refind/refind.conf}} on the ESP to ensure that the default options work for you.}}<br />
<br />
=== Manual configuration ===<br />
<br />
{{Tip| rEFInd can boot Linux in many ways. See [http://www.rodsbooks.com/refind/linux.html The rEFInd Boot Manager: Methods of Booting Linux] for coverage of the various approaches.}}<br />
{{Note|For 32-bit EFI, replace '''x64''' with '''ia32''' in the commands below.}}<br />
<br />
If the {{ic|refind-install}} script does not work for you, rEFInd can be set up manually. For this example, we assume that your ESP is mounted to {{ic|/boot/efi}} and we will organize rEFInd's files in {{ic|/boot/efi/EFI/refind}}. Both of these paths can be changed to fit your situation.<br />
<br />
First, copy the executable to the ESP:<br />
<br />
# cp /usr/share/refind/refind_x64.efi /boot/efi/EFI/refind/<br />
<br />
Then use [[UEFI#efibootmgr]] to create a boot entry in the UEFI NVRAM (change X and Y to match the device and partition of your ESP). If you are installing rEFInd to the default UEFI path {{ic|/EFI/BOOT/BOOTX64.EFI}}, you can probably skip this step.<br />
<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_x64.efi -L "rEFInd"<br />
<br />
At this point, you should be able to reboot into rEFInd but it will not be able to boot your kernel. If your kernel does not reside on your ESP, rEFInd can mount your partitions to find it - provided it has the right drivers:<br />
<br />
# mkdir /boot/efi/EFI/refind/drivers<br />
# cp /usr/share/refind/drivers_x64/myrootfs_x64.efi /boot/efi/EFI/refind/drivers<br />
<br />
Now rEFInd should have a boot entry for your kernel, but it will not pass the correct kernel parameters. Set up [[#Passing kernel parameters]]. You should now be able to boot your kernel using rEFInd. If you are still unable to boot or if you want to tweak rEFInd's settings, many options can be changed with a config file:<br />
<br />
# cp /usr/share/refind/refind.conf-sample /boot/efi/EFI/refind/refind.conf<br />
<br />
The sample config is well commented and self-explanatory.<br />
<br />
Unless you've set {{ic|textonly}} in the config file, you should copy rEFInd's icons to get rid of the ugly placeholders:<br />
<br />
# cp -r /usr/share/refind/icons /boot/efi/EFI/refind/<br />
<br />
And you can try out the different included fonts by copying them and setting {{ic|font myfont.png}} in {{ic|refind.conf}}:<br />
<br />
# cp -r /usr/share/refind/fonts /boot/efi/EFI/refind/<br />
<br />
{{tip|Pressing F10 in rEFInd will save a screenshot to the top level directory of the ESP.}}<br />
<br />
== Passing kernel parameters ==<br />
<br />
There are two methods for setting the [[kernel parameters]] that rEFInd will pass to the kernel.<br />
<br />
=== For kernels automatically detected by rEFInd ===<br />
<br />
If rEFInd automatically detects your kernel, you can place a {{ic|refind_linux.conf}} file containing the kernel parameters in the same directory as your kernel. You can use {{ic|/usr/share/refind/refind_linux.conf-sample}} as a starting point. The first uncommented line of {{ic|refind_linux.conf}} will be the default parameters for the kernel. Subsequent lines will create entries in a submenu accessible using {{ic|+}}, {{ic|F2}}, or {{ic|Insert}}.<br />
<br />
Alternatively, try running:<br />
<br />
# refind-mkrlconf<br />
<br />
Which will attempt to find your kernel in {{ic|/boot}} and automatically generate {{ic|refind_linux.conf}}. The script will only set up the most basic kernel parameters, so be sure to check the file it created for correctness.<br />
<br />
If you don't specify an {{ic|1=initrd=}} parameter, rEFInd will automatically add it by searching for common RAM disk filenames in the same directory as the kernel. If you need multiple {{ic|1=initrd=}} parameters (e.g. for [[Microcode]]) you must specify them manually in {{ic|refind_linux.conf}}.<br />
<br />
=== Manual boot stanzas ===<br />
<br />
If your kernel is not autodetected, or if you simply want more control over the options for a menu entry, you can manually create boot entries using stanzas in {{ic|refind.conf}}. Ensure that {{ic|scanfor}} includes {{ic|manual}} or these entries won't appear in rEFInd's menu. Kernel parameters are set with the {{ic|options}} keyword. rEFInd will append the {{ic|1=initrd=}} parameter using the file specified by the {{ic|initrd}} keyword in the stanza. If you need additional initrds (e.g. for [[Microcode]]), you can specify them in {{ic|options}} (and the one specified by the {{ic|initrd}} keyword will be added to the end).<br />
<br />
{{hc|/boot/efi/EFI/refind/refind.conf|<nowiki><br />
...<br />
<br />
menuentry "Arch Linux" {<br />
icon /EFI/refind/icons/os_arch.png<br />
volume Boot<br />
loader /boot/vmlinuz-linux<br />
initrd /boot/initramfs-linux.img<br />
options "root=PARTUUID=XXXXXXXX rootfstype=XXXX rw add_efi_memmap"<br />
}<br />
</nowiki>}}<br />
<br />
It is likely that you will need to change {{ic|volume}} to match the label or partition number (e.g. {{ic|0:}}) of the partition where the kernel image resides. See [[Ext3#Assigning_a_label]] as an example of assigning a volume label.<br />
<br />
== Using rEFInd with an existing UEFI Windows installation ==<br />
<br />
{{Note|The usual caveats of [[Windows and Arch dual boot]] apply.}}<br />
<br />
rEFInd is compatible with the EFI system partition created by a UEFI Windows installation, so there is no need to create or format another FAT32 partition when installing Arch alongside Windows. Simply mount Windows' ESP and install rEFInd as usual. By default, rEFInd's autodetection feature should recognize any existing Windows/recovery bootloaders.<br />
<br />
== Upgrading rEFInd ==<br />
<br />
Pacman updates the rEFInd files in {{ic|/usr/share/refind}} and will not copy new files to the ESP for you. If {{ic|refind-install}} worked for your original installation of rEFInd, you can rerun it to copy the updated files. The new config file will be copied as {{ic|refind.conf-sample}} so that you can integrate changes into your config file using a diff tool. If your rEFInd required [[#Manual configuration]], you will need to copy the new files yourself.<br />
<br />
=== Systemd automation ===<br />
<br />
To automate this process, you need a .path file for watching for rEFInd updates and a .service file for copying the new files and updating the nvram.<br />
<br />
{{hc|/etc/systemd/system/refind_update.path|<nowiki><br />
[Unit]<br />
Description=path monitor for rEFInd updates<br />
<br />
[Path]<br />
PathChanged=/usr/share/refind<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{hc|/etc/systemd/system/refind_update.service|<nowiki><br />
[Unit]<br />
Description=rEFInd boot manager update<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/refind-install<br />
</nowiki>}}<br />
<br />
Then [[enable]] {{ic|refind_update.path}}.<br />
<br />
== Apple Macs ==<br />
<br />
{{AUR|mactel-boot}} from the [[AUR]] is an experimental "bless" utility for Linux. If that does not work, use "bless" from within OSX to set rEFInd as the default boot entry. Assuming your UEFISYS partition is mounted at {{ic|/mnt/efi}} within OSX, do<br />
<br />
# bless --setBoot --folder /mnt/efi/EFI/refind --file /mnt/efi/EFI/refind/refind_x64.efi<br />
<br />
== VirtualBox ==<br />
<br />
Currently, VirtualBox will only boot the default {{ic|/EFI/BOOT/BOOT*.EFI}} path, so {{ic|refind-install}} needs to be used with at least the {{ic|--usedefault}} option. See [[VirtualBox#Installation in EFI mode]] for more info.<br />
<br />
== See also ==<br />
<br />
* [http://www.rodsbooks.com/refind/ The rEFInd Boot Manager] by Roderick W. Smith.<br />
* {{ic|/usr/share/refind/docs/README.txt}}</div>Bricewgehttps://wiki.archlinux.org/index.php?title=Libvirt&diff=336060Libvirt2014-09-19T08:03:45Z<p>Bricewge: /* Run daemon */ change QEMU default group to the actual default one (https://projects.archlinux.org/svntogit/community.git/commit/trunk?h=packages/libvirt&id=ab0030d25354011c32c697fd12630f63e49d56ac)</p>
<hr />
<div>{{DISPLAYTITLE:libvirt}}<br />
[[Category:Virtualization]]<br />
[[ja:libvirt]]<br />
[[zh-CN:libvirt]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related articles end}}<br />
libvirt is a virtualization API and a daemon for managing virtual machines (VMs) -- remote or locally, using multiple virtualization back-ends ([[QEMU]]/[[KVM]], [[VirtualBox]], [[Xen]], etc), communally called ''hypervisors'' . <br />
== Installing ==<br />
<br />
On the server, [[pacman|install]] at least {{Pkg|libvirt}} '''and''' a virtualization back-end such as [[QEMU]]. Then depending on the use case:<br />
* If network connectivity within the virtual machine is desired (which is most likely to be the case), install either both {{Pkg|ebtables}} and {{Pkg|dnsmasq}} for the default NAT/DHCP networking, {{Pkg|bridge-utils}} for bridged networking or the three of them to cover every method.<br />
* If remote management over [[SSH]] is desired, install {{Pkg|openbsd-netcat}}.<br />
<br />
On the client:<br />
* If planning on using only the command line, install the {{Pkg|libvirt}} package which provides the [http://wiki.libvirt.org/page/FAQ#What_is_the_.27virsh_edit.27_command_and_how_do_I_use_it.3F recommended] {{ic|virsh}} utility.<br />
* If wishing to use a graphical application, install {{Pkg|virt-manager}} and {{Pkg|virtviewer}}.<br />
<br />
{{Note|The server and client can be the same physical machine. Many more applications using ''libvirt'''s API may be found on [http://libvirt.org/apps.html libvirt's official website].}}<br />
<br />
===Building libvirt for Xen===<br />
The [[PKGBUILD]] for both {{AUR|libvirt-git}} in the [[Arch User Repository|AUR]] and {{Pkg|libvirt}} in the [[official repositories]] currently disables [[Xen]] support with the {{ic|--without-xen}} flag during the make process. If you want to use libvirt for managing Xen, you will need to [https://projects.archlinux.org/svntogit/community.git/tree/libvirt/repos/community-x86_64/ grab the whole file set] to enable Xen support and build your own libvirt package using the [[Arch Build System]]. The {{AUR|xen}} package from the [[AUR]] is required to build libvirt with Xen support.<br />
<br />
The alternative XenAPI driver is lacking a package at the moment? (2010-05-23, friesoft)<br />
<br />
==Server configuration==<br />
<br />
Libvirt is not usable "out of the box". At a minimum, you must [[#Run daemon|run the daemon]] and [[#Authorization|configure authorization]]. It is also advisable to [[#Enable KVM acceleration for QEMU]].<br />
Main configuration folders are found in {{ic|/etc/libvirt}}. Lots of files are in a '''.xml''' format.<br />
<br />
===Run daemon===<br />
<br />
{{Accuracy|The following section contains contradictory information concerning which group should be set in {{ic|/etc/libvirt/qemu.conf}}: {{ic|kvm}} is listed in the [[Users_and_groups#Deprecated_or_unused_groups|deprecated or unused groups]] section of the wiki, and why should one create a {{ic|qemu}} group when immediately after it is asked to create a {{ic|libvirt}} group?}}<br />
<br />
Change default user and group in {{ic|/etc/libvirt/qemu.conf}} to {{ic|qemu:qemu}}, as QEMU defaults to {{ic|nobody:kvm}}. You will need to [[Users_and_groups|change]] to the {{ic|qemu}} user and {{ic|kvm}} group. Omitting to change to the KVM group will leave you when running {{ic|virt-install --connect qemu:///system }} with this error: <br />
{{bc|Starting install...<br />
ERROR internal error: process exited while connecting to monitor:<br />
Could not access KVM kernel module: Permission denied<br />
failed to initialize KVM: Permission denied}}<br />
<br />
<br />
Then, [[File_Permissions_and_Attributes#Changing ownership using the chown command|set ownership]] of the following directories {{ic|/var/run/libvirt/qemu/}}, {{ic|/var/lib/libvirt/qemu/}}, {{ic|/var/lib/libvirt/images/}} and {{ic|/var/cache/libvirt/qemu/}} to match the user:group ID that QEMU guests will be run as.<br />
<br />
Start/enable {{ic|libvirtd.service}} [[Systemd#Using units|using systemd]].<br />
<br />
{{Note|The Avahi daemon is used for local discovery of libvirt hosts via multicast-DNS. To disable this functionality, set {{ic|1=mdns_adv = 0}} in {{ic|/etc/libvirt/libvirtd.conf}}.}}<br />
<br />
===Authorization===<br />
<br />
First, you will need to create the ''libvirt'' [[Users and groups|group]] and add any users you want to have access to libvirt to that group.<br />
# groupadd libvirt<br />
# gpasswd -a ''user'' libvirt<br />
<br />
Any users that are currently logged in will need to log out and log back in to update their groups. Alternatively, the user can use the following command in the shell they will be launching libvirt from to update the group:<br />
$ newgrp libvirt<br />
<br />
Then you have to follow either [[#polkit authorization]] '''or''' [[#file-based permissions]]:<br />
<br />
====polkit authorization====<br />
To allow users that are in the ''libvirt'' group to manage virtual machines, you need to create the following file:<br />
<br />
{{hc|/etc/polkit-1/rules.d/50-org.libvirt.unix.manage.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.libvirt.unix.manage" &&<br />
subject.isInGroup("libvirt")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
</nowiki>}}<br />
<br />
Alternatively, you can grant only monitoring privileges with {{ic|org.libvirt.unix.monitor}}.<br />
<br />
For more information, see [http://wiki.libvirt.org/page/SSHPolicyKitSetup#Configuring_management_access_via_PolicyKit the libvirt wiki].<br />
<br />
====file-based permissions====<br />
To allow users that are in the ''libvirt'' group to manage virtual machines, you can uncomment the following lines (they are not all in the same location in the file):<br />
<br />
{{hc|/etc/libvirt/libvirtd.conf|<nowiki><br />
#unix_sock_group = "libvirt"<br />
#unix_sock_ro_perms = "0777"<br />
#unix_sock_rw_perms = "0770"<br />
#auth_unix_ro = "none"<br />
#auth_unix_rw = "none"<br />
</nowiki>}}<br />
<br />
{{Note|You may also wish to change {{ic|unix_sock_ro_perms}} from {{ic|0777}} to {{ic|0770}} to disallow read-only access to people who are not members of the ''libvirt'' group.}}<br />
<br />
===Enable KVM acceleration for QEMU===<br />
{{Merge|kvm|this section would fit better in the [[Qemu]] or [[kvm]] wiki. It has nothing to do with libvirt}}<br />
{{Note|[[KVM]] will conflict with [[VirtualBox]]. You cannot use KVM and VirtualBox at the same time.}}<br />
<br />
Running virtual machines with the usual [[QEMU]] emulation (i.e. without KVM), will be '''painfully slow'''. You definitely want to enable KVM support if your CPU supports it. To find out, run the following command:<br />
$ egrep --color "vmx|svm" /proc/cpuinfo<br />
<br />
If that command generates output, then your CPU supports hardware acceleration via KVM; if that command does ''not'' generate output, then you ''cannot use KVM''.<br />
<br />
If KVM is ''not'' working, you will find the following message in your {{ic|/var/log/libvirt/qemu/VIRTNAME.log}}:<br />
{{hc|/var/log/libvirt/qemu/VIRTNAME.log|<br />
Could not initialize KVM, will disable KVM support<br />
}}<br />
<br />
More info is available from the [http://www.linux-kvm.org/page/FAQ official KVM FAQ]<br />
<br />
==Usage: creation of a new VM==<br />
Libvirt management is mostly done with three tools : one GUI, '''virt-manager''', and two CLI commands: '''virsh''' (part of libvirt) and '''guestfish''' (part of [https://aur.archlinux.org/packages/libguestfs/libguestfs libguestfs]) . Both tools let you create and then manage your VM.<br />
{{tip|basic virsh usages<br />
* {{ic|$ virsh [options]...<command> [args...]}} run a virsch command from your shell <br />
{{hc|$ virsh #launch an interactive virsh session|# virsh }} <br />
* {{ic|$ virsh list}} show ''running'' domains (pool-list lists ''active'' pools)<br />
* {{ic|$ virsh list --all}} list ''all'' domains ((pool-list --all lists ''all'' pools)<br />
}}<br />
{{Note|the virsh command is run as a regular user. This user shall belongs to the ''libvirt'' group.}}<br />
===Creating a storage pool===<br />
A ''storage pool'' is a quantity of storage for use by virtual machines. Storage pools are often divided into storage volumes and the volumes are assigned to guest virtual machines as block devices. The pool can be:<br />
* a directory pool<br />
* a filesystem pool<br />
* a network filesystem pool<br />
* a logical volume pool<br />
<br />
====using virt-manager====<br />
<br />
First, connect to an existing server. Once you are there, right click and choose '''Details'''. Go to '''Storage''' and press the '''+''' icon at the lower left. Then just follow the wizard.<br />
<br />
====using virsh====<br />
Add a [[lvm|logical volume]] pool when assuming there is already a '''vg0/''myStoragePool''''' LVM volume with some free space on it, as shown by the command output below.<br />
{{hc|# vgs|<br />
VG #PV #LV #SN Attr VSize VFree<br />
vg0 1 6 0 wz--n- 1.5t 150G<br />
}}<br />
We want now use the free space as a storage pool on a virsh interactive session.<br />
{{bc|# virsh<br />
<br />
virsh # pool-define-as ''myPoolName'' fs - - /dev/vg0/''myStoragePool'' - "''myMntPoint''"<br />
Pool ''myPoolName'' defined<br />
<br />
virsh# pool-build ''myPoolName''<br />
Pool ''myPoolName'' built<br />
<br />
virsh # pool-start ''myPoolName''<br />
Pool ''myPoolName'' started<br />
<br />
virsh # pool-list --all<br />
Name State Autostart<br />
<br />
default active yes<br />
''myPoolName'' active no<br />
<br />
virsh # pool-autostart ''myPoolName''<br />
Pool ''myPoolName'' marked as autostarted<br />
<br />
virsh # pool-info ''myPoolName''<br />
Name: ''myPoolName''<br />
UUID: 71dcb73a-6af9-4595-8208-a1c83e1ec6c7<br />
State: running<br />
Persistent: yes<br />
Autostart: yes<br />
Capacity: 1.5 t<br />
Allocation: 1 t<br />
Available: 150G<br />
<br />
virsh # quit<br />
}}<br />
<br />
{{Note|<br />
* libvirt will in fact change the ''myPoolName'' to ''myMntPoint''. When lisitng pools, the name will thus be ''myMntPoint''<br />
* a new ''myPoolName''.xml file has been created in {{ic|/etc/libvirt/storage}}<br />
* a new mountpoint ''myMntPoint'' directory is created<br />
* you can remove the default pool with the command {{ic|$ virsh pool-undefine default}}<br />
* the LVM volume vg0/''myStoragePool'' will be automatically mounted on the defined ''myMntPoint'' when VM is starting. No need to deal with it in your {{ic|/etc/fstab}}<br />
}}<br />
{{Tip|<br />
* Best practice is to dedicate a volume group to your storage pool only. Storage pool will be auto-started and could either contains volume you do not want to mount<br />
* Do not use your LVM volume group as your pool name, otherwise when deleting the pool storage you will delete your LVM group too<br />
}}<br />
<br />
===Creating a storage volume===<br />
Once the pool has been created, volumes for each VM can be created inside the pool.<br />
<br />
====Using virsh====<br />
{{bc|# virsh<br />
<br />
virsh # vol-create-as ''myPoolName'' volume1 120G<br />
Vol volume1 created<br />
<br />
# virsh vol-list ''myPoolName''<br />
Name Path<br />
<br />
volume1 ''myMntPoint''/volume1<br />
<br />
# virsh vol-dumpxml --pool ''myPoolName'' volume1<br />
<--------><br />
info on volume1 in xml format <br />
<---------><br />
<br />
}}<br />
<br />
{{Note|<br />
* the {{ic|vol-create}} command will take a while<br />
* a new file volume1 for installing the VM on has been created in ''myMntPoint''<br />
* to ''delete'' a volume, use this command {{ic| virsh # vol-delete volume1 --pool ''myPoolName''}}<br />
}}<br />
<br />
===Installing a new VM===<br />
To create a new VM, you need some sort of installation media, which is usually a standard {{ic|.iso}} file. Copy it to the {{ic|/var/lib/libvirt/images/}} directory (alternatively, you can create a new ''storage pool'' directory in virt-manager and copy it there).<br />
<br />
{{Note|[[SELinux]] requires that virtual machines be stored in {{ic|/var/lib/libvirt/images/}} by default. If you use SELinux and are having issues with virtual machines, ensure that your VMs are in that directory or ensure that you have added the correct labeling to the non-default directory that you used.}}<br />
<br />
====using virt-manager====<br />
<br />
Then run {{ic|virt-manager}}, connect to the server, right click on the connection and choose '''New'''. Choose a name, and select '''Local install media'''. Just continue with the wizard.<br />
<br />
On the '''4th step''', you may want to uncheck ''Allocate entire disk now'' -- this way you will save space when your VM is not using all of its disk. However, this can cause increased fragmentation of the disk, and you ''must'' pay attention to the total available disk space on the VM host because it is much easier to over-allocate disk space to VMs.<br />
<br />
On the '''5th step''', open '''Advanced options''' and make sure that ''Virt Type'' is set to '''kvm'''. If the kvm choice is not available, see section [[#Enable KVM acceleration for QEMU|Enable KVM acceleration for QEMU]] above.<br />
<br />
====using virt-install====<br />
The {{ic|$ virt-install}} command let you create the new VM with many arguments and sub options. For a complete list of arguments, please see [[http://linux.die.net/man/1/virt-install man virt-install]].<br />
<br />
The command will take this pattern:<br />
{{ic|$ virt-install --connect ''hypervisor'':///system [list of arguments and options]}}. <br />
{{Note| <br />
* {{ic|///session}} let you create/manage guests as a regular '''user'''. {{ic|///system}} create guests run by the system libvirtd instance.<br />
* ''hypervisor'' can of course be [[Qemu]], [[Xen]], [[Linux_Containers|lxc]].<br />
}}.<br />
<br />
Below is a basic command with most useful arguments. For clarification, the '''qemu''' hypervisor is used, the installed OS is '''windows8'''. <br />
{{bc|<nowiki> $ virt-install --connect qemu:///system \<br />
--name=myVMname \ # name of your VM<br />
--memory=2048 \ # ram you want to allocate<br />
--os-variant=win7 \ # type of os for the VM- win7 OR later<br />
--disk /path/to/myMntPoint/volume1 \ # point to the VM image<br />
--virt-type kvm \ # virtualization type<br />
--cdrom /dev/cdrom \ # use your guest cdrom <br />
--disk /path/to/iso/file,cdrom \ # path to guest .iso file. It will be on a cdrom device in the w8 guest and will be added as a storage pool.<br />
--controller scsi,model=virtio-scsi # use virtio<br />
</nowiki>}}<br />
<br />
{{Note|<br />
* the above command will create a {{ic|'''$XDG_CONFIG_HOME'''/libvirt/qemu/myVMname.xml}} file. This file can be edited later to more precised options.<br />
* the new VM is listed in '''virt-manager'''<br />
* As of 2014-08-20, the [http://www.spice-space.org/ spice protocol] does not provide windows binaries for w8. In case you really want this graphic protocol, you have to stick to w7 and add this line {{ic|--graphics spice}} to the {{ic|virt-install}} command.<br />
}}<br />
{{Tip| <br />
* it is possible to create a VM using an existing ''configuration_file.xml'' with the following command {{ic| $ visrh create ''configuration_file.xml''}}<br />
* most drivers and fine tuning sub options can be modified/added later when managing the VM. Best is to start with a basic install. For example, the above command will make the VM use the NAT network. If a more sophisticated network is wanted (like a bridge), do it later.}}<br />
<br />
====Using VirtualBox with virt-manager====<br />
{{Merge|virtualbox|this section would fit better in virtualbox wiki}}<br />
{{Note|[[VirtualBox]] support in libvirt is not quite stable yet and may cause your libvirtd to crash. Usually this is harmless and everything will be back once you restart the daemon.}}<br />
<br />
virt-manager does not let you to add any VirtualBox connections from the GUI. However, you can launch it from the command line:<br />
virt-manager -c vbox:///system<br />
<br />
Or if you want to manage a remote system over SSH:<br />
<nowiki>virt-manager -c vbox+ssh://username@host/system</nowiki><br />
<br />
==Usage: management of a VM==<br />
=== Using virt-manager ===<br />
The usage is pretty straightforward. Start the '''Virtual Machine Manager''', then click on the desired listed machine. It will then open the VM windows. Under the ''View'' menu, select ''Details''. You will see a new window with everything needed to list/view/add/modify ''Hardware''.<br />
<br />
=== Using virsh ===<br />
==== Starting KVM virtual machines on boot up ====<br />
<br />
At the command line, to set a VM to automatically start at boot-up, run:<br />
<br />
$ virsh autostart <domain><br />
<br />
To disable automatic starting:<br />
<br />
$ virsh autostart --disable <domain><br />
<br />
''virt-manager'' is equally easy having an autostart check box in the boot options of the VM.<br />
<br />
{{Note|VMs started by QEMU or KVM from the command line are not then manageable by ''virt-manager''.}}<br />
====Stopping / resuming guest at host shutdown / startup ====<br />
Running guests may be suspended (or shutdown) at host shutdown automatically using the {{ic|libvirt-guests.service}} systemd service. This same daemon will resume (startup) the suspended (shutdown) guests automatically at host startup.<br />
Check {{ic|/etc/conf.d/libvirtd-guests}} for libvirt-guests options.<br />
<br />
==== Live snapshots ====<br />
A feature called external snapshotting allows one to take a live snapshot of a virtual machine without turning it off. Currently it only works with qcow2 and raw file based images.<br />
<br />
Once a snapshot is created, KVM attaches that new snapshotted image to virtual machine that is used as its new block device, storing any new data directly to it while the original disk image is taken offline which you can easily copy or backup. After that you can merge the snapshotted image to the original image, again without shutting down your virtual machine.<br />
<br />
Here's how it works.<br />
<br />
Currently running virtual machines:<br />
{{hc|# virsh list|<nowiki><br />
Id Name State<br />
----------------------------------------------------<br />
3 archey running<br />
</nowiki>}}<br />
<br />
List all its current images:<br />
{{hc|# virsh domblklist archey|<nowiki><br />
Target Source<br />
------------------------------------------------<br />
vda /vms/archey.img<br />
</nowiki>}}<br />
<br />
Notice the image file properties<br />
{{hc|# qemu-img info /vms/archey.img|<nowiki><br />
image: /vms/archey.img<br />
file format: qcow2<br />
virtual size: 50G (53687091200 bytes)<br />
disk size: 2.1G<br />
cluster_size: 65536<br />
</nowiki>}}<br />
<br />
Create a disk-only snapshot. The switch {{ic|--atomic}} makes sure that the VM is not modified if snapshot creation fails.<br />
# virsh snapshot-create-as archey snapshot1 --disk-only --atomic<br />
<br />
List if you want to see the snapshots:<br />
{{hc|# virsh snapshot-list archey|<nowiki><br />
Name Creation Time State<br />
------------------------------------------------------------<br />
snapshot1 2012-10-21 17:12:57 -0700 disk-snapshot<br />
</nowiki>}}<br />
<br />
Notice the new snapshot image created by virsh and its image properties. It weighs just a few MiBs and is linked to its original "backing image/chain".<br />
{{hc|# qemu-img info /vms/archey.snapshot1|<nowiki><br />
image: /vms/archey.snapshot1<br />
file format: qcow2<br />
virtual size: 50G (53687091200 bytes)<br />
disk size: 18M<br />
cluster_size: 65536<br />
backing file: /vms/archey.img<br />
</nowiki>}}<br />
<br />
At this point, you can go ahead and copy the original image with {{ic|1=cp -sparse=true}} or {{ic|rsync -S}}. <br />
Then you can merge the original image back into the snapshot.<br />
# virsh blockpull --domain archey --path /vms/archey.snapshot1<br />
<br />
Now that you have pulled the blocks out of original image, the file {{ic|/vms/archey.snapshot1}} becomes the new disk image. Check its disk size to see what it means. After that is done, the original image {{ic|/vms/archey.img}} and the snapshot metadata can be deleted safely. The {{ic|virsh blockcommit}} would work opposite to {{ic|blockpull}} but it seems to be currently under development in qemu-kvm 1.3 (including snapshot-revert feature), scheduled to be released sometime next year.<br />
<br />
This new feature of KVM will certainly come handy to the people who like to take frequent live backups without risking corruption of the file system.<br />
<br />
==Remote access to libvirt==<br />
<br />
===Using unencrypted TCP/IP socket (most simple, least secure)===<br />
{{Warning|This should ''only'' be used for testing or use over a secure, private, and trusted network.}}<br />
<br />
Edit {{ic|/etc/libvirt/libvirtd.conf}}:<br />
{{hc|/etc/libvirt/libvirtd.conf|<nowiki><br />
listen_tls = 0<br />
listen_tcp = 1<br />
auth_tcp=none<br />
</nowiki>}}<br />
<br />
{{Warning|We do not enable SASL here, so all TCP traffic is cleartext! For real world use, ''always'' enable SASL.}}<br />
<br />
It is also necessary to start the server in listening mode by editing {{ic|/etc/conf.d/libvirtd}} <br />
{{hc|/etc/conf.d/libvirtd|2=LIBVIRTD_ARGS="--listen"}}<br />
<br />
===Using SSH===<br />
The {{Pkg|openbsd-netcat}} package is needed for remote management over [[SSH]].<br />
<br />
To connect to the remote system using {{ic|virsh}}:<br />
$ virsh -c qemu+ssh://''username''@''host''/system<br />
<br />
If something goes wrong, you can get some logs using:<br />
$ LIBVIRT_DEBUG=1 virsh -c qemu+ssh://''username''@''host''/system<br />
<br />
To display the graphical console for a virtual machine:<br />
$ virt-viewer --connect qemu+ssh://''username''@''host''/system myvirtualmachine<br />
<br />
To display the virtual machine desktop management tool:<br />
$ virt-manager -c qemu+ssh://''username''@''host''/system<br />
<br />
{{Note|If you are having problems connecting to a remote RHEL server (or anything other than Arch, really), try the two workarounds mentioned in {{bug|30748}} and {{bug|22068}}.}}<br />
<br />
=== Using Python ===<br />
The {{Pkg|libvirt-python}} package provides a {{Pkg|python2}} API in {{ic|/usr/lib/python2.7/site-packages/libvirt.py}}.<br />
<br />
General examples are given in {{ic|/usr/share/doc/libvirt-python-''your_libvirt_version''/examples/}}<br />
<br />
Unofficial example using {{Pkg|qemu}} and {{Pkg|openssh}}:<br />
<br />
#! /usr/bin/env python2<br />
# -*- coding: utf-8 -*-<br />
import socket<br />
import sys<br />
import libvirt<br />
if (__name__ == "__main__"):<br />
<nowiki>conn = libvirt.open("qemu+ssh://xxx/system")</nowiki><br />
print "Trying to find node on xxx"<br />
domains = conn.listDomainsID()<br />
for domainID in domains:<br />
domConnect = conn.lookupByID(domainID)<br />
if domConnect.name() == 'xxx-node':<br />
print "Found shared node on xxx with ID " + str(domainID)<br />
domServ = domConnect<br />
break<br />
<br />
== Bridged networking ==<br />
To use ''physical Ethernet'' from your virtual machines, you have to create a ''bridge'' between your physical Ethernet device (here ''eth0'') and the virtual Ethernet device the VM is using.<br />
<br />
=== Host configuration ===<br />
<br />
libvirt creates the bridge ''virbr0'' for NAT networking, so use another name such as ''br0'' or ''virbr1''.<br />
You have to create a new [[Netctl]] or [[Systemd-networkd]] profile to configure the bridge, for example (with DHCP configuration):<br />
<br />
{{hc|/etc/netctl/br0|<nowiki><br />
Description="Bridge connection for kvm"<br />
Interface=br0<br />
Connection=bridge<br />
BindsToInterfaces=(eno1)<br />
IP=dhcp<br />
</nowiki>}}<br />
<br />
{{out of date|The tip below needs to be updated for [[netctl]].}}<br />
{{Tip|It is recommended that you enable [[Wikipedia:Spanning_Tree_Protocol|Spanning Tree Protocol]] (STP) on the virtual bridge (e.g. ''br0'') that you create to avoid any potential bridging loops. You can automatically enable STP by appending {{ic|1=POST_UP="brctl stp $INTERFACE on"}} to the netcfg profile.}}<br />
<br />
=== Guest configuration ===<br />
Now we have to activate the ''bridge interface'' in our ''VMs''.<br />
If have a recent Linux machine, you can use this code in the ''.xml'' file:<br />
<br />
[...]<br />
<interface type='bridge'><br />
<source bridge='br0'/><br />
<mac address='24:42:53:21:52:49'/><br />
<model type='virtio' /><br />
</interface><br />
[...]<br />
<br />
This code activates a ''virtio'' device on the machine so, in Windows you will have to install an additional driver (you can find it here [http://www.linux-kvm.org/page/WindowsGuestDrivers/Download_Drivers Windows KVM VirtIO drivers]) or remove the line {{ic|<model type<nowiki>=</nowiki>'virtio' />}}:<br />
<br />
[...]<br />
<interface type='bridge'><br />
<source bridge='br0'/><br />
<mac address='24:42:53:21:52:49'/><br />
</interface><br />
[...]<br />
<br />
== See also ==<br />
* [http://libvirt.org/drvqemu.html libvirt web site]<br />
* [http://www-01.ibm.com/support/knowledgecenter/linuxonibm/liaat/liaatkvm.htm IBM KVM]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Virtualization_Administration_Guide/index.html Red Hat enterprise Linux 6 virtualization guide]</div>Bricewgehttps://wiki.archlinux.org/index.php?title=Talk:Libvirt&diff=335991Talk:Libvirt2014-09-18T16:26:31Z<p>Bricewge: /* kvm group */ new section</p>
<hr />
<div>==Xen integration?==<br />
What is the reasoning behind disabling Xen integration? I'm tempted to open a bug for the missing Xen integration, but I assume there is a reason it is excluded.<br />
<br />
-- [[User:TripleSpeeder|TripleSpeeder]] ([[User talk:TripleSpeeder|talk]]) 14:43, 27 November 2012 (UTC)<br />
<br />
:I'm assuming that Xen integration is disabled because {{AUR|xen}} is not in the official repositories. Even if an Arch user manages Xen VMs on remote systems (I'm assuming the remote systems are not running Arch), enabling Xen support in Arch's {{Pkg|libvirt}} package isn't going to help because when you connect to a remote VM host, you are connecting to the remote host's libvirt daemon, so only the remote host would need libvirt to support Xen. You could open an issue on the bug tracker requesting that Xen support be enabled, but I'm guessing it won't happen.<br />
:-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 03:25, 5 December 2013 (UTC)<br />
<br />
==libvirt-guests and systemd==<br />
libvirt-guests does not work with systemd. At least not without modification to the scripts. <br />
To enable a guest to auto-start you can either check the "autostart" box in virt-manager, enable autostart through virsh or you can manually create a symlink in the libvirt auto-start directory.<br />
<br />
To automatically start a guest named www that runs in qemu<br />
<pre><nowiki><br />
ln -s /etc/libvirt/qemu/www.xml /etc/libvirt/qemu/autostart/www.xml<br />
</nowiki></pre><br />
--[[User:En0|En0]] ([[User talk:En0|talk]]) 14:35, 10 December 2012 (UTC)<br />
<br />
==KVM acceleration after removing qemu-kvm package==<br />
In order to have KVM acceleration after the removal of [[KVM|qemu-kvm]] I had to edit the config of my virtual machines like this:<br />
<br />
<pre><nowiki><br />
<domain type='qemu' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'><br />
...<br />
<qemu:commandline><br />
<qemu:arg value='-machine'/><br />
<qemu:arg value='accel=kvm'/><br />
<qemu:arg value='kernel_irqchip=on' /><br />
</qemu:commandline><br />
</domain><br />
</nowiki></pre><br />
<br />
I don't know if there is some specific field in libvirt XML, but this works for me.<br />
<br />
--[[User:Vimes656|Vimes656]] ([[User talk:Vimes656|talk]]) 13:16, 7 March 2013 (UTC)Vimes656<br />
<br />
==Chip-level IRQs==<br />
Added chip level IRQs to the argument list of Vimes656 recommendation. <br />
<br />
--[[User:En0|En0]] ([[User talk:En0|talk]]) 15:49, 7 March 2013 (UTC)<br />
<br />
== bridged network edit ==<br />
<br />
note: sorry this is typed all lowercase (broken wrist)<br />
<br />
im looking to do an edit on bridged networking section im looking for a suggestion as what to keep since netcfg is deprecated...<br />
<br />
i pretty much want to layout how to set a bridge with netctl...<br />
<br />
Host<br />
<br />
first find your network device to bridge...<br />
<br />
ip a<br />
<br />
it should be somthing along the lines of enpXXX<br />
<br />
next create the bridge profile for netctl, then start and enable it<br />
<br />
/etc/netctl/br0<br />
<br />
Description="Internet bridge"<br />
Interface=br0<br />
Connection=bridge<br />
BindsToInterfaces=(enp8s) <br />
IP=dhcp<br />
<br />
netctl start br0<br />
<br />
netctl enable br0<br />
<br />
Guest<br />
<br />
now this is where i need suggestions...is the current info relevant?<br />
<br />
all i did was setup my vm to use br0 in virt-manager<br />
<br />
i will go through these steps i used virt-manager but dont want to delete info if it isnt deprecate<br />
<br />
:(Sorry for your wrist)<br />
<br />
:Please don't delete anything if you're not sure of what you're doing: add templates like [[Template:Accuracy]] or [[Template:Out of date]] where appropriate instead. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:35, 16 July 2013 (UTC)<br />
<br />
::Kynikos, just wondering if the info is still relevant as i took a totally different approach with virt-manager, ill go ahead and post my relevant info, removing only the deprecated netcfg stuff --[[User:Dzavitz|Dzavitz]] ([[User talk:Dzavitz|talk]]) 06:21, 17 July 2013 (UTC)<br />
<br />
:::Ok, just always remember to use the Edit Summary, thank you. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 08:28, 17 July 2013 (UTC)<br />
<br />
== kvm group ==<br />
<br />
About the disput of using or not the kvm group, the discussion which lead to adding this group in the [[Users_and_groups#Deprecated_or_unused_groups|depreceated group list]] is [https://wiki.archlinux.org/index.php?title=Talk:KVM&oldid=283995#kvm_user_group there]; deleted from the talk page of KVM article.<br />
[[User:Bricewge|Bricewge]] ([[User talk:Bricewge|talk]]) 16:26, 18 September 2014 (UTC)</div>Bricewgehttps://wiki.archlinux.org/index.php?title=Unified_Extensible_Firmware_Interface&diff=320448Unified Extensible Firmware Interface2014-06-16T19:16:56Z<p>Bricewge: /* OVMF for Virtual Machines */ Change options -bios to -pflash</p>
<hr />
<div>[[Category:Boot process]]<br />
[[es:Unified Extensible Firmware Interface]]<br />
[[it:Unified Extensible Firmware Interface]]<br />
[[ja:Unified Extensible Firmware Interface]]<br />
[[ru:Unified Extensible Firmware Interface]]<br />
[[zh-CN:Unified Extensible Firmware Interface]]<br />
{{Related articles start}}<br />
{{Related|Arch boot process}}<br />
{{Related|Master Boot Record}}<br />
{{Related|GUID Partition Table}}<br />
{{Related articles end}}<br />
<br />
'''Unified Extensible Firmware Interface''' (or UEFI for short) is a new type of firmware that was initially designed by Intel (known as EFI then) mainly for its Itanium based systems. It introduces new ways of booting an OS that is distinct from the commonly used "[[MBR]] boot code" method followed for [[Wikipedia:BIOS|BIOS]] systems. It started as Intel's EFI in versions 1.x and then a group of companies called the UEFI Forum took over its development from which it was called Unified EFI starting with version 2.0. As of 24 July 2013, UEFI Specification 2.4 (released July 11, 2013) is the most recent version.<br />
<br />
{{Note|<br />
* This page explains '''What is UEFI''' and '''UEFI support in Linux kernel'''. It does not describe setting up UEFI Boot Loaders. For that information see [[Boot loaders]].<br />
* Unless specified as EFI 1.x, EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware. Also unless stated explicitly, these instructions are general and some of them may not work or may be different in Apple Macs. Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one (U)EFI specification and therefore is not a standard UEFI firmware.}}<br />
<br />
== Differences between BIOS and UEFI ==<br />
<br />
See [[Arch boot process#Firmware_types]] for more details.<br />
<br />
== Boot Process under UEFI ==<br />
<br />
# System switched on - Power On Self Test, or POST process.<br />
# UEFI firmware is loaded. Firmware initializes the hardware required for booting.<br />
# Firmware then reads its Boot Manager data to determine which UEFI application to be launched and from where (i.e. from which disk and partition).<br />
# Firmware then launches the UEFI application as defined in the boot entry in the firmware's boot manager.<br />
# The launched UEFI application may launch another application (in case of UEFI Shell or a boot manager like rEFInd) or the kernel and initramfs (in case of a boot loader like GRUB) depending on how the UEFI application was configured.<br />
<br />
{{Note|On some UEFI systems the only possible way to launch UEFI application on boot (if it does not have custom entry in UEFI boot menu) is to put it in this fixed location: {{ic|<EFI SYSTEM PARTITION>/EFI/BOOT/BOOTX64.EFI}} (for 64-bit x86 system)}}<br />
<br />
=== Multibooting in UEFI ===<br />
<br />
Since each OS or vendor can maintain its own files within the EFI System Partition without affecting the other, multi-booting using UEFI is just a matter of launching a different UEFI application corresponding to the particular OS's bootloader. This removes the need for relying on chainloading mechanisms of one [[Boot loaders|boot loader]] to load another to switch OSes.<br />
<br />
==== Booting Microsoft Windows ====<br />
<br />
<br />
<br />
=== Detecting UEFI Firmware bitness ===<br />
<br />
==== Non Macs ====<br />
<br />
Check whether the dir {{ic|/sys/firmware/efi}} exists, if it exists it means the kernel has booted in EFI mode. In that case the UEFI bitness is same as kernel bitness. (ie. i686 or x86_64)<br />
<br />
{{Note|Intel Atom System-on-Chip systems ship with 32-bit UEFI (as on 2 November 2013). See [[HCL/Firmwares/UEFI#Intel_Atom_System-on-Chip|this page]] for more info.}}<br />
<br />
==== Apple Macs ====<br />
<br />
Pre-2008 Macs mostly have i386-efi firmware while >=2008 Macs have mostly x86_64-efi. All Macs capable of running Mac OS X Snow Leopard 64-bit Kernel have x86_64 EFI 1.x firmware. <br />
<br />
To find out the arch of the efi firmware in a Mac, type the following into the Mac OS X terminal:<br />
<br />
ioreg -l -p IODeviceTree | grep firmware-abi<br />
<br />
If the command returns EFI32 then it is IA32 (32-bit) EFI firmware. If it returns EFI64 then it is x86_64 EFI firmware. Most of the Macs do not have UEFI 2.x firmware as Apple's EFI implementation is not fully compliant with UEFI 2.x Specification.<br />
<br />
=== Secure Boot ===<br />
For an overview about Secure Boot in Linux see http://www.rodsbooks.com/efi-bootloaders/secureboot.html. This section focuses on how to set up Secure Boot in Arch Linux. For the time being, this section is limited to explain the procedure of booting the archiso with Secure Boot enabled.<br />
Booting the archiso with Secure Boot enabled is possible since the efi applications ''PreLoader.efi'' and ''HashTool.efi'' have been added to it. A message will show up that says ''Failed to Start loader... I will now execute HashTool.'' To use HashTool for enrolling the hash of ''loader.efi'' and ''vmlinuz.efi'', follow these steps.<br />
* Select {{ic|OK}}<br />
* In the HashTool main menu, select {{ic|Enroll Hash}}, choose {{ic|\loader.efi}} and confirm with {{ic|Yes}}. Again, select {{ic|Enroll Hash}} and {{ic|archiso}} to enter the archiso directory, then select {{ic|vmlinuz-efi}} and confirm with {{ic|Yes}}. Then choose {{ic|Exit}} to return to the boot device selection menu.<br />
* In the boot device selection menu choose {{ic|Arch Linux archiso x86_64 UEFI CD}}<br />
The archiso boots, and you are presented with a shell prompt, automatically logged in as root. To check if the archiso was booted with SecureBoot, use this command:<br />
<br />
$ od -An -t u1 /sys/firmware/efi/vars/SecureBoot-1234abcde-5678-/data<br />
<br />
If yes, this command returns 1. The characters denoted by 1234 differ from machine to machine. To help with this, you can use tab completion or list the efi variables.<br />
<br />
== Linux Kernel Config options for UEFI ==<br />
<br />
The required Linux Kernel configuration options for UEFI systems are :<br />
<br />
CONFIG_RELOCATABLE=y<br />
CONFIG_EFI=y<br />
CONFIG_EFI_STUB=y<br />
CONFIG_FB_EFI=y<br />
CONFIG_FRAMEBUFFER_CONSOLE=y<br />
<br />
UEFI Runtime Variables Support ('''efivarfs''' filesystem - {{ic|/sys/firmware/efi/efivars}}). This option is important as this is required to manipulate UEFI Runtime Variables using tools like {{ic|/usr/bin/efibootmgr}}. The below config option has been added in kernel 3.10 and above.<br />
<br />
CONFIG_EFIVAR_FS=y<br />
<br />
UEFI Runtime Variables Support (old '''efivars sysfs''' interface - {{ic|/sys/firmware/efi/vars}}). This option should be disabled to prevent any potential issues with both efivarfs and sysfs-efivars enabled.<br />
<br />
CONFIG_EFI_VARS=n<br />
<br />
GUID Partition Table [[GPT]] config option - mandatory for UEFI support<br />
<br />
CONFIG_EFI_PARTITION=y<br />
<br />
{{Note|All of the above options are required to boot Linux via UEFI, and are enabled in Archlinux kernels in official repos.}}<br />
<br />
Retrieved from https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt .<br />
<br />
== UEFI Variables ==<br />
<br />
UEFI defines variables through which an operating system can interact with the firmware. UEFI Boot Variables are used by the boot-loader and used by the OS only for early system start-up. UEFI Runtime Variables allow an OS to manage certain settings of the firmware like the UEFI Boot Manager or managing the keys for UEFI Secure Boot Protocol etc. You can get the list using <br />
$ efivar -l<br />
<br />
=== UEFI Variables Support in Linux Kernel ===<br />
<br />
Linux kernel exposes EFI variables data to userspace via 2 interfaces:<br />
<br />
* '''OLD sysfs-efivars''' interface (CONFIG_EFI_VARS) - populated by {{ic|efivars}} kernel module at {{ic|/sys/firmware/efi/vars}} - 1024 byte maximum per-variable data size limitation, no UEFI Secure Boot variables support (due to the size limitation) and not recommended by kernel upstream anymore. Still supported by kernel upstream but '''completely disabled in Arch's official kernels'''.<br />
<br />
* '''NEW efivarfs''' ('''EFI''' '''VAR'''iable '''F'''ile'''S'''ystem) interface (CONFIG_EFIVAR_FS) - mounted using {{ic|efivarfs}} kernel module at {{ic|/sys/firmware/efi/efivars}} - replacement for the OLD sysfs-efivars interface, has no maximum per-variable size limitation, supports UEFI Secure Boot variables and recommended by kernel upstream. Introduced in kernel 3.8 and NEW {{ic|efivarfs}} module split from OLD {{ic|efivars}} kernel module in kernel 3.10 .<br />
<br />
==== Inconsistency between efivarfs and sysfs-efivars ====<br />
<br />
Enabling both OLD sysfs-efivars and NEW efivarfs can cause data inconsistency issues (see See https://lkml.org/lkml/2013/4/16/473 for more info). Due to this OLD sysfs-efivars is completely disabled in Arch's official kernels (since '''core/{{Pkg|linux}}-3.11''' and '''core/{{Pkg|linux-lts}}-3.10''') and only NEW efivarfs is enabled/supported going forward. All the UEFI Variables related tools and utilities in [[official repositories]] support efivarfs as of 01 October 2013.<br />
<br />
{{Note|As a side-effect of disabling OLD sysfs-efivars, {{ic|efi_pstore}} module is also disabled in the official Arch kernels as EFI pstore functionality in the kernel depends of OLD sysfs-efivars support.}}<br />
<br />
If you have both interfaces enabled, you need to disable one of them, and disable and re-enable the other interface (to refresh the data, to prevent inconsistencies) before accessing the EFI VAR data using any userspace tool:<br />
<br />
To disable sysfs-efivars and refresh efivarfs:<br />
# modprobe -r efivars<br />
<br />
# umount /sys/firmware/efi/efivars<br />
# modprobe -r efivarfs<br />
<br />
# modprobe efivarfs<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
To disable efivarfs and refresh sysfs-efivars:<br />
# umount /sys/firmware/efi/efivars<br />
# modprobe -r efivarfs<br />
<br />
# modprobe -r efivars<br />
# modprobe efivars<br />
<br />
=== Requirements for UEFI Variables support to work properly ===<br />
<br />
# EFI Runtime Services support should be present in the kernel ({{ic|1=CONFIG_EFI=y}}, check if present with {{ic|zgrep CONFIG_EFI /proc/config.gz}}).<br />
# Kernel processor bitness/arch and EFI processor bitness/arch should match<br />
# Kernel should be booted in EFI mode (via [[EFISTUB]] or any [[Boot loaders|EFI boot loader]], not via BIOS/CSM or Apple's "bootcamp" which is also BIOS/CSM)<br />
# EFI Runtime Services in the kernel SHOULD NOT be disabled via kernel cmdline, i.e. {{ic|noefi}} kernel parameter SHOULD NOT be used<br />
# {{ic|efivarfs}} filesystem should be mounted at {{ic|/sys/firmware/efi/efivars}}, otherwise follow [[#Mount efivarfs]] section below.<br />
# {{ic|efivar}} should list (option {{ic|-l}}) the EFI Variables without any error. For sample output see [[#Sample_List_of_UEFI_Variables]].<br />
<br />
If EFI Variables support does not work even after the above conditions are satisfied, try the below workarounds:<br />
<br />
# If any userspace tool is unable to modify efi variables data, check for existence of {{ic|/sys/firmware/efi/efivars/dump-*}} files. If they exist, delete them, reboot and retry again.<br />
# If the above step does not fix the issue, try booting with {{ic|efi_no_storage_paranoia}} kernel parameter to disable kernel efi variable storage space check that may prevent writing/modification of efi variables.<br />
<br />
{{Note|{{ic|efi_no_storage_paranoia}} should only be used when needed and should not be left as a normal boot option. The effect of this kernel command line parameter turns off a safeguard that was put in place to help avoid the bricking of machines when the NVRAM gets too full.}}<br />
<br />
==== Mount efivarfs ====<br />
<br />
If {{ic|efivarfs}} is not automatically mounted at {{ic|/sys/firmware/efi/efivars}} by [[systemd]] during boot, then you need to manually mount it to expose UEFI Variable support to the userspace tools like {{ic|efibootmgr}} etc.:<br />
<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
{{Note|The above command should be run both OUTSIDE (BEFORE) and INSIDE '''chroot''', if any.}}<br />
<br />
It is also a good idea to auto-mount {{ic|efivarfs}} during boot via {{ic|/etc/fstab}} as follows:<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
efivarfs /sys/firmware/efi/efivars efivarfs defaults 0 0<br />
</nowiki>}}<br />
<br />
=== Userspace Tools ===<br />
<br />
There are few tools that can access/modify the UEFI variables, namely<br />
<br />
# '''efivar''' - Library and Tool to manipulate UEFI Variables (used by efibootmgr) - https://github.com/vathpela/efivar - {{Pkg|efivar}} or {{AUR|efivar-git}}<br />
# '''efibootmgr''' - Tool to manipulate UEFI Firmware Boot Manager Settings - https://github.com/vathpela/efibootmgr - {{Pkg|efibootmgr}} or {{AUR|efibootmgr-git}}<br />
# '''uefivars''' - Dumps list of EFI variables with some additional PCI related info (uses efibootmgr code internally) - https://github.com/fpmurphy/Various/tree/master/uefivars-2.0 supports only efivarfs and https://github.com/fpmurphy/Various/tree/master/uefivars-1.0 supports only sysfs-efivars . AUR package {{AUR|uefivars-git}} <br />
# '''efitools''' - Tools to Create and Setup own UEFI Secure Boot Certificates, Keys and Signed Binaries (requires efivarfs) - {{AUR|efitools-git}}<br />
# '''Ubuntu's Firmware Test Suite''' - https://wiki.ubuntu.com/FirmwareTestSuite/ - {{AUR|fwts}} (along with {{AUR|fwts-efi-runtime-dkms}}) or {{AUR|fwts-git}}<br />
<br />
==== efibootmgr ====<br />
<br />
{{Warning|<br />
* Using {{ic|efibootmgr}} in Apple Macs may brick the firmware and may need reflash of the motherboard ROM. There have been bug reports regarding this in Ubuntu/Launchpad bug tracker. Use bless command alone in case of Macs. Experimental "bless" utility for Linux by Fedora developers - {{AUR|mactel-boot}}.}}<br />
{{Note|<br />
* If {{ic|efibootmgr}} completely fails to work in your system, you can reboot into UEFI Shell v2 and use {{ic|bcfg}} command to create a boot entry for the bootloader.<br />
* If you are unable to use {{ic|efibootmgr}}, some UEFI BIOSes allow users to directly manage uefi boot options from within the BIOS. For example, some ASUS BIOSes have a "Add New Boot Option" choice which enables you to select a local EFI System Partition and manually enter the EFI stub location. (for example {{ic|\EFI\refind\refind_x64.efi}}).<br />
* The below commands use {{Pkg|refind-efi}} boot-loader as example.<br />
}}<br />
<br />
Assuming the boot-loader file to be launched is {{ic|/boot/efi/EFI/refind/refind_x64.efi}}, {{ic|/boot/efi/EFI/refind/refind_x64.efi}} can be split up as {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}}, wherein {{ic|/boot/efi}} is the mountpoint of the EFI System Partition, which is assumed to be {{ic|/dev/sdXY}} (here {{ic|X}} and {{ic|Y}} are just placeholders for the actual values - eg:- in {{ic|/dev/sda1}} , {{ic|1=X==a}} {{ic|1=Y==1}}).<br />
<br />
To determine the actual device path for the EFI System Partition (assuming mountpoint {{ic|/boot/efi}} for example) (should be in the form {{ic|/dev/sdXY}}), try :<br />
<br />
# findmnt /boot/efi<br />
TARGET SOURCE FSTYPE OPTIONS<br />
/boot/efi /dev/sdXY vfat rw,flush,tz=UTC<br />
<br />
Verify that uefi variables support in kernel is working properly by running:<br />
<br />
# efivar -l<br />
<br />
If efivar lists the uefi variables without any error, then you can proceed. If not, check whether all the conditions in [[#Requirements for UEFI Variables support to work properly]] are met.<br />
<br />
Then create the boot entry using efibootmgr as follows:<br />
<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_x64.efi -L "rEFInd"<br />
<br />
{{Note|1=UEFI uses backward slash {{ic|\}} as path separator (similar to Windows paths), but the official {{Pkg|efibootmgr}} pkg support passing unix-style paths with forward-slash {{ic|/}} as path-separator for the {{ic|-l}} option. Efibootmgr internally converts {{ic|/}} to {{ic|\}} before encoding the loader path. The relevant git commit that incorporated this feature in efibootmgr is http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/commit/?id=f38f4aaad1dfa677918e417c9faa6e3286411378 .}}<br />
<br />
In the above command {{ic|/boot/efi/EFI/refind/refind_x64.efi}} translates to {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}} which in turn translate to drive {{ic|/dev/sdX}} -> partition {{ic|Y}} -> file {{ic|/EFI/refind/refind_x64.efi}}.<br />
<br />
The 'label' is the name of the menu entry shown in the UEFI boot menu. This name is user's choice and does not affect the booting of the system. More info can be obtained from [http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/plain/README efibootmgr GIT README] .<br />
<br />
FAT32 filesystem is case-insensitive since it does not use UTF-8 encoding by default. In that case the firmware uses capital 'EFI' instead of small 'efi', therefore using {{ic|\EFI\refind\refindx64.efi}} or {{ic|\efi\refind\refind_x64.efi}} does not matter (this will change if the filesystem encoding is UTF-8).<br />
<br />
== EFI System Partition ==<br />
<br />
The EFI System Partition (also called ESP or EFISYS) is a FAT32 formatted physical partition (in the main partition table of the disk, not LVM or software raid etc.) from where the UEFI firmware launches the UEFI bootloader and application. It is a OS independent partition that acts as the storage place for the EFI bootloaders and applications which the firmware launches them. It is mandatory for UEFI boot. It should be marked as '''EF00''' or '''ef00''' type code in gdisk, or '''boot''' flag in case of GNU Parted (only for GPT disk). It is recommended to keep ESP size at 512 MiB although smaller/larger sizes are fine (smaller sizes provided it is higher than the minimum FAT32 FS partition size limit (as mandated by FAT32 specification from Microsoft). For more info visit [[Wikipedia:EFI_System_partition|link]].<br />
<br />
{{Note|<br />
* It is recommended to use always GPT for UEFI boot as some UEFI firmwares do not allow UEFI-MBR boot.<br />
* In GNU Parted, {{ic|boot}} flag (not to be confused with {{ic|legacy_boot}} flag) has different effect in MBR and GPT disk. In MBR disk, it marks the partition as active. In GPT disk, it changes the type code of the partition to {{ic|EFI System Partition}} type. Parted has no flag to mark a partition as ESP in MBR disk (this can be done using fdisk though).<br />
* Microsoft documentation noted the ESP size: For Advanced Format 4K Native drives (4-KB-per-sector) drives, the minimum size is 260 MB, due to a limitation of the FAT32 file format. The minimum partition size of FAT32 drives is calculated as sector size (4KB) x 65527 &#61; 256 MB. Advanced Format 512e drives are not affected by this limitation, because their emulated sector size is 512 bytes. 512 bytes x 65527 &#61; 32 MB, which is less than the 100 MB minimum size for this partition. From: http://technet.microsoft.com/en-us/library/hh824839.aspx#DiskPartitionRules<br />
* In case of [[EFISTUB]], the kernels and initramfs files should be stored in the EFI System Partition. For sake of simplicity, you can also use the ESP as the {{ic|/boot}} partition itself instead of a separate {{ic|/boot}} partition, for EFISTUB booting.<br />
}}<br />
<br />
=== GPT partitioned disks ===<br />
<br />
* Create a partition with partition type {{ic|ef00}} or {{ic|EF00}} using gdisk (from {{Pkg|gptfdisk}} pkg). Then format that partition as FAT32 using {{ic|mkfs.fat -F32 /dev/<THAT_PARTITION>}} <br />
(or)<br />
* Create a FAT32 partition and in GNU Parted set/activate the {{ic|boot}} flag (not {{ic|legacy_boot}} flag) on that partition<br />
<br />
{{Note|If you get the message {{ic|WARNING: Not enough clusters for a 32 bit FAT!}}, reduce cluster size with {{ic|mkfs.fat -s2 -F32 ...}} or {{ic|-s1}}, otherwise the partition may be unreadable by UEFI.}}<br />
<br />
=== MBR partitioned disks ===<br />
<br />
Create a partition with partition type {{ic|0xEF}} using fdisk (from {{Pkg|util-linux}} pkg). Then format that partition as FAT32 using {{ic|mkfs.fat -F32 /dev/<THAT_PARTITION>}}<br />
<br />
== UEFI Shell ==<br />
<br />
The UEFI Shell is a shell/terminal for the firmware which allows launching uefi applications which include uefi bootloaders. Apart from that, the shell can also be used to obtain various other information about the system or the firmware like memory map (memmap), modifying boot manager variables (bcfg), running partitioning programs (diskpart), loading uefi drivers, editing text files (edit), hexedit etc. <br />
<br />
=== Obtaining UEFI Shell ===<br />
<br />
You can download a BSD licensed UEFI Shell from Intel's Tianocore UDK/EDK2 Sourceforge.net project.<br />
<br />
* [[AUR]] '''{{AUR|uefi-shell-svn}}''' pkg (recommended) - provides x86_64 Shell in x86_64 system and IA32 Shell in i686 system - compiled directly from latest Tianocore EDK2 SVN source<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/ShellBinPkg/UefiShell/X64/Shell.efi Precompiled x86_64 UEFI Shell v2 binary] (may not be up-to-date)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/EdkShellBinPkg/FullShell/X64/Shell_Full.efi Precompiled x86_64 UEFI Shell v1 binary] (not updated anymore upstream)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/ShellBinPkg/UefiShell/Ia32/Shell.efi Precompiled IA32 UEFI Shell v2 binary] (may not be up-to-date)<br />
* [https://svn.code.sf.net/p/edk2/code/trunk/edk2/EdkShellBinPkg/FullShell/Ia32/Shell_Full.efi Precompiled IA32 UEFI Shell v1 binary] (not updated anymore upstream)<br />
<br />
Shell v2 works best in UEFI 2.3+ systems and is recommended over Shell v1 in those systems. Shell v1 should work in all UEFI systems irrespective of the spec. version the firmware follows. More info at [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=ShellPkg ShellPkg] and [http://sourceforge.net/mailarchive/message.php?msg_id=28690732 this mail]<br />
<br />
=== Launching UEFI Shell ===<br />
<br />
Few Asus and other AMI Aptio x86_64 UEFI firmware based motherboards (from Sandy Bridge onwards) provide an option called {{ic|"Launch EFI Shell from filesystem device"}} . For those motherboards, download the x86_64 UEFI Shell and copy it to your EFI System Partition as {{ic|<EFI_SYSTEM_PARTITION>/shellx64.efi}} (mostly {{ic|/boot/efi/shellx64.efi}}) .<br />
<br />
Systems with Phoenix SecureCore Tiano UEFI firmware are known to have embedded UEFI Shell which can be launched using either {{ic|F6}}, {{ic|F11}} or {{ic|F12}} key.<br />
<br />
{{Note|If you are unable to launch UEFI Shell from the firmware directly using any of the above mentioned methods, create a FAT32 USB pen drive with {{ic|Shell.efi}} copied as {{ic|(USB)/efi/boot/bootx64.efi}}. This USB should come up in the firmware boot menu. Launching this option will launch the UEFI Shell for you.}}<br />
<br />
=== Important UEFI Shell Commands ===<br />
<br />
UEFI Shell commands usually support {{ic|-b}} option which makes output pause after each page. {{ic|map}} lists recognized filesystems ({{ic|fs0}}, ...) and data storage devices ({{ic|blk0}}, ...). Run {{ic|help -b}} to list available commands.<br />
<br />
More info at http://software.intel.com/en-us/articles/efi-shells-and-scripting/<br />
<br />
==== bcfg ====<br />
<br />
BCFG command is used to modify the UEFI NVRAM entries, which allow the user to change the boot entries or driver options. This command is described in detail in page 83 (Section 5.3) of "UEFI Shell Specification 2.0" PDF document.<br />
<br />
{{Note|<br />
* Users are recommended to try {{ic|bcfg}} only if {{ic|efibootmgr}} fails to create working boot entries in their system.<br />
* UEFI Shell v1 official binary does not support {{ic|bcfg}} command. You can download a [http://dl.dropbox.com/u/17629062/Shell2.zip modified UEFI Shell v2 binary] which may work in UEFI pre-2.3 firmwares.<br />
}}<br />
<br />
To dump a list of current boot entries:<br />
<br />
Shell> bcfg boot dump -v<br />
<br />
To add a boot menu entry for rEFInd (for example) as 4th (numbering starts from zero) option in the boot menu:<br />
<br />
Shell> bcfg boot add 3 fs0:\EFI\refind\refind_x64.efi "rEFInd"<br />
<br />
where {{ic|fs0:}} is the mapping corresponding to the EFI System Partition and {{ic|fs0:\EFI\refind\refind_x64.efi}} is the file to be launched.<br />
<br />
To remove the 4th boot option:<br />
<br />
Shell> bcfg boot rm 3<br />
<br />
To move the boot option #3 to #0 (i.e. 1st or the default entry in the UEFI Boot menu):<br />
<br />
Shell> bcfg boot mv 3 0<br />
<br />
For bcfg help text:<br />
<br />
Shell> help bcfg -v -b<br />
<br />
or:<br />
<br />
Shell> bcfg -? -v -b<br />
<br />
==== edit ====<br />
<br />
EDIT command provides a basic text editor with an interface similar to nano text editor, but slightly less functional. It handles UTF-8 encoding and takes care or LF vs CRLF line endings.<br />
<br />
To edit, for example rEFInd's {{ic|refind.conf}} in the EFI System Partition ({{ic|fs0:}} in the firmware)<br />
<br />
Shell> fs0:<br />
FS0:\> cd \EFI\arch\refind<br />
FS0:\EFI\arch\refind\> edit refind.conf<br />
<br />
Type {{ic|Ctrl-E}} for help.<br />
<br />
== UEFI Linux Hardware Compatibility ==<br />
<br />
See [[HCL/Firmwares/UEFI]] for the main article.<br />
<br />
== UEFI Bootable Media ==<br />
<br />
=== Create UEFI bootable USB from ISO ===<br />
<br />
Follow [[USB Flash Installation Media#BIOS and UEFI Bootable USB]]<br />
<br />
=== Remove UEFI boot support from Optical Media ===<br />
<br />
{{Note|This section mentions removing UEFI boot support from a '''CD/DVD only''' (Optical Media), not from a USB flash drive.}}<br />
<br />
Most of the 32-bit EFI Macs and some 64-bit EFI Macs refuse to boot from a UEFI(X64)+BIOS bootable CD/DVD. If one wishes to proceed with the installation using optical media, it might be necessary to remove UEFI support first.<br />
<br />
* Mount the official installation media and obtain the {{ic|archisolabel}} as shown in the previous section.<br />
<br />
# mount -o loop ''input.iso'' /mnt/iso<br />
<br />
* Then rebuild the ISO, excluding the UEFI Optical Media booting support, using {{ic|xorriso}} from {{pkg|libisoburn}}<br />
{{bc|1=<br />
$ xorriso -as mkisofs -iso-level 3 \<br />
-full-iso9660-filenames\<br />
-volid "''archisolabel''" \<br />
-appid "Arch Linux CD" \<br />
-publisher "Arch Linux <https://www.archlinux.org>" \<br />
-preparer "prepared by $USER" \<br />
-eltorito-boot isolinux/isolinux.bin \<br />
-eltorito-catalog isolinux/boot.cat \<br />
-no-emul-boot -boot-load-size 4 -boot-info-table \<br />
-isohybrid-mbr "/mnt/iso/isolinux/isohdpfx.bin" \<br />
-output ''output.iso'' /mnt/iso/<br />
}}<br />
<br />
* Burn {{ic|''output.iso''}} to optical media and proceed with installation normally.<br />
<br />
== Testing UEFI in systems without native support ==<br />
<br />
=== OVMF for Virtual Machines ===<br />
<br />
OVMF [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=OVMF] is a tianocore project to enable UEFI support for Virtual Machines. OVMF contains a sample UEFI firmware for QEMU.<br />
<br />
You can build OVMF (with Secure Boot support) from AUR {{AUR|ovmf-svn}} and run it as follows:<br />
<br />
$ qemu-system-x86_64 -enable-kvm -net none -m 1024 -pflash /usr/share/ovmf/x86_64/bios.bin<br />
<br />
=== DUET for BIOS only systems ===<br />
<br />
DUET is a tianocore project that enables chainloading a full UEFI environment from a BIOS system, in a way similar to BIOS OS booting. This method is being discussed extensively in http://www.insanelymac.com/forum/topic/186440-linux-and-windows-uefi-boot-using-tianocore-duet-firmware/. Pre-build DUET images can be downloaded from one of the repos at https://gitorious.org/tianocore_uefi_duet_builds. Specific instructions for setting up DUET is available at https://gitorious.org/tianocore_uefi_duet_builds/tianocore_uefi_duet_installer/blobs/raw/master/Migle_BootDuet_INSTALL.txt. <br />
<br />
You can also try http://sourceforge.net/projects/cloverefiboot/ which provides modified DUET images that may contain some system specific fixes and is more frequently updated compared to the gitorious repos.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Windows 7 will not boot in UEFI Mode ===<br />
<br />
If you have installed Windows to a different harddisk with GPT partitioning and still have a MBR partitioned harddisk in your computer, then it is possible that the UEFI BIOS is starting it's CSM support (for booting MBR partitions) and therefor Windows will not boot. To solve this merge your MBR harddisk to GPT partitioning or disable the SATA port where the MBR harddisk is plugged in or unplug the SATA connector from this harddisk.<br />
<br />
Mainboards with this kind of problem:<br />
<br />
Gigabyte Z77X-UD3H rev. 1.1 (UEFI BIOS version F19e)<br />
<br />
- UEFI BIOS option for booting UEFI Only does not pretend the UEFI BIOS from starting CSM<br />
<br />
=== Windows changes boot order ===<br />
In some motherboards (confirmed in ASRock Z77 Extreme4) Windows 8 changes the boot order in the NVRAM everytime is booted. This can be fixed making the Windows Boot Manager to load another loader instead of booting Windows.<br />
Run this command in a Administrator mode console in Windows:<br />
bcdedit /set {bootmgr} path \EFI\boot_app_dir\boot_app.efi<br />
<br />
=== USB media gets struck with black screen ===<br />
<br />
* This issue can occur either due to [[KMS]] issue. Try [[Kernel_Mode_Setting#Disabling_modesetting|Disabling KMS]] while booting the USB.<br />
<br />
* If the issue is not due to KMS, then it may be due to bug in [[EFISTUB]] booting (see [https://bugs.archlinux.org/task/33745] and [https://bbs.archlinux.org/viewtopic.php?id=156670] for more information.). Both Official ISO ([[Archiso]]) and [[Archboot]] iso use EFISTUB (via [[Gummiboot]] Boot Manager for menu) for booting the kernel in UEFI mode. In such a case you have to use [[GRUB]] as the USB's UEFI bootloader by following the below section.<br />
<br />
==== Using GRUB ====<br />
<br />
* Create USB Flash Installation drive as mentioned in [[USB_Flash_Installation_Media#BIOS_and_UEFI_Bootable_USB|link]]. After that follow the below steps to use GRUB instead of Gummiboot.<br />
<br />
* Backup {{ic|<USB>/EFI/boot/loader.efi}} to {{ic|<USB>/EFI/boot/gummiboot.efi}}<br />
<br />
* [[GRUB#GRUB_Standalone|Create a GRUB standalone image]] and copy it to {{ic|<USB>/EFI/boot/loader.efi}}<br />
<br />
* Create {{ic|<USB>/EFI/boot/grub.cfg}} with the following contents (replace {{ic|ARCH_YYYYMM}} with the label of the USB disk e.g. {{ic|ARCH_201404}}):<br />
<br />
{{hc|grub.cfg for Official ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux archiso x86_64" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --label ARCH_YYYYMM<br />
linux /arch/boot/x86_64/vmlinuz archisobasedir=arch archisolabel=ARCH_YYYYMM add_efi_memmap<br />
initrd /arch/boot/x86_64/archiso.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --label ARCH_YYYYMM<br />
chainloader /EFI/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --label ARCH_YYYYMM<br />
chainloader /EFI/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
{{hc|grub.cfg for Archboot ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux x86_64 Archboot" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
linux /boot/vmlinuz_x86_64 cgroup_disable=memory loglevel=7 add_efi_memmap<br />
initrd /boot/initramfs_x86_64.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:UEFI]]<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 />
* [https://www.happyassassin.net/2014/01/25/uefi-boot-how-does-that-actually-work-then/ UEFI boot: how does that actually work, then? - A blog post by AdamW]<br />
* [[Wikipedia:EFI System partition]]<br />
* [http://blog.uncooperative.org/blog/2014/02/06/the-efi-system-partition/ The EFI System Partition and the Default Boot Behavior]<br />
* [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt Linux Kernel x86_64 UEFI Documentation]<br />
* [http://www.intel.com/technology/efi/ Intel's page on EFI]<br />
* [http://uefidk.intel.com/ Intel UEFI Community Resource Center]<br />
* [http://uefidk.intel.com/blog/linux-efi-boot-stub Matt Fleming - The Linux EFI Boot Stub]<br />
* [http://uefidk.intel.com/blog/accessing-uefi-variables-linux Matt Fleming - Accessing UEFI Variables from Linux]<br />
* [http://www.rodsbooks.com/linux-uefi/ Rod Smith - Linux on UEFI: A Quick Installation Guide]<br />
* [https://lkml.org/lkml/2011/6/8/322 UEFI Boot problems on some newer machines (LKML)]<br />
* [http://linuxplumbers.ubicast.tv/videos/plumbing-uefi-into-linux/ LPC 2012 Plumbing UEFI into Linux]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-1/ LPC 2012 UEFI Tutorial : part 1]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-2/ LPC 2012 UEFI Tutorial : part 2]<br />
* [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Welcome_to_TianoCore Intel's Tianocore Project] for Open-Source UEFI firmware which includes DuetPkg for direct BIOS based booting and OvmfPkg used in QEMU and Oracle VirtualBox<br />
* [http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/efi-boot-process.html FGA: The EFI boot process]<br />
* [http://www.microsoft.com/whdc/device/storage/GPT_FAQ.mspx Microsoft's Windows and GPT FAQ]<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Windows_x64_BIOS_to_UEFI Convert Windows x64 from BIOS-MBR mode to UEFI-GPT mode without Reinstall]<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Linux_Windows_BIOS_UEFI_boot_USB Create a Linux BIOS+UEFI and Windows x64 BIOS+UEFI bootable USB drive]<br />
* [http://rodsbooks.com/bios2uefi/ Rod Smith - A BIOS to UEFI Transformation]<br />
* [http://software.intel.com/en-us/articles/efi-shells-and-scripting/ EFI Shells and Scripting - Intel Documentation]<br />
* [http://software.intel.com/en-us/articles/uefi-shell/ UEFI Shell - Intel Documentation]<br />
* [http://www.hpuxtips.es/?q=node/293 UEFI Shell - bcfg command info]<br />
* [http://dl.dropbox.com/u/17629062/Shell2.zip UEFI Shell v2 binary with bcfg modified to work with UEFI pre-2.3 firmware - from Clover efiboot]</div>Bricewgehttps://wiki.archlinux.org/index.php?title=Dhcpd&diff=305627Dhcpd2014-03-19T17:17:17Z<p>Bricewge: /* Tips and Tricks */ Added listening on only one interface with a service file as discussed in the talk page</p>
<hr />
<div>[[Category:Networking]]<br />
[[de:Dhcpd]]<br />
dhcpd is the [http://www.isc.org/downloads/dhcp/ Internet Systems Consortium] DHCP Server. It is useful for instance on a machine acting as a router on a LAN.<br />
<br />
== Installation ==<br />
[[pacman|Install]] the {{pkg|dhcp}} package, available in the [[official repositories]].<br />
<br />
== Configuration ==<br />
<br />
Assign an static IPv4 address to the interface you want to use (usually {{ic|eth0}}). The first 3 bytes of this address cannot be exactly the same as those of another interface.<br />
<br />
# ip link set up dev eth0<br />
# ip addr add 139.96.30.100/24 dev eth0 # arbitrary address<br />
<br />
To have your static ip assigned at boot, see [[Network configuration#Static IP address]].<br />
<br />
The default {{ic|dhcpd.conf}} contains many uncommented examples, so relocate it<br />
<br />
# mv /etc/dhcpd.conf /etc/dhcpd.conf.example<br />
<br />
Edit the configuration file to contain:<br />
<br />
{{hc|/etc/dhcpd.conf|<br />
# Using the google's dns in the example.<br />
# Change it to 139.96.30.100 if you have a dns server installed<br />
option domain-name-servers 8.8.8.8;<br />
option subnet-mask 255.255.255.0;<br />
option routers 139.96.30.100;<br />
subnet 139.96.30.0 netmask 255.255.255.0 {<br />
range 139.96.30.150 139.96.30.250;<br />
}<br />
}}<br />
<br />
Start the ''dhcpd'' daemon with {{ic|dhcpd4.service}} using [[Systemd#Using units|systemctl]]. Optionally, enable it to start automatically on boot.<br />
<br />
Now, any computer you connect over ethernet will be assigned an IPv4 address (from {{ic|139.96.30.150}} to {{ic|139.96.30.250}} in this example).<br />
<br />
== Tips and Tricks ==<br />
=== Listening on only one interface ===<br />
If your computer is already part of one or several networks, it could be a problem if your computer starts giving ip addresses to machines from the other networks. It can be done by either configuring dhcpd or starting it as a daemon with [[Systemd#Using units|systemctl]].<br />
<br />
==== Configuring dhcpd ====<br />
In order to exclude an interface, you must create an empty declartion for the subnet that will be configured on that interface.<br />
<br />
This is done by editing the configuration file (for example):<br />
{{hc|/etc/dhcpd.conf|<nowiki><br />
# No DHCP service in DMZ network (192.168.2.0/24)<br />
subnet 192.168.2.0 netmask 255.255.255.0 {<br />
}<br />
</nowiki>}}<br />
<br />
==== Service file ====<br />
There is no service files provided by default to use ''dhcpd'' only on one interface so yo need to create one:<br />
<br />
{{hc| /etc/systemd/system/dhcpd4@.service|<nowiki><br />
[Unit]<br />
Description=IPv4 DHCP server on %I<br />
Wants=network.target<br />
After=network.target<br />
<br />
[Service]<br />
Type=forking<br />
PIDFile=/run/dhcpd4.pid<br />
ExecStart=/usr/bin/dhcpd -4 -q -pf /run/dhcpd4.pid %I<br />
KillSignal=SIGINT<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Now you can start ''dhcpd'' as a daemon which only listen to a specific interface, for exemple {{ic|eth0}}.<br />
# systemctl start dhcpd4@eth0.service<br />
<br />
==See also==<br />
*[[Dhcpcd]]</div>Bricewge