https://wiki.archlinux.org/api.php?action=feedcontributions&user=PhilippD&feedformat=atomArchWiki - User contributions [en]2024-03-29T14:53:02ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=NetworkManager&diff=706782NetworkManager2021-12-20T15:59:08Z<p>PhilippD: /* Configuration */ add section on how to tell NetworkManager not to manage some network interfaces</p>
<hr />
<div>[[Category:Network managers]]<br />
[[Category:Red Hat]]<br />
[[de:Networkmanager]]<br />
[[es:NetworkManager]]<br />
[[fr:NetworkManager]]<br />
[[ja:NetworkManager]]<br />
[[pt:NetworkManager]]<br />
[[zh-hans:NetworkManager]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related articles end}}<br />
[https://networkmanager.dev/ NetworkManager] is a program for providing detection and configuration for systems to automatically connect to networks. NetworkManager's functionality can be useful for both wireless and wired networks. For wireless networks, NetworkManager prefers known wireless networks and has the ability to switch to the most reliable network. NetworkManager-aware applications can switch from online and offline mode. NetworkManager also prefers wired connections over wireless ones, has support for modem connections and certain types of VPN. NetworkManager was originally developed by Red Hat and now is hosted by the [[GNOME]] project.<br />
<br />
{{Expansion|Clear text storage of secrets is not limited to just Wi-Fi passwords. The secrets are stored in files (and folder) only accesible to root.}}<br />
<br />
{{Warning|By default, Wi-Fi passwords are stored in clear text, see [[#Encrypted Wi-Fi passwords]].}}<br />
<br />
== Installation ==<br />
<br />
NetworkManager can be [[install]]ed with the package {{Pkg|networkmanager}}, which contains a daemon, a command line interface ({{ic|nmcli}}) and a curses‐based interface ({{ic|nmtui}}).<br />
<br />
=== Enable NetworkManager ===<br />
<br />
After installation, you should [[start/enable]] {{ic|NetworkManager.service}}. Once the NetworkManager daemon is started, it will automatically connect to any available "system connections" that have already been configured. Any "user connections" or unconfigured connections will need ''nmcli'' or an applet to configure and connect.<br />
<br />
{{Note|If [[systemd-resolved]] is not [[started]], an error message will start flooding your logs. See [[#Unit dbus-org.freedesktop.resolve1.service not found]] for more info.}}<br />
<br />
=== Additional interfaces ===<br />
<br />
* {{Pkg|nm-connection-editor}} for a graphical user interface,<br />
* {{Pkg|network-manager-applet}} for a system tray applet ({{ic|nm-applet}}).<br />
<br />
{{Note|You must ensure that no other service that wants to configure the network is running; in fact, multiple networking services will conflict. You can find a list of the currently running services with {{ic|1=systemctl --type=service}} and then [[stop]] them. See [[#Configuration]] to enable the NetworkManager service.}}<br />
<br />
=== Mobile broadband support ===<br />
<br />
NetworkManager uses [[ModemManager]] for mobile broadband connection support.<br />
<br />
[[Install]] {{Pkg|modemmanager}} and {{Pkg|usb_modeswitch}}. Afterwards [[enable]] and [[start]] {{ic|ModemManager.service}}.<br />
<br />
It may be necessary to [[restart]] {{ic|NetworkManager.service}} for it to detect ModemManager. After you restart it, re-plug the modem again and it should be recognized. <br />
<br />
Add connections from a front-end (e.g. {{Pkg|nm-connection-editor}}) and select mobile broadband as the connection type. After selecting your ISP and billing plan, [[Wikipedia:Access Point Name|APN]] and other settings should be filled in automatically using information from {{Pkg|mobile-broadband-provider-info}}.<br />
<br />
=== PPPoE / DSL support ===<br />
<br />
[[Install]] {{Pkg|rp-pppoe}} package for PPPoE / DSL connection support. To actually add PPPoE connection, use {{ic|1=nm-connection-editor}} and add new DSL/PPPoE connection.<br />
<br />
=== VPN support ===<br />
<br />
NetworkManager since version 1.16 has native support for [[WireGuard]], all it needs is the {{ic|wireguard}} kernel module. Read the [https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager blog post] for details.<br />
<br />
Support for other VPN types is based on a plug-in system. They are provided in the following packages:<br />
<br />
* {{Pkg|networkmanager-openconnect}} for [[OpenConnect]]<br />
* [[networkmanager-openvpn]] for [[OpenVPN]]<br />
* {{Pkg|networkmanager-pptp}} for [[PPTP Client]]<br />
* {{Pkg|networkmanager-vpnc}} for [[Vpnc]]<br />
* {{Pkg|networkmanager-strongswan}} for [[strongSwan]]<br />
* {{AUR|networkmanager-fortisslvpn-git}}<br />
* {{AUR|networkmanager-iodine-git}}<br />
* {{AUR|networkmanager-libreswan}}<br />
* {{Pkg|networkmanager-l2tp}}<br />
* {{AUR|networkmanager-ssh-git}}<br />
* {{Pkg|network-manager-sstp}}<br />
<br />
{{Warning|1=There are a lot of [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues?search=VPN&state=opened bugs] related to VPN support. Check the daemon processes options set via the GUI correctly and double-check with each package release.}}<br />
<br />
{{Note|To have fully functioning DNS resolution when using VPN, you should set up [[#DNS caching and conditional forwarding|conditional forwarding]].}}<br />
<br />
== Usage ==<br />
<br />
NetworkManager comes with {{man|1|nmcli}} and {{man|1|nmtui}}.<br />
<br />
=== nmcli examples ===<br />
<br />
List nearby Wi-Fi networks:<br />
<br />
$ nmcli device wifi list<br />
<br />
Connect to a Wi-Fi network:<br />
<br />
$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password''<br />
<br />
Connect to a hidden Wi-Fi network:<br />
<br />
$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password'' hidden yes<br />
<br />
Connect to a Wi-Fi on the {{ic|wlan1}} interface:<br />
<br />
$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password'' ifname wlan1 ''profile_name''<br />
<br />
Disconnect an interface:<br />
<br />
$ nmcli device disconnect ifname eth0<br />
<br />
Get a list of connections with their names, UUIDs, types and backing devices:<br />
<br />
$ nmcli connection show<br />
<br />
Activate a connection (i.e. connect to a network with an existing profile):<br />
<br />
$ nmcli connection up ''name_or_uuid''<br />
<br />
Delete a connection:<br />
<br />
$ nmcli connection delete ''name_or_uuid''<br />
<br />
See a list of network devices and their state:<br />
<br />
$ nmcli device<br />
<br />
Turn off Wi-Fi:<br />
<br />
$ nmcli radio wifi off<br />
<br />
=== Edit a connection ===<br />
<br />
For a comprehensive list of settings, see {{man|5|nm-settings}}.<br />
<br />
Firstly you need to get list of connections:<br />
<br />
{{hc|$ nmcli connection|<nowiki><br />
NAME UUID TYPE DEVICE<br />
Wired connection 2 e7054040-a421-3bef-965d-bb7d60b7cecf ethernet enp5s0<br />
Wired connection 1 997f2782-f0fc-301d-bfba-15421a2735d8 ethernet enp0s25<br />
MY-HOME-WIFI-5G 92a0f7b3-2eba-49ab-a899-24d83978f308 wifi --<br />
</nowiki>}}<br />
<br />
Here you can use the first column as connection-id used later. In this example we pick {{ic|Wired connection 2}} as a connection-id.<br />
<br />
You have three methods to configure a connection {{ic|Wired connection 2}} after it has been created:<br />
<br />
; nmcli interactive editor<br />
: {{ic|nmcli connection edit 'Wired connection 2'}}.<br> Usage is well documented from the editor.<br />
<br />
; nmcli command line interface<br />
: {{ic|nmcli connection modify 'Wired connection 2' ''setting''.''property'' ''value''}}. See {{man|1|nmcli}} for usage. For example you can change its IPv4 route metric to 200 using {{ic|nmcli connection modify 'Wired connection 2' ipv4.route-metric 200}} command.<br />
To remove a setting pass an empty field ("") to it like this:<br />
: {{ic|nmcli connection modify 'Wired connection 2' ''setting''.''property'' ""}}<br />
<br />
; Connection file<br />
: In {{ic|/etc/NetworkManager/system-connections/}}, modify the corresponding {{ic|Wired connection 2.nmconnection}} file .<br> Do not forget to reload the configuration file with {{ic|nmcli connection reload}}.<br />
<br />
== Front-ends ==<br />
<br />
To configure and have easy access to NetworkManager, most users will want to install an applet. This GUI front-end usually resides in the system tray (or notification area) and allows network selection and configuration of NetworkManager. Various desktop environments have their own applet. Otherwise you can use [[#nm-applet]].<br />
<br />
=== GNOME ===<br />
<br />
[[GNOME]] has a built-in tool, accessible from the Network settings.<br />
<br />
=== KDE Plasma ===<br />
<br />
[[Install]] the {{Pkg|plasma-nm}} package. After that, add it to the KDE taskbar via the ''Panel options > Add widgets > Networks'' menu.<br />
<br />
=== nm-applet ===<br />
<br />
{{Pkg|network-manager-applet}} is a GTK 3 front-end which works under Xorg environments with a systray.<br />
<br />
To store connection secrets install and configure [[GNOME/Keyring]].<br />
<br />
Be aware that after enabling the tick-box option {{ic|Make available to other users}} for a connection, NetworkManager stores the password in plain-text, though the respective file is accessible only to root (or other users via {{ic|nm-applet}}). See [[#Encrypted Wi-Fi passwords]].<br />
<br />
In order to run {{ic|nm-applet}} without a systray, you can use {{Pkg|trayer}} or {{Pkg|stalonetray}}. For example, you can add a script like this one in your path:<br />
<br />
{{hc|nmgui|<nowiki><br />
#!/bin/sh<br />
nm-applet 2>&1 > /dev/null &<br />
stalonetray 2>&1 > /dev/null<br />
killall nm-applet<br />
</nowiki>}}<br />
<br />
When you close the ''stalonetray'' window, it closes {{ic|nm-applet}} too, so no extra memory is used once you are done with network settings.<br />
<br />
The applet can show notifications for events such as connecting to or disconnecting from a WiFi network. For these notifications to display, ensure that you have a notification server installed - see [[Desktop notifications]]. If you use the applet without a notification server, you might see some messages in stdout/stderr, and the app might hang. See [https://bugzilla.gnome.org/show_bug.cgi?id=788313].<br />
<br />
In order to run {{ic|nm-applet}} with such notifications disabled, start the applet with the following command:<br />
<br />
$ nm-applet --no-agent<br />
<br />
{{Tip|{{ic|nm-applet}} might be started automatically with a [[XDG Autostart|autostart desktop file]], to add the --no-agent option modify the Exec line there, i.e.<br />
<br />
{{bc|1=Exec=nm-applet --no-agent}}<br />
<br />
}}<br />
<br />
{{Warning|On [[i3]], if nm-applet is started with the {{ic|--no-agent}} option, it is not possible to connect to a new encrypted WiFi network by clicking on the item list because no password input dialogue window will pop out. [[journal]] will show {{ic|no secrets: No agents were available for this request}}.}}<br />
<br />
==== Appindicator ====<br />
<br />
As of version 1.18.0 Appindicator support is [https://github.com/archlinux/svntogit-packages/commit/7640a2bd557fe84813207ef4d5e35bb5aece6c54 available] in the official {{Pkg|network-manager-applet}} package. To use nm-applet in an Appindicator environment start the applet with the following command:<br />
<br />
$ nm-applet --indicator<br />
<br />
=== networkmanager-dmenu ===<br />
<br />
Alternatively there is {{AUR|networkmanager-dmenu-git}} which is a small script to manage NetworkManager connections with [[dmenu]] or [[rofi]] instead of {{ic|nm-applet}}. It provides all essential features such as connection to existing NetworkManager wifi or wired connections, connect to new wifi connections, requests passphrase if required, connect to existing VPN connections, enable/disable networking, launch ''nm-connection-editor'' GUI, connect to Bluetooth networks.<br />
<br />
== Configuration ==<br />
<br />
NetworkManager will require some additional steps to be able run properly. Make sure you have configured {{ic|/etc/hosts}} as described in [[Network configuration#Set the hostname]] section.<br />
<br />
NetworkManager has a global configuration file at {{ic|/etc/NetworkManager/NetworkManager.conf}}. Additional configuration files can be placed in {{ic|/etc/NetworkManager/conf.d/}}. Usually no configuration needs to be done to the global defaults.<br />
<br />
After editing a configuration file, the changes can be applied by running:<br />
<br />
# nmcli general reload<br />
<br />
=== NetworkManager-wait-online ===<br />
Enabling {{ic|NetworkManager.service}} also enables {{ic|NetworkManager-wait-online.service}}, which is a oneshot system service that waits for the network to be configured. The latter has {{ic|1=WantedBy=network-online.target}}, so it will finish only when {{ic|network-online.target}} itself is enabled or pulled in by some other unit. See also [[systemd#Running services after the network is up]].<br />
<br />
By default, {{ic|NetworkManager-wait-online.service}} waits for NetworkManager startup to complete, rather than waiting for network connectivity specifically (see {{man|1|nm-online}}). If {{ic|NetworkManager-wait-online.service}} finishes before the network is really up, resulting in failed services on boot, [[extend the unit]] to remove the {{ic|-s}} from the {{ic|ExecStart}} line:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/bin/nm-online -q<br />
<br />
Be aware that this can cause [https://lists.fedoraproject.org/archives/list/users@lists.fedoraproject.org/thread/EGC324JD3HJCGVN7J55WYPRLFDA3TP7N/ other issues].<br />
<br />
In some cases, the service will still fail to start successfully on boot due to the timeout setting being too short. [[Edit]] the service to change {{ic|NM_ONLINE_TIMEOUT}} from {{ic|60}} to a higher value.<br />
<br />
=== Set up PolicyKit permissions ===<br />
<br />
See [[General troubleshooting#Session permissions]] for setting up a working session.<br />
<br />
With a working session, you have several options for granting the necessary privileges to NetworkManager:<br />
<br />
* ''Option 1.'' Run a [[Polkit]] authentication agent when you log in, such as {{ic|/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1}} (part of {{Pkg|polkit-gnome}}). You will be prompted for your password whenever you add or remove a network connection.<br />
* ''Option 2.'' [[Users and groups#Group management|Add]] yourself to the {{ic|wheel}} group. You will not have to enter your password, but your user account may be granted other permissions as well, such as the ability to use [[sudo]] without entering the root password.<br />
* ''Option 3.'' [[Users and groups#Group management|Add]] yourself to the {{ic|network}} group and create the following file:<br />
<br />
{{hc|/etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
</nowiki>}}<br />
<br />
: All users in the {{ic|network}} group will be able to add and remove networks without a password. This will not work under [[systemd]] if you do not have an active session with ''systemd-logind''.<br />
<br />
=== Proxy settings ===<br />
<br />
NetworkManager does not directly handle proxy settings, but if you are using [[GNOME]] or [[KDE]], you could use [http://marin.jb.free.fr/proxydriver/ proxydriver] which handles proxy settings using NetworkManager's information. proxydriver is found in the package {{AUR|proxydriver}}.<br />
<br />
In order for ''proxydriver'' to be able to change the proxy settings, you would need to execute this command, as part of the GNOME startup process (see [[GNOME#Autostart]]).<br />
<br />
xhost +si:localuser:''username''<br />
<br />
See also [[Proxy settings]].<br />
<br />
=== Checking connectivity ===<br />
<br />
NetworkManager can try to reach a webserver after connecting to a network in order to determine if it is e.g behind a captive portal. The default host (configured in {{ic|/usr/lib/NetworkManager/conf.d/20-connectivity.conf}}) is [https://ping.archlinux.org ping.archlinux.org]. To use a different webserver or to disable connectivity checking, create {{ic|/etc/NetworkManager/conf.d/20-connectivity.conf}}, see {{man|5|NetworkManager.conf|CONNECTIVITY SECTION}}. Below is an example of using GNOME servers (it does not require the use of [[GNOME]]):<br />
<br />
{{hc|/etc/NetworkManager/conf.d/20-connectivity.conf|<nowiki><br />
[connectivity]<br />
uri=http://nmcheck.gnome.org/check_network_status.txt<br />
</nowiki>}}<br />
<br />
To disable NetworkManager's connectivity check, use the following configuration. This can be useful when connected to a VPN that blocks connectivity checks.<br />
<br />
{{Accuracy|According to {{man|5|NetworkManager.conf|CONNECTIVITY SECTION}}, the option is {{ic|1=enabled=false}} not {{ic|1=.set.enabled=false}}.}}<br />
<br />
{{hc|/etc/NetworkManager/conf.d/20-connectivity.conf|<nowiki><br />
[connectivity] <br />
.set.enabled=false<br />
</nowiki>}}<br />
<br />
{{Note|Although automatic connectivity checks are a potential privacy leak, Arch Linux's default connectivity URL is committed to not logging any access. See [https://gitlab.archlinux.org/archlinux/infrastructure/-/commit/fabccd0f61e5dea3925e8a0c6a46d56d5750c121#a4f34381bbb18ea77bfb3dd11a8aeca707078fca_0_26] [https://gitlab.archlinux.org/archlinux/infrastructure/-/blob/master/roles/ping/templates/nginx.d.conf.j2].}}<br />
<br />
=== Captive portals ===<br />
<br />
{{Style|Complex scripts should not be maintained on the wiki.}}<br />
<br />
For those behind a [[Wikipedia:Captive portal|captive portal]], the desktop manager may automatically open a window asking for credentials. If your desktop does not, you can use {{Pkg|capnet-assist}} package (however, it currently it has a broken NetworkManager dispatcher script). Alternatively, you can create a NetworkManager dispatcher script with the following content:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/90-open_captive_portal|<nowiki><br />
#!/bin/sh -e<br />
# Script to dispatch NetworkManager events<br />
#<br />
# Runs shows a login webpage on walled garden networks.<br />
# See NetworkManager(8) for further documentation of the dispatcher events.<br />
<br />
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin<br />
<br />
if [ -x "/usr/bin/logger" ]; then<br />
logger="/usr/bin/logger -s -t captive-portal"<br />
else<br />
logger=":"<br />
fi<br />
<br />
wait_for_process() {<br />
PNAME=$1<br />
while [ -z "$(/usr/bin/pgrep $PNAME)" ]; do<br />
sleep 3;<br />
done<br />
}<br />
<br />
#launch the browser, but on boot we need to wait that nm-applet starts<br />
start_browser() {<br />
local user="$1"<br />
local display="$2"<br />
<br />
export DISPLAY="$display"<br />
wait_for_process nm-applet<br />
<br />
export XAUTHORITY="/home/$user/.Xauthority"<br />
<br />
$logger "Running browser as '$user' with display '$display' to login in captive portal"<br />
sudo -u "$user" --preserve-env=DISPLAY,XAUTHORITY -H xdg-open http://capnet.elementary.io 2>&1 > /dev/null<br />
}<br />
<br />
# Run the right scripts<br />
case "$2" in<br />
connectivity-change)<br />
$logger -p user.debug "dispatcher script triggered on connectivity change: $CONNECTIVITY_STATE"<br />
if [ "$CONNECTIVITY_STATE" = "PORTAL" ]; then<br />
# Match last column of who's output with ' :[at least one digit] '<br />
who | awk '$NF ~ /\(:[0-9]+\)/ { print $1 " " substr($NF, 2, length($NF)-2) };' | \<br />
while read user display; do<br />
start_browser $user $display || $logger -p user.err "Failed for user: '$user' display: '$display'"<br />
done<br />
fi<br />
;;<br />
*)<br />
# In a down phase<br />
exit 0<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
You will need to [[restart]] {{ic|NetworkManager.service}} or reboot for this to start working. Once you do, the dispatcher script should open a login window once it detects you are behind a captive portal.<br />
<br />
Another solution is {{AUR|captive-browser-git}} based on Google Chrome.<br />
<br />
=== DHCP client ===<br />
<br />
By default NetworkManager uses its internal DHCP client. The internal DHCPv4 plugin is based on the [https://nettools.github.io/n-dhcp4/ nettools' n-dhcp4] library, while the internal DHCPv6 plugin is made from code based on systemd-networkd.<br />
<br />
To use a different DHCP client [[install]] one of the alternatives:<br />
<br />
* {{Pkg|dhclient}} - [[dhclient]].<br />
* {{Pkg|dhcpcd}} - [[dhcpcd]].<br />
<br />
To change the DHCP client backend, set the option {{ic|1=main.dhcp=''dhcp_client_name''}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}. E.g.:<br />
<br />
{{hc|1=/etc/NetworkManager/conf.d/dhcp-client.conf|2=<br />
[main]<br />
dhcp=dhclient<br />
}}<br />
<br />
{{Note|<br />
* NetworkManger does not support using dhcpcd for IPv6. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/5 NetworkManager issue #5]. If dhcpcd is set as the DHCP client, NetworkManager will use the internal DHCP client for DHCPv6.<br />
* Do not enable the systemd units shipped with the {{Pkg|dhclient}} and {{Pkg|dhcpcd}} packages. They will conflict with NetworkManager, see the note in [[#Installation]] for details.<br />
}}<br />
<br />
=== DNS management ===<br />
<br />
NetworkManager's DNS management is described in the GNOME project's wiki page—[https://wiki.gnome.org/Projects/NetworkManager/DNS Projects/NetworkManager/DNS].<br />
<br />
==== DNS caching and conditional forwarding ====<br />
<br />
NetworkManager has a plugin to enable DNS caching and conditional forwarding ([https://gitlab.freedesktop.org/NetworkManager/NetworkManager/merge_requests/143 previously] called "split DNS" in NetworkManager's documentation) using [[dnsmasq]] or [[systemd-resolved]]. The advantages of this setup is that DNS lookups will be cached, shortening resolve times, and DNS lookups of VPN hosts will be routed to the relevant VPN's DNS servers. This is especially useful if you are connected to more than one VPN.<br />
<br />
{{Note|If {{ic|/etc/resolv.conf}} is a symlink to {{ic|/run/systemd/resolve/stub-resolv.conf}}, {{ic|/run/systemd/resolve/resolv.conf}},{{ic|/lib/systemd/resolv.conf}} or {{ic|/usr/lib/systemd/resolv.conf}}, NetworkManager will choose systemd-resolved automatically. To use dnsmasq, you must first remove that symlink, then restart NetworkManager.}}<br />
<br />
===== dnsmasq =====<br />
<br />
Make sure {{Pkg|dnsmasq}} has been installed. Then set {{ic|1=main.dns=dnsmasq}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/dns.conf|2=<br />
[main]<br />
dns=dnsmasq<br />
}}<br />
<br />
Now run {{ic|nmcli general reload}} as root. NetworkManager will automatically start dnsmasq and add {{ic|127.0.0.1}} to {{ic|/etc/resolv.conf}}. The original DNS servers can be found in {{ic|/run/NetworkManager/no-stub-resolv.conf}}. You can verify dnsmasq is being used by doing the same DNS lookup twice with {{ic|drill example.com}} and verifying the server and query times.<br />
<br />
{{Note|<br />
* You do not need to start {{ic|dnsmasq.service}} or edit {{ic|/etc/dnsmasq.conf}}. NetworkManager will start dnsmasq without using the systemd service and without reading the dnsmasq's default configuration file(s).<br />
* The dnsmasq instance started by NetworkManager will bind to {{ic|127.0.0.1:53}}, you cannot run any other software (including {{ic|dnsmasq.service}}) on the same address and port.<br />
}}<br />
<br />
====== Custom dnsmasq configuration ======<br />
<br />
Custom configurations can be created for ''dnsmasq'' by creating configuration files in {{ic|/etc/NetworkManager/dnsmasq.d/}}. For example, to change the size of the DNS cache (which is stored in RAM):<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/cache.conf|2=<br />
cache-size=1000<br />
}}<br />
<br />
You can check the configuration file syntax with:<br />
<br />
dnsmasq --test --conf-file=/dev/null --conf-dir=/etc/NetworkManager/dnsmasq.d<br />
<br />
See {{man|8|dnsmasq}} for all available options.<br />
<br />
====== IPv6 ======<br />
<br />
{{Accuracy|This does not solve the issue because NetworkManager does not add {{ic|::1}} to {{ic|/etc/resolv.conf}}. Unless {{ic|@::1}} is manually passed to drill, it will still fail with {{ic|Error: error sending query: No (valid) nameservers defined in the resolver}}.}}<br />
<br />
Enabling {{ic|dnsmasq}} in NetworkManager may break IPv6-only DNS lookups (i.e. {{ic|drill -6 [hostname]}}) which would otherwise work. In order to resolve this, creating the following file will configure ''dnsmasq'' to also listen to the IPv6 loopback:<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/ipv6-listen.conf|2=<br />
listen-address=::1<br />
}}<br />
<br />
In addition, {{ic|dnsmasq}} also does not prioritize upstream IPv6 DNS. Unfortunately NetworkManager does not do this ([https://bugs.launchpad.net/ubuntu/+source/network-manager/+bug/936712 Ubuntu Bug]). A workaround would be to disable IPv4 DNS in the NetworkManager config, assuming one exists.<br />
<br />
====== DNSSEC ======<br />
<br />
The dnsmasq instance started by NetworkManager by default will not validate [[DNSSEC]] since it is started with the {{ic|--proxy-dnssec}} option. It will trust whatever DNSSEC information it gets from the upstream DNS server.<br />
<br />
For dnsmasq to properly validate DNSSEC, thus breaking DNS resolution with name servers that do not support it, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/dnssec.conf|2=<br />
conf-file=/usr/share/dnsmasq/trust-anchors.conf<br />
dnssec<br />
}}<br />
<br />
===== systemd-resolved =====<br />
<br />
{{Expansion|NetworkManager 1.16 adds a new setting {{ic|main.systemd-resolved}}[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/d4eb4cb45f41b1751cacf71da558bf8f0988f383] (enabled by default). It unconditionally sends DNS configuration to systemd-resolved. Related to "Preserving resolv.conf" from [[systemd-resolved#DNS]]?}}<br />
<br />
NetworkManager can use [[systemd-resolved]] as a DNS resolver and cache. Make sure that ''systemd-resolved'' is properly configured and that {{ic|systemd-resolved.service}} is [[started]] before using it.<br />
<br />
systemd-resolved will be used automatically if {{ic|/etc/resolv.conf}} is a [[Systemd-resolved#DNS|symlink]] to {{ic|/run/systemd/resolve/stub-resolv.conf}}, {{ic|/run/systemd/resolve/resolv.conf}} or {{ic|/usr/lib/systemd/resolv.conf}}.<br />
<br />
You can enable it explicitly by setting {{ic|1=main.dns=systemd-resolved}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/dns.conf|2=<br />
[main]<br />
dns=systemd-resolved<br />
}}<br />
<br />
===== DNS resolver with an openresolv subscriber =====<br />
<br />
If [[openresolv]] has a subscriber for your local [[DNS resolver]], set up the subscriber and [[#Use openresolv|configure NetworkManager to use openresolv]].<br />
<br />
Because NetworkManager advertises a single "interface" to ''resolvconf'', it is not possible to implement conditional forwarding between two NetworkManager connections. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/153 NetworkManager issue 153].<br />
<br />
This can be partially mitigated if you set {{ic|1=private_interfaces="*"}} in {{ic|/etc/resolvconf.conf}}[https://roy.marples.name/projects/openresolv/configuration/]. Any queries for domains that are not in search domain list will not get forwarded. They will be handled according to the local resolver's configuration, for example, forwarded to another DNS server or resolved recursively from the DNS root.<br />
<br />
==== Custom DNS servers ====<br />
<br />
===== Setting custom global DNS servers =====<br />
<br />
To set DNS servers for all connections, specify them in {{man|5|NetworkManager.conf}} using the syntax {{ic|1=servers=''serveripaddress1'',''serveripaddress2'',''serveripaddress3''}} in a section named {{ic|[global-dns-domain-*]}}. For example:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/dns-servers.conf|2=<br />
[global-dns-domain-*]<br />
servers=::1,127.0.0.1<br />
}}<br />
<br />
{{Note|<br />
* If you use [[#DNS caching and conditional forwarding|NetworkManager's dnsmasq or systemd-resolved plugin]] or [[#DNS resolver with an openresolv subscriber|openresolv subscribers]], then do not specify loopback addresses with the {{ic|1=servers=}} option, it can break DNS resolution.<br />
* The specified servers do not get sent to [[systemd-resolved]], the connection's DNS servers are used instead.<br />
}}<br />
<br />
===== Setting custom DNS servers in a connection =====<br />
<br />
====== Setting custom DNS servers in a connection (GUI) ======<br />
<br />
Setup will depend on the type of front-end used; the process usually involves right-clicking on the applet, editing (or creating) a profile, and then choosing DHCP type as ''Automatic (specify addresses)''. The DNS addresses will need to be entered and are usually in this form: {{ic|127.0.0.1, ''DNS-server-one'', ...}}.<br />
<br />
====== Setting custom DNS servers in a connection (nmcli / connection file) ======<br />
<br />
To setup DNS Servers per connection, you can use the {{ic|dns}} field (and the associated {{ic|dns-search}} and {{ic|dns-options}}) in the [[#Edit a connection|connection settings]]. <br />
<br />
If {{ic|method}} is set to {{ic|auto}} (when you use DHCP), you need to set {{ic|ignore-auto-dns}} to {{ic|yes}}.<br />
<br />
==== /etc/resolv.conf ====<br />
<br />
NetworkManager's {{ic|/etc/resolv.conf}} management mode is configured with the {{ic|main.rc-manager}} setting. {{Pkg|networkmanager}} sets it to {{ic|symlink}} as apposed to the upstream default {{ic|auto}}. The setting and its values are documented in the {{man|5|NetworkManager.conf}} man page.<br />
<br />
{{Tip|Using openresolv allows NetworkManager to coexists with other ''resolvconf'' supporting software or, for example, to run a local DNS caching and split-DNS resolver for which openresolv has a [[openresolv#Subscribers|subscriber]]. Note that conditional forwarding is [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/153 not yet fully supported] when using NetworkManager with openresolv.}}<br />
<br />
''NetworkManager'' also offers hooks via so called dispatcher scripts that can be used to alter the {{ic|/etc/resolv.conf}} after network changes. See [[#Network services with NetworkManager dispatcher]] and {{man|8|NetworkManager}} for more information.<br />
<br />
{{Note|<br />
* If NetworkManager is configured to use either [[#dnsmasq|dnsmasq]] or [[#systemd-resolved|systemd-resolved]], then the appropriate loopback addresses will be written to {{ic|/etc/resolv.conf}}.<br />
* The {{ic|resolv.conf}} file NetworkManager writes or would write to {{ic|/etc/resolv.conf}} can be found at {{ic|/run/NetworkManager/resolv.conf}}.<br />
* A {{ic|resolv.conf}} file with the acquired name servers and search domains can be found at {{ic|/run/NetworkManager/no-stub-resolv.conf}}.<br />
}}<br />
<br />
===== Unmanaged /etc/resolv.conf =====<br />
<br />
To stop NetworkManager from touching {{ic|/etc/resolv.conf}}, set {{ic|1=main.dns=none}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/dns.conf|2=<br />
[main]<br />
dns=none<br />
}}<br />
<br />
{{Tip|You might also want to set {{ic|1=main.systemd-resolved=false}}, so that NetworkManager does not send the DNS configuration to [[systemd-resolved]].}}<br />
<br />
{{Note|See [[#DNS caching and conditional forwarding]], to configure NetworkManager using other DNS backends like [[dnsmasq]] and [[systemd-resolved]], instead of using {{ic|1=main.dns=none}}.}}<br />
<br />
After that {{ic|/etc/resolv.conf}} might be a broken symlink that you will need to remove. Then, just create a new {{ic|/etc/resolv.conf}} file.<br />
<br />
===== Use openresolv =====<br />
<br />
{{Note|NetworkManager does not support using systemd-resolved's ''resolvconf'' interface ({{man|1|resolvectl|COMPATIBILITY WITH RESOLVCONF(8)}}) which is provided by {{Pkg|systemd-resolvconf}}.<br />
* Do not set {{ic|1=main.rc-manager=resolvconf}} when using [[systemd-resolved]], instead make sure to [[systemd-resolved#DNS|correctly create the /etc/resolv.conf symlink]] or [[#systemd-resolved|configure NetworkManager to use systemd-resolved explicitly]].<br />
* Make sure the {{Pkg|systemd-resolvconf}} package is not installed when systemd-resolved is not used. Unless {{ic|systemd-resolved.service}} started, it will break all networking software (not just NetworkManager) that use resolvconf.<br />
}}<br />
<br />
To configure NetworkManager to use [[openresolv]], set {{ic|1=main.rc-manager=resolvconf}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/rc-manager.conf|2=<br />
[main]<br />
rc-manager=resolvconf<br />
}}<br />
<br />
=== Firewall ===<br />
<br />
You can [[Firewalld#Using_NetworkManager_to_manage_zones|assign a firewalld zone]] based on your current connection. For example a restrictive firewall when at work, and a less restrictive one when at home.<br />
<br />
This can also be done with [[#Network services with NetworkManager dispatcher|NetworkManager dispatcher]].<br />
<br />
=== Managed network interfaces ===<br />
<br />
You can block NetworkManager from managing some [[Network_configuration#Network_interfaces| network interfaces]] by adding the following content to {{ic|/etc/NetworkManager/NetworkManager.conf}}. The MAC addresses can be obtained from {{ic|/etc/sys/class/net/''interface''/address}}.<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|2=<br />
[main]<br />
plugins=keyfile<br />
<br />
[keyfile]<br />
unmanaged-devices=mac:''MAC address 1'';mac:''MAC address 2''<br />
}}<br />
<br />
== Network services with NetworkManager dispatcher ==<br />
<br />
There are quite a few network services that you will not want running until NetworkManager brings up an interface. NetworkManager has the ability to start services when you connect to a network and stop them when you disconnect (e.g. when using [[NFS]], [[SMB]] and [[NTPd]]).<br />
<br />
To activate the feature you need to [[enable]] and [[start]] the {{ic|NetworkManager-dispatcher.service}}.<br />
<br />
Once the service is active, scripts can be added to the {{ic|/etc/NetworkManager/dispatcher.d}} directory.<br />
<br />
Scripts must be owned by '''root''', otherwise the dispatcher will not execute them. For added security, set group [[ownership]] to root as well:<br />
<br />
# chown root:root /etc/NetworkManager/dispatcher.d/''10-script.sh''<br />
<br />
Make sure the file has correct permissions:<br />
<br />
# chmod 755 /etc/NetworkManager/dispatcher.d/''10-script.sh''<br />
<br />
The scripts will be run in alphabetical order at connection time, and in reverse alphabetical order at disconnect time. To ensure what order they come up in, it is common to use numerical characters prior to the name of the script (e.g. {{ic|10-portmap}} or {{ic|30-netfs}} (which ensures that the ''portmapper'' is up before NFS mounts are attempted).<br />
<br />
Scripts will receive the following arguments:<br />
<br />
* '''Interface name:''' e.g. {{ic|eth0}}<br />
* '''Action:''' ''up'', ''down'', ''vpn-up'', ''vpn-down'', ... (see {{man|8|NetworkManager}} for the complete list)<br />
<br />
{{Warning|If you connect to foreign or public networks, be aware of what services you are starting and what servers you expect to be available for them to connect to. You could make a security hole by starting the wrong services while connected to a public network.}}<br />
<br />
=== Avoiding the dispatcher timeout ===<br />
<br />
If the above is working, then this section is not relevant. However, there is a general problem related to running dispatcher scripts which take longer to be executed. Initially an internal timeout of three seconds only was used. If the called script did not complete in time, it was killed. Later the timeout was extended to about 20 seconds (see the [https://bugzilla.redhat.com/show_bug.cgi?id=982734 Bugtracker] for more information). If the timeout still creates the problem, a work around may be to modify the dispatcher service file {{ic|/usr/lib/systemd/system/NetworkManager-dispatcher.service}} to remain active after exit: <br />
<br />
{{hc|/etc/systemd/system/NetworkManager-dispatcher.service.d/remain_after_exit.conf|2=<br />
[Service]<br />
RemainAfterExit=yes<br />
}}<br />
<br />
Now start and enable the modified {{ic|NetworkManager-dispatcher}} service.<br />
<br />
{{Warning|Adding the {{ic|RemainAfterExit}} line to it will prevent the dispatcher from closing. Unfortunately, the dispatcher '''has''' to close before it can run your scripts again. With it the dispatcher will not time out but it also will not close, which means that the scripts will only run once per boot. Therefore, do not add the line unless the timeout is definitely causing a problem.}}<br />
<br />
=== Dispatcher examples ===<br />
<br />
==== Mount remote folder with sshfs ====<br />
<br />
As the script is run in a very restrictive environment, you have to export {{ic|SSH_AUTH_SOCK}} in order to connect to your SSH agent. There are different ways to accomplish this, see [https://bbs.archlinux.org/viewtopic.php?pid=1042030#p1042030 this message] for more information. The example below works with [[GNOME Keyring]], and will ask you for the password if not unlocked already. In case NetworkManager connects automatically on login, it is likely ''gnome-keyring'' has not yet started and the export will fail (hence the sleep). The {{ic|UUID}} to match can be found with the command {{ic|nmcli connection status}} or {{ic|nmcli connection list}}. <br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
USER='username'<br />
REMOTE='user@host:/remote/path'<br />
LOCAL='/local/path'<br />
<br />
interface=$1 status=$2<br />
if [ "$CONNECTION_UUID" = "</nowiki>''uuid''<nowiki>" ]; then<br />
case $status in<br />
up)<br />
SSH_AUTH_SOCK=$(find /tmp -maxdepth 1 -type s -user "$USER" -name 'ssh')<br />
export SSH_AUTH_SOCK<br />
su "$USER" -c "sshfs $REMOTE $LOCAL"<br />
;;<br />
down)<br />
fusermount -u "$LOCAL"<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
==== Mounting of SMB shares ====<br />
<br />
Some [[SMB]] shares are only available on certain networks or locations (e.g. at home). You can use the dispatcher to only mount SMB shares that are present at your current location.<br />
<br />
The following script will check if we connected to a specific network and mount shares accordingly:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/30-mount-smb.sh|<nowiki><br />
#!/bin/sh<br />
<br />
# Find the connection UUID with "nmcli connection show" in terminal.<br />
# All NetworkManager connection types are supported: wireless, VPN, wired...<br />
if [ "$2" = "up" ]; then<br />
if [ "$CONNECTION_UUID" = "uuid" ]; then<br />
mount /your/mount/point & <br />
# add more shares as needed<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
The following script will unmount all SMB shares before a software initiated disconnect from a specific network:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/pre-down.d/30-umount-smb.sh|<nowiki><br />
#!/bin/sh<br />
<br />
if [ "$CONNECTION_UUID" = "uuid" ]; then<br />
umount -a -l -t cifs<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|Make sure this script is located in the {{ic|pre-down.d}} sub-directory as shown above, otherwise it will unmount all shares on any connection state change.}}<br />
<br />
The following script will attempt to unmount all SMB shares following an unexpected disconnect from a specific network:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/40-umount-smb.sh|<nowiki><br />
#!/bin/sh<br />
<br />
if [ "$CONNECTION_UUID" = "uuid" ]; then<br />
if [ "$2" = "down" ]; then<br />
umount -a -l -t cifs<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|<br />
* Since NetworkManager 0.9.8, the ''pre-down'' and ''down'' events are not executed on shutdown or restart, see [https://bugzilla.gnome.org/show_bug.cgi?id&#61;701242 this bug report] for more info.<br />
* The previous ''umount'' scripts are still prone to leaving applications actually accessing the mount to 'hang'.<br />
}}<br />
<br />
An alternative is to use the script as seen in [[NFS#Using a NetworkManager dispatcher]]:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/30-smb.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Find the connection UUID with "nmcli con show" in terminal.<br />
# All NetworkManager connection types are supported: wireless, VPN, wired...<br />
WANTED_CON_UUID="CHANGE-ME-NOW-9c7eff15-010a-4b1c-a786-9b4efa218ba9"<br />
<br />
if [[ "$CONNECTION_UUID" == "$WANTED_CON_UUID" ]]; then<br />
<br />
# Script parameter $1: NetworkManager connection name, not used<br />
# Script parameter $2: dispatched event<br />
<br />
case "$2" in<br />
"up")<br />
mount -a -t cifs<br />
;;<br />
"pre-down");&<br />
"vpn-pre-down")<br />
umount -l -a -t cifs >/dev/null<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|This script ignores mounts with the {{ic|noauto}} option, remove this mount option or use {{ic|auto}} to allow the dispatcher to manage these mounts.}}<br />
<br />
Create a symlink inside {{ic|/etc/NetworkManager/dispatcher.d/pre-down/}} to catch the {{ic|pre-down}} events:<br />
<br />
# ln -s ../30-smb.sh /etc/NetworkManager/dispatcher.d/pre-down.d/30-smb.sh<br />
<br />
==== Mounting of NFS shares ====<br />
<br />
See [[NFS#Using a NetworkManager dispatcher]].<br />
<br />
==== Use dispatcher to automatically toggle wireless depending on LAN cable being plugged in ====<br />
<br />
The idea is to only turn Wi-Fi on when the LAN cable is unplugged (for example when detaching from a laptop dock), and for Wi-Fi to be automatically disabled, once a LAN cable is plugged in again. <br />
<br />
Create the following dispatcher script[https://superuser.com/questions/233448/disable-wlan-if-wired-cable-network-is-available], replacing {{ic|1=''LAN_interface''}} with yours.<br />
<br />
Note that there is a fail-safe for the case when the LAN interface was connected when the computer was last on, and then disconnected while the computer was off. That would mean the radio would still be off when the computer is turned back on, and with a disconnected LAN interface, you would have no network.<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/wlan_auto_toggle.sh|2=<br />
#!/bin/sh<br />
<br />
if [ "$1" = "''LAN_interface''" ]; then<br />
case "$2" in<br />
up)<br />
nmcli radio wifi off<br />
;;<br />
down)<br />
nmcli radio wifi on<br />
;;<br />
esac<br />
elif [ "$(nmcli -g GENERAL.STATE device show LAN_interface)" = "20 (unavailable)" ]; then<br />
nmcli radio wifi on<br />
fi<br />
}}<br />
<br />
{{Note|You can get a list of interfaces using [[#nmcli examples|nmcli]]. The Ethernet (LAN) interfaces start with {{ic|en}}, e.g. {{ic|1=enp0s5}}}}<br />
<br />
==== Use dispatcher to connect to a VPN after a network connection is established ====<br />
<br />
In this example we want to connect automatically to a previously defined VPN connection after connecting to a specific Wi-Fi network. First thing to do is to create the dispatcher script that defines what to do after we are connected to the network.<br />
<br />
{{Note|This script will require {{Pkg|wireless_tools}} in order to use {{ic|iwgetid}}.}}<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki><br />
#!/bin/sh<br />
VPN_NAME="name of VPN connection defined in NetworkManager"<br />
ESSID="Wi-Fi network ESSID (not connection name)"<br />
<br />
interface=$1 status=$2<br />
case $status in<br />
up|vpn-down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
nmcli connection up id "$VPN_NAME"<br />
fi<br />
;;<br />
down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
if nmcli connection show --active | grep "$VPN_NAME"; then<br />
nmcli connection down id "$VPN_NAME"<br />
fi<br />
fi<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
If you would like to attempt to automatically connect to VPN for all Wi-Fi networks, you can use the following definition of the ESSID: {{ic|1=ESSID=$(iwgetid -r)}}. Remember to set the script's permissions [[#Network services with NetworkManager dispatcher|accordingly]]. <br />
<br />
Trying to connect with the above script may still fail with {{ic|NetworkManager-dispatcher.service}} complaining about 'no valid VPN secrets', because of [https://developer.gnome.org/NetworkManager/0.9/secrets-flags.html the way VPN secrets are stored]. Fortunately, there are different options to give the above script access to your VPN password.<br />
<br />
1: One of them requires editing the VPN connection configuration file to make NetworkManager store the secrets by itself rather than inside a keyring [https://bugzilla.redhat.com/show_bug.cgi?id=710552 that will be inaccessible for root]: open up {{ic|/etc/NetworkManager/system-connections/''name of your VPN connection''}} and change the {{ic|password-flags}} and {{ic|secret-flags}} from {{ic|1}} to {{ic|0}}.<br />
<br />
If that alone does not work, you may have to create a {{ic|passwd-file}} in a safe location with the same permissions and ownership as the dispatcher script, containing the following:<br />
<br />
{{hc|/path/to/passwd-file|<br />
vpn.secrets.password:YOUR_PASSWORD<br />
}}<br />
<br />
The script must be changed accordingly, so that it gets the password from the file:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki><br />
#!/bin/sh<br />
VPN_NAME="name of VPN connection defined in NetworkManager"<br />
ESSID="Wi-Fi network ESSID (not connection name)"<br />
<br />
interface=$1 status=$2<br />
case $status in<br />
up|vpn-down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
nmcli connection up id "$VPN_NAME" passwd-file /path/to/passwd-file<br />
fi<br />
;;<br />
down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
if nmcli connection show --active | grep "$VPN_NAME"; then<br />
nmcli connection down id "$VPN_NAME"<br />
fi<br />
fi<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
2: Alternatively, change the {{ic|password-flags}} and put the password directly in the configuration file adding the section {{ic|vpn-secrets}}:<br />
<br />
[vpn]<br />
....<br />
password-flags=0<br />
<br />
[vpn-secrets]<br />
password=''your_password''<br />
<br />
{{Note|It may now be necessary to re-open the NetworkManager connection editor and save the VPN passwords/secrets again.}}<br />
<br />
==== Use dispatcher to disable IPv6 on VPN provider connections ====<br />
<br />
Many [[:Category:VPN providers|commercial VPN providers]] support only IPv4. That means all IPv6 traffic bypasses the VPN and renders it virtually useless. To avoid this, dispatcher can be used to disable all IPv6 traffic for the time a VPN connection is up.<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/10-vpn-ipv6|<nowiki><br />
#!/bin/sh<br />
<br />
case "$2" in<br />
vpn-up)<br />
echo 1 > /proc/sys/net/ipv6/conf/all/disable_ipv6<br />
;;<br />
vpn-down)<br />
echo 0 > /proc/sys/net/ipv6/conf/all/disable_ipv6<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
==== OpenNTPD ====<br />
<br />
See [[OpenNTPD#Using NetworkManager dispatcher]].<br />
<br />
== Testing ==<br />
<br />
NetworkManager applets are designed to load upon login so no further configuration should be necessary for most users. If you have already disabled your previous network settings and disconnected from your network, you can now test if NetworkManager will work. The first step is to [[start]] {{ic|NetworkManager.service}}.<br />
<br />
Some applets will provide you with a {{ic|.desktop}} file so that the NetworkManager applet can be loaded through the application menu. If it does not, you are going to either have to discover the command to use or logout and login again to start the applet. Once the applet is started, it will likely begin polling network connections with for auto-configuration with a DHCP server.<br />
<br />
To start the GNOME applet in non-xdg-compliant window managers like [[awesome]]:<br />
<br />
nm-applet --sm-disable &<br />
<br />
For static IP addresses, you will have to configure NetworkManager to understand them. The process usually involves right-clicking the applet and selecting something like 'Edit Connections'.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Encrypted Wi-Fi passwords ===<br />
<br />
By default, NetworkManager stores passwords in clear text in the connection files at {{ic|/etc/NetworkManager/system-connections/}}. To print the stored passwords, use the following command:<br />
<br />
# grep -r '^psk=' /etc/NetworkManager/system-connections/<br />
<br />
The passwords are accessible to the root user in the filesystem and to users with access to settings via the GUI (e.g. {{ic|nm-applet}}). <br />
<br />
It is preferable to save the passwords in encrypted form in a keyring instead of clear text. The downside of using a keyring is that the connections have to be set up for each user.<br />
<br />
==== Using GNOME Keyring ====<br />
<br />
The keyring daemon has to be started and the keyring needs to be unlocked for the following to work.<br />
<br />
Furthermore, NetworkManager needs to be configured not to store the password for all users. Using GNOME {{ic|nm-applet}}, run {{ic|nm-connection-editor}} from a terminal, select a network connection, click {{ic|Edit}}, select the {{ic|Wifi-Security}} tab and click on the right icon of password and check {{ic|Store the password only for this user}}.<br />
<br />
==== Using KDE Wallet ====<br />
<br />
Using KDE's {{Pkg|plasma-nm}}, click the applet, click on the top right {{ic|Settings}} icon, click on a network connection, in the {{ic|General settings}} tab, untick {{ic|all users may connect to this network}}. If the option is ticked, the passwords will still be stored in clear text, even if a keyring daemon is running.<br />
<br />
If the option was selected previously and you un-tick it, you may have to use the {{ic|reset}} option first to make the password disappear from the file. Alternatively, delete the connection first and set it up again.<br />
<br />
=== Sharing internet connection over Wi-Fi ===<br />
<br />
You can share your internet connection (e.g. 3G or wired) with a few clicks. Please note that a [[firewall]] may interfere with internet sharing.<br />
<br />
You will need a Wi-Fi card which supports AP mode, see [[Software access point#Wi-Fi device must support AP mode]] for details.<br />
<br />
[[Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection. Note that NetworkManager starts its own instance of ''dnsmasq'', independent of {{ic|dnsmasq.service}}, as a DHCP server. See [[#dnsmasq]] for the caveats.<br />
<br />
Create the shared connection:<br />
<br />
* Click on applet and choose ''Create new wireless network''.<br />
* Follow wizard (choose WPA2 or higher, be sure to use at least 8 character long password, lower lengths will fail).<br />
** Choose either [[Fedora:Features/RealHotspot|Hotspot]] or Ad-hoc as Wi-Fi mode.<br />
<br />
The connection will be saved and remain stored for the next time you need it.<br />
<br />
{{Note|Android does not support connecting to Ad-hoc networks. To share a connection with Android use infrastructure mode (i.e. set Wi-Fi mode to "Hotspot").}}<br />
<br />
=== Sharing internet connection over Ethernet ===<br />
<br />
Scenario: your device has internet connection over wi-fi and you want to share the internet connection to other devices over ethernet.<br />
<br />
Requirements:<br />
<br />
* [[Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection. Note that NetworkManager starts its own instance of ''dnsmasq'', independent of {{ic|dnsmasq.service}}, as a DHCP server. See [[#dnsmasq]] for the caveats.<br />
* Your internet connected device and the other devices are connected over a suitable ethernet cable (this usually means a cross over cable or a switch in between).<br />
* Internet sharing is not blocked by a [[firewall]].<br />
<br />
Steps:<br />
<br />
{{Style|{{Pkg|nm-connection-editor}} is not a dependency of {{Pkg|networkmanager}} and needs to be installed separately.}}<br />
<br />
* Run {{ic|nm-connection-editor}} from terminal.<br />
* Add a new ethernet connection.<br />
* Give it some sensible name. For example "Shared Internet"<br />
* Go to "IPv4 Settings".<br />
* For "Method:" select "Shared to other computers".<br />
* Save<br />
<br />
Now you should have a new option "Shared Internet" under the Wired connections in NetworkManager.<br />
<br />
=== Checking if networking is up inside a cron job or script ===<br />
<br />
{{Out of date|''nm-tool'' was remove from NetworkManager for long time now[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/bb8c75bd536d4f8fb80a4366025a279078f0ec81]. ''nmcli'' should be used instead.}}<br />
<br />
Some ''cron'' jobs require networking to be up to succeed. You may wish to avoid running these jobs when the network is down. To accomplish this, add an '''if''' test for networking that queries NetworkManager's ''nm-tool'' and checks the state of networking. The test shown here succeeds if any interface is up, and fails if they are all down. This is convenient for laptops that might be hardwired, might be on wireless, or might be off the network.<br />
<br />
{{bc|<nowiki><br />
if [ $(nm-tool|grep State|cut -f2 -d' ') == "connected" ]; then<br />
#Whatever you want to do if the network is online<br />
else<br />
#Whatever you want to do if the network is offline - note, this and the else above are optional<br />
fi<br />
</nowiki>}}<br />
<br />
This useful for a {{ic|cron.hourly}} script that runs ''fpupdate'' for the F-Prot virus scanner signature update, as an example. Another way it might be useful, with a little modification, is to differentiate between networks using various parts of the output from ''nm-tool''; for example, since the active wireless network is denoted with an asterisk, you could grep for the network name and then grep for a literal asterisk.<br />
<br />
=== Connect to network with secret on boot ===<br />
<br />
By default, NetworkManager will not connect to networks requiring a secret automatically on boot. This is because it locks such connections to the user who makes it by default, only connecting after they have logged in. To change this, do the following:<br />
<br />
# Right click on the {{ic|nm-applet}} icon in your panel and select Edit Connections and open the Wireless tab<br />
# Select the connection you want to work with and click the Edit button<br />
# Check the boxes “Connect Automatically” and “Available to all users”<br />
# Additionally, ensure that under "Wi-Fi Security", "Store password for all users (not encrypted)" is selected<br />
<br />
Log out and log back in to complete.<br />
<br />
=== OpenConnect with password in KWallet ===<br />
<br />
While you may type both values at connection time, {{Pkg|plasma-nm}} 0.9.3.2-1 and above are capable of retrieving OpenConnect username and password directly from [[KWallet]].<br />
<br />
Open "KDE Wallet Manager" and look up your OpenConnect VPN connection under "Network Management|Maps". Click "Show values" and <br />
enter your credentials in key "VpnSecrets" in this form (replace ''username'' and ''password'' accordingly):<br />
<br />
form:main:username%SEP%''username''%SEP%form:main:password%SEP%''password''<br />
<br />
Next time you connect, username and password should appear in the "VPN secrets" dialog box.<br />
<br />
=== Ignore specific devices ===<br />
<br />
Sometimes it may be desired that NetworkManager ignores specific devices and does not try to configure addresses and routes for them. You can quickly and easily ignore devices by MAC or interface-name by using the following in {{ic|/etc/NetworkManager/conf.d/unmanaged.conf}}:<br />
<br />
[keyfile]<br />
unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth0<br />
<br />
After editing the file, run {{ic|nmcli general reload}} as root. Afterwards you should be able to configure interfaces without NetworkManager altering what you have set.<br />
<br />
=== Configuring MAC address randomization ===<br />
<br />
{{Note|1=Disabling MAC address randomization may be needed to get (stable) link connection [https://bbs.archlinux.org/viewtopic.php?id=220101] and/or networks that restrict devices based on their MAC Address or have a limit network capacity.}}<br />
<br />
MAC randomization can be used for increased privacy by not disclosing your real MAC address to the network.<br />
<br />
NetworkManager supports two types MAC Address Randomization: randomization during scanning, and for network connections. Both modes can be configured by modifying {{ic|/etc/NetworkManager/NetworkManager.conf}} or by creating a separate configuration file in {{ic|/etc/NetworkManager/conf.d/}} which is recommended since the aforementioned config file may be overwritten by NetworkManager.<br />
<br />
Randomization during Wi-Fi scanning is enabled by default, but it may be disabled by adding the following lines to {{ic|/etc/NetworkManager/NetworkManager.conf}} or a dedicated configuration file under {{ic|/etc/NetworkManager/conf.d}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=<br />
[device]<br />
wifi.scan-rand-mac-address=no<br />
}}<br />
<br />
MAC randomization for network connections can be set to different modes for both wireless and ethernet interfaces. See the [https://blogs.gnome.org/thaller/2016/08/26/mac-address-spoofing-in-networkmanager-1-4-0/ GNOME blog post] for more details on the different modes. <br />
<br />
In terms of MAC randomization the most important modes are {{ic|stable}} and {{ic|random}}. {{ic|stable}} generates a random MAC address when you connect to a new network and associates the two permanently. This means that you will use the same MAC address every time you connect to that network. In contrast, {{ic|random}} will generate a new MAC address every time you connect to a network, new or previously known. You can configure the MAC randomization by adding the desired configuration under {{ic|/etc/NetworkManager/conf.d}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=<br />
[device-mac-randomization]<br />
# "yes" is already the default for scanning<br />
wifi.scan-rand-mac-address=yes<br />
<br />
[connection-mac-randomization]<br />
# Randomize MAC for every ethernet connection<br />
ethernet.cloned-mac-address=random<br />
# Generate a random MAC for each WiFi and associate the two permanently.<br />
wifi.cloned-mac-address=stable<br />
}}<br />
<br />
See the following [https://blogs.gnome.org/thaller/2016/08/26/mac-address-spoofing-in-networkmanager-1-4-0/ GNOME blog post] for more details.<br />
<br />
=== Enable IPv6 Privacy Extensions ===<br />
<br />
See [[IPv6#NetworkManager]].<br />
<br />
=== Working with wired connections ===<br />
<br />
By default, NetworkManager generates a connection profile for each wired ethernet connection it finds. At the point when generating the connection, it does not know whether there will be more ethernet adapters available. Hence, it calls the first wired connection "Wired connection 1". You can avoid generating this connection, by configuring {{ic|no-auto-default}} (see {{man|5|NetworkManager.conf}}), or by simply deleting it. Then NetworkManager will remember not to generate a connection for this interface again.<br />
<br />
You can also edit the connection (and persist it to disk) or delete it. NetworkManager will not re-generate a new connection. Then you can change the name to whatever you want. You can use something like nm-connection-editor for this task.<br />
<br />
=== Using iwd as the Wi-Fi backend ===<br />
<br />
{{Note|1=Consider [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues?scope=all&utf8=%E2%9C%93&state=opened&search=iwd existing issues] before switching to iwd.}}<br />
<br />
Enable the [https://iwd.wiki.kernel.org/networkmanager experimental] [[iwd]] backend creating the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/wifi_backend.conf|2=<br />
[device]<br />
wifi.backend=iwd<br />
}}<br />
<br />
Alternatively, you can install {{AUR|networkmanager-iwd}}, a modified package configured to build ''NetworkManager'' working exclusively with ''iwd'', with the main difference being that ''iwd'' is required and ''wpa_supplicant'' can be uninstalled after building.<br />
<br />
=== Running in a network namespace ===<br />
<br />
If you would like to run NetworkManager inside a network namespace (e.g., to manage a specific device which should be use by selected applications), bring the device down before moving it to the namespace:<br />
<br />
$ ip link set dev ''MY_DEVICE'' down<br />
$ ip link set dev ''MY_DEVICE'' netns ''MY_NAMESPACE''<br />
$ ip netns exec ''MY_NAMESPACE'' NetworkManager<br />
...<br />
$ ip netns exec ''MY_NAMESPACE'' killall NetworkManager<br />
<br />
otherwise NetworkManager will later fail to establish the connection with a {{ic|device is strictly unmanaged}} error.<br />
<br />
=== Automatically connect to VPN ===<br />
<br />
NetworkManager can be set to automatically connect to a VPN when connecting to the internet, on a per network basis. The VPN connection itself can be added in GNOME's NetworkManager front-end, but to make it automatically use the VPN {{ic|nmcli}} must be used. Other front-ends might not have this limitation.<br />
<br />
First, make sure to make the VPN connection available to all users. In the GNOME this is a matter of checking a box under the {{ic|details}} tab. Under the {{ic|Identity}} tab, in the password field, click the icon on the right side in the field, and set it to {{ic|Store the password for all users}}.<br />
<br />
Then find the UUID of the VPN connection, and add that to {{ic|connection.secondaries}} of the Internet connection:<br />
<br />
# UUID=$(nmcli --get-values connection.uuid connection show ''name-of-VPN-connection'')<br />
# nmcli connection modify ''name-of-Internet-connection'' connection.secondaries "$UUID"<br />
<br />
Now when NetworkManager is restarted and you connect to the Internet connection you have configured, you should automatically get connected to the VPN.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No prompt for password of secured Wi-Fi networks ===<br />
<br />
When trying to connect to a secured Wi-Fi network, no prompt for a password is shown and no connection is established. This happens when no keyring package is installed. An easy solution is to install {{Pkg|gnome-keyring}}. If you want the passwords to be stored in encrypted form, follow [[GNOME Keyring]] to set up the ''gnome-keyring-daemon''.<br />
<br />
=== Network management disabled ===<br />
<br />
When NetworkManager shuts down but the pid (state) file is not removed, you will see a {{ic|Network management disabled}} message. If this happens, remove the file manually:<br />
<br />
# rm /var/lib/NetworkManager/NetworkManager.state<br />
<br />
=== Problems with internal DHCP client ===<br />
<br />
If you have problems with getting an IP address using the internal DHCP client, consider using another DHCP client, see [[#DHCP client]] for instructions. This workaround might solve problems in big wireless networks like eduroam.<br />
<br />
=== DHCP problems with dhclient ===<br />
<br />
If you have problems with getting an IP address via DHCP, try to add the following to your {{ic|/etc/dhclient.conf}}:<br />
<br />
interface "eth0" {<br />
send dhcp-client-identifier 01:''aa:bb:cc:dd:ee:ff'';<br />
}<br />
<br />
Where {{ic|''aa:bb:cc:dd:ee:ff''}} is the MAC address of this NIC. The MAC address can be found using the {{ic|ip link show ''interface''}} command from the {{Pkg|iproute2}} package.<br />
<br />
=== 3G modem not detected ===<br />
<br />
See [[Mobile broadband modem#NetworkManager]].<br />
<br />
=== Switching off WLAN on laptops ===<br />
<br />
Sometimes NetworkManager will not work when you disable your Wi-Fi adapter with a switch on your laptop and try to enable it again afterwards. This is often a problem with ''rfkill''. To check if the driver notifies ''rfkill'' about the wireless adapter's status, use:<br />
<br />
$ watch -n1 rfkill list all<br />
<br />
If one identifier stays blocked after you switch on the adapter you could try to manually unblock it with (where X is the number of the identifier provided by the above output):<br />
<br />
# rfkill event unblock X<br />
<br />
=== Static IP address settings revert to DHCP ===<br />
<br />
Due to an unresolved bug, when changing default connections to a static IP address, {{ic|nm-applet}} may not properly store the configuration change, and will revert to automatic DHCP.<br />
<br />
To work around this issue you have to edit the default connection (e.g. "Auto eth0") in {{ic|nm-applet}}, change the connection name (e.g. "my eth0"), uncheck the "Available to all users" checkbox, change your static IP address settings as desired, and click '''Apply'''. This will save a new connection with the given name.<br />
<br />
Next, you will want to make the default connection not connect automatically. To do so, run {{ic|nm-connection-editor}} ('''not''' as root). In the connection editor, edit the default connection (e.g. "Auto eth0") and uncheck "Connect automatically". Click '''Apply''' and close the connection editor.<br />
<br />
=== Cannot edit connections as normal user ===<br />
<br />
See [[#Set up PolicyKit permissions]].<br />
<br />
=== Forget hidden wireless network ===<br />
<br />
Since hidden networks are not displayed in the selection list of the Wireless view, they cannot be forgotten (removed) with the GUI. You can delete one with the following command:<br />
<br />
# rm /etc/NetworkManager/system-connections/''SSID''<br />
<br />
This also works for any other connection.<br />
<br />
=== VPN not working in GNOME ===<br />
<br />
When setting up OpenConnect or vpnc connections in NetworkManager while using GNOME, you will sometimes never see the dialog box pop up and the following error appears in {{ic|/var/log/errors.log}}:<br />
<br />
localhost NetworkManager[399]: <error> [1361719690.10506] [nm-vpn-connection.c:1405] get_secrets_cb(): Failed to request VPN secrets #3: (6) No agents were available for this request.<br />
<br />
This is caused by the GNOME NM Applet expecting dialog scripts to be at {{ic|/usr/lib/gnome-shell}}, when NetworkManager's packages put them in {{ic|/usr/lib/networkmanager}}.<br />
As a "temporary" fix (this bug has been around for a while now), make the following symlink(s):<br />
<br />
* For OpenConnect: {{ic|ln -s /usr/lib/networkmanager/nm-openconnect-auth-dialog /usr/lib/gnome-shell/}}<br />
* For VPNC (i.e. Cisco VPN): {{ic|ln -s /usr/lib/networkmanager/nm-vpnc-auth-dialog /usr/lib/gnome-shell/}}<br />
<br />
This may need to be done for any other NM VPN plugins as well, but these are the two most common.<br />
<br />
=== Unable to connect to visible European wireless networks ===<br />
<br />
WLAN chips are shipped with a default [[Wireless network configuration#Respecting the regulatory domain|regulatory domain]]. If your access point does not operate within these limitations, you will not be able to connect to the network. Fixing this is easy:<br />
<br />
# [[Install]] {{Pkg|crda}}<br />
# Uncomment the correct Country Code in {{ic|/etc/conf.d/wireless-regdom}}<br />
# Reboot the system, because the setting is only read on boot<br />
<br />
=== Automatic connect to VPN on boot is not working ===<br />
<br />
The problem occurs when the system (i.e. NetworkManager running as the root user) tries to establish a VPN connection, but the password is not accessible because it is stored in the GNOME keyring of a particular user. <br />
<br />
A solution is to keep the password to your VPN in plaintext, as described in step (2.) of [[#Use dispatcher to connect to a VPN after a network connection is established]]. <br />
<br />
You do not need to use the dispatcher described in step (1.) to auto-connect anymore, if you use the new "auto-connect VPN" option from the {{ic|nm-applet}} GUI.<br />
<br />
=== Systemd Bottleneck ===<br />
<br />
Over time the log files ({{ic|/var/log/journal}}) can become very large. This can have a big impact on boot performance when using NetworkManager, see: [[Systemd#Boot time increasing over time]].<br />
<br />
=== Regular network disconnects, latency and lost packets (WiFi) ===<br />
<br />
NetworkManager does a scan every 2 minutes.<br />
<br />
Some WiFi drivers have issues when scanning for base stations whilst connected/associated. Symptoms include VPN disconnects/reconnects and lost packets, web pages failing to load and then refresh fine.<br />
<br />
Running {{ic|journalctl -f}} as root will indicate that this is taking place, messages like the following will be contained in the logs at regular intervals.<br />
<br />
NetworkManager[410]: <info> (wlp3s0): roamed from BSSID 00:14:48:11:20:CF (my-wifi-name) to (none) ((none))<br />
<br />
There is a patched version of NetworkManager which should prevent this type of scanning: {{AUR|networkmanager-noscan}}.<br />
<br />
Alternatively, if roaming is not important, the periodic scanning behavior can be disabled by locking the BSSID of the access point in the WiFi connection profile.<br />
<br />
=== Unable to turn on wi-fi with Lenovo laptop (IdeaPad, Legion, etc.) ===<br />
<br />
There is an issue with the {{ic|ideapad_laptop}} module on some Lenovo models due to the wi-fi driver incorrectly reporting a soft block. The card can still be manipulated with {{ic|netctl}}, but managers like NetworkManager break. You can verify that this is the problem by checking the output of {{ic|rfkill list}} after toggling your hardware switch and seeing that the soft block persists.<br />
<br />
{{Accuracy|Try to use {{ic|rfkill.default_state}} and {{ic|rfkill.master_switch_mode}} (see [https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/kernel-parameters.txt kernel-parameters.txt]) to fix the rfkill problem.}}<br />
<br />
[[modprobe|Unloading]] the {{ic|ideapad_laptop}} module should fix this. ('''warning''': this may disable the laptop keyboard and touchpad also!).<br />
<br />
=== Turn off hostname sending ===<br />
<br />
NetworkManager by default sends the hostname to the DHCP server. Hostname sending can only be disabled per connection not globally ([https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/584 Issue #584]).<br />
<br />
To disable sending your hostname to the DHCP server for a specific connection, add the following to your network connection file:<br />
<br />
{{hc|/etc/NetworkManager/system-connections/''your_connection_file''|2=<br />
...<br />
[ipv4]<br />
dhcp-send-hostname=false<br />
...<br />
[ipv6]<br />
dhcp-send-hostname=false<br />
...<br />
}}<br />
<br />
=== nm-applet disappears in i3wm ===<br />
<br />
If you use the {{ic|xfce4-notifyd.service}} for notifications you must [[edit]] the unit and add the following:<br />
<br />
{{hc|/etc/systemd/user/xfce4-notifyd.service.d/display_env.conf|2=<br />
[Service]<br />
Environment="DISPLAY=:0.0"<br />
}}<br />
<br />
After reloading the daemons [[restart]] {{ic|xfce4-notifyd.service}}. Exit i3 and start it back up again and the applet should show on the tray.<br />
<br />
=== nm-applet tray icons display wrongly ===<br />
<br />
Currently the tray icons of nm-applet are drawn on top of one another, i.e. the icon displaying wireless strength might show on top of the icon indicating no wired connection.<br />
This is apparently a GTK3 bug/problem: https://gitlab.gnome.org/GNOME/gtk/issues/1280 .<br />
<br />
A patched version of GTK3 exists in AUR, which apparently fixes the tray icon bug: {{AUR|gtk3-classic}}.<br />
<br />
=== Unit dbus-org.freedesktop.resolve1.service not found ===<br />
<br />
If {{ic|systemd-resolved.service}} is not started, NetworkManager will try to start it using D-Bus and fail:<br />
<br />
dbus-daemon[991]: [system] Activating via systemd: service name='org.freedesktop.resolve1' unit='dbus-org.freedesktop.resolve1.service' requested by ':1.23' (uid=0 pid=1012 comm="/usr/bin/NetworkManager --no-daemon ")<br />
dbus-daemon[991]: [system] Activation via systemd failed for unit 'dbus-org.freedesktop.resolve1.service': Unit dbus-org.freedesktop.resolve1.service not found.<br />
dbus-daemon[991]: [system] Activating via systemd: service name='org.freedesktop.resolve1' unit='dbus-org.freedesktop.resolve1.service' requested by ':1.23' (uid=0 pid=1012 comm="/usr/bin/NetworkManager --no-daemon ")<br />
<br />
This is because NetworkManager will try to send DNS information to [[systemd-resolved]] regardless of the {{ic|1=main.dns=}} setting in {{man|5|NetworkManager.conf}}.[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/d4eb4cb45f41b1751cacf71da558bf8f0988f383]<br />
<br />
This can be disabled with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/no-systemd-resolved.conf|2=<br />
[main]<br />
systemd-resolved=false<br />
}}<br />
<br />
See {{Bug|62138}}.<br />
<br />
=== Secrets were required, but not provided ===<br />
<br />
If you attempt to connect to a network using {{ic|nmcli device wifi connect ''SSID'' password ''password''}} and received the following error:<br />
<br />
Error: Connection activation failed: (7) Secrets were required, but not provided<br />
<br />
The error can be resolved by deleting the connection profile and creating a new one:<br />
<br />
$ nmcli connection delete ''SSID''<br />
$ nmcli device wifi connect ''SSID'' password ''password''<br />
<br />
You can also try disabling MAC address randomization:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=<br />
[device]<br />
wifi.scan-rand-mac-address=no<br />
}}<br />
<br />
=== WPA Enterprise connection with iwd ===<br />
<br />
If you try to connect to an WPA Enterprise network like 'eduroam' with NetworkManager with the [[#Using iwd as the Wi-Fi backend|iwd backend]] then you will get the following error from NetworkManager:<br />
<br />
Connection 'eduroam' is not avialable on device wlan0 because profile is not compatible with device (802.1x connections must have IWD provisioning files)<br />
<br />
This is because NetworkManager can not configure a WPA Enterprise network. Therefore you have to configure it using an iwd config file {{ic|/var/lib/iwd/''essid''.8021x}} like described in [[iwd#WPA Enterprise]].<br />
<br />
=== Failed to request VPN secrets ===<br />
<br />
If you get this error:<br />
Failed to request VPN secrets #1: No agents were available for this request.<br />
<br />
It is either because the password is empty or you have to [[#Set up PolicyKit permissions|set up PolicyKit permissions]].<br />
<br />
== See also ==<br />
<br />
* [https://blogs.gnome.org/dcbw/2015/02/16/networkmanager-for-administrators-part-1/ NetworkManager for Administrators Part 1]<br />
* [[Wikipedia:NetworkManager]]<br />
* [https://networkmanager.dev/ NetworkManager official website]</div>PhilippDhttps://wiki.archlinux.org/index.php?title=I3&diff=446958I32016-08-18T11:30:32Z<p>PhilippD: /* Screensaver and power management */ i3lock needs a forking systemd service.</p>
<hr />
<div>{{DISPLAYTITLE:i3}}<br />
[[Category:Tiling WMs]]<br />
[[Category:Dynamic WMs]]<br />
[[ja:i3]]<br />
[[ko:I3]]<br />
[[ru:I3]]<br />
[[zh-CN:I3]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Window manager}}<br />
{{Related|Comparison of tiling window managers}}<br />
{{Related|Clipboard}}<br />
{{Related|Autostarting#Graphical}}<br />
{{Related articles end}}<br />
[http://i3wm.org/ i3] is a dynamic [[Wikipedia:Tiling window manager|tiling window manager]] inspired by [[wmii]] that is primarily targeted at developers and advanced users.<br />
<br />
The stated goals for i3 include clear documentation, proper multi-monitor support, a tree structure for windows, and different modes like in [[vim]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Grp|i3}} [[Pacman#Installing package groups|package group]]. It includes the window manager {{Pkg|i3-wm}}, {{Pkg|i3status}} which writes a status line to i3bar through [[Wikipedia:Standard streams#Standard output (stdout)|stdout]], and {{Pkg|i3lock}}, a screen locker.<br />
<br />
Additional packages are available in the [[Arch User Repository]]. See the section [[#Patches]] for examples.<br />
<br />
=== Display manager ===<br />
<br />
{{Pkg|i3-wm}} includes {{ic|i3.desktop}} as [[Xsession]] which starts the window manager. {{ic|i3-with-shmlog.desktop}} enables logs (useful for debugging). {{AUR|i3-gnome}} integrates {{ic|i3}} into [[GNOME]].<br />
<br />
=== xinitrc ===<br />
<br />
Edit [[Xinitrc]], and add:<br />
<br />
exec i3<br />
<br />
To log the output from i3, add this line instead:<br />
<br />
exec i3 -V >> ~/i3log-$(date +'%F-%k-%M-%S') 2>&1<br />
<br />
== Usage ==<br />
<br />
See the [http://i3wm.org/docs official documentation] for more information, namely the [http://i3wm.org/docs/userguide.html i3 User’s Guide].<br />
<br />
=== Keybindings ===<br />
<br />
In i3, commands are invoked with a modifier key, referred to as {{ic|$mod}}. This is {{ic|Alt}} (Mod1) by default, with {{ic|Super}} (Mod4) being a popular alternative. Super is the key usually represented on a keyboard as a Windows icon, or on an Apple keyboard as a Command key.<br />
<br />
See the [http://i3wm.org/docs/refcard.html i3 reference card] and [http://i3wm.org/docs/userguide.html#_using_i3 Using i3] for the defaults. See [http://i3wm.org/docs/userguide.html#keybindings Keyboard bindings] to add new shortcuts.<br />
<br />
Users of non-Qwerty keyboard layouts may wish to circumvent the "configuration wizard" as [[#Configuration wizard and alternative keyboard layouts|described below]].<br />
<br />
=== Containers ===<br />
<br />
i3 manages windows in a tree structure, with containers as building blocks. This structure branches with horizontal or vertical splits. Containers are tiled by default, but can be set to tabbed or stacked layouts, as well as made floating (such as for dialog windows). Floating windows are always on top.<br />
<br />
See [http://i3wm.org/docs/userguide.html#_tree i3 Tree] and [http://www.youtube.com/watch?v=AWA8Pl57UBY Containers and the tree data structure] for details.<br />
<br />
=== Application launcher ===<br />
<br />
i3 uses [[dmenu]] as an application launcher, which is bound by default to {{ic|$mod+d}}.<br />
<br />
{{Pkg|i3-wm}} contains ''i3-dmenu-desktop'', a [[Wikipedia:Perl|Perl]] wrapper for ''dmenu'' which uses [[desktop entries]] to create a list of all installed applications. Alternatively, the package {{AUR|j4-dmenu-desktop-git}} can be used.<br />
<br />
== Configuration ==<br />
<br />
See [http://i3wm.org/docs/userguide.html#configuring Configuring i3] for details. The rest of this article assumes the ''i3'' configuration file to be in the folder {{ic|~/.config}}.<br />
<br />
=== Configuration wizard and alternative keyboard layouts ===<br />
<br />
When ''i3'' is first started, it offers to run the configuration wizard ''i3-config-wizard''. This tool creates {{ic|~/.config/i3/config}} by rewriting a template configuration file in {{ic|/etc/i3/config.keycodes}}. It makes two modifications to the default template: <br />
<br />
# It asks the user to choose a default modifier key, which it adds to the template as a single line, like {{ic|set $mod Mod1}}; and <br />
# it replaces all ''bindcode'' lines with ''bindsym'' lines corresponding to the user's current keyboard layout.<br />
<br />
Step 2 is designed to ensure that the four navigation shortcuts, {{ic|j}}, {{ic|k}}, {{ic|l}} and "semicolon" on a Qwerty keyboard, will be mapped to keysyms which have the same location, e.g. {{ic|h}}, {{ic|t}}, {{ic|n}}, {{ic|s}} on a [[Dvorak]] keyboard. The side-effect of this magic is that up to fifteen other keysyms may be remapped in ways which break the mnemonics - so that, for a Dvorak user, "restart" is bound to {{ic|$mod1+p}} instead of {{ic|$mod1+r}}, "split horizontally" is bound to {{ic|$mod1+d}} instead of {{ic|$mod1+h}}, and so on.<br />
<br />
Therefore, users of alternate keyboard layouts who want straightforward key bindings, which match the bindings given in tutorials, may prefer to circumvent the "config wizard". This can be done by just copying {{ic|/etc/i3/config}} into {{ic|~/.config/i3/config}} (or {{ic|~/.i3/config}}), and editing that file.<br />
<br />
Note that a keycode-based configuration is also possible, e.g. for users who often switch between keyboard layouts, but want the i3 bindings to stay the same.<br />
<br />
=== Colorschemes ===<br />
<br />
The configuration file allows for customization of window decoration colors, but the syntax makes it impractical to create or share themes. There are several projects which make this easier and include a variety of user-contributed themes.<br />
<br />
* {{App|i3-style|Modifies your config in place from a theme stored in a JSON object, designed for frequently tweaking or changing a colorscheme|https://github.com/acrisci/i3-style|{{Aur|nodejs-i3-style}}{{Broken package link|{{aur-mirror|nodejs-i3-style}}}}}}<br />
* {{App|j4-make-config|Merge your config with a collection of themes or personal config parts, for example host-specific configuration, allowing quick changing of the theme and flexible, dynamic customization of the configuration|https://github.com/okraits/j4-make-config|{{Aur|j4-make-config-git}}}}<br />
<br />
=== i3bar ===<br />
<br />
In addition to showing workspace information, i3bar can act as an input for i3status or an alternative, such as those mentioned in the next section. For example:<br />
<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
output LVDS1<br />
status_command i3status<br />
position top<br />
mode hide<br />
workspace_buttons yes<br />
tray_output none<br />
<br />
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1<br />
<br />
colors {<br />
background #000000<br />
statusline #ffffff<br />
<br />
focused_workspace #ffffff #285577<br />
active_workspace #ffffff #333333<br />
inactive_workspace #888888 #222222<br />
urgent_workspace #ffffff #900000<br />
}<br />
}<br />
}}<br />
<br />
See the [http://i3wm.org/docs/userguide.html#_configuring_i3bar Configuring i3bar] for details.<br />
<br />
==== i3bar alternatives ====<br />
<br />
Some users may prefer panels such as those provided by conventional [[Desktop environment|Desktop Environments]]. This can be achieved within i3 by launching the panel application of choice during startup.<br />
<br />
For the [[Xfce#Panel|XFCE panel]]{{Broken section link}}, add the following line anywhere in {{ic|~/.config/i3/config}}:<br />
<br />
exec --no-startup-id xfce4-panel --disable-wm-check<br />
<br />
i3bar can be disabled by commenting the {{ic|<nowiki>bar{ }</nowiki>}} section of {{ic|~/.config/i3/config}}, or defining a keybind to toggle the bar:<br />
<br />
{{hc|~/.config/i3/config|<br />
# bar toggle, hide or show <br />
bindsym $mod+m bar mode toggle<br />
}}<br />
<br />
=== i3status ===<br />
<br />
Copy over the default configuration files to the home directory:<br />
<br />
$ cp /etc/i3status.conf ~/.config/i3status/config<br />
<br />
Not all plugins are defined in the default configuration and some configuration values may be invalid for your system, so the need to be updated accordingly. See {{ic|man i3status}} for details.<br />
<br />
==== i3status replacements ====<br />
<br />
* {{App|[[conky]]| Highly extensible system monitor. For usage with i3bar see [http://i3wm.org/docs/user-contributed/conky-i3bar.html this tutorial] |https://github.com/brndnmtthws/conky|{{Pkg|conky}}}}<br />
* {{App|[[i3blocks]]|Extensible via shell scripts. It can handle click events, interrupts, and defining of refresh intervals on a per-block basis.|https://github.com/vivien/i3blocks|{{AUR|i3blocks}}}}<br />
* {{App|i3pystatus|Extensible Python 3 status bar with many plugins and configuration options by default.|https://github.com/enkore/i3pystatus i3pystatus|{{AUR|i3pystatus-git}}}}<br />
* {{App|i3situation|Another Python 3 status bar generator.|https://github.com/HarveyHunt/i3situation|{{Aur|i3situation-git}}}}<br />
* {{App|j4status|Provides a statusline, configurable via plugins, and written in C. Extra plugins are provided by {{Aur|j4status-plugins-git}}.|http://j4status.j4tools.org/|{{Aur|j4status-git}}}}<br />
* {{App|goi3bar|i3status replacement written in Go. Configuration-file driven with several plugins, concurrency options, and rich plugin support.|https://github.com/denbeigh2000/goi3bar/|{{Aur|goi3bar-git}}}}<br />
<br />
==== i3status wrappers ====<br />
<br />
* {{App|i3cat|A [[go]] based wrapper which can concatenate inputs from multiple external sources. It can handle click events and forwarding user specified signals to its subprocesses.|http://vincent-petithory.github.io/i3cat/|{{AUR|i3cat-git}}}}<br />
* {{App|py3status|An extensible i3status wrapper written in Python.|https://github.com/ultrabug/py3status|{{Aur|py3status}}}}<br />
<br />
==== Iconic fonts in the status bar ====<br />
<br />
''i3bar'' can be [[#Patches|patched]] for XBM icon support, but you can use iconic font sets instead.<br />
<br />
* {{App|ttf-font-awesome|Scalable vector icons that can be customized with CSS. A [http://fortawesome.github.io/Font-Awesome/cheatsheet/ cheatsheet] shows the Unicode point for each glyph.|http://fortawesome.github.io/Font-Awesome/|{{AUR|ttf-font-awesome}}}}<br />
* {{App|ttf-font-icons|Non-overlapping and consistently sized mix of Awesome and Ionicons. This also avoids minor overlapping between DejaVu Sans and Awesome.|http://kageurufu.net/icons.pdf|{{AUR|ttf-font-icons}}}}.<br />
<br />
To combine fonts, define a font fallback sequence in your configuration file, separating fonts with {{ic|,}} like so:<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
...<br />
font pango:DejaVu Sans Mono, Icons 8<br />
...<br />
}<br />
}}<br />
<br />
In accordance with [https://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string pango syntax], font size is specified only once, at the end of the comma-separated list of font families. Setting a size for each font would cause all but the last font to be ignored.<br />
<br />
Add icons to the format strings in {{ic|~/.config/i3status/config}} using the unicode numbers given in the cheatsheets linked above. The input method will vary between text editors. For instance, to insert the "heart" icon (unicode number f004):<br />
<br />
{{Merge|Internationalization|Should be described in one place; see also [[ArchWiki:Requests#Input methods]].}}<br />
<br />
* in various gui text editors (e.g. [[gedit]], Leafpad) and terminals (e.g. GNOME Terminal, xfce4-terminal): {{ic|ctrl+shift+u}}, {{ic|f004}}, {{ic|Enter}}<br />
* in [[Emacs]]: {{ic|ctrl+x}}, {{ic|8}}, {{ic|Enter}}, {{ic|f004}}, {{ic|Enter}}<br />
* in [[Vim]] (while in insert mode): {{ic|Ctrl+v}}, {{ic|uf004}}<br />
* in [[urxvt]]: while holding {{ic|Ctrl+Shift}}, type {{ic|f004}}<br />
<br />
=== Terminal emulator ===<br />
<br />
By default when pressing {{ic|$mod+Return}} it launches the {{ic|i3-sensible-terminal}} which is a script that invokes a terminal. See {{ic|man i3-sensible-terminal}} for the order terminals are invoked in.<br />
<br />
To instead launch a terminal of choice, modify this line in {{ic|~/.config/i3/config}}:<br />
<br />
bindsym $mod+Return exec i3-sensible-terminal<br />
<br />
Alternatively, set the {{ic|$TERMINAL}} [[environment variable]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Advanced window navigation ===<br />
<br />
See [http://www.slackword.net/?p=657 i3 window Navigation Tips].<br />
<br />
=== Jump to open window ===<br />
<br />
*{{App|quickswitch-i3|Python utility to quickly change to and locate windows in i3|https://github.com/proxypoke/quickswitch-for-i3|{{Aur|quickswitch-i3}}}}<br />
*{{App|i3-wm-scripts|search for and jump to windows with particular names matching regexp|https://github.com/yiuin/i3-wm-scripts||}}<br />
*{{App|winmenupy|Launches dmenu with a list of clients, sorted after workspaces. Selecting a client jumps to that window.|https://github.com/ziberna/i3-py/blob/master/examples/winmenu.py||}}<br />
*{{App|[[rofi]]|Search and jump to open and scratchpad window|https://davedavenport.github.io/rofi/|{{Pkg|rofi}}}}<br />
<br />
=== Jump to urgent window ===<br />
<br />
Add to {{ic|.i3/config}}: [https://faq.i3wm.org/question/853/how-to-jump-to-urgent-workspace/]<br />
<br />
bindsym $mod+x [urgent=latest] focus<br />
<br />
=== Save and restore the window layout ===<br />
<br />
From version 4.8, and onward ''i3'' can save and restore workspace layouts. To do this, the following packages are needed: {{Pkg|perl-anyevent-i3}} and {{Pkg|perl-json-xs}} from the [[official repositories]].<br />
<br />
{{note| This section only provides quick tutorial on how to save the current window layout of a single workspace and how to restore it for later use. Refer to the [http://i3wm.org/docs/layout-saving.html official documentation] for more details}}<br />
<br />
==== Save the current window layout of a single workspace ====<br />
<br />
To save the current window layout, follow these steps:<br />
<br />
# First, execute various commands to open windows in a preferred workspace and resize them if needed. Make sure to write down each executed command for each window.<br />
# Now, in a new workspace, open a terminal and run the following: {{bc|i3-save-tree --workspace N > ~/.i3/workspace_N.json}} where N is the number of the preferred workspace. This will save the current layout of workspace N to the file {{ic|~/.i3/workspace_N.json}}.<br />
# The newly created file needs to be edited, however this may be done with the following commands: {{bc|<nowiki>tail -n +2 ~/.i3/workspace_N.json | fgrep -v '// splitv' | sed 's|//||g' > ~/.i3/workspace_N.json</nowiki>}}<br />
<br />
==== Restore the window layout of the workspace ====<br />
<br />
There are two ways to restore the layout of the workspace: by writing a script, or by editing {{ic|~/.i3/config}} to automatically load the layout. In this section only the first case will be considered, refer to the [http://i3wm.org/docs/layout-saving.html#_restoring_the_layout official documentation] for the second case.<br />
<br />
To restore the saved layout in the previous section, write a file named {{ic|load_layout.sh}} with the following contents:<br />
<br />
* The starting lines:<br />
<br />
{{hc|head=~/load_layout.sh|output=<br />
#!/bin/bash<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
}}<br />
<br />
where M is the number of the workspace in which you would like to load the previously saved layout and N is the number of workspace saved in the previous section.<br />
* And the commands used in the previous section to get the preferred windows, but enclosed in parentheses and with an ampersand appended before the last parentheses.<br />
<br />
For example, if the saved layout contained three {{ic|uxterm}} windows:<br />
<br />
{{hc|head=~/load_layout.sh|output=<br />
#!/bin/bash<br />
<br />
# First we append the saved layout of worspace N to workspace M<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
<br />
# And finally we fill the containers with the programs they had<br />
(uxterm &)<br />
(uxterm &)<br />
(uxterm &)<br />
}}<br />
<br />
Then set the file as executable:<br />
<br />
chmod u+x ~/load_layout.sh<br />
<br />
And finally, the layout of worskpace N can be loaded onto to workspace M by running:<br />
<br />
~/load_layout.sh<br />
<br />
{{tip|Adding {{ic|bindsym $mod+g exec ~/load_layout.sh}} to {{ic|~/.i3/config}} and restarting i3 will bind Mod+g to run the above script.}}<br />
<br />
{{note|If the above script does not work properly, refer to the [http://i3wm.org/docs/layout-saving.html#_editing_layout_files official documentation]. The ''swallows'' sections of {{ic|~/.i3/workspace_N.json}} needs to be manually edited.}}<br />
<br />
=== Scratchpad containers ===<br />
<br />
By default, [http://i3wm.org/docs/userguide.html#_scratchpad scratchpads] only contain a single window. However, containers can also be made a scratchpad.<br />
<br />
Create a new container (for example, {{ic|Mod+Enter}}), split it ({{ic|Mod+v}}) and create another container. Focus the parent ({{ic|Mod+a}}), split in the opposite direction ({{ic|Mod+h}}), and create again. <br />
<br />
Focus the first container (with focus parent as needed), make the window floating ({{ic|Mod+Shift+Space}}), and move it to the scratchpad ({{ic|Mod+Shift+-}}). You can now split containers to preference.<br />
<br />
{{Note|Containers cannot be resized individually in floating windows. Resize the containers before making windows floating.}}<br />
{{Tip|When only using terminal applications, consider a multiplexer such as [[tmux]] instead.}}<br />
<br />
See also [https://faq.i3wm.org/question/138/multiple-scratchpad/i3] for multiple scratchpads.<br />
<br />
=== Screensaver and power management ===<br />
<br />
With [[Power management#xss-lock]] you can register a screenlocker for your i3 session. The {{ic|-time}} option locks the screen after a given time period.<br />
<br />
xautolock -time 10 -locker "i3lock -i 'background_image.png'" &<br />
<br />
A [[systemd]] service file can be used to lock the screen before the system is being sent to sleep or hibernation state. See [[Power management#Suspend/resume service files]]. Note that i3lock requires the type of the service to be {{ic|forking}}.<br />
<br />
See also [[DPMS]].<br />
<br />
=== Shutdown, reboot, lock screen ===<br />
<br />
Key combinations for shutdown, reboot and screenlock can be added to {{ic|~/.config/i3/config}}. The below example assumes you have {{Pkg|polkit}} installed to allow unprivileged users to run [[systemd#Power_management|power management]] commands.<br />
<br />
{{bc|<br />
set $Locker i3lock && sleep 1<br />
<br />
set $mode_system System (l) lock, (e) logout, (s) suspend, (h) hibernate, (r) reboot, (Shift+s) shutdown<br />
mode "$mode_system" {<br />
bindsym l exec --no-startup-id $Locker, mode "default"<br />
bindsym e exec --no-startup-id i3-msg exit, mode "default"<br />
bindsym s exec --no-startup-id $Locker && systemctl suspend, mode "default"<br />
bindsym h exec --no-startup-id $Locker && systemctl hibernate, mode "default"<br />
bindsym r exec --no-startup-id systemctl reboot, mode "default"<br />
bindsym Shift+s exec --no-startup-id systemctl poweroff -i, mode "default" <br />
<br />
# back to normal: Enter or Escape<br />
bindsym Return mode "default"<br />
bindsym Escape mode "default"<br />
}<br />
<br />
bindsym $mod+Pause mode "$mode_system"<br />
}}<br />
<br />
Once completed, you will be presented with a prompt whenever you press {{ic|$mod+pause}}. For more complex behaviour, use a separate script, and refer to it in the mode. [https://gist.github.com/anonymous/c8cd0a59bf4acb273068]<br />
<br />
{{Note|1=<br><br />
* {{ic|sleep 1}} adds a small delay to prevent possible race conditions with suspend [https://bugs.launchpad.net/ubuntu/+source/unity-2d/+bug/830348]<br />
* The {{ic|-i}} argument for {{ic|systemctl poweroff}} causes a shutdown even if other users are logged-in (this requires {{Pkg|polkit}}), or when ''logind'' (wrongly) assumes so. [https://bugs.freedesktop.org/show_bug.cgi?id=62676]<br />
}}<br />
<br />
For a list of alternative screen lockers, see [[List of applications/Security#Screen lockers]].<br />
<br />
===External displays manual management===<br />
<br />
Thanks to [[xrandr]] there are many ways to easily manage systems displays. The below example integrates it in the i3 config file, and behave as the Power Management section above.<br />
<br />
Here a laptop with both VGA and HDMI outputs will use a menu selection to switch them On/Off:<br />
<br />
## Manual management of external displays<br />
# Set the shortcuts and what they do<br />
set $mode_display Ext Screen (v) VGA ON, (h) HDMI ON, (x) VGA OFF, (y) HDMI OFF<br />
mode "$mode_display" {<br />
bindsym v exec --no-startup-id xrandr --output VGA1 --auto --right-of LVDS1, mode "default"<br />
bindsym h exec --no-startup-id xrandr --output HDMI1 --auto --right-of LVDS1, mode "default"<br />
bindsym x exec --no-startup-id xrandr --output VGA1 --auto --off, mode "default"<br />
bindsym y exec --no-startup-id xrandr --output HDMI1 --auto --off, mode "default"<br />
<br />
# back to normal: Enter or Escape<br />
bindsym Return mode "default"<br />
bindsym Escape mode "default"<br />
}<br />
# Declare here the shortcut to bring the display selection menu<br />
bindsym $mod+x mode "$mode_display"<br />
<br />
Any window that is still open in a switched Off display will automatically come back to the remaining active display.<br />
<br />
The simplest way to determine names of your devices is to plug the device you wish to use and run:<br />
<br />
$ xrandr --query<br />
<br />
which will output the available, recognized devices and their in-system names to set your config file appropriately. <br />
<br />
Refer to the [[xrandr]] page or man page for the complete list of available options, the [http://i3wm.org/docs/userguide.html i3 userguide] and/or the [https://www.reddit.com/r/i3wm i3 FAQ on reddit] for more info.<br />
<br />
=== Tabbed or stacked web-browsing ===<br />
<br />
Some web-browsers intentionally do not implement tabs, since managing tabs is considered to be the task of the window manager, not the task of the browser.<br />
<br />
To let i3 manage your tab-less web-browser, in this example for [[uzbl]], add the following line to your {{ic|~/.config/i3/config}}<br />
<br />
for_window [class="Uzbl-core"] focus child, layout stacking, focus<br />
<br />
This is for stacked web browsing, meaning that the windows will be shown vertically. The advantage over tabbed browsing is that the window-titles are fully visible, even if a lot of browser windows are open.<br />
<br />
If you prefer tabbed browsing, with windows in horizontal direction ('tabs'), use<br />
<br />
for_window [class="Uzbl-core"] focus child, layout tabbed, focus<br />
<br />
=== Workspace variables ===<br />
<br />
As workspaces are defined multiple times in i3, assigning workspace variables can be helpful. For example:<br />
<br />
set $WS1 term<br />
set $WS2 web<br />
set $WS3 misc<br />
set $WS4 media<br />
set $WS5 code<br />
<br />
Then replace workspace names with their matching variables:<br />
<br />
bindsym $mod+1 workspace $WS1<br />
...<br />
bindsym $mod+Shift+1 move container to workspace $WS1<br />
<br />
See [http://i3wm.org/docs/userguide.html#_changing_named_workspaces_moving_to_workspaces Changing named workspaces] for more information.<br />
<br />
=== Correct handling of floating dialogs ===<br />
<br />
While dialogs should open in floating mode by default [http://i3wm.org/docs/userguide.html#_floating], many still open in tiling mode. To change this behaviour, check the dialog's {{ic|WM_WINDOW_ROLE}} with {{pkg|xorg-xprop}} and add the correct rules to {{ic|~/.i3/config}} (using [http://www.pcre.org/ pcre] syntax):<br />
<br />
for_window [window_role="pop-up"] floating enable<br />
for_window [window_role="task_dialog"] floating enable<br />
<br />
You can also use title rules and regular expressions:<br />
<br />
for_window [title="Preferences$"] floating enable<br />
<br />
or {{ic|WM_CLASS}}:<br />
<br />
for_window [class="(?i)mplayer"] floating enable<br />
<br />
=== Network Download/Upload speed on statusbar ===<br />
<br />
You might adapt this upstream [http://code.stapelberg.de/git/i3status/tree/contrib/measure-net-speed.bash script]. For that,<br />
<br />
* rename both network cards according to your system (use {{ic|ip addr}})<br />
* find them on {{ic|/sys/devices}} then replace them appropriately:<br />
$ find /sys/devices -name ''network_interface''<br />
<br />
{{Tip|Use {{ic|/sys/class/net/''interface''/statistics/}} to not depend on PCI location.}}<br />
<br />
Now, just save the script in a suitable place (for example {{ic|~/.config/i3}}) and point your status program to it.<br />
<br />
== Patches ==<br />
<br />
{{Merge|#Installation|One package does not warrant a separate section}}<br />
<br />
Packages with patches not merged upstream are available in the [[AUR]]:<br />
<br />
* {{App|i3-wm-iconpatch|Titlebar icon support|https://github.com/ashinkarov/i3-extras|{{AUR|i3-wm-iconpatch}}}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== General ===<br />
<br />
In many cases, bugs are fixed in the development versions {{AUR|i3-git}} and {{AUR|i3status-git}}, and upstream will ask to reproduce any errors with this version. [http://i3wm.org/docs/debugging.html] See also [[Debug - Getting Traces#General]].<br />
<br />
=== Buttons in the i3 message bar do not work ===<br />
<br />
Buttons such as "Edit config" in {{ic|i3-nagbar}} call {{ic|i3-sensible-terminal}}, so make sure your [[#Terminal_emulator|Terminal emulator]] is recognized by i3.<br />
<br />
=== Faulty line wraps in tiled terminals ===<br />
<br />
i3 v4.3 and higher ignore size increment hints for tiled windows [https://www.mail-archive.com/i3-discuss@i3.zekjur.net/msg00709.html]. This may cause terminals to wrap lines prematurely, amongst other issues. As a workaround, make the offending window floating, before tiling it again.<br />
<br />
=== Mouse cursor remains in waiting mode ===<br />
<br />
When starting a script or application which does not support startup notifications, the mouse cursor will remain in busy/watch/clock mode for 60 seconds.<br />
<br />
To solve this for a particlar application, use the {{ic|--no-startup-id}} parameter, for example:<br />
exec --no-startup-id ~/script<br />
bindsym $mod+d exec --no-startup-id dmenu_run<br />
<br />
To disable this animation globally, see [[Cursor themes#Create links to missing cursors]].<br />
<br />
=== Unresponsive key bindings ===<br />
<br />
Some tools such as [[Taking_a_screenshot#scrot|scrot]] may not work when used with a regular key binding (executed after key press). In those cases, execute commands after key release with the {{ic|--release}} argument [http://i3wm.org/docs/userguide.html#keybindings]:<br />
<br />
bindsym --release Print exec --no-startup-id scrot<br />
bindsym --release Shift+Print exec --no-startup-id scrot -s<br />
<br />
=== Tearing ===<br />
<br />
i3 does [https://github.com/i3/i3/issues/661 not properly implement double buffering] hence tearing or flickering may occur. To prevent this, install and configure [[compton]]. [https://faq.i3wm.org/question/3279/do-i-need-a-composite-manager-compton.1#post-id-3282]<br />
<br />
=== Tray icons not visible ===<br />
<br />
The {{ic|tray_output primary}} directive may require setting a primary output with ''xrandr'', specifying the output explicitly or simply removing this directive. [https://github.com/i3/i3/issues/1144] See [[Xrandr]] for details. The default configuration created by i3-config-wizard no longer adds this directive to the configuration from i3 4.12.<br />
<br />
== See also ==<br />
<br />
* [http://i3wm.org Official website]<br />
* [http://www.funtoo.org/I3_Tiling_Window_Manager funtoo Wiki]<br />
* [http://code.stapelberg.de/git/i3 i3 Source code]<br />
* [https://github.com/ashinkarov/i3-extras i3-extras] - Collection of scripts and patches<br />
* [https://github.com/acrisci/i3ipc-glib i3ipc-glib] - A library for i3 extensions<br />
* [https://github.com/veelenga/i3ipc-ruby i3ipc-ruby] - An improved library for i3 extensions in Ruby<br />
* [http://www.j4tools.org/ j4tools] - non-official tools designed to work with i3<br />
<br />
'''Arch Linux Forums'''<br />
* [https://bbs.archlinux.org/viewtopic.php?id=99064 The i3 thread] - A general discussion about i3<br />
* [https://bbs.archlinux.org/viewtopic.php?id=103369 i3 desktop screenshots and config sharing]<br />
<br />
'''Screencasts'''<br />
* [http://www.youtube.com/watch?v=Wx0eNaGzAZU i3 window manager v4.1 screencast]<br />
* [https://www.youtube.com/watch?v=j1I63wGcvU4&index=1&list=PL5ze0DjYv5DbCv9vNEzFmP6sU7ZmkGzcf i3 window manager v4.1X screencasts]</div>PhilippDhttps://wiki.archlinux.org/index.php?title=Talk:Advanced_Linux_Sound_Architecture&diff=443318Talk:Advanced Linux Sound Architecture2016-07-26T19:23:38Z<p>PhilippD: /* Set the default sound card - Given advice does not work for me */ new section</p>
<hr />
<div>== Manually reloading settings from ~/.asoundrc ==<br />
<br />
Since the old "sudo rc.d restart alsa" and "sudo alsa force-reload" commands don't work anymore, it took me a bit of time the other day to figure out how to restart alsa without restarting the whole machine. Sometimes I make changes to ~/.asoundrc and want to make them effective without rebooting and this was the only command I found that could acheive this:<br />
alsactl kill rescan<br />
This should probably be added to the wiki somewhere but I wasn't sure where the best spot for it would be. Should it be a new section? There's a few areas of the alsa wiki that just say to "restart alsa" without specifying how to do so. These could probably be updated as well.<br />
<br />
[[User:Mynis|Mynis]] ([[User talk:Mynis|talk]]) 10:04, 14 May 2013 (UTC) mynis<br />
<br />
One year later, just in case somebody else with that problem gets here: <code>~/.asoundrc</code> is loaded by the ALSA library, not the kernel part. You can’t actually “restart ALSA” because it is not a daemon—you could reload the driver module but that is not going to have any other effect. ALSA configuration is loaded for each instance of the library, so to reload it, all you have to do is restart the programs that are using it.<br />
--[[User:Lachs0r|Lachs0r]] ([[User talk:Lachs0r|talk]]) 13:03, 29 May 2014 (UTC)<br />
<br />
:Alternatively, run {{ic|$ alsactl nrestore}}. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 13:29, 10 August 2014 (UTC)<br />
<br />
== On high quality resampling ==<br />
<br />
I’m not actually an Arch user and I don’t know what the default configuration is like, but to be honest, I believe the ALSA setup should use the libspeex-derived resampler by default, which offers much better quality than dumb linear interpolation, but without the performance implications of libsamplerate’s best converter.<br />
<br />
I don’t think any human being is able to tell the difference between libspeex and libsamplerate’s sinc resamplers because they both have about the same noise floor, which is actually lower than what 16-bit PCM audio can even represent. Thus, using the slower one is completely pointless.<br />
<br />
To support my claims, I’ve used the linear interpolation as well as some of the libspeex and libsamplerate converters. The test file was an 8 second 1-22050 Hz sine sweep generated with SoX as 32-bit signed integer PCM with 44.1 kHz sample rate. The output sample rate was 48 kHz, hence the most common conversion by far. The results were obtained by playing the test file through an ALSA ''rate'' device with a ''file'' device as its slave.<br />
<br />
These are the spectrograms of the results: [http://abload.de/img/resamplersgyoik.png]<br />
<br />
As you can see, all of these are way better than linear interpolation. The ''speexrate'' resampler might look bad at first in comparison to the others, but notice that the visible aliasing lines are actually very close to the noise floor, and certainly not bad enough to be noticeable. Not on this sine sweep, and certainly not on typical audio content. This is not a bad result at all, especially considering how fast this resampler is!<br />
<br />
Well, how fast is it? My tests have shown it to be roughly twice as fast as the corresponding ''libsamplerate'' resampler, and the trend continues with the higher quality modes:<br />
<br />
<pre><br />
linear: 0.01s user 0.04s system 0% cpu 8.138 total<br />
<br />
samplerate: 0.38s user 0.01s system 4% cpu 8.147 total<br />
speexrate: 0.24s user 0.01s system 2% cpu 8.137 total<br />
<br />
samplerate_medium: 0.60s user 0.01s system 7% cpu 8.149 total<br />
speexrate_medium: 0.32s user 0.06s system 4% cpu 8.143 total<br />
<br />
samplerate_best: 1.36s user 0.01s system 16% cpu 8.204 total<br />
speexrate_best: 0.79s user 0.01s system 9% cpu 8.166 total<br />
</pre><br />
<br />
Given these facts, it seems more like the common recommendation of using ''samplerate_best'' is based on a cargo cult myth rather than actual testing.<br />
--[[User:Lachs0r|Lachs0r]] ([[User talk:Lachs0r|talk]]) 13:06, 29 May 2014 (UTC)<br />
<br />
:Using subjective and pejorative terms like "placebo-quality" and "cult" that have no technical meaning whatsoever and only flame is highly discouraged. [Sampling] frequency is expressed in hertz, so it should be (in the article) 48000 Hz or better yet 48 kHz (there is a space in between the unit and the value, as suggested by several standards and norms). You used that here correctly, so why not in the article? I would also suggest you create a new page with the results you presented here and please include the exact procedure you used, so that others can reproduce it. Usually one should experiment with different scenarios, so testing several different input audio files, different resolutions and resampling converters with 96 kHz and 192 kHz as output SR would be nice. I appreciate your work, but the form you present it in could be better. --[[User:Emeres|Emeres]] ([[User talk:Emeres|talk]]) 12:26, 6 June 2014 (UTC)<br />
<br />
::Oh, I just left the first line of the section intact when I edited it. Yes, should have been 48 kHz. The results when resampling to different resolutions are very similar. The sine sweep was chosen because it shows certain characteristics such as aliasing, quantization noise and so on very clearly in the spectrograms (or actual listening tests), and using different input samples would serve no real purpose for that particular demonstration (hell, even the sine sweep is really hard to ABX with these resamplers). Some other graphs would be worthy additions, but actually that work has already been done by somebody else[http://src.infinitewave.ca], just lacking the results for the lower quality modes of the Speex resampler (note: on that site, libsamplerate is referred to by its code name “Secret Rabbit Code”). Sorry about the language I’ve employed here and in the summaries for some of my other edits; I was just disgruntled with the state of the Arch Wiki and the fact that I often had to tech support people who just followed some bad/outdated advice given in various articles. I tend to speak my mind in the wrong place when something like that happens. --[[User:Lachs0r|Lachs0r]] ([[User talk:Lachs0r|talk]]) 14:26, 6 June 2014 (UTC)<br />
<br />
== General Article Cleanup ==<br />
<br />
As stated in the section title, I think this page could use a large cleanup.<br />
Currently the troubleshooting section is quite a bit larger than the core<br />
article itself, and has some questionable advice, a lack of any sort of<br />
ordering, and just a big lack of consistency/concision in general. Just some<br />
examples:<br />
<br />
<s>[[Advanced_Linux_Sound_Architecture#Getting_S.2FPDIF_output]]<br />
<br />
Starts off referencing Gnome, when it should probably start the section<br />
off with the desktop agnostic method referenced below it.</s><br />
This has been addressed.<br />
<br />
<s>[[Advanced_Linux_Sound_Architecture#No_sound_with_Audigy_2_ZS]]</s><br />
<br />
This is arguably a bad solution. I'd be surprised if amixer could not accomplish this.<br />
<br />
:It looks like amixer could be used, but a confirmation from someone, who actually has the hardware would be better: {{bc|amixer sset 'Audigy Analog/Digital Output Jack' unmute # or on}}[https://help.ubuntu.com/community/SoundTroubleshootingProcedure#Step_15 Source 1], [http://forums.asterisk.org/viewtopic.php?f=1&t=88313&start=0#p193053 source 2]. The meq note should be expanded why it is relevant for headphones. It does cut in higher frequencies quite a bit, so I guess the author meant 2.0 in comparison to > 4.0, where higher frequencies are often the main aspect of the overall sound. Dmix references need to be inspected. Maybe a configuration like [https://bbs.archlinux.org/viewtopic.php?pid=1450413#p1450413 this one] should be emphasized, instead of the ever returning pcm.dmixed. The trouble shooting section could use a 'general troubleshooting' subsection on the top. I have a few lines written already, but the default section comes first.<br />
: -- [[User:Emeres|Emeres]] ([[User talk:Emeres|talk]]) 21:36, 13 September 2014 (UTC)<br />
<br />
::I've owned an Audigy 2, and alsamixer had no problem unmuting the card. Removed the section. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 14:48, 25 November 2014 (UTC)<br />
<br />
[[Advanced_Linux_Sound_Architecture#Using_mbeq]]<br />
<br />
I'm not sure how the note regarding stereophonic sound is relevant.<br />
<br />
These are obviously small issues, but the page is full of them. The<br />
troubleshooting section could most likely be trimmed down quite a bit just by<br />
combining similar problem cases and their respective solutions. Given the state<br />
of the troubleshooting section, I wouldn't be surprised if at least a few of the<br />
issues are fixed in current ALSA/Linux revisions.<br />
--[[User:Pyroh|Pyroh]] ([[User talk:Pyroh|talk]]) 01:42, 25 July 2014 (UTC)<br />
<br />
:I've already gotten started on the most egregious offenses, though there's still quite a<br />
:bit to do in terms of converting the page to a consistent writing style. I suppose this post<br />
:could be considered a bump, as I don't want to larger changes without some community<br />
:consultation. --[[User:Pyroh|Pyroh]] ([[User talk:Pyroh|talk]]) 02:30, 26 July 2014 (UTC)Pyroh<br />
<br />
::Hi, first of all please take care when removing nowiki tags from templates, I've had to [https://wiki.archlinux.org/index.php?title=Advanced_Linux_Sound_Architecture&diff=326866&oldid=326858 restore] some you removed.<br />
::Troubleshooting sections tend to become outdated in all articles, so it's very welcome if you try to update this article; it seems you're doing a good job in summarizing all your edits, so it's easy to understand what you're doing.<br />
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:00, 26 July 2014 (UTC)<br />
<br />
:::Thanks. I initially just removed all of the (nowiki tags) and then changed '1=' to '2=' and vice versa until there were no more {{ic|Template Error:}} messages. I assume you are implying that a lack of said error messages are not necessarily indicative of codified text being correctly displayed? I took a quick look over everything and it seemed to look fine, but I might have missed something as I was mainly checking the second portion of {{hc/{{bc references and I saw that you added nowiki tags around only the first portions.<br />
:::--[[User:Pyroh|Pyroh]] ([[User talk:Pyroh|talk]]) 07:04, 26 July 2014 (UTC)<br />
<br />
::::Correct, the fact that you don't see Template Errors does ''not'' mean that everything's all right. One frequent case is when the | (pipe) symbol has to be displayed, like in the cases that I've fixed; for example writing {{ic|<nowiki>{{bc|lsmod | grep snd}}</nowiki>}} displays: {{bc|lsmod | grep snd}}<br />
::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:52, 27 July 2014 (UTC)<br />
<br />
:::::The terms of card and device can be easily explained as follows; Card is a singular sound card which has one to many Devices. A multichannel card has a different device for each of the channels so the front, center, rear, and side each have their own device number. It should probably be noted that there is a common problem with having nvidia HDMI audio. The HDMI interface will be set as the default even when adding "options snd_hda_intel index=-2" what instead works is blacklisting the snd_hda_intel. I think the article would be easier to read by using the same card names throughout the article instead of listing specific examples for each section. I'll start working on that since it has been a while since any updates have been made.<br />
:::::[[User:Lucid|Lucid]] ([[User talk:Lucid|talk]]) 15:04, 9 July 2016 (UTC)<br />
<br />
== Adding a brief section on terminology ==<br />
<br />
This article seems to assume that readers are familiar with many of the terms and concepts used by ALSA. For example, this page extensively uses the term "PCM," but never defines it. I propose we add a short section called "Terminology" to the beginning of this page. Some points of interest might include:<br />
* What is a "PCM"? And what does it stand for?<br />
* How does a "card" differ from a "device"? (The amixer program suggests they are not synonymous.)<br />
* Is a "device," in the context of ALSA, in fact a device in the context of Linux (i.e. a block/character special file located in /dev)?<br />
* What is a "mixer"? Is it a "device" itself, some kind of pseudo-device, or something else entirely?<br />
* "S/PDIF"?<br />
<br />
I'm not suggesting that we recreate the entire [http://www.alsa-project.org/main/index.php/Documentation ALSA documentation] here, but rather that we define some of the terms used by this article, in order to make the article more approachable by readers who are not necessarily familiar with the language and concepts of ALSA. Thoughts? [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 13:26, 24 October 2014 (UTC)<br />
<br />
:I second the need to explain the non-obvious terms used in the article, however if this could be addressed through simple external links anchored at the proper keywords, it would be the best solution. For example PCM and S/PDIF are not specific to ALSA, and a link to e.g. their Wikipedia articles would be a cleaner solution. About the rest, I admit I haven't done any searches to see if ALSA's docs can be linked to specific sections that explain the concepts in details; if really it wouldn't be possible, I'd still like to avoid a "Terminology" section, whose expansion limits would be very unclear, and instead I'd suggest explaining the concepts (e.g. how a "card" differs from a "device") where they first appear in the article. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 02:55, 25 October 2014 (UTC)<br />
<br />
::Thanks for the feedback. That solution sounds good to me. I'll skim over the ALSA documentation as well as Wikipedia to see if I can find some of the appropriate links. I'm afraid, however, that I'm not qualified to handle some of the more detailed tasks (i.e. "card" vs "device"). After all, that's why I asked. I'll begin by outlinking some terms that have a suitable page elsewhere, and leave the structure to be modified by those who understand ALSA a little better.<br />
<br />
::Additionally, I'm not sure how much of this article also applies to other sound infrastructures, such as [[OSS]] and [[PulseAudio]], as I've never used anything else. With that being said, I wonder if it would be beneficial to move some of the broader topics to [[Sound]] or the like. That may have to be a project for another day, however. [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 13:17, 25 October 2014 (UTC)<br />
<br />
:::If you feel a section is lacking some details but you can't fix it yourself, fell free to mark it with [[Template:Expansion]] with a proper reason message.<br />
:::About splitting generic content, I'm not sure either, but it would certainly require a separate discussion with a more specific plan.<br />
:::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:31, 26 October 2014 (UTC)<br />
<br />
== Split up article into Main/Troubleshoot sections and reorganize Troubleshooting ==<br />
<br />
Lets move the Troubleshoot section to a new https://wiki.archlinux.org/index.php/Advanced_Linux_Sound_Architecture/Trobleshooting section and reorganize the Troubleshoot section similar to https://wiki.archlinux.org/index.php/PulseAudio/Troubleshooting I can do it, but I would prefer to do everything in one step, otherwise I loose focus on too many commit changes.<br />
Btw. should we add https://wiki.archlinux.org/index.php/Pro_Audio to "Related Articles"? --[[User:T.ask|T.ask]] ([[User talk:T.ask|talk]]) 16:19, 18 December 2014 (UTC)<br />
<br />
:+1 for moving [[Advanced Linux Sound Architecture#Troubleshooting]] to [[Advanced Linux Sound Architecture/Troubleshooting]]. I'm not sure what you mean with "one step", but to help you not lose focus, I've taken the chance to finally create a page with check lists when performing complex operations: you are interested in [[Help:Procedures#Split section to a new subpage]].<br />
:About the link to [[Pro Audio]], there's already a link to [[Sound system]] in the Related box, which in turn does link to [[Pro Audio]], but I wouldn't have objections if you added a direct link to [[Pro Audio]] also from this very article.<br />
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 01:45, 20 December 2014 (UTC)<br />
<br />
== Usage of "Advanced Linux Sound Architecture ...X..Y..Z..." lowers readability ==<br />
<br />
Please, use the well known abbreviation '''ALSA''' inside the article/for references.<br />
It's already difficult enough to read this page. Instead of using long names as "'''Advanced Linux Sound Architecture/Example Configurations'''" or " '''Advanced Linux Sound Architecture/Troubleshooting'''" please use short and easy readable "'''ALSA Configurations'''" and "'''ALSA Troubleshooting'''" instead. The term ALSA is widely used AND known in written and spoken terms. Besides, who would enter "'''Advanced Linux Sound Architecture/Example Configurations/Troubleshooting'''" or it's words as a search term?! It's fine once for the main article. Please, don't make it more complicated as it already is. --[[User:T.ask|T.ask]] ([[User talk:T.ask|talk]]) 16:07, 10 March 2015 (UTC)<br />
<br />
:I couldn't find any links in this page using the full title, except for the two in the related box, is this meant to be only a generic reminder? — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:23, 12 March 2015 (UTC)<br />
<br />
::Yes. I just read that its probably not possible to flip the current wording. If we can change it, then I would suggest to flip the wording for those three entries. --[[User:T.ask|T.ask]] ([[User talk:T.ask|talk]]) 12:59, 12 March 2015 (UTC)<br />
<br />
:::It does not matter how long the titles are, redirect pages such as [[ALSA/Troubleshooting]] can be used for references where long titles are not desired. It's just a matter of using them...<br />
:::In the "Related articles" box, I don't know if it's better to use redirects with more readable title or the full name, making it clear that the target is a ''subpage'' of the main page. I've recently applied the latter choice, but I'm open for discussing it further.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:12, 12 March 2015 (UTC)<br />
<br />
::::I too prefer the full title in the related box for the same reason, while in the body of the article it's indeed better to use the short redirect. Do we need to keep this discussion open? — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:23, 13 March 2015 (UTC)<br />
<br />
== Mention caps package in equalizer section ==<br />
<br />
I tried to follow the System-wide equalizer section (using ALSAEqual), but got the following error:<br />
<br />
Failed to load plugin "/usr/lib/ladspa/caps.so": /usr/lib/ladspa/caps.so: cannot open shared object file: No such file or directory<br />
<br />
It works after installing the {{Pkg|caps}} package, so I guess it should be mentioned that this package is required. —[[User:LucasWerkmeister|LucasWerkmeister]] ([[User talk:LucasWerkmeister|talk]]) 12:36, 17 January 2016 (UTC)<br />
<br />
== Set the default sound card - Given advice does not work for me ==<br />
<br />
I tried the settings listed in this section without any success on my Raspberry Pi. <br />
<br />
{{hc|/etc/modprobe.d/alsa-base.conf|2=<br />
options snd_mia index=0<br />
options snd_hda_intel index=1<br />
}}<br />
<br />
The order of the sound cards remained unchanged even after a reboot. Can anyone confirm?<br />
<br />
[[User:PhilippD|PhilippD]] ([[User talk:PhilippD|talk]]) 19:23, 26 July 2016 (UTC)</div>PhilippDhttps://wiki.archlinux.org/index.php?title=Talk:I3&diff=440440Talk:I32016-07-08T17:22:22Z<p>PhilippD: /* xautolock -lockaftersleep */</p>
<hr />
<div>== [[I3#Containers]] ==<br />
<br />
This section has a note saying it should be expanded. After reading the linked article ([http://i3wm.org/docs/userguide.html#_tree here) I don't see what needs expansion; to me it's quite clear and concise in conveying i3's concept of containers.<br />
--[[User:Pyroh|Pyroh]] ([[User talk:Pyroh|talk]]) 23:25, 27 July 2014 (UTC)<br />
<br />
:Well to the experienced user it may be quite clear, but personally I've found it not easy to tackle for the beginner. I'd thought of some simple examples (like a tabbed container layout with splits), as well as "focus child" which is not covered in the user's guide. Thoughts? -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 23:54, 27 July 2014 (UTC)<br />
<br />
::What has spountaneously come to my mind after reading these comments, is that i3 focuses so much on clarity of official documentation that they'd probably be happy if someone reported that some section is not clear enough, possibly attaching a "patched" version or some suggestions on how to improve it. However, I understand this is not as practical as editing this article directly, so at least I guess the reason for the Expansion template should be "expanded" with more precise indications of what's required. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 12:35, 29 July 2014 (UTC)<br />
<br />
== xautolock -lockaftersleep ==<br />
<br />
:''[Forward from email. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 19:02, 21 December 2015 (UTC)]''<br />
Hi, i've seen you've reverted back my changes on i3's wiki page, but i've seen that the -lockaftersleep of xautolock doesn't exist under its man.<br />
<br />
-- [[User:Toketin|Toketin]] Sun 20:29<br />
<br />
::The reason I've reverted the edit is because it duplicated [[Power management]], which users of other window managers benefit from as well (I realize I didn't set the right example by posting power management tips in the BBS i3 thread ...)<br />
::Anyway, if you can confirm the option doesn't work, feel free to remove it (I can't check it right now). -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 19:07, 21 December 2015 (UTC)<br />
::I have now removed the lockaftersleep option for the previously stated reason and added a link to systemd service files as I personally use these as a replacement. [[User:PhilippD|PhilippD]] ([[User talk:PhilippD|talk]]) 17:21, 8 July 2016 (UTC)</div>PhilippDhttps://wiki.archlinux.org/index.php?title=I3&diff=440438I32016-07-08T17:18:07Z<p>PhilippD: /* Screensaver and power management */ Instead of the vanished xautolock lockaftersleep option, there is now a hint to systemd unit files.</p>
<hr />
<div>{{DISPLAYTITLE:i3}}<br />
[[Category:Tiling WMs]]<br />
[[Category:Dynamic WMs]]<br />
[[ja:i3]]<br />
[[ko:I3]]<br />
[[ru:I3]]<br />
[[zh-CN:I3]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Window manager}}<br />
{{Related|Comparison of tiling window managers}}<br />
{{Related|Clipboard}}<br />
{{Related|Autostarting#Graphical}}<br />
{{Related articles end}}<br />
[http://i3wm.org/ i3] is a dynamic [[Wikipedia:Tiling window manager|tiling window manager]] inspired by [[wmii]] that is primarily targeted at developers and advanced users.<br />
<br />
The stated goals for i3 include clear documentation, proper multi-monitor support, a tree structure for windows, and different modes like in [[vim]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Grp|i3}} [[Pacman#Installing package groups|package group]]. It includes the window manager {{Pkg|i3-wm}}, {{Pkg|i3status}} which writes a status line to i3bar through [[Wikipedia:Standard streams#Standard output (stdout)|stdout]], and {{Pkg|i3lock}}, a screen locker.<br />
<br />
Additional packages are available in the [[Arch User Repository]]. See the section [[#Patches]] for examples.<br />
<br />
=== Display manager ===<br />
<br />
{{Pkg|i3-wm}} includes {{ic|i3.desktop}} as [[Xsession]] which starts the window manager. {{ic|i3-with-shmlog.desktop}} enables logs (useful for debugging). {{AUR|i3-gnome}} integrates {{ic|i3}} into [[GNOME]].<br />
<br />
=== xinitrc ===<br />
<br />
Edit [[Xinitrc]], and add:<br />
<br />
exec i3<br />
<br />
To log the output from i3, add this line instead:<br />
<br />
exec i3 -V >> ~/i3log-$(date +'%F-%k-%M-%S') 2>&1<br />
<br />
If you have trouble mapping keys (e.g. {{ic|;}} as semicolon), use {{Pkg|xorg-xev}} or see [[Extra keyboard keys]].<br />
<br />
$ xev | grep -A2 --line-buffered '^KeyRelease' | sed -n '/keycode /s/^.*keycode \([0-9]*\).* (.*, \(.*\)).*$/\1 \2/p'<br />
<br />
== Usage ==<br />
<br />
See the [http://i3wm.org/docs official documentation] for more information, namely the [http://i3wm.org/docs/userguide.html i3 User’s Guide].<br />
<br />
=== Keybindings ===<br />
<br />
In i3, commands are invoked with a modifier key, referred to as {{ic|$mod}}. This is {{ic|Alt}} (Mod1) by default, with {{ic|Super}} (Mod4) being a popular alternative. Super is the key usually represented on a keyboard as a Windows icon, or on an Apple keyboard as a Command key.<br />
<br />
See the [http://i3wm.org/docs/refcard.html i3 reference card] and [http://i3wm.org/docs/userguide.html#_using_i3 Using i3] for the defaults. See [http://i3wm.org/docs/userguide.html#keybindings Keyboard bindings] to add new shortcuts.<br />
<br />
Users of non-Qwerty keyboard layouts may wish to circumvent the "configuration wizard" as [[#Configuration wizard and alternative keyboard layouts|described below]].<br />
<br />
=== Containers ===<br />
<br />
{{Expansion|The User's guide explains basic use of containers, yet is not sufficiently clear to allow more advanced use cases. It also does not mention ''focus child'' as it does ''focus parent''. See also: [https://faq.i3wm.org/question/222/how-to-get-rid-of-another-container/], [https://github.com/i3/i3/issues/1326]}}<br />
<br />
i3 manages windows in a tree structure, with containers as building blocks. This structure branches with horizontal or vertical splits. Containers are tiled by default, but can be set to tabbed or stacked layouts, as well as made floating (such as for dialog windows). Floating windows are always on top.<br />
<br />
See [http://i3wm.org/docs/userguide.html#_tree i3 Tree] and [http://www.youtube.com/watch?v=AWA8Pl57UBY Containers and the tree data structure] for details.<br />
<br />
=== Application launcher ===<br />
<br />
i3 uses [[dmenu]] as an application launcher, which is bound by default to {{ic|$mod+d}}. As an alternative, one can use {{AUR|dmenu2}} from the AUR which has many more features including transparency and support for xft fonts.<br />
<br />
{{Pkg|i3-wm}} contains ''i3-dmenu-desktop'', a [[Wikipedia:Perl|Perl]] wrapper for ''dmenu'' which uses [[desktop entries]] to create a list of all installed applications. Alternatively, the package {{AUR|j4-dmenu-desktop-git}} can be used; it is a near-drop-in replacement for ''i3-dmenu-desktop'', but much faster [https://github.com/enkore/j4-dmenu-desktop/blob/master/README.md].<br />
<br />
== Configuration ==<br />
<br />
See [http://i3wm.org/docs/userguide.html#configuring Configuring i3] for details. The rest of this article assumes the ''i3'' configuration file to be in the folder {{ic|~/.config}} (contrary to ''i3-config-wizard'', which creates {{ic|~/.i3/config}}).<br />
<br />
=== Configuration wizard and alternative keyboard layouts ===<br />
<br />
When ''i3'' is first started, it offers to run the configuration wizard ''i3-config-wizard''. This tool creates {{ic|~/.i3/config}} by rewriting a template configuration file in {{ic|/etc/i3/config.keycodes}}. It makes two modifications to the default template: <br />
<br />
# It asks the user to choose a default modifier key, which it adds to the template as a single line, like {{ic|set $mod Mod1}}; and <br />
# it replaces all ''bindcode'' lines with ''bindsym'' lines corresponding to the user's current keyboard layout.<br />
<br />
Step 2 is designed to ensure that the four navigation shortcuts, {{ic|j}}, {{ic|k}}, {{ic|l}} and "semicolon" on a Qwerty keyboard, will be mapped to keysyms which have the same location, e.g. {{ic|h}}, {{ic|t}}, {{ic|n}}, {{ic|s}} on a [[Dvorak]] keyboard. The side-effect of this magic is that up to fifteen other keysyms may be remapped in ways which break the mnemonics - so that, for a Dvorak user, "restart" is bound to {{ic|$mod1+p}} instead of {{ic|$mod1+r}}, "split horizontally" is bound to {{ic|$mod1+d}} instead of {{ic|$mod1+h}}, and so on.<br />
<br />
Therefore, users of alternate keyboard layouts who want straightforward key bindings, which match the bindings given in tutorials, may prefer to circumvent the "config wizard". This can be done by just copying {{ic|/etc/i3/config}} into {{ic|~/.config/i3/config}} (or {{ic|~/.i3/config}}), and editing that file.<br />
<br />
Note that a keycode-based configuration is also possible, e.g. for users who often switch between keyboard layouts, but want the i3 bindings to stay the same.<br />
<br />
=== Colorschemes ===<br />
<br />
The configuration file allows for customization of window decoration colors, but the syntax makes it impractical to create or share themes. There are several projects which make this easier and include a variety of user-contributed themes.<br />
<br />
* {{App|i3-style|Modifies your config in place from a theme stored in a JSON object, designed for frequently tweaking or changing a colorscheme|https://github.com/acrisci/i3-style|{{Aur|nodejs-i3-style}}{{Broken package link|{{aur-mirror|nodejs-i3-style}}}}}}<br />
* {{App|j4-make-config|Merge your config with a collection of themes or personal config parts, for example host-specific configuration, allowing quick changing of the theme and flexible, dynamic customization of the configuration|https://github.com/okraits/j4-make-config|{{Aur|j4-make-config-git}}}}<br />
<br />
=== i3bar ===<br />
<br />
In addition to showing workspace information, i3bar can act as an input for i3status or an alternative, such as those mentioned in the next section. For example:<br />
<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
output LVDS1<br />
status_command i3status<br />
position top<br />
mode hide<br />
workspace_buttons yes<br />
tray_output none<br />
<br />
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1<br />
<br />
colors {<br />
background #000000<br />
statusline #ffffff<br />
<br />
focused_workspace #ffffff #285577<br />
active_workspace #ffffff #333333<br />
inactive_workspace #888888 #222222<br />
urgent_workspace #ffffff #900000<br />
}<br />
}<br />
}}<br />
<br />
See the [http://i3wm.org/docs/userguide.html#_configuring_i3bar Configuring i3bar] for details.<br />
<br />
==== i3bar alternatives ====<br />
<br />
{{Accuracy|i3 is [[Wikipedia:Extended_Window_Manager_Hints|NETWM]] compliant, so workspace management from external panels should usally work. See also [http://i3wm.org/docs/wsbar.html]}}<br />
<br />
Some users may prefer panels such as those provided by conventional [[Desktop environment|Desktop Environments]]. This can be achieved within i3 by launching the panel application of choice during startup.<br />
<br />
For the [[Xfce#Panel|XFCE panel]], add the following line anywhere in {{ic|~/.config/i3/config}}:<br />
<br />
exec --no-startup-id xfce4-panel --disable-wm-check<br />
<br />
{{Note|Panel features that are specific to the [[Desktop environment]] (e.g., widgets for managing workspaces/sessions) will most likely not work, though i3's functionality should remain unaffected.}}<br />
<br />
i3bar can be disabled by commenting out the {{ic|<nowiki>bar{ }</nowiki>}} section of {{ic|~/.config/i3/config}} or using: <br />
<br />
{{hc|~/.config/i3/config|<br />
# bar toggle, hide or show <br />
bindsym $mod+m bar mode toggle<br />
}}<br />
<br />
This way you can show or hide bar as you want.<br />
<br />
=== i3status ===<br />
<br />
Copy over the default configuration files to the home directory:<br />
<br />
$ cp /etc/i3status.conf ~/.config/i3status/config<br />
<br />
Not all plugins are defined in the default configuration and some configuration values may be invalid for your system, so the need to be updated accordingly. See {{ic|man i3status}} for details.<br />
<br />
==== i3status replacements ====<br />
<br />
* {{App|[[conky]]| Highly extensible system monitor. For usage with i3bar see [http://i3wm.org/docs/user-contributed/conky-i3bar.html this tutorial] |https://github.com/brndnmtthws/conky|{{Pkg|conky}}}}<br />
* {{App|[[i3blocks]]|Extensible via shell scripts. It can handle click events, interrupts, and defining of refresh intervals on a per-block basis.|https://github.com/vivien/i3blocks|{{AUR|i3blocks}}}}<br />
* {{App|i3phtatus|An easily extensible i3status replacement meant for i3bar, written in PHP.|https://github.com/mwgg/i3phtatus}}<br />
* {{App|i3-phpbar|Same replacement for i3bar, written in PHP.|https://github.com/johnynsk/i3-phpbar}}<br />
* {{App|goi3bar|Concurrent, extensible i3status replacement written in Go. Components can update at individual rates. |https://github.com/denbeigh2000/goi3bar}}<br />
* {{App|i3pystatus|Extensible Python 3 status bar with many plugins and configuration options by default.|https://github.com/enkore/i3pystatus i3pystatus|{{AUR|i3pystatus-git}}}}<br />
* {{App|i3situation|Another Python 3 status bar generator.|https://github.com/HarveyHunt/i3situation|{{Aur|i3situation-git}}}}<br />
* {{App|j4status|Provides a statusline, configurable via plugins, and written in C. Extra plugins are provided by {{Aur|j4status-plugins-git}}.|http://j4status.j4tools.org/|{{Aur|j4status-git}}}}<br />
<br />
==== i3status wrappers ====<br />
<br />
* {{App|[[h2status]]|Bash wrapper for i3status that allows custom json entries as input, and can handle click events as well as asynchronous updates of the status bar.|[[H2status]]|{{Aur|h2status}}{{Broken package link|{{aur-mirror|h2status}}}}}}<br />
* {{App|i3cat|A [[go]] based wrapper which can concatenate inputs from multiple external sources. It can handle click events and forwarding user specified signals to its subprocesses.|http://vincent-petithory.github.io/i3cat/|{{AUR|i3cat-git}}}}<br />
* {{App|py3status|An extensible i3status wrapper written in Python.|https://github.com/ultrabug/py3status|{{Aur|py3status}}}}<br />
<br />
==== Iconic fonts in the status bar ====<br />
<br />
''i3bar'' can be [[#Patches|patched]] for XBM icon support, but you can use iconic font sets instead.<br />
<br />
* {{App|ttf-font-awesome|Scalable vector icons that can be customized with CSS. A [http://fortawesome.github.io/Font-Awesome/cheatsheet/ cheatsheet] shows the Unicode point for each glyph.|http://fortawesome.github.io/Font-Awesome/|{{AUR|ttf-font-awesome}}}}<br />
* {{App|ttf-font-icons|Non-overlapping and consistently sized mix of Awesome and Ionicons. This also avoids minor overlapping between DejaVu Sans and Awesome.|http://kageurufu.net/icons.pdf|{{AUR|ttf-font-icons}}}}.<br />
<br />
To combine fonts, define a font fallback sequence in your configuration file, separating fonts with {{ic|,}} like so:<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
...<br />
font pango:DejaVu Sans Mono, Icons 8<br />
...<br />
}<br />
}}<br />
<br />
In accordance with [https://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string pango syntax], font size is specified only once, at the end of the comma-separated list of font families. Setting a size for each font would cause all but the last font to be ignored.<br />
<br />
Add icons to the format strings in {{ic|~/.config/i3status/config}} using the unicode numbers given in the cheatsheets linked above. The input method will vary between text editors. For instance, to insert the "heart" icon (unicode number f004):<br />
<br />
{{Merge|Internationalization|Should be described in one place; see also [[ArchWiki:Requests#Input methods]].}}<br />
<br />
* in various gui text editors (e.g. [[gedit]], Leafpad) and terminals (e.g. GNOME Terminal, xfce4-terminal): {{ic|ctrl+shift+u}}, {{ic|f004}}, {{ic|Enter}}<br />
* in [[Emacs]]: {{ic|ctrl+x}}, {{ic|8}}, {{ic|Enter}}, {{ic|f004}}, {{ic|Enter}}<br />
* in [[Vim]] (while in insert mode): {{ic|Ctrl+v}}, {{ic|uf004}}<br />
* in [[urxvt]]: while holding {{ic|Ctrl+Shift}}, type {{ic|f004}}<br />
<br />
=== Terminal emulator ===<br />
<br />
By default when pressing {{ic|$mod+Return}} it launches the {{ic|i3-sensible-terminal}} which is a script that invokes a terminal. See {{ic|man i3-sensible-terminal}} for the order terminals are invoked in.<br />
<br />
To instead launch a terminal of choice, modify this line in {{ic|~/.config/i3/config}}:<br />
<br />
bindsym $mod+Return exec i3-sensible-terminal<br />
<br />
Alternatively, [[Environment_variable#Per_user|locally define]] the {{ic|$TERMINAL}} variable:<br />
<br />
$ export TERMINAL=''yourterminal''<br />
<br />
== Tips and tricks ==<br />
<br />
=== Advanced window navigation ===<br />
<br />
See [http://www.slackword.net/?p=657 i3 window Navigation Tips].<br />
<br />
=== Jump to open window ===<br />
<br />
*{{App|quickswitch-i3|Python utility to quickly change to and locate windows in i3|https://github.com/proxypoke/quickswitch-for-i3|{{Aur|quickswitch-i3}}}}<br />
*{{App|i3-wm-scripts|search for and jump to windows with particular names matching regexp|https://github.com/yiuin/i3-wm-scripts||}}<br />
*{{App|winmenupy|Launches dmenu with a list of clients, sorted after workspaces. Selecting a client jumps to that window.|https://github.com/ziberna/i3-py/blob/master/examples/winmenu.py||}}<br />
*{{App|[[rofi]]|Search and jump to open and scratchpad window|https://davedavenport.github.io/rofi/|{{Pkg|rofi}}}}<br />
<br />
=== Jump to urgent window ===<br />
<br />
Add to {{ic|.i3/config}}: [https://faq.i3wm.org/question/853/how-to-jump-to-urgent-workspace/]<br />
<br />
bindsym $mod+x [urgent=latest] focus<br />
<br />
=== Save and restore the window layout ===<br />
<br />
From version 4.8, and onward ''i3'' can save and restore workspace layouts. To do this, the following packages are needed: {{Pkg|perl-anyevent-i3}} and {{Pkg|perl-json-xs}} from the [[official repositories]].<br />
<br />
{{note| This section only provides quick tutorial on how to save the current window layout of a single workspace and how to restore it for later use. Refer to the [http://i3wm.org/docs/layout-saving.html official documentation] for more details}}<br />
<br />
==== Save the current window layout of a single workspace ====<br />
<br />
To save the current window layout, follow these steps:<br />
<br />
# First, execute various commands to open windows in a preferred workspace and resize them if needed. Make sure to write down each executed command for each window.<br />
# Now, in a new workspace, open a terminal and run the following: {{bc|i3-save-tree --workspace N > ~/.i3/workspace_N.json}} where N is the number of the preferred workspace. This will save the current layout of workspace N to the file {{ic|~/.i3/workspace_N.json}}.<br />
# The newly created file needs to be edited, however this may be done with the following commands: {{bc|<nowiki>tail -n +2 ~/.i3/workspace_N.json | fgrep -v '// splitv' | sed 's|//||g' > ~/.i3/workspace_N.json</nowiki>}}<br />
<br />
==== Restore the window layout of the workspace ====<br />
<br />
There are two ways to restore the layout of the workspace: by writing a script, or by editing {{ic|~/.i3/config}} to automatically load the layout. In this section only the first case will be considered, refer to the [http://i3wm.org/docs/layout-saving.html#_restoring_the_layout official documentation] for the second case.<br />
<br />
To restore the saved layout in the previous section, write a file named {{ic|load_layout.sh}} with the following contents:<br />
<br />
* The starting lines:<br />
<br />
{{hc|head=~/load_layout.sh|output=<br />
#!/bin/bash<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
}}<br />
<br />
where M is the number of the workspace in which you would like to load the previously saved layout and N is the number of workspace saved in the previous section.<br />
* And the commands used in the previous section to get the preferred windows, but enclosed in parentheses and with an ampersand appended before the last parentheses.<br />
<br />
For example, if the saved layout contained three {{ic|uxterm}} windows:<br />
<br />
{{hc|head=~/load_layout.sh|output=<br />
#!/bin/bash<br />
<br />
# First we append the saved layout of worspace N to workspace M<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
<br />
# And finally we fill the containers with the programs they had<br />
(uxterm &)<br />
(uxterm &)<br />
(uxterm &)<br />
}}<br />
<br />
Then set the file as executable:<br />
<br />
chmod u+x ~/load_layout.sh<br />
<br />
And finally, the layout of worskpace N can be loaded onto to workspace M by running:<br />
<br />
~/load_layout.sh<br />
<br />
{{tip|Adding {{ic|bindsym $mod+g exec ~/load_layout.sh}} to {{ic|~/.i3/config}} and restarting i3 will bind Mod+g to run the above script.}}<br />
<br />
{{note|If the above script does not work properly, refer to the [http://i3wm.org/docs/layout-saving.html#_editing_layout_files official documentation]. The ''swallows'' sections of {{ic|~/.i3/workspace_N.json}} needs to be manually edited.}}<br />
<br />
=== Scratchpad containers ===<br />
<br />
By default, [http://i3wm.org/docs/userguide.html#_scratchpad scratchpads] only contain a single window. However, containers can also be made a scratchpad.<br />
<br />
Create a new container (for example, {{ic|Mod+Enter}}), split it ({{ic|Mod+v}}) and create another container. Focus the parent ({{ic|Mod+a}}), split in the opposite direction ({{ic|Mod+h}}), and create again. <br />
<br />
Focus the first container (with focus parent as needed), make the window floating ({{ic|Mod+Shift+Space}}), and move it to the scratchpad ({{ic|Mod+Shift+-}}). You can now split containers to preference.<br />
<br />
{{Note|Containers cannot be resized individually in floating windows. Resize the containers before making windows floating.}}<br />
{{Tip|When only using terminal applications, consider a multiplexer such as [[tmux]] instead.}}<br />
<br />
See also [https://faq.i3wm.org/question/138/multiple-scratchpad/i3] for multiple scratchpads.<br />
<br />
=== Screensaver and power management ===<br />
<br />
With [[Power management#xss-lock]] you can register a screenlocker for your i3 session.<br />
The {{ic|-time}} option locks the screen after a given time period.<br />
<br />
xautolock -time 10 -locker "i3lock -i 'background_image.png'" &<br />
<br />
A [[systemd]] service file can be used to lock the screen before the system is being sent to sleep or hibernation state. <br />
An example {{ic|suspend@.service}} file can be found here: [[Power_management#Suspend.2Fresume_service_files]].<br />
The following line invokes the {{ic|i3lock}} program.<br />
ExecStart=/usr/bin/i3lock -i 'background_image.png'<br />
<br />
See also [[DPMS]].<br />
<br />
=== Shutdown, reboot, lock screen ===<br />
<br />
Key combinations for shutdown, reboot and screenlock can be added to {{ic|~/.config/i3/config}}. The below example assumes you have {{Pkg|polkit}} installed to allow unprivileged users to run [[systemd#Power_management|power management]] commands.<br />
<br />
{{bc|<br />
set $Locker i3lock && sleep 1<br />
<br />
set $mode_system System (l) lock, (e) logout, (s) suspend, (h) hibernate, (r) reboot, (Shift+s) shutdown<br />
mode "$mode_system" {<br />
bindsym l exec --no-startup-id $Locker, mode "default"<br />
bindsym e exec --no-startup-id i3-msg exit, mode "default"<br />
bindsym s exec --no-startup-id $Locker && systemctl suspend, mode "default"<br />
bindsym h exec --no-startup-id $Locker && systemctl hibernate, mode "default"<br />
bindsym r exec --no-startup-id systemctl reboot, mode "default"<br />
bindsym Shift+s exec --no-startup-id systemctl poweroff -i, mode "default" <br />
<br />
# back to normal: Enter or Escape<br />
bindsym Return mode "default"<br />
bindsym Escape mode "default"<br />
}<br />
<br />
bindsym $mod+Pause mode "$mode_system"<br />
}}<br />
<br />
Once completed, you will be presented with a prompt whenever you press {{ic|$mod+pause}}. For more complex behaviour, use a separate script, and refer to it in the mode. [https://gist.github.com/anonymous/c8cd0a59bf4acb273068]<br />
<br />
{{Note|1=<br><br />
* {{ic|sleep 1}} adds a small delay to prevent possible race conditions with suspend [https://bugs.launchpad.net/ubuntu/+source/unity-2d/+bug/830348]<br />
* The {{ic|-i}} argument for {{ic|systemctl poweroff}} causes a shutdown even if other users are logged-in (this requires {{Pkg|polkit}}), or when ''logind'' (wrongly) assumes so. [https://bugs.freedesktop.org/show_bug.cgi?id=62676]<br />
}}<br />
<br />
For a list of alternative screen lockers, see [[List of applications/Security#Screen lockers]].<br />
<br />
===External displays manual management===<br />
<br />
Thanks to [[xrandr]] there are many ways to easily manage systems displays. The below example integrates it in the i3 config file, and behave as the Power Management section above.<br />
<br />
Here a laptop with both VGA and HDMI outputs will use a menu selection to switch them On/Off:<br />
<br />
## Manual management of external displays<br />
# Set the shortcuts and what they do<br />
set $mode_display Ext Screen (v) VGA ON, (h) HDMI ON, (x) VGA OFF, (y) HDMI OFF<br />
mode "$mode_display" {<br />
bindsym v exec --no-startup-id xrandr --output VGA1 --auto --right-of LVDS1, mode "default"<br />
bindsym h exec --no-startup-id xrandr --output HDMI1 --auto --right-of LVDS1, mode "default"<br />
bindsym x exec --no-startup-id xrandr --output VGA1 --auto --off, mode "default"<br />
bindsym y exec --no-startup-id xrandr --output HDMI1 --auto --off, mode "default"<br />
<br />
# back to normal: Enter or Escape<br />
bindsym Return mode "default"<br />
bindsym Escape mode "default"<br />
}<br />
# Declare here the shortcut to bring the display selection menu<br />
bindsym $mod+x mode "$mode_display"<br />
<br />
Any window that is still open in a switched Off display will automatically come back to the remaining active display.<br />
<br />
The simplest way to determine names of your devices is to plug the device you wish to use and run:<br />
<br />
$ xrandr --query<br />
<br />
which will output the available, recognized devices and their in-system names to set your config file appropriately. <br />
<br />
Refer to the [[xrandr]] page or man page for the complete list of available options, the [http://i3wm.org/docs/userguide.html i3 userguide] and/or the [https://www.reddit.com/r/i3wm i3 FAQ on reddit] for more info.<br />
<br />
=== Tabbed or stacked web-browsing ===<br />
<br />
Some web-browsers intentionally do not implement tabs, since managing tabs is considered to be the task of the window manager, not the task of the browser.<br />
<br />
To let i3 manage your tab-less web-browser, in this example for [[uzbl]], add the following line to your {{ic|~/.config/i3/config}}<br />
<br />
for_window [class="Uzbl-core"] focus child, layout stacking, focus<br />
<br />
This is for stacked web browsing, meaning that the windows will be shown vertically. The advantage over tabbed browsing is that the window-titles are fully visible, even if a lot of browser windows are open.<br />
<br />
If you prefer tabbed browsing, with windows in horizontal direction ('tabs'), use<br />
<br />
for_window [class="Uzbl-core"] focus child, layout tabbed, focus<br />
<br />
=== Workspace variables ===<br />
<br />
As workspaces are defined multiple times in i3, assigning workspace variables can be helpful. For example [https://github.com/dkeg/bloat2.0/blob/master/i3config#L55]:<br />
<br />
set $WS1 term<br />
set $WS2 web<br />
set $WS3 misc<br />
set $WS4 media<br />
set $WS5 code<br />
<br />
Then replace workspace names with their matching variables:<br />
<br />
bindsym $mod+1 workspace $WS1<br />
...<br />
bindsym $mod+Shift+1 move container to workspace $WS1<br />
<br />
See [http://i3wm.org/docs/userguide.html#_changing_named_workspaces_moving_to_workspaces Changing named workspaces] for more information.<br />
<br />
=== Correct handling of floating dialogs ===<br />
<br />
While dialogs should open in floating mode by default [http://i3wm.org/docs/userguide.html#_floating], many still open in tiling mode. To change this behaviour, check the dialog's {{ic|WM_WINDOW_ROLE}} with {{pkg|xorg-xprop}} and add the correct rules to {{ic|~/.i3/config}} (using [http://www.pcre.org/ pcre] syntax):<br />
<br />
for_window [window_role="pop-up"] floating enable<br />
for_window [window_role="task_dialog"] floating enable<br />
<br />
You can also use title rules and regular expressions:<br />
<br />
for_window [title="Preferences$"] floating enable<br />
<br />
or {{ic|WM_CLASS}}:<br />
<br />
for_window [class="(?i)mplayer"] floating enable<br />
<br />
=== Network Download/Upload speed on statusbar ===<br />
<br />
You might adapt this upstream [http://code.stapelberg.de/git/i3status/tree/contrib/measure-net-speed.bash script]. For that,<br />
<br />
* rename both network cards according to your system (use {{ic|ip addr}})<br />
* find them on {{ic|/sys/devices}} then replace them appropriately:<br />
$ find /sys/devices -name ''network_interface''<br />
<br />
{{Tip|Use {{ic|/sys/class/net/''interface''/statistics/}} to not depend on PCI location.}}<br />
<br />
Now, just save the script in a suitable place (for example {{ic|~/.config/i3}}) and point your status program to it.<br />
<br />
== Patches ==<br />
<br />
Packages with patches not merged upstream are available in the [[AUR]]:<br />
<br />
* {{App|i3bar-icons-git|Display XBM icons in i3bar|https://github.com/ashinkarov/i3-extras|{{AUR|i3bar-icons-git}}{{Broken package link|{{aur-mirror|i3bar-icons-git}}}}}}<br />
* {{App|i3-smart-border|Smart borders|https://github.com/ashinkarov/i3-extras|{{AUR|i3-smart-border}}{{Broken package link|{{aur-mirror|i3-smart-border}}}}}}<br />
* {{App|i3-wm-iconpatch|Titlebar icon support|https://github.com/ashinkarov/i3-extras|{{AUR|i3-wm-iconpatch}}}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== General ===<br />
<br />
In many cases, bugs are fixed in the development versions {{AUR|i3-git}} and {{AUR|i3status-git}}, and upstream will ask to reproduce any errors with this version. [http://i3wm.org/docs/debugging.html] See also [[Debug - Getting Traces#General]].<br />
<br />
=== Buttons in the i3 message bar do not work ===<br />
<br />
Buttons such as "Edit config" in {{ic|i3-nagbar}} call {{ic|i3-sensible-terminal}}, so make sure your [[#Terminal_emulator|Terminal emulator]] is recognized by i3.<br />
<br />
=== Faulty line wraps in tiled terminals ===<br />
<br />
i3 v4.3 and higher ignore size increment hints for tiled windows [https://www.mail-archive.com/i3-discuss@i3.zekjur.net/msg00709.html]. This may cause terminals to wrap lines prematurely, amongst other issues. As a workaround, make the offending window floating, before tiling it again.<br />
<br />
=== Mouse cursor remains in waiting mode ===<br />
<br />
When starting a script or application which does not support startup notifications, the mouse cursor will remain in busy/watch/clock mode for 60 seconds.<br />
<br />
To solve this for a particlar application, use the {{ic|--no-startup-id}} parameter, for example:<br />
exec --no-startup-id ~/script<br />
bindsym $mod+d exec --no-startup-id dmenu_run<br />
<br />
To disable this animation globally, see [[Cursor themes#Create links to missing cursors]].<br />
<br />
=== Unresponsive key bindings ===<br />
<br />
Some tools such as [[Taking_a_screenshot#scrot|scrot]] may not work when used with a regular key binding (executed after key press). In those cases, execute commands after key release with the {{ic|--release}} argument [http://i3wm.org/docs/userguide.html#keybindings]:<br />
<br />
bindsym --release Print exec --no-startup-id scrot<br />
bindsym --release Shift+Print exec --no-startup-id scrot -s<br />
<br />
=== Tearing ===<br />
<br />
i3 does [https://github.com/i3/i3/issues/661 not properly implement double buffering] hence tearing or flickering may occur. To prevent this, install and configure [[compton]]. [https://faq.i3wm.org/question/3279/do-i-need-a-composite-manager-compton.1#post-id-3282]<br />
<br />
=== Tray icons not visible ===<br />
<br />
The default {{ic|tray_output primary}} directive may require setting a primary output with ''xrandr'', specifying the output explicitly or simply removing this directive. [https://github.com/i3/i3/issues/1144] See [[Xrandr]] for details. The default configuration created by i3-config-wizard will no longer add this directive to the configuration with i3 4.12.<br />
<br />
== See also ==<br />
<br />
* [http://i3wm.org Official website]<br />
* [http://www.funtoo.org/I3_Tiling_Window_Manager funtoo Wiki]<br />
* [http://code.stapelberg.de/git/i3 i3 Source code]<br />
* [https://github.com/ashinkarov/i3-extras i3-extras] - Collection of scripts and patches<br />
* [https://github.com/acrisci/i3ipc-glib i3ipc-glib] - A library for i3 extensions<br />
* [https://github.com/veelenga/i3ipc-ruby i3ipc-ruby] - An improved library for i3 extensions in Ruby<br />
* [http://www.j4tools.org/ j4tools] - non-official tools designed to work with i3<br />
<br />
'''Arch Linux Forums'''<br />
* [https://bbs.archlinux.org/viewtopic.php?id=99064 The i3 thread] - A general discussion about i3<br />
* [https://bbs.archlinux.org/viewtopic.php?id=103369 i3 desktop screenshots and config sharing]<br />
<br />
'''Screencasts'''<br />
* [http://www.youtube.com/watch?v=Wx0eNaGzAZU i3 window manager v4.1 screencast]<br />
* [https://www.youtube.com/watch?v=j1I63wGcvU4&index=1&list=PL5ze0DjYv5DbCv9vNEzFmP6sU7ZmkGzcf i3 window manager v4.1X screencasts]</div>PhilippDhttps://wiki.archlinux.org/index.php?title=Talk:Power_management&diff=404327Talk:Power management2015-10-12T18:30:09Z<p>PhilippD: /* Resume file does not work after resuming from hibernation */ new section</p>
<hr />
<div>== Suspend/resume service files ==<br />
<br />
I have the slight suspicion that the service files posted in the section [[Power Management#Suspend/resume service files]] might not work. Has anybody tried them or is actually using them? <br><br />
-- [[User:Jakobh|jakobh]] [[User talk:Jakobh|✉]] 03:12, 10 May 2013 (UTC)<br />
<br />
: (Mod: the section was moved from [[systemd]] into [[Power Management]], so I moved this post too, fixed link along the way. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:24, 21 August 2013 (UTC))<br />
<br />
== Sleep hooks ==<br />
<br />
Where is the exact difference between '''Suspend/resume service files''' approach and '''Hooks in /usr/lib/systemd/system-sleep'''?<br />
<br />
Is the latter obsolete?<br />
<br />
-- [[User:Orschiro|Orschiro]] 07:33, 17 January 2014<br />
<br />
:From {{ic|systemd-sleep(8)}}:<br />
::"Note that scripts or binaries dropped in {{ic|/usr/lib/systemd/system-sleep/}} are intended for local use only and should be considered hacks."<br />
:It's always preferred to use service files, they are much more flexible in handling the dependencies etc.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 23:52, 31 January 2014 (UTC)<br />
<br />
== Delayed hibernation service ==<br />
<br />
I have found that the service file given in this section does not work. My laptop hibernates immediately after resuming from suspend. I have also found that the older version of this service found in the forum post does indeed work perfectly. Does anyone know why this is?<br />
[[User:Aouellette|Aouellette]] ([[User talk:Aouellette|talk]]) 16:16, 30 May 2015 (UTC)<br />
<br />
== Resume file does not work after resuming from hibernation ==<br />
<br />
The systemd unit {{ic|User resume actions}} presented on this page only worked for me after resuming from sleep, not from hibernate. <br />
After adding {{ic|hibernate.target}} to the {{ic|After}} and {{ic|WantedBy}} lines it works both ways.<br />
However this is the first time I've done anything with such service files so I ain't sure if this is the optimal way.<br />
Can anyone confirm?</div>PhilippDhttps://wiki.archlinux.org/index.php?title=I3&diff=403446I32015-10-05T17:46:14Z<p>PhilippD: /* Screensaver and power management */ added a hint at the -lockaftersleep option for xautolock</p>
<hr />
<div>{{DISPLAYTITLE:i3}}<br />
[[Category:Tiling WMs]]<br />
[[Category:Dynamic WMs]]<br />
[[ja:i3]]<br />
[[ko:I3]]<br />
[[ru:I3]]<br />
[[zh-CN:I3]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Window manager}}<br />
{{Related|Comparison of tiling window managers}}<br />
{{Related|Clipboard}}<br />
{{Related|Autostarting#Graphical}}<br />
{{Related articles end}}<br />
[http://i3wm.org/ i3] is a dynamic [[Wikipedia:Tiling window manager|tiling window manager]] inspired by [[wmii]] that is primarily targeted at developers and advanced users.<br />
<br />
The stated goals for i3 include clear documentation, proper multi-monitor support, a tree structure for windows, and different modes like in [[vim]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Grp|i3}} [[Pacman#Installing package groups|package group]]. It includes the window manager {{Pkg|i3-wm}}, {{Pkg|i3status}} which writes a status line to i3bar through [[Wikipedia:Standard streams#Standard output (stdout)|stdout]], and {{Pkg|i3lock}}, a screen locker.<br />
<br />
Additional packages are available in the [[Arch User Repository]]. See the section [[#Patches]] for examples.<br />
<br />
=== Display manager ===<br />
<br />
{{Pkg|i3-wm}} includes {{ic|i3.desktop}} as [[Xsession]] which starts the window manager. {{ic|i3-with-shmlog.desktop}} enables logs (useful for debugging). {{AUR|i3-gnome}} integrates {{ic|i3}} into [[GNOME]].<br />
<br />
=== xinitrc ===<br />
<br />
Edit [[Xinitrc]], and add:<br />
<br />
exec i3<br />
<br />
To log the output from i3, add this line instead:<br />
<br />
exec i3 -V >> ~/i3log-$(date +'%F-%k-%M-%S') 2>&1<br />
<br />
Nvidia binary drivers before version '''302.17''' need the {{ic|--force-xinerama}} flag. A detailed explanation can be found at [http://i3wm.org/docs/multi-monitor.html i3wm.org].<br />
<br />
exec i3 --force-xinerama<br />
<br />
If you have trouble mapping keys (e.g. {{ic|;}} as semicolon), use {{Pkg|xorg-xev}} or see [[Extra keyboard keys]].<br />
<br />
$ xev | grep -A2 --line-buffered '^KeyRelease' | sed -n '/keycode /s/^.*keycode \([0-9]*\).* (.*, \(.*\)).*$/\1 \2/p'<br />
<br />
== Usage ==<br />
<br />
See the [http://i3wm.org/docs official documentation] for more information, namely the [http://i3wm.org/docs/userguide.html i3 User’s Guide].<br />
<br />
=== Application launcher ===<br />
<br />
i3 uses [[dmenu]] as an application launcher, which is bound by default to {{ic|$mod+d}}. As an alternative, one can use {{AUR|dmenu2}} from the AUR which has many more features including transparency and support for xft fonts.<br />
<br />
{{Pkg|i3-wm}} contains ''i3-dmenu-desktop'', a [[Wikipedia:Perl|Perl]] wrapper for ''dmenu'' which uses [[desktop entries]] to create a list of all installed applications. Alternatively, the package {{AUR|j4-dmenu-desktop-git}} can be used; it is a near-drop-in replacement for ''i3-dmenu-desktop'', but much faster[[https://github.com/enkore/j4-dmenu-desktop/blob/master/README.md 1]].<br />
<br />
=== Keybindings ===<br />
<br />
In i3, commands are invoked with a modifier key, referred to as {{ic|$mod}}. This is {{ic|Alt}} (Mod1) by default, with {{ic|Super}} (Mod4) being a popular alternative.<br />
<br />
See the [http://i3wm.org/docs/refcard.html i3 reference card] and [http://i3wm.org/docs/userguide.html#_using_i3 Using i3] for the defaults. See [http://i3wm.org/docs/userguide.html#keybindings Keyboard bindings] to add new shortcuts.<br />
<br />
=== Containers ===<br />
<br />
{{Expansion|The User's guide explains basic use of containers, yet is not sufficiently clear to allow more advanced use cases. It also does not mention ''focus child'' as it does ''focus parent''. See also: [https://faq.i3wm.org/question/222/how-to-get-rid-of-another-container/], [https://github.com/i3/i3/issues/1326]}}<br />
<br />
i3 manages windows in a tree structure, with containers as building blocks. This structure branches with horizontal or vertical splits. Containers are tiled by default, but can be set to tabbed or stacked layouts, as well as made floating (such as for dialog windows). Floating windows are always on top.<br />
<br />
See [http://i3wm.org/docs/userguide.html#_tree i3 Tree] and [http://www.youtube.com/watch?v=AWA8Pl57UBY Containers and the tree data structure] for details.<br />
<br />
== Configuration ==<br />
<br />
See [http://i3wm.org/docs/userguide.html#configuring Configuring i3] for details. The rest of this article assumes the ''i3'' configuration file to be in the folder {{ic|~/.config}}.<br />
<br />
=== Colorschemes ===<br />
<br />
The configuration file allows for customization of window decoration colors, but the syntax makes it impractical to create or share themes. There are several projects which make this easier and include a variety of user-contributed themes.<br />
<br />
* {{App|i3-style|Modifies your config in place from a theme stored in a JSON object, designed for frequently tweaking or changing a colorscheme|https://github.com/acrisci/i3-style|{{Aur|nodejs-i3-style}}{{Broken package link|{{aur-mirror|nodejs-i3-style}}}}}}<br />
* {{App|j4-make-config|Merge your config with a collection of themes or personal config parts, for example host-specific configuration, allowing quick changing of the theme and flexible, dynamic customization of the configuration|https://github.com/okraits/j4-make-config|{{Aur|j4-make-config-git}}}}<br />
<br />
=== i3bar ===<br />
<br />
In addition to showing workspace information, i3bar can act as an input for i3status or an alternative, such as those mentioned in the next section. For example:<br />
<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
output LVDS1<br />
status_command i3status<br />
position top<br />
mode hide<br />
workspace_buttons yes<br />
tray_output none<br />
<br />
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1<br />
<br />
colors {<br />
background #000000<br />
statusline #ffffff<br />
<br />
focused_workspace #ffffff #285577<br />
active_workspace #ffffff #333333<br />
inactive_workspace #888888 #222222<br />
urgent_workspace #ffffff #900000<br />
}<br />
}<br />
}}<br />
<br />
See the [http://i3wm.org/docs/userguide.html#_configuring_i3bar Configuring i3bar] for details.<br />
<br />
==== i3bar alternatives ====<br />
<br />
Some users may prefer panels such as those provided by conventional [[Desktop environment|Desktop Environments]]. This can be achieved within i3 by launching the panel application of choice during startup.<br />
<br />
For the [[Xfce#Panel|XFCE panel]], add the following line anywhere in {{ic|~/.config/i3/config}}:<br />
<br />
exec --no-startup-id xfce4-panel --disable-wm-check<br />
<br />
Alternatively if using {{ic|startx}}, this can be done in your [[xinitrc]]:<br />
<br />
{{hc|~/.xinitrc|<br />
xfce4-panel --disable-wm-check &<br />
}}<br />
<br />
{{Accuracy|i3 is [[Wikipedia:Extended_Window_Manager_Hints|NETWM]] compliant, so workspace management from external panels should usally work. See also [http://i3wm.org/docs/wsbar.html]}}<br />
<br />
{{Note|Panel features that are specific to the [[Desktop environment]] (e.g., widgets for managing workspaces/sessions) will most likely not work, though i3's functionality should remain unaffected.}}<br />
<br />
i3bar can be disabled by commenting out the {{ic|<nowiki>bar{ }</nowiki>}} section of {{ic|~/.config/i3/config}} or using: <br />
<br />
{{hc|~/.config/i3/config|<br />
# bar toggle, hide or show <br />
bindsym $mod+m bar mode toggle<br />
}}<br />
This way you can show or hide bar as you want.<br />
<br />
=== i3status ===<br />
<br />
Copy over the default configuration files to the home directory:<br />
<br />
$ cp /etc/i3status.conf ~/.config/i3status/config<br />
<br />
Not all plugins are defined in the default configuration and some configuration values may be invalid for your system, so the need to be updated accordingly. See {{ic|man i3status}} for details.<br />
<br />
==== i3status replacements ====<br />
<br />
* {{App|[[conky]]| Highly extensible system monitor. For usage with i3bar see [http://i3wm.org/docs/user-contributed/conky-i3bar.html this tutorial] |https://github.com/brndnmtthws/conky|{{Pkg|conky}}}}<br />
* {{App|i3blocks|Extensible via shell scripts. It can handle click events, interrupts, and defining of refresh intervals on a per-block basis.|https://github.com/vivien/i3blocks|{{AUR|i3blocks}}}}<br />
* {{App|i3phtatus|An easily extensible i3status replacement meant for i3bar, written in PHP.|https://github.com/mwgg/i3phtatus}}<br />
* {{App|i3pystatus|Extensible Python 3 status bar with many plugins and configuration options by default.|https://github.com/enkore/i3pystatus i3pystatus|{{AUR|i3pystatus-git}}}}<br />
* {{App|i3situation|Another Python 3 status bar generator.|https://github.com/HarveyHunt/i3situation|{{Aur|i3situation-git}}}}<br />
* {{App|j4status|Provides a statusline, configurable via plugins, and written in C.|http://j4status.j4tools.org/|{{Aur|j4status-git}}}}<br />
<br />
==== i3status wrappers ====<br />
<br />
* {{App|[[h2status]]|Bash wrapper for i3status that allows custom json entries as input, and can handle click events as well as asynchronous updates of the status bar.|https://wiki.archlinux.org/index.php/H2status|{{Aur|h2status}}{{Broken package link|{{aur-mirror|h2status}}}}}}<br />
* {{App|i3cat|A [[go]] based wrapper which can concatenate inputs from multiple external sources. It can handle click events and forwarding user specified signals to its subprocesses.|http://vincent-petithory.github.io/i3cat/|{{AUR|i3cat-git}}}}<br />
* {{App|py3status|An extensible i3status wrapper written in Python.|https://github.com/ultrabug/py3status|{{Aur|py3status}}}}<br />
<br />
==== Iconic fonts in the status bar ====<br />
<br />
''i3bar'' can be [[#Patches|patched]] for XBM icon support, but you can use iconic font sets instead.<br />
<br />
* {{App|ttf-font-awesome|Scalable vector icons that can be customized with CSS. A [http://fortawesome.github.io/Font-Awesome/cheatsheet/ cheatsheet] shows the Unicode point for each glyph.|http://fortawesome.github.io/Font-Awesome/|{{AUR|ttf-font-awesome}}}}<br />
* {{App|ttf-font-icons|Non-overlapping and consistently sized mix of Awesome and Ionicons. This also avoids minor overlapping between DejaVu Sans and Awesome.|https://www.dropbox.com/s/9iysh2i0gadi4ic/icons.pdf|{{AUR|ttf-font-icons}}}}.<br />
<br />
To combine fonts, define a font fallback sequence in your configuration file, separating fonts with {{ic|,}} like so:<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
...<br />
font pango:DejaVu Sans Mono, Icons 8<br />
...<br />
}<br />
}}<br />
<br />
In accordance with [https://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string pango syntax], font size is specified only once, at the end of the comma-separated list of font families. Setting a size for each font would cause all but the last font to be ignored.<br />
<br />
Add icons to the format strings in {{ic|~/.config/i3status/config}} using the unicode numbers given in the cheatsheets linked above. The input method will vary between text editors. For instance, to insert the "heart" icon (unicode number f004):<br />
<br />
{{Merge|Internationalization|Should be described in one place; see also [[ArchWiki:Requests#Input methods]].}}<br />
<br />
* in various gui text editors (e.g. [[gedit]], Leafpad) and terminals (e.g. GNOME Terminal, xfce4-terminal): {{ic|ctrl+shift+u}}, {{ic|f004}}, {{ic|Enter}}<br />
* in [[Emacs]]: {{ic|ctrl+x}}, {{ic|8}}, {{ic|Enter}}, {{ic|f004}}, {{ic|Enter}}<br />
* in [[Vim]] (while in insert mode): {{ic|Ctrl+v}}, {{ic|uf004}}<br />
* in [[urxvt]]: while holding {{ic|Ctrl+Shift}}, type {{ic|f004}}<br />
<br />
=== Terminal emulator ===<br />
<br />
By default when pressing {{ic|$mod+Return}} it launches the {{ic|i3-sensible-terminal}} which is a script that invokes a terminal. See {{ic|man i3-sensible-terminal}} for the order terminals are invoked in.<br />
<br />
To instead launch a terminal of choice, modify this line in {{ic|~/.config/i3/config}}:<br />
<br />
bindsym $mod+Return exec i3-sensible-terminal<br />
<br />
Alternatively, [[Environment_variable#Defining_variables_locally|locally define]] the {{ic|$TERMINAL}} variable:<br />
<br />
$ export TERMINAL=''yourterminal''<br />
<br />
== Tips and tricks ==<br />
<br />
=== Advanced window navigation ===<br />
<br />
See [http://www.slackword.net/?p=657 i3 window Navigation Tips].<br />
<br />
=== Jump to open window ===<br />
<br />
*{{App|quickswitch-i3|Python utility to quickly change to and locate windows in i3|https://github.com/proxypoke/quickswitch-for-i3|{{Aur|quickswitch-i3}}}}<br />
*{{App|i3-wm-scripts|search for and jump to windows with particular names matching regexp|https://github.com/yiuin/i3-wm-scripts||}}<br />
*{{App|winmenupy|Launches dmenu with a list of clients, sorted after workspaces. Selecting a client jumps to that window.|https://github.com/ziberna/i3-py/blob/master/examples/winmenu.py||}}<br />
*{{App|rofi|Search and jump to open and scratchpad window|https://davedavenport.github.io/rofi/|{{Pkg|rofi}}}}<br />
<br />
=== Jump to urgent window ===<br />
<br />
Add to {{ic|.i3/config}}: [https://faq.i3wm.org/question/853/how-to-jump-to-urgent-workspace/]<br />
<br />
bindsym $mod+x [urgent=latest] focus<br />
<br />
=== Save and restore the window layout ===<br />
<br />
From version 4.8, and onward ''i3'' can save and restore workspace layouts. To do this, the following packages are needed: {{Pkg|perl-anyevent-i3}} and {{Pkg|perl-json-xs}} from the [[official repositories]].<br />
<br />
{{note| This section only provides quick tutorial on how to save the current window layout of a single workspace and how to restore it for later use. Refer to the [http://i3wm.org/docs/layout-saving.html official documentation] for more details}}<br />
<br />
==== Save the current window layout of a single workspace ====<br />
<br />
To save the current window layout, follow these steps:<br />
<br />
# First, execute various commands to open windows in a preferred workspace and resize them if needed. Make sure to write down each executed command for each window.<br />
# Now, in a new workspace, open a terminal and run the following: {{bc|i3-save-tree --workspace N > ~/.i3/workspace_N.json}} where N is the number of the preferred workspace. This will save the current layout of workspace N to the file {{ic|~/.i3/workspace_N.json}}.<br />
# The newly created file needs to be edited, however this may be done with the following commands: {{bc|<nowiki>tail -n +2 ~/.i3/workspace_N.json | fgrep -v '// splitv' | sed 's|//||g' > ~/.i3/workspace_N.json</nowiki>}}<br />
<br />
==== Restore the window layout of the workspace ====<br />
<br />
There are two ways to restore the layout of the workspace: by writing a script, or by editing {{ic|~/.i3/config}} to automatically load the layout. In this section only the first case will be considered, refer to the [http://i3wm.org/docs/layout-saving.html#_restoring_the_layout official documentation] for the second case.<br />
<br />
To restore the saved layout in the previous section, write a file named {{ic|load_layout.sh}} with the following contents:<br />
<br />
* The starting lines:<br />
<br />
{{hc|head=~/load_layout.sh|output=<br />
#!/bin/bash<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
}}<br />
<br />
where M is the number of the workspace in which you would like to load the previously saved layout and N is the number of workspace saved in the previous section.<br />
* And the commands used in the previous section to get the preferred windows, but enclosed in parentheses and with an ampersand appended before the last parentheses.<br />
<br />
For example, if the saved layout contained three {{ic|uxterm}} windows:<br />
<br />
{{hc|head=~/load_layout.sh|output=<br />
#!/bin/bash<br />
<br />
# First we append the saved layout of worspace N to workspace M<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
<br />
# And finally we fill the containers with the programs they had<br />
(uxterm &)<br />
(uxterm &)<br />
(uxterm &)<br />
}}<br />
<br />
Then set the file as executable:<br />
<br />
chmod u+x ~/load_layout.sh<br />
<br />
And finally, the layout of worskpace N can be loaded onto to workspace M by running:<br />
<br />
~/load_layout.sh<br />
<br />
{{tip|Adding {{ic|bindsym $mod+g exec ~/load_layout.sh}} to {{ic|~/.i3/config}} and restarting i3 will bind Mod+g to run the above script.}}<br />
<br />
{{note|If the above script does not work properly, refer to the [http://i3wm.org/docs/layout-saving.html#_editing_layout_files official documentation]. The ''swallows'' sections of {{ic|~/.i3/workspace_N.json}} needs to be manually edited.}}<br />
<br />
=== Scratchpad containers ===<br />
<br />
By default, [http://i3wm.org/docs/userguide.html#_scratchpad scratchpads] only contain a single window. However, containers can also be made a scratchpad.<br />
<br />
Create a new container (for example, {{ic|Mod+Enter}}), split it ({{ic|Mod+v}}) and create another container. Focus the parent ({{ic|Mod+a}}), split in the opposite direction ({{ic|Mod+h}}), and create again. <br />
<br />
Focus the first container (with focus parent as needed), make the window floating ({{ic|Mod+Shift+Space}}), and move it to the scratchpad ({{ic|Mod+Shift+-}}). You can now split containers to preference.<br />
<br />
{{Note|Containers cannot be resized individually in floating windows. Resize the containers before making windows floating.}}<br />
{{Tip|When only using terminal applications, consider a multiplexer such as [[tmux]] instead.}}<br />
<br />
See also [https://faq.i3wm.org/question/138/multiple-scratchpad/i3] for multiple scratchpads.<br />
<br />
=== Screensaver and power management ===<br />
<br />
You can use [[DPMS]] to blank your screen or to suspend/poweroff your monitor. Adding the following line to your {{ic|~/.config/i3/config}} will suspend your monitor after 10 minutes.<br />
<br />
exec --no-startup-id xset dpms 600<br />
<br />
With {{AUR|xss-lock-git}} you can register a screenlocker for your i3 session. xss-lock subscribes to the systemd-events {{ic|suspend}}, {{ic|hibernate}}, {{ic|lock-session}}, and {{ic|unlock-session}} with appropriate actions (run locker and wait for user to unlock or kill locker). It also reacts to the [[Display Power Management Signaling#xset screen-saver control|X screensaver]] and runs or kills the locker in response to the x-server signals. Start xss-lock in your [[autostart]] as follows:<br />
<br />
xss-lock -- i3lock -n -i ''background_image.png'' &<br />
<br />
Alternatively, you can use {{Pkg|xautolock}} to lock the screen after awakening from sleep or hibernation with the {{ic|-lockaftersleep}} option. The {{ic|-time}} option locks the screen after a given time period.<br />
<br />
xautolock -time 10 -locker "i3lock -i 'background_image.png'" -lockaftersleep &<br />
<br />
See also [[#Shutdown, reboot, lock screen]] and [[Pm-utils#Creating your own hooks]].<br />
<br />
=== Shutdown, reboot, lock screen ===<br />
<br />
As there are no Shutdown, Reboot, or Lock Screen buttons, we can add some hotkey combinations to help us out. The below assumes you have {{Pkg|polkit}} installed to allow unprivileged users to run [[systemd#Power_management|power management]] commands.<br />
<br />
Add the following lines to your {{ic|~/.config/i3/config}} Once completed you will be presented with a prompt whenever you press {{ic|$mod+pause}}.<br />
<br />
{{bc|<br />
set $Locker i3lock && sleep 1<br />
<br />
set $mode_system System (l) lock, (e) logout, (s) suspend, (h) hibernate, (r) reboot, (Shift+s) shutdown<br />
mode "$mode_system" {<br />
bindsym l exec --no-startup-id $Locker, mode "default"<br />
bindsym e exec --no-startup-id i3-msg exit, mode "default"<br />
bindsym s exec --no-startup-id $Locker && systemctl suspend, mode "default"<br />
bindsym h exec --no-startup-id $Locker && systemctl hibernate, mode "default"<br />
bindsym r exec --no-startup-id systemctl reboot, mode "default"<br />
bindsym Shift+s exec --no-startup-id systemctl poweroff -i, mode "default" <br />
<br />
# back to normal: Enter or Escape<br />
bindsym Return mode "default"<br />
bindsym Escape mode "default"<br />
}<br />
<br />
bindsym $mod+Pause mode "$mode_system"<br />
}}<br />
<br />
{{Note|1=<br><br />
* {{ic|sleep 1}} adds a small delay to prevent possible race conditions with suspend [https://bugs.launchpad.net/ubuntu/+source/unity-2d/+bug/830348]<br />
* The {{ic|-i}} argument for {{ic|systemctl poweroff}} causes a shutdown even if other users are logged-in (this requires {{Pkg|polkit}}), or when ''logind'' (wrongly) assumes so. [https://bugs.freedesktop.org/show_bug.cgi?id=62676]<br />
* If you use {{AUR|xss-lock-git}}, call {{ic|xset s activate}} to start the locker. With {{Pkg|xautolock}} the command is {{ic|xautolock -locknow}}<br />
* You can use a separate script for more complex behaviour, and refer to it in the mode. See [https://gist.github.com/anonymous/c8cd0a59bf4acb273068] for an example.<br />
}}<br />
<br />
For a list of alternative screen lockers, see [[List of applications/Security#Screen lockers]].<br />
<br />
=== Tabbed or stacked web-browsing ===<br />
<br />
Some web-browsers intentionally do not implement tabs, since managing tabs is considered to be the task of the window manager, not the task of the browser.<br />
<br />
To let i3 manage your tab-less web-browser, in this example for [[uzbl]], add the following line to your {{ic|~/.config/i3/config}}<br />
<br />
for_window [class="Uzbl-core"] focus child, layout stacking, focus<br />
<br />
This is for stacked web browsing, meaning that the windows will be shown vertically. The advantage over tabbed browsing is that the window-titles are fully visible, even if a lot of browser windows are open.<br />
<br />
If you prefer tabbed browsing, with windows in horizontal direction ('tabs'), use<br />
<br />
for_window [class="Uzbl-core"] focus child, layout tabbed, focus<br />
<br />
=== Workspace variables ===<br />
<br />
As workspaces are defined multiple times in i3, assigning workspace variables can be helpful. For example [https://github.com/dkeg/bloat2.0/blob/master/i3config#L55]:<br />
<br />
set $WS1 term<br />
set $WS2 web<br />
set $WS3 misc<br />
set $WS4 media<br />
set $WS5 code<br />
<br />
Then replace workspace names with their matching variables:<br />
<br />
bindsym $mod+1 workspace $WS1<br />
...<br />
bindsym $mod+Shift+1 move container to workspace $WS1<br />
<br />
See [http://i3wm.org/docs/userguide.html#_changing_named_workspaces_moving_to_workspaces Changing named workspaces] for more information.<br />
<br />
=== Correct handling of floating dialogs ===<br />
<br />
While dialogs should open in floating mode by default [http://i3wm.org/docs/userguide.html#_floating], many still open in tiling mode. To change this behaviour, check the dialog's {{ic|WM_WINDOW_ROLE}} with {{pkg|xorg-xprop}} and add the correct rules to {{ic|~/.i3/config}} (using [http://www.pcre.org/ pcre] syntax):<br />
<br />
for_window [window_role="pop-up"] floating enable<br />
for_window [window_role="task_dialog"] floating enable<br />
<br />
You can also use title rules and regular expressions:<br />
<br />
for_window [title="Preferences$"] floating enable<br />
<br />
or {{ic|WM_CLASS}}:<br />
<br />
for_window [class="(?i)mplayer"] floating enable<br />
<br />
=== Network Download/Upload speed on statusbar ===<br />
<br />
You might adapt this upstream [http://code.stapelberg.de/git/i3status/tree/contrib/measure-net-speed.bash script]. For that,<br />
<br />
* rename both network cards according to your system (use {{ic|ip addr}})<br />
* find them on {{ic|/sys/devices}} then replace them appropriately:<br />
$ find /sys/devices -name ''network_interface''<br />
<br />
{{Tip|Use {{ic|/sys/class/net/''interface''/statistics/}} to not depend on PCI location.}}<br />
<br />
Now, just save the script in a suitable place (for example {{ic|~/.config/i3}}) and point your status program to it.<br />
<br />
== Patches ==<br />
<br />
Packages with patches not merged upstream are available in the [[AUR]]:<br />
<br />
* {{App|i3bar-icons-git|Display XBM icons in i3bar|https://github.com/ashinkarov/i3-extras|{{AUR|i3bar-icons-git}}{{Broken package link|{{aur-mirror|i3bar-icons-git}}}}}}<br />
* {{App|i3-smart-border|Smart borders|https://github.com/ashinkarov/i3-extras|{{AUR|i3-smart-border}}{{Broken package link|{{aur-mirror|i3-smart-border}}}}}}<br />
* {{App|i3-wm-iconpatch|Titlebar icon support|https://github.com/ashinkarov/i3-extras|{{AUR|i3-wm-iconpatch}}}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== General ===<br />
<br />
{{Expansion|Official debugging instructions may not work as expected, so expand on this topic}}<br />
<br />
In many cases, bugs are fixed in the development version {{AUR|i3-git}} (from the [[AUR]]) and upstream will ask to reproduce any errors with this version. [http://i3wm.org/docs/debugging.html] See also [[Debug - Getting Traces#General]].<br />
<br />
=== Buttons in the i3 message bar do not work ===<br />
<br />
Buttons such as "Edit config" in {{ic|i3-msg}} call {{ic|i3-sensible-terminal}}, so make sure your [[#Terminal_emulator|Terminal emulator]] is recognized by i3.<br />
<br />
=== Faulty line wraps in tiled terminals ===<br />
<br />
i3 v4.3 and higher ignore size increment hints for tiled windows [https://www.mail-archive.com/i3-discuss@i3.zekjur.net/msg00709.html]. This may cause terminals to wrap lines prematurely, amongst other issues. As a workaround, make the offending window floating, before tiling it again.<br />
<br />
=== Mouse cursor remains in waiting mode ===<br />
<br />
When starting a script or application which does not support startup notifications, the mouse cursor will remain in busy/watch/clock mode for 60 seconds.<br />
<br />
To solve this for a particlar application, use the {{ic|--no-startup-id}} parameter, for example:<br />
exec --no-startup-id ~/script<br />
bindsym $mod+d exec --no-startup-id dmenu_run<br />
<br />
To disable this animation globally, see [[Cursor themes#Create links to missing cursors]].<br />
<br />
=== Unresponsive key bindings ===<br />
<br />
Some tools such as [[Taking_a_screenshot#scrot|scrot]] may not work when used with a regular key binding (executed after key press). In those cases, execute commands after key release with the {{ic|--release}} argument [http://i3wm.org/docs/userguide.html#keybindings]:<br />
<br />
bindsym --release Print exec --no-startup-id scrot<br />
bindsym --release Shift+Print exec --no-startup-id scrot -s<br />
<br />
=== Tearing ===<br />
<br />
i3 does [https://github.com/i3/i3/issues/661 not properly implement double buffering] hence tearing or flickering may occur. To prevent this, install and configure [[compton]]. [https://faq.i3wm.org/question/3279/do-i-need-a-composite-manager-compton/?answer=3282#post-id-3282]<br />
<br />
== See also ==<br />
<br />
* [http://i3wm.org Official website]<br />
* [http://www.funtoo.org/I3_Tiling_Window_Manager funtoo Wiki]<br />
* [http://code.stapelberg.de/git/i3 i3 Source code]<br />
* [https://github.com/ashinkarov/i3-extras i3-extras] - Collection of scripts and patches<br />
* [https://github.com/acrisci/i3ipc-glib i3ipc-glib] - A library for i3 extensions<br />
* [https://github.com/veelenga/i3ipc-ruby i3ipc-ruby] - An improved library for i3 extensions in Ruby<br />
* [http://www.j4tools.org/ j4tools] - non-official tools designed to work with i3<br />
<br />
'''Arch Linux Forums'''<br />
* [https://bbs.archlinux.org/viewtopic.php?id=99064 The i3 thread] - A general discussion about i3<br />
* [https://bbs.archlinux.org/viewtopic.php?id=103369 i3 desktop screenshots and config sharing]<br />
<br />
'''Screencasts'''<br />
* [http://www.youtube.com/watch?v=Wx0eNaGzAZU i3 window manager v4.1 screencast]</div>PhilippDhttps://wiki.archlinux.org/index.php?title=Power_management/Suspend_and_hibernate&diff=365803Power management/Suspend and hibernate2015-03-17T15:21:37Z<p>PhilippD: /* Wake-on-LAN */</p>
<hr />
<div>[[Category:Power management]]<br />
[[ja:サスペンドとハイバネート]]<br />
{{Related articles start}}<br />
{{Related|Uswsusp}}<br />
{{Related|TuxOnIce}}<br />
{{Related|systemd}}<br />
{{Related|pm-utils}}<br />
{{Related|hibernate-script}}<br />
{{Related|Suspending to RAM with hibernate-script}}<br />
{{Related|Power management}}<br />
{{Related articles end}}<br />
Currently there are three methods of suspending available: '''suspend to RAM''' (usually called just '''suspend'''), '''suspend to disk''' (usually known as '''hibernate'''), and '''hybrid suspend''' (sometimes aptly called '''suspend to both'''):<br />
<br />
* '''Suspend to RAM''' method cuts power to most parts of the machine aside from the RAM, which is required to restore the machine's state. Because of the large power savings, it is advisable for laptops to automatically enter this mode when the computer is running on batteries and the lid is closed (or the user is inactive for some time).<br />
<br />
* '''Suspend to disk''' method saves the machine's state into [[Swap|swap space]] and completely powers off the machine. When the machine is powered on, the state is restored. Until then, there is zero power consumption.<br />
<br />
* '''Suspend to both''' method saves the machine's state into swap space, but does not power off the machine. Instead, it invokes usual suspend to RAM. Therefore, if the battery is not depleted, the system can resume from RAM. If the battery is depleted, the system can be resumed from disk, which is much slower than resuming from RAM, but the machine's state has not been lost.<br />
<br />
There are multiple low level interfaces (backends) providing basic functionality, and some high level interfaces providing tweaks to handle problematic hardware drivers/kernel modules (e.g. video card re-initialization).<br />
<br />
== Low level interfaces ==<br />
<br />
Though these interfaces can be used directly, it is advisable to use some of [[#High level interfaces|high level interfaces]] to suspend/hibernate. Using low level interfaces directly is significantly faster than using any high level interface, since running all the pre- and post-suspend hooks takes time, but hooks can properly set hardware clock, restore wireless etc.<br />
<br />
=== kernel (swsusp) ===<br />
<br />
The most straightforward approach is to directly inform the in-kernel software suspend code (swsusp) to enter a suspended state; the exact method and state depends on the level of hardware support. On modern kernels, writing appropriate strings to {{ic|/sys/power/state}} is the primary mechanism to trigger this suspend.<br />
<br />
See [https://www.kernel.org/doc/Documentation/power/states.txt kernel documentation] for details.<br />
<br />
=== uswsusp ===<br />
<br />
The uswsusp ('Userspace Software Suspend') is a wrapper around the kernel's suspend-to-RAM mechanism, which performs some graphics adapter manipulations from userspace before suspending and after resuming.<br />
<br />
See main article [[Uswsusp]].<br />
<br />
=== tuxonice ===<br />
<br />
TuxOnIce is a fork of the kernel implementation of suspend/hibernate that provides kernel patches to improve the default implementation. It requires a custom kernel to achieve this purpose.<br />
<br />
See main article [[TuxOnIce]].<br />
<br />
== High level interfaces ==<br />
<br />
{{Note|The end goal of these packages is to provide binaries/scripts that can be invoked to perform suspend/hibernate. Actually hooking them up to power buttons or menu clicks or laptop lid events is usually left to other tools. To automatically suspend/hibernate on certain power events, such as laptop lid close or battery depletion percentage, you may want to look into running [[Acpid]].}}<br />
<br />
=== systemd ===<br />
<br />
[[systemd]] provides native commands for suspend, hibernate and a hybrid suspend, see [[Power management#Power management with systemd]] for details.<br />
<br />
See [[Power management#Sleep hooks]] for additional information on configuring suspend/hibernate hooks. Also see {{ic|man systemctl}}, {{ic|man systemd-sleep}}, and {{ic|man systemd.special}}.<br />
<br />
=== pm-utils ===<br />
<br />
pm-utils is a set of shell scripts that encapsulate the backend's suspend/hibernate functionality. It comes with a set of pre- and post-suspend tweaks and various hooks to customize the process.<br />
<br />
See main article [[pm-utils]].<br />
<br />
== Suspend to RAM ==<br />
<br />
Suspend to RAM should work out of the box.<br />
<br />
== Hibernation ==<br />
<br />
In order to use hibernation, you need to create swap partition or swap file. See [[Swap]] for details.<br />
<br />
=== About swap partition/file size ===<br />
<br />
Even if your swap partition is smaller than RAM, you still have a big chance of hibernating successfully. According to [https://www.kernel.org/doc/Documentation/power/interface.txt kernel documentation]:<br />
<br />
: ''{{ic|/sys/power/image_size}} controls the size of the image created by the suspend-to-disk mechanism. It can be written a string representing a non-negative integer that will be used as an upper limit of the image size, in bytes. The suspend-to-disk mechanism will do its best to ensure the image size will not exceed that number. However, if this turns out to be impossible, it will try to suspend anyway using the smallest image possible. In particular, if "0" is written to this file, the suspend image will be as small as possible. Reading from this file will display the current image size limit, which is set to 2/5 of available RAM by default.''<br />
<br />
You may either decrease the value of {{ic|/sys/power/image_size}} to make the suspend image as small as possible (for small swap partitions), or increase it to possibly speed up the hibernation process.<br />
<br />
=== Required kernel parameters ===<br />
<br />
The kernel parameter {{ic|1=resume=''swap_partition''}} has to be used. Either the name the kernel assigns to the partition (for example {{ic|/dev/sda1}}) or its [[UUID]] (for example {{ic|1=UUID=4209c845-f495-4c43-8a03-5363dd433153}}) can be used as {{ic|''swap_partition''}}. Generally, the naming method used for the {{ic|resume}} parameter should be the same as used for the {{ic|root}} parameter.<br />
<br />
The configuration depends on the used [[boot loader]], some examples are given below.<br />
<br />
==== Example for syslinux ====<br />
<br />
Just edit your {{ic|syslinux.cfg}} file and add the {{ic|resume}} parameter to {{ic|APPEND}}. For example:<br />
<br />
{{hc|/boot/syslinux/syslinux.cfg|2=<br />
APPEND root=/dev/sda1 rw resume=''swap_partition''<br />
}}<br />
<br />
==== Example for GRUB ====<br />
<br />
The kernel name for the partition (for example {{ic|/dev/sda1}}) should be used if and only if [[GRUB/Tips and tricks#Persistent_block_device_naming|GRUB_DISABLE_LINUX_UUID]] is set to {{ic|true}} in GRUB. The {{ic|resume}} parameter can be set for example in the {{ic|GRUB_CMDLINE_LINUX_DEFAULT}} variable:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX_DEFAULT="resume=''swap_partition''"<br />
}}<br />
<br />
Remember to run {{ic|grub-mkconfig -o /boot/grub/grub.cfg}} afterwards.<br />
<br />
==== Example for gummiboot ====<br />
<br />
If [[gummiboot]] is used as boot manager, you have to add the {{ic|1=resume=''swap_partition''}} parameter in the options-list of the entry file. <br />
<br />
For example if your efi system partition is mounted in {{ic|/boot}}, then the option list should look like this:<br />
<br />
{{hc|/boot/loader/entries/arch.conf|2=<br />
options root=/dev/sda''X'' rw resume=''swap_partition'' <br />
}}<br />
<br />
==== Hibernation into swap file ====<br />
<br />
{{Warning|[[Btrfs#Swap file|Btrfs]] does not support swap files. Failure to heed this warning may result in file system corruption. While a swap file may be used on Btrfs when mounted through a loop device, this will result in severely degraded swap performance.}}<br />
<br />
Using a swap file instead of a swap partition requires an additional kernel parameter {{ic|1=resume_offset=''swap_file_offset''}}.<br />
<br />
The value of {{ic|''swap_file_offset''}} can be obtained by running {{ic|filefrag -v ''swap_file''}}, the output is in a table format and the required value is located in the first row of the {{ic|physical_offset}} column. For example:<br />
<br />
{{hc|# filefrag -v /swapfile|<nowiki><br />
Filesystem type is: ef53<br />
File size of /swapfile is 4294967296 (1048576 blocks of 4096 bytes)<br />
ext: logical_offset: physical_offset: length: expected: flags:<br />
0: 0.. 0: 38912.. 38912: 1: <br />
1: 1.. 22527: 38913.. 61439: 22527: unwritten<br />
2: 22528.. 53247: 899072.. 929791: 30720: 61440: unwritten<br />
...<br />
</nowiki>}}<br />
<br />
In the example the value of {{ic|''swap_file_offset''}} is {{ic|38912}}.<br />
<br />
{{Tip|The value of {{ic|''swap_file_offset''}} can also be obtained by running {{ic|swap-offset ''swap_file''}}. The ''swap-offset'' binary is provided by package {{AUR|uswsusp-git}}.}}<br />
<br />
{{Note|<br />
* The {{ic|resume}} kernel parameter specifies the device of the partition that contains the swap file, not swap file itself! The parameter {{ic|resume_offset}} informs the system where the swap file starts on the resume device.<br />
* If using [[uswsusp]], then these two parameters have to be provided in {{ic|/etc/suspend.conf}} via the keys {{ic|resume device}} and {{ic|resume offset}}.<br />
}}<br />
<br />
=== Configure the initramfs ===<br />
<br />
<br />
When an [[initramfs]] with the {{ic|base}} hook is used, which is the default, the {{ic|resume}} hook is required in {{ic|/etc/mkinitcpio.conf}}. Whether by label or by UUID, the swap partition is referred to with a udev device node, so the {{ic|resume}} hook must go ''after'' the {{ic|udev}} hook. This example was made starting from the default hook configuration.<br />
<br />
HOOKS="base udev resume autodetect modconf block filesystems keyboard fsck"<br />
<br />
Rebuild the initramfs for these changes to take effect:<br />
<br />
# mkinitcpio -p linux<br />
<br />
The {{ic|systemd}} hook provides its own resume mechanism, so if using this hook, no modification to the initramfs needs to be made.<br />
<br />
{{Note|If you use a custom kernel, then you might have to change the value of the {{ic|-p}} option.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== ACPI_OS_NAME ===<br />
<br />
You might want to tweak your '''DSDT table''' to make it work. See [[DSDT]] article<br />
<br />
=== VAIO Users ===<br />
<br />
Add acpi_sleep=nonvs kernel flag to your loader, and you are done!<br />
<br />
=== Suspend/hibernate doesn't work ===<br />
<br />
There have been many reports about the screen going black without easily viewable errors or the ability to do anything when going into and coming back from suspend and/or hibernate. These problems have been seen on both laptops and desktops. This is not an official solution, but switching to an older kernel, especially the LTS-kernel, will probably fix this.<br />
<br />
=== Wake-on-LAN ===<br />
<br />
If [[Wake-on-LAN]] is active, the network interface card will consume power even if the computer is hibernated.</div>PhilippDhttps://wiki.archlinux.org/index.php?title=Power_management/Suspend_and_hibernate&diff=365802Power management/Suspend and hibernate2015-03-17T15:21:06Z<p>PhilippD: /* Troubleshooting */ Added a link towards Wake-on-LAN, as it may consume power during the hibernated state</p>
<hr />
<div>[[Category:Power management]]<br />
[[ja:サスペンドとハイバネート]]<br />
{{Related articles start}}<br />
{{Related|Uswsusp}}<br />
{{Related|TuxOnIce}}<br />
{{Related|systemd}}<br />
{{Related|pm-utils}}<br />
{{Related|hibernate-script}}<br />
{{Related|Suspending to RAM with hibernate-script}}<br />
{{Related|Power management}}<br />
{{Related articles end}}<br />
Currently there are three methods of suspending available: '''suspend to RAM''' (usually called just '''suspend'''), '''suspend to disk''' (usually known as '''hibernate'''), and '''hybrid suspend''' (sometimes aptly called '''suspend to both'''):<br />
<br />
* '''Suspend to RAM''' method cuts power to most parts of the machine aside from the RAM, which is required to restore the machine's state. Because of the large power savings, it is advisable for laptops to automatically enter this mode when the computer is running on batteries and the lid is closed (or the user is inactive for some time).<br />
<br />
* '''Suspend to disk''' method saves the machine's state into [[Swap|swap space]] and completely powers off the machine. When the machine is powered on, the state is restored. Until then, there is zero power consumption.<br />
<br />
* '''Suspend to both''' method saves the machine's state into swap space, but does not power off the machine. Instead, it invokes usual suspend to RAM. Therefore, if the battery is not depleted, the system can resume from RAM. If the battery is depleted, the system can be resumed from disk, which is much slower than resuming from RAM, but the machine's state has not been lost.<br />
<br />
There are multiple low level interfaces (backends) providing basic functionality, and some high level interfaces providing tweaks to handle problematic hardware drivers/kernel modules (e.g. video card re-initialization).<br />
<br />
== Low level interfaces ==<br />
<br />
Though these interfaces can be used directly, it is advisable to use some of [[#High level interfaces|high level interfaces]] to suspend/hibernate. Using low level interfaces directly is significantly faster than using any high level interface, since running all the pre- and post-suspend hooks takes time, but hooks can properly set hardware clock, restore wireless etc.<br />
<br />
=== kernel (swsusp) ===<br />
<br />
The most straightforward approach is to directly inform the in-kernel software suspend code (swsusp) to enter a suspended state; the exact method and state depends on the level of hardware support. On modern kernels, writing appropriate strings to {{ic|/sys/power/state}} is the primary mechanism to trigger this suspend.<br />
<br />
See [https://www.kernel.org/doc/Documentation/power/states.txt kernel documentation] for details.<br />
<br />
=== uswsusp ===<br />
<br />
The uswsusp ('Userspace Software Suspend') is a wrapper around the kernel's suspend-to-RAM mechanism, which performs some graphics adapter manipulations from userspace before suspending and after resuming.<br />
<br />
See main article [[Uswsusp]].<br />
<br />
=== tuxonice ===<br />
<br />
TuxOnIce is a fork of the kernel implementation of suspend/hibernate that provides kernel patches to improve the default implementation. It requires a custom kernel to achieve this purpose.<br />
<br />
See main article [[TuxOnIce]].<br />
<br />
== High level interfaces ==<br />
<br />
{{Note|The end goal of these packages is to provide binaries/scripts that can be invoked to perform suspend/hibernate. Actually hooking them up to power buttons or menu clicks or laptop lid events is usually left to other tools. To automatically suspend/hibernate on certain power events, such as laptop lid close or battery depletion percentage, you may want to look into running [[Acpid]].}}<br />
<br />
=== systemd ===<br />
<br />
[[systemd]] provides native commands for suspend, hibernate and a hybrid suspend, see [[Power management#Power management with systemd]] for details.<br />
<br />
See [[Power management#Sleep hooks]] for additional information on configuring suspend/hibernate hooks. Also see {{ic|man systemctl}}, {{ic|man systemd-sleep}}, and {{ic|man systemd.special}}.<br />
<br />
=== pm-utils ===<br />
<br />
pm-utils is a set of shell scripts that encapsulate the backend's suspend/hibernate functionality. It comes with a set of pre- and post-suspend tweaks and various hooks to customize the process.<br />
<br />
See main article [[pm-utils]].<br />
<br />
== Suspend to RAM ==<br />
<br />
Suspend to RAM should work out of the box.<br />
<br />
== Hibernation ==<br />
<br />
In order to use hibernation, you need to create swap partition or swap file. See [[Swap]] for details.<br />
<br />
=== About swap partition/file size ===<br />
<br />
Even if your swap partition is smaller than RAM, you still have a big chance of hibernating successfully. According to [https://www.kernel.org/doc/Documentation/power/interface.txt kernel documentation]:<br />
<br />
: ''{{ic|/sys/power/image_size}} controls the size of the image created by the suspend-to-disk mechanism. It can be written a string representing a non-negative integer that will be used as an upper limit of the image size, in bytes. The suspend-to-disk mechanism will do its best to ensure the image size will not exceed that number. However, if this turns out to be impossible, it will try to suspend anyway using the smallest image possible. In particular, if "0" is written to this file, the suspend image will be as small as possible. Reading from this file will display the current image size limit, which is set to 2/5 of available RAM by default.''<br />
<br />
You may either decrease the value of {{ic|/sys/power/image_size}} to make the suspend image as small as possible (for small swap partitions), or increase it to possibly speed up the hibernation process.<br />
<br />
=== Required kernel parameters ===<br />
<br />
The kernel parameter {{ic|1=resume=''swap_partition''}} has to be used. Either the name the kernel assigns to the partition (for example {{ic|/dev/sda1}}) or its [[UUID]] (for example {{ic|1=UUID=4209c845-f495-4c43-8a03-5363dd433153}}) can be used as {{ic|''swap_partition''}}. Generally, the naming method used for the {{ic|resume}} parameter should be the same as used for the {{ic|root}} parameter.<br />
<br />
The configuration depends on the used [[boot loader]], some examples are given below.<br />
<br />
==== Example for syslinux ====<br />
<br />
Just edit your {{ic|syslinux.cfg}} file and add the {{ic|resume}} parameter to {{ic|APPEND}}. For example:<br />
<br />
{{hc|/boot/syslinux/syslinux.cfg|2=<br />
APPEND root=/dev/sda1 rw resume=''swap_partition''<br />
}}<br />
<br />
==== Example for GRUB ====<br />
<br />
The kernel name for the partition (for example {{ic|/dev/sda1}}) should be used if and only if [[GRUB/Tips and tricks#Persistent_block_device_naming|GRUB_DISABLE_LINUX_UUID]] is set to {{ic|true}} in GRUB. The {{ic|resume}} parameter can be set for example in the {{ic|GRUB_CMDLINE_LINUX_DEFAULT}} variable:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX_DEFAULT="resume=''swap_partition''"<br />
}}<br />
<br />
Remember to run {{ic|grub-mkconfig -o /boot/grub/grub.cfg}} afterwards.<br />
<br />
==== Example for gummiboot ====<br />
<br />
If [[gummiboot]] is used as boot manager, you have to add the {{ic|1=resume=''swap_partition''}} parameter in the options-list of the entry file. <br />
<br />
For example if your efi system partition is mounted in {{ic|/boot}}, then the option list should look like this:<br />
<br />
{{hc|/boot/loader/entries/arch.conf|2=<br />
options root=/dev/sda''X'' rw resume=''swap_partition'' <br />
}}<br />
<br />
==== Hibernation into swap file ====<br />
<br />
{{Warning|[[Btrfs#Swap file|Btrfs]] does not support swap files. Failure to heed this warning may result in file system corruption. While a swap file may be used on Btrfs when mounted through a loop device, this will result in severely degraded swap performance.}}<br />
<br />
Using a swap file instead of a swap partition requires an additional kernel parameter {{ic|1=resume_offset=''swap_file_offset''}}.<br />
<br />
The value of {{ic|''swap_file_offset''}} can be obtained by running {{ic|filefrag -v ''swap_file''}}, the output is in a table format and the required value is located in the first row of the {{ic|physical_offset}} column. For example:<br />
<br />
{{hc|# filefrag -v /swapfile|<nowiki><br />
Filesystem type is: ef53<br />
File size of /swapfile is 4294967296 (1048576 blocks of 4096 bytes)<br />
ext: logical_offset: physical_offset: length: expected: flags:<br />
0: 0.. 0: 38912.. 38912: 1: <br />
1: 1.. 22527: 38913.. 61439: 22527: unwritten<br />
2: 22528.. 53247: 899072.. 929791: 30720: 61440: unwritten<br />
...<br />
</nowiki>}}<br />
<br />
In the example the value of {{ic|''swap_file_offset''}} is {{ic|38912}}.<br />
<br />
{{Tip|The value of {{ic|''swap_file_offset''}} can also be obtained by running {{ic|swap-offset ''swap_file''}}. The ''swap-offset'' binary is provided by package {{AUR|uswsusp-git}}.}}<br />
<br />
{{Note|<br />
* The {{ic|resume}} kernel parameter specifies the device of the partition that contains the swap file, not swap file itself! The parameter {{ic|resume_offset}} informs the system where the swap file starts on the resume device.<br />
* If using [[uswsusp]], then these two parameters have to be provided in {{ic|/etc/suspend.conf}} via the keys {{ic|resume device}} and {{ic|resume offset}}.<br />
}}<br />
<br />
=== Configure the initramfs ===<br />
<br />
<br />
When an [[initramfs]] with the {{ic|base}} hook is used, which is the default, the {{ic|resume}} hook is required in {{ic|/etc/mkinitcpio.conf}}. Whether by label or by UUID, the swap partition is referred to with a udev device node, so the {{ic|resume}} hook must go ''after'' the {{ic|udev}} hook. This example was made starting from the default hook configuration.<br />
<br />
HOOKS="base udev resume autodetect modconf block filesystems keyboard fsck"<br />
<br />
Rebuild the initramfs for these changes to take effect:<br />
<br />
# mkinitcpio -p linux<br />
<br />
The {{ic|systemd}} hook provides its own resume mechanism, so if using this hook, no modification to the initramfs needs to be made.<br />
<br />
{{Note|If you use a custom kernel, then you might have to change the value of the {{ic|-p}} option.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== ACPI_OS_NAME ===<br />
<br />
You might want to tweak your '''DSDT table''' to make it work. See [[DSDT]] article<br />
<br />
=== VAIO Users ===<br />
<br />
Add acpi_sleep=nonvs kernel flag to your loader, and you are done!<br />
<br />
=== Suspend/hibernate doesn't work ===<br />
<br />
There have been many reports about the screen going black without easily viewable errors or the ability to do anything when going into and coming back from suspend and/or hibernate. These problems have been seen on both laptops and desktops. This is not an official solution, but switching to an older kernel, especially the LTS-kernel, will probably fix this.<br />
<br />
=== Wake-on-LAN ===<br />
<br />
If [[Wake-on-LAN]] is active, your network interface card will consume power even if the computer is hibernated.</div>PhilippDhttps://wiki.archlinux.org/index.php?title=Wake-on-LAN&diff=365801Wake-on-LAN2015-03-17T15:18:22Z<p>PhilippD: /* Ensure that Wake-on-LAN is enabled and survives a reboot */ added explanation of d as a value in "Wake-on"</p>
<hr />
<div>[[Category:Networking]]<br />
'''Wake-on-LAN''', otherwise known as 'wol', is the ability to switch on a computer that is connected to a network (be it the internet or intranet). This article deals with what it is, how it can be used from an Arch Linux computer, and its general uses.<br />
<br />
It is important to note that Wake-on-LAN applies to the computers being physically connected (ie, not wireless).<br />
<br />
==Does my motherboard support Wake-on-LAN?==<br />
<br />
For Wake-on-LAN to work, the target computer motherboard must support this feature. Generally speaking, the Wake-on-LAN (non)ability of the target motherboard will be specified by the hardware manufacturer. Sometimes, this ability is evident by browsing through said motherboard's BIOS and looking for something like 'PCI Power up' or “Allow PCI wake up event”. Most modern motherboards should support Wake-on-LAN.<br />
<br />
==Ensure that Wake-on-LAN is enabled and survives a reboot==<br />
A common problem with the Wake-on-LAN in computers running Linux is that the network drivers have Wake-on-LAN switched off by default. To manually switch on the Wake-on-LAN feature on your driver, you will need to install {{Pkg|ethtool}}.<br />
<br />
{{Note|For the following commands substitute net0 with your network device, e.g. eth0}}<br />
<br />
First query the driver to see if it's defaulted to 'on' by using ethtool:<br />
<br />
{{hc|<nowiki># ethtool net0 | grep Wake-on</nowiki>|<nowiki><br />
Supports Wake-on: pumbag<br />
Wake-on: b<br />
</nowiki>}}<br />
<br />
The values define what activity to wake on: d (disabled), p (PHY activity), u (unicast activity), m (multicast activity), b (broadcast activity), a (ARP activity), and g (magic packet activity).<br />
<br />
{{Note|We need a 'Wake-on' value of 'g' for WOL to work.}}<br />
<br />
To enable the wol feature in the driver, simply run the following<br />
# ethtool -s net0 wol g<br />
<br />
This command does not last beyond the '''next''' reboot. If using netctl, one can make this setting persistent by adding the following to your netctl profile:<br />
{{hc|/etc/netctl/PROFILE|2=<br />
ExecUpPost='/usr/bin/ethtool -s net0 wol g'<br />
}}<br />
<br />
*If for some reason, you find that after using the command to switch your network drivers Wake-on-LAN feature on, the computer shuts down normally but then starts again, experiment with combinations of [u/b/m]g<br />
*For some network cards, you may also need the following command:<br />
<br />
# echo enabled > /sys/class/net/net0/device/power/wakeup<br />
<br />
===With udev===<br />
<br />
udev is capable of running any command you desire as soon as a device is visible. We want udev to turn on wake on lan for our device. Put the following in /etc/udev/rules.d/50-wol.rules, replacing N with the number for your interface:<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="netN", RUN+="/usr/bin/ethtool -s %k wol g"<br />
<br />
This tells udev to run "/usr/bin/ethtool -s netN wol g" as soon as the device netN exists. To turn on wake on lan for all new devices, replace the N with a '*':<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="net*", RUN+="/usr/bin/ethtool -s %k wol g"<br />
<br />
===With cron===<br />
<br />
A command can be run each time the computer is (re)booted using "@reboot" in a crontab. First, make sure [[Cron#Installation|cron]] is enabled, and then [[Cron#Basic_commands|edit a crontab]] for the root user that contains the following line:<br />
@reboot /usr/bin/ethtool -s [net-device] wol g<br />
<br />
===With systemd===<br />
<br />
If for some reason udev fails or is not an option, systemd can be used instead as a last resort. (In this editor's experience, systemd is rather intermittent.) To use systemd, do ''not'' follow the udev instructions. Instead, create a new service unit file /etc/systemd/system/wol@.service:<br />
<br />
{{bc|1=<br />
[Unit]<br />
Description=Wake-on-LAN for %i<br />
Requires=network.target<br />
After=network.target<br />
<br />
[Service]<br />
ExecStart=/usr/bin/ethtool -s %i wol g<br />
Type=oneshot<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
Or install {{AUR|wol-systemd}} package from the [[AUR]]<br />
<br />
Then activate this new service for your network adapter:<br />
<br />
# systemctl enable wol@net0<br />
<br />
and start it right now<br />
<br />
# systemctl start wol@net0<br />
<br />
==Wake-on-LAN in different situations==<br />
<br />
The computer that you want to use Wake-on-LAN on may be directly linked to your computer through a network cable, connected to the same router that you are using, or remotely, across the internet.<br />
<br />
There are four essential things needed in order to use Wake-on-LAN on a target PC:<br />
<br />
#Some kind of Wake-on-LAN software on the host (your) PC<br />
#A connection to the internet or intranet of the target PC<br />
#The MAC address of the target PC<br />
#The internal or external IP of the target PC<br />
<br />
*Firstly, install a Wake-on-LAN software. In this article, {{Pkg|wol}} (available in the [[official repositories]]) will be used.<br />
<br />
*'''It is recommended that you read the documentation of wol'''<br />
<br />
man wol<br />
wol --help<br />
<br />
*wol requires several parameters, the most basic needed:<br />
<br />
wol MACADDRESS<br />
<br />
*But it is good practice to include the IP address or hostname, therefore this syntax should be the minimal used:<br />
<br />
# wol -i HOSTNAME_OR_IP MACADDRESS<br />
<br />
*The documentation of wol states that:<br />
<br />
::''Each MAC-ADDRESS is written as x:x:x:x:x:x, where x is a hexadecimal number between 0 and ff which represents one byte of the address, which is in network byte order (big endian).''<br />
<br />
*To obtain the MACADDRESS of the target computer:<br />
<br />
$ ip link<br />
<br />
The port, IP or hostname of the target PC will be addressed in the relevant following sections.<br />
<br />
===Across your intranet/network (no router)===<br />
<br />
If you are connected directly to another computer through a network cable, or have disabled your router firewall (not a good idea), then using Wake-on-LAN should be very simple.<br />
<br />
====For two computers connected to each other====<br />
<br />
wol MACADDRESS_OF_TARGET_PC<br />
<br />
====For computers connected to a non-firewalled router====<br />
<br />
wol -i INTERNAL_IP_OF_TARGET_PC MACADDRESS_OF_TARGET_PC<br />
<br />
*To find the internal IP:<br />
{{bc|<nowiki>ip addr | grep 'inet '</nowiki>}}<br />
<br />
*Since you are not firewalled, then there is no need to worry about port redirects.<br />
*If you intend to continue using Wake-on-LAN, it is recommended that you assign your computer's MACADDRESS to a specific IP on your router. Consult your router for details as to how to do this.<br />
<br />
===Across your intranet/network (router)===<br />
<br />
The syntax used in this situation:<br />
<br />
wol -p PORT_FORWARDED_TO_INTERNAL_IP -i INTERNAL_IP MACADDRESS_OF_TARGET_PC<br />
<br />
*When you send the MagicPacket signal to the target computer via a specific port, the signal passes through your router. The router must be instructed to forward any signal heading for that specific port to the internal IP of the target PC.<br />
<br />
*It is recommended that for multiple computers connected to one computer, to assign a different port forward to each internal IP<br />
<br />
*For port forwarding help, please consult http://portforward.com/ (though this website has some Windows specific content, it has a very large database of router web interfaces)<br />
<br />
===Across the internet===<br />
{{Expansion|Request for OpenWRT instructions.}}<br />
The syntax needed in this case:<br />
<br />
wol -p X -i HOSTNAME_OR_EXTERNAL_IP_OF_TARGET MACADDRESS<br />
<br />
*Assuming that you know the external IP of the target machine, and that the [[Wake-on-LAN#Across_your_intranet.2Fnetwork_.28router.29|router ports]] on both sides have been forwarding correctly, then this should be exactly as the syntax states.<br />
<br />
<br />
Usually it is necessary to forward your wol port (typically UDP 9) to the broadcast address on your network, not to a particular IP. Most routers do not allow you to forward to broadcast, however if you can get shell access to your router (through telnet, ssh, serial cable, etc) you can implement this workaround:<br />
ip neighbor add 192.168.1.254 lladdr FF:FF:FF:FF:FF:FF dev net0<br />
<br />
(The above command assumes your network is 192.168.1.0/24 and use net0 as network interface). Now, forward UDP port 9 to 192.168.1.254. This has worked for me on a Linksys WRT54G running Tomato, and on the Verizon FIOS ActionTec router.<br />
<br />
For notes on how to do it on DD-WRT routers, see [http://www.dd-wrt.com/wiki/index.php/WOL#Remote_Wake_On_LAN_via_Port_Forwarding this tutorial].<br />
<br />
==Battery draining problem==<br />
Some laptops have battery draining problem after shutdown [http://ubuntuforums.org/archive/index.php/t-1729782.html]. This might be caused by enabled Wake-on-LAN. To solve this problem, we can disable it by using ethtool as mentioned above.<br />
<br />
# ethtool -s net0 wol d<br />
<br />
We can also add this to the '''/etc/rc.local''' or '''/etc/rc.local.shutdown'''.<br />
<br />
==Additional Notes==<br />
<br />
*A common problem is that some forget to switch on the Wake-on-LAN feature in their BIOS.<br />
<br />
*In some systems the BIOS option "Boot from PCI/PCI-E" needs to be Enabled.<br />
<br />
==Example WOL script==<br />
Here is a script you can use to automate wol to several different machine. Modify as you see fit:<br />
<br />
<pre>#!/bin/bash<br />
<br />
# definition of MAC addresses<br />
monster=01:12:46:82:ab:4f<br />
chronic=00:3a:53:21:bc:30<br />
powerless=1a:32:41:02:29:92<br />
ghost=01:1a:d2:56:6b:e6<br />
<br />
while [ "$input1" != quit ]; do<br />
echo "Which PC to wake?"<br />
echo "p) powerless"<br />
echo "m) monster"<br />
echo "c) chronic"<br />
echo "g) ghost"<br />
echo "b) wake monster, wait 40sec, then wake chronic"<br />
echo "q) quit and take no action"<br />
read input1<br />
if [ $input1 == p ]; then<br />
/usr/bin/wol $powerless<br />
exit 1<br />
fi<br />
<br />
if [ $input1 == m ]; then<br />
/usr/bin/wol $monster<br />
exit 1<br />
fi<br />
<br />
if [ $input1 == c ]; then<br />
/usr/bin/wol $chronic<br />
exit 1<br />
fi<br />
<br />
# this line requires an IP address in /etc/hosts for ghost<br />
# and should use wol over the internet provided that port 9<br />
# is forwarded to ghost on ghost's router<br />
<br />
if [ $input1 == g ]; then<br />
/usr/bin/wol -v -h -p 9 ghost $ghost<br />
exit 1<br />
fi<br />
<br />
if [ $input1 == b ]; then<br />
/usr/bin/wol $monster<br />
echo "monster sent, now waiting for 40sec then waking chronic"<br />
sleep 40<br />
/usr/bin/wol $chronic<br />
exit 1<br />
fi<br />
<br />
if [ $input1 == Q ] || [ $input1 == q ]; then<br />
echo "later!"<br />
exit 1<br />
fi<br />
<br />
done<br />
echo "this is the (quit) end!! c-ya!"</pre><br />
<br />
== Troubleshooting ==<br />
===Realtek===<br />
Users with Realtek 8168 8169 8101 8111(C) based NICs (cards / and on-board) may notice a problem where the NIC seems to be disabled on boot and has no Link light. See [[Network configuration#Realtek no link / WOL problem]]<br />
<br />
== See also ==<br />
<br />
* [http://www.depicus.com/wake-on-lan/woli.aspx Wake-On-Lan]</div>PhilippDhttps://wiki.archlinux.org/index.php?title=I3&diff=360120I32015-02-09T17:20:56Z<p>PhilippD: /* Screensaver and power management */ Completed information on locking the screen with xautolock.</p>
<hr />
<div>{{DISPLAYTITLE:i3}}<br />
[[Category:Tiling WMs]]<br />
[[Category:Dynamic WMs]]<br />
[[ja:i3]]<br />
[[ko:i3]]<br />
[[ru:i3]]<br />
[[zh-CN:i3]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Window manager}}<br />
{{Related|Comparison of tiling window managers}}<br />
{{Related|Clipboard}}<br />
{{Related|Autostarting#Graphical}}<br />
{{Related articles end}}<br />
<br />
[http://i3wm.org/ i3] is a dynamic [[Wikipedia:Tiling window manager|tiling window manager]] inspired by [[wmii]] that is primarily targeted at developers and advanced users.<br />
<br />
The stated goals for i3 include clear documentation, proper multi-monitor support, a tree structure for windows, and different modes like in [[vim]].<br />
<br />
== Installation ==<br />
<br />
[[pacman|Install]] the {{Grp|i3}} [[Pacman#Installing package groups|package group]] from the [[official repositories]]. It includes the window manager {{Pkg|i3-wm}}, {{Pkg|i3status}} which writes a status line to i3bar through [[Wikipedia:Standard streams#Standard output (stdout)|stdout]], and {{Pkg|i3lock}}, a screen locker.<br />
<br />
Additional packages are available in the [[Arch User Repository]]. See the section [[i3#Patches]] for examples.<br />
<br />
=== Display manager ===<br />
<br />
{{Pkg|i3-wm}} includes {{ic|i3.desktop}} as [[Xsession]] which starts the window manager. {{ic|i3-with-shmlog.desktop}} enables logs (useful for debugging). {{AUR|i3-gnome}} integrates {{ic|i3}} into [[GNOME]].<br />
<br />
=== xinitrc ===<br />
<br />
Edit [[Xinitrc]], and add:<br />
<br />
exec i3<br />
<br />
To log the output from i3, add this line instead:<br />
<br />
exec i3 -V >> ~/i3log-$(date +'%F-%k-%M-%S') 2>&1<br />
<br />
Nvidia binary drivers before version '''302.17''' need the {{ic|--force-xinerama}} flag. A detailed explanation can be found at [http://i3wm.org/docs/multi-monitor.html i3wm.org].<br />
<br />
exec i3 --force-xinerama<br />
<br />
If you have trouble mapping keys (e.g. {{ic|;}} as semicolon), use {{Pkg|xorg-xev}} or see [[Extra keyboard keys]].<br />
<br />
$ xev | grep -A2 --line-buffered '^KeyRelease' | sed -n '/keycode /s/^.*keycode \([0-9]*\).* (.*, \(.*\)).*$/\1 \2/p'<br />
<br />
== Usage ==<br />
<br />
See the [http://i3wm.org/docs official documentation] for more information, namely the [http://i3wm.org/docs/userguide.html i3 User’s Guide].<br />
<br />
=== Application launcher ===<br />
<br />
i3 uses [[dmenu]] as an application launcher, which is bound by default to {{ic|$mod+d}}.<br />
<br />
{{Pkg|i3-wm}} contains ''i3-dmenu-desktop'', a [[Wikipedia:Perl|Perl]] wrapper for ''dmenu'' which uses [[desktop entries]] to create a list of all installed applications. Alternatively, the package {{AUR|j4-dmenu-desktop-git}} can be used; it is a near-drop-in replacement for ''i3-dmenu-desktop'', but much faster[[https://github.com/enkore/j4-dmenu-desktop/blob/master/README.md 1]].<br />
<br />
=== Keybindings ===<br />
<br />
In i3, commands are invoked with a modifier key, referred to as {{ic|$mod}}. This is {{ic|Alt}} (Mod1) by default, with {{ic|Super}} (Mod4) being a popular alternative.<br />
<br />
See the [http://i3wm.org/docs/refcard.html i3 reference card] and [http://i3wm.org/docs/userguide.html#_using_i3 Using i3] for default keybindings.<br />
<br />
=== Containers ===<br />
<br />
{{Expansion|The User's guide explains basic use of containers, yet is not sufficiently clear to allow more advanced use cases. It also does not mention ''focus child'' as it does ''focus parent''. See also: [https://faq.i3wm.org/question/222/how-to-get-rid-of-another-container/]}}<br />
<br />
i3 manages windows in a tree structure, with containers as building blocks. This structure branches with horizontal or vertical splits. Containers are tiled by default, but can be set to tabbed or stacked layouts, as well as made floating (such as for dialog windows). Floating windows are always on top.<br />
<br />
See [http://i3wm.org/docs/userguide.html#_tree i3 Tree] and [http://www.youtube.com/watch?v=AWA8Pl57UBY Containers and the tree data structure] for details.<br />
<br />
== Configuration ==<br />
<br />
See [http://i3wm.org/docs/userguide.html#configuring Configuring i3] for details. The rest of this article assumes the ''i3'' configuration file to be in the folder {{ic|~/.config}}.<br />
<br />
=== Colorschemes ===<br />
<br />
The configuration file allows for customization of window decoration colors, but the syntax makes it impractical to create or share themes. There are several projects which make this easier and include a variety of user-contributed themes.<br />
<br />
* {{App|i3-style|Modifies your config in place from a theme stored in a JSON object, designed for frequently tweaking or changing a colorscheme|https://github.com/acrisci/i3-style|{{Aur|nodejs-i3-style}}}}<br />
* {{App|j4-make-config|Merge your config with a collection of themes or personal config parts, for example host-specific configuration, allowing quick changing of the theme and flexible, dynamic customization of the configuration|https://github.com/okraits/j4-make-config|{{Aur|j4-make-config-git}}}}<br />
<br />
=== i3bar ===<br />
<br />
In addition to showing workspace information, i3bar can act as an input for i3status or an alternative, such as those mentioned in the next section. For example:<br />
<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
output LVDS1<br />
status_command i3status<br />
position top<br />
mode hide<br />
workspace_buttons yes<br />
tray_output none<br />
<br />
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1<br />
<br />
colors {<br />
background #000000<br />
statusline #ffffff<br />
<br />
focused_workspace #ffffff #285577<br />
active_workspace #ffffff #333333<br />
inactive_workspace #888888 #222222<br />
urgent_workspace #ffffff #900000<br />
}<br />
}<br />
}}<br />
<br />
See the [http://i3wm.org/docs/userguide.html#_configuring_i3bar Configuring i3bar] for details.<br />
<br />
==== i3bar alternatives ====<br />
<br />
Some users may prefer panels such as those provided by conventional [[Desktop environment|Desktop Environments]]. This can be achieved within i3 by launching the panel application of choice during startup.<br />
<br />
For the [[Xfce#Panel|XFCE panel]], add the following line anywhere in {{ic|~/.config/i3/config}}:<br />
<br />
exec --no-startup-id xfce4-panel --disable-wm-check<br />
<br />
Alternatively if using {{ic|startx}}, this can be done in your [[xinitrc]]:<br />
<br />
{{hc|~/.xinitrc|<br />
xfce4-panel --disable-wm-check &<br />
}}<br />
<br />
{{Accuracy|i3 is [[Wikipedia:Extended_Window_Manager_Hints|NETWM]] compliant, so workspace management from external panels should usally work. See also [http://i3wm.org/docs/wsbar.html]}}<br />
<br />
{{Note|Panel features that are specific to the [[Desktop environment|Desktop Environment]] (e.g., widgets for managing workspaces/sessions) will most likely not work, though i3's functionality should remain unaffected.}}<br />
<br />
i3bar can be disabled by commenting out the {{ic|<nowiki>bar{ }</nowiki>}} section of {{ic|~/.config/i3/config}} or using: <br />
<br />
{{hc|~/.config/i3/config|<br />
# bar toggle, hide or show <br />
bindsym $mod+m bar mode toggle<br />
}}<br />
This way you can show or hide bar as you want.<br />
<br />
=== i3status ===<br />
<br />
Copy over the default configuration files to the home directory:<br />
<br />
$ cp /etc/i3status.conf ~/.config/i3status/config<br />
<br />
Not all plugins are defined in the default configuration, see {{ic|man 1 i3status}} for details.<br />
<br />
{{Note|The example configuration file uses {{ic|eth0}} and {{ic|wlan0}} as interface names, see [[Network configuration#Device names]] if they do not match with your system. See {{ic|man i3status}} for other possible mismatches, such as the battery path.}}<br />
<br />
==== i3status replacements ====<br />
<br />
* {{App|[[conky]]| Highly extensible system monitor. For usage with i3bar see [http://i3wm.org/docs/user-contributed/conky-i3bar.html this tutorial] |http://conky.sourceforge.net/|{{Pkg|conky}}}}<br />
* {{App|i3blocks|Extensible via shell scripts. It can handle click events, interrupts, and defining of refresh intervals on a per-block basis.|https://github.com/vivien/i3blocks|{{AUR|i3blocks}}}}<br />
* {{App|i3pystatus|Extensible Python 3 status bar with many plugins and configuration options by default.|https://github.com/enkore/i3pystatus i3pystatus|{{AUR|i3pystatus-git}}}}<br />
* {{App|i3situation|Another Python 3 status bar generator.|https://github.com/HarveyHunt/i3situation|{{Aur|i3situation-git}}}}<br />
* {{App|j4status|Provides a statusline, configurable via plugins, and written in C.|http://j4status.j4tools.org/|{{Aur|j4status-git}}}}<br />
<br />
==== i3status wrappers ====<br />
<br />
* {{App|[[h2status]]|Bash wrapper for i3status that allows custom json entries as input, and can handle click events as well as asynchronous updates of the status bar.|https://wiki.archlinux.org/index.php/H2status|{{Aur|h2status}}}}<br />
* {{App|i3cat|A [[go]] based wrapper which can concatenate inputs from multiple external sources. It can handle click events and forwarding user specified signals to its subprocesses.|http://vincent-petithory.github.io/i3cat/|{{AUR|i3cat-git}}}}<br />
* {{App|py3status|An extensible i3status wrapper written in Python.|https://github.com/ultrabug/py3status|{{Aur|py3status}}}}<br />
<br />
==== Iconic fonts in the status bar ====<br />
<br />
''i3bar'' can be [[#Patches|patched]] for XBM icon support, but you can use iconic font sets instead.<br />
<br />
* {{App|ttf-font-awesome|Scalable vector icons that can be customized with CSS. A [http://fortawesome.github.io/Font-Awesome/cheatsheet/ cheatsheet] shows the Unicode point for each glyph.|http://fortawesome.github.io/Font-Awesome/|{{AUR|ttf-font-awesome}}}}<br />
* {{App|ttf-font-icons|Non-overlapping and consistently sized mix of Awesome and Ionicons. This also avoids minor overlapping between DejaVu Sans and Awesome.|https://www.dropbox.com/s/9iysh2i0gadi4ic/icons.pdf|{{AUR|ttf-font-icons}}}}.<br />
<br />
To combine fonts, define a font fallback sequence in your configuration file, separating fonts with {{ic|,}} like so:<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
...<br />
font pango:DejaVu Sans Mono, Icons 8<br />
...<br />
}<br />
}}<br />
<br />
You have to first list the comma separated font families and then add only one size specification at the end of the string. Do not set a size for each family (even if the size is the same) and do not try to get the same result using multiple font directives, as the vertical alignments and heights of the different components of the i3bar will be wrong in unexpected ways. The correct pango descriptor syntax is as shown above.<br />
<br />
{{Poor writing|Not everyone uses vim}}<br />
<br />
Finally, enter the iconic glyphs into the format strings in {{ic|~/.config/i3status/config}}. For this, use the unicode numbers given in the cheatsheets linked above. For example, if you're using vim while in insert mode you can type {{ic|Ctrl+v}}, followed by the unicode hexadecimal number for the glyph.<br />
<br />
In [[urxvt]], hold down {{ic|Ctrl+Shift}}, followed by the desired Unicode point.<br />
<br />
=== Terminal emulator ===<br />
<br />
By default when pressing {{ic|$mod+Return}} it launches the {{ic|i3-sensible-terminal}} which is a script that invokes a terminal. See {{ic|man i3-sensible-terminal}} for the order terminals are invoked in.<br />
<br />
To instead launch a terminal of choice, modify this line in {{ic|~/.config/i3/config}}:<br />
<br />
bindsym $mod+Return exec i3-sensible-terminal<br />
<br />
Alternatively, [[Environment_variable#Defining_variables_locally|locally define]] the {{ic|$TERMINAL}} variable:<br />
<br />
$ export TERMINAL=''yourterminal''<br />
<br />
== Tips and tricks ==<br />
<br />
=== Advanced window navigation ===<br />
<br />
See [http://www.slackword.net/?p=657 i3 window Navigation Tips].<br />
<br />
=== Jump to open window ===<br />
<br />
*{{App|quickswitch-i3|Python utility to quickly change to and locate windows in i3|https://github.com/proxypoke/quickswitch-for-i3|{{Aur|quickswitch-i3}}}}<br />
*{{App|i3-wm-scripts|search for and jump to windows with particular names matching regexp|https://github.com/yiuin/i3-wm-scripts||}}<br />
*{{App|winmenupy|Launches dmenu with a list of clients, sorted after workspaces. Selecting a client jumps to that window.|https://github.com/ziberna/i3-py/blob/master/examples/winmenu.py||}}<br />
*{{App|rofi|Search and jump to open and scratchpad window|https://davedavenport.github.io/rofi/|{{Aur|rofi}}}}<br />
<br />
=== Jump to urgent window ===<br />
<br />
Add to {{ic|.i3/config}}: [https://faq.i3wm.org/question/853/how-to-jump-to-urgent-workspace/]<br />
<br />
bindsym $mod+x [urgent=latest] focus<br />
<br />
=== Save and restore the window layout ===<br />
<br />
From version 4.8, and onward ''i3'' can save and restore workspace layouts. To do this, the following packages are needed: {{Pkg|perl-anyevent-i3}} and {{Pkg|perl-json-xs}} from the [[official repositories]].<br />
<br />
{{note| This section only provides quick tutorial on how to save the current window layout of a single workspace and how to restore it for later use. Refer to the [http://i3wm.org/docs/layout-saving.html official documentation] for more details}}<br />
<br />
==== Save the current window layout of a single workspace ====<br />
<br />
To save the current window layout, follow these steps:<br />
<br />
# First, execute various commands to open windows in a preferred workspace and resize them if needed. Make sure to write down each executed command for each window.<br />
# Now, in a new workspace, open a terminal and run the following: {{bc|i3-save-tree --workspace N > ~/.i3/workspace_N.json}} where N is the number of the preferred workspace. This will save the current layout of workspace N to the file {{ic|~/.i3/workspace_N.json}}.<br />
# The newly created file needs to be edited, however this may be done with the following commands: {{bc|<nowiki>tail -n +2 ~/.i3/workspace_N.json | fgrep -v '// splitv' | sed 's|//||g' > ~/.i3/workspace_N.json</nowiki>}}<br />
<br />
==== Restore the window layout of the workspace ====<br />
<br />
There are two ways to restore the layout of the workspace: by writing a script, or by editing {{ic|~/.i3/config}} to automatically load the layout. In this section only the first case will be considered, refer to the [http://i3wm.org/docs/layout-saving.html#_restoring_the_layout official documentation] for the second case.<br />
<br />
To restore the saved layout in the previous section, write a file named {{ic|load_layout.sh}} with the following contents:<br />
<br />
* The starting lines: {{bc|<nowiki><br />
~/#!/bin/bash<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
</nowiki>}} where M is the number of the workspace in which you would like to load the previously saved layout and N is the number of workspace saved in the previous section.<br />
* And the commands used in the previous section to get the preferred windows, but enclosed in parentheses and with an ampersand appended before the last parentheses.<br />
<br />
For example, if the saved layout contained three {{ic|uxterm}} windows:<br />
<br />
{{hc|head=~/load_layout.sh|output=<br />
#!/bin/bash<br />
<br />
# First we append the saved layout of worspace N to workspace M<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
<br />
# And finally we fill the containers with the programs they had<br />
(uxterm &)<br />
(uxterm &)<br />
(uxterm &)<br />
}}<br />
<br />
Then set the file as executable:<br />
<br />
chmod u+x ~/load_layout.sh<br />
<br />
And finally, the layout of worskpace N can be loaded onto to workspace M by running:<br />
<br />
~/load_layout.sh<br />
<br />
{{tip|Adding {{ic|bindsym $mod+g exec ~/load_layout.sh}} to {{ic|~/.i3/config}} and restarting i3 will bind Mod+g to run the above script.}}<br />
<br />
{{note|If the above script does not work properly, refer to the [http://i3wm.org/docs/layout-saving.html#_editing_layout_files official documentation]. The ''swallows'' sections of {{ic|~/.i3/workspace_N.json}} needs to be manually edited.}}<br />
<br />
=== Scratchpad containers ===<br />
<br />
By default, [http://i3wm.org/docs/userguide.html#_scratchpad scratchpads] only contain a single window. However, containers can also be made a scratchpad.<br />
<br />
Create a new container (for example, {{ic|Mod+Enter}}), split it ({{ic|Mod+v}}) and create another container. Focus the parent ({{ic|Mod+a}}), split in the opposite direction ({{ic|Mod+h}}), and create again. <br />
<br />
Focus the first container (with focus parent as needed), make the window floating ({{ic|Mod+Shift+Space}}), and move it to the scratchpad ({{ic|Mod+Shift+-}}). You can now split containers to preference.<br />
<br />
{{Note|Containers cannot be resized individually in floating windows. Resize the containers before making windows floating.}}<br />
{{Tip|When only using terminal applications, consider a multiplexer such as [[tmux]] instead.}}<br />
<br />
See also [https://faq.i3wm.org/question/138/multiple-scratchpad/i3] for multiple scratchpads.<br />
<br />
=== Screensaver and power management ===<br />
<br />
You can use [[DPMS]] to blank your screen or to suspend/poweroff your monitor. Adding the following line to your {{ic|~/.config/i3/config}} will suspend your monitor after 10 minutes.<br />
<br />
exec --no-startup-id xset dpms 600<br />
<br />
With {{AUR|xss-lock-git}} you can register a screenlocker for your i3 session. xss-lock subscribes to the systemd-events {{ic|suspend}}, {{ic|hibernate}}, {{ic|lock-session}}, and {{ic|unlock-session}} with appropriate actions (run locker and wait for user to unlock or kill locker). It also reacts to the [[Display Power Management Signaling#xset screen-saver control|X screensaver]] and runs or kills the locker in response to the x-server signals. Start xss-lock in your autostart like this:<br />
<br />
xss-lock -- i3lock -i /path/to/background_image.png &<br />
<br />
Additionally, you can use {{Pkg|xautolock}} to lock the screen after a given time period:<br />
<br />
xautolock -time 10 -locker "i3lock -i /path/to/background_image.png" &<br />
<br />
See also [[#Shutdown, reboot, lock screen]] and [[Pm-utils#Creating your own hooks]].<br />
<br />
=== Shutdown, reboot, lock screen ===<br />
<br />
As there are no Shutdown, Reboot, or Lock Screen buttons, we can add some hotkey combinations to help us out. The below assumes you have {{Pkg|polkit}} installed to allow unprivileged users to run [[systemd#Power_management|power management]] commands.<br />
<br />
Add the following lines to your {{ic|~/.config/i3/config}} Once completed you will be presented with a prompt whenever you press {{ic|$mod+pause}}.<br />
<br />
{{bc|<br />
# Add a small delay to prevent suspend races<br />
# https://bugs.launchpad.net/ubuntu/+source/unity-2d/+bug/830348<br />
set $Locker i3lock && sleep 1<br />
<br />
set $mode_system System (l) lock, (e) logout, (s) suspend, (h) hibernate, (r) reboot, (Shift+s) shutdown<br />
mode "$mode_system" {<br />
bindsym l exec --no-startup-id $Locker, mode "default"<br />
bindsym e exec --no-startup-id i3-msg exit, mode "default"<br />
bindsym s exec --no-startup-id $Locker && systemctl suspend, mode "default"<br />
bindsym h exec --no-startup-id $Locker && systemctl hibernate, mode "default"<br />
bindsym r exec --no-startup-id systemctl reboot, mode "default"<br />
bindsym Shift+s exec --no-startup-id systemctl poweroff, mode "default" <br />
<br />
# back to normal: Enter or Escape<br />
bindsym Return mode "default"<br />
bindsym Escape mode "default"<br />
}<br />
<br />
bindsym $mod+Pause mode "$mode_system"<br />
}}<br />
<br />
{{Note|<br />
* If you use {{AUR|xss-lock-git}}, call {{ic|xset s activate}} to start the locker. With {{Pkg|xautolock}} the command is {{ic|xautolock -locknow}}<br />
* You can use a separate script for more complex behaviour, and refer to it in the mode. See [https://gist.github.com/anonymous/c8cd0a59bf4acb273068] for an example.<br />
}}<br />
<br />
For a list of alternative screen lockers, see [[List of applications/Security#Screen lockers]].<br />
<br />
=== Tabbed or stacked web-browsing ===<br />
<br />
Some web-browsers intentionally do not implement tabs, since managing tabs is considered to be the task of the window manager, not the task of the browser.<br />
<br />
To let i3 manage your tab-less web-browser, in this example for [[uzbl]], add the following line to your {{ic|~/.config/i3/config}}<br />
<br />
for_window [class="Uzbl-core"] focus child, layout stacking, focus<br />
<br />
This is for stacked web browsing, meaning that the windows will be shown vertically. The advantage over tabbed browsing is that the window-titles are fully visible, even if a lot of browser windows are open.<br />
<br />
If you prefer tabbed browsing, with windows in horizontal direction ('tabs'), use<br />
<br />
for_window [class="Uzbl-core"] focus child, layout tabbed, focus<br />
<br />
=== Workspace variables ===<br />
<br />
As workspaces are defined multiple times in i3, assigning workspace variables can be helpful. For example [https://github.com/dkeg/bloat2.0/blob/master/i3config#L55]:<br />
<br />
set $WS1 term<br />
set $WS2 web<br />
set $WS3 misc<br />
set $WS4 media<br />
set $WS5 code<br />
<br />
Then replace workspace names with their matching variables:<br />
<br />
bindsym $mod+1 workspace $WS1<br />
...<br />
bindsym $mod+Shift+1 move container to workspace $WS1<br />
<br />
See [http://i3wm.org/docs/userguide.html#_changing_named_workspaces_moving_to_workspaces Changing named workspaces] for more information.<br />
<br />
=== Correct handling of floating dialogs ===<br />
<br />
While dialogs should open in floating mode by default [http://i3wm.org/docs/userguide.html#_floating], many still open in tiling mode. To change this behaviour, check the dialog's {{ic|WM_WINDOW_ROLE}} with {{pkg|xorg-xprop}} and add the correct rules to {{ic|~/.i3/config}}:<br />
<br />
for_window [window_role="pop-up"] floating enable<br />
for_window [window_role="task_dialog"] floating enable<br />
<br />
You can also use title rules and regular expressions:<br />
<br />
for_window [title="Preferences$"] floating enable<br />
<br />
or {{ic|WM_CLASS}}:<br />
<br />
for_window [class="(?i)mplayer"] floating enable<br />
<br />
=== Network Download/Upload speed on statusbar ===<br />
<br />
You might adapt this upstream [http://code.stapelberg.de/git/i3status/tree/contrib/measure-net-speed.bash script]. For that,<br />
<br />
* rename both network cards according to your system (use {{ic|ip addr}})<br />
* find them on {{ic|/sys/devices}} then replace them appropriately:<br />
$ find /sys/devices -name ''network_interface''<br />
<br />
{{Tip|Use {{ic|/sys/class/net/''interface''/statistics/}} to not depend on PCI location.}}<br />
<br />
Now, just save the script in a suitable place (for example {{ic|~/.config/i3}}) and point your status program to it.<br />
<br />
== Patches ==<br />
<br />
Packages with patches not merged upstream are available in the [[AUR]]:<br />
<br />
* {{App|i3bar-icons-git|Display XBM icons in i3bar|https://github.com/ashinkarov/i3-extras|{{AUR|i3bar-icons-git}}}}<br />
* {{App|i3-mouse-close|Middle-click close support|https://faq.i3wm.org/question/550/manipulating-windows-with-the-mouse|{{AUR|i3-mouse-close}}}}<br />
* {{App|i3-smart-border|Smart borders|https://github.com/ashinkarov/i3-extras|{{AUR|i3-smart-border}}}}<br />
* {{App|i3-wm-iconpatch|Titlebar icon support|https://github.com/ashinkarov/i3-extras|{{AUR|i3-wm-iconpatch}}}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== General ===<br />
<br />
{{Expansion|Official debugging instructions may not work as expected, so expand on this topic}}<br />
<br />
In many cases, bugs are fixed in the development version {{AUR|i3-git}} (from the [[AUR]]) and upstream will ask to reproduce any errors with this version. [http://i3wm.org/docs/debugging.html] <br />
<br />
{{Warning|Debugging symbols are removed in the AUR package. See [[Debug - Getting Traces#General]] before sending backtraces upstream.}}<br />
<br />
=== Buttons in the i3 message bar do not work ===<br />
<br />
Buttons such as "Edit config" in {{ic|i3-msg}} call {{ic|i3-sensible-terminal}}, so make sure your [[I3#Terminal_emulator|Terminal emulator]] is recognized by i3.<br />
<br />
=== Faulty line wraps in tiled terminals ===<br />
<br />
i3 v4.3 and higher ignore size increment hints for tiled windows [https://www.mail-archive.com/i3-discuss@i3.zekjur.net/msg00709.html]. This may cause terminals to wrap lines prematurely, amongst other issues. As a workaround, make the offending window floating, before tiling it again.<br />
<br />
=== Mouse cursor remains in waiting mode ===<br />
<br />
When starting a script or application which does not support startup notifications, the mouse cursor will remain in busy/watch/clock mode for 60 seconds.<br />
<br />
To solve this for a particlar application, use the {{ic|--no-startup-id}} parameter, for example:<br />
exec --no-startup-id ~/script<br />
bindsym $mod+d exec --no-startup-id dmenu_run<br />
<br />
To disable this animation globally, see [[Cursor themes#Create_links_to_missing_cursors]].<br />
<br />
=== Unresponsive key bindings ===<br />
<br />
Some tools such as [[Taking_a_screenshot#scrot|scrot]] may not work when used with a regular key binding (executed after key press). In those cases, execute commands after key release with the {{ic|--release}} argument[http://i3wm.org/docs/userguide.html#keybindings]:<br />
<br />
bindsym --release Print exec --no-startup-id scrot '%Y-%m-%d$<br />
bindsym --release Shift+Print exec --no-startup-id scrot '%Y$<br />
<br />
=== Tearing ===<br />
<br />
i3 does [http://bugs.i3wm.org/report/ticket/661 not properly implement double buffering] hence tearing or flickering may occur. In case of problems, try using a [[Xorg#List_of_composite_managers|composite manager]].<br />
<br />
== See also ==<br />
<br />
* [http://i3wm.org Official website]<br />
* [http://www.funtoo.org/I3_Tiling_Window_Manager funtoo Wiki]<br />
* [http://code.stapelberg.de/git/i3 i3 Source code]<br />
* [https://github.com/ashinkarov/i3-extras i3-extras] - Collection of scripts and patches<br />
* [https://github.com/acrisci/i3ipc-glib i3ipc-glib] - A library for i3 extensions<br />
* [http://www.j4tools.org/ j4tools] - non-official tools designed to work with i3<br />
<br />
'''Arch Linux Forums'''<br />
* [https://bbs.archlinux.org/viewtopic.php?id=99064 The i3 thread] - A general discussion about i3<br />
* [https://bbs.archlinux.org/viewtopic.php?id=103369 i3 desktop screenshots and config sharing]<br />
<br />
'''Screencasts'''<br />
* [http://www.youtube.com/watch?v=Wx0eNaGzAZU i3 window manager v4.1 screencast]</div>PhilippDhttps://wiki.archlinux.org/index.php?title=Cron&diff=356814Cron2015-01-17T12:10:59Z<p>PhilippD: /* Anacron */ Added useful command to test /etc/anacrontab after editing.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Daemons and system services]]<br />
[[de:Cron]]<br />
[[fr:Cron]]<br />
[[ja:Cron]]<br />
[[ko:Cron]]<br />
[[sk:Cron]]<br />
[[zh-CN:Cron]]<br />
{{Related articles start}}<br />
{{Related|systemd/Timers}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Cron|Wikipedia]]:<br />
<br />
'''''cron''' is the time-based job scheduler in Unix-like computer operating systems. cron enables users to schedule jobs (commands or shell scripts) to run periodically at certain times or dates. It is commonly used to automate system maintenance or administration.''<br />
<br />
== Installation ==<br />
<br />
There are many cron implementations, but none of them are installed by default as the base system uses [[systemd/Timers]] instead. See the Gentoo's [http://www.gentoo.org/doc/en/cron-guide.xml cron guide], which offers comparisons.<br />
<br />
Packages available in [[official repositories]]:<br />
<br />
* {{Pkg|cronie}}<br />
* {{Pkg|fcron}}<br />
<br />
Packages available in [[AUR]]:<br />
<br />
* {{AUR|bcron}}<br />
* {{AUR|dcron}}<br />
* {{AUR|vixie-cron}}<br />
<br />
== Configuration ==<br />
<br />
=== Activation and autostart ===<br />
<br />
After installation, the daemon will not be enabled by default. The installed package likely provides a service, which can be controlled by [[systemd#Using units|systemctl]]. For example, to start and enable ''cronie'':<br />
<br />
# systemctl start cronie<br />
# systemctl enable cronie<br />
<br />
Check {{ic|/etc/cron.daily/}} and similar directories to see which jobs are present. Activating cron service will trigger all of them.<br />
<br />
{{Note|''cronie'' provides the {{ic|0anacron}} ''hourly'' job, which allows for [[#Asynchronous job processing|delayed runs of other jobs]] e.g. if the computer was switched off at the moment of standard execution.}}<br />
<br />
=== Handling errors of jobs ===<br />
<br />
cron registers the output from ''stdout'' and ''stderr'' and attempts to send it as email to the user's spools via the {{ic|sendmail}} command. Cronie disables mail output if {{ic|/usr/bin/sendmail}} is not found. To log these messages use the {{ic|-m}} option and write a script or install a rudimentary SMTP subsystem.<br />
<br />
# [[Systemd#Editing_provided_unit_files|Edit]] the {{ic|cronie.service}} unit.<br />
# Install {{Pkg|esmtp}}, [[msmtp]], {{Pkg|opensmtpd}} or write a custom script.<br />
<br />
==== Example with msmtp ====<br />
<br />
{{Expansion|How exactly do I ''make sure it detects the new {{ic|sendmail}} command''?}}<br />
<br />
Install {{Pkg|msmtp-mta}} which creates a symbolic link from {{ic|/usr/bin/sendmail}} to {{ic|/usr/bin/msmtp}}. Restart {{ic|cronie}} to make sure it detects the new {{ic|sendmail}} command. You must then provide a way for {{ic|msmtp}} to convert your username into an email address.<br />
<br />
Then either add {{ic|MAILTO}} line to your crontab, like so:<br />
<br />
<nowiki>MAILTO=your@email.com</nowiki><br />
<br />
'''or''' create {{ic|/etc/msmtprc}} and append this line:<br />
<br />
aliases /etc/aliases<br />
<br />
and create {{ic|/etc/aliases}}: <br />
<br />
your_username: your@email.com<br />
# Optional:<br />
default: your@email.com<br />
<br />
Then [[Systemd#Editing_provided_unit_files|modify the configuration]] of ''cronie'' daemon by replacing the {{ic|ExecStart}} command with:<br />
<br />
ExecStart=/usr/bin/crond -n -m '/usr/bin/msmtp -t'<br />
<br />
==== Example with esmtp ====<br />
<br />
Install {{Pkg|esmtp}} and {{Pkg|procmail}}.<br />
<br />
After installation configure the routing:<br />
{{hc|/etc/esmtprc|<br />
identity ''myself''@myisp.com<br />
hostname mail.myisp.com:25<br />
username ''"myself"''<br />
password ''"secret"''<br />
starttls enabled<br />
default<br />
mda "/usr/bin/procmail -d %T"<br />
}}<br />
<br />
Procmail needs root privileges to work in delivery mode but it is not an issue if you are running the cronjobs as root anyway.<br />
<br />
To test that everything works correctly, create a file {{ic|message.txt}} with {{ic|"test message"}} in it. <br />
<br />
From the same directory run:<br />
<br />
$ sendmail ''user_name'' < message.txt <br />
<br />
then:<br />
<br />
$ cat /var/spool/mail/''user_name''<br />
<br />
You should now see the test message and the time and date it was sent.<br />
<br />
The error output of all jobs will now be redirected to {{ic|/var/spool/mail/''user_name''}}.<br />
<br />
Due to the privileged issue, it is hard to create and send emails to root (e.g. {{ic|su -c ""}}). You can ask {{ic|esmtp}} to forward all root's email to an ordinary user with:<br />
{{hc|/etc/esmtprc|<br />
2=force_mda="''user-name''"<br />
}}<br />
<br />
{{Note|If the above test didn't work, you may try creating a local configuration in {{ic|~/.esmtprc}} with the same content.<br />
<br />
Run the following command to make sure it has the correct permission: <br />
<br />
$ chmod 710 ~/.esmtprc<br />
<br />
Then repeat the test with {{ic|message.txt}} exactly as before.}}<br />
<br />
==== Example with opensmtpd ====<br />
<br />
Install {{Pkg|opensmtpd}}.<br />
<br />
Edit {{ic|/etc/smtpd/smtpd.conf}}. The following configuration allows for local delivery:<br />
<br />
listen on localhost<br />
accept for local deliver to mbox<br />
<br />
You can proceed to test it:<br />
# systemctl start smtpd<br />
$ echo test | sendmail user<br />
<br />
''user'' can check his/her mail in with any [[:Category:Email clients|reader]] able to handle mbox format, or just have a look at the file {{ic|/var/spool/mail/''user''}}. If everything goes as expected, you can enable opensmtpd for future boots:<br />
# systemctl enable smtpd<br />
<br />
This approach has the advantage of not sending local cron notifications to a remote server. Not even network connection is needed. On the downside, you need a new daemon running.<br />
<br />
{{Note|<br />
* At the moment of writing the Arch opensmtpd package does not create all needed directories under {{ic|/var/spool/smtpd}}, but the daemon will warn about that specifying the required ownerships and permissions. Just create them as suggested.<br />
* Even though the suggested configuration does not accept remote connections, it's a healthy precaution to add an additional layer of security blocking port 25 with [[iptables]] or similar.<br />
}}<br />
<br />
==== Long cron job ====<br />
<br />
Suppose this program is invoked by cron :<br />
<br />
#!/bin/sh<br />
echo "I had a recoverable error!"<br />
sleep 1h<br />
<br />
What happens is this:<br />
# cron runs the script<br />
# as soon as cron sees some output, it runs your MTA, and provides it with the headers. It leaves the pipe open, because the job hasn't finished and there might be more output.<br />
# the MTA opens the connection to postfix and leaves that connection open while it waits for the rest of the body.<br />
# postfix closes the idle connection after less than an hour and you get an error like this :<br />
smtpmsg='421 … Error: timeout exceeded' errormsg='the server did not accept the mail'<br />
<br />
To solve this problem you can use the command chronic or sponge from {{Pkg|moreutils}}.<br />
From their respective man page:<br />
; chronic: chronic runs a command, and arranges for its standard out and standard error to only be displayed if the command fails (exits nonzero or crashes). If the command succeeds, any extraneous output will be hidden.<br />
; sponge: sponge reads standard input and writes it out to the specified file. Unlike a shell redirect, sponge soaks up all its input before opening the output file… If no output file is specified, sponge outputs to stdout.<br />
<br />
Even if it's not said chronic buffer the command output before opening its standard output (like sponge does).<br />
<br />
== Crontab format ==<br />
<br />
The basic format for a crontab is:<br />
<br />
''minute'' ''hour'' ''day_of_month'' ''month'' ''day_of_week'' ''command''<br />
<br />
* ''minute'' values can be from 0 to 59.<br />
* ''hour'' values can be from 0 to 23.<br />
* ''day_of_month'' values can be from 1 to 31.<br />
* ''month'' values can be from 1 to 12.<br />
* ''day_of_week'' values can be from 0 to 6, with 0 denoting Sunday.<br />
<br />
Multiple times may be specified with a comma, a range can be given with a hyphen, and the asterisk symbol is a wildcard character. Spaces are used to separate fields. For example, the line:<br />
<br />
*0,*5 9-16 * 1-5,9-12 1-5 ~/bin/i_love_cron.sh<br />
<br />
Will execute the script {{ic|i_love_cron.sh}} at five minute intervals from 9 AM to 4:55 PM on weekdays except during the summer months (June, July, and August). More examples and advanced configuration techniques can be found below.<br />
<br />
== Basic commands ==<br />
<br />
Crontabs should never be edited directly; instead, users should use the {{ic|crontab}} program to work with their crontabs. To be granted access to this command, user must be a member of the users group (see the {{ic|gpasswd}} command).<br />
<br />
To view their crontabs, users should issue the command:<br />
<br />
$ crontab -l<br />
<br />
To edit their crontabs, they may use:<br />
<br />
$ crontab -e<br />
<br />
{{Note|By default the {{ic|crontab}} command ueses the {{ic|vi}} editor. To change it, [[environment variable|export]] {{ic|EDITOR}} or {{ic|VISUAL}}, or specify the editor directly: {{ic|1=EDITOR=vim crontab -e}}.}}<br />
<br />
To remove their crontabs, they should use:<br />
<br />
$ crontab -r<br />
<br />
If a user has a saved crontab and would like to completely overwrite their old crontab, he or she should use:<br />
<br />
$ crontab ''saved_crontab_filename''<br />
<br />
To overwrite a crontab from the command line ([[Wikipedia:stdin]]), use<br />
<br />
$ crontab - <br />
<br />
To edit somebody else's crontab, issue the following command as root:<br />
<br />
# crontab -u ''username'' -e<br />
<br />
This same format (appending {{ic|-u ''username''}} to a command) works for listing and deleting crontabs as well.<br />
<br />
== Examples ==<br />
<br />
The entry:<br />
<br />
01 * * * * /bin/echo Hello, world!<br />
<br />
runs the command {{ic|/bin/echo Hello, world!}} on the first minute of every hour of every day of every month (i.e. at 12:01, 1:01, 2:01, etc.).<br />
<br />
Similarly:<br />
<br />
*/5 * * jan mon-fri /bin/echo Hello, world!<br />
<br />
runs the same job every five minutes on weekdays during the month of January (i.e. at 12:00, 12:05, 12:10, etc.).<br />
<br />
The line (as noted in "man 5 crontab"):<br />
<br />
*0,*5 9-16 * 1-5,9-12 1-5 /home/user/bin/i_love_cron.sh<br />
<br />
will execute the script {{Ic|i_love_cron.sh}} at five minute intervals from 9 AM to 5 PM (excluding 5 PM itself) every weekday (Mon-Fri) of every month except during the summer (June, July, and August).<br />
<br />
Periodical settings can also be entered as in this crontab template:<br />
<br />
<pre># Chronological table of program loadings <br />
# Edit with "crontab" for proper functionality, "man 5 crontab" for formatting<br />
# User: johndoe<br />
<br />
# mm hh DD MM W /path/progam [--option]... ( W = weekday: 0-6 [Sun=0] )<br />
21 01 * * * /usr/bin/systemctl hibernate<br />
@weekly $HOME/.local/bin/trash-empty<br />
</pre><br />
<br />
== Default editor ==<br />
<br />
To use an alternate default editor, define the {{ic|EDITOR}} environment variable in a shell initialization script as described in [[Environment variables]].<br />
<br />
As a regular user, {{ic|su}} will need to be used instead of {{ic|sudo}} for the environment variable to be pulled correctly:<br />
<br />
$ su -c "crontab -e"<br />
<br />
To have an alias to this {{ic|printf}} is required to carry the arbitrary string because {{ic|su}} launches in a new shell:<br />
<br />
alias scron="su -c $(printf "%q " "crontab -e")"<br />
<br />
== run-parts issue ==<br />
<br />
cronie uses {{ic|run-parts}} to carry out script in {{ic|cron.daily}}/{{ic|cron.weekly}}/{{ic|cron.monthly}}. Be careful that the script name in these won't include a dot (.), e.g. {{ic|backup.sh}}, since {{ic|run-parts}} without options will ignore them (see: {{ic|man run-parts}}).<br />
<br />
== Running X.org server-based applications ==<br />
<br />
Cron does not run under the X.org server therefore it cannot know the environmental variable necessary to be able to start an X.org server application so they will have to be defined. One can use a program like {{AUR|xuserrun}} to do it:<br />
<br />
17 02 * ... /usr/bin/xuserrun /usr/bin/xclock<br />
<br />
Or then can be defined manually ({{ic|echo $DISPLAY}} will give the current DISPLAY value):<br />
<br />
17 02 * ... env DISPLAY=:0 /usr/bin/xclock<br />
<br />
If done through say SSH, permission will need be given:<br />
<br />
# xhost +si:localuser:$(whoami)<br />
<br />
== Asynchronous job processing ==<br />
<br />
If you regularly turn off your computer but do not want to miss jobs, there are some solutions available (easiest to hardest):<br />
<br />
=== Cronie ===<br />
{{Pkg|cronie}} comes with anacron included.<br />
The project homepage reads:<br />
<br />
Cronie contains the standard UNIX daemon crond that runs specified programs at scheduled times and related tools.<br />
It is based on the original cron and has security and configuration enhancements like the ability to use pam and SELinux.<br />
<br />
=== Dcron ===<br />
<br />
Vanilla {{AUR|dcron}} supports asynchronous job processing. Just put it with @hourly, @daily, @weekly or @monthly with a jobname, like this:<br />
<br />
@hourly ID=greatest_ever_job echo This job is very useful.<br />
<br />
=== Cronwhip ===<br />
<br />
{{AUR|cronwhip}} is a script to automatically run missed cron jobs; it works with the former default cron implementation, ''dcron''.<br />
See also the [https://bbs.archlinux.org/viewtopic.php?id=57973 forum thread].<br />
<br />
=== Anacron ===<br />
Anacron is a full replacement for ''dcron'' which processes jobs asynchronously.<br />
It is provided by {{Pkg|cronie}}. The configuration file is {{ic|/etc/anacrontab}}. Information on the format can be found in the [[man page]].<br />
man anacrontab<br />
The following command tests {{ic|/etc/anacrontab}} for validity.<br />
anacron -T<br />
<br />
=== Fcron ===<br />
<br />
Like ''anacron'', {{Pkg|fcron}} assumes the computer is not always running and, unlike ''anacron'', it can schedule events at intervals shorter than a single day which may be useful for systems which suspend/hibernate regularly (such as a laptop). Like cronwhip, fcron can run jobs that should have been run during the computer's downtime.<br />
<br />
When replacing {{Pkg|cronie}} with fcron be aware the spool directory is {{ic|/var/spool/fcron}} and the {{ic|fcrontab}} command is used instead of ''crontab'' to edit the user crontabs. These crontabs are stored in a binary format with the text version next to them as ''foo''.orig in the spool directory. Any scripts which manually edit user crontabs may need to be adjusted due to this difference in behavior.<br />
<br />
A quick scriptlet which may aide in converting traditional user crontabs to fcron format:<br />
<br />
{{bc|<br />
cd /var/spool/cron && (<br />
for ctab in *; do<br />
fcrontab ${ctab} -u ${ctab}<br />
done<br />
)<br />
}}<br />
<br />
See also the [https://bbs.archlinux.org/viewtopic.php?id=140497 forum thread].<br />
<br />
== Ensuring exclusivity ==<br />
<br />
If you run potentially long-running jobs (e.g., a backup might all of a sudden run for a long time, because of many changes or a particular slow network connection), then {{AUR|lockrun}} can ensure that the cron job won't start a second time.<br />
<br />
5,35 * * * * /usr/bin/lockrun -n /tmp/lock.backup /root/make-backup.sh<br />
<br />
== Dcron ==<br />
<br />
The cron daemon parses a configuration file known as {{ic|crontab}}. Each user on the system can maintain a separate crontab file to schedule commands individually. The root user's crontab is used to schedule system-wide tasks (though users may opt to use {{ic|/etc/crontab}} or the {{ic|/etc/cron.d}} directory, depending on which cron implementation they choose).<br />
<br />
{{hc|/var/spool/cron/root<br />
|2=<nowiki><br />
# Run command at a scheduled time<br />
# Edit this 'crontab -e' for error checking, man 1 crontab for acceptable format<br />
<br />
# <@freq> <tags and command><br />
@hourly ID=sys-hourly /usr/sbin/run-cron /etc/cron.hourly<br />
@daily ID=sys-daily /usr/sbin/run-cron /etc/cron.daily<br />
@weekly ID=sys-weekly /usr/sbin/run-cron /etc/cron.weekly<br />
@monthly ID=sys-monthly /usr/sbin/run-cron /etc/cron.monthly<br />
<br />
# mm hh DD MM W /path/command (or tags) # W = week: 0-6, Sun=0<br />
21 01 * * * /usr/bin/systemctl suspend<br />
</nowiki>}}<br />
<br />
These lines exemplify one of the formats that crontab entries can have, namely whitespace-separated fields specifying:<br />
<br />
# @period<br />
# ID=jobname (this tag is specific to dcron)<br />
# command<br />
<br />
The other standard format for crontab entries is:<br />
<br />
# minute<br />
# hour<br />
# day<br />
# month<br />
# day of week<br />
# command<br />
<br />
The crontab files themselves are usually stored as {{ic|/var/spool/cron/username}}. For example, root's crontab is found at {{ic|/var/spool/cron/root}}<br />
<br />
See the crontab [[man page]] for further information and configuration examples.<br />
<br />
== See also ==<br />
<br />
* [http://www.gentoo.org/doc/en/cron-guide.xml Gentoo Linux Cron Guide]</div>PhilippDhttps://wiki.archlinux.org/index.php?title=Cron&diff=356811Cron2015-01-17T12:04:06Z<p>PhilippD: /* Anacron */ Added information on how to add jobs to anacron.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Daemons and system services]]<br />
[[de:Cron]]<br />
[[fr:Cron]]<br />
[[ja:Cron]]<br />
[[ko:Cron]]<br />
[[sk:Cron]]<br />
[[zh-CN:Cron]]<br />
{{Related articles start}}<br />
{{Related|systemd/Timers}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Cron|Wikipedia]]:<br />
<br />
'''''cron''' is the time-based job scheduler in Unix-like computer operating systems. cron enables users to schedule jobs (commands or shell scripts) to run periodically at certain times or dates. It is commonly used to automate system maintenance or administration.''<br />
<br />
== Installation ==<br />
<br />
There are many cron implementations, but none of them are installed by default as the base system uses [[systemd/Timers]] instead. See the Gentoo's [http://www.gentoo.org/doc/en/cron-guide.xml cron guide], which offers comparisons.<br />
<br />
Packages available in [[official repositories]]:<br />
<br />
* {{Pkg|cronie}}<br />
* {{Pkg|fcron}}<br />
<br />
Packages available in [[AUR]]:<br />
<br />
* {{AUR|bcron}}<br />
* {{AUR|dcron}}<br />
* {{AUR|vixie-cron}}<br />
<br />
== Configuration ==<br />
<br />
=== Activation and autostart ===<br />
<br />
After installation, the daemon will not be enabled by default. The installed package likely provides a service, which can be controlled by [[systemd#Using units|systemctl]]. For example, to start and enable ''cronie'':<br />
<br />
# systemctl start cronie<br />
# systemctl enable cronie<br />
<br />
Check {{ic|/etc/cron.daily/}} and similar directories to see which jobs are present. Activating cron service will trigger all of them.<br />
<br />
{{Note|''cronie'' provides the {{ic|0anacron}} ''hourly'' job, which allows for [[#Asynchronous job processing|delayed runs of other jobs]] e.g. if the computer was switched off at the moment of standard execution.}}<br />
<br />
=== Handling errors of jobs ===<br />
<br />
cron registers the output from ''stdout'' and ''stderr'' and attempts to send it as email to the user's spools via the {{ic|sendmail}} command. Cronie disables mail output if {{ic|/usr/bin/sendmail}} is not found. To log these messages use the {{ic|-m}} option and write a script or install a rudimentary SMTP subsystem.<br />
<br />
# [[Systemd#Editing_provided_unit_files|Edit]] the {{ic|cronie.service}} unit.<br />
# Install {{Pkg|esmtp}}, [[msmtp]], {{Pkg|opensmtpd}} or write a custom script.<br />
<br />
==== Example with msmtp ====<br />
<br />
{{Expansion|How exactly do I ''make sure it detects the new {{ic|sendmail}} command''?}}<br />
<br />
Install {{Pkg|msmtp-mta}} which creates a symbolic link from {{ic|/usr/bin/sendmail}} to {{ic|/usr/bin/msmtp}}. Restart {{ic|cronie}} to make sure it detects the new {{ic|sendmail}} command. You must then provide a way for {{ic|msmtp}} to convert your username into an email address.<br />
<br />
Then either add {{ic|MAILTO}} line to your crontab, like so:<br />
<br />
<nowiki>MAILTO=your@email.com</nowiki><br />
<br />
'''or''' create {{ic|/etc/msmtprc}} and append this line:<br />
<br />
aliases /etc/aliases<br />
<br />
and create {{ic|/etc/aliases}}: <br />
<br />
your_username: your@email.com<br />
# Optional:<br />
default: your@email.com<br />
<br />
Then [[Systemd#Editing_provided_unit_files|modify the configuration]] of ''cronie'' daemon by replacing the {{ic|ExecStart}} command with:<br />
<br />
ExecStart=/usr/bin/crond -n -m '/usr/bin/msmtp -t'<br />
<br />
==== Example with esmtp ====<br />
<br />
Install {{Pkg|esmtp}} and {{Pkg|procmail}}.<br />
<br />
After installation configure the routing:<br />
{{hc|/etc/esmtprc|<br />
identity ''myself''@myisp.com<br />
hostname mail.myisp.com:25<br />
username ''"myself"''<br />
password ''"secret"''<br />
starttls enabled<br />
default<br />
mda "/usr/bin/procmail -d %T"<br />
}}<br />
<br />
Procmail needs root privileges to work in delivery mode but it is not an issue if you are running the cronjobs as root anyway.<br />
<br />
To test that everything works correctly, create a file {{ic|message.txt}} with {{ic|"test message"}} in it. <br />
<br />
From the same directory run:<br />
<br />
$ sendmail ''user_name'' < message.txt <br />
<br />
then:<br />
<br />
$ cat /var/spool/mail/''user_name''<br />
<br />
You should now see the test message and the time and date it was sent.<br />
<br />
The error output of all jobs will now be redirected to {{ic|/var/spool/mail/''user_name''}}.<br />
<br />
Due to the privileged issue, it is hard to create and send emails to root (e.g. {{ic|su -c ""}}). You can ask {{ic|esmtp}} to forward all root's email to an ordinary user with:<br />
{{hc|/etc/esmtprc|<br />
2=force_mda="''user-name''"<br />
}}<br />
<br />
{{Note|If the above test didn't work, you may try creating a local configuration in {{ic|~/.esmtprc}} with the same content.<br />
<br />
Run the following command to make sure it has the correct permission: <br />
<br />
$ chmod 710 ~/.esmtprc<br />
<br />
Then repeat the test with {{ic|message.txt}} exactly as before.}}<br />
<br />
==== Example with opensmtpd ====<br />
<br />
Install {{Pkg|opensmtpd}}.<br />
<br />
Edit {{ic|/etc/smtpd/smtpd.conf}}. The following configuration allows for local delivery:<br />
<br />
listen on localhost<br />
accept for local deliver to mbox<br />
<br />
You can proceed to test it:<br />
# systemctl start smtpd<br />
$ echo test | sendmail user<br />
<br />
''user'' can check his/her mail in with any [[:Category:Email clients|reader]] able to handle mbox format, or just have a look at the file {{ic|/var/spool/mail/''user''}}. If everything goes as expected, you can enable opensmtpd for future boots:<br />
# systemctl enable smtpd<br />
<br />
This approach has the advantage of not sending local cron notifications to a remote server. Not even network connection is needed. On the downside, you need a new daemon running.<br />
<br />
{{Note|<br />
* At the moment of writing the Arch opensmtpd package does not create all needed directories under {{ic|/var/spool/smtpd}}, but the daemon will warn about that specifying the required ownerships and permissions. Just create them as suggested.<br />
* Even though the suggested configuration does not accept remote connections, it's a healthy precaution to add an additional layer of security blocking port 25 with [[iptables]] or similar.<br />
}}<br />
<br />
==== Long cron job ====<br />
<br />
Suppose this program is invoked by cron :<br />
<br />
#!/bin/sh<br />
echo "I had a recoverable error!"<br />
sleep 1h<br />
<br />
What happens is this:<br />
# cron runs the script<br />
# as soon as cron sees some output, it runs your MTA, and provides it with the headers. It leaves the pipe open, because the job hasn't finished and there might be more output.<br />
# the MTA opens the connection to postfix and leaves that connection open while it waits for the rest of the body.<br />
# postfix closes the idle connection after less than an hour and you get an error like this :<br />
smtpmsg='421 … Error: timeout exceeded' errormsg='the server did not accept the mail'<br />
<br />
To solve this problem you can use the command chronic or sponge from {{Pkg|moreutils}}.<br />
From their respective man page:<br />
; chronic: chronic runs a command, and arranges for its standard out and standard error to only be displayed if the command fails (exits nonzero or crashes). If the command succeeds, any extraneous output will be hidden.<br />
; sponge: sponge reads standard input and writes it out to the specified file. Unlike a shell redirect, sponge soaks up all its input before opening the output file… If no output file is specified, sponge outputs to stdout.<br />
<br />
Even if it's not said chronic buffer the command output before opening its standard output (like sponge does).<br />
<br />
== Crontab format ==<br />
<br />
The basic format for a crontab is:<br />
<br />
''minute'' ''hour'' ''day_of_month'' ''month'' ''day_of_week'' ''command''<br />
<br />
* ''minute'' values can be from 0 to 59.<br />
* ''hour'' values can be from 0 to 23.<br />
* ''day_of_month'' values can be from 1 to 31.<br />
* ''month'' values can be from 1 to 12.<br />
* ''day_of_week'' values can be from 0 to 6, with 0 denoting Sunday.<br />
<br />
Multiple times may be specified with a comma, a range can be given with a hyphen, and the asterisk symbol is a wildcard character. Spaces are used to separate fields. For example, the line:<br />
<br />
*0,*5 9-16 * 1-5,9-12 1-5 ~/bin/i_love_cron.sh<br />
<br />
Will execute the script {{ic|i_love_cron.sh}} at five minute intervals from 9 AM to 4:55 PM on weekdays except during the summer months (June, July, and August). More examples and advanced configuration techniques can be found below.<br />
<br />
== Basic commands ==<br />
<br />
Crontabs should never be edited directly; instead, users should use the {{ic|crontab}} program to work with their crontabs. To be granted access to this command, user must be a member of the users group (see the {{ic|gpasswd}} command).<br />
<br />
To view their crontabs, users should issue the command:<br />
<br />
$ crontab -l<br />
<br />
To edit their crontabs, they may use:<br />
<br />
$ crontab -e<br />
<br />
{{Note|By default the {{ic|crontab}} command ueses the {{ic|vi}} editor. To change it, [[environment variable|export]] {{ic|EDITOR}} or {{ic|VISUAL}}, or specify the editor directly: {{ic|1=EDITOR=vim crontab -e}}.}}<br />
<br />
To remove their crontabs, they should use:<br />
<br />
$ crontab -r<br />
<br />
If a user has a saved crontab and would like to completely overwrite their old crontab, he or she should use:<br />
<br />
$ crontab ''saved_crontab_filename''<br />
<br />
To overwrite a crontab from the command line ([[Wikipedia:stdin]]), use<br />
<br />
$ crontab - <br />
<br />
To edit somebody else's crontab, issue the following command as root:<br />
<br />
# crontab -u ''username'' -e<br />
<br />
This same format (appending {{ic|-u ''username''}} to a command) works for listing and deleting crontabs as well.<br />
<br />
== Examples ==<br />
<br />
The entry:<br />
<br />
01 * * * * /bin/echo Hello, world!<br />
<br />
runs the command {{ic|/bin/echo Hello, world!}} on the first minute of every hour of every day of every month (i.e. at 12:01, 1:01, 2:01, etc.).<br />
<br />
Similarly:<br />
<br />
*/5 * * jan mon-fri /bin/echo Hello, world!<br />
<br />
runs the same job every five minutes on weekdays during the month of January (i.e. at 12:00, 12:05, 12:10, etc.).<br />
<br />
The line (as noted in "man 5 crontab"):<br />
<br />
*0,*5 9-16 * 1-5,9-12 1-5 /home/user/bin/i_love_cron.sh<br />
<br />
will execute the script {{Ic|i_love_cron.sh}} at five minute intervals from 9 AM to 5 PM (excluding 5 PM itself) every weekday (Mon-Fri) of every month except during the summer (June, July, and August).<br />
<br />
Periodical settings can also be entered as in this crontab template:<br />
<br />
<pre># Chronological table of program loadings <br />
# Edit with "crontab" for proper functionality, "man 5 crontab" for formatting<br />
# User: johndoe<br />
<br />
# mm hh DD MM W /path/progam [--option]... ( W = weekday: 0-6 [Sun=0] )<br />
21 01 * * * /usr/bin/systemctl hibernate<br />
@weekly $HOME/.local/bin/trash-empty<br />
</pre><br />
<br />
== Default editor ==<br />
<br />
To use an alternate default editor, define the {{ic|EDITOR}} environment variable in a shell initialization script as described in [[Environment variables]].<br />
<br />
As a regular user, {{ic|su}} will need to be used instead of {{ic|sudo}} for the environment variable to be pulled correctly:<br />
<br />
$ su -c "crontab -e"<br />
<br />
To have an alias to this {{ic|printf}} is required to carry the arbitrary string because {{ic|su}} launches in a new shell:<br />
<br />
alias scron="su -c $(printf "%q " "crontab -e")"<br />
<br />
== run-parts issue ==<br />
<br />
cronie uses {{ic|run-parts}} to carry out script in {{ic|cron.daily}}/{{ic|cron.weekly}}/{{ic|cron.monthly}}. Be careful that the script name in these won't include a dot (.), e.g. {{ic|backup.sh}}, since {{ic|run-parts}} without options will ignore them (see: {{ic|man run-parts}}).<br />
<br />
== Running X.org server-based applications ==<br />
<br />
Cron does not run under the X.org server therefore it cannot know the environmental variable necessary to be able to start an X.org server application so they will have to be defined. One can use a program like {{AUR|xuserrun}} to do it:<br />
<br />
17 02 * ... /usr/bin/xuserrun /usr/bin/xclock<br />
<br />
Or then can be defined manually ({{ic|echo $DISPLAY}} will give the current DISPLAY value):<br />
<br />
17 02 * ... env DISPLAY=:0 /usr/bin/xclock<br />
<br />
If done through say SSH, permission will need be given:<br />
<br />
# xhost +si:localuser:$(whoami)<br />
<br />
== Asynchronous job processing ==<br />
<br />
If you regularly turn off your computer but do not want to miss jobs, there are some solutions available (easiest to hardest):<br />
<br />
=== Cronie ===<br />
{{Pkg|cronie}} comes with anacron included.<br />
The project homepage reads:<br />
<br />
Cronie contains the standard UNIX daemon crond that runs specified programs at scheduled times and related tools.<br />
It is based on the original cron and has security and configuration enhancements like the ability to use pam and SELinux.<br />
<br />
=== Dcron ===<br />
<br />
Vanilla {{AUR|dcron}} supports asynchronous job processing. Just put it with @hourly, @daily, @weekly or @monthly with a jobname, like this:<br />
<br />
@hourly ID=greatest_ever_job echo This job is very useful.<br />
<br />
=== Cronwhip ===<br />
<br />
{{AUR|cronwhip}} is a script to automatically run missed cron jobs; it works with the former default cron implementation, ''dcron''.<br />
See also the [https://bbs.archlinux.org/viewtopic.php?id=57973 forum thread].<br />
<br />
=== Anacron ===<br />
Anacron is a full replacement for ''dcron'' which processes jobs asynchronously.<br />
It is provided by {{Pkg|cronie}}. The configuration file is {{ic|/etc/anacrontab}}. Information on the format can be found in the [[man page]].<br />
man anacrontab<br />
<br />
=== Fcron ===<br />
<br />
Like ''anacron'', {{Pkg|fcron}} assumes the computer is not always running and, unlike ''anacron'', it can schedule events at intervals shorter than a single day which may be useful for systems which suspend/hibernate regularly (such as a laptop). Like cronwhip, fcron can run jobs that should have been run during the computer's downtime.<br />
<br />
When replacing {{Pkg|cronie}} with fcron be aware the spool directory is {{ic|/var/spool/fcron}} and the {{ic|fcrontab}} command is used instead of ''crontab'' to edit the user crontabs. These crontabs are stored in a binary format with the text version next to them as ''foo''.orig in the spool directory. Any scripts which manually edit user crontabs may need to be adjusted due to this difference in behavior.<br />
<br />
A quick scriptlet which may aide in converting traditional user crontabs to fcron format:<br />
<br />
{{bc|<br />
cd /var/spool/cron && (<br />
for ctab in *; do<br />
fcrontab ${ctab} -u ${ctab}<br />
done<br />
)<br />
}}<br />
<br />
See also the [https://bbs.archlinux.org/viewtopic.php?id=140497 forum thread].<br />
<br />
== Ensuring exclusivity ==<br />
<br />
If you run potentially long-running jobs (e.g., a backup might all of a sudden run for a long time, because of many changes or a particular slow network connection), then {{AUR|lockrun}} can ensure that the cron job won't start a second time.<br />
<br />
5,35 * * * * /usr/bin/lockrun -n /tmp/lock.backup /root/make-backup.sh<br />
<br />
== Dcron ==<br />
<br />
The cron daemon parses a configuration file known as {{ic|crontab}}. Each user on the system can maintain a separate crontab file to schedule commands individually. The root user's crontab is used to schedule system-wide tasks (though users may opt to use {{ic|/etc/crontab}} or the {{ic|/etc/cron.d}} directory, depending on which cron implementation they choose).<br />
<br />
{{hc|/var/spool/cron/root<br />
|2=<nowiki><br />
# Run command at a scheduled time<br />
# Edit this 'crontab -e' for error checking, man 1 crontab for acceptable format<br />
<br />
# <@freq> <tags and command><br />
@hourly ID=sys-hourly /usr/sbin/run-cron /etc/cron.hourly<br />
@daily ID=sys-daily /usr/sbin/run-cron /etc/cron.daily<br />
@weekly ID=sys-weekly /usr/sbin/run-cron /etc/cron.weekly<br />
@monthly ID=sys-monthly /usr/sbin/run-cron /etc/cron.monthly<br />
<br />
# mm hh DD MM W /path/command (or tags) # W = week: 0-6, Sun=0<br />
21 01 * * * /usr/bin/systemctl suspend<br />
</nowiki>}}<br />
<br />
These lines exemplify one of the formats that crontab entries can have, namely whitespace-separated fields specifying:<br />
<br />
# @period<br />
# ID=jobname (this tag is specific to dcron)<br />
# command<br />
<br />
The other standard format for crontab entries is:<br />
<br />
# minute<br />
# hour<br />
# day<br />
# month<br />
# day of week<br />
# command<br />
<br />
The crontab files themselves are usually stored as {{ic|/var/spool/cron/username}}. For example, root's crontab is found at {{ic|/var/spool/cron/root}}<br />
<br />
See the crontab [[man page]] for further information and configuration examples.<br />
<br />
== See also ==<br />
<br />
* [http://www.gentoo.org/doc/en/cron-guide.xml Gentoo Linux Cron Guide]</div>PhilippD