https://wiki.archlinux.org/api.php?action=feedcontributions&user=Edh&feedformat=atomArchWiki - User contributions [en]2024-03-28T16:18:15ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Talk:Slurm&diff=735480Talk:Slurm2022-06-29T05:58:13Z<p>Edh: /* Slurm and cgroup v2 */ Re: yes</p>
<hr />
<div>== Slurm and cgroup v2 ==<br />
<br />
It seems Slurm now supports cgroups [https://slurm.schedmd.com/cgroups.html cgroups v2].<br />
Shall we remove the note about Slurm not supporting cgroups v2?<br />
<br />
[[User:Wallun|Wallun]] ([[User talk:Wallun|talk]]) 18:35, 28 June 2022 (UTC)<br />
<br />
: Yes, it makes no sense to keep it. Feel free to remove it. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 05:58, 29 June 2022 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=Fstab&diff=687331Fstab2021-07-09T11:00:01Z<p>Edh: /* GPT partition automounting */ Choice of words / Spelling</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:File systems]]<br />
[[Category:Boot process]]<br />
[[ar:Fstab]]<br />
[[de:Fstab]]<br />
[[es:Fstab]]<br />
[[fr:Fstab]]<br />
[[hu:Fstab]]<br />
[[it:Fstab]]<br />
[[ja:Fstab]]<br />
[[pl:Fstab]]<br />
[[pt:Fstab]]<br />
[[ru:Fstab]]<br />
[[zh-hans:Fstab]]<br />
[[zh-hant:Fstab]]<br />
{{Related articles start}}<br />
{{Related|Persistent block device naming}}<br />
{{Related|File systems}}<br />
{{Related|tmpfs}}<br />
{{Related|swap}}<br />
{{Related articles end}}<br />
<br />
The {{man|5|fstab}} file can be used to define how disk partitions, various other block devices, or remote filesystems should be mounted into the filesystem.<br />
<br />
Each filesystem is described in a separate line. These definitions will be converted into [[systemd]] mount units dynamically at boot, and when the configuration of the system manager is reloaded. The default setup will automatically [[fsck]] and mount filesystems before starting services that need them to be mounted. For example, systemd automatically makes sure that remote filesystem mounts like [[NFS]] or [[Samba]] are only started after the network has been set up. Therefore, local and remote filesystem mounts specified in {{ic|/etc/fstab}} should work out-of-the-box. See {{man|5|systemd.mount}} for details.<br />
<br />
The {{ic|mount}} command will use fstab, if just one of either directory or device is given, to fill in the value for the other parameter. When doing so, mount options which are listed in fstab will also be used.<br />
<br />
== Usage ==<br />
<br />
A simple {{ic|/etc/fstab}}, using file system UUIDs:<br />
<br />
{{hc|/etc/fstab|2=<br />
# <device> <dir> <type> <options> <dump> <fsck><br />
UUID=0a3407de-014b-458b-b5c1-848e92a327a3 / ext4 noatime 0 1<br />
UUID=f9fe0b69-a280-415d-a03a-a32752370dee none swap defaults 0 0<br />
UUID=b411dc99-f0a0-4c87-9e05-184977be8539 /home ext4 noatime 0 2<br />
}}<br />
<br />
* {{ic|<device>}} describes the block special device or remote filesystem to be mounted; see [[#Identifying filesystems]].<br />
* {{ic|<dir>}} describes the [[mount]] directory. <br />
* {{ic|<type>}} the [[file system]] type.<br />
* {{ic|<options>}} the associated mount options; see {{man|8|mount|FILESYSTEM-INDEPENDENT_MOUNT_OPTIONS}} and {{man|5|ext4|MOUNT_OPTIONS}}.<br />
* {{ic|<dump>}} is checked by the {{man|8|dump|url=https://linux.die.net/man/8/dump}} utility. This field is usually set to {{ic|0}}, which disables the check.<br />
* {{ic|<fsck>}} sets the order for filesystem checks at boot time; see {{man|8|fsck}}. For the root device it should be {{ic|1}}. For other partitions it should be {{ic|2}}, or {{ic|0}} to disable checking.<br />
<br />
{{Tip|<br />
* The {{ic|auto}} type lets the mount command guess what type of file system is used. This is useful for [[Optical disc drive|optical media]] (CD/DVD/Blu-ray).<br />
* If the root file system is [[btrfs]] or [[XFS]], the fsck order should be set to {{ic|0}} instead of {{ic|1}}. See {{man|8|fsck.btrfs}} and {{man|8|fsck.xfs}}.<br />
}}<br />
<br />
All specified devices within {{ic|/etc/fstab}} will be automatically mounted on startup and when the {{ic|-a}} flag is used with {{man|8|mount}} unless the {{ic|noauto}} option is specified. Devices that are listed and not present will result in an error unless the {{ic|nofail}} option is used.<br />
<br />
See {{man|5|fstab|DESCRIPTION}} for details.<br />
<br />
== Identifying filesystems ==<br />
<br />
There are different ways to identify filesystems that will be mounted in {{ic|/etc/fstab}}: kernel name descriptor, file system label and UUID, and GPT partition label and UUID for GPT disks. UUID or PARTUUID must be privileged over kernel name descriptors and labels. See [[Persistent block device naming]] for more explanations. It is recommended to read that article first before continuing with this article.<br />
<br />
In this section, we will describe how to mount filesystems using all the mount methods available via examples. The output of the commands {{ic|lsblk -f}} and {{ic|blkid}} used in the following examples are available in the article [[Persistent block device naming]].<br />
<br />
To use [[Device file#Block device names|kernel name descriptors]], use {{ic|/dev/sd''xy''}} in the first column.<br />
<br />
=== Kernel name descriptors ===<br />
<br />
Run {{ic|lsblk -f}} to list the partitions and prefix the values in the ''NAME'' column with {{ic|/dev/}}.<br />
<br />
{{hc|/etc/fstab|<br />
# <device> <dir> <type> <options> <dump> <fsck><br />
/dev/sda1 /boot vfat defaults 0 2<br />
/dev/sda2 / ext4 defaults 0 1<br />
/dev/sda3 /home ext4 defaults 0 2<br />
/dev/sda4 none swap defaults 0 0<br />
}}<br />
<br />
{{Warning|Kernel name descriptors are not [[Persistent block device naming|persistent]] and can change each boot, they should not be used in configuration files.}}<br />
<br />
=== File system labels ===<br />
<br />
Run {{ic|lsblk -f}} to list the partitions, and prefix the values in the [[LABEL]] column with {{ic|1=LABEL=}} or alternatively run {{ic|blkid}} and use the LABEL values without the quotes:<br />
<br />
{{hc|/etc/fstab|2=<br />
# <device> <dir> <type> <options> <dump> <fsck><br />
LABEL=EFI /boot vfat defaults 0 2<br />
LABEL=SYSTEM / ext4 defaults 0 1<br />
LABEL=DATA /home ext4 defaults 0 2<br />
LABEL=SWAP none swap defaults 0 0<br />
}}<br />
<br />
{{Note|If any of your fields contains spaces, see [[#Filepath spaces]].}}<br />
<br />
=== File system UUIDs ===<br />
<br />
Run {{ic|lsblk -f}} to list the partitions, and prefix the values in the [[UUID]] column with {{ic|1=UUID=}} or alternatively run {{ic|blkid}} and use the UUID values without the quotes::<br />
<br />
{{hc|/etc/fstab|2=<br />
# <device> <dir> <type> <options> <dump> <fsck><br />
UUID=CBB6-24F2 /boot vfat defaults 0 2<br />
UUID=0a3407de-014b-458b-b5c1-848e92a327a3 / ext4 defaults 0 1<br />
UUID=b411dc99-f0a0-4c87-9e05-184977be8539 /home ext4 defaults 0 2<br />
UUID=f9fe0b69-a280-415d-a03a-a32752370dee none swap defaults 0 0<br />
}}<br />
<br />
=== GPT partition labels ===<br />
<br />
Run {{ic|blkid}} to list the partitions, and use the [[PARTLABEL]] values without the quotes:<br />
<br />
{{hc|/etc/fstab|2=<br />
# <device> <dir> <type> <options> <dump> <fsck><br />
PARTLABEL=EFI\040SYSTEM\040PARTITION /boot vfat defaults 0 2<br />
PARTLABEL=GNU/LINUX / ext4 defaults 0 1<br />
PARTLABEL=HOME /home ext4 defaults 0 2<br />
PARTLABEL=SWAP none swap defaults 0 0<br />
}}<br />
<br />
{{Note|If any of your fields contains spaces, see [[#Filepath spaces]].}}<br />
<br />
=== GPT partition UUIDs ===<br />
<br />
Run {{ic|blkid}} to list the partitions, and use the [[PARTUUID]] values without the quotes:<br />
<br />
{{hc|/etc/fstab|2=<br />
# <device> <dir> <type> <options> <dump> <fsck><br />
PARTUUID=d0d0d110-0a71-4ed6-936a-304969ea36af /boot vfat defaults 0 2<br />
PARTUUID=98a81274-10f7-40db-872a-03df048df366 / ext4 defaults 0 1<br />
PARTUUID=7280201c-fc5d-40f2-a9b2-466611d3d49e /home ext4 defaults 0 2<br />
PARTUUID=039b6c1c-7553-4455-9537-1befbc9fbc5b none swap defaults 0 0<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Automount with systemd ===<br />
<br />
See {{man|5|systemd.mount}} for all systemd mount options.<br />
<br />
==== Local partition ====<br />
<br />
In case of a large partition, it may be more efficient to allow services that do not depend on it to start while it is checked by ''fsck''. This can be achieved by adding the following options to the {{ic|/etc/fstab}} entry of the partition:<br />
<br />
noauto,x-systemd.automount<br />
<br />
This will fsck and mount the partition only when it is first accessed, and the kernel will buffer all file access to it until it is ready.<br />
This method can be relevant if one has, for example, a significantly large {{ic|/home}} partition.<br />
{{Note|This will make the filesystem type {{ic|autofs}} which is ignored by [[mlocate]] by default.}}<br />
<br />
==== Remote filesystem ====<br />
<br />
The same applies to remote filesystem mounts. If you want them to be mounted only upon access, you will need to use the {{ic|noauto,x-systemd.automount}} parameters. In addition, you can use the {{ic|1=x-systemd.mount-timeout=}} option to specify how long systemd should wait for the mount command to finish. Also, the {{ic|_netdev}} option ensures systemd understands that the mount is network dependent and order it after the network is online.<br />
<br />
noauto,x-systemd.automount,x-systemd.mount-timeout=30,_netdev<br />
<br />
==== Encrypted filesystem ====<br />
<br />
If you have encrypted filesystems with keyfiles, you can also add the {{ic|noauto}} parameter to the corresponding entries in {{ic|/etc/crypttab}}. ''systemd'' will then not open the encrypted device on boot, but instead wait until it is actually accessed and then automatically open it with the specified keyfile before mounting it. This might save a few seconds on boot if you are using an encrypted RAID device for example, because systemd does not have to wait for the device to become available. For example:<br />
<br />
{{hc|/etc/crypttab|<br />
data /dev/md0 /root/key noauto<br />
}}<br />
<br />
==== Automatic unmount ====<br />
<br />
You may also specify an idle timeout for a mount with the {{ic|x-systemd.idle-timeout}} flag. For example:<br />
<br />
noauto,x-systemd.automount,x-systemd.idle-timeout=1min<br />
<br />
This will make systemd unmount the mount after it has been idle for 1 minute.<br />
<br />
=== External devices ===<br />
<br />
External devices that are to be mounted when present but ignored if absent may require the {{ic|nofail}} option. This prevents errors being reported at boot. For example: <br />
<br />
{{hc|/etc/fstab|2=<br />
/dev/sdg1 /media/backup jfs nofail,x-systemd.device-timeout=1ms 0 2<br />
}}<br />
<br />
The {{ic|nofail}} option is best combined with the {{ic|x-systemd.device-timeout}} option. This is because the default device timeout is 90 seconds, so a disconnected external device with only {{ic|nofail}} will make your boot take 90 seconds longer, unless you reconfigure the timeout as shown. Make sure not to set the timeout to 0, as this translates to infinite timeout.<br />
<br />
=== Filepath spaces ===<br />
<br />
Since spaces are used in {{ic|fstab}} to delimit fields, if any field (''PARTLABEL'', ''LABEL'' or the mount point) contains spaces, these spaces must be replaced by escape characters {{ic|\}} followed by the 3 digit octal code {{ic|040}}:<br />
<br />
{{hc|/etc/fstab|2=<br />
UUID=47FA-4071 /home/username/Camera<font color="grey">\040</font>Pictures vfat noatime 0 0<br />
/dev/sda7 /media/100<font color="grey">\040</font>GB<font color="grey">\040</font>(Storage) ext4 noatime,user 0 2<br />
}}<br />
<br />
=== atime options ===<br />
<br />
Below atime options can impact drive performance.<br />
<br />
* The {{ic|strictatime}} option updates the access time of the files every time they are accessed. This is more purposeful when Linux is used for servers; it does not have much value for desktop use. The drawback about the {{ic|strictatime}} option is that even reading a file from the page cache (reading from memory instead of the drive) will still result in a write.<br />
* The {{ic|noatime}} option fully disables writing file access times to the drive every time you read a file. This works well for almost all applications, except for those that need to know if a file has been read since the last time it was modified. The write time information to a file will continue to be updated anytime the file is written to with this option enabled.<br />
* The {{ic|nodiratime}} option disables the writing of file access times only for directories while other files still get access times written. {{Note|{{ic|noatime}} implies {{ic|nodiratime}}. [https://lwn.net/Articles/244941/ You do not need to specify both].}}<br />
* {{ic|relatime}} updates the access time only if the previous access time was earlier than the current modify or change time. In addition, since Linux 2.6.30, the access time is always updated if the previous access time was more than 24 hours old. This option is used when the {{ic|defaults}} option, {{ic|atime}} option (which means to use the kernel default, which is {{ic|relatime}}; see {{man|8|mount}} and [[wikipedia:Stat (system call)#Criticism of atime]]) or no options at all are specified.<br />
<br />
When using [[Mutt]] or other applications that need to know if a file has been read since the last time it was modified, the {{ic|noatime}} option should not be used; using the {{ic|relatime}} option is acceptable and still provides a performance improvement.<br />
<br />
Since kernel 4.0 there is another related option:<br />
<br />
* {{ic|lazytime}} reduces writes to disk by maintaining changes to inode timestamps (access, modification and creation times) only in memory. The on-disk timestamps are updated only when either (1) the file inode needs to be updated for some change unrelated to file timestamps, (2) a sync to disk occurs, (3) an undeleted inode is evicted from memory or (4) if more than 24 hours passed since the the last time the in-memory copy was written to disk.<br />
: {{Warning|In the event of a system crash, the access and modification times on disk might be out of date by up to 24 hours.}}<br />
<br />
Note that the {{ic|lazytime}} option works '''in combination''' with the aforementioned {{ic|*atime}} options, not as an alternative. That is {{ic|relatime}} by default, but can be even {{ic|strictatime}} with the same or less cost of disk writes as the plain {{ic|relatime}} option.<br />
<br />
=== Remounting the root partition ===<br />
<br />
If for some reason the root partition has been improperly mounted read only, remount the root partition with read-write access with the following command:<br />
<br />
# mount -o remount,rw /<br />
<br />
=== GPT partition automounting ===<br />
<br />
When using UEFI/GPT, it is possible to omit certain partitions from {{ic|/etc/fstab}} by partitioning according to the [https://systemd.io/DISCOVERABLE_PARTITIONS/ Discoverable Partitions Specification] and having {{man|8|systemd-gpt-auto-generator}} mount the partitions. See [[systemd#GPT partition automounting]].<br />
<br />
== See also ==<br />
<br />
* [https://www.kernel.org/pub/linux/docs/lanana/device-list/devices-2.6.txt Full device listing including block device]<br />
* [https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html Filesystem Hierarchy Standard]<br />
* [https://www.askapache.com/optimize/super-speed-secrets/ 30x Faster Cache and Site Speed with TMPFS]</div>Edhhttps://wiki.archlinux.org/index.php?title=TLP&diff=657151TLP2021-04-01T18:24:48Z<p>Edh: /* Configuration */ Remove excessive spacing</p>
<hr />
<div>[[Category:Power management]]<br />
[[ja:TLP]]<br />
[[zh-hans:TLP]]<br />
{{Related articles start}}<br />
{{Related|Laptop}}<br />
{{Related|Laptop Mode Tools}}<br />
{{Related articles end}}<br />
<br />
From the [http://linrunner.de/en/tlp/tlp.html project page]:<br />
<br />
:TLP brings you the benefits of advanced power management for Linux without the need to understand every technical detail. TLP comes with a default configuration already optimized for battery life, so you may just install and forget it. Nevertheless TLP is highly customizable to fulfill your specific requirements.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|tlp}} package. Installing the optional dependencies may help provide additional power saving.<br />
<br />
[[Enable]]/[[start]] {{ic|tlp.service}}.<br />
<br />
=== Radio Device Wizard (tlp-rdw) ===<br />
<br />
When using the Radio Device Wizard ({{pkg|tlp-rdw}}), it is required to use [[NetworkManager]] and [[enabling]] {{ic|NetworkManager-dispatcher.service}}.<br />
<br />
One should also [[mask]] the service {{ic|systemd-rfkill.service}} and socket {{ic|systemd-rfkill.socket}} to avoid conflicts and assure proper operation of TLP's radio device switching options.<br />
<br />
See [http://linrunner.de/en/tlp/docs/tlp-configuration.html#rdw TLP configuration] for details.<br />
<br />
=== ThinkPads only ===<br />
<br />
For advanced battery functions, i.e. charge thresholds and recalibration, install the following package(s):<br />
<br />
* [[tp_smapi]] – tp-smapi is needed for battery charge thresholds, recalibration and specific status output of tlp-stat<br />
* {{Pkg|acpi_call}} – acpi-call is needed for battery charge thresholds and recalibration on Sandy Bridge and newer models (X220/T420, X230/T430 et al.). Use {{Pkg|acpi_call-dkms}} if not running kernels from [[official repositories]].<br />
<br />
See the TLP FAQ, section [https://linrunner.de/tlp/faq/battery.html?highlight=kernel%20module#which-kernel-module-do-i-need-for-my-hardware "Which kernel module?"], for details.<br />
<br />
Controlling the charge thresholds using D-Bus without root privileges is possible using {{AUR|threshy}} and it's example Qt user interface {{AUR|threshy-gui}}.<br />
<br />
=== Front end ===<br />
<br />
{{AUR|tlpui-git}} is a [[GTK]] user interface for TLP written in Python. As of Feb 2021, the software is still in beta.<br />
<br />
== Configuration ==<br />
<br />
The configuration file is located at {{ic|/etc/tlp.conf}} and provides a largely optimized power saving by default. For a full explanation of options see: [http://linrunner.de/en/tlp/docs/tlp-configuration.html TLP configuration].<br />
<br />
=== USB autosuspend ===<br />
<br />
When starting TLP with the default configuration, some USB devices such as audio DACs will be '''powered down when running on battery''' due to TLP's autosuspend feature. Some devices such as keyboards and scanners are blacklisted from autosuspend by default.<br />
<br />
You may simply want to disable USB autosuspend entirely with the following setting:<br />
<br />
{{hc|/etc/tlp.conf|2=<br />
# Do not suspend USB devices<br />
USB_AUTOSUSPEND=0}}<br />
<br />
Or blacklist specific devices from being auto-suspended. See the [https://linrunner.de/tlp/settings/usb.html TLP documentation on USB devices] for details.<br />
<br />
=== Force battery (BAT) configuration ===<br />
<br />
When no power supply can be detected, the setting for AC will be used on devices like desktops and embedded hardware.<br />
<br />
You may want to force the battery (BAT) settings when using TLP on these devices to enable more power saving:<br />
<br />
{{hc|/etc/tlp.conf|2=<br />
# Operation mode when no power supply can be detected: AC, BAT.<br />
TLP_DEFAULT_MODE=BAT<br />
<br />
# Operation mode select: 0=depend on power source, 1=always use TLP_DEFAULT_MODE<br />
TLP_PERSISTENT_DEFAULT=1}}<br />
<br />
=== Bumblebee with NVIDIA driver ===<br />
<br />
If you're running [[Bumblebee]] with NVIDIA driver, you need to disable power management for the GPU in TLP in order to make Bumblebee control the power of the GPU.<br />
<br />
Depending on the driver(s) that you are using, blacklist one or more of them, preventing TLP from managing their power state:<br />
{{hc|/etc/tlp.conf|2=<br />
RUNTIME_PM_DRIVER_BLACKLIST="nouveau nvidia" }}<br />
<br />
=== PCI(e) runtime power management on AC ===<br />
<br />
Enabling [https://linrunner.de/tlp/settings/runtimepm.html runtime power management] for PCI(e) bus devices while on AC may improve power saving on some laptops. This is enabled by default on battery, but not on AC. To enable on AC, set:<br />
<br />
{{hc|/etc/tlp.conf|2=<br />
RUNTIME_PM_ON_AC=auto<br />
}}<br />
<br />
=== Command line ===<br />
<br />
TLP provides several command line tools. See [https://linrunner.de/tlp/usage/index.html#commands TLP commands].<br />
<br />
== Debugging ==<br />
<br />
You can display information about the currently used Mode(AC/BAT) and applied configurations:<br />
<br />
# tlp-stat<br />
<br />
== hci0: link tx timeout ==<br />
<br />
If your bluetooth headphones suddenly stop working and you see this error in {{ic|dmesg}}, it may be caused by TLP suspending your device. Add device ID to {{ic|USB_BLACKLIST}} in {{ic|/etc/tlp.conf}}:<br />
<br />
# Disable bluetooth autosuspend<br />
USB_BLACKLIST="8087:0aaa"<br />
<br />
Get the device ID for your bluetooth device from {{ic|lsusb -v}}. Restart TLP and the bluetooth service.<br />
<br />
== Features intentionally excluded ==<br />
<br />
* Fan control. See [[Fan speed control]]<br />
<br />
* Backlight brightness. See [[Backlight]]<br />
<br />
== See also ==<br />
<br />
* [http://linrunner.de/tlp TLP - Linux Advanced Power Management] - Project homepage & documentation.<br />
* [https://linrunner.de/en/tlp/docs/tlp-faq.html Project FAQ] - Project FAQ</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:PipeWire&diff=656306Talk:PipeWire2021-03-27T11:03:46Z<p>Edh: /* Configuration section */ Re</p>
<hr />
<div>== 0.3.16 pulse replacement ==<br />
<br />
For the pulse-dropin-replacement to work, you probably also need to clear your users config, {{ic|~/.config/pulse}} (like in delete/move the content) - That is created by pulseaudio for pulseaudio.<br />
Otherwise the server could be unable to start.<br />
<br />
[[User:Fabis.cafe|Fabis.cafe]] ([[User talk:Fabis.cafe|talk]]) 14:12, 23 November 2020 (UTC)<br />
<br />
----<br />
<br />
I just installed the pulse replacement and while everything seems to be working just fine, the only problem is gnome-shell doesn't seem to be able to see the pipewrire pulse server, thus the volume control in the top right system menu is absent and keyboard media keys for volume don't work either. I think this should be addressed in the troubleshooting section with a solution if there is one.<br />
<br />
Interestingly enough gnome-control-center is able to control the volume as well as other typical pulseaudio parameters.<br />
<br />
UPDATE: running {{ic|killall pipewire-pulse; killall pipewire}} restarts the pipewire pulse daemon and makes the volume control in gnome-shell work as expected. This of course is a workaround and not a proper solution.<br />
<br />
UPDATE 2: the above makes the volume control menu item and shortcuts appear, but adjusting the volume does nothing.<br />
<br />
[[User:GabMus|GabMus]] ([[User talk:GabMus|talk]]) 09:39, 3 December 2020 (UTC)<br />
<br />
:I don't see volume indicator in gnome-shell/wayland but I'm able to control volume with media keys. -- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 15:55, 3 December 2020 (UTC)<br />
<br />
:: Possibly related: https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/426 [[User:Hexchain|Hexchain]] ([[User talk:Hexchain|talk]]) 18:05, 3 December 2020 (UTC)<br />
<br />
: Solved, refer to the latest change I made in the main page, found the solution thanks to Hexchain's link. -- [[User:GabMus|GabMus]] ([[User talk:GabMus|talk]]) 19:55, 4 December 2020 (UTC)<br />
<br />
== aptX support ==<br />
<br />
Does `pipewire` support low latency/high quality bluetooth codecs (aptX, LDAC, ...) ? <br />
<br />
along the lines of https://aur.archlinux.org/packages/pulseaudio-modules-bt-git/ <br />
<br />
If yes, how to configure it? <br />
<br />
along the lines of https://freedesktop.org/software/pulseaudio/pavucontrol/ <br />
<br />
[[User:NTia89|nTia89]] ([[User talk:NTia89|talk]]) 21:23, 3 December 2020 (UTC)<br />
<br />
: I switched to PipeWire and currently bluetooth sound poorly works: high latency and low quality.<br />
: Actually open bug/enhancement in pipewire bugtracker [https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/136].<br />
[[User:NTia89|nTia89]] ([[User talk:NTia89|talk]]) 10:20, 5 December 2020 (UTC)<br />
<br />
: It does now but currently there is no way to select a codec manually. It uses (the first supported?) codec in this order: LDAC, AptX HD, AptX, SBC. You can check for the current codec with {{ic|pactl list sinks}} IIRC. [[User:Hexchain|Hexchain]] ([[User talk:Hexchain|talk]]) 00:41, 21 December 2020 (UTC)<br />
<br />
== Better introduction? ==<br />
<br />
Right now I think the description is missing some content to exactly explain what pipewire is and what it can be used for.<br />
The website names some important examples imho:<br />
<br />
* Capture and playback of audio and video with minimal latency.<br />
* Real-time Multimedia processing on audio and video.<br />
* Multiprocess architecture to let applications share multimedia content.<br />
* Seamless support for PulseAudio, JACK, ALSA and GStreamer applications.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 15:21, 28 February 2021 (UTC)<br />
<br />
: I fully agree! TBH I don't see an urgent need for a discussion on this topic. Feel free to amend the page with whatever you think is right. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 19:30, 3 March 2021 (UTC)<br />
<br />
:: Ok, I have added some parts. Someone with better knowledge on this topic might edit it further.<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:26, 5 March 2021 (UTC)<br />
<br />
== Move section "webrtc screen sharing" below other sections in "Usage" ==<br />
<br />
I think that the "Audio" and "Video" sections are more important and more general, so they should be placed first.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 15:23, 28 February 2021 (UTC)<br />
<br />
: IMHO the ordering is just fine as of now. Pipewire is completely optional for handling audio and video. However, for screensharing under wayland you must use it. I strongly believe that this section is of most interest to the average user. Note, I am fine though with whatever reaches a consensus. I do not feel too strongly about the ordering of these sections. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 19:28, 3 March 2021 (UTC)<br />
<br />
:: For now I would be ok with the ordering, but afaik Pipewire is aimed to become some kind of "replacement" for pulseaudio etc., so the other parts will become more important in the future.<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:33, 5 March 2021 (UTC)<br />
<br />
== <s>No output devices after update</s> ==<br />
<br />
The only solution that worked is removing /etc/pipewire than reinstalling.<br />
<br />
Related:<br />
<br />
https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/840<br />
<br />
[[User:Sigmasd|Sigmasd]] ([[User talk:Sigmasd|talk]]) 07:33, 20 March 2021 (UTC)<br />
<br />
:This is covered in [[Pacman/Pacnew and Pacsave]], closing. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:31, 20 March 2021 (UTC)<br />
<br />
== 0.3.23 no pcm devices found ==<br />
<br />
Thanks [[User:NTia89|nTia89]] for reverting my change. pipewire-alsa isn't needed, I checked contents of the package, it definitely can't help.<br />
<br />
Spent 5h on pipewire, it did not find any sound-card. The moment I installed pipewire-alsa it started working. I used <code>pw-cli ls | grep -i pcm</code> to find pcm devices. I didn't change any config the whole time, because the wiki-page says it should work out of the box. I rebooted a lot. I hoped I could help that other users don't have to spend 5h on this. pipewire seems very nice. So here is what I did in the end.<br />
<br />
* install <code>pipewire pipewire-media-session pipewire-alsa pipewire-jack pipewire-pulse pipewire-jack-dropin</code> (ignore jack if you don't have jack-applications)<br />
* remove <code>pulseaudio</code><br />
* <code>systemctl --user enable pipewire.socket pipewire-pulse.service pipewire-media-session.service</code><br />
* <code>systemctl --user restart pipewire.service pipewire-pulse.service pipewire-media-session.service</code><br />
<br />
I try to find out what exactly my mistake was.<br />
<br />
[[User:Streampunk|Streampunk]] ([[User talk:Streampunk|talk]]) 14:59, 22 March 2021 (UTC)<br />
<br />
== Configuration section ==<br />
<br />
I think we have to mention the official wiki page: https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Configuration#set-global-sample-rate<br />
because it is a complete and always up-to-date resource.<br />
<br />
<br />
I think we should add a Configuration section; a sort of:<br />
<br />
`PipeWire is a powerful tool having a plethora of options. We recommend to read the official wiki page[1] in order to have a complete sight of all possibilities. Although most users are happy with default settings, particular configuration cases are reported in the Pipewire/Examples page. On the other hand, most common issues and their solutions are reported below in the Troubleshooting section.`<br />
<br />
What do you think?<br />
<br />
<br />
[[User:NTia89|nTia89]] ([[User talk:NTia89|talk]]) 10:16, 27 March 2021 (UTC)<br />
<br />
: I fully agree with you about mentioning the official wiki page. However, I think it is fine to recap some of the most important configuration options in the ArchWiki too! At least to me the current phrasing of the paragraph suggests that we solely refer to the official wiki page for that. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 11:03, 27 March 2021 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655070Sway2021-03-15T21:36:45Z<p>Edh: /* Custom keybindings */ Add note on systemd's loginctl handling some special keys like the power key as well as the lid close and open</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set the configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}.<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}). These need to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
{{hc|~/.config/sway/config|<br />
output <name> scale <factor><br />
}}<br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
{{note|Systemd handles some special keys like the power key and lid open as well as close events. These may interfere with the ones configured in sway. See {{man|1|loginctl}} and {{man|5|logind.conf}} for details on how to configure them in [[systemd]].}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Idle ===<br />
<br />
Sway has a dedicated idle management daemon named {{pkg|swayidle}} to handle idling sessions. There are different ways to start and parameterize the daemon. The simplest is to use the config of sway itself. {{ic|swayidle}} accepts a multitude of arguments to configure events like {{ic|timeout}} (a.k.a. idling), {{ic|resume}} (resume from sleep), {{ic|before-sleep}} etc. See {{man|1|swayidle}} for more details and further explanations of the events. Each event can then be assigned an action. To assign multiple actions to an event simply repeat the trigger.<br />
<br />
The following instructs {{ic|swayidle}} to lock the screen after 30 minutes and turn it off five seconds after:<br />
{{hc|~/.config/sway/config|<br />
exec swayidle -w \<br />
timeout 1800 'swaylock' \<br />
timeout 1805 'swaymsg "output * dpms off"' \<br />
resume 'swaymsg "output * dpms on"'<br />
}}<br />
<br />
To turn of a locked screen much sooner e.g. after 10 seconds, grep the process list for your locking manager and execute {{ic|swaymsg "output * dpms off"}} accordingly like so<br />
<br />
timeout 10 'if pgrep -x swaylock; then swaymsg "output * dpms off"; fi'<br />
<br />
In order to lock the screen before suspending and pause any playing media, amend the following instructions to the swayidle command:<br />
<br />
before-sleep 'playerctl pause'<br />
before-sleep 'swaylock'<br />
<br />
{{note|Systemd too handles some idle events which may conflict with the ones configured in sway. See {{man|1|loginctl}} and {{man|5|logind.conf}} for details on how to configure them.}}<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655069Sway2021-03-15T21:34:22Z<p>Edh: /* Idle */ Add note on systemd handling some idling events too</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set the configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}.<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}). These need to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
{{hc|~/.config/sway/config|<br />
output <name> scale <factor><br />
}}<br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Idle ===<br />
<br />
Sway has a dedicated idle management daemon named {{pkg|swayidle}} to handle idling sessions. There are different ways to start and parameterize the daemon. The simplest is to use the config of sway itself. {{ic|swayidle}} accepts a multitude of arguments to configure events like {{ic|timeout}} (a.k.a. idling), {{ic|resume}} (resume from sleep), {{ic|before-sleep}} etc. See {{man|1|swayidle}} for more details and further explanations of the events. Each event can then be assigned an action. To assign multiple actions to an event simply repeat the trigger.<br />
<br />
The following instructs {{ic|swayidle}} to lock the screen after 30 minutes and turn it off five seconds after:<br />
{{hc|~/.config/sway/config|<br />
exec swayidle -w \<br />
timeout 1800 'swaylock' \<br />
timeout 1805 'swaymsg "output * dpms off"' \<br />
resume 'swaymsg "output * dpms on"'<br />
}}<br />
<br />
To turn of a locked screen much sooner e.g. after 10 seconds, grep the process list for your locking manager and execute {{ic|swaymsg "output * dpms off"}} accordingly like so<br />
<br />
timeout 10 'if pgrep -x swaylock; then swaymsg "output * dpms off"; fi'<br />
<br />
In order to lock the screen before suspending and pause any playing media, amend the following instructions to the swayidle command:<br />
<br />
before-sleep 'playerctl pause'<br />
before-sleep 'swaylock'<br />
<br />
{{note|Systemd too handles some idle events which may conflict with the ones configured in sway. See {{man|1|loginctl}} and {{man|5|logind.conf}} for details on how to configure them.}}<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655063Sway2021-03-15T21:29:13Z<p>Edh: /* Idle */ Remove comment from code `swayidle` block</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set the configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}.<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}). These need to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
{{hc|~/.config/sway/config|<br />
output <name> scale <factor><br />
}}<br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Idle ===<br />
<br />
Sway has a dedicated idle management daemon named {{pkg|swayidle}} to handle idling sessions. There are different ways to start and parameterize the daemon. The simplest is to use the config of sway itself. {{ic|swayidle}} accepts a multitude of arguments to configure events like {{ic|timeout}} (a.k.a. idling), {{ic|resume}} (resume from sleep), {{ic|before-sleep}} etc. See {{man|1|swayidle}} for more details and further explanations of the events. Each event can then be assigned an action. To assign multiple actions to an event simply repeat the trigger.<br />
<br />
The following instructs {{ic|swayidle}} to lock the screen after 30 minutes and turn it off five seconds after:<br />
{{hc|~/.config/sway/config|<br />
exec swayidle -w \<br />
timeout 1800 'swaylock' \<br />
timeout 1805 'swaymsg "output * dpms off"' \<br />
resume 'swaymsg "output * dpms on"'<br />
}}<br />
<br />
To turn of a locked screen much sooner e.g. after 10 seconds, grep the process list for your locking manager and execute {{ic|swaymsg "output * dpms off"}} accordingly like so<br />
<br />
timeout 10 'if pgrep -x swaylock; then swaymsg "output * dpms off"; fi'<br />
<br />
In order to lock the screen before suspending and pause any playing media, amend the following instructions to the swayidle command:<br />
<br />
before-sleep 'playerctl pause'<br />
before-sleep 'swaylock'<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655062Sway2021-03-15T21:28:37Z<p>Edh: /* Idle */ Describe how to idle sway sooner if locked and provide an example for `before-sleep`</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set the configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}.<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}). These need to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
{{hc|~/.config/sway/config|<br />
output <name> scale <factor><br />
}}<br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Idle ===<br />
<br />
Sway has a dedicated idle management daemon named {{pkg|swayidle}} to handle idling sessions. There are different ways to start and parameterize the daemon. The simplest is to use the config of sway itself. {{ic|swayidle}} accepts a multitude of arguments to configure events like {{ic|timeout}} (a.k.a. idling), {{ic|resume}} (resume from sleep), {{ic|before-sleep}} etc. See {{man|1|swayidle}} for more details and further explanations of the events. Each event can then be assigned an action. To assign multiple actions to an event simply repeat the trigger.<br />
<br />
The following instructs {{ic|swayidle}} to lock the screen after 30 minutes and turn it off five seconds after:<br />
{{hc|~/.config/sway/config|<br />
# Idle configuration<br />
exec swayidle -w \<br />
timeout 1800 'swaylock' \<br />
timeout 1805 'swaymsg "output * dpms off"' \<br />
resume 'swaymsg "output * dpms on"'<br />
}}<br />
<br />
To turn of a locked screen much sooner e.g. after 10 seconds, grep the process list for your locking manager and execute {{ic|swaymsg "output * dpms off"}} accordingly like so<br />
<br />
timeout 10 'if pgrep -x swaylock; then swaymsg "output * dpms off"; fi'<br />
<br />
In order to lock the screen before suspending and pause any playing media, amend the following instructions to the swayidle command:<br />
<br />
before-sleep 'playerctl pause'<br />
before-sleep 'swaylock'<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655061Sway2021-03-15T21:23:51Z<p>Edh: /* Idle */ Add example for swayidle config</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set the configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}.<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}). These need to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
{{hc|~/.config/sway/config|<br />
output <name> scale <factor><br />
}}<br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Idle ===<br />
<br />
Sway has a dedicated idle management daemon named {{pkg|swayidle}} to handle idling sessions. There are different ways to start and parameterize the daemon. The simplest is to use the config of sway itself. {{ic|swayidle}} accepts a multitude of arguments to configure events like {{ic|timeout}} (a.k.a. idling), {{ic|resume}} (resume from sleep), {{ic|before-sleep}} etc. See {{man|1|swayidle}} for more details and further explanations of the events. Each event can then be assigned an action. To assign multiple actions to an event simply repeat the trigger.<br />
<br />
The following instructs {{ic|swayidle}} to lock the screen after 30 minutes and turn it off five seconds after:<br />
{{hc|~/.config/sway/config|<br />
# Idle configuration<br />
exec swayidle -w \<br />
timeout 1800 'swaylock' \<br />
timeout 1805 'swaymsg "output * dpms off"' \<br />
resume 'swaymsg "output * dpms on"'<br />
}}<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655060Sway2021-03-15T21:20:32Z<p>Edh: /* Configuration */ Add section on idling (swayidle)</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set the configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}.<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}). These need to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
{{hc|~/.config/sway/config|<br />
output <name> scale <factor><br />
}}<br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Idle ===<br />
<br />
Sway has a dedicated idle management daemon named {{pkg|swayidle}} to handle idling sessions. There are different ways to start and parameterize the daemon. The simplest is to use the config of sway itself. {{ic|swayidle}} accepts a multitude of arguments to configure events like {{ic|timeout}} (a.k.a. idling), {{ic|resume}} (resume from sleep), {{ic|before-sleep}} etc. See {{man|1|swayidle}} for more details and further explanations of the events. Each event can then be assigned an action. To assign multiple actions to an event simply repeat the trigger.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:Sway&diff=655059Talk:Sway2021-03-15T21:05:15Z<p>Edh: /* Remove "Candidate for Merging" banner at Sway#Manage Sway-specific daemons with systemd */ Fix wording</p>
<hr />
<div>== 'xwayland disable' is not necessary to run programs natively under Wayland ==<br />
<br />
I'm afraid the statement is not totally true. Under one circumstance, which is when {{Pkg|xorg-server-xwayland}} is not installed, programs won't run(or render on screen) even with [[Wayland#GUI libraries|GUI libraries]] env variables properly set. Maybe a bug?. I've noticed on sway log that {{ic|xwayland.c}} function of {{Pkg|wlroots}} isn't called if and only if {{ic|xwayland disable}} is set.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
This is a GTK+ bug. It tries to connect to Xwayland even if it only uses Wayland. I've no idea why, it would be nice to report this to the GTK+ devs and figure out how to fix it.<br />
<br />
If you don't disable Xwayland and have it uninstalled, you'll have an invalid `DISPLAY` set.<br />
<br />
[[User:Emersion|Emersion]] ([[User talk:Emersion|talk]]) 21:51, 5 May 2019 (UTC)<br />
<br />
== <s>Keeping XWayland enabled is good for programs that don't work otherwise</s> ==<br />
<br />
It depends on user choice. I think having a wiki section on how to disable xwayland may benefit those who want to avoid X.Org.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
: Agreed. However, by now there already is a dedicated section about this at [[Sway#XWayland]]. Thus, I think it is safe to close this discussion. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:11, 15 March 2021 (UTC)<br />
<br />
== <s>Making Kwallet access possible in KDE programs</s> ==<br />
<br />
The article contained the required information before the latest revert to date. Unlike the comment by the moderator suggests, the information is not generic for all graphical environments (unlocking via PAM is sufficient for e.g. Gnome, but not Sway).<br />
[[User:Aufkrawall|Aufkrawall]] ([[User talk:Aufkrawall|talk]]) 16:03, 7 December 2019 (UTC)<br />
<br />
:In any case, the information is not specific to Sway so it does not belong to this page. Please add it to [[Kwallet]] instead. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:13, 7 December 2019 (UTC)<br />
<br />
: I have not been involved in the discussion but considering the existence of [[Kwallet#Unlock KDE Wallet automatically on login]] and no reply to this section for more than a year, I am closing it for now. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:15, 15 March 2021 (UTC)<br />
<br />
== <s>Unclear how to start 'output' command as it is not part of minimal installation?</s> ==<br />
<br />
The output command is mentioned in this wiki. It is unclear which package contains it? It was not installed when I did "sudo pacman -S sway".<br />
<br />
[[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 16:38, 4 January 2020 (UTC)<br />
<br />
:"output" is not a shell command, but sway command. You need to install {{Pkg|swaybg}} as described in [[Sway#Wallpaper]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:26, 4 January 2020 (UTC)<br />
<br />
:I did install swaybg. What do you mean with "output is a sway command"? [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 17:44, 4 January 2020 (UTC)<br />
<br />
:fixed it, "sway output ..." did the job. Perhaps this can be clarified? It wasn't clear to me that output wasn't a shell command ... [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 18:00, 4 January 2020 (UTC)<br />
<br />
: I fixed another {{ic|output}} being formatted as if it were a command. Hopefully, every occurrence is resolved by now thus I am closing the discussion. Feel free to re-open it if you object. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:18, 15 March 2021 (UTC)<br />
<br />
== Mention the `--locked` option for keybindings ==<br />
<br />
When the option `--locked` is used on keybindings, they also work while sway is locked with `swaylock`. It is a great feature for e.g. media or brightness keys and definitely worth mentioning in the wiki; however I'm unsure as to where this information would fit best: under 'Custom Keybindings' or somewhere in the 'Tips and Tricks' section? What do you all think? [[User:Bloor|Bloor]] ([[User talk:Bloor|talk]]) 13:36, 12 March 2020 (UTC)<br />
<br />
: I think the current solution at [[Sway#Custom keybindings]] is just fine. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:19, 15 March 2021 (UTC)<br />
<br />
== XWayland launchers still getting stuck an issue? ==<br />
<br />
The Application Launches section mentions a problem with some X11-based launchers getting stuck:<br />
<br />
https://wiki.archlinux.org/index.php/Sway#Application_launchers<br />
<br />
Is this still an issue since this patch was added to Sway 1.5?<br />
<br />
https://github.com/swaywm/sway/issues/4693<br />
<br />
{{Unsigned|23:42, 18 August 2020 (UTC)|Markstos}}<br />
<br />
:The section does not mention popup windows at all, so I think it's still the same problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:04, 19 August 2020 (UTC)<br />
<br />
== Color temperature adjustment ==<br />
<br />
Perhaps there should be a link to [[Backlight#Wayland]] somewhere on the page to inform people of {{Pkg|gammastep}}?<br />
<br />
[[User:Forgonewarrior|Forgonewarrior]] ([[User talk:Forgonewarrior|talk]]) 17:00, 6 January 2021 (UTC)<br />
<br />
:Yes, it can be done like [[Sway#Screen capture and screen sharing]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:14, 7 January 2021 (UTC)<br />
<br />
== Remove "Candidate for Merging" banner at [[Sway#Manage Sway-specific daemons with systemd]] ==<br />
<br />
I propose to remove the {{ic|Merge}} banner in [[Sway#Manage Sway-specific daemons with systemd]]. Just as the description already states the way to define custom targets akin to e.g. {{ic|graphical-session.target}} should be described at [[systemd/User]]. However, from my point of view this does not invalidate the way more specific use case which is outlined for sway here. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:24, 15 March 2021 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:Sway&diff=655057Talk:Sway2021-03-15T20:25:32Z<p>Edh: New section: Propose to remove `Merge` banner for Sway#Manage Sway-specific daemons with systemd</p>
<hr />
<div>== 'xwayland disable' is not necessary to run programs natively under Wayland ==<br />
<br />
I'm afraid the statement is not totally true. Under one circumstance, which is when {{Pkg|xorg-server-xwayland}} is not installed, programs won't run(or render on screen) even with [[Wayland#GUI libraries|GUI libraries]] env variables properly set. Maybe a bug?. I've noticed on sway log that {{ic|xwayland.c}} function of {{Pkg|wlroots}} isn't called if and only if {{ic|xwayland disable}} is set.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
This is a GTK+ bug. It tries to connect to Xwayland even if it only uses Wayland. I've no idea why, it would be nice to report this to the GTK+ devs and figure out how to fix it.<br />
<br />
If you don't disable Xwayland and have it uninstalled, you'll have an invalid `DISPLAY` set.<br />
<br />
[[User:Emersion|Emersion]] ([[User talk:Emersion|talk]]) 21:51, 5 May 2019 (UTC)<br />
<br />
== <s>Keeping XWayland enabled is good for programs that don't work otherwise</s> ==<br />
<br />
It depends on user choice. I think having a wiki section on how to disable xwayland may benefit those who want to avoid X.Org.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
: Agreed. However, by now there already is a dedicated section about this at [[Sway#XWayland]]. Thus, I think it is safe to close this discussion. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:11, 15 March 2021 (UTC)<br />
<br />
== <s>Making Kwallet access possible in KDE programs</s> ==<br />
<br />
The article contained the required information before the latest revert to date. Unlike the comment by the moderator suggests, the information is not generic for all graphical environments (unlocking via PAM is sufficient for e.g. Gnome, but not Sway).<br />
[[User:Aufkrawall|Aufkrawall]] ([[User talk:Aufkrawall|talk]]) 16:03, 7 December 2019 (UTC)<br />
<br />
:In any case, the information is not specific to Sway so it does not belong to this page. Please add it to [[Kwallet]] instead. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:13, 7 December 2019 (UTC)<br />
<br />
: I have not been involved in the discussion but considering the existence of [[Kwallet#Unlock KDE Wallet automatically on login]] and no reply to this section for more than a year, I am closing it for now. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:15, 15 March 2021 (UTC)<br />
<br />
== <s>Unclear how to start 'output' command as it is not part of minimal installation?</s> ==<br />
<br />
The output command is mentioned in this wiki. It is unclear which package contains it? It was not installed when I did "sudo pacman -S sway".<br />
<br />
[[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 16:38, 4 January 2020 (UTC)<br />
<br />
:"output" is not a shell command, but sway command. You need to install {{Pkg|swaybg}} as described in [[Sway#Wallpaper]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:26, 4 January 2020 (UTC)<br />
<br />
:I did install swaybg. What do you mean with "output is a sway command"? [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 17:44, 4 January 2020 (UTC)<br />
<br />
:fixed it, "sway output ..." did the job. Perhaps this can be clarified? It wasn't clear to me that output wasn't a shell command ... [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 18:00, 4 January 2020 (UTC)<br />
<br />
: I fixed another {{ic|output}} being formatted as if it were a command. Hopefully, every occurrence is resolved by now thus I am closing the discussion. Feel free to re-open it if you object. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:18, 15 March 2021 (UTC)<br />
<br />
== Mention the `--locked` option for keybindings ==<br />
<br />
When the option `--locked` is used on keybindings, they also work while sway is locked with `swaylock`. It is a great feature for e.g. media or brightness keys and definitely worth mentioning in the wiki; however I'm unsure as to where this information would fit best: under 'Custom Keybindings' or somewhere in the 'Tips and Tricks' section? What do you all think? [[User:Bloor|Bloor]] ([[User talk:Bloor|talk]]) 13:36, 12 March 2020 (UTC)<br />
<br />
: I think the current solution at [[Sway#Custom keybindings]] is just fine. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:19, 15 March 2021 (UTC)<br />
<br />
== XWayland launchers still getting stuck an issue? ==<br />
<br />
The Application Launches section mentions a problem with some X11-based launchers getting stuck:<br />
<br />
https://wiki.archlinux.org/index.php/Sway#Application_launchers<br />
<br />
Is this still an issue since this patch was added to Sway 1.5?<br />
<br />
https://github.com/swaywm/sway/issues/4693<br />
<br />
{{Unsigned|23:42, 18 August 2020 (UTC)|Markstos}}<br />
<br />
:The section does not mention popup windows at all, so I think it's still the same problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:04, 19 August 2020 (UTC)<br />
<br />
== Color temperature adjustment ==<br />
<br />
Perhaps there should be a link to [[Backlight#Wayland]] somewhere on the page to inform people of {{Pkg|gammastep}}?<br />
<br />
[[User:Forgonewarrior|Forgonewarrior]] ([[User talk:Forgonewarrior|talk]]) 17:00, 6 January 2021 (UTC)<br />
<br />
:Yes, it can be done like [[Sway#Screen capture and screen sharing]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:14, 7 January 2021 (UTC)<br />
<br />
== Remove "Candidate for Merging" banner at [[Sway#Manage Sway-specific daemons with systemd]] ==<br />
<br />
I propose to remove the {{ic|Merge}} banner in the [[Sway#Manage Sway-specific daemons with systemd]]. As the description already states, the way to define custom targets akin to e.g. {{ic|graphical-session.target}} should be described at [[systemd/User]]. However, from my point of view this does not invalidate the way more specific use case which is outlined for sway here. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:24, 15 March 2021 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:Sway&diff=655056Talk:Sway2021-03-15T20:20:03Z<p>Edh: /* Mention the `--locked` option for keybindings */ Re: fine as it is now in Sway#Custom keybindings</p>
<hr />
<div>== 'xwayland disable' is not necessary to run programs natively under Wayland ==<br />
<br />
I'm afraid the statement is not totally true. Under one circumstance, which is when {{Pkg|xorg-server-xwayland}} is not installed, programs won't run(or render on screen) even with [[Wayland#GUI libraries|GUI libraries]] env variables properly set. Maybe a bug?. I've noticed on sway log that {{ic|xwayland.c}} function of {{Pkg|wlroots}} isn't called if and only if {{ic|xwayland disable}} is set.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
This is a GTK+ bug. It tries to connect to Xwayland even if it only uses Wayland. I've no idea why, it would be nice to report this to the GTK+ devs and figure out how to fix it.<br />
<br />
If you don't disable Xwayland and have it uninstalled, you'll have an invalid `DISPLAY` set.<br />
<br />
[[User:Emersion|Emersion]] ([[User talk:Emersion|talk]]) 21:51, 5 May 2019 (UTC)<br />
<br />
== <s>Keeping XWayland enabled is good for programs that don't work otherwise</s> ==<br />
<br />
It depends on user choice. I think having a wiki section on how to disable xwayland may benefit those who want to avoid X.Org.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
: Agreed. However, by now there already is a dedicated section about this at [[Sway#XWayland]]. Thus, I think it is safe to close this discussion. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:11, 15 March 2021 (UTC)<br />
<br />
== <s>Making Kwallet access possible in KDE programs</s> ==<br />
<br />
The article contained the required information before the latest revert to date. Unlike the comment by the moderator suggests, the information is not generic for all graphical environments (unlocking via PAM is sufficient for e.g. Gnome, but not Sway).<br />
[[User:Aufkrawall|Aufkrawall]] ([[User talk:Aufkrawall|talk]]) 16:03, 7 December 2019 (UTC)<br />
<br />
:In any case, the information is not specific to Sway so it does not belong to this page. Please add it to [[Kwallet]] instead. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:13, 7 December 2019 (UTC)<br />
<br />
: I have not been involved in the discussion but considering the existence of [[Kwallet#Unlock KDE Wallet automatically on login]] and no reply to this section for more than a year, I am closing it for now. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:15, 15 March 2021 (UTC)<br />
<br />
== <s>Unclear how to start 'output' command as it is not part of minimal installation?</s> ==<br />
<br />
The output command is mentioned in this wiki. It is unclear which package contains it? It was not installed when I did "sudo pacman -S sway".<br />
<br />
[[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 16:38, 4 January 2020 (UTC)<br />
<br />
:"output" is not a shell command, but sway command. You need to install {{Pkg|swaybg}} as described in [[Sway#Wallpaper]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:26, 4 January 2020 (UTC)<br />
<br />
:I did install swaybg. What do you mean with "output is a sway command"? [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 17:44, 4 January 2020 (UTC)<br />
<br />
:fixed it, "sway output ..." did the job. Perhaps this can be clarified? It wasn't clear to me that output wasn't a shell command ... [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 18:00, 4 January 2020 (UTC)<br />
<br />
: I fixed another {{ic|output}} being formatted as if it were a command. Hopefully, every occurrence is resolved by now thus I am closing the discussion. Feel free to re-open it if you object. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:18, 15 March 2021 (UTC)<br />
<br />
== Mention the `--locked` option for keybindings ==<br />
<br />
When the option `--locked` is used on keybindings, they also work while sway is locked with `swaylock`. It is a great feature for e.g. media or brightness keys and definitely worth mentioning in the wiki; however I'm unsure as to where this information would fit best: under 'Custom Keybindings' or somewhere in the 'Tips and Tricks' section? What do you all think? [[User:Bloor|Bloor]] ([[User talk:Bloor|talk]]) 13:36, 12 March 2020 (UTC)<br />
<br />
: I think the current solution at [[Sway#Custom keybindings]] is just fine. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:19, 15 March 2021 (UTC)<br />
<br />
== XWayland launchers still getting stuck an issue? ==<br />
<br />
The Application Launches section mentions a problem with some X11-based launchers getting stuck:<br />
<br />
https://wiki.archlinux.org/index.php/Sway#Application_launchers<br />
<br />
Is this still an issue since this patch was added to Sway 1.5?<br />
<br />
https://github.com/swaywm/sway/issues/4693<br />
<br />
{{Unsigned|23:42, 18 August 2020 (UTC)|Markstos}}<br />
<br />
:The section does not mention popup windows at all, so I think it's still the same problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:04, 19 August 2020 (UTC)<br />
<br />
== Color temperature adjustment ==<br />
<br />
Perhaps there should be a link to [[Backlight#Wayland]] somewhere on the page to inform people of {{Pkg|gammastep}}?<br />
<br />
[[User:Forgonewarrior|Forgonewarrior]] ([[User talk:Forgonewarrior|talk]]) 17:00, 6 January 2021 (UTC)<br />
<br />
:Yes, it can be done like [[Sway#Screen capture and screen sharing]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:14, 7 January 2021 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:Sway&diff=655055Talk:Sway2021-03-15T20:18:42Z<p>Edh: /* Unclear how to start 'output' command as it is not part of minimal installation? */ Closing as there are no loose `output` statements in the article anymore</p>
<hr />
<div>== 'xwayland disable' is not necessary to run programs natively under Wayland ==<br />
<br />
I'm afraid the statement is not totally true. Under one circumstance, which is when {{Pkg|xorg-server-xwayland}} is not installed, programs won't run(or render on screen) even with [[Wayland#GUI libraries|GUI libraries]] env variables properly set. Maybe a bug?. I've noticed on sway log that {{ic|xwayland.c}} function of {{Pkg|wlroots}} isn't called if and only if {{ic|xwayland disable}} is set.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
This is a GTK+ bug. It tries to connect to Xwayland even if it only uses Wayland. I've no idea why, it would be nice to report this to the GTK+ devs and figure out how to fix it.<br />
<br />
If you don't disable Xwayland and have it uninstalled, you'll have an invalid `DISPLAY` set.<br />
<br />
[[User:Emersion|Emersion]] ([[User talk:Emersion|talk]]) 21:51, 5 May 2019 (UTC)<br />
<br />
== <s>Keeping XWayland enabled is good for programs that don't work otherwise</s> ==<br />
<br />
It depends on user choice. I think having a wiki section on how to disable xwayland may benefit those who want to avoid X.Org.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
: Agreed. However, by now there already is a dedicated section about this at [[Sway#XWayland]]. Thus, I think it is safe to close this discussion. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:11, 15 March 2021 (UTC)<br />
<br />
== <s>Making Kwallet access possible in KDE programs</s> ==<br />
<br />
The article contained the required information before the latest revert to date. Unlike the comment by the moderator suggests, the information is not generic for all graphical environments (unlocking via PAM is sufficient for e.g. Gnome, but not Sway).<br />
[[User:Aufkrawall|Aufkrawall]] ([[User talk:Aufkrawall|talk]]) 16:03, 7 December 2019 (UTC)<br />
<br />
:In any case, the information is not specific to Sway so it does not belong to this page. Please add it to [[Kwallet]] instead. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:13, 7 December 2019 (UTC)<br />
<br />
: I have not been involved in the discussion but considering the existence of [[Kwallet#Unlock KDE Wallet automatically on login]] and no reply to this section for more than a year, I am closing it for now. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:15, 15 March 2021 (UTC)<br />
<br />
== <s>Unclear how to start 'output' command as it is not part of minimal installation?</s> ==<br />
<br />
The output command is mentioned in this wiki. It is unclear which package contains it? It was not installed when I did "sudo pacman -S sway".<br />
<br />
[[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 16:38, 4 January 2020 (UTC)<br />
<br />
:"output" is not a shell command, but sway command. You need to install {{Pkg|swaybg}} as described in [[Sway#Wallpaper]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:26, 4 January 2020 (UTC)<br />
<br />
:I did install swaybg. What do you mean with "output is a sway command"? [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 17:44, 4 January 2020 (UTC)<br />
<br />
:fixed it, "sway output ..." did the job. Perhaps this can be clarified? It wasn't clear to me that output wasn't a shell command ... [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 18:00, 4 January 2020 (UTC)<br />
<br />
: I fixed another {{ic|output}} being formatted as if it were a command. Hopefully, every occurrence is resolved by now thus I am closing the discussion. Feel free to re-open it if you object. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:18, 15 March 2021 (UTC)<br />
<br />
== Mention the `--locked` option for keybindings ==<br />
<br />
When the option `--locked` is used on keybindings, they also work while sway is locked with `swaylock`. It is a great feature for e.g. media or brightness keys and definitely worth mentioning in the wiki; however I'm unsure as to where this information would fit best: under 'Custom Keybindings' or somewhere in the 'Tips and Tricks' section? What do you all think? [[User:Bloor|Bloor]] ([[User talk:Bloor|talk]]) 13:36, 12 March 2020 (UTC)<br />
<br />
== XWayland launchers still getting stuck an issue? ==<br />
<br />
The Application Launches section mentions a problem with some X11-based launchers getting stuck:<br />
<br />
https://wiki.archlinux.org/index.php/Sway#Application_launchers<br />
<br />
Is this still an issue since this patch was added to Sway 1.5?<br />
<br />
https://github.com/swaywm/sway/issues/4693<br />
<br />
{{Unsigned|23:42, 18 August 2020 (UTC)|Markstos}}<br />
<br />
:The section does not mention popup windows at all, so I think it's still the same problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:04, 19 August 2020 (UTC)<br />
<br />
== Color temperature adjustment ==<br />
<br />
Perhaps there should be a link to [[Backlight#Wayland]] somewhere on the page to inform people of {{Pkg|gammastep}}?<br />
<br />
[[User:Forgonewarrior|Forgonewarrior]] ([[User talk:Forgonewarrior|talk]]) 17:00, 6 January 2021 (UTC)<br />
<br />
:Yes, it can be done like [[Sway#Screen capture and screen sharing]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:14, 7 January 2021 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:Sway&diff=655054Talk:Sway2021-03-15T20:15:11Z<p>Edh: /* Making Kwallet access possible in KDE programs */ No discussion since more than a year and amendments in the kwallet page lead be to believe the issue has been resolved; Closing</p>
<hr />
<div>== 'xwayland disable' is not necessary to run programs natively under Wayland ==<br />
<br />
I'm afraid the statement is not totally true. Under one circumstance, which is when {{Pkg|xorg-server-xwayland}} is not installed, programs won't run(or render on screen) even with [[Wayland#GUI libraries|GUI libraries]] env variables properly set. Maybe a bug?. I've noticed on sway log that {{ic|xwayland.c}} function of {{Pkg|wlroots}} isn't called if and only if {{ic|xwayland disable}} is set.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
This is a GTK+ bug. It tries to connect to Xwayland even if it only uses Wayland. I've no idea why, it would be nice to report this to the GTK+ devs and figure out how to fix it.<br />
<br />
If you don't disable Xwayland and have it uninstalled, you'll have an invalid `DISPLAY` set.<br />
<br />
[[User:Emersion|Emersion]] ([[User talk:Emersion|talk]]) 21:51, 5 May 2019 (UTC)<br />
<br />
== <s>Keeping XWayland enabled is good for programs that don't work otherwise</s> ==<br />
<br />
It depends on user choice. I think having a wiki section on how to disable xwayland may benefit those who want to avoid X.Org.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
: Agreed. However, by now there already is a dedicated section about this at [[Sway#XWayland]]. Thus, I think it is safe to close this discussion. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:11, 15 March 2021 (UTC)<br />
<br />
== <s>Making Kwallet access possible in KDE programs</s> ==<br />
<br />
The article contained the required information before the latest revert to date. Unlike the comment by the moderator suggests, the information is not generic for all graphical environments (unlocking via PAM is sufficient for e.g. Gnome, but not Sway).<br />
[[User:Aufkrawall|Aufkrawall]] ([[User talk:Aufkrawall|talk]]) 16:03, 7 December 2019 (UTC)<br />
<br />
:In any case, the information is not specific to Sway so it does not belong to this page. Please add it to [[Kwallet]] instead. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:13, 7 December 2019 (UTC)<br />
<br />
: I have not been involved in the discussion but considering the existence of [[Kwallet#Unlock KDE Wallet automatically on login]] and no reply to this section for more than a year, I am closing it for now. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:15, 15 March 2021 (UTC)<br />
<br />
== Unclear how to start 'output' command as it is not part of minimal installation? ==<br />
<br />
The output command is mentioned in this wiki. It is unclear which package contains it? It was not installed when I did "sudo pacman -S sway".<br />
<br />
[[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 16:38, 4 January 2020 (UTC)<br />
<br />
:"output" is not a shell command, but sway command. You need to install {{Pkg|swaybg}} as described in [[Sway#Wallpaper]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:26, 4 January 2020 (UTC)<br />
<br />
:I did install swaybg. What do you mean with "output is a sway command"? [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 17:44, 4 January 2020 (UTC)<br />
<br />
:fixed it, "sway output ..." did the job. Perhaps this can be clarified? It wasn't clear to me that output wasn't a shell command ... [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 18:00, 4 January 2020 (UTC)<br />
<br />
== Mention the `--locked` option for keybindings ==<br />
<br />
When the option `--locked` is used on keybindings, they also work while sway is locked with `swaylock`. It is a great feature for e.g. media or brightness keys and definitely worth mentioning in the wiki; however I'm unsure as to where this information would fit best: under 'Custom Keybindings' or somewhere in the 'Tips and Tricks' section? What do you all think? [[User:Bloor|Bloor]] ([[User talk:Bloor|talk]]) 13:36, 12 March 2020 (UTC)<br />
<br />
== XWayland launchers still getting stuck an issue? ==<br />
<br />
The Application Launches section mentions a problem with some X11-based launchers getting stuck:<br />
<br />
https://wiki.archlinux.org/index.php/Sway#Application_launchers<br />
<br />
Is this still an issue since this patch was added to Sway 1.5?<br />
<br />
https://github.com/swaywm/sway/issues/4693<br />
<br />
{{Unsigned|23:42, 18 August 2020 (UTC)|Markstos}}<br />
<br />
:The section does not mention popup windows at all, so I think it's still the same problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:04, 19 August 2020 (UTC)<br />
<br />
== Color temperature adjustment ==<br />
<br />
Perhaps there should be a link to [[Backlight#Wayland]] somewhere on the page to inform people of {{Pkg|gammastep}}?<br />
<br />
[[User:Forgonewarrior|Forgonewarrior]] ([[User talk:Forgonewarrior|talk]]) 17:00, 6 January 2021 (UTC)<br />
<br />
:Yes, it can be done like [[Sway#Screen capture and screen sharing]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:14, 7 January 2021 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:Sway&diff=655053Talk:Sway2021-03-15T20:11:07Z<p>Edh: /* Keeping XWayland enabled is good for programs that don't work otherwise */ Re: implemented in Sway#XWayland; Closing</p>
<hr />
<div>== 'xwayland disable' is not necessary to run programs natively under Wayland ==<br />
<br />
I'm afraid the statement is not totally true. Under one circumstance, which is when {{Pkg|xorg-server-xwayland}} is not installed, programs won't run(or render on screen) even with [[Wayland#GUI libraries|GUI libraries]] env variables properly set. Maybe a bug?. I've noticed on sway log that {{ic|xwayland.c}} function of {{Pkg|wlroots}} isn't called if and only if {{ic|xwayland disable}} is set.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
This is a GTK+ bug. It tries to connect to Xwayland even if it only uses Wayland. I've no idea why, it would be nice to report this to the GTK+ devs and figure out how to fix it.<br />
<br />
If you don't disable Xwayland and have it uninstalled, you'll have an invalid `DISPLAY` set.<br />
<br />
[[User:Emersion|Emersion]] ([[User talk:Emersion|talk]]) 21:51, 5 May 2019 (UTC)<br />
<br />
== <s>Keeping XWayland enabled is good for programs that don't work otherwise</s> ==<br />
<br />
It depends on user choice. I think having a wiki section on how to disable xwayland may benefit those who want to avoid X.Org.<br />
<br />
[[User:Rahcor|Rahcor]] ([[User talk:Rahcor|talk]]) 21:25, 5 May 2019 (UTC)<br />
<br />
: Agreed. However, by now there already is a dedicated section about this at [[Sway#XWayland]]. Thus, I think it is safe to close this discussion. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 20:11, 15 March 2021 (UTC)<br />
<br />
== Making Kwallet access possible in KDE programs ==<br />
<br />
The article contained the required information before the latest revert to date. Unlike the comment by the moderator suggests, the information is not generic for all graphical environments (unlocking via PAM is sufficient for e.g. Gnome, but not Sway).<br />
[[User:Aufkrawall|Aufkrawall]] ([[User talk:Aufkrawall|talk]]) 16:03, 7 December 2019 (UTC)<br />
<br />
:In any case, the information is not specific to Sway so it does not belong to this page. Please add it to [[Kwallet]] instead. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:13, 7 December 2019 (UTC)<br />
<br />
== Unclear how to start 'output' command as it is not part of minimal installation? ==<br />
<br />
The output command is mentioned in this wiki. It is unclear which package contains it? It was not installed when I did "sudo pacman -S sway".<br />
<br />
[[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 16:38, 4 January 2020 (UTC)<br />
<br />
:"output" is not a shell command, but sway command. You need to install {{Pkg|swaybg}} as described in [[Sway#Wallpaper]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:26, 4 January 2020 (UTC)<br />
<br />
:I did install swaybg. What do you mean with "output is a sway command"? [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 17:44, 4 January 2020 (UTC)<br />
<br />
:fixed it, "sway output ..." did the job. Perhaps this can be clarified? It wasn't clear to me that output wasn't a shell command ... [[User:Bronze|Bronze]] ([[User talk:Bronze|talk]]) 18:00, 4 January 2020 (UTC)<br />
<br />
== Mention the `--locked` option for keybindings ==<br />
<br />
When the option `--locked` is used on keybindings, they also work while sway is locked with `swaylock`. It is a great feature for e.g. media or brightness keys and definitely worth mentioning in the wiki; however I'm unsure as to where this information would fit best: under 'Custom Keybindings' or somewhere in the 'Tips and Tricks' section? What do you all think? [[User:Bloor|Bloor]] ([[User talk:Bloor|talk]]) 13:36, 12 March 2020 (UTC)<br />
<br />
== XWayland launchers still getting stuck an issue? ==<br />
<br />
The Application Launches section mentions a problem with some X11-based launchers getting stuck:<br />
<br />
https://wiki.archlinux.org/index.php/Sway#Application_launchers<br />
<br />
Is this still an issue since this patch was added to Sway 1.5?<br />
<br />
https://github.com/swaywm/sway/issues/4693<br />
<br />
{{Unsigned|23:42, 18 August 2020 (UTC)|Markstos}}<br />
<br />
:The section does not mention popup windows at all, so I think it's still the same problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:04, 19 August 2020 (UTC)<br />
<br />
== Color temperature adjustment ==<br />
<br />
Perhaps there should be a link to [[Backlight#Wayland]] somewhere on the page to inform people of {{Pkg|gammastep}}?<br />
<br />
[[User:Forgonewarrior|Forgonewarrior]] ([[User talk:Forgonewarrior|talk]]) 17:00, 6 January 2021 (UTC)<br />
<br />
:Yes, it can be done like [[Sway#Screen capture and screen sharing]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:14, 7 January 2021 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655051Sway2021-03-15T19:56:50Z<p>Edh: /* HiDPI */ Streamline syntax and use hc template here too + reference the default configuration file again as done in all previous sections</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set the configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}.<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}). These need to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
{{hc|~/.config/sway/config|<br />
output <name> scale <factor><br />
}}<br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655050Sway2021-03-15T19:54:46Z<p>Edh: /* Input devices */ Remove excessive example which is already described properly</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set the configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}.<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}). These need to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655049Sway2021-03-15T19:53:57Z<p>Edh: /* Input devices */ Add missing "the"s</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set the configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}. For example, to set the pointer acceleration:<br />
<br />
{{hc|~/.config/sway/config|<br />
input "2:14:ETPS/2_Elantech_Touchpad" pointer_accel 0.2<br />
}}<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655048Sway2021-03-15T19:51:56Z<p>Edh: /* Wallpaper */ Minor reordering and choice of word</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
The following line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}. For example, to set pointer acceleration:<br />
<br />
{{hc|~/.config/sway/config|<br />
input "2:14:ETPS/2_Elantech_Touchpad" pointer_accel 0.2<br />
}}<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655047Sway2021-03-15T19:49:16Z<p>Edh: /* Wallpaper */ Remove reference to specific long released sway version; Sway version 1.1.1 was released on Jun 3, 2019; IMHO there is no need to mention the specific version anymore as this might imply that Arch still somehow distributes this version</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
The displaying of a wallpaper in sway is handled by a dedicated program which is packaged separately as {{Pkg|swaybg}}. It is needed in order to run the output command.<br />
<br />
This line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}. For example, to set pointer acceleration:<br />
<br />
{{hc|~/.config/sway/config|<br />
input "2:14:ETPS/2_Elantech_Touchpad" pointer_accel 0.2<br />
}}<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655046Sway2021-03-15T19:44:43Z<p>Edh: /* Statusbar */ Move tip on the existence of waybar above the i3status explanation</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
=== Wallpaper ===<br />
<br />
Since release 1.1.1 the wallpaper part of the SwayWM project was moved to {{Pkg|swaybg}}, which is needed in order to run the output command.<br />
<br />
This line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}. For example, to set pointer acceleration:<br />
<br />
{{hc|~/.config/sway/config|<br />
input "2:14:ETPS/2_Elantech_Touchpad" pointer_accel 0.2<br />
}}<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655045Sway2021-03-15T19:43:53Z<p>Edh: /* Statusbar */ Remove sentence suggesting that the default sway config is required even though the bar is already configured just fine via the here outlined config</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
=== Wallpaper ===<br />
<br />
Since release 1.1.1 the wallpaper part of the SwayWM project was moved to {{Pkg|swaybg}}, which is needed in order to run the output command.<br />
<br />
This line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}. For example, to set pointer acceleration:<br />
<br />
{{hc|~/.config/sway/config|<br />
input "2:14:ETPS/2_Elantech_Touchpad" pointer_accel 0.2<br />
}}<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655044Sway2021-03-15T19:41:06Z<p>Edh: /* Statusbar */ Improve wording</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to enable colored output for i3status, you need to adjust the following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
In both examples, the system-wide installed configuration files have been copied over to the user directory and then modified. <br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
=== Wallpaper ===<br />
<br />
Since release 1.1.1 the wallpaper part of the SwayWM project was moved to {{Pkg|swaybg}}, which is needed in order to run the output command.<br />
<br />
This line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}. For example, to set pointer acceleration:<br />
<br />
{{hc|~/.config/sway/config|<br />
input "2:14:ETPS/2_Elantech_Touchpad" pointer_accel 0.2<br />
}}<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655043Sway2021-03-15T19:37:28Z<p>Edh: /* Keymap */ Simplify wording of config taking precedence over env</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}. The config options take precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to achieve colored output of i3status, you can adjust following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
In both examples, the system-wide installed configuration files have been copied over to the user directory and then modified. <br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
=== Wallpaper ===<br />
<br />
Since release 1.1.1 the wallpaper part of the SwayWM project was moved to {{Pkg|swaybg}}, which is needed in order to run the output command.<br />
<br />
This line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}. For example, to set pointer acceleration:<br />
<br />
{{hc|~/.config/sway/config|<br />
input "2:14:ETPS/2_Elantech_Touchpad" pointer_accel 0.2<br />
}}<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Sway&diff=655042Sway2021-03-15T19:35:35Z<p>Edh: /* Configuration */ Simplify introduction; Remove reference to DFALLBACK_CONFIG_DIR in favor of keeping the introduction simple</p>
<hr />
<div>[[Category:Wayland compositors]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
{{Note|All proprietary graphics drivers are [https://github.com/swaywm/sway/wiki#nvidia-users not supported], including [[NVIDIA]].}}<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
The default application launcher is {{Pkg|dmenu}} and the default terminal emulator is {{Pkg|alacritty}}. Before starting ''sway'' it is advisable to either install them or set a new launcher and terminal in the configuration.<br />
<br />
== Starting ==<br />
<br />
=== Manually ===<br />
<br />
To start Sway, simply type {{ic|sway}} in the Linux console.<br />
<br />
=== Automatically on TTY login ===<br />
<br />
Similarly to X, Sway can be started by adding the following to your shell initialization file (see [[Command-line shell#Login shell]])<br />
<br />
{{bc|1=<nowiki><br />
if [ -z $DISPLAY ] && [ "$(tty)" == "/dev/tty1" ]; then<br />
exec sway<br />
fi<br />
</nowiki>}}<br />
<br />
For more details, see [[Xinit#Autostart X at login]]<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, you may copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file located at {{ic|/etc/sway/config}} to {{ic|~/.config/sway/config}}. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<br />
input * {<br />
xkb_layout "us,de,ru"<br />
xkb_variant "colemak,,typewriter"<br />
xkb_options "grp:win_space_toggle"<br />
}<br />
<br />
input <identifier> xkb_model "pc101"<br />
}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting {{ic|sway}}, with config options taking precedence over environment variables.<br />
<br />
=== Typematic delay and rate ===<br />
<br />
To change typematic delay and rate, you can add the following lines to your {{ic|input}} section:<br />
<br />
{{hc|~/.config/sway/config|<br />
input <identifier> repeat_delay 300<br />
input <identifier> repeat_rate 30<br />
}}<br />
<br />
=== Statusbar ===<br />
<br />
''sway'' ships with a default status bar in the form of ''swaybar'' which runs in a pure [[Wayland]] environment. ''swaybar'' can call a shell script or other program to show information in the status bar. See {{man|5|sway-bar}} and {{man|7|swaybar-protocol}} for details.<br />
<br />
Installing [[i3#i3status|i3status]] is an option to obtain a practical, default status bar under Wayland. All you have to do is add the following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<br />
bar {<br />
status_command i3status<br />
}<br />
}}<br />
<br />
If you want to achieve colored output of i3status, you can adjust following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|2=<br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
}}<br />
<br />
In both examples, the system-wide installed configuration files have been copied over to the user directory and then modified. <br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
=== Wallpaper ===<br />
<br />
Since release 1.1.1 the wallpaper part of the SwayWM project was moved to {{Pkg|swaybg}}, which is needed in order to run the output command.<br />
<br />
This line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<br />
output "*" bg /path/to/image fill<br />
}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
You may use {{AUR|azote}} as the GTK3 frontend to swaybg.<br />
<br />
Solid colors may be set as follows:<br />
<br />
output * bg #000000 solid_color<br />
<br />
=== Input devices ===<br />
<br />
It is possible to tweak specific input device configurations. For example, to enable tap-to-click and natural scrolling for all touchpads:<br />
<br />
{{hc|~/.config/sway/config|<br />
input type:touchpad {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
}}<br />
<br />
To set configuration for a particular touchpad, use {{ic|swaymsg -t get_inputs}} to obtain a device identifier and use it instead of {{ic|type:touchpad}}. For example, to set pointer acceleration:<br />
<br />
{{hc|~/.config/sway/config|<br />
input "2:14:ETPS/2_Elantech_Touchpad" pointer_accel 0.2<br />
}}<br />
<br />
{{Note|The output from the {{ic|swaymsg -t get_inputs}} command may contain "\" to escape symbols like "/" (e.g. {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.}}<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control volume, monitor brightness or media players:<br />
<br />
{{hc|~/.config/sway/config|<br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
bindsym XF86Search exec bemenu-run<br />
}}<br />
<br />
See [[PulseAudio#Keyboard volume control]], [[Advanced Linux Sound Architecture#Keyboard volume control]], [[Backlight#Backlight utilities]] and [[MPRIS]] for details and alternative utilities.<br />
<br />
To allow a keybinding to be executed while the lockscreen is active add the {{ic|--locked}} parameter to bindsym.<br />
<br />
bindsym --locked XF86AudioPlay exec playerctl play-pause<br />
<br />
{{Tip|{{AUR|wev}} is a tool which provides functionality similar to that of {{Pkg|xorg-xev}}, but on Wayland.}}<br />
<br />
==== Graphical indicator bars ====<br />
<br />
It is often desirable to have the current level of some percentage-valued setting, such as brightness or volume, be indicated by a graphical bar when it is adjusted. A good option for providing this facility in Sway is {{AUR|wob}} (alternatively {{AUR|wob-git}}), which provides a subset of the functionality of the popular X tool {{AUR|xob}} but as a native Wayland utility implementing the layer-shell protocol. See the [https://github.com/francma/wob project website] for usage examples.<br />
<br />
=== Floating windows ===<br />
<br />
To enable floating windows or window assignments, open the application and then use the {{ic|app_id}}, the {{ic|class}}, the {{ic|instance}} and the {{ic|title}} attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.<br />
<br />
$ swaymsg -t get_tree<br />
<br />
To get only the {{ic|app_id}}'s of all open windows use:<br />
<br />
$ swaymsg -t get_tree | grep "app_id"<br />
<br />
To get the {{ic|app_id}} of the focused window use:<br />
<br />
$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'<br />
<br />
If the {{ic|app_id}} happens to be null for some windows, you might have to use the {{ic|class}} and/or the {{ic|instance}} attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.<br />
<br />
{{hc|~/.config/sway/config|2=<br />
for_window [app_id="galculator"] floating enable<br />
assign [class="firefox"] -> 3<br />
assign [class="^Urxvt$" instance="^htop$"] -> 9<br />
}}<br />
<br />
This is similar to using {{Pkg|xorg-xprop}} to find the {{ic|class}} or {{ic|wm_name}} attributes in [[X11]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== XWayland ===<br />
<br />
See [[Wayland#XWayland]] for details and an overview of available packages.<br />
<br />
The use of XWayland is enabled by default.<br />
<br />
If you would like to disable XWayland entirely and run a "pure" Wayland session, set the following config key to deactivate the use of XWayland:<br />
<br />
{{hc|~/.config/sway/config|<br />
xwayland disable<br />
}}<br />
<br />
{{Note|Some programs need [[Wayland#GUI_libraries|special environment variables or configuration options]] to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep XWayland on so that legacy applications can be used.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enable CapsLock/NumLock ===<br />
Enable the capslock and/or numlock by adding the following lines to your sway config<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_capslock enable<br />
input * xkb_numlock enable<br />
</nowiki>}}<br />
{{Note|1=Enabling these options may cause Firefox to crash upon reloading your sway config file: [https://bugzilla.mozilla.org/show_bug.cgi?id=1652820 Bugzilla 1652820]}}<br />
<br />
=== Current keyboard layout ===<br />
<br />
The current keyboard layout can be retrieved as follows, where {{ic|''kbd_identifier''}} needs to be replaced with your keyboard's identifier:<br />
<br />
$ swaymsg -t get_inputs {{!}} jq -r '.[] {{!}} select(.identifier == "''kbd_identifier''") {{!}} .xkb_active_layout_name'<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture and screen sharing ===<br />
<br />
See [[Screen capture#Wayland]].<br />
<br />
=== Color temperature adjustment ===<br />
<br />
See [[Backlight#Wayland]].<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change cursor theme and size ===<br />
<br />
To set the [[cursor theme]] and size:<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme ''my_cursor_theme'' ''my_cursor_size''<br />
}}<br />
<br />
Where {{ic|''my_cursor_theme''}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|''my_cursor_size''}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the application to see the changes.<br />
<br />
{{Note|Wayland uses client-side cursors. It's possible that applications do not evaluate the values of {{ic|$XCURSOR_SIZE}} and {{ic|$XCURSOR_THEME}}.}}<br />
<br />
=== Manage Sway-specific daemons with systemd ===<br />
<br />
{{Merge|systemd/User|The {{ic|graphical-session.target}} should be described generally on the systemd page. [[systemd/User#Xorg and systemd]] is flagged for expansion.}}<br />
<br />
Users may want to start some services/daemons (such as {{Pkg|swayidle}} or {{Pkg|kanshi}}) only when the current window manager is Sway, and they may also want these services to stop when Sway stops. This can be done by creating a {{ic|sway-session.target}} and let those daemons/services wanted by {{ic|sway-session.target}}. This systemd target should be a user target (see [[systemd/User]]). For example:<br />
<br />
{{hc|1=~/.config/systemd/user/sway-session.target|2=<br />
[Unit]<br />
Description=Sway compositor session<br />
Documentation=man:systemd.special<br />
BindsTo=graphical-session.target<br />
Wants=graphical-session-pre.target<br />
After=graphical-session-pre.target<br />
}}<br />
<br />
Then, add the following line to Sway's config file (for example, append the line to {{ic|~/.config/sway/config}}, or add a new file to {{ic|/etc/sway/config.d/}}):<br />
<br />
{{hc|1=~/.config/sway/config|2=<br />
...<br />
...<br />
...<br />
exec_always "systemctl --user import-environment; systemctl --user start sway-session.target"<br />
}}<br />
<br />
With the above line in the configuration file, whenever Sway starts, it also activates {{ic|sway-session.target}}.<br />
<br />
Finally, link the desired services to {{ic|sway-session.target}}. For example, adding a {{Pkg|kanshi}} (or {{AUR|kanshi-git}}) service:<br />
<br />
{{hc|1=~/.config/systemd/user/kanshi.service|2=<br />
[Unit]<br />
Description=Dynamic output configuration for Wayland compositors<br />
Documentation=https://github.com/emersion/kanshi<br />
BindsTo=sway-session.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/kanshi<br />
<br />
[Install]<br />
WantedBy=sway-session.target<br />
}}<br />
<br />
When this service is enabled (with {{ic|--user}} flag), it is only activated when Sway is running and deactivated when Sway stops:<br />
<br />
{{bc|$ systemctl --user enable --now kanshi.service}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
{{Tip|Sway's wiki also has a [https://github.com/swaywm/sway/wiki#program-launchers list of known application launchers].}}<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
Also {{ic|krunner}} binary provided by {{Pkg|plasma-workspace}} package can serve as launcher, offering both XWayland and native Wayland support.<br />
<br />
{{AUR|rofi-lbonn-wayland-git}} is a fork of {{Pkg|rofi}} that works in Wayland and also has an {{ic|-x11}} flag if you need to launch it in an X11 session. <br />
<br />
{{Pkg|wofi}} is a command launcher, that provides some of the same features as rofi but running under Wayland. wofi lacks some features from rofi like an SSH mode and a window-switching mode. It is based on {{Pkg|wlroots}} library and use GTK3 for rendering. It works pretty well with sway.<br />
<br />
=== Virtualization ===<br />
<br />
Sway works with both [[VirtualBox]] and [[VMware]] ESXi.<br />
<br />
==== Unable to start Sway from tty ====<br />
<br />
For ESXi, you need to enable 3D support under the ''Hardware Configuration > Video card settings''. See also [[VMware#Enable 3D graphics on Intel and Optimus]].<br />
<br />
==== No visible cursor ====<br />
<br />
When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [https://github.com/swaywm/sway/issues/3814]:<br />
<br />
$ export WLR_NO_HARDWARE_CURSORS=1<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
Alternatively you can create a variable {{ic|set $mybind bindsym --to-code}} and then replace all instances of {{ic|bindsym}} with {{ic|$mybind}} like so: {{ic|$mybind $mod+w thing}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
Some issues with Java applications have been fixed in OpenJDK 11 and Sway 1.5. However, certain applications require additional configuration to use newer versions of OpenJDK, in the case of Android Studio you must set {{ic|1=STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/}}. [https://github.com/swaywm/sway/issues/5414]<br />
<br />
=== Scroll on border ===<br />
<br />
If using the mouse scroll wheel on an application's border crashes sway, you could use {{ic|border none}} for the {{ic|app_id}} (e.g. Firefox).<br />
<br />
=== Program cannot open display ===<br />
<br />
If a program crashes on start with the error message "cannot open display", it is likely that the program you are using is an X11 program. You can use the XWayland compatibility layer to run X11 programs under Wayland, see [[#XWayland]] for details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Edhhttps://wiki.archlinux.org/index.php?title=Ranger&diff=653940Ranger2021-03-03T19:50:15Z<p>Edh: /* Defining commands */ Highlight that the stated command mustn't be the only command in the file</p>
<hr />
<div>{{DISPLAYTITLE:ranger}}<br />
[[Category:File managers]]<br />
[[Category:Console applications]]<br />
[[ar:Ranger]]<br />
[[de:Ranger]]<br />
[[es:Ranger]]<br />
[[fa:ranger]]<br />
[[fr:ranger]]<br />
[[ja:Ranger]]<br />
[[zh-hans:Ranger]]<br />
{{Related articles start}}<br />
{{Related|Midnight Commander}}<br />
{{Related|nnn}}<br />
{{Related|vifm}}<br />
{{Related articles end}}<br />
[https://ranger.github.io/ ranger] is a text-based file manager written in [[Python]]. Directories are displayed in one pane with three columns. Moving between them is accomplished with keystrokes, bookmarks, the mouse or the command history. File previews and directory contents show automatically for the current selection.<br />
<br />
Features include: [[vi]]-style key bindings, bookmarks, selections, tagging, tabs, command history, the ability to make symbolic links, several console modes, and a task view. ''ranger'' has customizable commands and key bindings, including bindings to external scripts. Ranger also comes with its own [[file opener]], {{man|1|rifle}}. The closest competitors are [[Vifm]] and [https://github.com/gokcehan/lf lf].<br />
<br />
== Installation ==<br />
[[Install]] the {{Pkg|ranger}} package, or {{AUR|ranger-git}} for the development version.<br />
<br />
== Usage ==<br />
<br />
To start ranger, launch a [[List of applications#Terminal emulators|terminal]] and run {{ic|ranger}}.<br />
<br />
{| class="wikitable"<br />
|+<br />
! Key !! Command<br />
|-<br />
| {{ic|?}} || Open the manual or list keybindings, commands and settings<br />
|-<br />
| {{ic|l}}, {{ic|Enter}} || Launch files<br />
|-<br />
| {{ic|j}}, {{ic|k}} || Select file in the current directory<br />
|-<br />
| {{ic|h}}, {{ic|l}} || Travel up and down in the directory tree<br />
|}<br />
<br />
== Configuration ==<br />
<br />
After startup, ranger creates a directory {{ic|~/.config/ranger}}. To copy the default configuration to this directory issue the following command:<br />
<br />
$ ranger --copy-config=all<br />
<br />
* {{ic|rc.conf}} - startup commands and key bindings<br />
* {{ic|commands.py}} - commands which are launched with {{ic|:}}<br />
* {{ic|rifle.conf}} - applications used when a given type of file is launched.<br />
<br />
{{ic|rc.conf}} only needs to include changes from the default file as both are loaded. For {{ic|commands.py}}, if you do not include the whole file, put this line at the top:<br />
<br />
from ranger.api.commands import *<br />
<br />
See {{man|1|ranger}} for general configuration.<br />
<br />
=== Move to trash ===<br />
<br />
To add a keybind that moves files to your trash directory {{ic|~/.local/share/Trash/files/}} with {{ic|DD}}, amend the configuration file as follows:<br />
{{hc|~/.config/ranger/rc.conf|<nowiki><br />
...<br />
map DD shell mv %s /home/${USER}/.local/share/Trash/files/<br />
...<br />
</nowiki>}}<br />
<br />
Alternatively, use GIO commandline tool provided by {{Pkg|glib2}} package:<br />
<br />
map DD shell gio trash %s<br />
<br />
Inspecting and emptying the "trash" is normally supported by graphical file managers such as {{Pkg|nautilus}}, but you can also see the trash with the command {{ic|gio list trash://}}, and empty it with: {{ic|gio trash --empty}}.<br />
<br />
=== Defining commands ===<br />
<br />
Continuing the above example, add the following entry to empty the trash directory {{ic|~/.Trash}}.<br />
<br />
{{hc|~/.config/ranger/commands.py|<nowiki><br />
...<br />
<br />
class empty(Command):<br />
""":empty<br />
<br />
Empties the trash directory ~/.Trash<br />
"""<br />
<br />
def execute(self):<br />
self.fm.run("rm -rf /home/myname/.Trash/{*,.[^.]*}")<br />
</nowiki>}}<br />
<br />
To use it, type {{ic|:empty}} and {{ic|Enter}} with tab completion as desired.<br />
<br />
{{Warning|{{ic|[^.]}} is an essential part of the above command. Without it, all files and directories of the form {{ic|..*}} will be deleted, wiping out everything in your home directory.}}<br />
<br />
=== Color schemes ===<br />
<br />
Ranger comes with four color schemes: {{ic|default}}, {{ic|jungle}}, {{ic|snow}} and {{ic|solarized}}.<br />
You can change your color scheme using:<br />
<br />
set colorscheme ''scheme''<br />
<br />
Custom color schemes can be placed in {{ic|~/.config/ranger/colorschemes}}.<br />
<br />
=== Color highlight in file previews ===<br />
<br />
Install the {{Pkg|python-pygments}} package, then copy {{ic|/usr/share/doc/ranger/config/scope.sh}} to {{ic|~/.config/ranger/scope.sh}} and edit the variable {{ic|PYGMENTIZE_STYLE}} in the configuration file of ranger to your liking. The complete list of supported themes can be obtained via {{ic|pygmentize -L style}}.<br />
<br />
=== File association ===<br />
<br />
Ranger uses its own file opener called {{ic|rifle}}.<br />
It's configured in {{ic|~/.config/ranger/rifle.conf}}. Run {{ic|1=ranger --copy-config=rifle}} if it does not exist. For example, the following line <br />
makes {{Pkg|kile}} the default program for tex files:<br />
<br />
ext tex = kile "$@"<br />
<br />
To open all files with {{Pkg|xdg-utils}}, make sure your {{ic|$EDITOR}} and {{ic|$PAGER}} are set and add:<br />
<br />
else = xdg-open "$1"<br />
label editor = "$EDITOR" -- "$@"<br />
label pager = "$PAGER" -- "$@"<br />
<br />
== Tips and tricks ==<br />
<br />
{{Template:Style|bad style}}<br />
<br />
=== Archives ===<br />
<br />
These commands use {{Pkg|atool}} to perform archive operations.<br />
<br />
==== Archive extraction ====<br />
<br />
The following command implements archive extraction of the selected items to the current directory.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class extract_here(Command):<br />
def execute(self):<br />
""" extract selected files to current directory."""<br />
cwd = self.fm.thisdir<br />
marked_files = tuple(cwd.get_selection())<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
one_file = marked_files[0]<br />
cwd = self.fm.thisdir<br />
original_path = cwd.path<br />
au_flags = ['-x', cwd.path]<br />
au_flags += self.line.split()[1:]<br />
au_flags += ['-e']<br />
<br />
self.fm.copy_buffer.clear()<br />
self.fm.cut_buffer = False<br />
if len(marked_files) == 1:<br />
descr = "extracting: " + os.path.basename(one_file.path)<br />
else:<br />
descr = "extracting files from: " + os.path.basename(<br />
one_file.dirname)<br />
obj = CommandLoader(args=['aunpack'] + au_flags<br />
+ [f.path for f in marked_files], descr=descr,<br />
read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
==== Compression ====<br />
<br />
The following command allows users to compress several files on the current directory by marking them and then calling {{ic|:compress ''package name''}}. It supports name suggestions by getting the basename of the current directory and appending several possibilities for the extension. You need to have {{pkg|atool}} installed, otherwise you will see an error message when you create the archive.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class compress(Command):<br />
def execute(self):<br />
""" Compress marked files to current directory """<br />
cwd = self.fm.thisdir<br />
marked_files = cwd.get_selection()<br />
<br />
if not marked_files:<br />
return<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
original_path = cwd.path<br />
parts = self.line.split()<br />
au_flags = parts[1:]<br />
<br />
descr = "compressing files in: " + os.path.basename(parts[1])<br />
obj = CommandLoader(args=['apack'] + au_flags + \<br />
[os.path.relpath(f.path, cwd.path) for f in marked_files], descr=descr, read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
<br />
def tab(self, tabnum):<br />
""" Complete with current folder name """<br />
<br />
extension = ['.zip', '.tar.gz', '.rar', '.7z']<br />
return ['compress ' + os.path.basename(self.fm.thisdir.path) + ext for ext in extension]<br />
</nowiki>}}<br />
<br />
=== External drives ===<br />
<br />
External drives can be automatically mounted with [[udev]] or [[udisks]]. The default key mappings to go to common mount points {{ic|/media}} and {{ic|/run/media/$USER}} are {{ic|gm}} and {{ic|gi}} respectively.<br />
<br />
=== Hidden files ===<br />
<br />
You can toggle the visibility of hidden files with the following command: {{ic|:set show_hidden!}}, or use {{ic|:set show_hidden true}} to make hidden files visible.<br />
<br />
To make this permanent, add the setting to your configuration file:<br />
<br />
{{hc|rc.conf|<nowiki><br />
set show_hidden true<br />
</nowiki>}}<br />
<br />
Alternatively, hidden files can be toggled by pressing {{ic|zh}}.<br />
<br />
=== Image mounting ===<br />
<br />
The following command assumes you are using [[CDemu]] as your image mounter and some kind of system like [[autofs]] which mounts the virtual drive to a specified location ('/media/virtualrom' in this case). '''Do not forget to change mountpath to reflect your system settings'''.<br />
<br />
To mount an image (or images) to a cdemud virtual drive from ranger you select the image files and then type ':mount' on the console. The mounting may actually take some time depending on your setup (in mine it may take as long as one minute) so the command uses a custom loader that waits until the mount directory is mounted and then opens it on the background in tab 9.<br />
<br />
{{bc|<nowiki><br />
import os, time<br />
from ranger.core.loader import Loadable<br />
from ranger.ext.signals import SignalDispatcher<br />
from ranger.ext.shell_escape import *<br />
<br />
class MountLoader(Loadable, SignalDispatcher):<br />
"""<br />
Wait until a directory is mounted<br />
"""<br />
def __init__(self, path):<br />
SignalDispatcher.__init__(self)<br />
descr = "Waiting for dir '" + path + "' to be mounted"<br />
Loadable.__init__(self, self.generate(), descr)<br />
self.path = path<br />
<br />
def generate(self):<br />
available = False<br />
while not available:<br />
try:<br />
if os.path.ismount(self.path):<br />
available = True<br />
except:<br />
pass<br />
yield<br />
time.sleep(0.03)<br />
self.signal_emit('after')<br />
<br />
class mount(Command):<br />
def execute(self):<br />
selected_files = self.fm.thisdir.get_selection()<br />
<br />
if not selected_files:<br />
return<br />
<br />
space = ' '<br />
self.fm.execute_command("cdemu -b system unload 0")<br />
self.fm.execute_command("cdemu -b system load 0 " + \<br />
space.join([shell_escape(f.path) for f in selected_files]))<br />
<br />
mountpath = "/media/virtualrom/"<br />
<br />
def mount_finished(path):<br />
currenttab = self.fm.current_tab<br />
self.fm.tab_open(9, mountpath)<br />
self.fm.tab_open(currenttab)<br />
<br />
obj = MountLoader(mountpath)<br />
obj.signal_bind('after', mount_finished)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
=== New tab in current folder ===<br />
<br />
You may have noticed there are two shortcuts for opening a new tab in home ({{ic|g}}{{ic|n}} and {{ic|Ctrl+n}}). Let us rebind {{ic|Ctrl+n}}:<br />
{{hc|rc.conf|<nowiki><br />
map <c-n> eval fm.tab_new('%d')<br />
</nowiki>}}<br />
<br />
=== PDF file preview ===<br />
By default, ranger will preview PDF files as text. However, you can preview PDF files as an image in ranger by first converting the PDF file to an image. Ranger stores the image previews in {{ic|~/.cache/ranger/}}. You either need to create this directory manually or set {{ic|preview_images}} to {{ic|true}} in {{ic|~/.config/ranger/rc.conf}} to tell {{ic|ranger}} to create it automatically at the next start. However, note that {{ic|preview_images}} does not need to be set to {{ic|true}} the whole time to preview PDF file as images, only {{ic|~/.cache/ranger}} directory is needed.<br />
<br />
To enable this feature, uncomment the appropriate lines in {{ic|/usr/share/doc/ranger/config/scope.sh}}, or add/uncomment these lines in your local file {{ic|~/.config/ranger/scope.sh}}.<br />
<br />
=== Shell tips ===<br />
<br />
==== Synchronize path ====<br />
<br />
Ranger provides a shell [[Bash/Functions|function]] {{ic|/usr/share/doc/ranger/examples/shell_automatic_cd.sh}}. Running {{ic|ranger_cd}} instead of {{ic|ranger}} will automatically ''cd'' to the last browsed folder.<br />
<br />
If you launch ranger from a graphical launcher (such as {{ic|$TERMCMD -e ranger}}, where TERMCMD is an X terminal), you cannot use {{ic|ranger_cd}}. Instead, create an executable script:<br />
<br />
{{hc|ranger-launcher.sh|<nowiki><br />
#!/bin/sh<br />
export RANGERCD=true<br />
$TERMCMD<br />
</nowiki>}}<br />
<br />
And add the following at the end of your shell configuration:<br />
<br />
{{hc|.''shell''rc|<nowiki><br />
$RANGERCD && unset RANGERCD && ranger_cd<br />
</nowiki>}}<br />
<br />
This will launch {{ic|ranger_cd}} only if the {{ic|RANGERCD}} variable is set. It is important to unset this variable again, otherwise launching a subshell from this terminal will automatically relaunch {{ic|ranger}}.<br />
<br />
==== Start a shell from ranger ====<br />
<br />
{{Accuracy|the shell seems to start in the correct directory by default with Ranger's {{ic|S}} key binding|section=Starting a shell in the current directory}}<br />
<br />
With the previous method you can switch to a shell in last browsed path simply by leaving ranger. However you may not want to quit ranger for several reasons (numerous opened tabs, copy in progress, etc.).<br />
You can start a shell from ranger ({{ic|S}} by default) without losing your ranger session. Unfortunately, the shell will not switch to the current folder automatically. Again, this can be solved with an executable script:<br />
<br />
{{hc|shellcd|<nowiki><br />
#!/bin/sh<br />
export AUTOCD="$(realpath "$1")"<br />
<br />
$SHELL<br />
</nowiki>}}<br />
<br />
and - as before - add this to at the very end of your shell configuration:<br />
<br />
{{hc|shellrc|<nowiki><br />
cd "$AUTOCD"<br />
</nowiki>}}<br />
<br />
Now you can change your shell binding for ranger:<br />
<br />
{{hc|rc.conf|<br />
map S shell shellcd %d<br />
}}<br />
<br />
Alternatively, you can make use of your shell history file if it has one. For instance, you could do this for [[zsh#Dirstack|zsh]]:<br />
<br />
{{hc|shellcd|<nowiki><br />
## Prepend argument to zsh dirstack.<br />
BUF="$(realpath "$1")<br />
$(grep -v "$(realpath "$1")" "$ZDIRS")"<br />
echo "$BUF" > "$ZDIRS"<br />
<br />
zsh<br />
</nowiki>}}<br />
<br />
Change ZDIRS for your dirstack.<br />
<br />
===== A simpler solution =====<br />
<br />
{{hc|rc.conf|<nowiki><br />
map S shell bash -c "cd %d; bash"<br />
</nowiki>}}<br />
This could probably be adapted to other shells as well.<br />
Instead of just running a shell (like the default config), this will run {{ic|cd}} in a shell, then execute a interactive shell which will not immediately exit so that you can continue with what you wanted.<br />
<br />
==== Preventing nested ranger instances ====<br />
<br />
You can start a shell in the current directory with {{ic|S}}, when you exit the shell you get back to your ranger instance.<br />
<br />
When you however forget that you already are in a ranger shell and start ranger again you end up with ranger running a shell running ranger.<br />
<br />
To prevent this you can create the following function in your [[Autostarting#On_shell_login_.2F_logout|shell's startup file]]:<br />
<br />
ranger() {<br />
if [ -z "$RANGER_LEVEL" ]; then<br />
/usr/bin/ranger "$@"<br />
else<br />
exit<br />
fi<br />
}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Artifacts in image preview ===<br />
<br />
Borderless columns may cause stripes in image previews. [https://bbs.linuxdistrocommunity.com/showthread.php?tid=1051] In {{ic|~/.config/ranger/rc.conf}} set:<br />
<br />
set draw_borders true<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=93025 BBS thread]<br />
* [http://dotshare.it/category/fms/ranger/ DotShare.it configurations]<br />
* [https://github.com/hut/ranger GitHub]<br />
* [https://github.com/ranger/ranger/wiki/Official-user-guide Official User Guide]<br />
* [https://www.digitalocean.com/community/tutorials/installing-and-using-ranger-a-terminal-file-manager-on-a-ubuntu-vps Installing and using ranger]<br />
* [https://lists.nongnu.org/mailman/listinfo/ranger-users Mailing list]<br />
* [https://bloerg.net/2012/10/17/ranger-file-manager.html Ranger tutorial]</div>Edhhttps://wiki.archlinux.org/index.php?title=Ranger&diff=653939Ranger2021-03-03T19:44:55Z<p>Edh: /* Color highlight in file previews */ Be more specific about the location of the configuration parameter</p>
<hr />
<div>{{DISPLAYTITLE:ranger}}<br />
[[Category:File managers]]<br />
[[Category:Console applications]]<br />
[[ar:Ranger]]<br />
[[de:Ranger]]<br />
[[es:Ranger]]<br />
[[fa:ranger]]<br />
[[fr:ranger]]<br />
[[ja:Ranger]]<br />
[[zh-hans:Ranger]]<br />
{{Related articles start}}<br />
{{Related|Midnight Commander}}<br />
{{Related|nnn}}<br />
{{Related|vifm}}<br />
{{Related articles end}}<br />
[https://ranger.github.io/ ranger] is a text-based file manager written in [[Python]]. Directories are displayed in one pane with three columns. Moving between them is accomplished with keystrokes, bookmarks, the mouse or the command history. File previews and directory contents show automatically for the current selection.<br />
<br />
Features include: [[vi]]-style key bindings, bookmarks, selections, tagging, tabs, command history, the ability to make symbolic links, several console modes, and a task view. ''ranger'' has customizable commands and key bindings, including bindings to external scripts. Ranger also comes with its own [[file opener]], {{man|1|rifle}}. The closest competitors are [[Vifm]] and [https://github.com/gokcehan/lf lf].<br />
<br />
== Installation ==<br />
[[Install]] the {{Pkg|ranger}} package, or {{AUR|ranger-git}} for the development version.<br />
<br />
== Usage ==<br />
<br />
To start ranger, launch a [[List of applications#Terminal emulators|terminal]] and run {{ic|ranger}}.<br />
<br />
{| class="wikitable"<br />
|+<br />
! Key !! Command<br />
|-<br />
| {{ic|?}} || Open the manual or list keybindings, commands and settings<br />
|-<br />
| {{ic|l}}, {{ic|Enter}} || Launch files<br />
|-<br />
| {{ic|j}}, {{ic|k}} || Select file in the current directory<br />
|-<br />
| {{ic|h}}, {{ic|l}} || Travel up and down in the directory tree<br />
|}<br />
<br />
== Configuration ==<br />
<br />
After startup, ranger creates a directory {{ic|~/.config/ranger}}. To copy the default configuration to this directory issue the following command:<br />
<br />
$ ranger --copy-config=all<br />
<br />
* {{ic|rc.conf}} - startup commands and key bindings<br />
* {{ic|commands.py}} - commands which are launched with {{ic|:}}<br />
* {{ic|rifle.conf}} - applications used when a given type of file is launched.<br />
<br />
{{ic|rc.conf}} only needs to include changes from the default file as both are loaded. For {{ic|commands.py}}, if you do not include the whole file, put this line at the top:<br />
<br />
from ranger.api.commands import *<br />
<br />
See {{man|1|ranger}} for general configuration.<br />
<br />
=== Move to trash ===<br />
<br />
To add a keybind that moves files to your trash directory {{ic|~/.local/share/Trash/files/}} with {{ic|DD}}, amend the configuration file as follows:<br />
{{hc|~/.config/ranger/rc.conf|<nowiki><br />
...<br />
map DD shell mv %s /home/${USER}/.local/share/Trash/files/<br />
...<br />
</nowiki>}}<br />
<br />
Alternatively, use GIO commandline tool provided by {{Pkg|glib2}} package:<br />
<br />
map DD shell gio trash %s<br />
<br />
Inspecting and emptying the "trash" is normally supported by graphical file managers such as {{Pkg|nautilus}}, but you can also see the trash with the command {{ic|gio list trash://}}, and empty it with: {{ic|gio trash --empty}}.<br />
<br />
=== Defining commands ===<br />
<br />
Continuing the above example, add the following entry to empty the trash directory {{ic|~/.Trash}}.<br />
<br />
{{hc|~/.config/ranger/commands.py|<nowiki><br />
class empty(Command):<br />
""":empty<br />
<br />
Empties the trash directory ~/.Trash<br />
"""<br />
<br />
def execute(self):<br />
self.fm.run("rm -rf /home/myname/.Trash/{*,.[^.]*}")<br />
</nowiki>}}<br />
<br />
To use it, type {{ic|:empty}} and {{ic|Enter}} with tab completion as desired.<br />
<br />
{{Warning|{{ic|[^.]}} is an essential part of the above command. Without it, all files and directories of the form {{ic|..*}} will be deleted, wiping out everything in your home directory.}}<br />
<br />
=== Color schemes ===<br />
<br />
Ranger comes with four color schemes: {{ic|default}}, {{ic|jungle}}, {{ic|snow}} and {{ic|solarized}}.<br />
You can change your color scheme using:<br />
<br />
set colorscheme ''scheme''<br />
<br />
Custom color schemes can be placed in {{ic|~/.config/ranger/colorschemes}}.<br />
<br />
=== Color highlight in file previews ===<br />
<br />
Install the {{Pkg|python-pygments}} package, then copy {{ic|/usr/share/doc/ranger/config/scope.sh}} to {{ic|~/.config/ranger/scope.sh}} and edit the variable {{ic|PYGMENTIZE_STYLE}} in the configuration file of ranger to your liking. The complete list of supported themes can be obtained via {{ic|pygmentize -L style}}.<br />
<br />
=== File association ===<br />
<br />
Ranger uses its own file opener called {{ic|rifle}}.<br />
It's configured in {{ic|~/.config/ranger/rifle.conf}}. Run {{ic|1=ranger --copy-config=rifle}} if it does not exist. For example, the following line <br />
makes {{Pkg|kile}} the default program for tex files:<br />
<br />
ext tex = kile "$@"<br />
<br />
To open all files with {{Pkg|xdg-utils}}, make sure your {{ic|$EDITOR}} and {{ic|$PAGER}} are set and add:<br />
<br />
else = xdg-open "$1"<br />
label editor = "$EDITOR" -- "$@"<br />
label pager = "$PAGER" -- "$@"<br />
<br />
== Tips and tricks ==<br />
<br />
{{Template:Style|bad style}}<br />
<br />
=== Archives ===<br />
<br />
These commands use {{Pkg|atool}} to perform archive operations.<br />
<br />
==== Archive extraction ====<br />
<br />
The following command implements archive extraction of the selected items to the current directory.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class extract_here(Command):<br />
def execute(self):<br />
""" extract selected files to current directory."""<br />
cwd = self.fm.thisdir<br />
marked_files = tuple(cwd.get_selection())<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
one_file = marked_files[0]<br />
cwd = self.fm.thisdir<br />
original_path = cwd.path<br />
au_flags = ['-x', cwd.path]<br />
au_flags += self.line.split()[1:]<br />
au_flags += ['-e']<br />
<br />
self.fm.copy_buffer.clear()<br />
self.fm.cut_buffer = False<br />
if len(marked_files) == 1:<br />
descr = "extracting: " + os.path.basename(one_file.path)<br />
else:<br />
descr = "extracting files from: " + os.path.basename(<br />
one_file.dirname)<br />
obj = CommandLoader(args=['aunpack'] + au_flags<br />
+ [f.path for f in marked_files], descr=descr,<br />
read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
==== Compression ====<br />
<br />
The following command allows users to compress several files on the current directory by marking them and then calling {{ic|:compress ''package name''}}. It supports name suggestions by getting the basename of the current directory and appending several possibilities for the extension. You need to have {{pkg|atool}} installed, otherwise you will see an error message when you create the archive.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class compress(Command):<br />
def execute(self):<br />
""" Compress marked files to current directory """<br />
cwd = self.fm.thisdir<br />
marked_files = cwd.get_selection()<br />
<br />
if not marked_files:<br />
return<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
original_path = cwd.path<br />
parts = self.line.split()<br />
au_flags = parts[1:]<br />
<br />
descr = "compressing files in: " + os.path.basename(parts[1])<br />
obj = CommandLoader(args=['apack'] + au_flags + \<br />
[os.path.relpath(f.path, cwd.path) for f in marked_files], descr=descr, read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
<br />
def tab(self, tabnum):<br />
""" Complete with current folder name """<br />
<br />
extension = ['.zip', '.tar.gz', '.rar', '.7z']<br />
return ['compress ' + os.path.basename(self.fm.thisdir.path) + ext for ext in extension]<br />
</nowiki>}}<br />
<br />
=== External drives ===<br />
<br />
External drives can be automatically mounted with [[udev]] or [[udisks]]. The default key mappings to go to common mount points {{ic|/media}} and {{ic|/run/media/$USER}} are {{ic|gm}} and {{ic|gi}} respectively.<br />
<br />
=== Hidden files ===<br />
<br />
You can toggle the visibility of hidden files with the following command: {{ic|:set show_hidden!}}, or use {{ic|:set show_hidden true}} to make hidden files visible.<br />
<br />
To make this permanent, add the setting to your configuration file:<br />
<br />
{{hc|rc.conf|<nowiki><br />
set show_hidden true<br />
</nowiki>}}<br />
<br />
Alternatively, hidden files can be toggled by pressing {{ic|zh}}.<br />
<br />
=== Image mounting ===<br />
<br />
The following command assumes you are using [[CDemu]] as your image mounter and some kind of system like [[autofs]] which mounts the virtual drive to a specified location ('/media/virtualrom' in this case). '''Do not forget to change mountpath to reflect your system settings'''.<br />
<br />
To mount an image (or images) to a cdemud virtual drive from ranger you select the image files and then type ':mount' on the console. The mounting may actually take some time depending on your setup (in mine it may take as long as one minute) so the command uses a custom loader that waits until the mount directory is mounted and then opens it on the background in tab 9.<br />
<br />
{{bc|<nowiki><br />
import os, time<br />
from ranger.core.loader import Loadable<br />
from ranger.ext.signals import SignalDispatcher<br />
from ranger.ext.shell_escape import *<br />
<br />
class MountLoader(Loadable, SignalDispatcher):<br />
"""<br />
Wait until a directory is mounted<br />
"""<br />
def __init__(self, path):<br />
SignalDispatcher.__init__(self)<br />
descr = "Waiting for dir '" + path + "' to be mounted"<br />
Loadable.__init__(self, self.generate(), descr)<br />
self.path = path<br />
<br />
def generate(self):<br />
available = False<br />
while not available:<br />
try:<br />
if os.path.ismount(self.path):<br />
available = True<br />
except:<br />
pass<br />
yield<br />
time.sleep(0.03)<br />
self.signal_emit('after')<br />
<br />
class mount(Command):<br />
def execute(self):<br />
selected_files = self.fm.thisdir.get_selection()<br />
<br />
if not selected_files:<br />
return<br />
<br />
space = ' '<br />
self.fm.execute_command("cdemu -b system unload 0")<br />
self.fm.execute_command("cdemu -b system load 0 " + \<br />
space.join([shell_escape(f.path) for f in selected_files]))<br />
<br />
mountpath = "/media/virtualrom/"<br />
<br />
def mount_finished(path):<br />
currenttab = self.fm.current_tab<br />
self.fm.tab_open(9, mountpath)<br />
self.fm.tab_open(currenttab)<br />
<br />
obj = MountLoader(mountpath)<br />
obj.signal_bind('after', mount_finished)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
=== New tab in current folder ===<br />
<br />
You may have noticed there are two shortcuts for opening a new tab in home ({{ic|g}}{{ic|n}} and {{ic|Ctrl+n}}). Let us rebind {{ic|Ctrl+n}}:<br />
{{hc|rc.conf|<nowiki><br />
map <c-n> eval fm.tab_new('%d')<br />
</nowiki>}}<br />
<br />
=== PDF file preview ===<br />
By default, ranger will preview PDF files as text. However, you can preview PDF files as an image in ranger by first converting the PDF file to an image. Ranger stores the image previews in {{ic|~/.cache/ranger/}}. You either need to create this directory manually or set {{ic|preview_images}} to {{ic|true}} in {{ic|~/.config/ranger/rc.conf}} to tell {{ic|ranger}} to create it automatically at the next start. However, note that {{ic|preview_images}} does not need to be set to {{ic|true}} the whole time to preview PDF file as images, only {{ic|~/.cache/ranger}} directory is needed.<br />
<br />
To enable this feature, uncomment the appropriate lines in {{ic|/usr/share/doc/ranger/config/scope.sh}}, or add/uncomment these lines in your local file {{ic|~/.config/ranger/scope.sh}}.<br />
<br />
=== Shell tips ===<br />
<br />
==== Synchronize path ====<br />
<br />
Ranger provides a shell [[Bash/Functions|function]] {{ic|/usr/share/doc/ranger/examples/shell_automatic_cd.sh}}. Running {{ic|ranger_cd}} instead of {{ic|ranger}} will automatically ''cd'' to the last browsed folder.<br />
<br />
If you launch ranger from a graphical launcher (such as {{ic|$TERMCMD -e ranger}}, where TERMCMD is an X terminal), you cannot use {{ic|ranger_cd}}. Instead, create an executable script:<br />
<br />
{{hc|ranger-launcher.sh|<nowiki><br />
#!/bin/sh<br />
export RANGERCD=true<br />
$TERMCMD<br />
</nowiki>}}<br />
<br />
And add the following at the end of your shell configuration:<br />
<br />
{{hc|.''shell''rc|<nowiki><br />
$RANGERCD && unset RANGERCD && ranger_cd<br />
</nowiki>}}<br />
<br />
This will launch {{ic|ranger_cd}} only if the {{ic|RANGERCD}} variable is set. It is important to unset this variable again, otherwise launching a subshell from this terminal will automatically relaunch {{ic|ranger}}.<br />
<br />
==== Start a shell from ranger ====<br />
<br />
{{Accuracy|the shell seems to start in the correct directory by default with Ranger's {{ic|S}} key binding|section=Starting a shell in the current directory}}<br />
<br />
With the previous method you can switch to a shell in last browsed path simply by leaving ranger. However you may not want to quit ranger for several reasons (numerous opened tabs, copy in progress, etc.).<br />
You can start a shell from ranger ({{ic|S}} by default) without losing your ranger session. Unfortunately, the shell will not switch to the current folder automatically. Again, this can be solved with an executable script:<br />
<br />
{{hc|shellcd|<nowiki><br />
#!/bin/sh<br />
export AUTOCD="$(realpath "$1")"<br />
<br />
$SHELL<br />
</nowiki>}}<br />
<br />
and - as before - add this to at the very end of your shell configuration:<br />
<br />
{{hc|shellrc|<nowiki><br />
cd "$AUTOCD"<br />
</nowiki>}}<br />
<br />
Now you can change your shell binding for ranger:<br />
<br />
{{hc|rc.conf|<br />
map S shell shellcd %d<br />
}}<br />
<br />
Alternatively, you can make use of your shell history file if it has one. For instance, you could do this for [[zsh#Dirstack|zsh]]:<br />
<br />
{{hc|shellcd|<nowiki><br />
## Prepend argument to zsh dirstack.<br />
BUF="$(realpath "$1")<br />
$(grep -v "$(realpath "$1")" "$ZDIRS")"<br />
echo "$BUF" > "$ZDIRS"<br />
<br />
zsh<br />
</nowiki>}}<br />
<br />
Change ZDIRS for your dirstack.<br />
<br />
===== A simpler solution =====<br />
<br />
{{hc|rc.conf|<nowiki><br />
map S shell bash -c "cd %d; bash"<br />
</nowiki>}}<br />
This could probably be adapted to other shells as well.<br />
Instead of just running a shell (like the default config), this will run {{ic|cd}} in a shell, then execute a interactive shell which will not immediately exit so that you can continue with what you wanted.<br />
<br />
==== Preventing nested ranger instances ====<br />
<br />
You can start a shell in the current directory with {{ic|S}}, when you exit the shell you get back to your ranger instance.<br />
<br />
When you however forget that you already are in a ranger shell and start ranger again you end up with ranger running a shell running ranger.<br />
<br />
To prevent this you can create the following function in your [[Autostarting#On_shell_login_.2F_logout|shell's startup file]]:<br />
<br />
ranger() {<br />
if [ -z "$RANGER_LEVEL" ]; then<br />
/usr/bin/ranger "$@"<br />
else<br />
exit<br />
fi<br />
}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Artifacts in image preview ===<br />
<br />
Borderless columns may cause stripes in image previews. [https://bbs.linuxdistrocommunity.com/showthread.php?tid=1051] In {{ic|~/.config/ranger/rc.conf}} set:<br />
<br />
set draw_borders true<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=93025 BBS thread]<br />
* [http://dotshare.it/category/fms/ranger/ DotShare.it configurations]<br />
* [https://github.com/hut/ranger GitHub]<br />
* [https://github.com/ranger/ranger/wiki/Official-user-guide Official User Guide]<br />
* [https://www.digitalocean.com/community/tutorials/installing-and-using-ranger-a-terminal-file-manager-on-a-ubuntu-vps Installing and using ranger]<br />
* [https://lists.nongnu.org/mailman/listinfo/ranger-users Mailing list]<br />
* [https://bloerg.net/2012/10/17/ranger-file-manager.html Ranger tutorial]</div>Edhhttps://wiki.archlinux.org/index.php?title=Ranger&diff=653938Ranger2021-03-03T19:44:18Z<p>Edh: /* Color highlight in file previews */ Remove excessive description for changing the theme and fix spelling mistakes</p>
<hr />
<div>{{DISPLAYTITLE:ranger}}<br />
[[Category:File managers]]<br />
[[Category:Console applications]]<br />
[[ar:Ranger]]<br />
[[de:Ranger]]<br />
[[es:Ranger]]<br />
[[fa:ranger]]<br />
[[fr:ranger]]<br />
[[ja:Ranger]]<br />
[[zh-hans:Ranger]]<br />
{{Related articles start}}<br />
{{Related|Midnight Commander}}<br />
{{Related|nnn}}<br />
{{Related|vifm}}<br />
{{Related articles end}}<br />
[https://ranger.github.io/ ranger] is a text-based file manager written in [[Python]]. Directories are displayed in one pane with three columns. Moving between them is accomplished with keystrokes, bookmarks, the mouse or the command history. File previews and directory contents show automatically for the current selection.<br />
<br />
Features include: [[vi]]-style key bindings, bookmarks, selections, tagging, tabs, command history, the ability to make symbolic links, several console modes, and a task view. ''ranger'' has customizable commands and key bindings, including bindings to external scripts. Ranger also comes with its own [[file opener]], {{man|1|rifle}}. The closest competitors are [[Vifm]] and [https://github.com/gokcehan/lf lf].<br />
<br />
== Installation ==<br />
[[Install]] the {{Pkg|ranger}} package, or {{AUR|ranger-git}} for the development version.<br />
<br />
== Usage ==<br />
<br />
To start ranger, launch a [[List of applications#Terminal emulators|terminal]] and run {{ic|ranger}}.<br />
<br />
{| class="wikitable"<br />
|+<br />
! Key !! Command<br />
|-<br />
| {{ic|?}} || Open the manual or list keybindings, commands and settings<br />
|-<br />
| {{ic|l}}, {{ic|Enter}} || Launch files<br />
|-<br />
| {{ic|j}}, {{ic|k}} || Select file in the current directory<br />
|-<br />
| {{ic|h}}, {{ic|l}} || Travel up and down in the directory tree<br />
|}<br />
<br />
== Configuration ==<br />
<br />
After startup, ranger creates a directory {{ic|~/.config/ranger}}. To copy the default configuration to this directory issue the following command:<br />
<br />
$ ranger --copy-config=all<br />
<br />
* {{ic|rc.conf}} - startup commands and key bindings<br />
* {{ic|commands.py}} - commands which are launched with {{ic|:}}<br />
* {{ic|rifle.conf}} - applications used when a given type of file is launched.<br />
<br />
{{ic|rc.conf}} only needs to include changes from the default file as both are loaded. For {{ic|commands.py}}, if you do not include the whole file, put this line at the top:<br />
<br />
from ranger.api.commands import *<br />
<br />
See {{man|1|ranger}} for general configuration.<br />
<br />
=== Move to trash ===<br />
<br />
To add a keybind that moves files to your trash directory {{ic|~/.local/share/Trash/files/}} with {{ic|DD}}, amend the configuration file as follows:<br />
{{hc|~/.config/ranger/rc.conf|<nowiki><br />
...<br />
map DD shell mv %s /home/${USER}/.local/share/Trash/files/<br />
...<br />
</nowiki>}}<br />
<br />
Alternatively, use GIO commandline tool provided by {{Pkg|glib2}} package:<br />
<br />
map DD shell gio trash %s<br />
<br />
Inspecting and emptying the "trash" is normally supported by graphical file managers such as {{Pkg|nautilus}}, but you can also see the trash with the command {{ic|gio list trash://}}, and empty it with: {{ic|gio trash --empty}}.<br />
<br />
=== Defining commands ===<br />
<br />
Continuing the above example, add the following entry to empty the trash directory {{ic|~/.Trash}}.<br />
<br />
{{hc|~/.config/ranger/commands.py|<nowiki><br />
class empty(Command):<br />
""":empty<br />
<br />
Empties the trash directory ~/.Trash<br />
"""<br />
<br />
def execute(self):<br />
self.fm.run("rm -rf /home/myname/.Trash/{*,.[^.]*}")<br />
</nowiki>}}<br />
<br />
To use it, type {{ic|:empty}} and {{ic|Enter}} with tab completion as desired.<br />
<br />
{{Warning|{{ic|[^.]}} is an essential part of the above command. Without it, all files and directories of the form {{ic|..*}} will be deleted, wiping out everything in your home directory.}}<br />
<br />
=== Color schemes ===<br />
<br />
Ranger comes with four color schemes: {{ic|default}}, {{ic|jungle}}, {{ic|snow}} and {{ic|solarized}}.<br />
You can change your color scheme using:<br />
<br />
set colorscheme ''scheme''<br />
<br />
Custom color schemes can be placed in {{ic|~/.config/ranger/colorschemes}}.<br />
<br />
=== Color highlight in file previews ===<br />
<br />
Install the {{Pkg|python-pygments}} package, then copy {{ic|/usr/share/doc/ranger/config/scope.sh}} to {{ic|~/.config/ranger/scope.sh}} and edit the variable {{ic|PYGMENTIZE_STYLE}} to your liking. The complete list of supported themes can be obtained via {{ic|pygmentize -L style}}.<br />
<br />
=== File association ===<br />
<br />
Ranger uses its own file opener called {{ic|rifle}}.<br />
It's configured in {{ic|~/.config/ranger/rifle.conf}}. Run {{ic|1=ranger --copy-config=rifle}} if it does not exist. For example, the following line <br />
makes {{Pkg|kile}} the default program for tex files:<br />
<br />
ext tex = kile "$@"<br />
<br />
To open all files with {{Pkg|xdg-utils}}, make sure your {{ic|$EDITOR}} and {{ic|$PAGER}} are set and add:<br />
<br />
else = xdg-open "$1"<br />
label editor = "$EDITOR" -- "$@"<br />
label pager = "$PAGER" -- "$@"<br />
<br />
== Tips and tricks ==<br />
<br />
{{Template:Style|bad style}}<br />
<br />
=== Archives ===<br />
<br />
These commands use {{Pkg|atool}} to perform archive operations.<br />
<br />
==== Archive extraction ====<br />
<br />
The following command implements archive extraction of the selected items to the current directory.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class extract_here(Command):<br />
def execute(self):<br />
""" extract selected files to current directory."""<br />
cwd = self.fm.thisdir<br />
marked_files = tuple(cwd.get_selection())<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
one_file = marked_files[0]<br />
cwd = self.fm.thisdir<br />
original_path = cwd.path<br />
au_flags = ['-x', cwd.path]<br />
au_flags += self.line.split()[1:]<br />
au_flags += ['-e']<br />
<br />
self.fm.copy_buffer.clear()<br />
self.fm.cut_buffer = False<br />
if len(marked_files) == 1:<br />
descr = "extracting: " + os.path.basename(one_file.path)<br />
else:<br />
descr = "extracting files from: " + os.path.basename(<br />
one_file.dirname)<br />
obj = CommandLoader(args=['aunpack'] + au_flags<br />
+ [f.path for f in marked_files], descr=descr,<br />
read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
==== Compression ====<br />
<br />
The following command allows users to compress several files on the current directory by marking them and then calling {{ic|:compress ''package name''}}. It supports name suggestions by getting the basename of the current directory and appending several possibilities for the extension. You need to have {{pkg|atool}} installed, otherwise you will see an error message when you create the archive.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class compress(Command):<br />
def execute(self):<br />
""" Compress marked files to current directory """<br />
cwd = self.fm.thisdir<br />
marked_files = cwd.get_selection()<br />
<br />
if not marked_files:<br />
return<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
original_path = cwd.path<br />
parts = self.line.split()<br />
au_flags = parts[1:]<br />
<br />
descr = "compressing files in: " + os.path.basename(parts[1])<br />
obj = CommandLoader(args=['apack'] + au_flags + \<br />
[os.path.relpath(f.path, cwd.path) for f in marked_files], descr=descr, read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
<br />
def tab(self, tabnum):<br />
""" Complete with current folder name """<br />
<br />
extension = ['.zip', '.tar.gz', '.rar', '.7z']<br />
return ['compress ' + os.path.basename(self.fm.thisdir.path) + ext for ext in extension]<br />
</nowiki>}}<br />
<br />
=== External drives ===<br />
<br />
External drives can be automatically mounted with [[udev]] or [[udisks]]. The default key mappings to go to common mount points {{ic|/media}} and {{ic|/run/media/$USER}} are {{ic|gm}} and {{ic|gi}} respectively.<br />
<br />
=== Hidden files ===<br />
<br />
You can toggle the visibility of hidden files with the following command: {{ic|:set show_hidden!}}, or use {{ic|:set show_hidden true}} to make hidden files visible.<br />
<br />
To make this permanent, add the setting to your configuration file:<br />
<br />
{{hc|rc.conf|<nowiki><br />
set show_hidden true<br />
</nowiki>}}<br />
<br />
Alternatively, hidden files can be toggled by pressing {{ic|zh}}.<br />
<br />
=== Image mounting ===<br />
<br />
The following command assumes you are using [[CDemu]] as your image mounter and some kind of system like [[autofs]] which mounts the virtual drive to a specified location ('/media/virtualrom' in this case). '''Do not forget to change mountpath to reflect your system settings'''.<br />
<br />
To mount an image (or images) to a cdemud virtual drive from ranger you select the image files and then type ':mount' on the console. The mounting may actually take some time depending on your setup (in mine it may take as long as one minute) so the command uses a custom loader that waits until the mount directory is mounted and then opens it on the background in tab 9.<br />
<br />
{{bc|<nowiki><br />
import os, time<br />
from ranger.core.loader import Loadable<br />
from ranger.ext.signals import SignalDispatcher<br />
from ranger.ext.shell_escape import *<br />
<br />
class MountLoader(Loadable, SignalDispatcher):<br />
"""<br />
Wait until a directory is mounted<br />
"""<br />
def __init__(self, path):<br />
SignalDispatcher.__init__(self)<br />
descr = "Waiting for dir '" + path + "' to be mounted"<br />
Loadable.__init__(self, self.generate(), descr)<br />
self.path = path<br />
<br />
def generate(self):<br />
available = False<br />
while not available:<br />
try:<br />
if os.path.ismount(self.path):<br />
available = True<br />
except:<br />
pass<br />
yield<br />
time.sleep(0.03)<br />
self.signal_emit('after')<br />
<br />
class mount(Command):<br />
def execute(self):<br />
selected_files = self.fm.thisdir.get_selection()<br />
<br />
if not selected_files:<br />
return<br />
<br />
space = ' '<br />
self.fm.execute_command("cdemu -b system unload 0")<br />
self.fm.execute_command("cdemu -b system load 0 " + \<br />
space.join([shell_escape(f.path) for f in selected_files]))<br />
<br />
mountpath = "/media/virtualrom/"<br />
<br />
def mount_finished(path):<br />
currenttab = self.fm.current_tab<br />
self.fm.tab_open(9, mountpath)<br />
self.fm.tab_open(currenttab)<br />
<br />
obj = MountLoader(mountpath)<br />
obj.signal_bind('after', mount_finished)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
=== New tab in current folder ===<br />
<br />
You may have noticed there are two shortcuts for opening a new tab in home ({{ic|g}}{{ic|n}} and {{ic|Ctrl+n}}). Let us rebind {{ic|Ctrl+n}}:<br />
{{hc|rc.conf|<nowiki><br />
map <c-n> eval fm.tab_new('%d')<br />
</nowiki>}}<br />
<br />
=== PDF file preview ===<br />
By default, ranger will preview PDF files as text. However, you can preview PDF files as an image in ranger by first converting the PDF file to an image. Ranger stores the image previews in {{ic|~/.cache/ranger/}}. You either need to create this directory manually or set {{ic|preview_images}} to {{ic|true}} in {{ic|~/.config/ranger/rc.conf}} to tell {{ic|ranger}} to create it automatically at the next start. However, note that {{ic|preview_images}} does not need to be set to {{ic|true}} the whole time to preview PDF file as images, only {{ic|~/.cache/ranger}} directory is needed.<br />
<br />
To enable this feature, uncomment the appropriate lines in {{ic|/usr/share/doc/ranger/config/scope.sh}}, or add/uncomment these lines in your local file {{ic|~/.config/ranger/scope.sh}}.<br />
<br />
=== Shell tips ===<br />
<br />
==== Synchronize path ====<br />
<br />
Ranger provides a shell [[Bash/Functions|function]] {{ic|/usr/share/doc/ranger/examples/shell_automatic_cd.sh}}. Running {{ic|ranger_cd}} instead of {{ic|ranger}} will automatically ''cd'' to the last browsed folder.<br />
<br />
If you launch ranger from a graphical launcher (such as {{ic|$TERMCMD -e ranger}}, where TERMCMD is an X terminal), you cannot use {{ic|ranger_cd}}. Instead, create an executable script:<br />
<br />
{{hc|ranger-launcher.sh|<nowiki><br />
#!/bin/sh<br />
export RANGERCD=true<br />
$TERMCMD<br />
</nowiki>}}<br />
<br />
And add the following at the end of your shell configuration:<br />
<br />
{{hc|.''shell''rc|<nowiki><br />
$RANGERCD && unset RANGERCD && ranger_cd<br />
</nowiki>}}<br />
<br />
This will launch {{ic|ranger_cd}} only if the {{ic|RANGERCD}} variable is set. It is important to unset this variable again, otherwise launching a subshell from this terminal will automatically relaunch {{ic|ranger}}.<br />
<br />
==== Start a shell from ranger ====<br />
<br />
{{Accuracy|the shell seems to start in the correct directory by default with Ranger's {{ic|S}} key binding|section=Starting a shell in the current directory}}<br />
<br />
With the previous method you can switch to a shell in last browsed path simply by leaving ranger. However you may not want to quit ranger for several reasons (numerous opened tabs, copy in progress, etc.).<br />
You can start a shell from ranger ({{ic|S}} by default) without losing your ranger session. Unfortunately, the shell will not switch to the current folder automatically. Again, this can be solved with an executable script:<br />
<br />
{{hc|shellcd|<nowiki><br />
#!/bin/sh<br />
export AUTOCD="$(realpath "$1")"<br />
<br />
$SHELL<br />
</nowiki>}}<br />
<br />
and - as before - add this to at the very end of your shell configuration:<br />
<br />
{{hc|shellrc|<nowiki><br />
cd "$AUTOCD"<br />
</nowiki>}}<br />
<br />
Now you can change your shell binding for ranger:<br />
<br />
{{hc|rc.conf|<br />
map S shell shellcd %d<br />
}}<br />
<br />
Alternatively, you can make use of your shell history file if it has one. For instance, you could do this for [[zsh#Dirstack|zsh]]:<br />
<br />
{{hc|shellcd|<nowiki><br />
## Prepend argument to zsh dirstack.<br />
BUF="$(realpath "$1")<br />
$(grep -v "$(realpath "$1")" "$ZDIRS")"<br />
echo "$BUF" > "$ZDIRS"<br />
<br />
zsh<br />
</nowiki>}}<br />
<br />
Change ZDIRS for your dirstack.<br />
<br />
===== A simpler solution =====<br />
<br />
{{hc|rc.conf|<nowiki><br />
map S shell bash -c "cd %d; bash"<br />
</nowiki>}}<br />
This could probably be adapted to other shells as well.<br />
Instead of just running a shell (like the default config), this will run {{ic|cd}} in a shell, then execute a interactive shell which will not immediately exit so that you can continue with what you wanted.<br />
<br />
==== Preventing nested ranger instances ====<br />
<br />
You can start a shell in the current directory with {{ic|S}}, when you exit the shell you get back to your ranger instance.<br />
<br />
When you however forget that you already are in a ranger shell and start ranger again you end up with ranger running a shell running ranger.<br />
<br />
To prevent this you can create the following function in your [[Autostarting#On_shell_login_.2F_logout|shell's startup file]]:<br />
<br />
ranger() {<br />
if [ -z "$RANGER_LEVEL" ]; then<br />
/usr/bin/ranger "$@"<br />
else<br />
exit<br />
fi<br />
}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Artifacts in image preview ===<br />
<br />
Borderless columns may cause stripes in image previews. [https://bbs.linuxdistrocommunity.com/showthread.php?tid=1051] In {{ic|~/.config/ranger/rc.conf}} set:<br />
<br />
set draw_borders true<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=93025 BBS thread]<br />
* [http://dotshare.it/category/fms/ranger/ DotShare.it configurations]<br />
* [https://github.com/hut/ranger GitHub]<br />
* [https://github.com/ranger/ranger/wiki/Official-user-guide Official User Guide]<br />
* [https://www.digitalocean.com/community/tutorials/installing-and-using-ranger-a-terminal-file-manager-on-a-ubuntu-vps Installing and using ranger]<br />
* [https://lists.nongnu.org/mailman/listinfo/ranger-users Mailing list]<br />
* [https://bloerg.net/2012/10/17/ranger-file-manager.html Ranger tutorial]</div>Edhhttps://wiki.archlinux.org/index.php?title=Ranger&diff=653936Ranger2021-03-03T19:38:47Z<p>Edh: /* Defining commands */ Use hc tag instead of describing file name and content</p>
<hr />
<div>{{DISPLAYTITLE:ranger}}<br />
[[Category:File managers]]<br />
[[Category:Console applications]]<br />
[[ar:Ranger]]<br />
[[de:Ranger]]<br />
[[es:Ranger]]<br />
[[fa:ranger]]<br />
[[fr:ranger]]<br />
[[ja:Ranger]]<br />
[[zh-hans:Ranger]]<br />
{{Related articles start}}<br />
{{Related|Midnight Commander}}<br />
{{Related|nnn}}<br />
{{Related|vifm}}<br />
{{Related articles end}}<br />
[https://ranger.github.io/ ranger] is a text-based file manager written in [[Python]]. Directories are displayed in one pane with three columns. Moving between them is accomplished with keystrokes, bookmarks, the mouse or the command history. File previews and directory contents show automatically for the current selection.<br />
<br />
Features include: [[vi]]-style key bindings, bookmarks, selections, tagging, tabs, command history, the ability to make symbolic links, several console modes, and a task view. ''ranger'' has customizable commands and key bindings, including bindings to external scripts. Ranger also comes with its own [[file opener]], {{man|1|rifle}}. The closest competitors are [[Vifm]] and [https://github.com/gokcehan/lf lf].<br />
<br />
== Installation ==<br />
[[Install]] the {{Pkg|ranger}} package, or {{AUR|ranger-git}} for the development version.<br />
<br />
== Usage ==<br />
<br />
To start ranger, launch a [[List of applications#Terminal emulators|terminal]] and run {{ic|ranger}}.<br />
<br />
{| class="wikitable"<br />
|+<br />
! Key !! Command<br />
|-<br />
| {{ic|?}} || Open the manual or list keybindings, commands and settings<br />
|-<br />
| {{ic|l}}, {{ic|Enter}} || Launch files<br />
|-<br />
| {{ic|j}}, {{ic|k}} || Select file in the current directory<br />
|-<br />
| {{ic|h}}, {{ic|l}} || Travel up and down in the directory tree<br />
|}<br />
<br />
== Configuration ==<br />
<br />
After startup, ranger creates a directory {{ic|~/.config/ranger}}. To copy the default configuration to this directory issue the following command:<br />
<br />
$ ranger --copy-config=all<br />
<br />
* {{ic|rc.conf}} - startup commands and key bindings<br />
* {{ic|commands.py}} - commands which are launched with {{ic|:}}<br />
* {{ic|rifle.conf}} - applications used when a given type of file is launched.<br />
<br />
{{ic|rc.conf}} only needs to include changes from the default file as both are loaded. For {{ic|commands.py}}, if you do not include the whole file, put this line at the top:<br />
<br />
from ranger.api.commands import *<br />
<br />
See {{man|1|ranger}} for general configuration.<br />
<br />
=== Move to trash ===<br />
<br />
To add a keybind that moves files to your trash directory {{ic|~/.local/share/Trash/files/}} with {{ic|DD}}, amend the configuration file as follows:<br />
{{hc|~/.config/ranger/rc.conf|<nowiki><br />
...<br />
map DD shell mv %s /home/${USER}/.local/share/Trash/files/<br />
...<br />
</nowiki>}}<br />
<br />
Alternatively, use GIO commandline tool provided by {{Pkg|glib2}} package:<br />
<br />
map DD shell gio trash %s<br />
<br />
Inspecting and emptying the "trash" is normally supported by graphical file managers such as {{Pkg|nautilus}}, but you can also see the trash with the command {{ic|gio list trash://}}, and empty it with: {{ic|gio trash --empty}}.<br />
<br />
=== Defining commands ===<br />
<br />
Continuing the above example, add the following entry to empty the trash directory {{ic|~/.Trash}}.<br />
<br />
{{hc|~/.config/ranger/commands.py|<nowiki><br />
class empty(Command):<br />
""":empty<br />
<br />
Empties the trash directory ~/.Trash<br />
"""<br />
<br />
def execute(self):<br />
self.fm.run("rm -rf /home/myname/.Trash/{*,.[^.]*}")<br />
</nowiki>}}<br />
<br />
To use it, type {{ic|:empty}} and {{ic|Enter}} with tab completion as desired.<br />
<br />
{{Warning|{{ic|[^.]}} is an essential part of the above command. Without it, all files and directories of the form {{ic|..*}} will be deleted, wiping out everything in your home directory.}}<br />
<br />
=== Color schemes ===<br />
<br />
Ranger comes with four color schemes: {{ic|default}}, {{ic|jungle}}, {{ic|snow}} and {{ic|solarized}}.<br />
You can change your color scheme using:<br />
<br />
set colorscheme ''scheme''<br />
<br />
Custom color schemes can be placed in {{ic|~/.config/ranger/colorschemes}}.<br />
<br />
=== Color highlight in file previews ===<br />
<br />
Install {{Pkg|python-pygments}} package, then copy {{ic|/usr/share/doc/ranger/config/scope.sh}} in {{ic|~/.config/ranger/scope.sh}} and edit the line 47:<br />
<br />
# from<br />
PYGMENTIZE_STYLE=${PYGMENTIZE_STYLE:-autumn}<br />
# to<br />
PYGMENTIZE_STYLE=${PYGMENTIZE_STYLE:-monokai}<br />
<br />
to switch to {{ic|monokai}} pygmentize theme. The complete list of supported themes can be obtained with {{ic|pygmentize -L style}}.<br />
<br />
=== File association ===<br />
<br />
Ranger uses its own file opener called {{ic|rifle}}.<br />
It's configured in {{ic|~/.config/ranger/rifle.conf}}. Run {{ic|1=ranger --copy-config=rifle}} if it does not exist. For example, the following line <br />
makes {{Pkg|kile}} the default program for tex files:<br />
<br />
ext tex = kile "$@"<br />
<br />
To open all files with {{Pkg|xdg-utils}}, make sure your {{ic|$EDITOR}} and {{ic|$PAGER}} are set and add:<br />
<br />
else = xdg-open "$1"<br />
label editor = "$EDITOR" -- "$@"<br />
label pager = "$PAGER" -- "$@"<br />
<br />
== Tips and tricks ==<br />
<br />
{{Template:Style|bad style}}<br />
<br />
=== Archives ===<br />
<br />
These commands use {{Pkg|atool}} to perform archive operations.<br />
<br />
==== Archive extraction ====<br />
<br />
The following command implements archive extraction of the selected items to the current directory.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class extract_here(Command):<br />
def execute(self):<br />
""" extract selected files to current directory."""<br />
cwd = self.fm.thisdir<br />
marked_files = tuple(cwd.get_selection())<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
one_file = marked_files[0]<br />
cwd = self.fm.thisdir<br />
original_path = cwd.path<br />
au_flags = ['-x', cwd.path]<br />
au_flags += self.line.split()[1:]<br />
au_flags += ['-e']<br />
<br />
self.fm.copy_buffer.clear()<br />
self.fm.cut_buffer = False<br />
if len(marked_files) == 1:<br />
descr = "extracting: " + os.path.basename(one_file.path)<br />
else:<br />
descr = "extracting files from: " + os.path.basename(<br />
one_file.dirname)<br />
obj = CommandLoader(args=['aunpack'] + au_flags<br />
+ [f.path for f in marked_files], descr=descr,<br />
read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
==== Compression ====<br />
<br />
The following command allows users to compress several files on the current directory by marking them and then calling {{ic|:compress ''package name''}}. It supports name suggestions by getting the basename of the current directory and appending several possibilities for the extension. You need to have {{pkg|atool}} installed, otherwise you will see an error message when you create the archive.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class compress(Command):<br />
def execute(self):<br />
""" Compress marked files to current directory """<br />
cwd = self.fm.thisdir<br />
marked_files = cwd.get_selection()<br />
<br />
if not marked_files:<br />
return<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
original_path = cwd.path<br />
parts = self.line.split()<br />
au_flags = parts[1:]<br />
<br />
descr = "compressing files in: " + os.path.basename(parts[1])<br />
obj = CommandLoader(args=['apack'] + au_flags + \<br />
[os.path.relpath(f.path, cwd.path) for f in marked_files], descr=descr, read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
<br />
def tab(self, tabnum):<br />
""" Complete with current folder name """<br />
<br />
extension = ['.zip', '.tar.gz', '.rar', '.7z']<br />
return ['compress ' + os.path.basename(self.fm.thisdir.path) + ext for ext in extension]<br />
</nowiki>}}<br />
<br />
=== External drives ===<br />
<br />
External drives can be automatically mounted with [[udev]] or [[udisks]]. The default key mappings to go to common mount points {{ic|/media}} and {{ic|/run/media/$USER}} are {{ic|gm}} and {{ic|gi}} respectively.<br />
<br />
=== Hidden files ===<br />
<br />
You can toggle the visibility of hidden files with the following command: {{ic|:set show_hidden!}}, or use {{ic|:set show_hidden true}} to make hidden files visible.<br />
<br />
To make this permanent, add the setting to your configuration file:<br />
<br />
{{hc|rc.conf|<nowiki><br />
set show_hidden true<br />
</nowiki>}}<br />
<br />
Alternatively, hidden files can be toggled by pressing {{ic|zh}}.<br />
<br />
=== Image mounting ===<br />
<br />
The following command assumes you are using [[CDemu]] as your image mounter and some kind of system like [[autofs]] which mounts the virtual drive to a specified location ('/media/virtualrom' in this case). '''Do not forget to change mountpath to reflect your system settings'''.<br />
<br />
To mount an image (or images) to a cdemud virtual drive from ranger you select the image files and then type ':mount' on the console. The mounting may actually take some time depending on your setup (in mine it may take as long as one minute) so the command uses a custom loader that waits until the mount directory is mounted and then opens it on the background in tab 9.<br />
<br />
{{bc|<nowiki><br />
import os, time<br />
from ranger.core.loader import Loadable<br />
from ranger.ext.signals import SignalDispatcher<br />
from ranger.ext.shell_escape import *<br />
<br />
class MountLoader(Loadable, SignalDispatcher):<br />
"""<br />
Wait until a directory is mounted<br />
"""<br />
def __init__(self, path):<br />
SignalDispatcher.__init__(self)<br />
descr = "Waiting for dir '" + path + "' to be mounted"<br />
Loadable.__init__(self, self.generate(), descr)<br />
self.path = path<br />
<br />
def generate(self):<br />
available = False<br />
while not available:<br />
try:<br />
if os.path.ismount(self.path):<br />
available = True<br />
except:<br />
pass<br />
yield<br />
time.sleep(0.03)<br />
self.signal_emit('after')<br />
<br />
class mount(Command):<br />
def execute(self):<br />
selected_files = self.fm.thisdir.get_selection()<br />
<br />
if not selected_files:<br />
return<br />
<br />
space = ' '<br />
self.fm.execute_command("cdemu -b system unload 0")<br />
self.fm.execute_command("cdemu -b system load 0 " + \<br />
space.join([shell_escape(f.path) for f in selected_files]))<br />
<br />
mountpath = "/media/virtualrom/"<br />
<br />
def mount_finished(path):<br />
currenttab = self.fm.current_tab<br />
self.fm.tab_open(9, mountpath)<br />
self.fm.tab_open(currenttab)<br />
<br />
obj = MountLoader(mountpath)<br />
obj.signal_bind('after', mount_finished)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
=== New tab in current folder ===<br />
<br />
You may have noticed there are two shortcuts for opening a new tab in home ({{ic|g}}{{ic|n}} and {{ic|Ctrl+n}}). Let us rebind {{ic|Ctrl+n}}:<br />
{{hc|rc.conf|<nowiki><br />
map <c-n> eval fm.tab_new('%d')<br />
</nowiki>}}<br />
<br />
=== PDF file preview ===<br />
By default, ranger will preview PDF files as text. However, you can preview PDF files as an image in ranger by first converting the PDF file to an image. Ranger stores the image previews in {{ic|~/.cache/ranger/}}. You either need to create this directory manually or set {{ic|preview_images}} to {{ic|true}} in {{ic|~/.config/ranger/rc.conf}} to tell {{ic|ranger}} to create it automatically at the next start. However, note that {{ic|preview_images}} does not need to be set to {{ic|true}} the whole time to preview PDF file as images, only {{ic|~/.cache/ranger}} directory is needed.<br />
<br />
To enable this feature, uncomment the appropriate lines in {{ic|/usr/share/doc/ranger/config/scope.sh}}, or add/uncomment these lines in your local file {{ic|~/.config/ranger/scope.sh}}.<br />
<br />
=== Shell tips ===<br />
<br />
==== Synchronize path ====<br />
<br />
Ranger provides a shell [[Bash/Functions|function]] {{ic|/usr/share/doc/ranger/examples/shell_automatic_cd.sh}}. Running {{ic|ranger_cd}} instead of {{ic|ranger}} will automatically ''cd'' to the last browsed folder.<br />
<br />
If you launch ranger from a graphical launcher (such as {{ic|$TERMCMD -e ranger}}, where TERMCMD is an X terminal), you cannot use {{ic|ranger_cd}}. Instead, create an executable script:<br />
<br />
{{hc|ranger-launcher.sh|<nowiki><br />
#!/bin/sh<br />
export RANGERCD=true<br />
$TERMCMD<br />
</nowiki>}}<br />
<br />
And add the following at the end of your shell configuration:<br />
<br />
{{hc|.''shell''rc|<nowiki><br />
$RANGERCD && unset RANGERCD && ranger_cd<br />
</nowiki>}}<br />
<br />
This will launch {{ic|ranger_cd}} only if the {{ic|RANGERCD}} variable is set. It is important to unset this variable again, otherwise launching a subshell from this terminal will automatically relaunch {{ic|ranger}}.<br />
<br />
==== Start a shell from ranger ====<br />
<br />
{{Accuracy|the shell seems to start in the correct directory by default with Ranger's {{ic|S}} key binding|section=Starting a shell in the current directory}}<br />
<br />
With the previous method you can switch to a shell in last browsed path simply by leaving ranger. However you may not want to quit ranger for several reasons (numerous opened tabs, copy in progress, etc.).<br />
You can start a shell from ranger ({{ic|S}} by default) without losing your ranger session. Unfortunately, the shell will not switch to the current folder automatically. Again, this can be solved with an executable script:<br />
<br />
{{hc|shellcd|<nowiki><br />
#!/bin/sh<br />
export AUTOCD="$(realpath "$1")"<br />
<br />
$SHELL<br />
</nowiki>}}<br />
<br />
and - as before - add this to at the very end of your shell configuration:<br />
<br />
{{hc|shellrc|<nowiki><br />
cd "$AUTOCD"<br />
</nowiki>}}<br />
<br />
Now you can change your shell binding for ranger:<br />
<br />
{{hc|rc.conf|<br />
map S shell shellcd %d<br />
}}<br />
<br />
Alternatively, you can make use of your shell history file if it has one. For instance, you could do this for [[zsh#Dirstack|zsh]]:<br />
<br />
{{hc|shellcd|<nowiki><br />
## Prepend argument to zsh dirstack.<br />
BUF="$(realpath "$1")<br />
$(grep -v "$(realpath "$1")" "$ZDIRS")"<br />
echo "$BUF" > "$ZDIRS"<br />
<br />
zsh<br />
</nowiki>}}<br />
<br />
Change ZDIRS for your dirstack.<br />
<br />
===== A simpler solution =====<br />
<br />
{{hc|rc.conf|<nowiki><br />
map S shell bash -c "cd %d; bash"<br />
</nowiki>}}<br />
This could probably be adapted to other shells as well.<br />
Instead of just running a shell (like the default config), this will run {{ic|cd}} in a shell, then execute a interactive shell which will not immediately exit so that you can continue with what you wanted.<br />
<br />
==== Preventing nested ranger instances ====<br />
<br />
You can start a shell in the current directory with {{ic|S}}, when you exit the shell you get back to your ranger instance.<br />
<br />
When you however forget that you already are in a ranger shell and start ranger again you end up with ranger running a shell running ranger.<br />
<br />
To prevent this you can create the following function in your [[Autostarting#On_shell_login_.2F_logout|shell's startup file]]:<br />
<br />
ranger() {<br />
if [ -z "$RANGER_LEVEL" ]; then<br />
/usr/bin/ranger "$@"<br />
else<br />
exit<br />
fi<br />
}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Artifacts in image preview ===<br />
<br />
Borderless columns may cause stripes in image previews. [https://bbs.linuxdistrocommunity.com/showthread.php?tid=1051] In {{ic|~/.config/ranger/rc.conf}} set:<br />
<br />
set draw_borders true<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=93025 BBS thread]<br />
* [http://dotshare.it/category/fms/ranger/ DotShare.it configurations]<br />
* [https://github.com/hut/ranger GitHub]<br />
* [https://github.com/ranger/ranger/wiki/Official-user-guide Official User Guide]<br />
* [https://www.digitalocean.com/community/tutorials/installing-and-using-ranger-a-terminal-file-manager-on-a-ubuntu-vps Installing and using ranger]<br />
* [https://lists.nongnu.org/mailman/listinfo/ranger-users Mailing list]<br />
* [https://bloerg.net/2012/10/17/ranger-file-manager.html Ranger tutorial]</div>Edhhttps://wiki.archlinux.org/index.php?title=Ranger&diff=653935Ranger2021-03-03T19:36:18Z<p>Edh: /* Move to trash */ Use hc tag instead of describing file name and content</p>
<hr />
<div>{{DISPLAYTITLE:ranger}}<br />
[[Category:File managers]]<br />
[[Category:Console applications]]<br />
[[ar:Ranger]]<br />
[[de:Ranger]]<br />
[[es:Ranger]]<br />
[[fa:ranger]]<br />
[[fr:ranger]]<br />
[[ja:Ranger]]<br />
[[zh-hans:Ranger]]<br />
{{Related articles start}}<br />
{{Related|Midnight Commander}}<br />
{{Related|nnn}}<br />
{{Related|vifm}}<br />
{{Related articles end}}<br />
[https://ranger.github.io/ ranger] is a text-based file manager written in [[Python]]. Directories are displayed in one pane with three columns. Moving between them is accomplished with keystrokes, bookmarks, the mouse or the command history. File previews and directory contents show automatically for the current selection.<br />
<br />
Features include: [[vi]]-style key bindings, bookmarks, selections, tagging, tabs, command history, the ability to make symbolic links, several console modes, and a task view. ''ranger'' has customizable commands and key bindings, including bindings to external scripts. Ranger also comes with its own [[file opener]], {{man|1|rifle}}. The closest competitors are [[Vifm]] and [https://github.com/gokcehan/lf lf].<br />
<br />
== Installation ==<br />
[[Install]] the {{Pkg|ranger}} package, or {{AUR|ranger-git}} for the development version.<br />
<br />
== Usage ==<br />
<br />
To start ranger, launch a [[List of applications#Terminal emulators|terminal]] and run {{ic|ranger}}.<br />
<br />
{| class="wikitable"<br />
|+<br />
! Key !! Command<br />
|-<br />
| {{ic|?}} || Open the manual or list keybindings, commands and settings<br />
|-<br />
| {{ic|l}}, {{ic|Enter}} || Launch files<br />
|-<br />
| {{ic|j}}, {{ic|k}} || Select file in the current directory<br />
|-<br />
| {{ic|h}}, {{ic|l}} || Travel up and down in the directory tree<br />
|}<br />
<br />
== Configuration ==<br />
<br />
After startup, ranger creates a directory {{ic|~/.config/ranger}}. To copy the default configuration to this directory issue the following command:<br />
<br />
$ ranger --copy-config=all<br />
<br />
* {{ic|rc.conf}} - startup commands and key bindings<br />
* {{ic|commands.py}} - commands which are launched with {{ic|:}}<br />
* {{ic|rifle.conf}} - applications used when a given type of file is launched.<br />
<br />
{{ic|rc.conf}} only needs to include changes from the default file as both are loaded. For {{ic|commands.py}}, if you do not include the whole file, put this line at the top:<br />
<br />
from ranger.api.commands import *<br />
<br />
See {{man|1|ranger}} for general configuration.<br />
<br />
=== Move to trash ===<br />
<br />
To add a keybind that moves files to your trash directory {{ic|~/.local/share/Trash/files/}} with {{ic|DD}}, amend the configuration file as follows:<br />
{{hc|~/.config/ranger/rc.conf|<nowiki><br />
...<br />
map DD shell mv %s /home/${USER}/.local/share/Trash/files/<br />
...<br />
</nowiki>}}<br />
<br />
Alternatively, use GIO commandline tool provided by {{Pkg|glib2}} package:<br />
<br />
map DD shell gio trash %s<br />
<br />
Inspecting and emptying the "trash" is normally supported by graphical file managers such as {{Pkg|nautilus}}, but you can also see the trash with the command {{ic|gio list trash://}}, and empty it with: {{ic|gio trash --empty}}.<br />
<br />
=== Defining commands ===<br />
<br />
Continuing the above example, add the following entry to {{ic|~/.config/ranger/commands.py}} to empty the trash directory {{ic|~/.Trash}}.<br />
<br />
{{bc|<nowiki><br />
class empty(Command):<br />
""":empty<br />
<br />
Empties the trash directory ~/.Trash<br />
"""<br />
<br />
def execute(self):<br />
self.fm.run("rm -rf /home/myname/.Trash/{*,.[^.]*}")<br />
</nowiki>}}<br />
<br />
To use it, type {{ic|:empty}} and {{ic|Enter}} with tab completion as desired.<br />
<br />
{{Warning|{{ic|[^.]}} is an essential part of the above command. Without it, all files and directories of the form {{ic|..*}} will be deleted, wiping out everything in your home directory.}}<br />
<br />
=== Color schemes ===<br />
<br />
Ranger comes with four color schemes: {{ic|default}}, {{ic|jungle}}, {{ic|snow}} and {{ic|solarized}}.<br />
You can change your color scheme using:<br />
<br />
set colorscheme ''scheme''<br />
<br />
Custom color schemes can be placed in {{ic|~/.config/ranger/colorschemes}}.<br />
<br />
=== Color highlight in file previews ===<br />
<br />
Install {{Pkg|python-pygments}} package, then copy {{ic|/usr/share/doc/ranger/config/scope.sh}} in {{ic|~/.config/ranger/scope.sh}} and edit the line 47:<br />
<br />
# from<br />
PYGMENTIZE_STYLE=${PYGMENTIZE_STYLE:-autumn}<br />
# to<br />
PYGMENTIZE_STYLE=${PYGMENTIZE_STYLE:-monokai}<br />
<br />
to switch to {{ic|monokai}} pygmentize theme. The complete list of supported themes can be obtained with {{ic|pygmentize -L style}}.<br />
<br />
=== File association ===<br />
<br />
Ranger uses its own file opener called {{ic|rifle}}.<br />
It's configured in {{ic|~/.config/ranger/rifle.conf}}. Run {{ic|1=ranger --copy-config=rifle}} if it does not exist. For example, the following line <br />
makes {{Pkg|kile}} the default program for tex files:<br />
<br />
ext tex = kile "$@"<br />
<br />
To open all files with {{Pkg|xdg-utils}}, make sure your {{ic|$EDITOR}} and {{ic|$PAGER}} are set and add:<br />
<br />
else = xdg-open "$1"<br />
label editor = "$EDITOR" -- "$@"<br />
label pager = "$PAGER" -- "$@"<br />
<br />
== Tips and tricks ==<br />
<br />
{{Template:Style|bad style}}<br />
<br />
=== Archives ===<br />
<br />
These commands use {{Pkg|atool}} to perform archive operations.<br />
<br />
==== Archive extraction ====<br />
<br />
The following command implements archive extraction of the selected items to the current directory.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class extract_here(Command):<br />
def execute(self):<br />
""" extract selected files to current directory."""<br />
cwd = self.fm.thisdir<br />
marked_files = tuple(cwd.get_selection())<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
one_file = marked_files[0]<br />
cwd = self.fm.thisdir<br />
original_path = cwd.path<br />
au_flags = ['-x', cwd.path]<br />
au_flags += self.line.split()[1:]<br />
au_flags += ['-e']<br />
<br />
self.fm.copy_buffer.clear()<br />
self.fm.cut_buffer = False<br />
if len(marked_files) == 1:<br />
descr = "extracting: " + os.path.basename(one_file.path)<br />
else:<br />
descr = "extracting files from: " + os.path.basename(<br />
one_file.dirname)<br />
obj = CommandLoader(args=['aunpack'] + au_flags<br />
+ [f.path for f in marked_files], descr=descr,<br />
read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
==== Compression ====<br />
<br />
The following command allows users to compress several files on the current directory by marking them and then calling {{ic|:compress ''package name''}}. It supports name suggestions by getting the basename of the current directory and appending several possibilities for the extension. You need to have {{pkg|atool}} installed, otherwise you will see an error message when you create the archive.<br />
<br />
{{bc|<nowiki><br />
import os<br />
from ranger.core.loader import CommandLoader<br />
<br />
class compress(Command):<br />
def execute(self):<br />
""" Compress marked files to current directory """<br />
cwd = self.fm.thisdir<br />
marked_files = cwd.get_selection()<br />
<br />
if not marked_files:<br />
return<br />
<br />
def refresh(_):<br />
cwd = self.fm.get_directory(original_path)<br />
cwd.load_content()<br />
<br />
original_path = cwd.path<br />
parts = self.line.split()<br />
au_flags = parts[1:]<br />
<br />
descr = "compressing files in: " + os.path.basename(parts[1])<br />
obj = CommandLoader(args=['apack'] + au_flags + \<br />
[os.path.relpath(f.path, cwd.path) for f in marked_files], descr=descr, read=True)<br />
<br />
obj.signal_bind('after', refresh)<br />
self.fm.loader.add(obj)<br />
<br />
def tab(self, tabnum):<br />
""" Complete with current folder name """<br />
<br />
extension = ['.zip', '.tar.gz', '.rar', '.7z']<br />
return ['compress ' + os.path.basename(self.fm.thisdir.path) + ext for ext in extension]<br />
</nowiki>}}<br />
<br />
=== External drives ===<br />
<br />
External drives can be automatically mounted with [[udev]] or [[udisks]]. The default key mappings to go to common mount points {{ic|/media}} and {{ic|/run/media/$USER}} are {{ic|gm}} and {{ic|gi}} respectively.<br />
<br />
=== Hidden files ===<br />
<br />
You can toggle the visibility of hidden files with the following command: {{ic|:set show_hidden!}}, or use {{ic|:set show_hidden true}} to make hidden files visible.<br />
<br />
To make this permanent, add the setting to your configuration file:<br />
<br />
{{hc|rc.conf|<nowiki><br />
set show_hidden true<br />
</nowiki>}}<br />
<br />
Alternatively, hidden files can be toggled by pressing {{ic|zh}}.<br />
<br />
=== Image mounting ===<br />
<br />
The following command assumes you are using [[CDemu]] as your image mounter and some kind of system like [[autofs]] which mounts the virtual drive to a specified location ('/media/virtualrom' in this case). '''Do not forget to change mountpath to reflect your system settings'''.<br />
<br />
To mount an image (or images) to a cdemud virtual drive from ranger you select the image files and then type ':mount' on the console. The mounting may actually take some time depending on your setup (in mine it may take as long as one minute) so the command uses a custom loader that waits until the mount directory is mounted and then opens it on the background in tab 9.<br />
<br />
{{bc|<nowiki><br />
import os, time<br />
from ranger.core.loader import Loadable<br />
from ranger.ext.signals import SignalDispatcher<br />
from ranger.ext.shell_escape import *<br />
<br />
class MountLoader(Loadable, SignalDispatcher):<br />
"""<br />
Wait until a directory is mounted<br />
"""<br />
def __init__(self, path):<br />
SignalDispatcher.__init__(self)<br />
descr = "Waiting for dir '" + path + "' to be mounted"<br />
Loadable.__init__(self, self.generate(), descr)<br />
self.path = path<br />
<br />
def generate(self):<br />
available = False<br />
while not available:<br />
try:<br />
if os.path.ismount(self.path):<br />
available = True<br />
except:<br />
pass<br />
yield<br />
time.sleep(0.03)<br />
self.signal_emit('after')<br />
<br />
class mount(Command):<br />
def execute(self):<br />
selected_files = self.fm.thisdir.get_selection()<br />
<br />
if not selected_files:<br />
return<br />
<br />
space = ' '<br />
self.fm.execute_command("cdemu -b system unload 0")<br />
self.fm.execute_command("cdemu -b system load 0 " + \<br />
space.join([shell_escape(f.path) for f in selected_files]))<br />
<br />
mountpath = "/media/virtualrom/"<br />
<br />
def mount_finished(path):<br />
currenttab = self.fm.current_tab<br />
self.fm.tab_open(9, mountpath)<br />
self.fm.tab_open(currenttab)<br />
<br />
obj = MountLoader(mountpath)<br />
obj.signal_bind('after', mount_finished)<br />
self.fm.loader.add(obj)<br />
</nowiki>}}<br />
<br />
=== New tab in current folder ===<br />
<br />
You may have noticed there are two shortcuts for opening a new tab in home ({{ic|g}}{{ic|n}} and {{ic|Ctrl+n}}). Let us rebind {{ic|Ctrl+n}}:<br />
{{hc|rc.conf|<nowiki><br />
map <c-n> eval fm.tab_new('%d')<br />
</nowiki>}}<br />
<br />
=== PDF file preview ===<br />
By default, ranger will preview PDF files as text. However, you can preview PDF files as an image in ranger by first converting the PDF file to an image. Ranger stores the image previews in {{ic|~/.cache/ranger/}}. You either need to create this directory manually or set {{ic|preview_images}} to {{ic|true}} in {{ic|~/.config/ranger/rc.conf}} to tell {{ic|ranger}} to create it automatically at the next start. However, note that {{ic|preview_images}} does not need to be set to {{ic|true}} the whole time to preview PDF file as images, only {{ic|~/.cache/ranger}} directory is needed.<br />
<br />
To enable this feature, uncomment the appropriate lines in {{ic|/usr/share/doc/ranger/config/scope.sh}}, or add/uncomment these lines in your local file {{ic|~/.config/ranger/scope.sh}}.<br />
<br />
=== Shell tips ===<br />
<br />
==== Synchronize path ====<br />
<br />
Ranger provides a shell [[Bash/Functions|function]] {{ic|/usr/share/doc/ranger/examples/shell_automatic_cd.sh}}. Running {{ic|ranger_cd}} instead of {{ic|ranger}} will automatically ''cd'' to the last browsed folder.<br />
<br />
If you launch ranger from a graphical launcher (such as {{ic|$TERMCMD -e ranger}}, where TERMCMD is an X terminal), you cannot use {{ic|ranger_cd}}. Instead, create an executable script:<br />
<br />
{{hc|ranger-launcher.sh|<nowiki><br />
#!/bin/sh<br />
export RANGERCD=true<br />
$TERMCMD<br />
</nowiki>}}<br />
<br />
And add the following at the end of your shell configuration:<br />
<br />
{{hc|.''shell''rc|<nowiki><br />
$RANGERCD && unset RANGERCD && ranger_cd<br />
</nowiki>}}<br />
<br />
This will launch {{ic|ranger_cd}} only if the {{ic|RANGERCD}} variable is set. It is important to unset this variable again, otherwise launching a subshell from this terminal will automatically relaunch {{ic|ranger}}.<br />
<br />
==== Start a shell from ranger ====<br />
<br />
{{Accuracy|the shell seems to start in the correct directory by default with Ranger's {{ic|S}} key binding|section=Starting a shell in the current directory}}<br />
<br />
With the previous method you can switch to a shell in last browsed path simply by leaving ranger. However you may not want to quit ranger for several reasons (numerous opened tabs, copy in progress, etc.).<br />
You can start a shell from ranger ({{ic|S}} by default) without losing your ranger session. Unfortunately, the shell will not switch to the current folder automatically. Again, this can be solved with an executable script:<br />
<br />
{{hc|shellcd|<nowiki><br />
#!/bin/sh<br />
export AUTOCD="$(realpath "$1")"<br />
<br />
$SHELL<br />
</nowiki>}}<br />
<br />
and - as before - add this to at the very end of your shell configuration:<br />
<br />
{{hc|shellrc|<nowiki><br />
cd "$AUTOCD"<br />
</nowiki>}}<br />
<br />
Now you can change your shell binding for ranger:<br />
<br />
{{hc|rc.conf|<br />
map S shell shellcd %d<br />
}}<br />
<br />
Alternatively, you can make use of your shell history file if it has one. For instance, you could do this for [[zsh#Dirstack|zsh]]:<br />
<br />
{{hc|shellcd|<nowiki><br />
## Prepend argument to zsh dirstack.<br />
BUF="$(realpath "$1")<br />
$(grep -v "$(realpath "$1")" "$ZDIRS")"<br />
echo "$BUF" > "$ZDIRS"<br />
<br />
zsh<br />
</nowiki>}}<br />
<br />
Change ZDIRS for your dirstack.<br />
<br />
===== A simpler solution =====<br />
<br />
{{hc|rc.conf|<nowiki><br />
map S shell bash -c "cd %d; bash"<br />
</nowiki>}}<br />
This could probably be adapted to other shells as well.<br />
Instead of just running a shell (like the default config), this will run {{ic|cd}} in a shell, then execute a interactive shell which will not immediately exit so that you can continue with what you wanted.<br />
<br />
==== Preventing nested ranger instances ====<br />
<br />
You can start a shell in the current directory with {{ic|S}}, when you exit the shell you get back to your ranger instance.<br />
<br />
When you however forget that you already are in a ranger shell and start ranger again you end up with ranger running a shell running ranger.<br />
<br />
To prevent this you can create the following function in your [[Autostarting#On_shell_login_.2F_logout|shell's startup file]]:<br />
<br />
ranger() {<br />
if [ -z "$RANGER_LEVEL" ]; then<br />
/usr/bin/ranger "$@"<br />
else<br />
exit<br />
fi<br />
}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Artifacts in image preview ===<br />
<br />
Borderless columns may cause stripes in image previews. [https://bbs.linuxdistrocommunity.com/showthread.php?tid=1051] In {{ic|~/.config/ranger/rc.conf}} set:<br />
<br />
set draw_borders true<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=93025 BBS thread]<br />
* [http://dotshare.it/category/fms/ranger/ DotShare.it configurations]<br />
* [https://github.com/hut/ranger GitHub]<br />
* [https://github.com/ranger/ranger/wiki/Official-user-guide Official User Guide]<br />
* [https://www.digitalocean.com/community/tutorials/installing-and-using-ranger-a-terminal-file-manager-on-a-ubuntu-vps Installing and using ranger]<br />
* [https://lists.nongnu.org/mailman/listinfo/ranger-users Mailing list]<br />
* [https://bloerg.net/2012/10/17/ranger-file-manager.html Ranger tutorial]</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:PipeWire&diff=653934Talk:PipeWire2021-03-03T19:30:23Z<p>Edh: /* Better introduction? */ Re: Agree</p>
<hr />
<div>== 0.3.16 pulse replacement ==<br />
<br />
For the pulse-dropin-replacement to work, you probably also need to clear your users config, {{ic|~/.config/pulse}} (like in delete/move the content) - That is created by pulseaudio for pulseaudio.<br />
Otherwise the server could be unable to start.<br />
<br />
[[User:Fabis.cafe|Fabis.cafe]] ([[User talk:Fabis.cafe|talk]]) 14:12, 23 November 2020 (UTC)<br />
<br />
----<br />
<br />
I just installed the pulse replacement and while everything seems to be working just fine, the only problem is gnome-shell doesn't seem to be able to see the pipewrire pulse server, thus the volume control in the top right system menu is absent and keyboard media keys for volume don't work either. I think this should be addressed in the troubleshooting section with a solution if there is one.<br />
<br />
Interestingly enough gnome-control-center is able to control the volume as well as other typical pulseaudio parameters.<br />
<br />
UPDATE: running {{ic|killall pipewire-pulse; killall pipewire}} restarts the pipewire pulse daemon and makes the volume control in gnome-shell work as expected. This of course is a workaround and not a proper solution.<br />
<br />
UPDATE 2: the above makes the volume control menu item and shortcuts appear, but adjusting the volume does nothing.<br />
<br />
[[User:GabMus|GabMus]] ([[User talk:GabMus|talk]]) 09:39, 3 December 2020 (UTC)<br />
<br />
:I don't see volume indicator in gnome-shell/wayland but I'm able to control volume with media keys. -- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 15:55, 3 December 2020 (UTC)<br />
<br />
:: Possibly related: https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/426 [[User:Hexchain|Hexchain]] ([[User talk:Hexchain|talk]]) 18:05, 3 December 2020 (UTC)<br />
<br />
: Solved, refer to the latest change I made in the main page, found the solution thanks to Hexchain's link. -- [[User:GabMus|GabMus]] ([[User talk:GabMus|talk]]) 19:55, 4 December 2020 (UTC)<br />
<br />
== aptX support ==<br />
<br />
Does `pipewire` support low latency/high quality bluetooth codecs (aptX, LDAC, ...) ? <br />
<br />
along the lines of https://aur.archlinux.org/packages/pulseaudio-modules-bt-git/ <br />
<br />
If yes, how to configure it? <br />
<br />
along the lines of https://freedesktop.org/software/pulseaudio/pavucontrol/ <br />
<br />
[[User:NTia89|nTia89]] ([[User talk:NTia89|talk]]) 21:23, 3 December 2020 (UTC)<br />
<br />
: I switched to PipeWire and currently bluetooth sound poorly works: high latency and low quality.<br />
: Actually open bug/enhancement in pipewire bugtracker [https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/136].<br />
[[User:NTia89|nTia89]] ([[User talk:NTia89|talk]]) 10:20, 5 December 2020 (UTC)<br />
<br />
: It does now but currently there is no way to select a codec manually. It uses (the first supported?) codec in this order: LDAC, AptX HD, AptX, SBC. You can check for the current codec with {{ic|pactl list sinks}} IIRC. [[User:Hexchain|Hexchain]] ([[User talk:Hexchain|talk]]) 00:41, 21 December 2020 (UTC)<br />
<br />
== Better introduction? ==<br />
<br />
Right now I think the description is missing some content to exactly explain what pipewire is and what it can be used for.<br />
The website names some important examples imho:<br />
<br />
* Capture and playback of audio and video with minimal latency.<br />
* Real-time Multimedia processing on audio and video.<br />
* Multiprocess architecture to let applications share multimedia content.<br />
* Seamless support for PulseAudio, JACK, ALSA and GStreamer applications.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 15:21, 28 February 2021 (UTC)<br />
<br />
: I fully agree! TBH I don't see an urgent need for a discussion on this topic. Feel free to amend the page with whatever you think is right. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 19:30, 3 March 2021 (UTC)<br />
<br />
== Move section "webrtc screen sharing" below other sections in "Usage" ==<br />
<br />
I think that the "Audio" and "Video" sections are more important and more general, so they should be placed first.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 15:23, 28 February 2021 (UTC)<br />
<br />
: IMHO the ordering is just fine as of now. Pipewire is completely optional for handling audio and video. However, for screensharing under wayland you must use it. I strongly believe that this section is of most interest to the average user. Note, I am fine though with whatever reaches a consensus. I do not feel too strongly about the ordering of these sections. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 19:28, 3 March 2021 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:PipeWire&diff=653933Talk:PipeWire2021-03-03T19:28:21Z<p>Edh: /* Move section "webrtc screen sharing" below other sections in "Usage" */ Re: I disagree with the proposal as I believe the ordering is just fine as it is now</p>
<hr />
<div>== 0.3.16 pulse replacement ==<br />
<br />
For the pulse-dropin-replacement to work, you probably also need to clear your users config, {{ic|~/.config/pulse}} (like in delete/move the content) - That is created by pulseaudio for pulseaudio.<br />
Otherwise the server could be unable to start.<br />
<br />
[[User:Fabis.cafe|Fabis.cafe]] ([[User talk:Fabis.cafe|talk]]) 14:12, 23 November 2020 (UTC)<br />
<br />
----<br />
<br />
I just installed the pulse replacement and while everything seems to be working just fine, the only problem is gnome-shell doesn't seem to be able to see the pipewrire pulse server, thus the volume control in the top right system menu is absent and keyboard media keys for volume don't work either. I think this should be addressed in the troubleshooting section with a solution if there is one.<br />
<br />
Interestingly enough gnome-control-center is able to control the volume as well as other typical pulseaudio parameters.<br />
<br />
UPDATE: running {{ic|killall pipewire-pulse; killall pipewire}} restarts the pipewire pulse daemon and makes the volume control in gnome-shell work as expected. This of course is a workaround and not a proper solution.<br />
<br />
UPDATE 2: the above makes the volume control menu item and shortcuts appear, but adjusting the volume does nothing.<br />
<br />
[[User:GabMus|GabMus]] ([[User talk:GabMus|talk]]) 09:39, 3 December 2020 (UTC)<br />
<br />
:I don't see volume indicator in gnome-shell/wayland but I'm able to control volume with media keys. -- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 15:55, 3 December 2020 (UTC)<br />
<br />
:: Possibly related: https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/426 [[User:Hexchain|Hexchain]] ([[User talk:Hexchain|talk]]) 18:05, 3 December 2020 (UTC)<br />
<br />
: Solved, refer to the latest change I made in the main page, found the solution thanks to Hexchain's link. -- [[User:GabMus|GabMus]] ([[User talk:GabMus|talk]]) 19:55, 4 December 2020 (UTC)<br />
<br />
== aptX support ==<br />
<br />
Does `pipewire` support low latency/high quality bluetooth codecs (aptX, LDAC, ...) ? <br />
<br />
along the lines of https://aur.archlinux.org/packages/pulseaudio-modules-bt-git/ <br />
<br />
If yes, how to configure it? <br />
<br />
along the lines of https://freedesktop.org/software/pulseaudio/pavucontrol/ <br />
<br />
[[User:NTia89|nTia89]] ([[User talk:NTia89|talk]]) 21:23, 3 December 2020 (UTC)<br />
<br />
: I switched to PipeWire and currently bluetooth sound poorly works: high latency and low quality.<br />
: Actually open bug/enhancement in pipewire bugtracker [https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/136].<br />
[[User:NTia89|nTia89]] ([[User talk:NTia89|talk]]) 10:20, 5 December 2020 (UTC)<br />
<br />
: It does now but currently there is no way to select a codec manually. It uses (the first supported?) codec in this order: LDAC, AptX HD, AptX, SBC. You can check for the current codec with {{ic|pactl list sinks}} IIRC. [[User:Hexchain|Hexchain]] ([[User talk:Hexchain|talk]]) 00:41, 21 December 2020 (UTC)<br />
<br />
== Better introduction? ==<br />
<br />
Right now I think the description is missing some content to exactly explain what pipewire is and what it can be used for.<br />
The website names some important examples imho:<br />
<br />
* Capture and playback of audio and video with minimal latency.<br />
* Real-time Multimedia processing on audio and video.<br />
* Multiprocess architecture to let applications share multimedia content.<br />
* Seamless support for PulseAudio, JACK, ALSA and GStreamer applications.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 15:21, 28 February 2021 (UTC)<br />
<br />
== Move section "webrtc screen sharing" below other sections in "Usage" ==<br />
<br />
I think that the "Audio" and "Video" sections are more important and more general, so they should be placed first.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 15:23, 28 February 2021 (UTC)<br />
<br />
: IMHO the ordering is just fine as of now. Pipewire is completely optional for handling audio and video. However, for screensharing under wayland you must use it. I strongly believe that this section is of most interest to the average user. Note, I am fine though with whatever reaches a consensus. I do not feel too strongly about the ordering of these sections. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 19:28, 3 March 2021 (UTC)</div>Edhhttps://wiki.archlinux.org/index.php?title=XDG_MIME_Applications&diff=653386XDG MIME Applications2021-02-25T11:18:22Z<p>Edh: Replace an underscore with a space in a link to a wiki page</p>
<hr />
<div>[[Category:Freedesktop.org]]<br />
[[ja:デフォルトアプリケーション]]<br />
[[ru:XDG MIME Applications]]<br />
[[zh-hans:Default applications]]<br />
{{Related articles start}}<br />
{{Related|Desktop entries}}<br />
{{Related|Desktop environment}}<br />
{{Related|Window manager}}<br />
{{Related|Default applications}}<br />
{{Related|xdg-utils}}<br />
{{Related articles end}}<br />
The [https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-latest.html XDG MIME Applications specification] builds upon the [[#Shared MIME database|shared MIME database]] and [[desktop entries]] to provide [[default applications]].<br />
<br />
# Applications describe what MIME types they can handle using [[desktop entries]].<br />
# {{Pkg|desktop-file-utils}} registers a [[pacman hook]] to build a cache database of MIME types handled by desktop entries, see {{man|1|update-desktop-database}}.<br />
# Applications can install new MIME types by placing XML files in {{ic|/usr/share/mime/packages/}}.<br />
# {{Pkg|shared-mime-info}} registers a [[pacman hook]] to build the Shared MIME-Info database cache, see {{man|1|update-mime-database}}.<br />
# [[Desktop environment]]s and users can change default applications and add or remove MIME type to application associations using [[#mimeapps.list|mimeapps.list]] files.<br />
<br />
== Shared MIME database ==<br />
<br />
The [https://specifications.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html XDG Shared MIME-info Database specification] facilitates a shared MIME database across desktop environments and allows applications to easily register new MIME types system-wide.<br />
<br />
The database is built from the XML files installed by packages in {{ic|/usr/share/mime/packages/}} using the tools from {{Pkg|shared-mime-info}}.<br />
<br />
The files in {{ic|/usr/share/mime/}} should not be directly edited, however it is possible to maintain a separate database on a per-user basis in the {{ic|~/.local/share/mime/}} tree.<br />
<br />
"URI scheme handling [..] are handled through applications handling the {{ic|x-scheme-handler/foo}} MIME type, where foo is the URI scheme in question."[https://specifications.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html#idm140625828587776]<br />
<br />
=== New MIME types ===<br />
<br />
{{expansion|Is the process different for assigning an extension to an existing MIME type?}}<br />
<br />
This example defines a new MIME type {{ic|application/x-foobar}} and assigns it to any file with a name ending in ''.foo''. Simply create the following file:<br />
<br />
{{hc|~/.local/share/mime/packages/application-x-foobar.xml|2=<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<nowiki><mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info"></nowiki><br />
'''<mime-type type="application/x-foobar">'''<br />
<comment>foo file</comment><br />
<icon name="application-x-foobar"/><br />
<glob-deleteall/><br />
'''<glob pattern="*.foo"/>'''<br />
</mime-type><br />
</mime-info><br />
}}<br />
<br />
And then update the MIME database:<br />
<br />
$ update-mime-database ~/.local/share/mime<br />
<br />
Of course this will not have any effect if no desktop entries are associated with the MIME type. You may need to create new [[desktop entries]] or modify [[#mimeapps.list|mimeapps.list]].<br />
<br />
== mimeapps.list ==<br />
<br />
The [https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-1.0.html XDG standard] is the most common for configuring desktop environments. Default applications for each MIME type are stored in {{ic|mimeapps.list}} files, which can be stored in several locations. They are searched in the following order, with earlier associations taking precedence over later ones:<br />
<br />
{| class="wikitable"<br />
! Path !! Usage<br />
|-<br />
| {{ic|~/.config/mimeapps.list}} || user overrides<br />
|-<br />
| {{ic|/etc/xdg/mimeapps.list}} || system-wide overrides<br />
|-<br />
| {{ic|~/.local/share/applications/mimeapps.list}} || ('''deprecated''') user overrides<br />
|-<br />
| {{ic|/usr/local/share/applications/mimeapps.list}}<br>{{ic|/usr/share/applications/mimeapps.list}} || distribution-provided defaults<br />
|}<br />
<br />
Additionally, it is possible to define [[desktop environment]]-specific default applications in a file named {{ic|''desktop''-mimeapps.list}} where {{ic|''desktop''}} is the name of the desktop environment (from the {{ic|XDG_CURRENT_DESKTOP}} environment variable). For example, {{ic|/etc/xdg/xfce-mimeapps.list}} defines system-wide default application overrides for [[Xfce]]. These desktop-specific overrides take precedence over the corresponding non-desktop-specific file. For example, {{ic|/etc/xdg/xfce-mimeapps.list}} takes precedence over {{ic|/etc/xdg/mimeapps.list}} but is still overridden by {{ic|~/.config/mimeapps.list}}.<br />
<br />
{{Tip|1=Although deprecated, several applications still read/write to {{ic|~/.local/share/applications/mimeapps.list}}. To simplify maintenance, simply symlink it to {{ic|~/.config/mimeapps.list}}: {{bc|$ ln -s ~/.config/mimeapps.list ~/.local/share/applications/mimeapps.list}}}}<br />
<br />
{{Note|You might also find files in these locations named {{ic|defaults.list}}. This file is similar to {{ic|mimeapps.list}} except it only lists default applications (not added/removed associations). It is now deprecated and should be manually merged with {{ic|mimeapps.list}}.}}<br />
<br />
To discover all the files that are scanned it is possible to enable debug mode by setting the environment variable ''XDG_UTILS_DEBUG_LEVEL=2'': e.g. the {{ic|''xdg-mime query default <type>''}} command will print each configuration file it is searchin for mime information.<br />
<br />
==== Format ====<br />
<br />
Consider the following example:<br />
<br />
{{hc|mimeapps.list|2=<br />
[Added Associations]<br />
image/jpeg=bar.desktop;baz.desktop<br />
video/H264=bar.desktop<br />
[Removed Associations]<br />
video/H264=baz.desktop<br />
[Default Applications]<br />
image/jpeg=foo.desktop}}<br />
<br />
Each section assigns one or more desktop entries to MIME types.<br />
* '''Added Associations''' indicates that the applications support opening that MIME type. For example, {{ic|bar.desktop}} and {{ic|baz.desktop}} can open JPEG images. This might affect the application list you see when right-clicking a file in a file browser.<br />
* '''Removed Associations''' indicates that the applications ''do not'' support that MIME type. For example, {{ic|baz.desktop}} cannot open H.264 video.<br />
* '''Default Applications''' indicates that the applications should be the default choice for opening that MIME type. For example, JPEG images should be opened with {{ic|foo.desktop}}. This implicitly adds an association between the application and the MIME type. If there are multiple applications, they are tried in order.<br />
<br />
Each section is optional and can be omitted if unneeded.<br />
<br />
== Utilities ==<br />
<br />
While it is possible to configure default applications and MIME types by directly editing [[#mimeapps.list|mimeapps.list]] and the [[#Shared MIME database|shared MIME database]], there are many tools that can simplify the process. These tools are also important because applications may delegate opening of files to these tools rather than trying to implement the MIME type standard themselves.<br />
<br />
If you use a [[desktop environment]] you should first check if it provides its own utility. That should be preferred over these alternatives.<br />
<br />
The official [[xdg-utils]] contain tools for managing MIME types and default applications according to the XDG standard ([[xdg-utils#xdg-mime|xdg-mime]]). Most importantly it provides [[xdg-open]] which many applications use to open a file with its default application.<br />
<br />
=== lsdesktopf ===<br />
<br />
{{AUR|lsdesktopf}} provides several methods of searching the MIME database and desktop MIME entries.<br />
<br />
For example, to see all MIME extensions in the system's ''.desktop'' files that have MIME type {{ic|video}} you can use {{ic|lsdesktopf --gm -gx video}} or to search in the XML database files use {{ic|lsdesktopf --gdx -gx video}}. To get a quick overview of how many and which ''.desktop'' files can be associated with a certain MIME type, use {{ic|lsdesktopf --gen-mimeapps}}. To see all file name extensions in XML database files, use {{ic|lsdesktopf --gdx -gfx}}.<br />
<br />
=== selectdefaultapplication ===<br />
<br />
{{AUR|selectdefaultapplication-git}} is GUI application that lists up all applications supporting various mimetypes and lets you quickly set it as default for all or some of the mimetypes it supports (by modifying {{ic|mimeapps.list}}).<br />
<br />
It shows the "readable" name and file extensions as well, so you do not need to remember the name of the mimetypes.<br />
<br />
== Troubleshooting ==<br />
<br />
If a file is not being opened by your desired default application, there are several possible causes. You may need to check each case.<br />
<br />
=== Missing desktop entry ===<br />
<br />
A [[desktop entry]] is required in order to associate an application with a MIME type. Ensure that such an entry exists and can be used to (manually) open files in the application.<br />
<br />
=== Missing association ===<br />
<br />
If the application's desktop entry does not specify the MIME type under its {{ic|MimeType}} key, it will not be considered when an application is needed to open that type. Edit [[#mimeapps.list|mimeapps.list]] to add an association between the .desktop file and the MIME type.<br />
<br />
=== Non-default application ===<br />
<br />
If the desktop entry is associated with the MIME type, it may simply not be set as the default. Edit [[#mimeapps.list|mimeapps.list]] to set the default association.<br />
<br />
=== Nonstandard association ===<br />
<br />
Applications are free to ignore or only partially implement the XDG standard. Check for usage of deprecated files such as {{ic|~/.local/share/applications/mimeapps.list}} and {{ic|~/.local/share/applications/defaults.list}}. If you are attempting to open the file from another application (e.g. a web browser or file manager) check if that application has its own method of selecting default applications.<br />
<br />
=== Variables in .desktop files that affect application launch ===<br />
<br />
{{Expansion|1=The fact {{ic|MimeType}} entries may be missing in the desktop files is only implied here, i.e. "Even if an application...", though this is a common cause of errors. Some openers may also associate mime types not explicitly listed in a desktop file (such as {{Pkg|exo}}). Further environment-specific factors are at play, e.g. whether {{ic|1=Terminal=true}} has an effect, though latter should arguably be expanded on in [[Desktop entries]].}}<br />
<br />
Desktop environments and file managers supporting the specifications launch programs according to definition in the ''.desktop'' files. See [[Desktop entries#Application entry]]. <br />
<br />
Usually, configuration of the packaged ''.desktop'' files is not required, but it may not be bug-free. Even if an application containing necessary MIME type description in the ''.desktop'' file {{ic|MimeType}} variable that is used for association, it can fail to start correctly, not start at all or start without opening a file. <br />
<br />
This may happen, for example, if the {{ic|Exec}} variable is missing internal options needed for how to open a file, or how the application is shown in the menu. The {{ic|Exec}} variable usually begins with {{ic|%}}; for its currently supported options, see [https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#exec-variables exec-variables].<br />
<br />
The following table lists the main variable entries of ''.desktop'' files that affect how an application starts, if it has a MIME type associated with it. <br />
<br />
{| class="wikitable"<br />
! Variable names !! Example 1 content !! Example 2 content !! Description<br />
|-<br />
| DBusActivatable || DBusActivatable=true || DBusActivatable=false || Application interact with [https://www.freedesktop.org/wiki/Software/dbus/ D-Bus]. <br> See also configuration: [https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus D-Bus].<br />
|-<br />
| MimeType || MimeType=application/vnd.oasis.opendocument.text || MimeType=application/vnd.sun.xml.math || List of MIME types supported by application<br />
|-<br />
| StartupWMClass || StartupWMClass=google-chrome || StartupWMClass=xpad || Associate windows with the owning application<br />
|-<br />
| Terminal || Terminal=true || Terminal=false || Start in default terminal<br />
|}</div>Edhhttps://wiki.archlinux.org/index.php?title=XDG_MIME_Applications&diff=653385XDG MIME Applications2021-02-25T11:17:41Z<p>Edh: Add `xdg-utils` and `Default_applications` to the list of related articles</p>
<hr />
<div>[[Category:Freedesktop.org]]<br />
[[ja:デフォルトアプリケーション]]<br />
[[ru:XDG MIME Applications]]<br />
[[zh-hans:Default applications]]<br />
{{Related articles start}}<br />
{{Related|Desktop entries}}<br />
{{Related|Desktop environment}}<br />
{{Related|Window manager}}<br />
{{Related|Default_applications}}<br />
{{Related|xdg-utils}}<br />
{{Related articles end}}<br />
The [https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-latest.html XDG MIME Applications specification] builds upon the [[#Shared MIME database|shared MIME database]] and [[desktop entries]] to provide [[default applications]].<br />
<br />
# Applications describe what MIME types they can handle using [[desktop entries]].<br />
# {{Pkg|desktop-file-utils}} registers a [[pacman hook]] to build a cache database of MIME types handled by desktop entries, see {{man|1|update-desktop-database}}.<br />
# Applications can install new MIME types by placing XML files in {{ic|/usr/share/mime/packages/}}.<br />
# {{Pkg|shared-mime-info}} registers a [[pacman hook]] to build the Shared MIME-Info database cache, see {{man|1|update-mime-database}}.<br />
# [[Desktop environment]]s and users can change default applications and add or remove MIME type to application associations using [[#mimeapps.list|mimeapps.list]] files.<br />
<br />
== Shared MIME database ==<br />
<br />
The [https://specifications.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html XDG Shared MIME-info Database specification] facilitates a shared MIME database across desktop environments and allows applications to easily register new MIME types system-wide.<br />
<br />
The database is built from the XML files installed by packages in {{ic|/usr/share/mime/packages/}} using the tools from {{Pkg|shared-mime-info}}.<br />
<br />
The files in {{ic|/usr/share/mime/}} should not be directly edited, however it is possible to maintain a separate database on a per-user basis in the {{ic|~/.local/share/mime/}} tree.<br />
<br />
"URI scheme handling [..] are handled through applications handling the {{ic|x-scheme-handler/foo}} MIME type, where foo is the URI scheme in question."[https://specifications.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html#idm140625828587776]<br />
<br />
=== New MIME types ===<br />
<br />
{{expansion|Is the process different for assigning an extension to an existing MIME type?}}<br />
<br />
This example defines a new MIME type {{ic|application/x-foobar}} and assigns it to any file with a name ending in ''.foo''. Simply create the following file:<br />
<br />
{{hc|~/.local/share/mime/packages/application-x-foobar.xml|2=<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<nowiki><mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info"></nowiki><br />
'''<mime-type type="application/x-foobar">'''<br />
<comment>foo file</comment><br />
<icon name="application-x-foobar"/><br />
<glob-deleteall/><br />
'''<glob pattern="*.foo"/>'''<br />
</mime-type><br />
</mime-info><br />
}}<br />
<br />
And then update the MIME database:<br />
<br />
$ update-mime-database ~/.local/share/mime<br />
<br />
Of course this will not have any effect if no desktop entries are associated with the MIME type. You may need to create new [[desktop entries]] or modify [[#mimeapps.list|mimeapps.list]].<br />
<br />
== mimeapps.list ==<br />
<br />
The [https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-1.0.html XDG standard] is the most common for configuring desktop environments. Default applications for each MIME type are stored in {{ic|mimeapps.list}} files, which can be stored in several locations. They are searched in the following order, with earlier associations taking precedence over later ones:<br />
<br />
{| class="wikitable"<br />
! Path !! Usage<br />
|-<br />
| {{ic|~/.config/mimeapps.list}} || user overrides<br />
|-<br />
| {{ic|/etc/xdg/mimeapps.list}} || system-wide overrides<br />
|-<br />
| {{ic|~/.local/share/applications/mimeapps.list}} || ('''deprecated''') user overrides<br />
|-<br />
| {{ic|/usr/local/share/applications/mimeapps.list}}<br>{{ic|/usr/share/applications/mimeapps.list}} || distribution-provided defaults<br />
|}<br />
<br />
Additionally, it is possible to define [[desktop environment]]-specific default applications in a file named {{ic|''desktop''-mimeapps.list}} where {{ic|''desktop''}} is the name of the desktop environment (from the {{ic|XDG_CURRENT_DESKTOP}} environment variable). For example, {{ic|/etc/xdg/xfce-mimeapps.list}} defines system-wide default application overrides for [[Xfce]]. These desktop-specific overrides take precedence over the corresponding non-desktop-specific file. For example, {{ic|/etc/xdg/xfce-mimeapps.list}} takes precedence over {{ic|/etc/xdg/mimeapps.list}} but is still overridden by {{ic|~/.config/mimeapps.list}}.<br />
<br />
{{Tip|1=Although deprecated, several applications still read/write to {{ic|~/.local/share/applications/mimeapps.list}}. To simplify maintenance, simply symlink it to {{ic|~/.config/mimeapps.list}}: {{bc|$ ln -s ~/.config/mimeapps.list ~/.local/share/applications/mimeapps.list}}}}<br />
<br />
{{Note|You might also find files in these locations named {{ic|defaults.list}}. This file is similar to {{ic|mimeapps.list}} except it only lists default applications (not added/removed associations). It is now deprecated and should be manually merged with {{ic|mimeapps.list}}.}}<br />
<br />
To discover all the files that are scanned it is possible to enable debug mode by setting the environment variable ''XDG_UTILS_DEBUG_LEVEL=2'': e.g. the {{ic|''xdg-mime query default <type>''}} command will print each configuration file it is searchin for mime information.<br />
<br />
==== Format ====<br />
<br />
Consider the following example:<br />
<br />
{{hc|mimeapps.list|2=<br />
[Added Associations]<br />
image/jpeg=bar.desktop;baz.desktop<br />
video/H264=bar.desktop<br />
[Removed Associations]<br />
video/H264=baz.desktop<br />
[Default Applications]<br />
image/jpeg=foo.desktop}}<br />
<br />
Each section assigns one or more desktop entries to MIME types.<br />
* '''Added Associations''' indicates that the applications support opening that MIME type. For example, {{ic|bar.desktop}} and {{ic|baz.desktop}} can open JPEG images. This might affect the application list you see when right-clicking a file in a file browser.<br />
* '''Removed Associations''' indicates that the applications ''do not'' support that MIME type. For example, {{ic|baz.desktop}} cannot open H.264 video.<br />
* '''Default Applications''' indicates that the applications should be the default choice for opening that MIME type. For example, JPEG images should be opened with {{ic|foo.desktop}}. This implicitly adds an association between the application and the MIME type. If there are multiple applications, they are tried in order.<br />
<br />
Each section is optional and can be omitted if unneeded.<br />
<br />
== Utilities ==<br />
<br />
While it is possible to configure default applications and MIME types by directly editing [[#mimeapps.list|mimeapps.list]] and the [[#Shared MIME database|shared MIME database]], there are many tools that can simplify the process. These tools are also important because applications may delegate opening of files to these tools rather than trying to implement the MIME type standard themselves.<br />
<br />
If you use a [[desktop environment]] you should first check if it provides its own utility. That should be preferred over these alternatives.<br />
<br />
The official [[xdg-utils]] contain tools for managing MIME types and default applications according to the XDG standard ([[xdg-utils#xdg-mime|xdg-mime]]). Most importantly it provides [[xdg-open]] which many applications use to open a file with its default application.<br />
<br />
=== lsdesktopf ===<br />
<br />
{{AUR|lsdesktopf}} provides several methods of searching the MIME database and desktop MIME entries.<br />
<br />
For example, to see all MIME extensions in the system's ''.desktop'' files that have MIME type {{ic|video}} you can use {{ic|lsdesktopf --gm -gx video}} or to search in the XML database files use {{ic|lsdesktopf --gdx -gx video}}. To get a quick overview of how many and which ''.desktop'' files can be associated with a certain MIME type, use {{ic|lsdesktopf --gen-mimeapps}}. To see all file name extensions in XML database files, use {{ic|lsdesktopf --gdx -gfx}}.<br />
<br />
=== selectdefaultapplication ===<br />
<br />
{{AUR|selectdefaultapplication-git}} is GUI application that lists up all applications supporting various mimetypes and lets you quickly set it as default for all or some of the mimetypes it supports (by modifying {{ic|mimeapps.list}}).<br />
<br />
It shows the "readable" name and file extensions as well, so you do not need to remember the name of the mimetypes.<br />
<br />
== Troubleshooting ==<br />
<br />
If a file is not being opened by your desired default application, there are several possible causes. You may need to check each case.<br />
<br />
=== Missing desktop entry ===<br />
<br />
A [[desktop entry]] is required in order to associate an application with a MIME type. Ensure that such an entry exists and can be used to (manually) open files in the application.<br />
<br />
=== Missing association ===<br />
<br />
If the application's desktop entry does not specify the MIME type under its {{ic|MimeType}} key, it will not be considered when an application is needed to open that type. Edit [[#mimeapps.list|mimeapps.list]] to add an association between the .desktop file and the MIME type.<br />
<br />
=== Non-default application ===<br />
<br />
If the desktop entry is associated with the MIME type, it may simply not be set as the default. Edit [[#mimeapps.list|mimeapps.list]] to set the default association.<br />
<br />
=== Nonstandard association ===<br />
<br />
Applications are free to ignore or only partially implement the XDG standard. Check for usage of deprecated files such as {{ic|~/.local/share/applications/mimeapps.list}} and {{ic|~/.local/share/applications/defaults.list}}. If you are attempting to open the file from another application (e.g. a web browser or file manager) check if that application has its own method of selecting default applications.<br />
<br />
=== Variables in .desktop files that affect application launch ===<br />
<br />
{{Expansion|1=The fact {{ic|MimeType}} entries may be missing in the desktop files is only implied here, i.e. "Even if an application...", though this is a common cause of errors. Some openers may also associate mime types not explicitly listed in a desktop file (such as {{Pkg|exo}}). Further environment-specific factors are at play, e.g. whether {{ic|1=Terminal=true}} has an effect, though latter should arguably be expanded on in [[Desktop entries]].}}<br />
<br />
Desktop environments and file managers supporting the specifications launch programs according to definition in the ''.desktop'' files. See [[Desktop entries#Application entry]]. <br />
<br />
Usually, configuration of the packaged ''.desktop'' files is not required, but it may not be bug-free. Even if an application containing necessary MIME type description in the ''.desktop'' file {{ic|MimeType}} variable that is used for association, it can fail to start correctly, not start at all or start without opening a file. <br />
<br />
This may happen, for example, if the {{ic|Exec}} variable is missing internal options needed for how to open a file, or how the application is shown in the menu. The {{ic|Exec}} variable usually begins with {{ic|%}}; for its currently supported options, see [https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#exec-variables exec-variables].<br />
<br />
The following table lists the main variable entries of ''.desktop'' files that affect how an application starts, if it has a MIME type associated with it. <br />
<br />
{| class="wikitable"<br />
! Variable names !! Example 1 content !! Example 2 content !! Description<br />
|-<br />
| DBusActivatable || DBusActivatable=true || DBusActivatable=false || Application interact with [https://www.freedesktop.org/wiki/Software/dbus/ D-Bus]. <br> See also configuration: [https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus D-Bus].<br />
|-<br />
| MimeType || MimeType=application/vnd.oasis.opendocument.text || MimeType=application/vnd.sun.xml.math || List of MIME types supported by application<br />
|-<br />
| StartupWMClass || StartupWMClass=google-chrome || StartupWMClass=xpad || Associate windows with the owning application<br />
|-<br />
| Terminal || Terminal=true || Terminal=false || Start in default terminal<br />
|}</div>Edhhttps://wiki.archlinux.org/index.php?title=Netctl&diff=652505Netctl2021-02-15T13:23:21Z<p>Edh: Undo revision 652504 by Hatul (talk) There actually is a dedicated key for security called `wpa-configsection`; Considering this note explicitly states that `Security=wpa-config` shall not be used, I assume the original author really meant `Security=wpa-configsection` (i.e. this is not a spelling mistake)</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network managers]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[cs:Netctl]]<br />
[[de:Netctl]]<br />
[[es:Netctl]]<br />
[[fr:Netctl]]<br />
[[it:Netcfg]]<br />
[[ja:Netctl]]<br />
[[zh-hans:Netctl]]<br />
{{Related articles start}}<br />
{{Related|Bridge with netctl}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related articles end}}<br />
[https://projects.archlinux.org/netctl.git/ netctl] is a CLI and profile-based network manager and an Arch project.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|netctl}} package.<br />
<br />
''netctl's'' [[#Special systemd units]] used in automating connections require some additional dependencies; see that section for more information.<br />
<br />
Other optional dependencies are shown in the table below.<br />
<br />
{| class="wikitable"<br />
! Feature<br />
! Dependency<br />
|-<br />
| WPA || {{Pkg|wpa_supplicant}}<br />
|-<br />
| DHCP || {{Pkg|dhcpcd}} or {{Pkg|dhclient}}<br />
|-<br />
| ''wifi-menu'' || {{Pkg|dialog}}<br />
|-<br />
| PPPoE || {{Pkg|ppp}}<br />
|-<br />
|}<br />
<br />
{{Warning|Do not enable concurrent, conflicting network services. Use {{ic|1=systemctl --type=service}} to ensure that no other network service is running before enabling a ''netctl'' profile/service.}}<br />
<br />
== Configuration ==<br />
<br />
''netctl'' uses profiles to manage network connections and different modes of operation to start profiles automatically or manually on demand. <br />
<br />
The ''netctl'' profile files are stored in {{ic|/etc/netctl/}} and example configuration files are available in {{ic|/etc/netctl/examples/}}. <br />
<br />
To use an example profile, simply copy it from {{ic|/etc/netctl/examples/}} to {{ic|/etc/netctl/}} and configure it to your needs; see basic [[#Example profiles]] below. The first parameter you need to create a profile is the network {{ic|Interface}}, see [[Network configuration#Network interfaces]] for details.<br />
<br />
{{Tip|<br />
* For wireless settings, you can use {{ic|wifi-menu}} as root to generate the profile file in {{ic|/etc/netctl/}}. The {{pkg|dialog}} package is required to use ''wifi-menu''.<br />
* Use {{ic|1=SkipNoCarrier=yes}} in your profile to enable a static IP profile on a wired interface no matter if the cable is connected or not.<br />
}}<br />
<br />
See {{man|5|netctl.profile}} for a complete list of profile options.<br />
<br />
== Usage ==<br />
<br />
See {{man|1|netctl}} for a complete list of ''netctl'' commands.<br />
<br />
=== Starting a profile ===<br />
<br />
Once you have created your profile, attempt to establish a connection, where ''profile'' is only the profile name, not the full path:<br />
<br />
# netctl start ''profile''<br />
<br />
If the above command results in a failure, then use {{ic|journalctl -xn}} and {{ic|netctl status ''profile''}} to obtain a more in-depth explanation of the failure.<br />
<br />
=== Enabling a profile ===<br />
<br />
A profile can be enabled to start at boot by using:<br />
<br />
# netctl enable ''profile''<br />
<br />
This will create and enable a [[systemd]] service that will start when the computer boots. Changes to the profile file will not propagate to the service file automatically. After such changes, it is necessary to reenable the profile:<br />
<br />
# netctl reenable ''profile''<br />
<br />
After enabling a profile, it will be started at next boot. Obviously this can only be successful, if the network cable for a wired connection is plugged in, or the wireless access point used in a profile is in range respectively.<br />
<br />
If you need to switch multiple profiles frequently (i.e., traveling with a laptop), use [[#Special systemd units]] instead of enabling a profile.<br />
<br />
=== Special systemd units ===<br />
<br />
''netctl'' provides special [[systemd]] services for automatically switching of profiles for wired and wireless connections. See {{man|7|netctl.special}} for a complete list of special systemd units.<br />
<br />
==== Wired ====<br />
<br />
[[Install]] the {{Pkg|ifplugd}} package and [[start/enable]] the {{ic|netctl-ifplugd@''interface''.service}} systemd unit. DHCP profiles will be started/stopped when the network cable is plugged in/unplugged.<br />
* The {{ic|netctl-ifplugd@''interface''.service}} will prefer profiles that use [[Wikipedia:DHCP|DHCP]].<br />
* To automatically start a static IP profile the option {{ic|1=ExcludeAuto=no}} needs to be set in it.<br />
* To prioritize a profile with a static IP over DHCP profiles, you can set {{ic|1=Priority=2}}, which is higher than the default priority given to DHCP profiles of {{ic|1=Priority=1}}.<br />
<br />
==== Wireless ====<br />
<br />
[[Start/enable]] {{ic|netctl-auto@''interface''.service}} systemd unit. ''netctl'' profiles will be started/stopped automatically as you move from the range of one network into the range of another network (roaming).<br />
<br />
* Profiles must use {{ic|1=Security=wpa-configsection}} or {{ic|1=Security=wpa}} to work with ''netctl-auto'' rather than {{ic|1=Security=wpa-config}}.<br />
* If you want some wireless profile '''not''' to be started automatically by {{ic|netctl-auto@''interface''.service}}, you have to explicitly add {{ic|1=ExcludeAuto=yes}} to that profile. <br />
* You can use {{ic|1=priority=}} in the ''WPAConfigSection'' (see {{ic|/etc/netctl/examples/wireless-wpa-configsection}}) to set priority of a profile when multiple wireless access points are available. Larger numbers indicate a higher priority.<br />
<br />
Note that ''interface'' is not literal, but to be substituted by the name of your device's interface, e.g. {{ic|netctl-auto@wlp4s0.service}}. See {{ic|netctl.profile(5)}} for details.<br />
<br />
{{Note|<br />
* If any of the profiles contain errors, such as an empty or misquoted {{ic|1=Key=}} variable, the unit will fail to load with the message {{ic|"Failed to read or parse configuration '/run/network/wpa_supplicant_wlan0.conf'}}, even when that profile is not being used.<br />
* If you have previously [[#Enabling a profile|enabled a profile]] through ''netctl'', run {{ic|netctl disable ''profile''}} to prevent the profile from starting twice at boot.<br />
}}<br />
<br />
It is possible to manually control an interface otherwise managed by ''netctl-auto'' without having to stop {{ic|netctl-auto.service}}. This is done using the ''netctl-auto'' command. For a complete list of available actions see {{man|1|netctl-auto}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Example profiles ===<br />
<br />
==== Wired ====<br />
<br />
For a DHCP connection, only the {{ic|Interface}} has to be configured after copying the {{ic|/etc/netctl/examples/ethernet-dhcp}} example profile to {{ic|/etc/netctl}}. <br />
<br />
For example:<br />
{{hc|/etc/netctl/''my_dhcp_profile''|<nowiki><br />
Interface=enp1s0<br />
Connection=ethernet<br />
IP=dhcp</nowiki><br />
}}<br />
<br />
For a static IP configuration copy the {{ic|/etc/netctl/examples/ethernet-static}} example profile to {{ic|/etc/netctl}} and modify {{ic|Interface}}, {{ic|Address}}, {{ic|Gateway}} and {{ic|DNS}}) as needed. <br />
<br />
For example:<br />
{{hc|/etc/netctl/''my_static_profile''|<nowiki><br />
Interface=enp1s0<br />
Connection=ethernet<br />
IP=static<br />
Address=('10.1.10.2/24')<br />
Gateway='10.1.10.1'<br />
DNS=('10.1.10.1')</nowiki><br />
}}<br />
<br />
Take care to include the subnet notation of {{ic|/24}}. It equates to a netmask of {{ic|255.255.255.0}}) and without it the profile will fail to start. See also [[wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR notation]]. To alias more than one IP address per a NIC set {{ic|Address&#61;('10.1.10.2/24' '192.168.1.2/24')}}.<br />
<br />
==== Wireless (WPA-PSK) ====<br />
<br />
The following applies for the standard wireless connections using a pre-shared key (WPA-PSK).<br />
<br />
{{hc|/etc/netctl/wireless-wpa|2=<br />
Description='A simple WPA encrypted wireless connection using 256-bit PSK'<br />
Interface=wlp2s2<br />
Connection=wireless<br />
Security=wpa<br />
IP=dhcp<br />
ESSID=''your_essid''<br />
Key=\"64cf3ced850ecef39197bb7b7b301fc39437a6aa6c6a599d0534b16af578e04a<br />
}}<br />
<br />
{{Note|<br />
* Make sure to use the '''special quoting rules''' for the {{ic|Key}} variable as explained at the end of [https://github.com/joukewitteveen/netctl/blob/master/docs/netctl.profile.5.txt netctl.profile(5)].<br />
* If the passphrase fails, try removing the {{ic|\"}} in the {{ic|Key}} variable.<br />
* Although "encrypted", the key that you put in the profile configuration is enough to connect to a WPA-PSK network. Therefore this process is only useful for hiding the human-readable version of the passphrase. This will not prevent anyone with read access to this file from connecting to the network.}}<br />
<br />
=== Obfuscate wireless passphrase ===<br />
<br />
You can also follow the following step to obfuscate the wireless passphrase (''wifi-menu'' does it automatically when using the {{ic|-o}} flag): <br />
<br />
Users '''not''' wishing to have the passphrase to their wireless network stored in ''plain text'' have the option of storing the corresponding 256-bit pre-shared key instead, which is calculated from the passphrase and the SSID using standard algorithms.<br />
<br />
Calculate your 256-bit PSK using [[wpa_supplicant#Connecting with wpa passphrase|wpa_passphrase]]:<br />
{{hc|$ wpa_passphrase ''your_essid''|2=<br />
network={<br />
ssid="''your_essid''"<br />
#psk="''passphrase''"<br />
psk=64cf3ced850ecef39197bb7b7b301fc39437a6aa6c6a599d0534b16af578e04a<br />
}<br />
}}<br />
<br />
The ''pre-shared key'' (psk) now needs to replace the plain text passphrase of the {{ic|Key}} variable in the profile.<br />
<br />
=== Using an experimental GUI ===<br />
<br />
If you want a graphical user interface to manage ''netctl'' and your connections and you are not afraid of highly experimental unofficial packages, there are some options available. {{AUR|netctl-gui}} provides a Qt-based graphical interface, DBus daemon and KDE widget. {{AUR|netmenu}} uses {{Pkg|dmenu}} as its graphical interface, and {{AUR|gnome-shell-extension-netctl-auto-gnome-git}} is a gnome shell extension.<br />
<br />
There is also an application that displays desktop notifications on profile changes and shows a tray icon: {{AUR|netctl-tray}}.<br />
<br />
=== Bonding ===<br />
<br />
From [https://www.kernel.org/doc/html/latest/networking/bonding.html kernel documentation]:<br />
<br />
:The Linux bonding driver provides a method for aggregating multiple network interfaces into a single logical "bonded" interface. The behavior of the bonded interfaces depends on the mode. Generally speaking, modes provide either hot standby or load balancing services. Additionally, link integrity monitoring may be performed.<br />
<br />
==== Load balancing ====<br />
<br />
To use bonding with netctl, additional package from official repositories is required: {{Pkg|ifenslave}}.<br />
<br />
Copy {{ic|/etc/netctl/examples/bonding}} to {{ic|/etc/netctl/bond0}} and edit it, for example:<br />
<br />
{{hc|/etc/netctl/bond0|2=<br />
Description='Bond Interface'<br />
Interface='bond0'<br />
Connection=bond<br />
BindsToInterfaces=('eth0' 'eth1')<br />
IP=dhcp<br />
IP6=stateless}}<br />
<br />
Now you can disable your old configuration and set ''bond0'' to be started automatically. Switch to the new profile, for example:<br />
<br />
# netctl switch-to bond0<br />
<br />
{{Note|This uses the round-robin policy, which is the default for the {{ic|bonding}} driver. See [https://www.kernel.org/doc/html/latest/networking/bonding.html official documentation] for details. }}<br />
<br />
Setting the MODE in the netctl configuration is not always successful and it may be necessary to pass options directly to the bonding module on load as noted [https://bbs.archlinux.org/viewtopic.php?id=203255 here]. This may be needed to use LACP / mode 4.<br />
<br />
{{Tip|To check the status and bonding mode: {{bc|$ cat /proc/net/bonding/bond0}}}}<br />
<br />
==== Wired to wireless failover ====<br />
<br />
This example describes how to use ''bonding'' to fallback to wireless when the wired ethernet goes down. This is most useful when both the wired and wireless interface will be connected to the same network. Your wireless router/access point must be configured in [[bridge]] mode.<br />
<br />
You will need additional packages from the official repositories: {{Pkg|ifenslave}} and {{Pkg|wpa_supplicant}}.<br />
<br />
First enable the bonding module to be loaded upon boot time, as instructed on [[Kernel modules#Automatic module loading with systemd]]:<br />
<br />
{{hc|/etc/modules-load.d/bonding.conf|2=<br />
bonding<br />
}}<br />
<br />
Then, configure the options of the {{ic|bonding}} driver to use {{ic|active-backup}} and configure the {{ic|primary}} parameter to the device you want to be the active one (normally the wired interface). Also, be sure to use the same device name as returned when running {{ic|ip link}}:<br />
<br />
{{hc|/etc/modprobe.d/bonding.conf|2=<br />
options bonding mode=active-backup miimon=100 primary=eth0 max_bonds=0<br />
}}<br />
<br />
The {{ic|miimon}} option is needed, for the link failure detection. The {{ic|max_bonds}} option avoids the {{ic|Interface bond0 already exists}} error. More information can be obtained on the [https://www.kernel.org/doc/html/latest/networking/bonding.html kernel documentation].<br />
<br />
Next, configure a netctl profile to enslave the two hardware interfaces. Use the name of all the devices you want to enslave. If you have more than two wired or wireless interfaces, you can enslave all of them on a bond interface. But, for most cases you will have only two devices, a wired and a wireless one:<br />
<br />
{{hc|/etc/netctl/failover|2=<br />
Description='A wired connection with failover to wireless'<br />
Interface='bond0'<br />
Connection=bond<br />
BindsToInterfaces=('eth0' 'wlan0')<br />
IP='dhcp'<br />
}}<br />
<br />
Disable any other profiles (specially a wired or wireless) you had enabled before and then enable the failover profile on startup:<br />
<br />
# netctl enable failover<br />
<br />
Now you need to configure ''wpa_supplicant'' to connect to any known network you wish. You should create a file for each interface and enable it on systemd. Create the following file with this content:<br />
<br />
{{hc|/etc/wpa_supplicant/wpa_supplicant-wlan0.conf|2=<br />
ctrl_interface=/run/wpa_supplicant<br />
update_config=1<br />
}}<br />
<br />
And append to the end of this file any network you want to connect to: <br />
<br />
network={<br />
ssid="SSID"<br />
psk=PSK<br />
}<br />
<br />
To generate the obfuscated PSK you can run ''wpa_passphrase'' as on the [[wpa_supplicant#Connecting with wpa_passphrase]] page.<br />
<br />
Now, [[enable]] the {{ic|wpa_supplicant@}} template service on the network interface, for example {{ic|wpa_supplicant@wlan0}}.<br />
<br />
You can try now to reboot your machine and see if your configuration worked.<br />
<br />
{{Note|If you get this error on boot bonding:<br />
<br />
wlan0 is up - this may be due to an out of date ifenslave<br />
<br />
Then this is happening because the ''wpa_supplicant'' is being run before the {{ic|failover}} netctl profile. This happens because [[systemd]] runs everything in parallel, unless told otherwise. ''ifenslave'' need all the interfaces to be down before bonding them to the {{ic|bond0}} interface. And, since the ''wpa_supplicant'' need to put the interface up to be able to scan for networks, this might cause the interface to not be enslaved and your bonding to only have the wired interface.<br />
<br />
If this is your case, then you will need to setup a custom dependency on the {{ic|wpa_supplicant@wlan0}} service in relation with the {{ic|netctl@failover}} profile. More specifically, the ''wpa_supplicant'' must be started '''after''' the netctl profile. To accomplish this, create a custom dependency file based on the instructions provided here: [[systemd#Handling dependencies]]<br />
<br />
{{hc|/etc/systemd/system/wpa_supplicant@wlan0.service.d/customdependency.conf|2=<br />
[Unit]<br />
After=netctl@failover.service<br />
}}<br />
<br />
After that you can try to reboot your system again and see if it works. You can check the status of your bonding by checking [[journalctl]] for the {{ic|netctl@failover.service}} unit.<br />
<br />
And by checking:<br />
<br />
# ip link<br />
<br />
You should see something like this:<br />
<br />
1: eth0: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP mode DEFAULT group default qlen 1000<br />
link/ether xx:xx:xx:xx:xx:xx brd ff:ff:ff:ff:ff:ff<br />
2: wlan0: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc mq master bond0 state UP mode DORMANT group default qlen 1000<br />
link/ether xx:xx:xx:xx:xx:xx brd ff:ff:ff:ff:ff:ff<br />
3: bond0: <BROADCAST,MULTICAST,MASTER,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default <br />
link/ether xx:xx:xx:xx:xx:xx brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
Now, you can test your failover setup, by initiating a big download. Unplug your wired interface. Your download should keep going over the wireless interface. Then, plug your wired interface again and it should keep working. You can debug by checking [[journalctl]] for the {{ic|netctl@failover.service}} and {{ic|wpa_supplicant@wlan0.service}} units.<br />
<br />
=== Using any interface ===<br />
In some cases it may be desirable to allow a profile to use any interface on the system. A common example use case is using a common disk image across many machines with differing hardware (this is especially useful if they are headless). If you use the kernel's naming scheme, and your machine has only one ethernet interface, you can probably guess that eth0 is the right interface. If you use udev's [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/ Predictable Network Interface Names], however, names will be assigned based on the specific hardware itself (e.g. enp1s0), rather than simply the order that the hardware was detected (e.g. eth0, eth1). This means that a netctl profile may work on one machine and not another, because they each have different interface names.<br />
<br />
A quick and dirty solution is to make use of the {{ic|/etc/netctl/interfaces/}} directory. Choose a name for your interface alias ({{ic|en-any}} in this example), and write the following to a file with that name (making sure it is executable).<br />
{{hc|/etc/netctl/interfaces/en-any|<nowiki><br />
#!/bin/bash<br />
for interface in /sys/class/net/en*; do<br />
break;<br />
done<br />
Interface=$(basename $interface)<br />
echo "en-any: using interface $Interface";<br />
</nowiki>}}<br />
Then create a profile that uses the interface. Pay special attention to the {{ic|Interface}} directive. The rest are only provided as examples.<br />
{{hc|/etc/netctl/wired|<nowiki><br />
Description='Wired'<br />
Interface=en-any<br />
Connection=ethernet<br />
IP=static<br />
Address=('192.168.1.15/24')<br />
Gateway='192.168.1.1'<br />
DNS=('192.168.1.1')<br />
</nowiki>}}<br />
<br />
When the {{ic|wired}} profile is started, any machine using the two files above will automatically bring up and configure the first ethernet interface found on the system, regardless of what name udev assigned to it. Note that this is not the most robust way to go about configuring interfaces. If you use multiple interfaces, netctl may try to assign the same interface to them, and will likely cause a disruption in connectivity. If you do not mind a more complicated solution, {{ic|netctl-auto}} is likely to be more reliable.<br />
<br />
=== Using hooks ===<br />
<br />
netctl supports hooks in {{ic|/etc/netctl/hooks/}} and per interface hooks in {{ic|/etc/netctl/interfaces/}}. You can set any option in a hook/interface that you can<br />
in a profile. Most importantly this includes {{ic|ExecUpPost}} and {{ic|ExecDownPre}}. <br />
<br />
When a profile is read, netctl sources '''all executable''' scripts in {{ic|hooks}}, then it reads the profile file for the connection and finally it sources an executable script with the name of the interface used in the profile from the {{ic|interfaces}} directory. Therefore, declarations in an interface script override declarations in the profile, which override declarations in hooks. <br />
<br />
The variables {{ic|$INTERFACE}} and {{ic|$ACTION}} are available in hooks/interfaces '''only''' when using {{ic|netctl-auto}} <br />
<br />
==== Examples ====<br />
<br />
===== Execute commands on established connection =====<br />
{{hc|/etc/netctl/hooks/myservices|<nowiki><br />
#!/bin/sh<br />
ExecUpPost="systemctl start crashplan.service; systemctl start dropbox@<username>.service"<br />
ExecDownPre="systemctl stop crashplan.service; systemctl stop dropbox@<username>.service"<br />
</nowiki>}}<br />
<br />
===== Set default DHCP client =====<br />
<br />
To set or change the DHCP client used for all profiles: <br />
<br />
{{hc|/etc/netctl/hooks/dhcp|<nowiki><br />
#!/bin/sh<br />
DHCPClient='dhclient'<br />
</nowiki>}}<br />
<br />
Alternatively, it may also be specified for a specific network interface by creating an executable file {{ic|/etc/netctl/interfaces/<interface>}} with the following line:<br />
<br />
DHCPClient='dhclient'<br />
<br />
{{Expansion|It would be useful to replace the example with a general hook that executes different actions depending on {{ic|$ACTION}} being CONNECT and DISCONNECT.}}<br />
<br />
=== Minimal WPAConfigSection ===<br />
As stated in the [https://projects.archlinux.org/netctl.git/tree/docs/netctl.profile.5.txt#n281 netctl.profile(5)] man page, the {{ic|WPAConfigSection}} variable is an array of config lines passed to [[wpa_supplicant]]. So, a minimal WPAConfigSection would contain:<br />
Description='A wireless connection using a custom network block configuration'<br />
Interface=wlan0<br />
Connection=wireless<br />
Security=wpa-configsection<br />
IP=dhcp<br />
WPAConfigSection=(<br />
'ssid="University"'<br />
'psk="very secret passphrase"'<br />
)<br />
<br />
{{Note|If trying to connect to an SSID with non-ASCII characters (unicode, emoji, etc), you can specify the SSID as hex instead of as a string, e.g. {{ic|1=ssid=F09F90BA}} for "🐺". When unsure on the hex encoding, run ''wifi-menu'' (be sure to remove the \ and x characters).}}<br />
<br />
=== resolv.conf ===<br />
<br />
If you use {{ic|DNS*}} options in your profile, ''netctl'' calls [[resolvconf]] to overwrite [[resolv.conf]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Job for netctl@wlan(...).service failed ===<br />
<br />
{{Warning|This section assumes that there is no other network service running before starting a ''netctl'' profile/service. See [[#Installation]] for details.}}<br />
<br />
Some people have an issue when they connect to a network with ''netctl'', for example:<br />
<br />
{{hc|# netctl start wlan0-ssid|<nowiki><br />
Job for netctl@wlan0\x2ssid.service failed. See 'systemctl status netctl@wlan0\x2ssid.service' and 'journalctl -xn' for details.<br />
</nowiki>}}<br />
<br />
When then looking at {{ic|journalctl -xn}}, either of the following are shown:<br />
<br />
1. If your device ({{ic|wlan0}} in this case) is up:<br />
network[2322]: The interface of network profile 'wlan0-ssid' is already up<br />
<br />
Setting the interface down should resolve the problem:<br />
# ip link set wlan0 down<br />
<br />
Then retry:<br />
# netctl start wlan0-ssid<br />
<br />
2. If the error continues, try again after adding the {{ic|ForceConnect}} option:<br />
<br />
{{hc|/etc/netctl/wlan0-ssid|<nowiki><br />
...<br />
ForceConnect=yes<br />
</nowiki>}}<br />
<br />
Save it and try to connect with the profile:<br />
# netctl start wlan0-ssid<br />
<br />
=== dhcpcd: ipv4_addroute: File exists ===<br />
<br />
On some systems dhcpcd in combination with netctl causes timeout issues on resume, particularly when having switched networks in the meantime. netctl will report that you are successfully connected but you still receive timeout issues. In this case, the old default route still exists and is not being renewed. A workaround to avoid this misbehaviour is to switch to [[#Set default DHCP client|dhclient]] as the default dhcp client. More information on the issue can be found [https://bbs.archlinux.org/viewtopic.php?pid=1399842#p1399842 here].<br />
<br />
=== DHCP timeout issues ===<br />
<br />
If you are having timeout issues when requesting leases via DHCP you can set the timeout value higher than netctl's 30 seconds by default. Create a file in {{ic|/etc/netctl/hooks/}} or {{ic|/etc/netctl/interfaces/}}, add {{ic|1=TimeoutDHCP=40}} to it for a timeout of 40 seconds and make the file executable.<br />
<br />
=== dhcpcd debugging ===<br />
<br />
If dhcpcd fails to obtain an address, add the {{ic|-d}} option to {{ic|/usr/lib/netctl/dhcp}} and then use {{ic|journalctl -xe}} to view the debugging messages which may indicate, for example, that the IP address offered by the server is rejected by the client after detecting that the IP address is already in use.<br />
<br />
=== Connection timeout issues ===<br />
<br />
If you are having timeout issues that are unrelated to DHCP (on a static ethernet connection for example), and are experiencing errors similar to the following when starting your profile:<br />
{{hc|# journalctl _SYSTEMD_UNIT&#61;netctl@''profile''.service|<br />
Starting network profile &#39;''profile''&#39;...<br />
No connection found on interface 'eth0' (timeout)<br />
Failed to bring the network up for profile &#39;''profile''&#39;<br />
}}<br />
Then you should increase carrier and up timeouts by adding {{ic|1=TimeoutUp=}} and {{ic|1=TimeoutCarrier=}} to your profile file:<br />
{{hc|/etc/netctl/''profile''|<nowiki><br />
...<br />
TimeoutUp=300<br />
TimeoutCarrier=300</nowiki><br />
}}<br />
Do not forget to reenable your profile:<br />
<br />
# netctl reenable ''profile''<br />
<br />
=== Problems with netctl-auto on resume ===<br />
Sometimes ''netctl-auto'' fails to reconnect when the system resumes from suspend, hibernate or hybrid-sleep. An easy solution is to restart the service for ''netctl-auto''. <br />
This can be automated with an additional service like the following ({{Aur|netctl-auto-resume}}):<br />
<br />
{{hc|/etc/systemd/system/netctl-auto-resume@.service|<nowiki><br />
[Unit]<br />
Description=restart netctl-auto on resume.<br />
Requisite=netctl-auto@%i.service<br />
After=sleep.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/systemctl restart netctl-auto@%i.service<br />
<br />
[Install]<br />
WantedBy=sleep.target<br />
</nowiki>}}<br />
<br />
To [[enable]] this service for your wireless card, for example, enable {{ic|netctl-auto-resume@wlan0.service}} as root. Change {{ic|wlan0}} to the required network interface.<br />
<br />
If the device is not yet running on resume when the unit is started, this will fail. It can be fixed by adding the following dependency in the ''After'' line:<br />
<br />
{{hc|/etc/systemd/system/netctl-auto-resume@.service|<nowiki><br />
...<br />
After=sleep.target sys-subsystem-net-devices-%i.device<br />
...<br />
</nowiki>}}<br />
<br />
=== netctl-auto does not automatically unblock a wireless card to use an interface ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by the kernel. This can be handled by [[rfkill]].<br />
<br />
If you want ''netctl-auto'' to automatically unblock your wireless card to connect to a particular network, set {{ic|1=RFKill=++auto++}} option for the wireless connection of your choice, as specified in the [https://github.com/joukewitteveen/netctl/blob/master/docs/netctl.profile.5.txt netctl.profile(5)] man page.<br />
<br />
=== RTNETLINK answers: File exists (with multiple NICs) ===<br />
<br />
This is a very misleading response, it really means that you have assigned a default gateway in an earlier netctl control file. When netctl starts up the n-th NIC and goes to set its local route, it fails because there is already a default route from n-1.<br />
<br />
Remove it and everything works, except you no longer have a default route and so cannot access things such as the internet. {{ic|ExecUpPost}} does not work as it gets executed for each network card.<br />
<br />
A possible solution is creating a new service. Replace "FIRST_INTERFACE" and "SECOND_INTERFACE" with your interface names, and replace "192.168.xxx.yyy" with your default gateway.<br />
<br />
{{hc|/etc/systemd/system/defaultrouter.service|<nowiki><br />
[Unit]<br />
Description="Configure default gateway"<br />
Requires=netctl@FIRST_INTERFACE.service netctl@SECOND_INTERFACE.service<br />
After=netctl@FIRST_INTERFACE.service netctl@SECOND_INTERFACE.service<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/ip route add default via 192.168.xxx.yyy<br />
<br />
[Install]<br />
WantedBy=network-online.target<br />
</nowiki>}}<br />
<br />
=== Problems with eduroam and other MSCHAPv2 connections ===<br />
<br />
See [[wpa_supplicant#Problems with eduroam and other MSCHAPv2 connections]].<br />
<br />
=== Journal warnings for profiles using .include directives ===<br />
<br />
Profiles still using systemd's old {{ic|.include}} directives will produce journal warnings, for example:<br />
systemd[1]: /etc/systemd/system/netctl@<profile>.service:1: .include directives are deprecated, and support for them will be removed in a future version of systemd. Please use drop-in files instead.<br />
<br />
See {{Bug|59494}} for details.<br />
<br />
Executing<br />
netctl reenable ''profile''<br />
will update the profile to the new [[drop-in unit file]] format.<br />
<br />
=== Hooks do not work ===<br />
<br />
If you have multiple hooks in {{ic|/etc/netctl/hooks/}}, variables like {{ic|ExecUpPost}} and {{ic|ExecDownPre}} will be executed only from one file. To fix this, define the variables like this:<br />
<br />
{{hc|/etc/netctl/hooks/test|<nowiki><br />
ExecUpPost="some command ; "$ExecUpPost<br />
ExecDownPre="some command ; "$ExecDownPre<br />
</nowiki>}}<br />
<br />
This will append your commands to be executed with already defined ones.<br />
<br />
== See also ==<br />
<br />
* [https://lists.archlinux.org/pipermail/arch-projects/2012-December/003473.html Initial mailing list announcement]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=157670 Official announcement thread]<br />
* [https://archlinux.org/news/netctl-is-now-in-core/ Official news announcement]</div>Edhhttps://wiki.archlinux.org/index.php?title=PipeWire&diff=651919PipeWire2021-02-11T11:14:25Z<p>Edh: Undo revision 651916 by Harmathy (talk): Remove section on merging configurations files as this is a common system maintenance task and not specific to pipewire; Furthermore, configs should be merged not simply overridden; Additionally, it is not necessary to use `sudo` to do stuff as root</p>
<hr />
<div>[[Category:Multimedia]]<br />
[[fi:PipeWire]]<br />
[[ja:PipeWire]]<br />
{{Related articles start}}<br />
{{Related|PipeWire/Examples}}<br />
{{Related articles end}}<br />
<br />
[http://pipewire.org PipeWire] is a new multimedia framework by GNOME. The main developer is Wim Taymans.<br />
<br />
PipeWire supports containers like [[Flatpak]] and does not rely on [[user group]]s ''audio'' and ''video'', but rather uses a [[Polkit]]-like security model asking Flatpak or Wayland for permission to record screen or audio.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{pkg|pipewire}} package from the official repositories.<br />
<br />
Pipewire uses [[Systemd/User]] for management of the server and automatic socket activation. See the respective [[Systemd/User]] for more details on the startup behavior and logging of the service.<br />
<br />
Optionally, install {{pkg|pipewire-docs}} to review the documentation. Other packages, such as {{pkg|pipewire-alsa}}, {{pkg|pipewire-pulse}}, and {{pkg|pipewire-jack}} are normally not needed unless one wants to [[#Audio|use PipeWire as a PulseAudio/JACK replacement]]. Also available are {{aur|lib32-pipewire}}, {{aur|lib32-pipewire-pulse-git}}{{Broken package link|package not found}}, and {{aur|lib32-pipewire-jack}} for multilib support.<br />
<br />
== Usage ==<br />
<br />
=== WebRTC screen sharing ===<br />
<br />
Most browsers used to rely on X11 for capturing the desktop (or individual applications) when using WebRTC (e.g. on Google Hangouts). On Wayland, the sharing mechanism is handled differently for security reasons. PipeWire enables sharing content under Wayland with fine-grained access controls.<br />
<br />
This requires {{Pkg|xdg-desktop-portal}} and one of its backends [http://jgrulich.cz/2018/07/04/how-to-enable-and-use-screen-sharing-on-wayland to be installed]. The available backends are:<br />
<br />
* {{Pkg|xdg-desktop-portal-gtk}} for GNOME.<br />
* {{Pkg|xdg-desktop-portal-kde}} for KDE.<br />
* {{Pkg|xdg-desktop-portal-wlr}} for Wlroots-based compositor (e.g. [[Sway]], dwl)<br />
<br />
Firefox (84+) supports this method by default, while on Chromium (73+) one needs to enable [https://bugs.chromium.org/p/chromium/issues/detail?id=682122 WebRTC PipeWire support] by setting the corresponding (experimental) flag at the following URL<br />
chrome://flags/#enable-webrtc-pipewire-capturer<br />
<br />
For {{ic|xdg-desktop-portal-wlr}} to work you need to set {{ic|XDG_CURRENT_DESKTOP}}[https://github.com/emersion/xdg-desktop-portal-wlr#running]:<br />
export XDG_CURRENT_DESKTOP=sway<br />
<br />
Note, since Chromium is currently using PipeWire 0.2 whereas Arch ships PipeWire 0.3, you also need to install {{Pkg|libpipewire02}} for screen sharing to work.<br />
<br />
{{Tip|To share an individual monitor with {{ic|xdg-desktop-portal-wlr}} if you have more than one, you can add the {{ic|1=--output=''Monitor''}} flag to it by [[Systemd#Editing_provided_units|editing]] the {{ic|1=ExecStart=}} option in the unit's service file. The complete line could look like {{ic|1=ExecStart=@libexecdir@/xdg-desktop-portal-wlr --output=eDP-1}}}}<br />
<br />
{{Accuracy|Since [https://github.com/flatpak/xdg-desktop-portal-gtk/pull/225 this pull request] was merged, the following note about specific app/window sharing may be not correct anymore for {{Pkg|xdg-desktop-portal-gtk}}. Also see the ticket tracking the discussion at [https://github.com/flatpak/xdg-desktop-portal-gtk/issues/204].}}<br />
<br />
Note that the only supported feature is sharing the entire desktop and not a specific app/window [https://github.com/emersion/xdg-desktop-portal-wlr/wiki/FAQ#will-this-let-me-share-individual-windows][https://github.com/KDE/xdg-desktop-portal-kde/blob/master/TODO].<br />
<br />
=== Video ===<br />
<br />
Although the software is not yet production-ready, it is safe to play around with. Most applications that rely on [[GStreamer]] to handle e.g. video streams should work out-of-the-box thanks to the PipeWire GStreamer plugin. Applications like e.g. {{pkg|cheese}} are therefore already able to share video input using it.<br />
<br />
=== Audio ===<br />
<br />
PipeWire can be used as an audio server, similar to PulseAudio and JACK. It aims to replace both PulseAudio and JACK, by providing a PulseAudio-compatible server implementation and ABI-compatible libraries for JACK clients. See [https://blogs.gnome.org/uraeus/2020/09/04/pipewire-late-summer-update-2020/ this blog entry] for more information.<br />
<br />
==== ALSA/Legacy applications ====<br />
<br />
Install {{pkg|pipewire-alsa}} to route all application using the ALSA API through PipeWire.<br />
<br />
==== PulseAudio clients ====<br />
<br />
Install {{pkg|pipewire-pulse}}. Normally, no further action is needed, as the user service {{ic|pipewire-pulse.socket}} should be enabled automatically by the package. If PipeWire does not work correctly on system startup, validate that the user services {{ic|pipewire-pulse.service}} and {{ic|pipewire.service}} are up and running. See [[Systemd/User]].<br />
<br />
Reboot or re-login to see the effect.<br />
<br />
To check if the replacement is working, run the following command and see the output:<br />
<br />
{{hc|1=$ pactl info|2=<br />
...<br />
Server Name: PulseAudio (on PipeWire 0.3.16)<br />
...<br />
}}<br />
<br />
==== JACK clients ====<br />
<br />
Install {{pkg|pipewire-jack}} and use {{ic|pw-jack}} to launch JACK clients with the compatible libraries instead of the original {{ic|libjack*}}:<br />
<br />
pw-jack ''application''<br />
<br />
Alternatively, install {{aur|pipewire-jack-dropin}} to let JACK clients load the compatible libraries automatically.<br />
<br />
Use {{ic|ldd}} to verify that the JACK application links to the correct library:<br />
<br />
{{hc|1=$ ldd /usr/bin/qjackctl {{!}} grep -i libjack|2=<br />
libjack.so.0 => /usr/lib/pipewire-0.3/jack/libjack.so.0 (0x00007f7e5080a000)<br />
}}<br />
<br />
==== Bluetooth devices ====<br />
<br />
PipeWire handles Bluetooth audio devices if the {{pkg|pipewire-pulse}} package is installed. More specifically, the media session daemon checks for {{ic|/etc/pipewire/media-session.d/with-pulseaudio}}, and enables its {{ic|bluez5}} module automatically if the file exists.<br />
<br />
==== Run PipeWire on top of native JACK ====<br />
<br />
PipeWire can also run as a JACK client on top of the native JACK daemon if desired. See [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/JACK JACK and PipeWire] for more information.<br />
<br />
== Troubleshooting ==<br />
=== Microphone is not detected by PipeWire ===<br />
<br />
PipeWire's {{ic|alsa-monitor}} module uses {{pkg|alsa-card-profiles}} to detect devices by default. If this isn't working for you, try to turn off {{ic|api.alsa.use-acp}}, or optionally turn on {{ic|api.alsa.use-ucm}} in {{ic|/etc/pipewire/media-session.d/alsa-monitor.conf}}, under {{ic|rules}} -> the first rule -> {{ic|actions}} -> {{ic|update-props}}:<br />
<br />
...<br />
update-props = {<br />
api.alsa.use-acp = false<br />
...<br />
<br />
Then, restart pipewire and check available devices:<br />
<br />
{{hc|1=<br />
$ pw-record --list-targets<br />
|2=<br />
Available targets ("*" denotes default): 62<br />
58: description="Built-in Audio" prio=1872<br />
60: description="Built-in Audio" prio=2000<br />
* 62: description="Built-in Audio (Loopback PCM)" prio=1984<br />
}}<br />
<br />
=== No sound after connecting to Bluetooth device ===<br />
<br />
As of 2020-12-07, if there is no sound after connecting a Bluetooth device, you might need to switch the default sink and/or move a sink input to the correct sink. Use {{ic|pactl set-default-sink}} to set the sink and {{ic|pactl list sinks}} to list the available ones. This can be automated via [[udev]] using a script similar to [https://gist.github.com/tinywrkb/04e7fd644afa9b92d33a3a99ab07ee9e this one].<br />
<br />
See this [https://www.reddit.com/r/archlinux/comments/jydd02/pipewirepulse_03164_in_testing_now_replaces/gd3m7fu/?context=3 Reddit thread] for a discussion of the issue. According to author of the script, the headset profile (HSP) might still have problems.<br />
<br />
=== Low volume ===<br />
<br />
After replacing PulseAudio with Pipewire, sound worked fine, but after a reboot, the volume was intolerably low.<br />
<br />
Open {{ic|alsamixer}}, use {{ic|F6}} to select the proper soundcard, and make sure the ALSA volumes are at 100%. {{ic|alsactl}} should maintain this setting after reboot.<br />
<br />
=== Increasing RLIMIT_MEMLOCK ===<br />
<br />
Dec 13 11:11:11 HOST pipewire-pulse[99999]: Failed to mlock memory 0x7f4f659d8000 32832: This is not a problem but for best performance, consider increasing RLIMIT_MEMLOCK<br />
<br />
Install {{pkg|realtime-privileges}} and add your own user to the {{ic|realtime}} group.<br />
<br />
Alternatively, increasing memlock from 64kB to 128kB seems enough to fix this. If you are running {{ic|pipewire-pulse}} under [[systemd/User]], add:<br />
<br />
username soft memlock 64<br />
username hard memlock 128<br />
<br />
to {{ic|/etc/security/limits.d/username.conf}}, and:<br />
<br />
LimitMEMLOCK=131072<br />
<br />
to {{ic|pipewire-pulse.service}}.<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home Wiki] — PipeWire Wiki on Freedesktop GitLab<br />
* [https://blogs.gnome.org/uraeus/2018/01/26/an-update-on-pipewire-the-multimedia-revolution-an-update/ Pipewire Update Blog Post] — Blog post from January 2018 outlining the state of PipeWire at the time<br />
* [https://blogs.gnome.org/uraeus/2020/09/04/pipewire-late-summer-update-2020/ PipeWire Late Summer Update 2020] — Blog post from September 2020</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651874WireGuard2021-02-10T22:14:28Z<p>Edh: /* Server config */ Replace quotes by ic tags to highlight the netmask</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
For recent kernels (≥ 5.6) and if using [[#systemd-networkd|systemd-networkd]] or [[#NetworkManager|NetworkManager]] as network manager, no additional tools are required to set up a WireGuard interface. Else, [[install]] {{Pkg|wireguard-tools}}.<br />
<br />
If using an older Linux kernel additionally install the appropriate kernel module:<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer. If connecting dozens of peers optionally consider a vanity keypair to personalize the Base64 encoded public key string. See [[#Vanity keys]].<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
To connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on {{ic|51820/UDP}}).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, {{ic|51820/UDP}}) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of {{ic|/24}} and the clients on {{ic|AllowedIPs}} {{ic|/32}}. The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651873WireGuard2021-02-10T22:13:25Z<p>Edh: /* Server */ Put ic tags around UDP port numbers</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
For recent kernels (≥ 5.6) and if using [[#systemd-networkd|systemd-networkd]] or [[#NetworkManager|NetworkManager]] as network manager, no additional tools are required to set up a WireGuard interface. Else, [[install]] {{Pkg|wireguard-tools}}.<br />
<br />
If using an older Linux kernel additionally install the appropriate kernel module:<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer. If connecting dozens of peers optionally consider a vanity keypair to personalize the Base64 encoded public key string. See [[#Vanity keys]].<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
To connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on {{ic|51820/UDP}}).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, {{ic|51820/UDP}}) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of "/24" and the clients on {{ic|AllowedIPs}} "/32". The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651872WireGuard2021-02-10T22:10:48Z<p>Edh: /* Installation */ Shorten introduction</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
For recent kernels (≥ 5.6) and if using [[#systemd-networkd|systemd-networkd]] or [[#NetworkManager|NetworkManager]] as network manager, no additional tools are required to set up a WireGuard interface. Else, [[install]] {{Pkg|wireguard-tools}}.<br />
<br />
If using an older Linux kernel additionally install the appropriate kernel module:<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer. If connecting dozens of peers optionally consider a vanity keypair to personalize the Base64 encoded public key string. See [[#Vanity keys]].<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
To connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of "/24" and the clients on {{ic|AllowedIPs}} "/32". The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651870WireGuard2021-02-10T22:08:37Z<p>Edh: /* Installation */ Fix kernel version in which wireguard was added</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
For recent kernels (≥ 5.6) and if using [[#systemd-networkd|systemd-networkd]] or [[#NetworkManager|NetworkManager]] as network manager, no additional tools are required as they both have native support for setting up WireGuard interfaces. Else, [[install]] {{Pkg|wireguard-tools}}.<br />
<br />
If using an older Linux kernel additionally install the appropriate kernel module:<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer. If connecting dozens of peers optionally consider a vanity keypair to personalize the Base64 encoded public key string. See [[#Vanity keys]].<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
To connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of "/24" and the clients on {{ic|AllowedIPs}} "/32". The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651868WireGuard2021-02-10T22:01:18Z<p>Edh: /* Site-to-site */ Fix spelling</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
For recent kernels (≥ 5.7) and if using [[#systemd-networkd|systemd-networkd]] or [[#NetworkManager|NetworkManager]] as network manager, no additional tools are required as they both have native support for setting up WireGuard interfaces. Else, [[install]] {{Pkg|wireguard-tools}}.<br />
<br />
If using an older Linux kernel additionally install the appropriate kernel module:<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer. If connecting dozens of peers optionally consider a vanity keypair to personalize the Base64 encoded public key string. See [[#Vanity keys]].<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
To connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of "/24" and the clients on {{ic|AllowedIPs}} "/32". The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651866WireGuard2021-02-10T21:58:40Z<p>Edh: /* Key generation */ Convert tip environment to plain text; To give the reader a better feeling for what to expect from a "vanity keypair", describe the term a little more verbosely</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
For recent kernels (≥ 5.7) and if using [[#systemd-networkd|systemd-networkd]] or [[#NetworkManager|NetworkManager]] as network manager, no additional tools are required as they both have native support for setting up WireGuard interfaces. Else, [[install]] {{Pkg|wireguard-tools}}.<br />
<br />
If using an older Linux kernel additionally install the appropriate kernel module:<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer. If connecting dozens of peers optionally consider a vanity keypair to personalize the Base64 encoded public key string. See [[#Vanity keys]].<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
For connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of "/24" and the clients on {{ic|AllowedIPs}} "/32". The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651865WireGuard2021-02-10T21:47:09Z<p>Edh: /* Installation */ Reword</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
For recent kernels (≥ 5.7) and if using [[#systemd-networkd|systemd-networkd]] or [[#NetworkManager|NetworkManager]] as network manager, no additional tools are required as they both have native support for setting up WireGuard interfaces. Else, [[install]] {{Pkg|wireguard-tools}}.<br />
<br />
If using an older Linux kernel additionally install the appropriate kernel module:<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer.<br />
<br />
{{Tip|Optionally consider a vanity keypair. See [[#Vanity keys]].}}<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
For connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of "/24" and the clients on {{ic|AllowedIPs}} "/32". The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651864WireGuard2021-02-10T21:45:04Z<p>Edh: /* Installation */ Compactify</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
For recent kernels (≥ 5.7) and if using [[#systemd-networkd|systemd-networkd]] or [[#NetworkManager|NetworkManager]] as network manager, no installation of additional tools is required as they both have native support for setting up WireGuard interfaces. Else, [[install]] {{Pkg|wireguard-tools}} and for Linux kernels < 5.6 additionally install the appropriate kernel module:<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer.<br />
<br />
{{Tip|Optionally consider a vanity keypair. See [[#Vanity keys]].}}<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
For connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of "/24" and the clients on {{ic|AllowedIPs}} "/32". The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651863WireGuard2021-02-10T21:43:40Z<p>Edh: /* Installation */ Make it more explicit that systemd-networkd and NetworkManager do not need additional tools to create wireguard interfaces</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
For recent kernels (≥ 5.7) and if using [[#systemd-networkd|systemd-networkd]] or [[#NetworkManager|NetworkManager]] as network manager, no installation of additional tools is required as they both have native support for setting up WireGuard interfaces.<br />
<br />
# [[Install]] {{Pkg|wireguard-tools}}. <br />
# For Linux kernels < 5.6 additionally install the appropriate kernel module: (not needed when using the default {{Pkg|linux}} package)<br />
#* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
#* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer.<br />
<br />
{{Tip|Optionally consider a vanity keypair. See [[#Vanity keys]].}}<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
For connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of "/24" and the clients on {{ic|AllowedIPs}} "/32". The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=651861WireGuard2021-02-10T21:39:27Z<p>Edh: /* Installation */ Convert a tip environment on systemd and network manager support wireguard to plain text as general support from network managers can be assumed considering the installation instructions</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
# [[Install]] {{Pkg|wireguard-tools}}. <br />
# For Linux kernels < 5.6 additionally install the appropriate kernel module: (not needed when using the default {{Pkg|linux}} package)<br />
#* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
#* {{Pkg|wireguard-dkms}} for the DKMS variant for other Linux < 5.6 [[kernel]]s.<br />
<br />
Note, [[#systemd-networkd|systemd-networkd]] and [[#NetworkManager|NetworkManager]] both have native support for setting up WireGuard interfaces, they only require the kernel module.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer.<br />
<br />
{{Tip|Optionally consider a vanity keypair. See [[#Vanity keys]].}}<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual WireGuard setup ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
For connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/]}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
'''Routing all traffic over Wireguard'''<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routs all its traffic over Wireguard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. At least Netctl version ≥ 1.23 is recommended as previous versions had various bugs around WireGuard implementation. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of "/24" and the clients on {{ic|AllowedIPs}} "/32". The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the .conf extension, for client).<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Edhhttps://wiki.archlinux.org/index.php?title=PipeWire&diff=651860PipeWire2021-02-10T21:23:29Z<p>Edh: /* WebRTC screen sharing */ Provide further proof that support for sharing a single window was added to xdg-desktop-portal-gtk ( https://github.com/flatpak/xdg-desktop-portal-gtk/issues/204 )</p>
<hr />
<div>[[Category:Multimedia]]<br />
[[fi:PipeWire]]<br />
[[ja:PipeWire]]<br />
{{Related articles start}}<br />
{{Related|PipeWire/Examples}}<br />
{{Related articles end}}<br />
<br />
[http://pipewire.org PipeWire] is a new multimedia framework by GNOME. The main developer is Wim Taymans.<br />
<br />
PipeWire supports containers like [[Flatpak]] and does not rely on [[user group]]s ''audio'' and ''video'', but rather uses a [[Polkit]]-like security model asking Flatpak or Wayland for permission to record screen or audio.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{pkg|pipewire}} package from the official repositories.<br />
<br />
Pipewire uses [[Systemd/User]] for management of the server and automatic socket activation. See the respective [[Systemd/User]] for more details on the startup behavior and logging of the service.<br />
<br />
Optionally, install {{pkg|pipewire-docs}} to review the documentation. Other packages, such as {{pkg|pipewire-alsa}}, {{pkg|pipewire-pulse}}, and {{pkg|pipewire-jack}} are normally not needed unless one wants to [[#Audio|use PipeWire as a PulseAudio/JACK replacement]]. Also available are {{aur|lib32-pipewire}}, {{aur|lib32-pipewire-pulse-git}}{{Broken package link|package not found}}, and {{aur|lib32-pipewire-jack}} for multilib support.<br />
<br />
== Usage ==<br />
<br />
=== WebRTC screen sharing ===<br />
<br />
Most browsers used to rely on X11 for capturing the desktop (or individual applications) when using WebRTC (e.g. on Google Hangouts). On Wayland, the sharing mechanism is handled differently for security reasons. PipeWire enables sharing content under Wayland with fine-grained access controls.<br />
<br />
This requires {{Pkg|xdg-desktop-portal}} and one of its backends [http://jgrulich.cz/2018/07/04/how-to-enable-and-use-screen-sharing-on-wayland to be installed]. The available backends are:<br />
<br />
* {{Pkg|xdg-desktop-portal-gtk}} for GNOME.<br />
* {{Pkg|xdg-desktop-portal-kde}} for KDE.<br />
* {{Pkg|xdg-desktop-portal-wlr}} for Wlroots-based compositor (e.g. [[Sway]], dwl)<br />
<br />
Firefox (84+) supports this method by default, while on Chromium (73+) one needs to enable [https://bugs.chromium.org/p/chromium/issues/detail?id=682122 WebRTC PipeWire support] by setting the corresponding (experimental) flag at the following URL<br />
chrome://flags/#enable-webrtc-pipewire-capturer<br />
<br />
For {{ic|xdg-desktop-portal-wlr}} to work you need to set {{ic|XDG_CURRENT_DESKTOP}}[https://github.com/emersion/xdg-desktop-portal-wlr#running]:<br />
export XDG_CURRENT_DESKTOP=sway<br />
<br />
Note, since Chromium is currently using PipeWire 0.2 whereas Arch ships PipeWire 0.3, you also need to install {{Pkg|libpipewire02}} for screen sharing to work.<br />
<br />
{{Tip|To share an individual monitor with {{ic|xdg-desktop-portal-wlr}} if you have more than one, you can add the {{ic|1=--output=''Monitor''}} flag to it by [[Systemd#Editing_provided_units|editing]] the {{ic|1=ExecStart=}} option in the unit's service file. The complete line could look like {{ic|1=ExecStart=@libexecdir@/xdg-desktop-portal-wlr --output=eDP-1}}}}<br />
<br />
{{Accuracy|Since [https://github.com/flatpak/xdg-desktop-portal-gtk/pull/225 this pull request] was merged, the following note about specific app/window sharing may be not correct anymore for {{Pkg|xdg-desktop-portal-gtk}}. Also see the ticket tracking the discussion at [https://github.com/flatpak/xdg-desktop-portal-gtk/issues/204].}}<br />
<br />
Note that the only supported feature is sharing the entire desktop and not a specific app/window [https://github.com/emersion/xdg-desktop-portal-wlr/wiki/FAQ#will-this-let-me-share-individual-windows][https://github.com/KDE/xdg-desktop-portal-kde/blob/master/TODO].<br />
<br />
=== Video ===<br />
<br />
Although the software is not yet production-ready, it is safe to play around with. Most applications that rely on [[GStreamer]] to handle e.g. video streams should work out-of-the-box thanks to the PipeWire GStreamer plugin. Applications like e.g. {{pkg|cheese}} are therefore already able to share video input using it.<br />
<br />
=== Audio ===<br />
<br />
PipeWire can be used as an audio server, similar to PulseAudio and JACK. It aims to replace both PulseAudio and JACK, by providing a PulseAudio-compatible server implementation and ABI-compatible libraries for JACK clients. See [https://blogs.gnome.org/uraeus/2020/09/04/pipewire-late-summer-update-2020/ this blog entry] for more information.<br />
<br />
==== ALSA/Legacy applications ====<br />
<br />
Install {{pkg|pipewire-alsa}} to route all application using the ALSA API through PipeWire.<br />
<br />
==== PulseAudio clients ====<br />
<br />
Install {{pkg|pipewire-pulse}}. Normally, no further action is needed, as the user service {{ic|pipewire-pulse.socket}} should be enabled automatically by the package. If PipeWire does not work correctly on system startup, validate that the user services {{ic|pipewire-pulse.service}} and {{ic|pipewire.service}} are up and running. See [[Systemd/User]].<br />
<br />
Reboot or re-login to see the effect.<br />
<br />
To check if the replacement is working, run the following command and see the output:<br />
<br />
{{hc|1=$ pactl info|2=<br />
...<br />
Server Name: PulseAudio (on PipeWire 0.3.16)<br />
...<br />
}}<br />
<br />
==== JACK clients ====<br />
<br />
Install {{pkg|pipewire-jack}} and use {{ic|pw-jack}} to launch JACK clients with the compatible libraries instead of the original {{ic|libjack*}}:<br />
<br />
pw-jack ''application''<br />
<br />
Alternatively, install {{aur|pipewire-jack-dropin}} to let JACK clients load the compatible libraries automatically.<br />
<br />
Use {{ic|ldd}} to verify that the JACK application links to the correct library:<br />
<br />
{{hc|1=$ ldd /usr/bin/qjackctl {{!}} grep -i libjack|2=<br />
libjack.so.0 => /usr/lib/pipewire-0.3/jack/libjack.so.0 (0x00007f7e5080a000)<br />
}}<br />
<br />
==== Bluetooth devices ====<br />
<br />
PipeWire handles Bluetooth audio devices if the {{pkg|pipewire-pulse}} package is installed. More specifically, the media session daemon checks for {{ic|/etc/pipewire/media-session.d/with-pulseaudio}}, and enables its {{ic|bluez5}} module automatically if the file exists.<br />
<br />
==== Run PipeWire on top of native JACK ====<br />
<br />
PipeWire can also run as a JACK client on top of the native JACK daemon if desired. See [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/JACK JACK and PipeWire] for more information.<br />
<br />
== Troubleshooting ==<br />
=== Microphone is not detected by PipeWire ===<br />
<br />
PipeWire's {{ic|alsa-monitor}} module uses {{pkg|alsa-card-profiles}} to detect devices by default. If this isn't working for you, try to turn off {{ic|api.alsa.use-acp}}, or optionally turn on {{ic|api.alsa.use-ucm}} in {{ic|/etc/pipewire/media-session.d/alsa-monitor.conf}}, under {{ic|rules}} -> the first rule -> {{ic|actions}} -> {{ic|update-props}}:<br />
<br />
...<br />
update-props = {<br />
api.alsa.use-acp = false<br />
...<br />
<br />
Then, restart pipewire and check available devices:<br />
<br />
{{hc|1=<br />
$ pw-record --list-targets<br />
|2=<br />
Available targets ("*" denotes default): 62<br />
58: description="Built-in Audio" prio=1872<br />
60: description="Built-in Audio" prio=2000<br />
* 62: description="Built-in Audio (Loopback PCM)" prio=1984<br />
}}<br />
<br />
=== No sound after connecting to Bluetooth device ===<br />
<br />
As of 2020-12-07, if there is no sound after connecting a Bluetooth device, you might need to switch the default sink and/or move a sink input to the correct sink. Use {{ic|pactl set-default-sink}} to set the sink and {{ic|pactl list sinks}} to list the available ones. This can be automated via [[udev]] using a script similar to [https://gist.github.com/tinywrkb/04e7fd644afa9b92d33a3a99ab07ee9e this one].<br />
<br />
See this [https://www.reddit.com/r/archlinux/comments/jydd02/pipewirepulse_03164_in_testing_now_replaces/gd3m7fu/?context=3 Reddit thread] for a discussion of the issue. According to author of the script, the headset profile (HSP) might still have problems.<br />
<br />
=== Low volume ===<br />
<br />
After replacing PulseAudio with Pipewire, sound worked fine, but after a reboot, the volume was intolerably low.<br />
<br />
Open {{ic|alsamixer}}, use {{ic|F6}} to select the proper soundcard, and make sure the ALSA volumes are at 100%. {{ic|alsactl}} should maintain this setting after reboot.<br />
<br />
=== Increasing RLIMIT_MEMLOCK ===<br />
<br />
Dec 13 11:11:11 HOST pipewire-pulse[99999]: Failed to mlock memory 0x7f4f659d8000 32832: This is not a problem but for best performance, consider increasing RLIMIT_MEMLOCK<br />
<br />
Install {{pkg|realtime-privileges}} and add your own user to the {{ic|realtime}} group.<br />
<br />
Alternatively, increasing memlock from 64kB to 128kB seems enough to fix this. If you are running {{ic|pipewire-pulse}} under [[systemd/User]], add:<br />
<br />
username soft memlock 64<br />
username hard memlock 128<br />
<br />
to {{ic|/etc/security/limits.d/username.conf}}, and:<br />
<br />
LimitMEMLOCK=131072<br />
<br />
to {{ic|pipewire-pulse.service}}.<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home Wiki] — PipeWire Wiki on Freedesktop GitLab<br />
* [https://blogs.gnome.org/uraeus/2018/01/26/an-update-on-pipewire-the-multimedia-revolution-an-update/ Pipewire Update Blog Post] — Blog post from January 2018 outlining the state of PipeWire at the time<br />
* [https://blogs.gnome.org/uraeus/2020/09/04/pipewire-late-summer-update-2020/ PipeWire Late Summer Update 2020] — Blog post from September 2020</div>Edhhttps://wiki.archlinux.org/index.php?title=PulseAudio/Troubleshooting&diff=651858PulseAudio/Troubleshooting2021-02-10T20:54:46Z<p>Edh: /* Enable Echo/Noise-Cancellation */ Fix broken section link</p>
<hr />
<div>[[Category:Sound]]<br />
[[it:PulseAudio (Italiano)/Troubleshooting]]<br />
[[ja:PulseAudio/トラブルシューティング]]<br />
[[ru:PulseAudio (Русский)/Troubleshooting]]<br />
See [[PulseAudio]] for the main article.<br />
== Getting debug output from pulseaudio ==<br />
It can be useful to stop the daemon and start it in a terminal during debugging:<br />
$ systemctl --user stop pulseaudio.socket<br />
$ systemctl --user stop pulseaudio.service<br />
$ pulseaudio -v<br />
<br />
Add v's to increase verbosity.<br />
<br />
== Volume ==<br />
<br />
Here you will find some hints on volume issues and why you may not hear anything.<br />
<br />
=== Auto-Mute Mode ===<br />
<br />
''Auto-Mute Mode'' is a configurable setting from {{ic|amixer}}. For more information, see [[ALSA#Disabling auto mute on startup]].<br />
<br />
=== Muted audio device ===<br />
<br />
If one experiences no audio output via any means while using [[ALSA]], attempt to unmute the sound card. To do this, launch {{ic|alsamixer}} and make sure each column has a green {{ic|00}} under it (this can be toggled by pressing {{ic|m}}):<br />
<br />
$ alsamixer -c 0<br />
<br />
{{Note|alsamixer will not tell you which output device is set as the default. One possible cause of no sound after install is that PulseAudio detects the wrong output device as a default. Install {{Pkg|pavucontrol}} and check if there is any output on the pavucontrol panel when playing a ''.wav'' file.}}<br />
<br />
=== Output stuck muted while Master is toggled ===<br />
<br />
In setups with multiple outputs (e.g. 'Headphone' and 'Speaker') using plain amixer to toggle Master can trigger PulseAudio to mute the active output too, but it does not necessarily unmute it when Master is toggled back to be unmuted. [https://lists.freedesktop.org/archives/pulseaudio-discuss/2015-December/025062.html] To resolve this, amixer must have the device flag set to 'pulse':<br />
<br />
$ amixer -D pulse sset Master toggle<br />
<br />
This will cause amixer to ask PulseAudio to do the toggling rather than toggling it directly.<br />
Because of this, PulseAudio will correctly unmute Master as well as any applicable output.<br />
<br />
=== Muted application ===<br />
<br />
If a specific application is muted or low while all else seems to be in order, it may be due to individual {{ic|sink-input}} settings. With the offending application playing audio, run:<br />
<br />
$ pacmd list-sink-inputs<br />
<br />
Find and make note of the {{ic|index}} of the corresponding {{ic|sink input}}. The {{ic|properties:}} {{ic|application.name}} and {{ic|application.process.binary}}, among others, should help here. Ensure sane settings are present, specifically those of {{ic|muted}} and {{ic|volume}}.<br />
If the sink is muted, it can be unmuted by:<br />
<br />
$ pacmd set-sink-input-mute <index> false<br />
<br />
If the volume needs adjusting, it can be set to 100% by:<br />
<br />
$ pacmd set-sink-input-volume <index> 0x10000<br />
<br />
{{Note|If {{ic|pacmd}} reports {{ic|0 sink input(s)}}, double-check that the application is playing audio. If it is still absent, verify that other applications show up as sink inputs.}}<br />
<br />
=== Volume adjustment does not work properly ===<br />
<br />
Check {{ic|/usr/share/alsa-card-profile/mixer/paths/analog-output.conf.common}}.<br />
<br />
If the volume does not appear to increment/decrement properly using {{ic|alsamixer}} or {{ic|amixer}}, it may be due to PulseAudio having a larger number of increments (65537 to be exact). Try using larger values when changing volume (e.g. {{ic|amixer set Master 655+}}).<br />
<br />
=== Per-application volumes change when the Master volume is adjusted ===<br />
<br />
This is because PulseAudio uses flat volumes by default, instead of relative volumes, relative to an absolute master volume. If this is found to be inconvenient, asinine, or otherwise undesireable, relative volumes can be enabled by disabling flat volumes in the PulseAudio daemon's configuration file:<br />
<br />
{{hc|/etc/pulse/daemon.conf or ~/.config/pulse/daemon.conf|2=<br />
flat-volumes = no<br />
}}<br />
<br />
and then restarting PulseAudio by executing<br />
<br />
$ pulseaudio -k<br />
$ pulseaudio --start<br />
<br />
=== Volume gets louder every time a new application is started ===<br />
<br />
Per default, it seems as if changing the volume in an application sets the global system volume to that level instead of only affecting the respective application. Applications setting their volume on startup will therefore cause the system volume to "jump".<br />
<br />
Fix this by disabling flat volumes, as demonstrated in the previous section. When Pulse comes back after a few seconds, applications will not alter the global system volume anymore but have their own volume level again.<br />
<br />
{{Note|A previously installed and removed pulseaudio-equalizer may leave behind remnants of the setup in {{ic|~/.config/pulse/default.pa}} or {{ic|~/.pulse/default.pa}} which can also cause maximized volume trouble. Comment that out as needed.}}<br />
<br />
=== Sound output is only mono on M-Audio Audiophile 2496 sound card ===<br />
<br />
Add the following:<br />
<br />
{{hc|/etc/pulseaudio/default.pa|2=<br />
load-module module-alsa-sink sink_name=delta_out device=hw:M2496 format=s24le channels=10 channel_map=left,right,aux0,aux1,aux2,aux3,aux4,aux5,aux6,aux7<br />
load-module module-alsa-source source_name=delta_in device=hw:M2496 format=s24le channels=12 channel_map=left,right,aux0,aux1,aux2,aux3,aux4,aux5,aux6,aux7,aux8,aux9<br />
set-default-sink delta_out<br />
set-default-source delta_in<br />
}}<br />
<br />
=== No sound below a volume cutoff or Clipping on a particular output device ===<br />
<br />
Known issue (will not fix): https://bugs.launchpad.net/ubuntu/+source/pulseaudio/+bug/223133<br />
<br />
If sound does not play when PulseAudio's volume is set below a certain level, or if you hear clipping on output even at low volume (including bluetooth devices), try setting {{ic|1=ignore_dB=1}} in {{ic|/etc/pulse/default.pa}}:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
load-module module-udev-detect ignore_dB=1<br />
}}<br />
<br />
However, be aware that it may cause another bug preventing PulseAudio to unmute speakers when headphones or other audio devices are unplugged.<br />
<br />
=== Low volume for internal microphone ===<br />
<br />
If you experience low volume on internal notebook microphone, try setting:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
set-source-volume 1 300000<br />
}}<br />
<br />
=== Clients alter master output volume (a.k.a. volume jumps to 100% after running application) ===<br />
<br />
If changing the volume in specific applications or simply running an application changes the master output volume this is likely due to flat volumes mode of pulseaudio. Before disabling it, KDE users should try lowering their system notifications volume in ''System Settings -> Application and System Notifications -> Manage Notifications'' under the ''Player Settings'' tab to something reasonable. Changing the ''Event Sounds'' volume in KMix or another volume mixer application will not help here. This should make the flat-volumes mode work out as intended, if it does not work, some other application is likely requesting 100% volume when its playing something. If all else fails, you can try to disable flat-volumes:<br />
<br />
{{hc|/etc/pulse/daemon.conf|2=<br />
flat-volumes = no<br />
}}<br />
<br />
Then restart PulseAudio daemon:<br />
<br />
# pulseaudio -k<br />
# pulseaudio --start<br />
<br />
=== No sound after resume from suspend ===<br />
<br />
If audio generally works, but stops after resume from suspend, try "reloading" PulseAudio by executing:<br />
<br />
$ /usr/bin/pasuspender /bin/true<br />
<br />
This is better than completely killing and restarting it ({{ic|pulseaudio -k}} followed by {{ic|pulseaudio --start}}), because it does not break already running applications.<br />
<br />
If the above fixes your problem, you may wish to automate it, by creating a systemd service file.<br />
<br />
1. Create the template service file in {{ic|/etc/systemd/system/resume-fix-pulseaudio@.service}}:<br />
<br />
[Unit]<br />
Description=Fix PulseAudio after resume from suspend<br />
After=suspend.target<br />
<br />
[Service]<br />
User=%I<br />
Type=oneshot<br />
Environment="XDG_RUNTIME_DIR=/run/user/%U"<br />
ExecStart=/usr/bin/pasuspender /bin/true<br />
<br />
[Install]<br />
WantedBy=suspend.target<br />
<br />
2. Enable it for your user account<br />
<br />
# systemctl enable resume-fix-pulseaudio@''YOUR_USERNAME_HERE''.service<br />
<br />
3. Reload systemd<br />
<br />
# systemctl --system daemon-reload<br />
<br />
=== ALSA channels mute when headphones are plugged/unplugged improperly ===<br />
<br />
If when you unplug your headphones or plug them in the audio remains muted in alsamixer on the wrong channel due to it being set to 0%, you may be able to fix it by opening {{ic|/etc/pulse/default.pa}} and commenting out the line:<br />
<br />
load-module module-switch-on-port-available<br />
<br />
Then restart the pulseaudio backend:<br />
$ systemctl --user restart pulseaudio<br />
<br />
=== Volume resets to 50% every few seconds ===<br />
<br />
Install {{Pkg|alsa-tools}} and use:<br />
<br />
$ hdajackretask<br />
<br />
Set "Not Connected" to everything but the ports you are using. It seems the other unused audio ports on the motherboard interfere with the used ones.<br />
Then if you want use the Boot Override to save this change between reboots. There is a possibility it is the Front Green Headphone that is causing the bug, if you need it override the Front Microphone to Headphone and the Front Green Headphone to "Not Connected" and use the Front Microphone port as your headphone port.<br />
<br />
More info about this problem: [https://bugs.launchpad.net/ubuntu/+source/pulseaudio/+bug/1585084].<br />
<br />
=== Volume low/too quiet on analog headphones/speakers ===<br />
<br />
If you added the {{ic|1=ignore_dB=1}} option earlier to the {{ic|load-module module-udev-detect}} line in your {{ic|/etc/pulse/default.pa}}, try removing it.<br />
<br />
=== Delay when changing volume using media keys ===<br />
<br />
Edit {{ic|/etc/pulse/daemon.conf}} and set {{ic|1=enable-deferred-volume = no}}. This might cause some sound crackles when changing volume, in that case you might want to leave that option enabled and tweak the {{ic|deferred-volume-safety-margin-usec}} and {{ic|deferred-volume-extra-delay-usec}} options instead.<br />
<br />
== Microphone ==<br />
<br />
=== Microphone not detected by PulseAudio ===<br />
<br />
{{Note|1=For bluetooth headsets you may be seeking [https://bbs.archlinux.org/viewtopic.php?pid=1921917#p1921917/ this thread] instead.}}<br />
<br />
Determine the card and device number of your mic:<br />
<br />
{{hc|$ arecord -l|<br />
**** List of CAPTURE Hardware Devices ****<br />
card 0: PCH [HDA Intel PCH], device 0: ALC269VC Analog [ALC269VC Analog]<br />
Subdevices: 1/1<br />
Subdevice #0: subdevice #0<br />
}}<br />
<br />
In {{ic|hw:''CARD'',''DEVICE''}} notation, you would specify the above device as {{ic|hw:0,0}}.<br />
<br />
Then, edit {{ic|/etc/pulse/default.pa}} and insert a {{ic|load-module}} line specifying your device as follows:<br />
<br />
load-module module-alsa-source device=hw:0,0<br />
# the line above should be somewhere before the line below<br />
.ifexists module-udev-detect.so<br />
<br />
Finally, restart pulseaudio to apply the new settings:<br />
<br />
$ pulseaudio -k ; pulseaudio -D<br />
<br />
If everything worked correctly, you should now see your mic show up when running {{ic|pavucontrol}} (under the {{ic|Input Devices}} tab).<br />
<br />
=== PulseAudio uses wrong microphone ===<br />
<br />
If PulseAudio uses the wrong microphone, and changing the Input Device with Pavucontrol did not help, take a look at alsamixer. It seems that Pavucontrol does not always set the input source correctly.<br />
<br />
$ alsamixer<br />
<br />
Press {{ic|F6}} and choose your sound card, e.g. HDA Intel. Now press {{ic|F5}} to display all items. Try to find the item: {{ic|Input Source}}. With the up/down arrow keys you are able to change the input source.<br />
<br />
Now try if the correct microphone is used for recording.<br />
<br />
=== No microphone on ThinkPad T400/T500/T420 ===<br />
<br />
Run:<br />
<br />
$ alsamixer -c 0<br />
<br />
Unmute and maximize the volume of the "Internal Mic".<br />
<br />
Once you see the device with:<br />
<br />
$ arecord -l<br />
<br />
you might still need to adjust the settings. The microphone and the audio jack are duplexed. Set the configuration of the internal audio in pavucontrol to ''Analog Stereo Duplex''.<br />
<br />
=== No microphone input on Acer Aspire One and Lenovo Ideapad 310-15ISK/330-15ARR ===<br />
<br />
Install pavucontrol, unlink the microphone channels and turn down the left one to 0.<br />
<br />
Some applications (e.g. chromium) can change microphone levels causing the same issue, a workaround is to [[#Another Possible Cause|remap stereo input to mono]] and use the remapped device as default.<br />
<br />
=== Static noise in microphone recording ===<br />
<br />
If we are getting static noise in Skype, gnome-sound-recorder, arecord, etc.'s recordings, then the sound card sample rate is incorrect. That is why there is static noise in Linux microphone recordings. To fix this, we need to set the sampling rate in {{ic|/etc/pulse/daemon.conf}} for the sound hardware.<br />
<br />
In addition to the guide below, since [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/11.0/ PulseAudio 11] it is possible to set {{ic|1=avoid-resampling = yes}} in [[PulseAudio#daemon.conf|daemon.conf]].<br />
<br />
==== Determine sound cards in the system (1/5) ====<br />
<br />
This requires {{Pkg|alsa-utils}} and related packages to be installed:<br />
<br />
{{hc|$ arecord --list-devices|<br />
**** List of CAPTURE Hardware Devices ****<br />
card 0: Intel [HDA Intel], device 0: ALC888 Analog [ALC888 Analog]<br />
Subdevices: 1/1<br />
Subdevice #0: subdevice #0<br />
card 0: Intel [HDA Intel], device 2: ALC888 Analog [ALC888 Analog]<br />
Subdevices: 1/1<br />
Subdevice #0: subdevice #0<br />
}}<br />
<br />
The sound card is {{ic|hw:''x'',''y''}} where {{ic|''x''}} is the card number and {{ic|''y''}} is the device number. In the above example, it is {{ic|hw:0,0}}.<br />
<br />
==== Determine sampling rate of the sound card (2/5) ====<br />
<br />
We aim to find the highest sample rate supported by the {{ic|hw:0,0}} sound card using a ''trial-and-error'' procedure starting from a low value. When the top value is reached, we got a warning message:<br />
<br />
{{hc|1=arecord -f dat -r 60000 -D hw:0,0 -d 5 test.wav|2=<br />
"Recording WAVE 'test.wav' : Signed 16 bit Little Endian, Rate 60000 Hz, Stereo<br />
Warning: rate is not accurate (requested = 60000Hz, '''got = 44100Hz''')<br />
please, try the plug plugin<br />
}}<br />
<br />
observe, the {{ic|1=got = 44100Hz}}. This is the maximum sampling rate of our card.<br />
<br />
==== Setting the sound card's sampling rate into PulseAudio configuration (3/5) ====<br />
<br />
The default sampling rate in PulseAudio:<br />
<br />
{{hc|1=$ grep "default-sample-rate" /etc/pulse/daemon.conf|2=<br />
; default-sample-rate = 48000<br />
}}<br />
<br />
{{ic|48000}} is disabled and needs to be changed to {{ic|44100}}:<br />
<br />
# sed 's/; default-sample-rate = 48000/default-sample-rate = 44100/g' -i /etc/pulse/daemon.conf<br />
<br />
==== Restart PulseAudio to apply the new settings (4/5) ====<br />
<br />
$ pulseaudio -k<br />
$ pulseaudio --start<br />
<br />
==== Finally check by recording and playing it back (5/5) ====<br />
<br />
Let us record some voice using a microphone for, say, 10 seconds. Make sure the microphone is not muted and all<br />
<br />
$ arecord -f cd -d 10 test-mic.wav<br />
<br />
After 10 seconds, let us play the recording...<br />
<br />
$ aplay test-mic.wav<br />
<br />
Now hopefully, there is no static noise in microphone recording anymore.<br />
<br />
==== Another Possible Cause ====<br />
<br />
Another possible cause is that your mic has two channels but only one channel can provide a valid sound signal. Some information can be found [https://github.com/MaartenBaert/ssr/issues/323#issuecomment-268230548 here]. The solution is to remap the stereo input to a mono input:<br />
<br />
1. Find your source name from the following command; mine is {{ic|alsa_input.pci-0000_00_1f.3.analog-stereo}}<br />
<br />
pacmd list-sources | grep 'name:.*input'<br />
<br />
2. Edit {{ic|/etc/pulse/default.pa}} and add the following lines, where INPUT_NAME is name of the input source from above step:<br />
<br />
load-module module-remap-source source_name=record_mono master=INPUT_NAME master_channel_map=front-left channel_map=mono<br />
set-default-source record_mono<br />
<br />
3. Restart PulseAudio:<br />
<br />
$ pulseaudio -k<br />
$ pulseaudio --start<br />
<br />
Now {{ic|arecord}} hopefully works. You may still need to change the {{ic|RecordStream from}} setting to {{ic|Remapped Built-in Audio Analog Stereo}} of a specific application in the {{ic|Recording}} tab of {{ic|pavucontrol}}.<br />
<br />
==== If using a USB microphone ====<br />
<br />
Try plugging it into a different port (eg: ports at the back rather than front).<br />
<br />
=== No microphone on Steam or Skype with enable-remixing = no ===<br />
<br />
When you set {{ic|1=enable-remixing = no}} on {{ic|/etc/pulse/daemon.conf}} you may find that your microphone has stopped working on certain applications like Skype or Steam. This happens because these applications capture the microphone as mono only and because remixing is disabled, Pulseaudio will no longer remix your stereo microphone to mono.<br />
<br />
To fix this you need to tell Pulseaudio to do this for you:<br />
<br />
1. Find the name of the source <br />
<br />
# pacmd list-sources<br />
<br />
Example output edited for brevity, the name you need is in bold:<br />
<br />
index: 2<br />
name: <'''alsa_input.pci-0000_00_14.2.analog-stereo'''><br />
driver: <module-alsa-card.c><br />
flags: HARDWARE HW_MUTE_CTRL HW_VOLUME_CTRL DECIBEL_VOLUME LATENCY DYNAMIC_LATENCY<br />
<br />
2. Add a remap rule to {{ic|/etc/pulse/default.pa}}, use the name you found with the previous command, here we will use '''alsa_input.pci-0000_00_14.2.analog-stereo''' as an example:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
### Remap microphone to mono<br />
load-module module-remap-source master=alsa_input.pci-0000_00_14.2.analog-stereo master_channel_map=front-left,front-right channels=2 channel_map=mono,mono<br />
}}<br />
<br />
3. Restart Pulseaudio<br />
<br />
# pulseaudio -k<br />
<br />
{{Note|Pulseaudio may fail to start if you do not exit a program that was using the microphone (e.g. if you tested on Steam before modifying the file), in which case you should exit the application and manually start Pulseaudio}}<br />
<br />
# pulseaudio --start<br />
<br />
=== Microphone distorted due to automatic adjustment ===<br />
If your microphone volume creeps up automatically and causes the sound to be distorted, you can fix it by disabling mic boost:<br />
<br />
In all files {{ic|/usr/share/alsa-card-profile/mixer/paths/analog-input*.conf}},<br />
<br />
* Under {{ic|[Element Capture]}} set {{ic|volume}} to {{ic|zero}}<br />
* Under {{ic|[Element Internal Mic Boost]}} set {{ic|volume}} to {{ic|zero}}.<br />
* Under {{ic|[Element Int Mic Boost]}} set {{ic|volume}} to {{ic|zero}}.<br />
* Under {{ic|[Element Mic Boost]}} set {{ic|volume}} to {{ic|zero}}.<br />
including all variations such as {{ic|[Element Headphone Mic Boost]}} and {{ic|[Element Mic Boost (+20dB)]}}<br />
<br />
Then restart PulseAudio:<br />
<br />
# pulseaudio -k<br />
<br />
=== Microphone crackling with Realtek ALC892 ===<br />
<br />
Sometimes ALC892 chips have crackling sound while recording using a microphone. Some Pulseaudio config changes may help:<br />
<br />
{{hc|/etc/pulse/daemon.conf|output=<br />
resample-method = src-sinc-best-quality<br />
default-sample-format = s16le<br />
default-sample-rate = 48000<br />
}}<br />
<br />
and add the {{ic|use_ucm}} option to<br />
<br />
{{hc|/etc/pulse/default.pa|output=<br />
load-module module-udev-detect use_ucm=0 tsched=0<br />
}}<br />
<br />
then restart pulseaudio.<br />
<br />
=== Microphone crackling with Azalia chipsets ===<br />
<br />
Some Azalia based chips have popping/crackling noise and distortion while recording using a microphone with PulseAudio. This can be fixed by loading the {{ic|snd-hda-intel}} module with {{ic|position_fix}} set to an appropriate value. This tells the module to use various DMA pointer fixes. Use trial and error to determine which value works for you. ([https://wiki.sabayon.org/index.php?title=HOWTO:_Resolve_Problems_with_HDA-Intel_Sound_Cards source])<br />
<br />
Create a new {{ic|modprobe.d}} config:<br />
<br />
{{hc|/etc/modprobe.d/azalia-microphone.conf|output=<br />
options snd-hda-intel position_fix=1<br />
}}<br />
<br />
Valid values for {{ic|position_fix}} are:<br />
* {{ic|0}} = Auto<br />
* {{ic|1}} = None<br />
* {{ic|2}} = POSBUF<br />
* {{ic|3}} = FIFO size<br />
<br />
then reload your modules.<br />
<br />
=== Echo test ===<br />
<br />
If you are unsure about your microphone setup, you can hear the input from the microphone in real-time by enabling the [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#index57h3 loopback module] ([https://answers.launchpad.net/ubuntu/+source/pulseaudio/+question/83742 source]):<br />
<br />
$ pactl load-module module-loopback<br />
<br />
The module will show up in the '''Recording''' tab of the {{Pkg|pavucontrol}} program, where the source and volume can be configured. While latency should be low, it should be sufficient to get a feeling of the sound quality as you will hear yourself speak in the microphone. To make the change permanent, add the following pulseaudio configuration:<br />
<br />
{{hc|/etc/pulse/default.pa|output=<br />
load-module module-loopback<br />
}}<br />
<br />
Watch out for feedback! Be ready to lower all volumes in case the microphone picks up the output from the loudspeakers. Naturally, it is better to run such a test with headphones.<br />
<br />
== Audio quality ==<br />
<br />
=== Enable Echo/Noise-Cancellation ===<br />
<br />
Arch does not load the Pulseaudio Echo-Cancellation module by default, therefore, we have to add it in {{ic|/etc/pulse/default.pa}}. First you can test if the module is present with {{ic|pacmd}} and entering {{ic|list-modules}}. If you cannot find a line showing {{ic|name: <module-echo-cancel>}} you have to add <br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
### Enable Echo/Noise-Cancellation<br />
load-module module-echo-cancel use_master_format=1 aec_method=webrtc aec_args="analog_gain_control=0\ digital_gain_control=1" source_name=echoCancel_source sink_name=echoCancel_sink<br />
set-default-source echoCancel_source<br />
set-default-sink echoCancel_sink<br />
}}<br />
<br />
then restart Pulseaudio<br />
<br />
$ pulseaudio -k<br />
$ pulseaudio --start<br />
<br />
and check if the module is activated by starting {{ic|pavucontrol}}. Under {{ic|Recording}} the input device should show {{ic|Echo-Cancel Source Stream from"}}.<br />
<br />
Turning on {{ic|1=beamforming=1}} in the aec_args can also significantly reduce background noise if you have more than one microphone (which is common on many new laptops). However, beamforming requires specifying your {{ic|mic_geometry}} (see below).<br />
<br />
If you want existing streams to be automatically moved to the new sink and source, you have to load the [[Bluetooth headset#Setting up auto connection|module-switch-on-connect]] with {{ic|1=ignore_virtual=no}} before.<br />
<br />
{{Note|1=If you plug in a USB sound card or headset, or you have for example a 5.1 Speaker configuration and plug in a headset on your front audio connectors after you have loaded the {{ic|module-echo-cancel}}, you have to manually unload and load the {{ic|module-echo-cancel}} again, because unfortunately there is no way to tell the module that it should automatically switch to the new default 'source_master' and 'source_sink'. See [https://gitlab.freedesktop.org/pulseaudio/pulseaudio/issues/196].}}<br />
<br />
==== Possible 'aec_args' for 'aec_method=webrtc' ====<br />
<br />
Here is a list of possible 'aec_args' for 'aec_method=webrtc' with their default values [https://github.com/pulseaudio/pulseaudio/blob/master/src/modules/echo-cancel/webrtc.cc][https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#index45h3]:<br />
<br />
* {{ic|1=analog_gain_control=1}} - Analog AGC - 'Automatic Gain Control' done over changing the volume directly - Will most likely lead to [[#Microphone distorted due to automatic adjustment|distortions]].<br />
* {{ic|1=digital_gain_control=0}} - Digital AGC - 'Automatic Gain Control' done in post processing (higher CPU load).<br />
* {{ic|1=experimental_agc=0}} - Allow enabling of the webrtc experimental AGC mechanism.<br />
* {{ic|1=agc_start_volume=85}} - Initial volume when using AGC - Possible values 0-255 - A too low initial volume may prevent the AGC algorithm from ever raising the volume high enough [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/9.0/].<br />
* {{ic|1=high_pass_filter=1}} - ?<br />
* {{ic|1=noise_suppression=1}} - Noise suppression.<br />
* {{ic|1=voice_detection=1}} - VAD - Voice activity detection.<br />
* {{ic|1=extended_filter=0}} - The extended filter is more complex and less sensitive to incorrect delay reporting from the hardware than the regular filter. The extended filter mode is disabled by default, because it seemed produce worse results during double-talk [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/9.0/]. Enable this option if your microphone or speaker has a larger latency, for example, if you use a wireless microphone or some HDMI TVs as speaker.<br />
* {{ic|1=intelligibility_enhancer=0}} - Some bits for webrtc intelligibility enhancer.<br />
* {{ic|1=drift_compensation=0}} - Drift compensation to allow echo cancellation between different devices (such as speakers on your laptop and the microphone on your USB webcam). - only possible with "mobile=0".<br />
* {{ic|1=beamforming=0}} - This can significantly reduce background noise. See [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#index45h3][https://arunraghavan.net/2016/06/beamforming-in-pulseaudio/]<br />
** {{ic|1=mic_geometry=x1,y1,z1,x2,y2,z2}} - Only with "beamforming=1".<br />
** {{ic|1=target_direction=a,e,r}} - Only with "beamforming=1". Note: If the module does not want to load with this argument, set azimuth (a) to the desired value, but set elevation (e) and radius (r) to 0.<br />
* {{ic|1=mobile=0}} - ?<br />
** {{ic|1=routing_mode=speakerphone}} - Possible Values "quiet-earpiece-or-headset,earpiece,loud-earpiece,speakerphone,loud-speakerphone" - only valid with "mobile=1".<br />
** {{ic|1=comfort_noise=1}} - ? - only valid with "mobile=1".<br />
<br />
==== Disable audio post processing in certain applications ====<br />
<br />
If you are using the [[#Enable Echo/Noise-Cancellation|module-echo-cancel]], you probably do not want other applications to do additional audio post processing. Here is a list for disabling audio post processing in following applications:<br />
<br />
* Mumble:<br />
*# Configure -> Settings -> Check 'Advanced' check box -> Audio Input<br />
*# Echo: Select 'Disabled'<br />
*# Noise Suppression: Set slider to 'Off'<br />
*# Max. Aplification: Set slider to '1.0'<br />
* TeamSpeak:<br />
*# Tools -> Options -> Capture<br />
*# Uncheck: 'Typing attenuation', 'Remove background noise', 'Echo cancellation' and 'Echo reduction (Ducking)'<br />
* Firefox: see [[Firefox tweaks#Disable WebRTC audio post processing]]<br />
* Steam:<br />
*# In window "Friends List" -> Manage friends list settings (gear symbol) -> VOICE -> Show Advanced Settings<br />
*# Set the following sliders to "OFF": "Echo cancellation", "Noise cancellation", "Automatic volume/gain control"<br />
* Skype:<br />
*# Tools -> Settings... -> Audio & Video -> Microphone -> Automatically adjust microphone settings -> off<br />
<br />
==== Script for reloading module-echo-cancel ====<br />
<br />
Since the module-echo-cancel is not always needed, or must be reloaded if the source_master or sink_master has changed, it is nice to have a easy way to load or reload the module-echo-cancel.<br />
<br />
[[Create]] the following script and make it [[executable]]:<br />
<br />
{{hc|echoCancelEnable.sh|<nowiki><br />
#!/bin/bash<br />
aecArgs="$*"<br />
# If no "aec_args" are passed on to the script, use this "aec_args" as default:<br />
[ -z "$aecArgs" ] && aecArgs="analog_gain_control=0 digital_gain_control=1"<br />
newSourceName="echoCancelSource"<br />
newSinkName="echoCancelSink"<br />
<br />
# "module-switch-on-connect" with "ignore_virtual=no" (needs PulseAudio 12 or higher) is needed to automatically move existing streams to a new (virtual) default source and sink.<br />
if ! pactl list modules short | grep "module-switch-on-connect.*ignore_virtual=no" >/dev/null 2>&1; then<br />
echo Load module \"module-switch-on-connect\" with \"ignore_virtual=no\"<br />
pactl unload-module module-switch-on-connect 2>/dev/null<br />
pactl load-module module-switch-on-connect ignore_virtual=no<br />
fi<br />
<br />
# Reload "module-echo-cancel"<br />
echo Reload \"module-echo-cancel\" with \"aec_args=$aecArgs\"<br />
pactl unload-module module-echo-cancel 2>/dev/null<br />
if pactl load-module module-echo-cancel use_master_format=1 aec_method=webrtc aec_args=\"$aecArgs\" source_name=$newSourceName sink_name=$newSinkName; then<br />
# Set a new default source and sink, if module-echo-cancel has loaded successfully.<br />
pacmd set-default-source $newSourceName<br />
pacmd set-default-sink $newSinkName<br />
fi<br />
</nowiki>}}<br />
<br />
To run the script easily from the graphical environment, you can create a [[desktop launcher]] for it.<br />
<br />
=== Recurrent neural network noise suppression (RNNoise) ===<br />
<br />
Installing the pacakge {{AUR|noise-suppression-for-voice}} will allow real-time noise suppression based on RNNoise: Learning Noise Suppression [https://jmvalin.ca/demo/rnnoise/]. Configuration details can be found on the projects Github site [https://github.com/werman/noise-suppression-for-voice].<br />
<br />
=== Glitches, skips or crackling ===<br />
<br />
The newer implementation of the PulseAudio sound server uses timer-based audio scheduling instead of the traditional, interrupt-driven approach. <br />
<br />
Timer-based scheduling may expose issues in some ALSA drivers. On the other hand, other drivers might be glitchy without it on, so check to see what works on your system. <br />
<br />
To turn timer-based scheduling off add {{ic|1=tsched=0}} in {{ic|/etc/pulse/default.pa}}:<br />
{{hc|/etc/pulse/default.pa|2=<br />
load-module module-udev-detect tsched=0<br />
}}<br />
<br />
Then restart the PulseAudio server:<br />
<br />
$ pulseaudio -k<br />
$ pulseaudio --start<br />
<br />
Do the reverse to enable timer-based scheduling, if not already enabled by default.<br />
<br />
If you are using Intel's [[Wikipedia:IOMMU|IOMMU]] and experience glitches and/or skips, add {{ic|1=intel_iommu=igfx_off}} to your kernel command line.<br />
<br />
Some Intel audio cards using the {{ic|snd-hda-intel}} module need the otions {{ic|1=vid=8086 pid=8ca0 snoop=0}}. In order to set them permanently, create/modify the following file including the line below.<br />
<br />
{{hc|/etc/modprobe.d/sound.conf|2=<br />
options snd-hda-intel vid=8086 pid=8ca0 snoop=0<br />
}}<br />
<br />
Please report any such cards to [https://www.freedesktop.org/wiki/Software/PulseAudio/Backends/ALSA/BrokenDrivers/ PulseAudio Broken Sound Driver page]<br />
<br />
=== Static noise when using headphones ===<br />
<br />
Time-based scheduling may be causing this, disable it as explained in [[#Glitches, skips or crackling]].<br />
<br />
Another reason you are encountering static noise in your headphone jack could be ALSA's loopback mixing.<br />
<br />
Make sure you have {{Pkg|alsa-utils}} installed, launch {{ic|alsamixer}}, then select your audio device (pressing {{ic|F6}}), navigate all the way left using the {{ic|left arrow}}, and stop on '''Loopback''', if '''Enabled''' disable it using the {{ic|down arrow}}. This should not impact audio playback or microphone recording negatively, unless you require loopback mixing.<br />
<br />
Some notebook models, like Dell XPS 13 9360, suffer from [[Dell XPS 13 (9360)#Continuous_hissing_sound_with_headphones|continuous hissing sound]] when a headphone is plugged in.<br />
<br />
Yet another reason for this symptom could be the power-saving mode of your audio device.[https://askubuntu.com/a/534082] If you followed [[Power management#Audio]], revert the changes and check if it solves the problem.<br />
<br />
=== Setting the default fragment number and buffer size in PulseAudio ===<br />
<br />
{{Style|Copied from Linux mint topic with few additions}}<br />
<br />
==== Disabling timer-based scheduling (0/4) ====<br />
<br />
By default, PulseAudio uses timer-based scheduling. In this mode, fixed-size fragments are not used at all, and so the default-fragments and default-fragment-size-msec parameters are ignored.<br />
To turn timer-based scheduling off add {{ic|1=tsched=0}} in {{ic|/etc/pulse/default.pa}}:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
load-module module-udev-detect tsched=0<br />
}}<br />
<br />
==== Decide on audio device parameters (1/4) ====<br />
<br />
Instructions below will cause PulseAudio to use a fixed size and number for audio fragments. These settings directly affect latency and power consumption. The latency is determined as {{ic|1=default-fragments * default-fragment-size-msec}}, and the interrupt rate (i.e. how often the application is notified that some sound has indeed been played) is {{ic|1=1000 / default-fragment-size-msec}}. The considerations are:<br />
<br />
* The total number of fragments must be within the limits accepted by the hardware. Most sound cards are OK with two or more fragments, but some require three or more.<br />
* Giving the sound card more fragments than strictly necessary increases the latency, does not change power consumption, and does not remove the load from the scheduler. Therefore, it is advised only in the cases when the interrupts are not reliably delivered to the CPU, and one extra fragment beyond the minimum required should always be enough.<br />
* Giving the sound card bigger fragments increases latency and decreases power consumption.<br />
* Some applications (games and VoIP) request low latency and produce glitches when PulseAudio cannot fulfill their request.<br />
* Setting the latency too low will put a lot of stress on the scheduler, also resulting in glitches.<br />
<br />
If one does not care about excessive power consumption, then 2 or 3 fragments, 5 ms each, are a reasonable choice.<br />
<br />
==== Modify PulseAudio's configuration file (2/4) ====<br />
<br />
{{hc|/etc/pulse/daemon.conf|2=<br />
default-fragments = '''3'''<br />
default-fragment-size-msec = '''5'''<br />
}}<br />
<br />
==== Restart the PulseAudio daemon (3/4) ====<br />
<br />
$ systemctl --user restart pulseaudio.service<br />
<br />
==== See if it helps (4/4) ====<br />
<br />
Run your applications, listen to the sounds they produce, inspect the journal.<br />
<br />
If the skips/pops/glitches are occasional and mostly correlated to the system being highly loaded: this is a scheduler problem, the latency needs to be increased.<br />
<br />
If there is metallic sound with the wrong speed from all applications: the most common reason is that you are trying to configure the fragment size which is way too small, like 1 ms. Do not do this.<br />
<br />
If some, but not all, applications produce a constant stream of glitches: this is an application that assumes a low-latency setup. So the fragment size must be decreased so that the application request becomes valid.<br />
<br />
=== Choppy sound with analog surround sound setup ===<br />
<br />
The low-frequency effects (LFE) or Subwoofer channel is not remixed per default. To enable it the following needs to be set in {{ic|/etc/pulse/daemon.conf}} :<br />
<br />
{{hc|/etc/pulse/daemon.conf|2=<br />
remixing-produce-lfe = yes<br />
remixing-consume-lfe = yes<br />
}}<br />
<br />
You should also consider to set a proper crossover frequency for the LFE- channel.<br />
The crossover frequency is the frequency up to which the audio signal is rerouted to the LFE sink.<br />
The optimal crossover frequency in Hz depends on the size of all your speakers.<br />
<br />
{{hc|/etc/pulse/daemon.conf|2=<br />
lfe-crossover-freq = <40-200><br />
}}<br />
<br />
=== Laggy sound ===<br />
<br />
This issue is due to incorrect buffer sizes. First verify that the variables {{ic|default-fragments}} and {{ic|default-fragment-size-msec}} are not being set to non default values in the file {{ic|/etc/pulse/daemon.conf}}. If the issue is still present, try setting them to the following values:<br />
<br />
{{hc|/etc/pulse/daemon.conf|2=<br />
default-fragments = 5<br />
default-fragment-size-msec = 2<br />
}}<br />
<br />
=== Choppy/distorted sound ===<br />
<br />
This can result from an incorrectly set sample rate. Try the following setting:<br />
<br />
{{hc|/etc/pulse/daemon.conf|2=<br />
avoid-resampling = yes #(Needs [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/11.0/ PA11] or higher)<br />
default-sample-rate = 48000<br />
}}<br />
<br />
and restart the PulseAudio server.<br />
<br />
If one experiences choppy sound in applications using [[Wikipedia:OpenAL|OpenAL]], change the sample rate in {{ic|/etc/openal/alsoft.conf}}:<br />
<br />
{{hc|/etc/openal/alsoft.conf|2=<br />
frequency = 48000<br />
}}<br />
<br />
Setting the PCM volume above 0 dB can cause [[Wikipedia:Clipping_(audio)|clipping]]. Running {{ic|alsamixer}} will allow you to see if this is the problem and if so fix it. Note that ALSA may not [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/PulseAudioStoleMyVolumes/ correctly export] the dB information to PulseAudio. Try the following:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
load-module module-udev-detect ignore_dB=1<br />
}}<br />
<br />
and restart the PulseAudio server. See also [[#No sound below a volume cutoff or Clipping on a particular output device]].<br />
<br />
=== Sound stuttering when streaming over network ===<br />
<br />
When streaming over Wi-Fi using module-native-protocol-tcp you can experience periodic sound stuttering with buffer underruns. As a workaround you can try to use rtp protocol. On sender side create rtp sink:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
load-module module-null-sink sink_name=rtp<br />
load-module module-rtp-send source=rtp.monitor<br />
}}<br />
<br />
and switch to it:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
set-default-sink rtp<br />
}}<br />
<br />
On receiver side load rtp module:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
load-module module-rtp-recv<br />
}}<br />
<br />
=== Pops when starting and stopping playback ===<br />
<br />
PulseAudio can suspend sinks after a period of inactivity. This can make an audible noise (like a crack/pop/scratch). Sometimes even when move the slider volume, or open and close windows (KDE4). This behavior is enabled in default configuration files:<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
load-module module-suspend-on-idle<br />
}}<br />
<br />
{{hc|/etc/pulse/system.pa|2=<br />
load-module module-suspend-on-idle<br />
}}<br />
<br />
Commenting that line in relevant file fixes that issue. A better solution is to add the following file:<br />
<br />
{{hc|~/.config/pulse/default.pa|2=<br />
.include /etc/pulse/default.pa<br />
.nofail<br />
unload-module module-suspend-on-idle<br />
.fail<br />
}}<br />
<br />
== Hardware and Cards ==<br />
<br />
=== No HDMI sound output after some time with the monitor turned off ===<br />
<br />
The monitor is connected via HDMI/DisplayPort, and the audio jack is plugged in the headphone jack of the monitor, but PulseAudio insists that it is unplugged:<br />
<br />
{{hc|pactl list sinks|<br />
...<br />
hdmi-output-0: HDMI / DisplayPort (priority: 5900, not available)<br />
...<br />
}}<br />
<br />
This leads to no sound coming from HDMI output. A workaround for this is to switch to another VT and back again. If that does not work, try: turn off your monitor, switch to another VT, turn on your monitor, and switch back. This problem has been reported by ATI/Nvidia/Intel users.<br />
<br />
Another workaround could be to disable the switch-on-port-available module by commenting it in /etc/pulse/default.pa [https://bugs.freedesktop.org/show_bug.cgi?id=93946#c36]:<br />
<br />
{{hc|/etc/pulse/default.pa|<br />
...<br />
### Should be after module-*-restore but before module-*-detect<br />
#load-module module-switch-on-port-available<br />
...<br />
}}<br />
<br />
=== No HDMI sound using a headless server ===<br />
<br />
You might want to use HDMI audio with your a/v receiver but no display. HDMI requires a video signal, which we have from the virtual terminal. <br />
<br />
By default, this signal is turned off after 600 seconds, thus the audio sink gets lost as well.<br />
<br />
To prevent screen blanking, add {{ic|consoleblank&#61;0}} to the kernel command line.<br />
<br />
=== No cards ===<br />
<br />
If PulseAudio starts, run {{ic|pacmd list}}. If no cards are reported, make sure that the ALSA devices are not in use:<br />
<br />
$ fuser -v /dev/snd/*<br />
$ fuser -v /dev/dsp<br />
<br />
Make sure any applications using the pcm or dsp files are shut down before restarting PulseAudio.<br />
<br />
=== Starting an application interrupts other app's sound ===<br />
<br />
If you have trouble with some applications (such as TeamSpeak or Mumble) interrupting sound output of already running applications (such as Deadbeaf), you can solve this by commenting out the line {{ic|load-module module-role-cork}} in {{ic|/etc/pulse/default.pa}} like shown below:<br />
<br />
{{hc|/etc/pulse/default.pa|<br />
### Cork music/video streams when a phone stream is active<br />
# load-module module-role-cork<br />
}}<br />
<br />
Then restart pulseaudio by using your normal user account with<br />
<br />
$ pulseaudio -k<br />
$ pulseaudio --start<br />
<br />
=== The only device shown is "dummy output" or newly connected cards are not detected ===<br />
<br />
If the only playback device is the Dummy Output, PulseAudio cannot access your sound devices. It is possible there is an issue with logind giving permissions, see [[General troubleshooting#Session permissions]] for more information.<br />
<br />
An application might also not have been configured to work with PulseAudio. This happens with [[FluidSynth#Conflicting_with_PulseAudio|FluidSynth]] for example. To see which application is responsible for a direct access to the sound card via alsa, run the following command:<br />
<br />
# fuser -v /dev/snd/*<br />
<br />
Try to close these applications. pulseaudio, if running, should take again precedence over these applications and all the applications relying on pulseaudio should work again like expected.<br />
<br />
=== No HDMI 5/7.1 Selection for Device ===<br />
<br />
If you are unable to select 5/7.1 channel output for a working HDMI device, then turning off "stream device reading" in {{ic|/etc/pulse/default.pa}} might help. <br />
<br />
See [[#Fallback device is not respected]].<br />
<br />
=== Failed to create sink input: sink is suspended ===<br />
<br />
If you do not have any output sound and receive dozens of errors related to a suspended sink in your {{ic|journalctl -b}} log, then backup first and then delete your user-specific pulse folders:<br />
<br />
$ rm -r ~/.pulse ~/.pulse-cookie ~/.config/pulse<br />
<br />
=== Simultaneous output to multiple sound cards / devices ===<br />
<br />
Simultaneous output to two different devices can be very useful. For example, being able to send audio to your A/V receiver via your graphics card's HDMI output, while also sending the same audio through the analogue output of your motherboard's built-in audio. This is much less hassle than it used to be (in this example, we are using GNOME desktop).<br />
<br />
Using {{Pkg|paprefs}}, simply select "Add virtual output device for simultaneous output on all local sound cards" from under the "Simultaneous Output" tab. Then, under GNOME's "sound settings", select the simultaneous output you have just created.<br />
<br />
If this does not work, try adding the following to {{ic|~/.asoundrc}}:<br />
<br />
pcm.dsp {<br />
type plug<br />
slave.pcm "dmix"<br />
}<br />
<br />
{{Tip|Simultaneous output can also be achieved manually using alsamixer. Disable "auto mute" item, then unmute other output sources you want to hear and increase their volume.}}<br />
<br />
=== Simultaneous output to multiple sinks on the same sound card not working ===<br />
<br />
This can be useful for users who have multiple sound sources and want to play them on different sinks/outputs. <br />
An example use-case for this would be if you play music and also voice chat and want to output music to speakers (in this case Digital S/PDIF) and voice to headphones. (Analog)<br />
<br />
This is sometimes auto detected by PulseAudio but not always. If you know that your sound card can output to both Analog and S/PDIF at the same time and PulseAudio does not have this option in its profiles in pavucontrol, or veromix then you probably need to create a configuration file for your sound card.<br />
<br />
More in detail you need to create a profile-set for your specific sound card.<br />
This is done in two steps mostly.<br />
<br />
* Create udev rule to make PulseAudio choose your PulseAudio configuration file specific to the sound card.<br />
* Create the actual configuration.<br />
<br />
Create a pulseaudio udev rule.<br />
<br />
{{Note|This is only an example for Asus Xonar Essence STX.<br />
Read [[udev]] to find out the correct values.}}<br />
<br />
{{Note|Your configuration file should have lower number than the original PulseAudio rule to take effect.}}<br />
<br />
{{hc|/usr/lib/udev/rules.d/90-pulseaudio-Xonar-STX.rules|<br />
ACTION&#61;&#61;"change", SUBSYSTEM&#61;&#61;"sound", KERNEL&#61;&#61;"card*", \<br />
ATTRS&#123;subsystem_vendor&#125;&#61;&#61;"0x1043", ATTRS&#123;subsystem_device&#125;&#61;&#61;"0x835c", ENV&#123;PULSE_PROFILE_SET&#125;&#61;"asus-xonar-essence-stx.conf" <br />
}}<br />
<br />
Now, create a configuration file. If you bother, you can start from scratch and make it saucy. However you can also use the default configuration file, rename it, and then add your profile there that you know works. Less pretty but also faster.<br />
<br />
To enable multiple sinks for Asus Xonar Essence STX you need only to add this in.<br />
<br />
{{Note|{{ic|asus-xonar-essence-stx.conf}} also includes all code/mappings from {{ic|default.conf}}.}}<br />
<br />
{{hc|/usr/share/alsa-card-profile/mixer/profile-sets/asus-xonar-essence-stx.conf|<br />
[Profile analog-stereo+iec958-stereo]<br />
description &#61; Analog Stereo Duplex + Digital Stereo Output<br />
input-mappings &#61; analog-stereo<br />
output-mappings &#61; analog-stereo iec958-stereo<br />
skip-probe &#61; yes<br />
}}<br />
<br />
This will auto-profile your Asus Xonar Essence STX with default profiles and add your own profile so you can have multiple sinks.<br />
<br />
You need to create another profile in the configuration file if you want to have the same functionality with AC3 Digital 5.1 output.<br />
<br />
[https://www.freedesktop.org/wiki/Software/PulseAudio/Backends/ALSA/Profiles/ See PulseAudio article about profiles]<br />
<br />
=== Some profiles like SPDIF are not enabled by default on the card ===<br />
<br />
Some profiles like IEC-958 (i.e. S/PDIF) may not be enabled by default on the selected sink. Each time the system starts up, the card profile is disabled and the pulseaudio daemon cannot select it.<br />
You have to add the profile selection to you default.pa file. <br />
Verify the card and profile name with :<br />
<br />
$ pacmd list-cards<br />
<br />
Then edit the config to add the profile<br />
<br />
{{hc|~/.config/pulse/default.pa|<br />
## Replace with your card name and the profile you want to activate<br />
set-card-profile alsa_card.pci-0000_00_1b.0 output:iec958-stereo+input:analog-stereo<br />
}}<br />
<br />
Pulse audio will add this profile the pool of available profiles<br />
<br />
=== Only S/PDIF output available ===<br />
<br />
This might happen if PulseAudio use the wrong output device. Firstly, set up proper card profile:<br />
<br />
$ pacmd set-card-profile alsa_card.pci-0000_00_1f.3 output:analog-stereo<br />
<br />
or<br />
<br />
$ pacmd set-card-profile alsa_card.pci-0000_00_1f.3 output:analog-stereo+input:analog-stereo<br />
<br />
Replace {{ic|alsa_card.pci-0000_00_1f.3}} with your card, and {{ic|output:analog-stereo}} or {{ic|output:analog-stereo+input:analog-stereo}} with your profile, remember to choose the profile with analog. Using shell auto completion could help you a lot. One could also use check available cards and profiles with:<br />
<br />
$ pacmd list-cards<br />
<br />
One might also need to set sink port by:<br />
<br />
$ pacmd set-sink-port alsa_output.pci-0000_00_1f.3.analog-stereo analog-output-headphones<br />
<br />
Check available sink ports with:<br />
<br />
$ pacmd list-sinks<br />
<br />
To keep these setting, add them to PulseAudio's configuration file {{ic|default.pa}}.<br />
<br />
{{hc|~/.config/pulse/default.pa|<br />
.include /etc/pulse/default.pa<br />
<br />
set-card-profile alsa_card.pci-0000_00_1f.3 output:analog-stereo+input:analog-stereo<br />
set-sink-port alsa_output.pci-0000_00_1f.3.analog-stereo analog-output-headphones<br />
}}<br />
<br />
=== Crackling or popping USB sound issues ===<br />
<br />
Although not related to PulseAudio, it is also possible that the card is not powered properly by it's USB port, or that it doesn't provide enough bandwidth.<br />
<br />
Try connecting the USB DAC directly to your computer's USB ports, avoiding any hubs or docks.<br />
<br />
== Bluetooth ==<br />
<br />
See [[Bluetooth headset#Troubleshooting]].<br />
<br />
== Applications ==<br />
<br />
=== Audacity ===<br />
<br />
To work with PulseAudio, Audacity requires the {{Pkg|pulseaudio-alsa}} is installed. This provides the {{ic|1=pulse:...}} playback and recording devices.<br />
<br />
When starting Audacity you may find that your headphones no longer work. This can be because Audacity is trying to use them as a recording device. To fix this, open Audacity, then set its recording device to {{ic|1=pulse:Internal Mic:0}}.<br />
<br />
Under some circumstances, playback may be distorted, very fast, or freeze, as discussed in the [http://wiki.audacityteam.org/wiki/Linux_Issues#ALSA_and_other_sound_systems Audacity Wiki's Linux Issues page].<br />
<br />
The solution proposed in this page may work: start Audacity with:<br />
<br />
$ env PULSE_LATENCY_MSEC=30 audacity<br />
<br />
If the solution above does not fix this issue, one may wish to temporarily disable pulseaudio while running Audacity by using the {{ic|pasuspender}} command:<br />
<br />
$ pasuspender -- audacity<br />
<br />
Then, be sure to select the appropriate ALSA input and output devices in Audacity.<br />
<br />
See also [[#Setting the default fragment number and buffer size in PulseAudio]].<br />
<br />
=== OpenAL ===<br />
<br />
Some games may prevent you from switching the output device. Trying to move the sink with {{ic|pactl}} gives the following error:<br />
<br />
pactl move-sink-input 11 alsa_output.pci-0000_01_00.1.hdmi-stereo-extra1<br />
Failure: Invalid argument<br />
<br />
OpenAL needs to be configured to allow moving the sink:<br />
<br />
{{hc|head=~/.alsoftrc|output=[pulse]<br />
allow-moves = true<br />
}}<br />
<br />
== Other Issues ==<br />
<br />
=== Cannot update configuration of sound device in pavucontrol ===<br />
<br />
{{Pkg|pavucontrol}} is a handy GUI utility for configuring PulseAudio. Under its 'Configuration' tab, you can select different profiles for each of your sound devices e.g. analogue stereo, digital output (IEC958), HDMI 5.1 Surround etc.<br />
<br />
However, you may run into an instance where selecting a different profile for a card results in the pulse daemon crashing and auto restarting without the new selection "sticking". If this occurs, use the other useful GUI tool, {{Pkg|paprefs}}, to check under the "Simultaneous Output" tab for a virtual simultaneous device. If this setting is active (checked), it will prevent you changing any card's profile in pavucontrol. Uncheck this setting, then adjust your profile in pavucontrol prior to re-enabling simultaneous output in paprefs.<br />
<br />
=== Failed to create sink input: sink is suspended ===<br />
<br />
If you do not have any output sound and receive dozens of errors related to a suspended sink in your {{ic|journalctl -b}} log, then backup first and then delete your user-specific pulse folders:<br />
<br />
$ rm -r ~/.pulse ~/.pulse-cookie ~/.config/pulse<br />
<br />
=== Pulse overwrites ALSA settings ===<br />
<br />
PulseAudio usually overwrites the ALSA settings — for example set with alsamixer — at start-up, even when the ALSA daemon is loaded. Since there seems to be no other way to restrict this behaviour, a workaround is to restore the ALSA settings again after PulseAudio has started. Add the following command to {{ic|.xinitrc}} or {{ic|.bash_profile}} or any other [[autostart]] file:<br />
<br />
restore_alsa() {<br />
while [ -z "$(pidof pulseaudio)" ]; do<br />
sleep 0.5<br />
done<br />
alsactl -f /var/lib/alsa/asound.state restore <br />
}<br />
restore_alsa &<br />
<br />
=== Daemon startup failed ===<br />
<br />
Try resetting PulseAudio:<br />
<br />
$ rm -rf /tmp/pulse* ~/.pulse* ~/.config/pulse<br />
$ pulseaudio -k<br />
$ pulseaudio --start<br />
<br />
* Check that options for sinks are set up correctly.<br />
* If you configured in default.pa to load and use the OSS modules then check with {{Pkg|lsof}} that {{ic|/dev/dsp}} device is not used by another application.<br />
* Set a preferred working resample method. Use {{ic|pulseaudio --dump-resample-methods}} to see a list with all available resample methods you can use.<br />
* To get details about currently appeared unfixed errors or just get status of daemon use commands like {{ic|pax11publish -d}} and {{ic|pulseaudio -v}} where {{ic|v}} option can be used multiple time to set verbosity of log output equal to the {{ic|1=--log-level[=LEVEL]}} option where LEVEL is from 0 to 4. See the [[#Outputs by PulseAudio error status check utilities]] section.<br />
<br />
See also man pages for {{man|1|pax11publish}} and {{man|1|pulseaudio}} for more details.<br />
<br />
==== Outputs by PulseAudio error status check utilities ====<br />
<br />
If the {{ic|pax11publish -d}} shows error like:<br />
<br />
N: [pulseaudio] main.c: User-configured server at "user", refusing to start/autospawn.<br />
<br />
then run {{ic|pax11publish -r}} command then could be also good to logout and login again.<br />
<br />
If the {{ic|pulseaudio -vvvv}} command shows error like:<br />
<br />
E: [pulseaudio] module-udev-detect.c: You apparently ran out of inotify watches, probably because Tracker/Beagle took them all away. I wished people would do their homework first and fix inotify before using it for watching whole directory trees which is something the current inotify is certainly not useful for. Please make sure to drop the Tracker/Beagle guys a line complaining about their broken use of inotify.<br />
<br />
This can be resolved temporary by:<br />
<br />
$ echo 100000 > /proc/sys/fs/inotify/max_user_watches<br />
<br />
For permanent use save settings in the ''99-sysctl.conf'' file:<br />
<br />
{{hc|/etc/sysctl.d/99-sysctl.conf|2=<br />
# Increase inotify max watchs per user<br />
fs.inotify.max_user_watches = 100000<br />
}}<br />
<br />
{{Warning|It may cause much bigger consumption of memory by kernel.}}<br />
<br />
'''See also''' <br />
<br />
* [http://www.linuxinsight.com/proc_sys_fs_inotify.html proc_sys_fs_inotify]{{Dead link|2020|04|01|status=domain name not resolved}} and [http://lwn.net/Articles/604686/ dnotify, inotify]- more details about ''inotify/max_user_watches''<br />
* [https://stackoverflow.com/questions/535768/what-is-a-reasonable-amount-of-inotify-watches-with-linux?answertab=votes#tab-top reasonable amount of inotify watches with Linux]<br />
* {{man|7|inotify}} - man page<br />
<br />
=== Daemon already running ===<br />
<br />
On some systems, PulseAudio may be started multiple times. journalctl will report:<br />
<br />
[pulseaudio] pid.c: Daemon already running.<br />
<br />
Make sure to use only one method of autostarting applications. {{Pkg|pulseaudio}} includes these files:<br />
<br />
* {{ic|/etc/X11/xinit/xinitrc.d/pulseaudio}}<br />
* {{ic|/etc/xdg/autostart/pulseaudio.desktop}}<br />
* {{ic|/etc/xdg/autostart/pulseaudio-kde.desktop}}<br />
<br />
Also check user autostart files and directories, such as [[xinitrc]], {{ic|~/.config/autostart/}} etc.<br />
<br />
=== Subwoofer stops working after end of every song ===<br />
<br />
Known issue: https://bugs.launchpad.net/ubuntu/+source/pulseaudio/+bug/494099<br />
<br />
To fix this, {{ic|1=enable-lfe-remixing = yes}} must be set as described in [[#Choppy sound with analog surround sound setup]].<br />
<br />
=== Unable to select surround configuration other than "Surround 4.0" ===<br />
<br />
If you are unable to set 5.1 surround output in pavucontrol because it only shows "Analog Surround 4.0 Output", open the ALSA mixer and change the output configuration there to 6 channels. Then restart pulseaudio, and pavucontrol will list many more options.<br />
<br />
=== Realtime scheduling ===<br />
<br />
If rtkit does not work, you can manually set up your system to run PulseAudio with real-time scheduling, which can help performance. To do this, add the following lines to {{ic|/etc/security/limits.conf}}:<br />
<br />
@pulse-rt - rtprio 9<br />
@pulse-rt - nice -11<br />
<br />
Afterwards, you need to add your user to the {{ic|pulse-rt}} group:<br />
<br />
# gpasswd -a <user> pulse-rt<br />
<br />
=== pactl "invalid option" error with negative percentage arguments ===<br />
<br />
{{ic|pactl}} commands that take negative percentage arguments will fail with an 'invalid option' error. Use the standard shell '--' pseudo argument<br />
to disable argument parsing before the negative argument. ''e.g.'' {{ic|pactl set-sink-volume 1 -- -5%}}.<br />
<br />
=== Fallback device is not respected ===<br />
<br />
PulseAudio does not have a true default device. Instead it uses a [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/DefaultDevice/ "fallback"], which only applies to new sound streams. This means previously run applications are not affected by the newly set fallback device.<br />
<br />
{{Pkg|gnome-control-center}}, {{Pkg|mate-media}} and {{AUR|paswitch}} handle this gracefully. Alternatively: <br />
<br />
1. Move the old streams in {{Pkg|pavucontrol}} manually to the new sound card.<br />
<br />
2. Stop Pulse, erase the "stream-volumes" in {{ic|~/.config/pulse}} and/or {{ic|~/.pulse}} and restart Pulse. This also resets application volumes.<br />
<br />
3. Disable stream device reading. This may be not wanted when using different soundcards with different applications.<br />
<br />
{{hc|/etc/pulse/default.pa|2=<br />
load-module module-stream-restore restore_device=false<br />
}}<br />
<br />
=== RTP/UDP packet flood ===<br />
<br />
In some cases the default configuration might flood the network with UDP packets.[https://gitlab.freedesktop.org/pulseaudio/pulseaudio/issues/505] <br />
To fix this problem, launch {{ic|paprefs}} and disable "Multicast/RTP Sender".[https://bugs.launchpad.net/ubuntu/+source/pulseaudio/+bug/411688/comments/36]<br />
<br />
=== New audio source streams auto-select to "blank" stream instead of BT headphones ===<br />
<br />
Example scenario: Restarting, stopping, fast forwarding a Youtube video on Firefox 68.0.1 on KDE + Arch might set the "sink" associated with it in PulseAudio to a blank state, and then output sound over laptop speakers. Inconsistently reproducible on Dell 9360. <br />
<br />
Fix seems to be to kill and restart {{ic|pulseaudio}}.<br />
<br />
pulseaudio -k<br />
pulseaudio --start</div>Edhhttps://wiki.archlinux.org/index.php?title=Talk:PipeWire&diff=651857Talk:PipeWire2021-02-10T20:49:32Z<p>Edh: /* Troubleshoot: dbus issue */ rm closed</p>
<hr />
<div>== 0.3.16 pulse replacement ==<br />
<br />
For the pulse-dropin-replacement to work, you probably also need to clear your users config, {{ic|~/.config/pulse}} (like in delete/move the content) - That is created by pulseaudio for pulseaudio.<br />
Otherwise the server could be unable to start.<br />
<br />
[[User:Fabis.cafe|Fabis.cafe]] ([[User talk:Fabis.cafe|talk]]) 14:12, 23 November 2020 (UTC)<br />
<br />
----<br />
<br />
I just installed the pulse replacement and while everything seems to be working just fine, the only problem is gnome-shell doesn't seem to be able to see the pipewrire pulse server, thus the volume control in the top right system menu is absent and keyboard media keys for volume don't work either. I think this should be addressed in the troubleshooting section with a solution if there is one.<br />
<br />
Interestingly enough gnome-control-center is able to control the volume as well as other typical pulseaudio parameters.<br />
<br />
UPDATE: running {{ic|killall pipewire-pulse; killall pipewire}} restarts the pipewire pulse daemon and makes the volume control in gnome-shell work as expected. This of course is a workaround and not a proper solution.<br />
<br />
UPDATE 2: the above makes the volume control menu item and shortcuts appear, but adjusting the volume does nothing.<br />
<br />
[[User:GabMus|GabMus]] ([[User talk:GabMus|talk]]) 09:39, 3 December 2020 (UTC)<br />
<br />
:I don't see volume indicator in gnome-shell/wayland but I'm able to control volume with media keys. -- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 15:55, 3 December 2020 (UTC)<br />
<br />
:: Possibly related: https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/426 [[User:Hexchain|Hexchain]] ([[User talk:Hexchain|talk]]) 18:05, 3 December 2020 (UTC)<br />
<br />
: Solved, refer to the latest change I made in the main page, found the solution thanks to Hexchain's link. -- [[User:GabMus|GabMus]] ([[User talk:GabMus|talk]]) 19:55, 4 December 2020 (UTC)<br />
<br />
== aptX support ==<br />
<br />
Does `pipewire` support low latency/high quality bluetooth codecs (aptX, LDAC, ...) ? <br />
<br />
along the lines of https://aur.archlinux.org/packages/pulseaudio-modules-bt-git/ <br />
<br />
If yes, how to configure it? <br />
<br />
along the lines of https://freedesktop.org/software/pulseaudio/pavucontrol/ <br />
<br />
[[User:NTia89|nTia89]] ([[User talk:NTia89|talk]]) 21:23, 3 December 2020 (UTC)<br />
<br />
: I switched to PipeWire and currently bluetooth sound poorly works: high latency and low quality.<br />
: Actually open bug/enhancement in pipewire bugtracker [https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/136].<br />
[[User:NTia89|nTia89]] ([[User talk:NTia89|talk]]) 10:20, 5 December 2020 (UTC)<br />
<br />
: It does now but currently there is no way to select a codec manually. It uses (the first supported?) codec in this order: LDAC, AptX HD, AptX, SBC. You can check for the current codec with {{ic|pactl list sinks}} IIRC. [[User:Hexchain|Hexchain]] ([[User talk:Hexchain|talk]]) 00:41, 21 December 2020 (UTC)</div>Edh