https://wiki.archlinux.org/api.php?action=feedcontributions&user=Pgoetz&feedformat=atomArchWiki - User contributions [en]2024-03-29T07:37:01ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=InfiniBand&diff=804758InfiniBand2024-03-27T20:34:23Z<p>Pgoetz: /* Overview */ Updated the vendor attribution.</p>
<hr />
<div>[[Category:Networking]]<br />
[[ja:InfiniBand]]<br />
This page explains how to set up, diagnose, and benchmark [[Wikipedia:InfiniBand|InfiniBand]] networks.<br />
<br />
== Introduction ==<br />
<br />
=== Overview ===<br />
<br />
InfiniBand (abbreviated IB) is an alternative to Ethernet and Fibre Channel. IB provides high bandwidth and low latency. IB can transfer data directly to and from a storage device on one machine to userspace on another machine, bypassing and avoiding the overhead of a system call. IB adapters can handle the networking protocols, unlike Ethernet networking protocols which are ran on the CPU. This allows the OS's and CPU's to remain free while the high bandwidth transfers take place, which can be a real problem with 10Gb+ Ethernet.<br />
<br />
IB hardware is made by Mellanox (which merged with Voltaire, and is heavily backed by Oracle) and Intel (which acquired QLogic's IB division in 2012). Mellanox was acquired by Nvidia in 2019. IB is most often used by supercomputers, clusters, and data centers. IBM, HP, and Cray are also members of the InfiniBand Steering Committee. Facebook, Twitter, eBay, YouTube, and PayPal are examples of IB users.<br />
<br />
IB software is developed under the [https://www.openfabrics.org/ OpenFabrics Open Source Alliance]<br />
<br />
=== Affordable used equipment ===<br />
<br />
With large businesses benefiting so much from jumping to newer versions, the maximum length limitations of passive IB cabling, the high cost of active IB cabling, and the more technically complex setup than Ethernet, the used IB market is heavily saturated, allowing used IB devices to affordably be used at home or smaller businesses for their internal networks.<br />
<br />
=== Bandwidth ===<br />
<br />
==== Signal transfer rates ====<br />
<br />
IB transfer rates corresponded in the beginning to the maximum supported by PCI Express (abbreviated PCIe), later on, as PCIe made less progress, the transfer rates corresponded to other I/O technologies and the number of PCIe lanes per port was increased instead. It launched using SDR (Single Data Rate) with a signaling rate of 2.5Gb/s per lane (corresponding with PCI Express v1.0), and has added: DDR (Double Data Rate) at 5Gb/s (PCI Express v2.0); QDR (Quad Data Rate) at 10Gb/s (matching the throughput of PCI Express 3.0 with improved coding of PCIe 3.0 instead of the signaling rate); and FDR (Fourteen Data Rate) at 14.0625Gbps (matching 16GFC Fibre Channel). IB is now delivering EDR (Enhanced Data Rate) at 25Gb/s (matching 25Gb Ethernet). Planned around 2017 will be HDR (High Data Rate) at 50Gb/s.<br />
<br />
==== Effective throughput ====<br />
<br />
Because SDR, DDR, and QDR versions use 8/10 encoding (8 bits of data takes 10 bits of signaling), effective throughput for these is lowered to 80%: SDR at 2Gb/s/link; DDR at 4Gb/s/link; and QDR at 8Gb/s/link. Starting with FDR, IB uses 64/66 encoding, allowing a higher effective throughput to signaling rate ratio of 96.97%: FDR at 13.64Gb/s/link; EDR at 24.24Gb/s/lane; and HDR at 48.48Gb/s/link.<br />
<br />
IB devices are capable of sending data over multiple links, though commercial products standardized around 4 links per cable. <br />
<br />
When using the common 4X link devices, this effectively allows total effective throughputs of: SDR of 8Gb/s; DDR of 16Gb/s; QDR of 32Gb/s; FDR of 54.54Gb/s; EDR of 96.97Gb/s; and HDR of 193.94Gb/s.<br />
<br />
=== Latency ===<br />
<br />
IB's latency is incredibly small: SDR (5us); DDR (2.5us); QDR (1.3us); FDR (0.7us); EDR (0.5us); and HDR (< 0.5us). For comparison 10Gb Ethernet is more like 7.22us, ten times more than FDR's latency.<br />
<br />
=== Backwards compatibility ===<br />
<br />
IB devices are almost always backwards compatible. Connections should be established at the lowest common denominator. A DDR adapter meant for a PCI Express 8x slot should work in a PCI Express 4x slot (with half the bandwidth).<br />
<br />
=== Cables ===<br />
<br />
IB passive copper cables can be up to 7 meters using up to QDR, and 3 meters using FDR.<br />
<br />
IB active fiber (optical) cables can be up to 300 meters using up to FDR (only 100 meters on FDR10).<br />
<br />
Mellanox MetroX devices exist which allow up to 80 kilometer connections. Latency increases by about 5us per kilometer.<br />
<br />
An IB cable can be used to directly link two computers without a switch; IB cross-over cables do not exist.<br />
<br />
== Terminology ==<br />
<br />
=== Hardware ===<br />
<br />
Adapters, switches, routers, and bridges/gateways must be specifically made for IB.<br />
<br />
; HCA (Host Channel Adapter): Like an Ethernet NIC (Network Interface Card). Connects the IB cable to the PCI Express bus, at the full speed of the bus if the proper generation of HCA is used. An end node on an IB network, executes transport-level functions, and supports the IB verbs interface.<br />
; Switch: Like an Ethernet NIC. Moves packets from one link to another on the same IB subnet.<br />
; Router: Like an Ethernet router. Moves packets between different IB subnets.<br />
; Bridge/Gateway: A standalone piece of hardware, or a computer performing this function. Bridges IB and Ethernet networks.<br />
<br />
=== GUID ===<br />
<br />
Like Ethernet MAC addresses, but a device has multiple GUID's. Assigned by the hardware manufacturer, and remains the same through reboots. 64-bit addresses (24-bit manufacturer prefix and 40-bit device identifier). Given to adapters, switches, routers, and bridges/gateways.<br />
<br />
; Node GUID: Identifies the HCA, Switch, or Router<br />
; Port GUID: Identifies a port on a HCA, Switch, or Router (even a HCA often has multiple ports)<br />
; System GUID: Allows treating multiple GUIDs as one entity<br />
; LID (Local IDentifier): 16-bit addresses, assigned by the Subnet Manager when picked up by the Subnet Manager. Used for routing packets. Not persistent through reboots.<br />
<br />
=== Network Management ===<br />
<br />
; SM (Subnet Manager): Actively manages an IB subnet. Can be implemented as a software program on a computer connected to the IB network, built in to an IB switch, or as a specialized IB device. Initializes and configures everything else on the subnet, including assigning LIDs (Local IDentifiers). Establishes traffic paths through the subnet. Isolates faults. Prevents unauthorized Subnet Managers. You can have multiple switches all on one subnet, under one Subnet Manager. You can have redundant Subnet Managers on one subnet, but only one can be active at a time.<br />
; MAD (MAnagement Datagram): Standard message format for subnet manager to and from IB device communication, carried by a UD (Unreliable Datagram).<br />
; UD (Unreliable Datagram):<br />
<br />
== Installation ==<br />
<br />
First install {{Pkg|rdma-core}} which contains all core libraries and daemons.<br />
<br />
=== Upgrade firmware ===<br />
<br />
Running the most recent firmware can give significant performance increases, and fix connectivity issues.<br />
<br />
{{Warning|Be careful or the device may be bricked!}}<br />
<br />
==== For Mellanox ====<br />
<br />
* Install {{AUR|mstflint}}<br />
* Determine your adapter's PCI device ID (in this example, "05:00.0" is the adapter's PCI device ID)<br />
{{hc|$ lspci {{!}} grep Mellanox|'''05:00.0''' InfiniBand: Mellanox Technologies MT25418 [ConnectX VPI PCIe 2.0 2.5GT/s - IB DDR / 10GigE] (rev a0)}}<br />
* Determine what firmware version your adapter has, and your adapter's PSID (more specific than just a model number - specific to a compatible set of revisions)<br />
{{hc|# mstflint -d <adapter PCI device ID> query|...<br />
FW Version: '''2.7.1000'''<br />
...<br />
PSID: '''MT_04A0110002'''}}<br />
* Check latest firmware version<br />
** Visit [https://www.mellanox.com/page/firmware_download Mellanox's firmware download page] (this guide incorporates this link's "firmware burning instructions", using its mstflint option)<br />
** Choose the category of device you have<br />
** Locate your device's PSID on their list, that mstflint gave you<br />
** Examine the Firmware Image filename to see if it is more recent than your adapter's FW Version, i.e. {{ic|fw-25408-2_9_1000-MHGH28-XTC_A1.bin.zip}}, is version {{ic|2.9.1000}}<br />
* If there is a more recent version, download new firmware and burn it to your adapter<br />
$ unzip <''firmware .bin.zip file name''><br />
# mstflint -d <''adapter PCI device ID''> -i <''firmware .bin file name''> burn<br />
<br />
==== For Intel/QLogic ====<br />
<br />
Search for the model number (or a substring) over at [https://downloadcenter.intel.com/ Intel Download Center] and follow the instructions. The downloaded software will probably need to be run from RHEL/CentOS or SUSE/OpenSUSE.<br />
<br />
=== Kernel modules ===<br />
<br />
Edit {{ic|/etc/rdma/modules/rdma.conf}} and {{ic|/etc/rdma/modules/infiniband.conf}} to your liking. Then load the kernel modules written in these files such as {{ic|ib_ipoib}}, or just reboot the system. (Although there should be no need to do this, [[start]] and [[enable]] both {{ic|rdma-load-modules@rdma.service}} and {{ic|rdma-load-modules@infiniband.service}} if kernel modules are not loaded correctly. Rebooting the system will be fine).<br />
<br />
{{note|1=[https://bugzilla.redhat.com/show_bug.cgi?id=965829 Due to how the kernel stacks are handled], changes to {{ic|/etc/rdma/modules/rdma.conf}} only take effect max once every boot, when {{ic|rdma-load-modules@*.service}} is started for first time. Restarting {{ic|rdma-load-modules@*.service}} has no effect.}}<br />
<br />
=== Subnet manager ===<br />
<br />
Each IB network requires at least one subnet manager. Without one, devices may show having a link, but will never change state from {{ic|Initializing}} to {{ic|Active}}. A subnet manager often (typically every 5 or 30 seconds) checks the network for new adapters and adds them to the routing tables. If you have an IB switch with an embedded subnet manager, you can use that, or you can keep it disabled and use a software subnet manager instead. Dedicated IB subnet manager devices also exist.<br />
<br />
=== Enable port ===<br />
<br />
If the port is in the physical state {{ic|Sleep}} (can be verified with {{ic|ibstat}}) then it first needs to be enabled by running {{ic|ibportstate --Direct 0 1 enable}} for it to wake up. This may need to be automated at boot if the ports at both ends of the link are sleeping.<br />
<br />
==== Software subnet manager ====<br />
<br />
On one system:<br />
<br />
* Install {{AUR|opensm}}<br />
* Correct the systemd file {{ic|/usr/lib/systemd/system/opensm.service}} as the following instruction.<br />
* [[Start]] and [[enable]] {{ic|opensm.service}}<br />
<br />
The current opensm's configuration for opensm is not compatible with RDMA's systemd configuration. That is, edit the 2 lines in {{ic|/usr/lib/systemd/system/opensm.service}} as following (Commented ones are original contents.).<br />
<br />
{{hc|# /usr/lib/systemd/system/opensm.service|Requires{{=}}rdma-load-modules@rdma.service # Requires{{=}}rdma.service<br />
After{{=}}rdma-load-modules@rdma.service # After{{=}}rdma.service}}<br />
<br />
All of your connected IB ports should now be in a (port) state of {{ic|Active}}, and a physical state of {{ic|LinkUp}}. You can check this by running [[#ibstat - View a computer's IB GUIDs|ibstat]].<br />
{{hc|$ ibstat|... (look at the ports shown you expect to be connected)<br />
State: Active<br />
Physical state: LinkUp<br />
...}}<br />
Or by examining the {{ic|/sys}} filesystem:<br />
{{hc|$ cat /sys/class/infiniband/''kernel_module''/ports/''port_number''/phys_state|5: LinkUp}}<br />
{{hc|$ cat /sys/class/infiniband/''kernel_module''/ports/''port_number''/state|4: ACTIVE}}<br />
<br />
== TCP/IP (IPoIB) ==<br />
<br />
You can create a virtual Ethernet Adapter that runs on the HCA. This is intended so programs designed to work with TCP/IP but not IB, can (indirectly) use IB networks. Performance is negatively affected due to sending all traffic through the normal TCP stack; requiring system calls, memory copies, and network protocols to run on the CPU rather than on the HCA.<br />
<br />
IB interface will appear when the module {{ic|ib_ipoib}} is loaded. The simple configuration to make it appear is adding the line {{ic|ib_ipoib}} in {{ic|/etc/rdma/modules/infiniband.conf}} then rebooting the system. After booting the system with the module {{ic|ib_ipoib}}, links with the name like {{ic|ibp16s0}} should be confirmed with the command {{ic|ip link}}.<br />
<br />
Detailed configuration is possible for the IB interface (e.g. naming it {{ic|ib0}} and assigning IP addresses [[Network configuration|like a traditional Ethernet adapter]]).<br />
<br />
=== Connection mode ===<br />
<br />
IPoIB can run in datagram (default) or connected mode. Connected mode [[#Finetuning connection mode and MTU|allows you to set a higher MTU]], but does increase TCP latency for short messages by about 5% more than datagram mode.<br />
<br />
To see the current mode used:<br />
<br />
$ cat /sys/class/net/''interface''/mode<br />
<br />
=== MTU ===<br />
<br />
In datagram mode, UD (Unreliable Datagram) transport is used, which typically forces the MTU to be 2044 bytes. Technically to the IB L2 MTU - 4 bytes for the IPoIB encapsulation header, which is usually 2044 bytes.<br />
<br />
In connected mode, RC (Reliable Connected) transport is used, which allows a MTU up to the maximum IP packet size, 65520 bytes.<br />
<br />
To see your MTU:<br />
<br />
$ ip link show ''interface''<br />
<br />
=== Finetuning connection mode and MTU ===<br />
<br />
You only need {{ic|ipoibmodemtu}} if you want to change the default connection mode and/or MTU.<br />
<br />
* [[#TCP/IP (IPoIB)|Install and set up TCP/IP over IB (IPoIB)]]<br />
* Install {{AUR|ipoibmodemtu}}<br />
* Configure {{ic|ipoibmodemtu}} through {{ic|/etc/ipoibmodemtu.conf}}, which contains instructions on how to do so<br />
** It defaults to setting a single IB port {{ic|ib0}} to {{ic|connected}} mode and MTU {{ic|65520}}<br />
* [[Start]] and [[enable]] {{ic|ipoibmodemtu.service}}<br />
<br />
Different setups will see different results. Some people see a gigantic (double+) speed increase by using {{ic|connected}} mode and MTU {{ic|65520}}, and a few see about the same or even worse speeds. Use [[#qperf - Measure performance over RDMA or TCP/IP|qperf]] and [[#iperf - Measure performance over TCP/IP|iperf]] to finetune your system.<br />
<br />
Using the [[#qperf - Measure performance over RDMA or TCP/IP|qperf]] examples given in this article, here are example results from an SDR network (8 theoretical Gb/s) with various finetuning:<br />
{| class="wikitable"<br />
! Mode !! MTU !! MB/s !! us latency<br />
|-<br />
| datagram || 2044 || 707 || 19.4<br />
|-<br />
| connected || 2044 || 353 || 18.9<br />
|-<br />
| connected || 65520 || 726 || 19.6<br />
|}<br />
<br />
{{Tip|Use the same connection and MTU settings for the entire subnet. Mixing and matching does not work optimally.}}<br />
<br />
== Soft RoCE (RXE) ==<br />
<br />
Soft ROCE is a software implementation of RoCE that allows using Infiniband over any ethernet adapter.<br />
<br />
* Install {{pkg|iproute2}}<br />
* Run {{ic|rdma link add rxe_eth0 type rxe netdev ethN}} to configure an RXE instance on ethernet device ethN.<br />
<br />
You should now have an rxe0 device:<br />
{{hc|# rdma link|<br />
link rxe_eth0/1 state ACTIVE physical_state LINK_UP netdev enp1s0}}<br />
<br />
== Remote data storage ==<br />
<br />
You can share physical or virtual devices from a target (host/server) to an initiator (guest/client) system over an IB network, using iSCSI, iSCSI with iSER, or SRP. These methods differ from traditional file sharing (i.e. [[Samba]] or [[NFS]]) because the initiator system views the shared device as its own block level device, rather than a traditionally mounted network shared folder. i.e. {{ic|fdisk /dev/''block_device_id''}}, {{ic|mkfs.btrfs /dev/''block_device_id_with_partition_number''}}<br />
<br />
The disadvantage is only one system can use each shared device at a time; trying to mount a shared device on the target or another initiator system will fail (an initiator system can certainly run traditional file sharing on top).<br />
<br />
The advantages are faster bandwidth, more control, and even having an initiator's root filesystem being physically located remotely (remote booting).<br />
<br />
=== targetcli ===<br />
<br />
{{ic|targetcli}} acts like a shell that presents its complex (and not worth creating by hand) {{ic|/etc/target/saveconfig.json}} as a pseudo-filesystem.<br />
<br />
==== Installing and using ====<br />
<br />
On the target system:<br />
* Install {{AUR|targetcli-fb}}<br />
* [[Start]] and [[enable]] {{ic|target.service}}<br />
<br />
In {{ic|targetcli}}:<br />
* In any pseudo-directory, you can run {{ic|help}} to see the commands available ''in that pseudo-directory'' or {{ic|help ''command''}} (like {{ic|help create}}) for more detailed help<br />
* Tab-completion is also available for many commands<br />
* Run {{ic|ls}} to see the entire pseudo-filesystem at and below the current pseudo-directory<br />
<br />
==== Create backstores ====<br />
<br />
Enter the configuration shell:<br />
<br />
# targetcli<br />
<br />
Within {{ic|targetcli}}, setup a backstore for each device or virtual device to share:<br />
* To share an actual block device, run: {{ic|cd /backstores/block}}; and {{ic|create ''name'' ''dev''}}<br />
* To share a file as a virtual block device, run: {{ic|cd /backstores/fileio}}; and {{ic|create ''name'' ''file''}}<br />
* To share a physical SCSI device as a pass-through, run: {{ic|cd /backstores/pscsi}}; and {{ic|create ''name'' ''dev''}}<br />
* To share a RAM disk, run: {{ic|cd /backstores/ramdisk}}; and {{ic|create ''name'' ''size''}}<br />
* Where ''name'' is for the backstore's name<br />
* Where ''dev'' is the block device to share (i.e. {{ic|/dev/sda}}, {{ic|/dev/sda4}}, {{ic|/dev/disk/by-id/''XXX''}}, or a LVM logical volume {{ic|/dev/vg0/lv1}})<br />
* Where ''file'' is the file to share (i.e. {{ic|/path/to/file}})<br />
* Where ''size'' is the size of the RAM disk to create (i.e. 512MB, 20GB)<br />
<br />
=== iSCSI ===<br />
<br />
iSCSI allows storage devices and virtual storage devices to be used over a network. For IB networks, the storage can either work over IPoIB or iSER.<br />
<br />
There is a lot of overlap with the [[iSCSI Target]], [[iSCSI Initiator]], and [[iSCSI Boot]] articles, but the necessities will be discussed since much needs to be customized for usage over IB.<br />
<br />
==== Over IPoIB ====<br />
<br />
Perform the target system instructions first, which will direct you when to temporarily switch over to the initiator system instructions.<br />
<br />
* On the target and initiator systems, [[#TCP/IP (IPoIB)|install TCP/IP over IB]]<br />
<br />
* On the target system, for each device or virtual device you want to share, in {{ic|targetcli}}:<br />
** [[#Create backstores|Create a backstore]]<br />
** For each backstore, create an IQN (iSCSI Qualified Name) (the name other systems' configurations will see the storage as)<br />
*** Run: {{ic|cd /iscsi}}; and {{ic|create}}. It will give you a ''randomly_generated_target_name'', i.e. {{ic|iqn.2003-01.org.linux-iscsi.hostname.x8664:sn.3d74b8d4020a}}<br />
*** Set up the TPG (Target Portal Group), automatically created in the last step as tpg1<br />
**** Create a lun (Logical Unit Number)<br />
***** Run: {{ic|cd ''randomly_generated_target_name''/tpg1/luns}}; and {{ic|create ''storage_object''}}. Where {{ic|''storage_object''}} is a full path to an existing storage object, i.e. {{ic|/backstores/block/''name''}}<br />
**** Create an acl (Access Control List)<br />
***** Run: {{ic|cd ../acls}}; and {{ic|create ''wwn''}}, where {{ic|''wwn''}} is the initiator system's IQN (iSCSI Qualified Name), aka its (World Wide Name)<br />
****** Get the {{ic|''wwn''}} by running on the initiator system, '''not''' this target system: (after installing on it {{pkg|open-iscsi}}) {{ic|cat /etc/iscsi/initiatorname.iscsi}}<br />
** Save and exit by running: {{ic|cd /}}; {{ic|saveconfig}}; and {{ic|exit}}<br />
<br />
* On the initiator system:<br />
** Install {{pkg|open-iscsi}}<br />
** At this point, you can obtain this initiator system's IQN (iSCSI Qualified Name), aka its wwn (World Wide Name), for setting up the target system's {{ic|luns}}:<br />
*** {{ic|pacman}} should have displayed {{ic|>>> Setting Initiatorname ''wwn''}}<br />
*** Otherwise, run: {{ic|cat /etc/iscsi/initiatorname.iscsi}} to see {{ic|1=InitiatorName=''wwn''}}<br />
** [[Start]] and [[enable]] {{ic|iscsid.service}}<br />
** To automatically login to discovered targets at boot, before discovering targets, edit {{ic|/etc/iscsi/iscsid.conf}} to set {{ic|1=node.startup = automatic}}<br />
** Discover online targets. Run {{ic|iscsiadm -m discovery -t sendtargets -p ''portal''}} as root, where ''portal'' is an IP (v4 or v6) address or hostname<br />
*** If using a hostname, make sure it routes to the IB IP address rather than Ethernet - it may be beneficial to just use the IB IP address<br />
** To automatically login to discovered targets at boot, [[Start]] and [[enable]] {{ic|iscsi.service}}<br />
** To manually login to discovered targets, run {{ic|iscsiadm -m node -L all}} as root.<br />
** View which block device ID was given to each target logged into. Run {{ic|iscsiadm -m session -P 3 {{!}} grep Attached}} as root. The block device ID will be the last line in the tree for each target ({{ic|-P}} is the print command, its option is the verbosity level, and only level 3 lists the block device IDs)<br />
<br />
==== Over iSER ====<br />
<br />
iSER (iSCSI Extensions for RDMA) takes advantage of IB's RDMA protocols, rather than using TCP/IP. It eliminates TCP/IP overhead, and provides higher bandwidth, zero copy time, lower latency, and lower CPU utilization.<br />
<br />
Follow the [[#Over IPoIB|iSCSI Over IPoIB]] instructions, with the following changes:<br />
<br />
* If you wish, instead of [[#TCP/IP (IPoIB)|installing IPoIB]], you can just [[#Kernel modules|install RDMA for loading kernel modules]]<br />
* On the target system, after everything else is setup, while still in {{ic|targetcli}}, enable iSER on the target:<br />
** Run {{ic|cd /iscsi/''iqn''/tpg1/portals/0.0.0.0:3260}} for each ''iqn'' you want to have use iSER rather than IPoIB<br />
*** Where ''iqn'' is the randomly generated target name, i.e. {{ic|iqn.2003-01.org.linux-iscsi.hostname.x8664:sn.3d74b8d4020a}}<br />
** Run {{ic|enable_iser true}}<br />
** Save and exit by running: {{ic|cd /}}; {{ic|saveconfig}}; and {{ic|exit}}<br />
* On the initiator system, when running {{ic|iscsiadm}} to discover online targets, use the additional argument {{ic|-I iser}}, and when you login to them, you should see: {{ic|Logging in to [iface: iser...}}<br />
<br />
==== Adding to /etc/fstab ====<br />
<br />
The last time you discovered targets, automatic login must have been turned on.<br />
<br />
Add your mount entry to {{ic|/etc/fstab}} as if it were a local block device, except add a {{ic|_netdev}} option to avoid attempting to mount it before network initialization.<br />
<br />
== Network segmentation ==<br />
<br />
{{Expansion|Explain in more detail with examples}}<br />
<br />
An IB subnet can be partitioned for different customers or applications, giving security and quality of service guarantees. Each partition is identified by a PKEY (Partition Key).<br />
<br />
== SDP (Sockets Direct Protocol) ==<br />
<br />
Use {{ic|librdmacm}} (successor to rsockets and libspd) and {{ic|LD_PRELOAD}} to intercept non-IB programs' socket calls, and transparently (to the program) send them over IB via RDMA. Dramatically speeding up programs built for TCP/IP, much more than can be achieved by using IPoIB. It avoids the need to change the program's source code to work with IB and can even be used for closed source programs. It does not work for programs that statically link in socket libraries.<br />
<br />
== Diagnosing and benchmarking ==<br />
<br />
All IB specific tools are included in {{Pkg|rdma-core}} and {{AUR|ibutils}}.<br />
<br />
=== ibstat - View a computer's IB GUIDs ===<br />
<br />
ibstat will show you detailed information about each IB adapter in the computer it is ran on, including: model number; number of ports; firmware and hardware version; node, system image, and port GUIDs; and port state, physical state, rate, base lid, lmc, SM lid, capability mask, and link layer.<br />
<br />
{{hc|$ ibstat|CA 'mlx4_0'<br />
CA type: MT25418<br />
Number of ports: 2<br />
Firmware version: 2.9.1000<br />
Hardware version: a0<br />
Node GUID: 0x0002c90300002f78<br />
System image GUID: 0x0002c90300002f7b<br />
Port 1:<br />
State: Active<br />
Physical state: LinkUp<br />
Rate: 20<br />
Base lid: 3<br />
LMC: 0<br />
SM lid: 3<br />
Capability mask: 0x0251086a<br />
Port GUID: 0x0002c90300002f79<br />
Link layer: InfiniBand<br />
Port 2:<br />
State: Down<br />
Physical state: Polling<br />
Rate: 10<br />
Base lid: 0<br />
LMC: 0<br />
SM lid: 0<br />
Capability mask: 0x02510868<br />
Port GUID: 0x0002c90300002f7a<br />
Link layer: InfiniBand}}<br />
<br />
This example shows a Mellanox Technologies (MT) adapter. Its PCI Device ID is reported (25418), rather than the model number of part number. It shows a state of "Active", which means is it properly connected to a subnet manager. It shows a physical state of "LinkUp", which means it has an electrical connection via cable, but is not necessarily properly connected to a subnet manager. It shows a total rate of 20 Gb/s (which for this card is from a 5.0 Gb/s signaling rate and 4 virtual lanes). It shows the subnet manager assigned the port a lid of 3.<br />
<br />
=== ibhosts - View all hosts on IB network ===<br />
<br />
ibhosts will show you the Node GUIDs, number of ports, and device names, for each host on the IB network.<br />
<br />
{{hc|# ibhosts|<br />
Ca : 0x0002c90300002778 ports 2 "MT25408 ConnectX Mellanox Technologies"<br />
Ca : 0x0002c90300002f78 ports 2 "hostname mlx4_0"<br />
}}<br />
<br />
=== ibswitches - View all switches on IB network ===<br />
<br />
ibswitches will show you the Node GUIDs, number of ports, and device names, for each switch on the IB network. If you are running with direct connections only, it will show nothing.<br />
<br />
# ibswitches<br />
<br />
=== iblinkinfo - View link information on IB network ===<br />
<br />
iblinkinfo will show you the device names, Port GUIDs, number of virtual lanes, [[#Signal transfer rates|signal transfer rates]], state, physical state, and what it is connected to.<br />
<br />
{{hc|# iblinkinfo|2=<br />
CA: MT25408 ConnectX Mellanox Technologies:<br />
0x0002c90300002779 4 1[ ] ==( 4X 5.0 Gbps Active/ LinkUp)==> 3 1[ ] "kvm mlx4_0" ( )<br />
CA: hostname mlx4_0:<br />
0x0002c90300002f79 3 1[ ] ==( 4X 5.0 Gbps Active/ LinkUp)==> 4 1[ ] "MT25408 ConnectX Mellanox Technologies" ( )<br />
}}<br />
<br />
This example shows two adapters directly connected with out a switch, using a 5.0 Gb/s [[#Signal transfer rates|signal transfer rate]], and 4 virtual lanes (4X).<br />
<br />
=== ibping - Ping another IB device ===<br />
<br />
ibping will attempt pinging another IB GUID. ibping must be ran in server mode on one computer, and in client mode on another.<br />
<br />
ibping must be ran in server mode on one computer.<br />
<br />
# ibping -S<br />
<br />
And in client mode on another. It is pinging a specific port, so it cannot take a CA name, or a Node or System GUID. It requires {{ic|-G}} with a Port GUID, or {{ic|-L}} with a Lid.<br />
<br />
{{hc|# ibping -G 0x0002c90300002779<br />
-or-<br />
# ibping -L 1|2=<br />
Pong from hostname.(none) (Lid 1): time 0.053 ms<br />
Pong from hostname.(none) (Lid 1): time 0.074 ms<br />
^C<br />
--- hostname.(none) (Lid 4) ibping statistics ---<br />
2 packets transmitted, 2 received, 0% packet loss, time 1630 ms<br />
rtt min/avg/max = 0.053/0.063/0.074 ms}}<br />
<br />
If you are running IPoIB, you can use regular {{ic|ping}} which pings through the TCP/IP stack. ibping uses IB interfaces, and does not use the TCP/IP stack.<br />
<br />
=== ibdiagnet - Show diagnostic information for entire subnet ===<br />
<br />
ibdiagnet will show you potential problems on your subnet. You can run it without options. {{ic|-lw <1x{{!}}4x{{!}}12x>}} specifies the expected link width (number of virtual lanes) for your computer's adapter, so it can check if it is running as intended. {{ic|-ls <2.5{{!}}5{{!}}10>}} specifies the expected link speed (signaling rate) for your computer's adapter, so it can check if it is running as intended, but it does not yet support options faster than 10 for FDR+ devices. {{ic|-c <count>}} overrides the default number of packets to be sent of 10.<br />
<br />
{{hc|# ibdiagnet -lw 4x -ls 5 -c 1000|<nowiki><br />
Loading IBDIAGNET from: /usr/lib/ibdiagnet1.5.7<br />
-W- Topology file is not specified.<br />
Reports regarding cluster links will use direct routes.<br />
Loading IBDM from: /usr/lib/ibdm1.5.7<br />
-I- Using port 1 as the local port.<br />
-I- Discovering ... 2 nodes (0 Switches & 2 CA-s) discovered.<br />
<br />
-I---------------------------------------------------<br />
-I- Bad Guids/LIDs Info<br />
-I---------------------------------------------------<br />
-I- No bad Guids were found<br />
<br />
-I---------------------------------------------------<br />
-I- Links With Logical State = INIT<br />
-I---------------------------------------------------<br />
-I- No bad Links (with logical state = INIT) were found<br />
<br />
-I---------------------------------------------------<br />
-I- General Device Info<br />
-I---------------------------------------------------<br />
<br />
-I---------------------------------------------------<br />
-I- PM Counters Info<br />
-I---------------------------------------------------<br />
-I- No illegal PM counters values were found<br />
<br />
-I---------------------------------------------------<br />
-I- Links With links width != 4x (as set by -lw option)<br />
-I---------------------------------------------------<br />
-I- No unmatched Links (with width != 4x) were found<br />
<br />
-I---------------------------------------------------<br />
-I- Links With links speed != 5 (as set by -ls option)<br />
-I---------------------------------------------------<br />
-I- No unmatched Links (with speed != 5) were found<br />
<br />
-I---------------------------------------------------<br />
-I- Fabric Partitions Report (see ibdiagnet.pkey for a full hosts list)<br />
-I---------------------------------------------------<br />
-I- PKey:0x7fff Hosts:2 full:2 limited:0<br />
<br />
-I---------------------------------------------------<br />
-I- IPoIB Subnets Check<br />
-I---------------------------------------------------<br />
-I- Subnet: IPv4 PKey:0x7fff QKey:0x00000b1b MTU:2048Byte rate:10Gbps SL:0x00<br />
-W- Suboptimal rate for group. Lowest member rate:20Gbps > group-rate:10Gbps<br />
<br />
-I---------------------------------------------------<br />
-I- Bad Links Info<br />
-I- No bad link were found<br />
-I---------------------------------------------------<br />
----------------------------------------------------------------<br />
-I- Stages Status Report:<br />
STAGE Errors Warnings<br />
Bad GUIDs/LIDs Check 0 0 <br />
Link State Active Check 0 0 <br />
General Devices Info Report 0 0 <br />
Performance Counters Report 0 0 <br />
Specific Link Width Check 0 0 <br />
Specific Link Speed Check 0 0 <br />
Partitions Check 0 0 <br />
IPoIB Subnets Check 0 1 <br />
<br />
Please see /tmp/ibdiagnet.log for complete log<br />
----------------------------------------------------------------<br />
<br />
-I- Done. Run time was 0 seconds.<br />
</nowiki>}}<br />
<br />
=== qperf - Measure performance over RDMA or TCP/IP ===<br />
<br />
qperf can measure bandwidth and latency over RDMA (SDP, UDP, UD, and UC) or TCP/IP (including IPoIB)<br />
<br />
qperf must be ran in server mode on one computer.<br />
<br />
$ qperf<br />
<br />
And in client mode on another. SERVERNODE can be a hostname, or for IPoIB a TCP/IP address. There are many tests. Some of the most useful are below.<br />
<br />
$ qperf SERVERNODE [OPTIONS] TESTS<br />
<br />
==== TCP/IP over IPoIB ====<br />
<br />
{{hc|$ qperf 192.168.2.2 tcp_bw tcp_lat|2=<br />
tcp_bw:<br />
bw = 701 MB/sec<br />
tcp_lat:<br />
latency = 19.8 us<br />
}}<br />
<br />
=== iperf - Measure performance over TCP/IP ===<br />
<br />
iperf is not an IB aware program, and is meant to test over TCP/IP or UDP. Even though [[#qperf - Measure performance over RDMA or TCP/IP|qperf]] can test your IB TCP/IP performace using IPoIB, iperf is still another program you can use.<br />
<br />
iperf must be ran in server mode on one computer.<br />
<br />
$ iperf3 -s<br />
<br />
And in client mode on another.<br />
<br />
{{hc|$ iperf3 -c 192.168.2.2|<br />
[ 4] local 192.168.2.1 port 20139 connected to 192.168.2.2 port 5201<br />
[ ID] Interval Transfer Bandwidth<br />
[ 4] 0.00-1.00 sec 639 MBytes 5.36 Gbits/sec <br />
...<br />
[ 4] 9.00-10.00 sec 638 MBytes 5.35 Gbits/sec <br />
- - - - - - - - - - - - - - - - - - - - - - - - -<br />
[ ID] Interval Transfer Bandwidth<br />
[ 4] 0.00-10.00 sec 6.23 GBytes 5.35 Gbits/sec sender<br />
[ 4] 0.00-10.00 sec 6.23 GBytes 5.35 Gbits/sec receiver<br />
<br />
iperf Done.}}<br />
<br />
iperf shows Transfer in base 10 GB's, and Bandwidth in base 2 GB's. So, this example shows 6.23GB (base 10) in 10 seconds. That is 6.69GB (base 2) in 10 seconds. (6.23 * 2^30 / 10^9) That's 5.35 Gb/s (base 2), as shown by iperf. (6.23 * 2^30 / 10^9 * 8 / 10) That is 685 MB/s (base 2), which is roughly the speed that qperf reported. (6.23 * 2^30 / 10^9 * 8 / 10 * 1024 / 8)<br />
<br />
== Common problems / FAQ ==<br />
<br />
=== Connection problems ===<br />
<br />
==== Link, physical state and port state ====<br />
<br />
* See if the IB hardware modules are recognized by the system. If you have an Intel adapter, you will have to use Intel here and look through a few lines if you have other Intel hardware:<br />
{{hc|# dmesg {{!}} grep -Ei "Mellanox{{!}}InfiniBand{{!}}QLogic{{!}}Voltaire"|<br />
[ 6.287556] mlx4_core: Mellanox ConnectX core driver v2.2-1 (Feb, 2014)<br />
[ 8.686257] <mlx4_ib> mlx4_ib_add: mlx4_ib: Mellanox ConnectX InfiniBand driver v2.2-1 (Feb 2014)<br />
}}<br />
{{hc|$ ls -l /sys/class/infiniband|mlx4_0 -> ../../devices/pci0000:00/0000:00:03.0/0000:05:00.0/infiniband/mlx4_0}}<br />
If nothing is shown, your kernel is not recognizing your adapter. This example shows approximately what you will see if you have a Mellanox ConnectX adapter, which uses the mlx4_0 kernel module.<br />
<br />
* Check the port and physical states. Either run [[#ibstat - View a computer's IB GUIDs|ibstat]] or examine {{ic|/sys}}.<br />
{{hc|$ ibstat|<br />
(look at the port shown that you expect to be connected)}}<br />
or<br />
{{hc|$ cat /sys/class/infiniband/<kernel module>/ports/<port number>/phys_state|<br />
5: LinkUp}}<br />
{{hc|$ cat /sys/class/infiniband/<kernel module>/ports/<port number>/state|<br />
4: ACTIVE}}<br />
The physical state should be "LinkUp". If it is not, your cable likely is not plugged in, is not connected to anything on the other end, or is defective. The (port) state should be "Active". If it is "Initializing" or "INIT", your [[#Subnet manager|subnet manager]] does not exist, is not running, or has not added the port to the network's routing tables.<br />
<br />
* Can you successfully [[#ibping - Ping another IB device|ibping]] which uses IB directly, rather than IPoIB? Can you successfully {{ic|ping}}, if you are running IPoIB?<br />
<br />
* Consider [[#Upgrade firmware|upgrading firmware]].<br />
<br />
==== getaddrinfo failed: Name or service not known ====<br />
<br />
* Run [[#ibhosts - View all hosts on IB network|ibhosts]] to see the CA names at the end of each line in quotes.<br />
<br />
=== Speed problems ===<br />
<br />
* Start by double-checking your expectations.<br />
How have you determined you have a speed problem? Are you using [[#qperf - Measure performance over RDMA or TCP/IP|qperf]] or [[#iperf - Measure performance over TCP/IP|iperf]], which both transmit data to and from memory rather than hard drives. Or, are you benchmarking actual file transfers, which relies on your hard drives? Unless you are running RAID to boost speed, even with the fastest SSD's available in mid 2015, a single hard drive (or sometimes even multiple ones) will be bottlenecking your IB transfer speeds. Are you using RDMA or TCP/IP via IPoIB? If so, [[#TCP/IP (IPoIB)|there is a performance hit]] for using IPoIB instead of RDMA.<br />
<br />
* Check your link speeds. Run [[#ibstat - View a computer's IB GUIDs|ibstat]], [[#iblinkinfo - View link information on IB network|iblinkinfo]], or examine {{ic|/sys}}.<br />
{{hc|$ ibstat|<br />
(look at the Rate shown on the port you are using)}}<br />
or<br />
{{hc|# iblinkinfo|<br />
(look at the middle part formatted like "4X 5.0 Gbps")}}<br />
or<br />
{{hc|$ cat /sys/class/infiniband/<kernel module>/ports/<port number>/rate|<br />
20 Gb/sec (4X DDR)}}<br />
Does this match your expected [[#Bandwidth|bandwidth and number of virtual lanes]]?<br />
<br />
* Check diagnostic information for entire subnet. Run [[#ibdiagnet - Show diagnostic information for entire subnet]]. Make sure to use {{ic|-ls }} with [[#Bandwidth|the proper signaling rate, which is likely the advertised speed of your card divided by 4]].<br />
# ibdiagnet -lw <expected number of virtual lanes -ls <expected signaling rate> -c 1000<br />
<br />
* Consider [[#Upgrade firmware|upgrading firmware]].</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Samba/Active_Directory_domain_controller&diff=696716Samba/Active Directory domain controller2021-09-19T12:27:35Z<p>Pgoetz: my initial edit appears to be incorrect: apparently you cannot use timedatectl on a domain controller</p>
<hr />
<div>[[Category:Network sharing]]<br />
[[ja:Samba/Active Directory ドメインコントローラ]]<br />
[[ru:Samba (Русский)/Active Directory domain controller]]<br />
{{Related articles start}}<br />
{{Related|Active Directory Integration}}<br />
{{Related|Samba}}<br />
{{Related|SOGo}}<br />
{{Related articles end}}<br />
<br />
This article explains how to setup an Active Directory domain controller using [[Samba]]. It is assumed that all configuration files are in their unmodified, post-installation state. This article was written and tested on a fresh installation, with no modifications other than setting up a static IPv4 network connection (required). Finally, most of the commands below will require elevated privileges. Despite conventional wisdom, it may be easier to run these short few commands from a root session as opposed to obtaining rights on an as needed basis.<br />
<br />
== Installation ==<br />
<br />
{{Note|Make sure you can access the machines in your network via their hostname. See [[Network configuration#Local network hostname resolution]] for more information.}}<br />
<br />
A fully functional samba domain controller requires several programs beyond those included with the Samba distribution. [[Install]] the {{Pkg|bind}}, {{Pkg|krb5}}, {{Pkg|ntp}}, {{Pkg|python-dnspython}}, {{Pkg|openresolv}} and {{Pkg|samba}} packages from the official repositories.<br />
<br />
Samba contains its own fully functional DNS server, but if you need to maintain DNS zones for external domains, you are strongly encouraged to use [[BIND]] instead. If you need to share printers, you will also need [[CUPS]]. If needed, install the {{Pkg|bind}} and/or {{Pkg|cups}} packages.<br />
<br />
== Creating a new directory ==<br />
<br />
=== Provisioning ===<br />
<br />
The first step to creating an Active Directory domain is provisioning. This involves setting up the internal [[LDAP]], [[Kerberos]], and DNS servers and performing all of the basic configuration needed for the directory. If you have set up a directory server before, you are undoubtedly aware of the potential for errors in making these individual components work together as a single unit. The difficulty in doing so is the very reason that the Samba developers chose to provide internal versions of these programs. The server packages above were installed only for the client utilities. Provisioning is quite a bit easier with Samba. Just issue the following command:<br />
<br />
# samba-tool domain provision --use-rfc2307 --interactive<br />
<br />
==== Argument explanations ====<br />
<br />
;--use-rfc2307<br />
:this argument adds POSIX attributes (UID/GID) to the AD Schema. This will be necessary if you intend to authenticate Linux, BSD, or macOS clients (including the local machine) in addition to Microsoft Windows.<br />
<br />
;--interactive<br />
:this parameter forces the provision script to run interactively.<br />
<br />
Alternately, you can review the help for the provision step by running {{ic|samba-tool domain provision --help}}.<br />
<br />
==== Interactive provision explanations ====<br />
<br />
;Realm<br />
:'''INTERNAL.DOMAIN.COM''' - This should be the same as the DNS domain in all caps. It is common to use an internal-only sub-domain to separate your internal domain from your external DNS domains, but it is not required.<br />
<br />
;Domain<br />
:'''INTERNAL''' - This will be the NetBIOS domain name, usually the leftmost DNS sub-domain but can be anything you like. For example, the name INTERNAL would not be very descriptive. Perhaps company name or initials would be appropriate. This should be entered in all caps, and should have a 15 character maximum length for compatibility with older clients.<br />
<br />
;Server Role<br />
:'''dc''' - This article assumes that your are installing the first DC in a new domain. If you select anything different, the rest of this article will likely be useless to you.<br />
<br />
;DNS Backend<br />
:'''BIND9_DLZ''' or '''SAMBA_INTERNAL''' - This is down to personal preference of the server admin. Again, if you are hosting DNS for external domains, you are strongly encouraged to use the '''BIND9_DLZ''' backend so that flat zone files can continue to be used and existing transfer rules can co-exist with the internal DNS server. If unsure, use the '''SAMBA_INTERNAL''' backend.<br />
<br />
;DNS forwarder IP address<br />
: '''xxx.xxx.xxx.xxx''' or '''none''' - This option is only presented when using the SAMBA_INTERNAL DNS backend. Supply the IP address of a DNS server for forwarding non local DNS queries, or use the string '''none''' to always do root lookups.<br />
<br />
;Administrator password<br />
:'''xxxxxxxx''' - You must select a ''strong'' password for the administrator account. The minimum requirements are one upper case letter, one number, and at least eight characters. If you attempt to use a password that does not meet the complexity requirements, provisioning will fail.<br />
<br />
=== Configuring daemons ===<br />
<br />
==== NTPD ====<br />
<br />
Create a suitable NTP configuration for your network time server. See [[Network Time Protocol daemon]] for explanations of, and additional configuration options.<br />
<br />
Modify the {{ic|/etc/ntp.conf}} file with the following contents:<br />
<br />
{{hc|/etc/ntp.conf|<nowiki><br />
# Please consider joining the pool:<br />
#<br />
# http://www.pool.ntp.org/join.html<br />
#<br />
# For additional information see:<br />
# - https://wiki.archlinux.org/index.php/Network_Time_Protocol_daemon<br />
# - http://support.ntp.org/bin/view/Support/GettingStarted<br />
# - the ntp.conf man page<br />
<br />
# Associate to Arch's NTP pool<br />
server 0.arch.pool.ntp.org<br />
server 1.arch.pool.ntp.org<br />
server 2.arch.pool.ntp.org<br />
server 3.arch.pool.ntp.org<br />
<br />
# Restrictions<br />
restrict default kod limited nomodify notrap nopeer mssntp<br />
restrict 127.0.0.1<br />
restrict ::1<br />
restrict 0.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
restrict 1.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
restrict 2.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
restrict 3.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
<br />
# Location of drift file<br />
driftfile /var/lib/ntp/ntpd.drift<br />
<br />
# Location of the update directory<br />
ntpsigndsocket /var/lib/samba/ntp_signd/<br />
</nowiki>}}<br />
<br />
Create the state directory and set permissions:<br />
<br />
# install -d /var/lib/samba/ntp_signd<br />
# chown root:ntp /var/lib/samba/ntp_signd<br />
# chmod 0750 /var/lib/samba/ntp_signd<br />
<br />
Enable and start the {{ic|ntpd.service}} unit.<br />
<br />
==== BIND ====<br />
<br />
If you elected to use the '''BIND9_DLZ''' DNS backend, [[Install]] the {{Pkg|bind}} package and create the following BIND configuration. See [[BIND]] for explanations of, and additional configuration options. Be sure to replace the '''x''' characters with suitable values:<br />
<br />
Create the {{ic|/etc/named.conf}} file:<br />
<br />
{{hc|/etc/named.conf|<nowiki><br />
// vim:set ts=4 sw=4 et:<br />
acl local-networks {<br />
127.0.0.0/8;<br />
xxx.xxx.xxx.xxx/xx;<br />
// Uncomment the following line(s) if using IPv6<br />
//::1/128;<br />
//xxxx:xxxx:xxxx:xxxx::/64;<br />
};<br />
<br />
options {<br />
directory "/var/named";<br />
pid-file "/run/named/named.pid";<br />
session-keyfile "/run/named/session.key";<br />
<br />
// Uncomment this line to enable IPv6 connections support<br />
// listen-on-v6 { any; };<br />
// Add this for no IPv4:<br />
// listen-on { none; };<br />
<br />
// Add any subnets or hosts you want to allow to the local-networks acl<br />
allow-query { local-networks; };<br />
allow-recursion { local-networks; };<br />
allow-query-cache { local-networks; };<br />
allow-transfer { none; };<br />
allow-update { none; };<br />
<br />
version none;<br />
hostname none;<br />
server-id none;<br />
<br />
auth-nxdomain yes;<br />
datasize default;<br />
empty-zones-enable no;<br />
tkey-gssapi-keytab "/var/lib/samba/private/dns.keytab";<br />
<br />
// Uncomment if you wish to use ISP forwarders<br />
// forwarders { xxx.xxx.xxx.xxx; xxx.xxx.xxx.xxx; };<br />
};<br />
<br />
zone "localhost" IN {<br />
type master;<br />
file "localhost.zone";<br />
};<br />
<br />
zone "0.0.127.in-addr.arpa" IN {<br />
type master;<br />
file "127.0.0.zone";<br />
};<br />
<br />
zone "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa" {<br />
type master;<br />
file "localhost.ip6.zone";<br />
};<br />
<br />
// Load AD integrated zones<br />
dlz "AD DNS Zones" {<br />
database "dlopen /usr/lib/samba/bind9/dlz_bind9_12.so";<br />
};<br />
<br />
//zone "example.org" IN {<br />
// type slave;<br />
// file "example.zone";<br />
// masters {<br />
// 192.168.1.100;<br />
// };<br />
// allow-query { any; };<br />
// allow-transfer { any; };<br />
//};<br />
<br />
logging {<br />
channel xfer-log {<br />
file "/var/log/named.log";<br />
print-category yes;<br />
print-severity yes;<br />
severity info;<br />
};<br />
category xfer-in { xfer-log; };<br />
category xfer-out { xfer-log; };<br />
category notify { xfer-log; };<br />
};<br />
</nowiki>}}<br />
<br />
Set permissions:<br />
<br />
# chgrp named /var/lib/samba/private/dns.keytab<br />
# chmod g+r /var/lib/samba/private/dns.keytab<br />
# touch /var/log/named.log<br />
# chown root:named /var/log/named.log<br />
# chmod 664 /var/log/named.log<br />
<br />
Enable and start the {{ic|named.service}} unit.<br />
<br />
Good values for forwarders are your ISP's DNS servers. Google (8.8.8.8, 8.8.4.4, 2001:4860:4860::8888, and 2001:4860:4860::8844) and OpenDNS (208.67.222.222, 208.67.220.220, 2620:0:ccc::2 and 2620:0:ccd::2) provide suitable public DNS servers free of charge. Appropriate values for subnets are specific to your network.<br />
<br />
==== Kerberos client utilities ====<br />
<br />
The provisioning step above created a perfectly valid krb5.conf file for use with a Samba domain controller. Install it with the following commands:<br />
<br />
# mv /etc/krb5.conf{,.default}<br />
# cp /var/lib/samba/private/krb5.conf /etc<br />
<br />
==== DNS ====<br />
<br />
You will need to begin using the local DNS server now. Reconfigure resolvconf to use only localhost for DNS lookups. Create the {{ic|/etc/resolv.conf.tail}} (do not forget to substitute '''internal.domain.tld''' with your internal domain):<br />
<br />
# Samba configuration<br />
search '''internal.domain.tld'''<br />
# If using IPv6, uncomment the following line<br />
#nameserver ::1<br />
nameserver 127.0.0.1<br />
<br />
Set permissions and regenerate the new {{ic|/etc/resolv.conf}} file:<br />
<br />
# chmod 644 /etc/resolv.conf.tail<br />
# resolvconf -u<br />
<br />
==== Samba ====<br />
<br />
Enable and start the {{ic|samba.service}} unit. If you intend to use the LDB utilities, you will also need create the {{ic|/etc/profile.d/sambaldb.sh}} file to set '''LDB_MODULES_PATH''':<br />
<br />
export LDB_MODULES_PATH="${LDB_MODULES_PATH}:/usr/lib/samba/ldb"<br />
<br />
Set permissions on the file and source it:<br />
# chmod 0755 /etc/profile.d/sambaldb.sh<br />
# . /etc/profile.d/sambaldb.sh<br />
<br />
=== Testing the installation ===<br />
<br />
==== DNS ====<br />
<br />
First, verify that DNS is working as expected. Execute the following commands substituting appropriate values for '''internal.domain.com''' and '''server''':<br />
<br />
# host -t SRV _ldap._tcp.'''internal.domain.com'''.<br />
# host -t SRV _kerberos._udp.'''internal.domain.com'''.<br />
# host -t A '''server'''.'''internal.domain.com'''.<br />
<br />
You should receive output similar to the following:<br />
<br />
{{bc|_ldap._tcp.internal.domain.com has SRV record 0 100 389 server.internal.domain.com.<br />
_kerberos._udp.internal.domain.com has SRV record 0 100 88 server.internal.domain.com.<br />
server.internal.domain.com has address xxx.xxx.xxx.xxx}}<br />
<br />
==== NT authentication ====<br />
<br />
Next, verify that password authentication is working as expected:<br />
<br />
# smbclient //localhost/netlogon -U Administrator -c 'ls'<br />
<br />
You will be prompted for a password (the one you selected earlier), and will get a directory listing like the following:<br />
<br />
{{bc| . D 0 Wed Nov 27 23:59:07 2013<br />
.. D 0 Wed Nov 27 23:59:12 2013<br />
<br />
50332 blocks of size 2097152. 47185 blocks available}}<br />
<br />
==== Kerberos ====<br />
<br />
Now verify that the KDC is working as expected. Be sure to replace '''INTERNAL.DOMAIN.COM''' and use upper case letters:<br />
<br />
# kinit administrator@'''INTERNAL.DOMAIN.COM'''<br />
<br />
You should be prompted for a password and get output similar to the following:<br />
<br />
{{bc|Warning: Your password will expire in 41 days on Wed 08 Jan 2014 11:59:11 PM CST}}<br />
<br />
Verify that you actually got a ticket:<br />
<br />
# klist<br />
<br />
You should get output similar to below:<br />
<br />
{{bc|Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: administrator@INTERNAL.DOMAIN.COM<br />
<br />
Valid starting Expires Service principal<br />
11/28/2013 00:22:17 11/28/2013 10:22:17 krbtgt/INTERNAL.DOMAIN.COM@INTERNAL.DOMAIN.COM<br />
renew until 11/29/2013 00:22:14}}<br />
<br />
As a final test, use smbclient with your recently acquired ticket. Replace '''server''' with the correct server name:<br />
<br />
# smbclient //'''server'''/netlogon -k -c 'ls'<br />
<br />
The output should be the same as when testing password authentication above.<br />
<br />
=== Additional configuration ===<br />
<br />
==== DNS ====<br />
<br />
You will also need to create a reverse lookup zone for each subnet in your environment in DNS. It is important that this is kept in Samba's DNS as opposed to BIND to allow for dynamic updates by cleints. For each subnet, create a reverse lookup zone with the following commands. Replace '''server'''.'''internal'''.'''domain'''.'''tld''' and '''xxx'''.'''xxx'''.'''xxx''' with appropriate values. For '''xxx'''.'''xxx'''.'''xxx''', use the first three octets of the subnet in reverse order (for example: 192.168.0.0/24 becomes 0.168.192):<br />
<br />
# samba-tool dns zonecreate '''server'''.'''internal'''.'''domain'''.'''tld''' '''xxx'''.'''xxx'''.'''xxx'''.in-addr.arpa -U Administrator<br />
<br />
Now, add a record for you server (if your server is multi-homed, add for each subnet) again substituting appropriate values as above. '''zzz''' will be replaced by the fourth octet of the IP for the server:<br />
<br />
# samba-tool dns add '''server'''.'''internal'''.'''domain'''.'''tld''' '''xxx'''.'''xxx'''.'''xxx'''.in-addr.arpa '''zzz''' PTR '''server'''.'''internal'''.'''domain'''.'''tld''' -U Administrator<br />
<br />
Restart the {{ic|samba}} service. If using BIND for DNS, restart the {{ic|named}} service as well.<br />
<br />
Finally, test the lookup. Replace '''xxx'''.'''xxx'''.'''xxx'''.'''xxx''' with the IP of your server:<br />
<br />
# host -t PTR '''xxx'''.'''xxx'''.'''xxx'''.'''xxx'''<br />
<br />
You should get output similar to the following:<br />
<br />
xxx.xxx.xxx.xxx.in-addr.arpa domain name pointer server.internal.domain.tld.<br />
<br />
==== TLS ====<br />
<br />
TLS support is not enabled by default, however, a default certificate was created when the DC was brought up. With the release of Samba 4.3.8 and 4.2.2, unsecured LDAP binds are disabled by default, and you must configure TLS to use Samba as an authentication source (without reducing the security of your Samba installation). To use the default keys, append the following lines to the "'''[global]'''" section of the {{ic|/etc/samba/smb.conf}} file:<br />
<br />
tls enabled = yes<br />
tls keyfile = tls/key.pem<br />
tls certfile = tls/cert.pem<br />
tls cafile = tls/ca.pem<br />
<br />
If a trusted certificate is needed, create a signing key and a certificate request (see [[OpenSSL]] for detailed instructions). Get the request signed by your chosen certificate authority, and put into this directory. If your certificate authority also needs an intermediate certificate, concatenate the certs (server cert first, then intermediate) and leave '''tls cafile''' blank.<br />
<br />
Restart {{ic|samba}} for the changes to take effect.<br />
<br />
== Adding a second domain controller to an existing domain ==<br />
<br />
=== Prerequisites ===<br />
<br />
As with the provisioning setup when setting up a new domain, you must have {{Pkg|ntp}} configured per [[#NTPD|the above instructions]]. Additionally, some of the arguments and parameters on the original domain setup must be replicated here.<br />
<br />
==== Argument explanations ====<br />
<br />
;--option='idmap_ldb<nowiki>:</nowiki>use rfc2307 = yes'<br />
: this is required if you elected to include Unix UID/GID support on your existing domain (using the '''--use-rfc2307''' option for Samba's provision step or applied the RFC 2307 schema extensions).<br />
<br />
;--dns-backend='''DNSTYPE'''<br />
:replace '''DNSTYPE''' with '''BIND9_DLZ''' or '''SAMBA_INTERNAL''' - This is again down to personal preference of the server admin. If using '''BIND9_DLZ''' backend, you will need to configure {{Pkg|bind}} as per [[#BIND|the above instructions]] after joining the domain.<br />
<br />
;--option="dns forwarder="'''xxx.xxx.xxx.xxx'''"<br />
:this is only valid for the SAMBA_INTERNAL DNS backend which allows you to specify a DNS forwarder. Replace '''xxx.xxx.xxx.xxx''' with appropriate value. <br />
<br />
;--site='''SITE'''<br />
:if you have multiple sites defined, use this to join directly in that site.<br />
<br />
See the output of {{ic|samba-tool domain join --help}} for additional options.<br />
<br />
=== Joining an existing domain as a new DC ===<br />
<br />
Execute the following command (adding any necessary parameters above to the end of the command):<br />
<br />
# samba-tool domain join '''internal.domain.tld''' DC -U"'''INTERNAL'''\'''administrator'''"<br />
<br />
Now copy the {{ic|krb5.conf}}:<br />
<br />
# cp /var/lib/samba/private/krb5.conf /etc/krb5.conf<br />
<br />
If you used the RFC 2307 schema extensions, you need to copy the idmap from an existing DC. If using Samba, execute the following command from another DC:<br />
<br />
# tdbbackup -s .bak /var/lib/samba/private/idmap.ldb<br />
<br />
This will generate a file {{ic|/var/lib/samba/private/idmap.ldb.bak}}, transfer this file to the new server in the {{ic|/var/lib/samba/private}} directory, removing the .bak extension. If you intend to keep multiple DCs, you will need to automate this process going forward using one of the methods listed on the Samba website [https://wiki.samba.org/index.php/Joining_a_Samba_DC_to_an_Existing_Active_Directory#Built-in_User_.26_Group_ID_Mappings here]. This also applies to transferring the idmap from Windows DCs.<br />
<br />
Enable and start the {{ic|samba.service}} unit.<br />
<br />
If using BIND9_DLZ DNS backend, and the {{ic|/var/lib/samba/private/dns}} directory is not created, run the following command (ignore warning about updating named.conf):<br />
<br />
# samba_upgradedns --dns-backend=BIND9_DLZ<br />
<br />
Restart the {{ic|named.service}} and then update the DNS records with the following command:<br />
<br />
# samba_dnsupdate --all-names --use-samba-tool --verbose<br />
<br />
Now proceed with LDB configuration and testing as with a new domain [[#Samba|here]].<br />
<br />
=== Transferring the FSMO roles ===<br />
<br />
If this is intended to replace an existing domain controller, you will need to transfer the FSMO roles before demoting the existing DC. This is currently outside the scope of this document. See the Samba wiki [https://wiki.samba.org/index.php/Transferring_and_Seizing_FSMO_Roles here].<br />
<br />
== Additional Services ==<br />
<br />
=== Printing ===<br />
<br />
By default, a Samba server, when configured as a domain controller, does not enable printing by default. You will need to add the following lines to the global section of the {{ic|/etc/samba/smb.conf}} file:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
...<br />
rpc_server:spoolss = external<br />
rpc_daemon:spoolssd = fork<br />
printing = CUPS<br />
...<br />
[printers]<br />
path = /var/spool/samba/<br />
printable = yes<br />
</nowiki>}}<br />
<br />
The above configuration will enable automatic sharing of all CUPS print queues. If you wish to share only specific print queues, you will want to add the following additional lines (removing the '''[printers]''' share above):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
...<br />
load printers = no<br />
...<br />
# Add and example print share<br />
[HPDJ3050]<br />
path = /var/spool/samba/<br />
printable = yes<br />
printer name = hpdj3050<br />
</nowiki>}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== DHCP with dynamic DNS updates ===<br />
<br />
It should be noted that using this method will affect functionality of windows clients, as they will still attempt to update DNS on their own. When this occurs, the machine will be denied permission to do so as the record will be owned by the dhcp user rather than the machine account. While this is essentially harmless, it will generate warnings in the system log of the offending machine. You should create a GPO to overcome this, but unfortunately, Samba does not yet have a command line utility to modify GPOs. You will need a Windows PC with the RSAT tools installed. Simply create a dedicated GPO with the Group Policy Editor, and apply only to OUs that contain workstations using DHCP (so that Samba/Windows servers and statically configured Samba/Windows clients can still update using 'ipconfig /registerdns') and configure the following settings:<br />
<br />
{{bc|1=Computer Configuration<br />
Policies<br />
Administrative Templates<br />
Network<br />
DNS Client<br />
Dynamic Update = Disabled<br />
Register PTR Records = Disabled}}<br />
<br />
[[Install]] the {{Pkg|dhcp}}, {{Pkg|sudo}}, and the {{AUR|samba-dhcpd-update}} packages.<br />
<br />
Create an unprivileged user in AD for performing the updates. When prompted for password, use a secure password. 63 random, mixed case, alpha-numeric characters is sufficient. Optionally samba-tool also takes a random argument:<br />
<br />
# samba-tool user create dhcp --description="Unprivileged user for DNS updates via DHCP server"<br />
<br />
Since this is a service account, disabling password expiration on the user account is recommended, but not required:<br />
<br />
# samba-tool user setexpiry dhcp --noexpiry<br />
<br />
Give the user privileges to administer DNS:<br />
# samba-tool group addmembers DnsAdmins dhcp<br />
<br />
Export the users credentials to a private keytab:<br />
# samba-tool domain exportkeytab --principal=dhcp@'''INTERNAL'''.'''DOMAIN'''.'''TLD''' dhcpd.keytab<br />
# install -vdm 755 /etc/dhcpd<br />
# mv dhcpd.keytab /etc/dhcpd<br />
# chown root:root /etc/dhcpd/dhcpd.keytab<br />
# chmod 400 /etc/dhcpd/dhcpd.keytab<br />
<br />
Modify the {{ic|dhcpd-update-samba-dns.conf}} file with the following commands (substituting correct values for '''server''', '''internal'''.'''domain'''.'''tld''', and '''INTERNAL'''.'''DOMAIN'''.'''TLD'''):<br />
<br />
{{hc|/etc/dhcpd/dhcpd-update-samba-dns.conf|<nowiki><br />
# Variables<br />
KRB5CC="/tmp/dhcpd4.krb5cc"<br />
KEYTAB="/etc/dhcpd/dhcpd.keytab"<br />
DOMAIN=</nowiki>"'''internal'''.'''domain'''.'''tld'''"<nowiki><br />
REALM=</nowiki>"'''INTERNAL'''.'''DOMAIN'''.'''TLD'''"<nowiki><br />
PRINCIPAL="dhcp@${REALM}"<br />
NAMESERVER="</nowiki>'''server'''<nowiki>.${DOMAIN}"<br />
ZONE="${DOMAIN}"<br />
</nowiki>}}<br />
<br />
Grant the dhcp user account permissions to run the update script without a password prompt (replace '''server''' with the hostname of the server):<br />
<br />
{{hc|/etc/sudoers.d/dhcp-update|<nowiki><br />
dhcp </nowiki>'''server'''<nowiki> = (root) NOPASSWD: /usr/bin/dhcpd-update-samba-dns.sh<br />
</nowiki>}}<br />
<br />
Configure the dhcpd server following the [[dhcpd]] article and add the following to all subnet declarations in the {{ic|/etc/dhcpd.conf}} file that provide DHCP service:<br />
<br />
{{bc|<nowiki><br />
on commit {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "add", ClientIP, ClientName);<br />
}<br />
<br />
on release {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
}<br />
<br />
on expiry {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
</nowiki>}}<br />
<br />
Here is a complete example {{ic|/etc/dhcpd.conf}} file for reference:<br />
<br />
{{hc|/etc/dhcpd.conf|<nowiki><br />
<br />
subnet </nowiki>'''192.168.1.0''' netmask '''255.255.255.0'''<nowiki> {<br />
range </nowiki>'''192.168.1.100''' '''192.168.1.199'''<nowiki>;<br />
option subnet-mask </nowiki>'''255.255.255.0'''<nowiki>;<br />
option routers </nowiki>'''192.168.1.254'''<nowiki>;<br />
option domain-name "</nowiki>'''internal.domain.tld'''<nowiki>";<br />
option domain-name-servers </nowiki>'''192.168.1.1'''<nowiki>;<br />
option broadcast-address </nowiki>'''192.168.1.255'''<nowiki>;<br />
default-lease-time 28800;<br />
max-lease-time 43200;<br />
authoritative;<br />
<br />
on commit {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "add", ClientIP, ClientName);<br />
}<br />
<br />
on release {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
}<br />
<br />
on expiry {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
}<br />
}<br />
</nowiki>}}<br />
<br />
Finally, enable and start (or restart) the {{ic|dhcpd4}} service.<br />
<br />
=== Transferring users from one directory to another ===<br />
<br />
Unfortunately, there is no built-in utility to export users from one directory to another. This is one way, albeit exceptionally ugly, to get the user specific fields out of your existing SAM and into a suitable LDIF format for ldbmodify:<br />
<br />
ldbsearch -H /var/lib/samba/private/sam.ldb \<br />
-s sub -b cn=Users,dc='''internal''',dc='''domain''',dc='''tld''' '(objectClass=user)' | \<br />
grep -e "^\# record" -e "^accountExpires:" -e "^c:" -e "^cn:" -e "^co:" -e "^codePage:" \<br />
-e "^comment:" -e "^company:" -e "^countryCode:" -e "^department:" \<br />
-e "^description:" -e "^displayName" -e "^displayNamePrintable:" \<br />
-e "^distinguishedName" -e "^division:" -e "^dn:" -e "^employeeID:" \<br />
-e "^facsimileTelephoneNumber:" -e "^generationQualifier:" \<br />
-e "^givenName" -e "^homeDirectory:" -e "^homeDrive:" -e "^homePhone:" \<br />
-e "^homePostalAddress:" -e "^info:" -e "^initials:" \<br />
-e "^internationalISDNNumber:" -e "^ipPhone:" -e "^l:" -e "^mail:" \<br />
-e "^manager:" -e "^middleName:" -e "^mobile:" -e "^name:" -e "^o:" \<br />
-e "^objectClass" -e "^otherFacsimileTelephoneNumber:" \<br />
-e "^otherHomePhone:" -e "^otherIpPhone:" -e "^otherMailbox:" \<br />
-e "^otherMobile:" -e "^otherPager:" -e "^otherTelephone:" -e "^pager:" \<br />
-e "^personalTitle:" -e "^physicalDeliveryOfficeName:" -e "^postalAddress:" \<br />
-e "^postalCode:" -e "^postOfficeBox:" -e "^proxyAddresses\: SMTP" \<br />
-e "^proxyAddresses: smtp" -e "^referredDeliveryMethod:" \<br />
-e "^primaryInternationalISDNNumber:" -e "^primaryTelexNumber:" \<br />
-e "^profilePath:" -e "^registeredAddress:" -e "^sAMAccountName:" \<br />
-e "^scriptPath:" -e "^sn:" -e "^st:" -e "^street:" -e "^streetAddress:" \<br />
-e "^telephoneNumber:" -e "^teletexTerminalIdentifier:" \<br />
-e "^telexNumber:" -e "^title:" -e "^userAccountControl:" -e "^userPrincipalName:"\<br />
-e "^url:" -e "^userSharedFolder:" -e "^userSharedFolderOther:" -e "^wWWHomePage:" | \<br />
sed '/^dn:.*/ a\changetype: add' | sed '/^# record/ i\\n' > user-export.ldif<br />
<br />
Explanation: Run an ldbsearch in the users container only, using sub-tree search for objectclass=user. If you need the whole directory, you can modify the search base to use the root or some other OU. The output from ldbsearch is then piped into a really long grep command that returns only appropriate attributes to keep in the new directory. This is obviously subjective, and probably should be tailored to your specific use case. Finally, we use sed to insert the changetype line (needed to tell ldbmodify that we are adding a user), and prefix with a blank line (to make it easier to read) for each exported object.<br />
<br />
{{Note|You will need to modify the output file and remove any objects that you do not want transferred. The output file will contain objects (service users, built-ins, etc.) that can break your new directory if you fail to remove them! It will also contain the old domain in both the "dn" and "distinguishedName" attributies that must be changed before import.}}<br />
<br />
To import, after editing the file and transferring to the new server, simply run the following command on your new samba domain controller:<br />
<br />
ldbmodify -H /var/lib/samba/private/sam.ldb user-export.ldif<br />
<br />
=== Password Complexity ===<br />
<br />
By default, Samba requires strong passwords. To disable the complexity check, issue the following command:<br />
<br />
{{bc|# samba-tool domain passwordsettings set --complexity&#61;off}}<br />
<br />
Set [https://wiki.samba.org/index.php/Password_Settings_Objects Password Settings Objects] in the Samba wiki for more information</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Samba/Active_Directory_domain_controller&diff=696309Samba/Active Directory domain controller2021-09-17T13:39:58Z<p>Pgoetz: reverting system-resolved comment, as that appears to be incorrect.</p>
<hr />
<div>[[Category:Network sharing]]<br />
[[ja:Samba/Active Directory ドメインコントローラ]]<br />
[[ru:Samba (Русский)/Active Directory domain controller]]<br />
{{Related articles start}}<br />
{{Related|Active Directory Integration}}<br />
{{Related|Samba}}<br />
{{Related|SOGo}}<br />
{{Related articles end}}<br />
<br />
This article explains how to setup an Active Directory domain controller using [[Samba]]. It is assumed that all configuration files are in their unmodified, post-installation state. This article was written and tested on a fresh installation, with no modifications other than setting up a static IPv4 network connection (required). Finally, most of the commands below will require elevated privileges. Despite conventional wisdom, it may be easier to run these short few commands from a root session as opposed to obtaining rights on an as needed basis.<br />
<br />
== Installation ==<br />
<br />
{{Note|Make sure you can access the machines in your network via their hostname. See [[Network configuration#Local network hostname resolution]] for more information.}}<br />
<br />
A fully functional samba domain controller requires several programs beyond those included with the Samba distribution. [[Install]] the {{Pkg|bind}}, {{Pkg|krb5}}, {{Pkg|ntp}}, {{Pkg|python-dnspython}}, {{Pkg|openresolv}} and {{Pkg|samba}} packages from the official repositories.<br />
<br />
Samba contains its own fully functional DNS server, but if you need to maintain DNS zones for external domains, you are strongly encouraged to use [[BIND]] instead. If you need to share printers, you will also need [[CUPS]]. If needed, install the {{Pkg|bind}} and/or {{Pkg|cups}} packages.<br />
<br />
Note that you can use [[timedatectl]] as an alternative to {{Pkg|ntp}}. This tool is included in the {{Pkg|systemd}} package.<br />
<br />
== Creating a new directory ==<br />
<br />
=== Provisioning ===<br />
<br />
The first step to creating an Active Directory domain is provisioning. This involves setting up the internal [[LDAP]], [[Kerberos]], and DNS servers and performing all of the basic configuration needed for the directory. If you have set up a directory server before, you are undoubtedly aware of the potential for errors in making these individual components work together as a single unit. The difficulty in doing so is the very reason that the Samba developers chose to provide internal versions of these programs. The server packages above were installed only for the client utilities. Provisioning is quite a bit easier with Samba. Just issue the following command:<br />
<br />
# samba-tool domain provision --use-rfc2307 --interactive<br />
<br />
==== Argument explanations ====<br />
<br />
;--use-rfc2307<br />
:this argument adds POSIX attributes (UID/GID) to the AD Schema. This will be necessary if you intend to authenticate Linux, BSD, or macOS clients (including the local machine) in addition to Microsoft Windows.<br />
<br />
;--interactive<br />
:this parameter forces the provision script to run interactively.<br />
<br />
Alternately, you can review the help for the provision step by running {{ic|samba-tool domain provision --help}}.<br />
<br />
==== Interactive provision explanations ====<br />
<br />
;Realm<br />
:'''INTERNAL.DOMAIN.COM''' - This should be the same as the DNS domain in all caps. It is common to use an internal-only sub-domain to separate your internal domain from your external DNS domains, but it is not required.<br />
<br />
;Domain<br />
:'''INTERNAL''' - This will be the NetBIOS domain name, usually the leftmost DNS sub-domain but can be anything you like. For example, the name INTERNAL would not be very descriptive. Perhaps company name or initials would be appropriate. This should be entered in all caps, and should have a 15 character maximum length for compatibility with older clients.<br />
<br />
;Server Role<br />
:'''dc''' - This article assumes that your are installing the first DC in a new domain. If you select anything different, the rest of this article will likely be useless to you.<br />
<br />
;DNS Backend<br />
:'''BIND9_DLZ''' or '''SAMBA_INTERNAL''' - This is down to personal preference of the server admin. Again, if you are hosting DNS for external domains, you are strongly encouraged to use the '''BIND9_DLZ''' backend so that flat zone files can continue to be used and existing transfer rules can co-exist with the internal DNS server. If unsure, use the '''SAMBA_INTERNAL''' backend.<br />
<br />
;DNS forwarder IP address<br />
: '''xxx.xxx.xxx.xxx''' or '''none''' - This option is only presented when using the SAMBA_INTERNAL DNS backend. Supply the IP address of a DNS server for forwarding non local DNS queries, or use the string '''none''' to always do root lookups.<br />
<br />
;Administrator password<br />
:'''xxxxxxxx''' - You must select a ''strong'' password for the administrator account. The minimum requirements are one upper case letter, one number, and at least eight characters. If you attempt to use a password that does not meet the complexity requirements, provisioning will fail.<br />
<br />
=== Configuring daemons ===<br />
<br />
==== NTPD ====<br />
<br />
Create a suitable NTP configuration for your network time server. See [[Network Time Protocol daemon]] for explanations of, and additional configuration options.<br />
<br />
Modify the {{ic|/etc/ntp.conf}} file with the following contents:<br />
<br />
{{hc|/etc/ntp.conf|<nowiki><br />
# Please consider joining the pool:<br />
#<br />
# http://www.pool.ntp.org/join.html<br />
#<br />
# For additional information see:<br />
# - https://wiki.archlinux.org/index.php/Network_Time_Protocol_daemon<br />
# - http://support.ntp.org/bin/view/Support/GettingStarted<br />
# - the ntp.conf man page<br />
<br />
# Associate to Arch's NTP pool<br />
server 0.arch.pool.ntp.org<br />
server 1.arch.pool.ntp.org<br />
server 2.arch.pool.ntp.org<br />
server 3.arch.pool.ntp.org<br />
<br />
# Restrictions<br />
restrict default kod limited nomodify notrap nopeer mssntp<br />
restrict 127.0.0.1<br />
restrict ::1<br />
restrict 0.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
restrict 1.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
restrict 2.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
restrict 3.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
<br />
# Location of drift file<br />
driftfile /var/lib/ntp/ntpd.drift<br />
<br />
# Location of the update directory<br />
ntpsigndsocket /var/lib/samba/ntp_signd/<br />
</nowiki>}}<br />
<br />
Create the state directory and set permissions:<br />
<br />
# install -d /var/lib/samba/ntp_signd<br />
# chown root:ntp /var/lib/samba/ntp_signd<br />
# chmod 0750 /var/lib/samba/ntp_signd<br />
<br />
Enable and start the {{ic|ntpd.service}} unit.<br />
<br />
==== BIND ====<br />
<br />
If you elected to use the '''BIND9_DLZ''' DNS backend, [[Install]] the {{Pkg|bind}} package and create the following BIND configuration. See [[BIND]] for explanations of, and additional configuration options. Be sure to replace the '''x''' characters with suitable values:<br />
<br />
Create the {{ic|/etc/named.conf}} file:<br />
<br />
{{hc|/etc/named.conf|<nowiki><br />
// vim:set ts=4 sw=4 et:<br />
acl local-networks {<br />
127.0.0.0/8;<br />
xxx.xxx.xxx.xxx/xx;<br />
// Uncomment the following line(s) if using IPv6<br />
//::1/128;<br />
//xxxx:xxxx:xxxx:xxxx::/64;<br />
};<br />
<br />
options {<br />
directory "/var/named";<br />
pid-file "/run/named/named.pid";<br />
session-keyfile "/run/named/session.key";<br />
<br />
// Uncomment this line to enable IPv6 connections support<br />
// listen-on-v6 { any; };<br />
// Add this for no IPv4:<br />
// listen-on { none; };<br />
<br />
// Add any subnets or hosts you want to allow to the local-networks acl<br />
allow-query { local-networks; };<br />
allow-recursion { local-networks; };<br />
allow-query-cache { local-networks; };<br />
allow-transfer { none; };<br />
allow-update { none; };<br />
<br />
version none;<br />
hostname none;<br />
server-id none;<br />
<br />
auth-nxdomain yes;<br />
datasize default;<br />
empty-zones-enable no;<br />
tkey-gssapi-keytab "/var/lib/samba/private/dns.keytab";<br />
<br />
// Uncomment if you wish to use ISP forwarders<br />
// forwarders { xxx.xxx.xxx.xxx; xxx.xxx.xxx.xxx; };<br />
};<br />
<br />
zone "localhost" IN {<br />
type master;<br />
file "localhost.zone";<br />
};<br />
<br />
zone "0.0.127.in-addr.arpa" IN {<br />
type master;<br />
file "127.0.0.zone";<br />
};<br />
<br />
zone "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa" {<br />
type master;<br />
file "localhost.ip6.zone";<br />
};<br />
<br />
// Load AD integrated zones<br />
dlz "AD DNS Zones" {<br />
database "dlopen /usr/lib/samba/bind9/dlz_bind9_12.so";<br />
};<br />
<br />
//zone "example.org" IN {<br />
// type slave;<br />
// file "example.zone";<br />
// masters {<br />
// 192.168.1.100;<br />
// };<br />
// allow-query { any; };<br />
// allow-transfer { any; };<br />
//};<br />
<br />
logging {<br />
channel xfer-log {<br />
file "/var/log/named.log";<br />
print-category yes;<br />
print-severity yes;<br />
severity info;<br />
};<br />
category xfer-in { xfer-log; };<br />
category xfer-out { xfer-log; };<br />
category notify { xfer-log; };<br />
};<br />
</nowiki>}}<br />
<br />
Set permissions:<br />
<br />
# chgrp named /var/lib/samba/private/dns.keytab<br />
# chmod g+r /var/lib/samba/private/dns.keytab<br />
# touch /var/log/named.log<br />
# chown root:named /var/log/named.log<br />
# chmod 664 /var/log/named.log<br />
<br />
Enable and start the {{ic|named.service}} unit.<br />
<br />
Good values for forwarders are your ISP's DNS servers. Google (8.8.8.8, 8.8.4.4, 2001:4860:4860::8888, and 2001:4860:4860::8844) and OpenDNS (208.67.222.222, 208.67.220.220, 2620:0:ccc::2 and 2620:0:ccd::2) provide suitable public DNS servers free of charge. Appropriate values for subnets are specific to your network.<br />
<br />
==== Kerberos client utilities ====<br />
<br />
The provisioning step above created a perfectly valid krb5.conf file for use with a Samba domain controller. Install it with the following commands:<br />
<br />
# mv /etc/krb5.conf{,.default}<br />
# cp /var/lib/samba/private/krb5.conf /etc<br />
<br />
==== DNS ====<br />
<br />
You will need to begin using the local DNS server now. Reconfigure resolvconf to use only localhost for DNS lookups. Create the {{ic|/etc/resolv.conf.tail}} (do not forget to substitute '''internal.domain.tld''' with your internal domain):<br />
<br />
# Samba configuration<br />
search '''internal.domain.tld'''<br />
# If using IPv6, uncomment the following line<br />
#nameserver ::1<br />
nameserver 127.0.0.1<br />
<br />
Set permissions and regenerate the new {{ic|/etc/resolv.conf}} file:<br />
<br />
# chmod 644 /etc/resolv.conf.tail<br />
# resolvconf -u<br />
<br />
==== Samba ====<br />
<br />
Enable and start the {{ic|samba.service}} unit. If you intend to use the LDB utilities, you will also need create the {{ic|/etc/profile.d/sambaldb.sh}} file to set '''LDB_MODULES_PATH''':<br />
<br />
export LDB_MODULES_PATH="${LDB_MODULES_PATH}:/usr/lib/samba/ldb"<br />
<br />
Set permissions on the file and source it:<br />
# chmod 0755 /etc/profile.d/sambaldb.sh<br />
# . /etc/profile.d/sambaldb.sh<br />
<br />
=== Testing the installation ===<br />
<br />
==== DNS ====<br />
<br />
First, verify that DNS is working as expected. Execute the following commands substituting appropriate values for '''internal.domain.com''' and '''server''':<br />
<br />
# host -t SRV _ldap._tcp.'''internal.domain.com'''.<br />
# host -t SRV _kerberos._udp.'''internal.domain.com'''.<br />
# host -t A '''server'''.'''internal.domain.com'''.<br />
<br />
You should receive output similar to the following:<br />
<br />
{{bc|_ldap._tcp.internal.domain.com has SRV record 0 100 389 server.internal.domain.com.<br />
_kerberos._udp.internal.domain.com has SRV record 0 100 88 server.internal.domain.com.<br />
server.internal.domain.com has address xxx.xxx.xxx.xxx}}<br />
<br />
==== NT authentication ====<br />
<br />
Next, verify that password authentication is working as expected:<br />
<br />
# smbclient //localhost/netlogon -U Administrator -c 'ls'<br />
<br />
You will be prompted for a password (the one you selected earlier), and will get a directory listing like the following:<br />
<br />
{{bc| . D 0 Wed Nov 27 23:59:07 2013<br />
.. D 0 Wed Nov 27 23:59:12 2013<br />
<br />
50332 blocks of size 2097152. 47185 blocks available}}<br />
<br />
==== Kerberos ====<br />
<br />
Now verify that the KDC is working as expected. Be sure to replace '''INTERNAL.DOMAIN.COM''' and use upper case letters:<br />
<br />
# kinit administrator@'''INTERNAL.DOMAIN.COM'''<br />
<br />
You should be prompted for a password and get output similar to the following:<br />
<br />
{{bc|Warning: Your password will expire in 41 days on Wed 08 Jan 2014 11:59:11 PM CST}}<br />
<br />
Verify that you actually got a ticket:<br />
<br />
# klist<br />
<br />
You should get output similar to below:<br />
<br />
{{bc|Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: administrator@INTERNAL.DOMAIN.COM<br />
<br />
Valid starting Expires Service principal<br />
11/28/2013 00:22:17 11/28/2013 10:22:17 krbtgt/INTERNAL.DOMAIN.COM@INTERNAL.DOMAIN.COM<br />
renew until 11/29/2013 00:22:14}}<br />
<br />
As a final test, use smbclient with your recently acquired ticket. Replace '''server''' with the correct server name:<br />
<br />
# smbclient //'''server'''/netlogon -k -c 'ls'<br />
<br />
The output should be the same as when testing password authentication above.<br />
<br />
=== Additional configuration ===<br />
<br />
==== DNS ====<br />
<br />
You will also need to create a reverse lookup zone for each subnet in your environment in DNS. It is important that this is kept in Samba's DNS as opposed to BIND to allow for dynamic updates by cleints. For each subnet, create a reverse lookup zone with the following commands. Replace '''server'''.'''internal'''.'''domain'''.'''tld''' and '''xxx'''.'''xxx'''.'''xxx''' with appropriate values. For '''xxx'''.'''xxx'''.'''xxx''', use the first three octets of the subnet in reverse order (for example: 192.168.0.0/24 becomes 0.168.192):<br />
<br />
# samba-tool dns zonecreate '''server'''.'''internal'''.'''domain'''.'''tld''' '''xxx'''.'''xxx'''.'''xxx'''.in-addr.arpa -U Administrator<br />
<br />
Now, add a record for you server (if your server is multi-homed, add for each subnet) again substituting appropriate values as above. '''zzz''' will be replaced by the fourth octet of the IP for the server:<br />
<br />
# samba-tool dns add '''server'''.'''internal'''.'''domain'''.'''tld''' '''xxx'''.'''xxx'''.'''xxx'''.in-addr.arpa '''zzz''' PTR '''server'''.'''internal'''.'''domain'''.'''tld''' -U Administrator<br />
<br />
Restart the {{ic|samba}} service. If using BIND for DNS, restart the {{ic|named}} service as well.<br />
<br />
Finally, test the lookup. Replace '''xxx'''.'''xxx'''.'''xxx'''.'''xxx''' with the IP of your server:<br />
<br />
# host -t PTR '''xxx'''.'''xxx'''.'''xxx'''.'''xxx'''<br />
<br />
You should get output similar to the following:<br />
<br />
xxx.xxx.xxx.xxx.in-addr.arpa domain name pointer server.internal.domain.tld.<br />
<br />
==== TLS ====<br />
<br />
TLS support is not enabled by default, however, a default certificate was created when the DC was brought up. With the release of Samba 4.3.8 and 4.2.2, unsecured LDAP binds are disabled by default, and you must configure TLS to use Samba as an authentication source (without reducing the security of your Samba installation). To use the default keys, append the following lines to the "'''[global]'''" section of the {{ic|/etc/samba/smb.conf}} file:<br />
<br />
tls enabled = yes<br />
tls keyfile = tls/key.pem<br />
tls certfile = tls/cert.pem<br />
tls cafile = tls/ca.pem<br />
<br />
If a trusted certificate is needed, create a signing key and a certificate request (see [[OpenSSL]] for detailed instructions). Get the request signed by your chosen certificate authority, and put into this directory. If your certificate authority also needs an intermediate certificate, concatenate the certs (server cert first, then intermediate) and leave '''tls cafile''' blank.<br />
<br />
Restart {{ic|samba}} for the changes to take effect.<br />
<br />
== Adding a second domain controller to an existing domain ==<br />
<br />
=== Prerequisites ===<br />
<br />
As with the provisioning setup when setting up a new domain, you must have {{Pkg|ntp}} configured per [[#NTPD|the above instructions]]. Additionally, some of the arguments and parameters on the original domain setup must be replicated here.<br />
<br />
==== Argument explanations ====<br />
<br />
;--option='idmap_ldb<nowiki>:</nowiki>use rfc2307 = yes'<br />
: this is required if you elected to include Unix UID/GID support on your existing domain (using the '''--use-rfc2307''' option for Samba's provision step or applied the RFC 2307 schema extensions).<br />
<br />
;--dns-backend='''DNSTYPE'''<br />
:replace '''DNSTYPE''' with '''BIND9_DLZ''' or '''SAMBA_INTERNAL''' - This is again down to personal preference of the server admin. If using '''BIND9_DLZ''' backend, you will need to configure {{Pkg|bind}} as per [[#BIND|the above instructions]] after joining the domain.<br />
<br />
;--option="dns forwarder="'''xxx.xxx.xxx.xxx'''"<br />
:this is only valid for the SAMBA_INTERNAL DNS backend which allows you to specify a DNS forwarder. Replace '''xxx.xxx.xxx.xxx''' with appropriate value. <br />
<br />
;--site='''SITE'''<br />
:if you have multiple sites defined, use this to join directly in that site.<br />
<br />
See the output of {{ic|samba-tool domain join --help}} for additional options.<br />
<br />
=== Joining an existing domain as a new DC ===<br />
<br />
Execute the following command (adding any necessary parameters above to the end of the command):<br />
<br />
# samba-tool domain join '''internal.domain.tld''' DC -U"'''INTERNAL'''\'''administrator'''"<br />
<br />
Now copy the {{ic|krb5.conf}}:<br />
<br />
# cp /var/lib/samba/private/krb5.conf /etc/krb5.conf<br />
<br />
If you used the RFC 2307 schema extensions, you need to copy the idmap from an existing DC. If using Samba, execute the following command from another DC:<br />
<br />
# tdbbackup -s .bak /var/lib/samba/private/idmap.ldb<br />
<br />
This will generate a file {{ic|/var/lib/samba/private/idmap.ldb.bak}}, transfer this file to the new server in the {{ic|/var/lib/samba/private}} directory, removing the .bak extension. If you intend to keep multiple DCs, you will need to automate this process going forward using one of the methods listed on the Samba website [https://wiki.samba.org/index.php/Joining_a_Samba_DC_to_an_Existing_Active_Directory#Built-in_User_.26_Group_ID_Mappings here]. This also applies to transferring the idmap from Windows DCs.<br />
<br />
Enable and start the {{ic|samba.service}} unit.<br />
<br />
If using BIND9_DLZ DNS backend, and the {{ic|/var/lib/samba/private/dns}} directory is not created, run the following command (ignore warning about updating named.conf):<br />
<br />
# samba_upgradedns --dns-backend=BIND9_DLZ<br />
<br />
Restart the {{ic|named.service}} and then update the DNS records with the following command:<br />
<br />
# samba_dnsupdate --all-names --use-samba-tool --verbose<br />
<br />
Now proceed with LDB configuration and testing as with a new domain [[#Samba|here]].<br />
<br />
=== Transferring the FSMO roles ===<br />
<br />
If this is intended to replace an existing domain controller, you will need to transfer the FSMO roles before demoting the existing DC. This is currently outside the scope of this document. See the Samba wiki [https://wiki.samba.org/index.php/Transferring_and_Seizing_FSMO_Roles here].<br />
<br />
== Additional Services ==<br />
<br />
=== Printing ===<br />
<br />
By default, a Samba server, when configured as a domain controller, does not enable printing by default. You will need to add the following lines to the global section of the {{ic|/etc/samba/smb.conf}} file:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
...<br />
rpc_server:spoolss = external<br />
rpc_daemon:spoolssd = fork<br />
printing = CUPS<br />
...<br />
[printers]<br />
path = /var/spool/samba/<br />
printable = yes<br />
</nowiki>}}<br />
<br />
The above configuration will enable automatic sharing of all CUPS print queues. If you wish to share only specific print queues, you will want to add the following additional lines (removing the '''[printers]''' share above):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
...<br />
load printers = no<br />
...<br />
# Add and example print share<br />
[HPDJ3050]<br />
path = /var/spool/samba/<br />
printable = yes<br />
printer name = hpdj3050<br />
</nowiki>}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== DHCP with dynamic DNS updates ===<br />
<br />
It should be noted that using this method will affect functionality of windows clients, as they will still attempt to update DNS on their own. When this occurs, the machine will be denied permission to do so as the record will be owned by the dhcp user rather than the machine account. While this is essentially harmless, it will generate warnings in the system log of the offending machine. You should create a GPO to overcome this, but unfortunately, Samba does not yet have a command line utility to modify GPOs. You will need a Windows PC with the RSAT tools installed. Simply create a dedicated GPO with the Group Policy Editor, and apply only to OUs that contain workstations using DHCP (so that Samba/Windows servers and statically configured Samba/Windows clients can still update using 'ipconfig /registerdns') and configure the following settings:<br />
<br />
{{bc|1=Computer Configuration<br />
Policies<br />
Administrative Templates<br />
Network<br />
DNS Client<br />
Dynamic Update = Disabled<br />
Register PTR Records = Disabled}}<br />
<br />
[[Install]] the {{Pkg|dhcp}}, {{Pkg|sudo}}, and the {{AUR|samba-dhcpd-update}} packages.<br />
<br />
Create an unprivileged user in AD for performing the updates. When prompted for password, use a secure password. 63 random, mixed case, alpha-numeric characters is sufficient. Optionally samba-tool also takes a random argument:<br />
<br />
# samba-tool user create dhcp --description="Unprivileged user for DNS updates via DHCP server"<br />
<br />
Since this is a service account, disabling password expiration on the user account is recommended, but not required:<br />
<br />
# samba-tool user setexpiry dhcp --noexpiry<br />
<br />
Give the user privileges to administer DNS:<br />
# samba-tool group addmembers DnsAdmins dhcp<br />
<br />
Export the users credentials to a private keytab:<br />
# samba-tool domain exportkeytab --principal=dhcp@'''INTERNAL'''.'''DOMAIN'''.'''TLD''' dhcpd.keytab<br />
# install -vdm 755 /etc/dhcpd<br />
# mv dhcpd.keytab /etc/dhcpd<br />
# chown root:root /etc/dhcpd/dhcpd.keytab<br />
# chmod 400 /etc/dhcpd/dhcpd.keytab<br />
<br />
Modify the {{ic|dhcpd-update-samba-dns.conf}} file with the following commands (substituting correct values for '''server''', '''internal'''.'''domain'''.'''tld''', and '''INTERNAL'''.'''DOMAIN'''.'''TLD'''):<br />
<br />
{{hc|/etc/dhcpd/dhcpd-update-samba-dns.conf|<nowiki><br />
# Variables<br />
KRB5CC="/tmp/dhcpd4.krb5cc"<br />
KEYTAB="/etc/dhcpd/dhcpd.keytab"<br />
DOMAIN=</nowiki>"'''internal'''.'''domain'''.'''tld'''"<nowiki><br />
REALM=</nowiki>"'''INTERNAL'''.'''DOMAIN'''.'''TLD'''"<nowiki><br />
PRINCIPAL="dhcp@${REALM}"<br />
NAMESERVER="</nowiki>'''server'''<nowiki>.${DOMAIN}"<br />
ZONE="${DOMAIN}"<br />
</nowiki>}}<br />
<br />
Grant the dhcp user account permissions to run the update script without a password prompt (replace '''server''' with the hostname of the server):<br />
<br />
{{hc|/etc/sudoers.d/dhcp-update|<nowiki><br />
dhcp </nowiki>'''server'''<nowiki> = (root) NOPASSWD: /usr/bin/dhcpd-update-samba-dns.sh<br />
</nowiki>}}<br />
<br />
Configure the dhcpd server following the [[dhcpd]] article and add the following to all subnet declarations in the {{ic|/etc/dhcpd.conf}} file that provide DHCP service:<br />
<br />
{{bc|<nowiki><br />
on commit {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "add", ClientIP, ClientName);<br />
}<br />
<br />
on release {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
}<br />
<br />
on expiry {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
</nowiki>}}<br />
<br />
Here is a complete example {{ic|/etc/dhcpd.conf}} file for reference:<br />
<br />
{{hc|/etc/dhcpd.conf|<nowiki><br />
<br />
subnet </nowiki>'''192.168.1.0''' netmask '''255.255.255.0'''<nowiki> {<br />
range </nowiki>'''192.168.1.100''' '''192.168.1.199'''<nowiki>;<br />
option subnet-mask </nowiki>'''255.255.255.0'''<nowiki>;<br />
option routers </nowiki>'''192.168.1.254'''<nowiki>;<br />
option domain-name "</nowiki>'''internal.domain.tld'''<nowiki>";<br />
option domain-name-servers </nowiki>'''192.168.1.1'''<nowiki>;<br />
option broadcast-address </nowiki>'''192.168.1.255'''<nowiki>;<br />
default-lease-time 28800;<br />
max-lease-time 43200;<br />
authoritative;<br />
<br />
on commit {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "add", ClientIP, ClientName);<br />
}<br />
<br />
on release {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
}<br />
<br />
on expiry {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
}<br />
}<br />
</nowiki>}}<br />
<br />
Finally, enable and start (or restart) the {{ic|dhcpd4}} service.<br />
<br />
=== Transferring users from one directory to another ===<br />
<br />
Unfortunately, there is no built-in utility to export users from one directory to another. This is one way, albeit exceptionally ugly, to get the user specific fields out of your existing SAM and into a suitable LDIF format for ldbmodify:<br />
<br />
ldbsearch -H /var/lib/samba/private/sam.ldb \<br />
-s sub -b cn=Users,dc='''internal''',dc='''domain''',dc='''tld''' '(objectClass=user)' | \<br />
grep -e "^\# record" -e "^accountExpires:" -e "^c:" -e "^cn:" -e "^co:" -e "^codePage:" \<br />
-e "^comment:" -e "^company:" -e "^countryCode:" -e "^department:" \<br />
-e "^description:" -e "^displayName" -e "^displayNamePrintable:" \<br />
-e "^distinguishedName" -e "^division:" -e "^dn:" -e "^employeeID:" \<br />
-e "^facsimileTelephoneNumber:" -e "^generationQualifier:" \<br />
-e "^givenName" -e "^homeDirectory:" -e "^homeDrive:" -e "^homePhone:" \<br />
-e "^homePostalAddress:" -e "^info:" -e "^initials:" \<br />
-e "^internationalISDNNumber:" -e "^ipPhone:" -e "^l:" -e "^mail:" \<br />
-e "^manager:" -e "^middleName:" -e "^mobile:" -e "^name:" -e "^o:" \<br />
-e "^objectClass" -e "^otherFacsimileTelephoneNumber:" \<br />
-e "^otherHomePhone:" -e "^otherIpPhone:" -e "^otherMailbox:" \<br />
-e "^otherMobile:" -e "^otherPager:" -e "^otherTelephone:" -e "^pager:" \<br />
-e "^personalTitle:" -e "^physicalDeliveryOfficeName:" -e "^postalAddress:" \<br />
-e "^postalCode:" -e "^postOfficeBox:" -e "^proxyAddresses\: SMTP" \<br />
-e "^proxyAddresses: smtp" -e "^referredDeliveryMethod:" \<br />
-e "^primaryInternationalISDNNumber:" -e "^primaryTelexNumber:" \<br />
-e "^profilePath:" -e "^registeredAddress:" -e "^sAMAccountName:" \<br />
-e "^scriptPath:" -e "^sn:" -e "^st:" -e "^street:" -e "^streetAddress:" \<br />
-e "^telephoneNumber:" -e "^teletexTerminalIdentifier:" \<br />
-e "^telexNumber:" -e "^title:" -e "^userAccountControl:" -e "^userPrincipalName:"\<br />
-e "^url:" -e "^userSharedFolder:" -e "^userSharedFolderOther:" -e "^wWWHomePage:" | \<br />
sed '/^dn:.*/ a\changetype: add' | sed '/^# record/ i\\n' > user-export.ldif<br />
<br />
Explanation: Run an ldbsearch in the users container only, using sub-tree search for objectclass=user. If you need the whole directory, you can modify the search base to use the root or some other OU. The output from ldbsearch is then piped into a really long grep command that returns only appropriate attributes to keep in the new directory. This is obviously subjective, and probably should be tailored to your specific use case. Finally, we use sed to insert the changetype line (needed to tell ldbmodify that we are adding a user), and prefix with a blank line (to make it easier to read) for each exported object.<br />
<br />
{{Note|You will need to modify the output file and remove any objects that you do not want transferred. The output file will contain objects (service users, built-ins, etc.) that can break your new directory if you fail to remove them! It will also contain the old domain in both the "dn" and "distinguishedName" attributies that must be changed before import.}}<br />
<br />
To import, after editing the file and transferring to the new server, simply run the following command on your new samba domain controller:<br />
<br />
ldbmodify -H /var/lib/samba/private/sam.ldb user-export.ldif<br />
<br />
=== Password Complexity ===<br />
<br />
By default, Samba requires strong passwords. To disable the complexity check, issue the following command:<br />
<br />
{{bc|# samba-tool domain passwordsettings set --complexity&#61;off}}<br />
<br />
Set [https://wiki.samba.org/index.php/Password_Settings_Objects Password Settings Objects] in the Samba wiki for more information</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Samba/Active_Directory_domain_controller&diff=696295Samba/Active Directory domain controller2021-09-17T12:57:33Z<p>Pgoetz: Noted that ntp and openresolv are unnecessary on modern systemd-based systems.</p>
<hr />
<div>[[Category:Network sharing]]<br />
[[ja:Samba/Active Directory ドメインコントローラ]]<br />
[[ru:Samba (Русский)/Active Directory domain controller]]<br />
{{Related articles start}}<br />
{{Related|Active Directory Integration}}<br />
{{Related|Samba}}<br />
{{Related|SOGo}}<br />
{{Related articles end}}<br />
<br />
This article explains how to setup an Active Directory domain controller using [[Samba]]. It is assumed that all configuration files are in their unmodified, post-installation state. This article was written and tested on a fresh installation, with no modifications other than setting up a static IPv4 network connection (required). Finally, most of the commands below will require elevated privileges. Despite conventional wisdom, it may be easier to run these short few commands from a root session as opposed to obtaining rights on an as needed basis.<br />
<br />
== Installation ==<br />
<br />
{{Note|Make sure you can access the machines in your network via their hostname. See [[Network configuration#Local network hostname resolution]] for more information.}}<br />
<br />
A fully functional samba domain controller requires several programs beyond those included with the Samba distribution. [[Install]] the {{Pkg|bind}}, {{Pkg|krb5}}, {{Pkg|ntp}}, {{Pkg|python-dnspython}}, {{Pkg|openresolv}} and {{Pkg|samba}} packages from the official repositories.<br />
<br />
Samba contains its own fully functional DNS server, but if you need to maintain DNS zones for external domains, you are strongly encouraged to use [[BIND]] instead. If you need to share printers, you will also need [[CUPS]]. If needed, install the {{Pkg|bind}} and/or {{Pkg|cups}} packages.<br />
<br />
Note that you can use [[timedatectl]] as an alternative to {{Pkg|ntp}} and [[systemd-resolved]] as an alternative to {{Pkg|openresolv}}. These tools are included in the {{Pkg|systemd}} package.<br />
<br />
== Creating a new directory ==<br />
<br />
=== Provisioning ===<br />
<br />
The first step to creating an Active Directory domain is provisioning. This involves setting up the internal [[LDAP]], [[Kerberos]], and DNS servers and performing all of the basic configuration needed for the directory. If you have set up a directory server before, you are undoubtedly aware of the potential for errors in making these individual components work together as a single unit. The difficulty in doing so is the very reason that the Samba developers chose to provide internal versions of these programs. The server packages above were installed only for the client utilities. Provisioning is quite a bit easier with Samba. Just issue the following command:<br />
<br />
# samba-tool domain provision --use-rfc2307 --interactive<br />
<br />
==== Argument explanations ====<br />
<br />
;--use-rfc2307<br />
:this argument adds POSIX attributes (UID/GID) to the AD Schema. This will be necessary if you intend to authenticate Linux, BSD, or macOS clients (including the local machine) in addition to Microsoft Windows.<br />
<br />
;--interactive<br />
:this parameter forces the provision script to run interactively.<br />
<br />
Alternately, you can review the help for the provision step by running {{ic|samba-tool domain provision --help}}.<br />
<br />
==== Interactive provision explanations ====<br />
<br />
;Realm<br />
:'''INTERNAL.DOMAIN.COM''' - This should be the same as the DNS domain in all caps. It is common to use an internal-only sub-domain to separate your internal domain from your external DNS domains, but it is not required.<br />
<br />
;Domain<br />
:'''INTERNAL''' - This will be the NetBIOS domain name, usually the leftmost DNS sub-domain but can be anything you like. For example, the name INTERNAL would not be very descriptive. Perhaps company name or initials would be appropriate. This should be entered in all caps, and should have a 15 character maximum length for compatibility with older clients.<br />
<br />
;Server Role<br />
:'''dc''' - This article assumes that your are installing the first DC in a new domain. If you select anything different, the rest of this article will likely be useless to you.<br />
<br />
;DNS Backend<br />
:'''BIND9_DLZ''' or '''SAMBA_INTERNAL''' - This is down to personal preference of the server admin. Again, if you are hosting DNS for external domains, you are strongly encouraged to use the '''BIND9_DLZ''' backend so that flat zone files can continue to be used and existing transfer rules can co-exist with the internal DNS server. If unsure, use the '''SAMBA_INTERNAL''' backend.<br />
<br />
;DNS forwarder IP address<br />
: '''xxx.xxx.xxx.xxx''' or '''none''' - This option is only presented when using the SAMBA_INTERNAL DNS backend. Supply the IP address of a DNS server for forwarding non local DNS queries, or use the string '''none''' to always do root lookups.<br />
<br />
;Administrator password<br />
:'''xxxxxxxx''' - You must select a ''strong'' password for the administrator account. The minimum requirements are one upper case letter, one number, and at least eight characters. If you attempt to use a password that does not meet the complexity requirements, provisioning will fail.<br />
<br />
=== Configuring daemons ===<br />
<br />
==== NTPD ====<br />
<br />
Create a suitable NTP configuration for your network time server. See [[Network Time Protocol daemon]] for explanations of, and additional configuration options.<br />
<br />
Modify the {{ic|/etc/ntp.conf}} file with the following contents:<br />
<br />
{{hc|/etc/ntp.conf|<nowiki><br />
# Please consider joining the pool:<br />
#<br />
# http://www.pool.ntp.org/join.html<br />
#<br />
# For additional information see:<br />
# - https://wiki.archlinux.org/index.php/Network_Time_Protocol_daemon<br />
# - http://support.ntp.org/bin/view/Support/GettingStarted<br />
# - the ntp.conf man page<br />
<br />
# Associate to Arch's NTP pool<br />
server 0.arch.pool.ntp.org<br />
server 1.arch.pool.ntp.org<br />
server 2.arch.pool.ntp.org<br />
server 3.arch.pool.ntp.org<br />
<br />
# Restrictions<br />
restrict default kod limited nomodify notrap nopeer mssntp<br />
restrict 127.0.0.1<br />
restrict ::1<br />
restrict 0.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
restrict 1.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
restrict 2.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
restrict 3.arch.pool.ntp.org mask 255.255.255.255 nomodify notrap nopeer noquery<br />
<br />
# Location of drift file<br />
driftfile /var/lib/ntp/ntpd.drift<br />
<br />
# Location of the update directory<br />
ntpsigndsocket /var/lib/samba/ntp_signd/<br />
</nowiki>}}<br />
<br />
Create the state directory and set permissions:<br />
<br />
# install -d /var/lib/samba/ntp_signd<br />
# chown root:ntp /var/lib/samba/ntp_signd<br />
# chmod 0750 /var/lib/samba/ntp_signd<br />
<br />
Enable and start the {{ic|ntpd.service}} unit.<br />
<br />
==== BIND ====<br />
<br />
If you elected to use the '''BIND9_DLZ''' DNS backend, [[Install]] the {{Pkg|bind}} package and create the following BIND configuration. See [[BIND]] for explanations of, and additional configuration options. Be sure to replace the '''x''' characters with suitable values:<br />
<br />
Create the {{ic|/etc/named.conf}} file:<br />
<br />
{{hc|/etc/named.conf|<nowiki><br />
// vim:set ts=4 sw=4 et:<br />
acl local-networks {<br />
127.0.0.0/8;<br />
xxx.xxx.xxx.xxx/xx;<br />
// Uncomment the following line(s) if using IPv6<br />
//::1/128;<br />
//xxxx:xxxx:xxxx:xxxx::/64;<br />
};<br />
<br />
options {<br />
directory "/var/named";<br />
pid-file "/run/named/named.pid";<br />
session-keyfile "/run/named/session.key";<br />
<br />
// Uncomment this line to enable IPv6 connections support<br />
// listen-on-v6 { any; };<br />
// Add this for no IPv4:<br />
// listen-on { none; };<br />
<br />
// Add any subnets or hosts you want to allow to the local-networks acl<br />
allow-query { local-networks; };<br />
allow-recursion { local-networks; };<br />
allow-query-cache { local-networks; };<br />
allow-transfer { none; };<br />
allow-update { none; };<br />
<br />
version none;<br />
hostname none;<br />
server-id none;<br />
<br />
auth-nxdomain yes;<br />
datasize default;<br />
empty-zones-enable no;<br />
tkey-gssapi-keytab "/var/lib/samba/private/dns.keytab";<br />
<br />
// Uncomment if you wish to use ISP forwarders<br />
// forwarders { xxx.xxx.xxx.xxx; xxx.xxx.xxx.xxx; };<br />
};<br />
<br />
zone "localhost" IN {<br />
type master;<br />
file "localhost.zone";<br />
};<br />
<br />
zone "0.0.127.in-addr.arpa" IN {<br />
type master;<br />
file "127.0.0.zone";<br />
};<br />
<br />
zone "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa" {<br />
type master;<br />
file "localhost.ip6.zone";<br />
};<br />
<br />
// Load AD integrated zones<br />
dlz "AD DNS Zones" {<br />
database "dlopen /usr/lib/samba/bind9/dlz_bind9_12.so";<br />
};<br />
<br />
//zone "example.org" IN {<br />
// type slave;<br />
// file "example.zone";<br />
// masters {<br />
// 192.168.1.100;<br />
// };<br />
// allow-query { any; };<br />
// allow-transfer { any; };<br />
//};<br />
<br />
logging {<br />
channel xfer-log {<br />
file "/var/log/named.log";<br />
print-category yes;<br />
print-severity yes;<br />
severity info;<br />
};<br />
category xfer-in { xfer-log; };<br />
category xfer-out { xfer-log; };<br />
category notify { xfer-log; };<br />
};<br />
</nowiki>}}<br />
<br />
Set permissions:<br />
<br />
# chgrp named /var/lib/samba/private/dns.keytab<br />
# chmod g+r /var/lib/samba/private/dns.keytab<br />
# touch /var/log/named.log<br />
# chown root:named /var/log/named.log<br />
# chmod 664 /var/log/named.log<br />
<br />
Enable and start the {{ic|named.service}} unit.<br />
<br />
Good values for forwarders are your ISP's DNS servers. Google (8.8.8.8, 8.8.4.4, 2001:4860:4860::8888, and 2001:4860:4860::8844) and OpenDNS (208.67.222.222, 208.67.220.220, 2620:0:ccc::2 and 2620:0:ccd::2) provide suitable public DNS servers free of charge. Appropriate values for subnets are specific to your network.<br />
<br />
==== Kerberos client utilities ====<br />
<br />
The provisioning step above created a perfectly valid krb5.conf file for use with a Samba domain controller. Install it with the following commands:<br />
<br />
# mv /etc/krb5.conf{,.default}<br />
# cp /var/lib/samba/private/krb5.conf /etc<br />
<br />
==== DNS ====<br />
<br />
You will need to begin using the local DNS server now. Reconfigure resolvconf to use only localhost for DNS lookups. Create the {{ic|/etc/resolv.conf.tail}} (do not forget to substitute '''internal.domain.tld''' with your internal domain):<br />
<br />
# Samba configuration<br />
search '''internal.domain.tld'''<br />
# If using IPv6, uncomment the following line<br />
#nameserver ::1<br />
nameserver 127.0.0.1<br />
<br />
Set permissions and regenerate the new {{ic|/etc/resolv.conf}} file:<br />
<br />
# chmod 644 /etc/resolv.conf.tail<br />
# resolvconf -u<br />
<br />
==== Samba ====<br />
<br />
Enable and start the {{ic|samba.service}} unit. If you intend to use the LDB utilities, you will also need create the {{ic|/etc/profile.d/sambaldb.sh}} file to set '''LDB_MODULES_PATH''':<br />
<br />
export LDB_MODULES_PATH="${LDB_MODULES_PATH}:/usr/lib/samba/ldb"<br />
<br />
Set permissions on the file and source it:<br />
# chmod 0755 /etc/profile.d/sambaldb.sh<br />
# . /etc/profile.d/sambaldb.sh<br />
<br />
=== Testing the installation ===<br />
<br />
==== DNS ====<br />
<br />
First, verify that DNS is working as expected. Execute the following commands substituting appropriate values for '''internal.domain.com''' and '''server''':<br />
<br />
# host -t SRV _ldap._tcp.'''internal.domain.com'''.<br />
# host -t SRV _kerberos._udp.'''internal.domain.com'''.<br />
# host -t A '''server'''.'''internal.domain.com'''.<br />
<br />
You should receive output similar to the following:<br />
<br />
{{bc|_ldap._tcp.internal.domain.com has SRV record 0 100 389 server.internal.domain.com.<br />
_kerberos._udp.internal.domain.com has SRV record 0 100 88 server.internal.domain.com.<br />
server.internal.domain.com has address xxx.xxx.xxx.xxx}}<br />
<br />
==== NT authentication ====<br />
<br />
Next, verify that password authentication is working as expected:<br />
<br />
# smbclient //localhost/netlogon -U Administrator -c 'ls'<br />
<br />
You will be prompted for a password (the one you selected earlier), and will get a directory listing like the following:<br />
<br />
{{bc| . D 0 Wed Nov 27 23:59:07 2013<br />
.. D 0 Wed Nov 27 23:59:12 2013<br />
<br />
50332 blocks of size 2097152. 47185 blocks available}}<br />
<br />
==== Kerberos ====<br />
<br />
Now verify that the KDC is working as expected. Be sure to replace '''INTERNAL.DOMAIN.COM''' and use upper case letters:<br />
<br />
# kinit administrator@'''INTERNAL.DOMAIN.COM'''<br />
<br />
You should be prompted for a password and get output similar to the following:<br />
<br />
{{bc|Warning: Your password will expire in 41 days on Wed 08 Jan 2014 11:59:11 PM CST}}<br />
<br />
Verify that you actually got a ticket:<br />
<br />
# klist<br />
<br />
You should get output similar to below:<br />
<br />
{{bc|Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: administrator@INTERNAL.DOMAIN.COM<br />
<br />
Valid starting Expires Service principal<br />
11/28/2013 00:22:17 11/28/2013 10:22:17 krbtgt/INTERNAL.DOMAIN.COM@INTERNAL.DOMAIN.COM<br />
renew until 11/29/2013 00:22:14}}<br />
<br />
As a final test, use smbclient with your recently acquired ticket. Replace '''server''' with the correct server name:<br />
<br />
# smbclient //'''server'''/netlogon -k -c 'ls'<br />
<br />
The output should be the same as when testing password authentication above.<br />
<br />
=== Additional configuration ===<br />
<br />
==== DNS ====<br />
<br />
You will also need to create a reverse lookup zone for each subnet in your environment in DNS. It is important that this is kept in Samba's DNS as opposed to BIND to allow for dynamic updates by cleints. For each subnet, create a reverse lookup zone with the following commands. Replace '''server'''.'''internal'''.'''domain'''.'''tld''' and '''xxx'''.'''xxx'''.'''xxx''' with appropriate values. For '''xxx'''.'''xxx'''.'''xxx''', use the first three octets of the subnet in reverse order (for example: 192.168.0.0/24 becomes 0.168.192):<br />
<br />
# samba-tool dns zonecreate '''server'''.'''internal'''.'''domain'''.'''tld''' '''xxx'''.'''xxx'''.'''xxx'''.in-addr.arpa -U Administrator<br />
<br />
Now, add a record for you server (if your server is multi-homed, add for each subnet) again substituting appropriate values as above. '''zzz''' will be replaced by the fourth octet of the IP for the server:<br />
<br />
# samba-tool dns add '''server'''.'''internal'''.'''domain'''.'''tld''' '''xxx'''.'''xxx'''.'''xxx'''.in-addr.arpa '''zzz''' PTR '''server'''.'''internal'''.'''domain'''.'''tld''' -U Administrator<br />
<br />
Restart the {{ic|samba}} service. If using BIND for DNS, restart the {{ic|named}} service as well.<br />
<br />
Finally, test the lookup. Replace '''xxx'''.'''xxx'''.'''xxx'''.'''xxx''' with the IP of your server:<br />
<br />
# host -t PTR '''xxx'''.'''xxx'''.'''xxx'''.'''xxx'''<br />
<br />
You should get output similar to the following:<br />
<br />
xxx.xxx.xxx.xxx.in-addr.arpa domain name pointer server.internal.domain.tld.<br />
<br />
==== TLS ====<br />
<br />
TLS support is not enabled by default, however, a default certificate was created when the DC was brought up. With the release of Samba 4.3.8 and 4.2.2, unsecured LDAP binds are disabled by default, and you must configure TLS to use Samba as an authentication source (without reducing the security of your Samba installation). To use the default keys, append the following lines to the "'''[global]'''" section of the {{ic|/etc/samba/smb.conf}} file:<br />
<br />
tls enabled = yes<br />
tls keyfile = tls/key.pem<br />
tls certfile = tls/cert.pem<br />
tls cafile = tls/ca.pem<br />
<br />
If a trusted certificate is needed, create a signing key and a certificate request (see [[OpenSSL]] for detailed instructions). Get the request signed by your chosen certificate authority, and put into this directory. If your certificate authority also needs an intermediate certificate, concatenate the certs (server cert first, then intermediate) and leave '''tls cafile''' blank.<br />
<br />
Restart {{ic|samba}} for the changes to take effect.<br />
<br />
== Adding a second domain controller to an existing domain ==<br />
<br />
=== Prerequisites ===<br />
<br />
As with the provisioning setup when setting up a new domain, you must have {{Pkg|ntp}} configured per [[#NTPD|the above instructions]]. Additionally, some of the arguments and parameters on the original domain setup must be replicated here.<br />
<br />
==== Argument explanations ====<br />
<br />
;--option='idmap_ldb<nowiki>:</nowiki>use rfc2307 = yes'<br />
: this is required if you elected to include Unix UID/GID support on your existing domain (using the '''--use-rfc2307''' option for Samba's provision step or applied the RFC 2307 schema extensions).<br />
<br />
;--dns-backend='''DNSTYPE'''<br />
:replace '''DNSTYPE''' with '''BIND9_DLZ''' or '''SAMBA_INTERNAL''' - This is again down to personal preference of the server admin. If using '''BIND9_DLZ''' backend, you will need to configure {{Pkg|bind}} as per [[#BIND|the above instructions]] after joining the domain.<br />
<br />
;--option="dns forwarder="'''xxx.xxx.xxx.xxx'''"<br />
:this is only valid for the SAMBA_INTERNAL DNS backend which allows you to specify a DNS forwarder. Replace '''xxx.xxx.xxx.xxx''' with appropriate value. <br />
<br />
;--site='''SITE'''<br />
:if you have multiple sites defined, use this to join directly in that site.<br />
<br />
See the output of {{ic|samba-tool domain join --help}} for additional options.<br />
<br />
=== Joining an existing domain as a new DC ===<br />
<br />
Execute the following command (adding any necessary parameters above to the end of the command):<br />
<br />
# samba-tool domain join '''internal.domain.tld''' DC -U"'''INTERNAL'''\'''administrator'''"<br />
<br />
Now copy the {{ic|krb5.conf}}:<br />
<br />
# cp /var/lib/samba/private/krb5.conf /etc/krb5.conf<br />
<br />
If you used the RFC 2307 schema extensions, you need to copy the idmap from an existing DC. If using Samba, execute the following command from another DC:<br />
<br />
# tdbbackup -s .bak /var/lib/samba/private/idmap.ldb<br />
<br />
This will generate a file {{ic|/var/lib/samba/private/idmap.ldb.bak}}, transfer this file to the new server in the {{ic|/var/lib/samba/private}} directory, removing the .bak extension. If you intend to keep multiple DCs, you will need to automate this process going forward using one of the methods listed on the Samba website [https://wiki.samba.org/index.php/Joining_a_Samba_DC_to_an_Existing_Active_Directory#Built-in_User_.26_Group_ID_Mappings here]. This also applies to transferring the idmap from Windows DCs.<br />
<br />
Enable and start the {{ic|samba.service}} unit.<br />
<br />
If using BIND9_DLZ DNS backend, and the {{ic|/var/lib/samba/private/dns}} directory is not created, run the following command (ignore warning about updating named.conf):<br />
<br />
# samba_upgradedns --dns-backend=BIND9_DLZ<br />
<br />
Restart the {{ic|named.service}} and then update the DNS records with the following command:<br />
<br />
# samba_dnsupdate --all-names --use-samba-tool --verbose<br />
<br />
Now proceed with LDB configuration and testing as with a new domain [[#Samba|here]].<br />
<br />
=== Transferring the FSMO roles ===<br />
<br />
If this is intended to replace an existing domain controller, you will need to transfer the FSMO roles before demoting the existing DC. This is currently outside the scope of this document. See the Samba wiki [https://wiki.samba.org/index.php/Transferring_and_Seizing_FSMO_Roles here].<br />
<br />
== Additional Services ==<br />
<br />
=== Printing ===<br />
<br />
By default, a Samba server, when configured as a domain controller, does not enable printing by default. You will need to add the following lines to the global section of the {{ic|/etc/samba/smb.conf}} file:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
...<br />
rpc_server:spoolss = external<br />
rpc_daemon:spoolssd = fork<br />
printing = CUPS<br />
...<br />
[printers]<br />
path = /var/spool/samba/<br />
printable = yes<br />
</nowiki>}}<br />
<br />
The above configuration will enable automatic sharing of all CUPS print queues. If you wish to share only specific print queues, you will want to add the following additional lines (removing the '''[printers]''' share above):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
...<br />
load printers = no<br />
...<br />
# Add and example print share<br />
[HPDJ3050]<br />
path = /var/spool/samba/<br />
printable = yes<br />
printer name = hpdj3050<br />
</nowiki>}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== DHCP with dynamic DNS updates ===<br />
<br />
It should be noted that using this method will affect functionality of windows clients, as they will still attempt to update DNS on their own. When this occurs, the machine will be denied permission to do so as the record will be owned by the dhcp user rather than the machine account. While this is essentially harmless, it will generate warnings in the system log of the offending machine. You should create a GPO to overcome this, but unfortunately, Samba does not yet have a command line utility to modify GPOs. You will need a Windows PC with the RSAT tools installed. Simply create a dedicated GPO with the Group Policy Editor, and apply only to OUs that contain workstations using DHCP (so that Samba/Windows servers and statically configured Samba/Windows clients can still update using 'ipconfig /registerdns') and configure the following settings:<br />
<br />
{{bc|1=Computer Configuration<br />
Policies<br />
Administrative Templates<br />
Network<br />
DNS Client<br />
Dynamic Update = Disabled<br />
Register PTR Records = Disabled}}<br />
<br />
[[Install]] the {{Pkg|dhcp}}, {{Pkg|sudo}}, and the {{AUR|samba-dhcpd-update}} packages.<br />
<br />
Create an unprivileged user in AD for performing the updates. When prompted for password, use a secure password. 63 random, mixed case, alpha-numeric characters is sufficient. Optionally samba-tool also takes a random argument:<br />
<br />
# samba-tool user create dhcp --description="Unprivileged user for DNS updates via DHCP server"<br />
<br />
Since this is a service account, disabling password expiration on the user account is recommended, but not required:<br />
<br />
# samba-tool user setexpiry dhcp --noexpiry<br />
<br />
Give the user privileges to administer DNS:<br />
# samba-tool group addmembers DnsAdmins dhcp<br />
<br />
Export the users credentials to a private keytab:<br />
# samba-tool domain exportkeytab --principal=dhcp@'''INTERNAL'''.'''DOMAIN'''.'''TLD''' dhcpd.keytab<br />
# install -vdm 755 /etc/dhcpd<br />
# mv dhcpd.keytab /etc/dhcpd<br />
# chown root:root /etc/dhcpd/dhcpd.keytab<br />
# chmod 400 /etc/dhcpd/dhcpd.keytab<br />
<br />
Modify the {{ic|dhcpd-update-samba-dns.conf}} file with the following commands (substituting correct values for '''server''', '''internal'''.'''domain'''.'''tld''', and '''INTERNAL'''.'''DOMAIN'''.'''TLD'''):<br />
<br />
{{hc|/etc/dhcpd/dhcpd-update-samba-dns.conf|<nowiki><br />
# Variables<br />
KRB5CC="/tmp/dhcpd4.krb5cc"<br />
KEYTAB="/etc/dhcpd/dhcpd.keytab"<br />
DOMAIN=</nowiki>"'''internal'''.'''domain'''.'''tld'''"<nowiki><br />
REALM=</nowiki>"'''INTERNAL'''.'''DOMAIN'''.'''TLD'''"<nowiki><br />
PRINCIPAL="dhcp@${REALM}"<br />
NAMESERVER="</nowiki>'''server'''<nowiki>.${DOMAIN}"<br />
ZONE="${DOMAIN}"<br />
</nowiki>}}<br />
<br />
Grant the dhcp user account permissions to run the update script without a password prompt (replace '''server''' with the hostname of the server):<br />
<br />
{{hc|/etc/sudoers.d/dhcp-update|<nowiki><br />
dhcp </nowiki>'''server'''<nowiki> = (root) NOPASSWD: /usr/bin/dhcpd-update-samba-dns.sh<br />
</nowiki>}}<br />
<br />
Configure the dhcpd server following the [[dhcpd]] article and add the following to all subnet declarations in the {{ic|/etc/dhcpd.conf}} file that provide DHCP service:<br />
<br />
{{bc|<nowiki><br />
on commit {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "add", ClientIP, ClientName);<br />
}<br />
<br />
on release {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
}<br />
<br />
on expiry {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
</nowiki>}}<br />
<br />
Here is a complete example {{ic|/etc/dhcpd.conf}} file for reference:<br />
<br />
{{hc|/etc/dhcpd.conf|<nowiki><br />
<br />
subnet </nowiki>'''192.168.1.0''' netmask '''255.255.255.0'''<nowiki> {<br />
range </nowiki>'''192.168.1.100''' '''192.168.1.199'''<nowiki>;<br />
option subnet-mask </nowiki>'''255.255.255.0'''<nowiki>;<br />
option routers </nowiki>'''192.168.1.254'''<nowiki>;<br />
option domain-name "</nowiki>'''internal.domain.tld'''<nowiki>";<br />
option domain-name-servers </nowiki>'''192.168.1.1'''<nowiki>;<br />
option broadcast-address </nowiki>'''192.168.1.255'''<nowiki>;<br />
default-lease-time 28800;<br />
max-lease-time 43200;<br />
authoritative;<br />
<br />
on commit {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "add", ClientIP, ClientName);<br />
}<br />
<br />
on release {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
}<br />
<br />
on expiry {<br />
set ClientIP = binary-to-ascii(10, 8, ".", leased-address);<br />
set ClientName = pick-first-value(option host-name, host-decl-name);<br />
execute("/usr/bin/sudo", "/usr/bin/dhcpd-update-samba-dns.sh", "delete", ClientIP, ClientName);<br />
}<br />
}<br />
</nowiki>}}<br />
<br />
Finally, enable and start (or restart) the {{ic|dhcpd4}} service.<br />
<br />
=== Transferring users from one directory to another ===<br />
<br />
Unfortunately, there is no built-in utility to export users from one directory to another. This is one way, albeit exceptionally ugly, to get the user specific fields out of your existing SAM and into a suitable LDIF format for ldbmodify:<br />
<br />
ldbsearch -H /var/lib/samba/private/sam.ldb \<br />
-s sub -b cn=Users,dc='''internal''',dc='''domain''',dc='''tld''' '(objectClass=user)' | \<br />
grep -e "^\# record" -e "^accountExpires:" -e "^c:" -e "^cn:" -e "^co:" -e "^codePage:" \<br />
-e "^comment:" -e "^company:" -e "^countryCode:" -e "^department:" \<br />
-e "^description:" -e "^displayName" -e "^displayNamePrintable:" \<br />
-e "^distinguishedName" -e "^division:" -e "^dn:" -e "^employeeID:" \<br />
-e "^facsimileTelephoneNumber:" -e "^generationQualifier:" \<br />
-e "^givenName" -e "^homeDirectory:" -e "^homeDrive:" -e "^homePhone:" \<br />
-e "^homePostalAddress:" -e "^info:" -e "^initials:" \<br />
-e "^internationalISDNNumber:" -e "^ipPhone:" -e "^l:" -e "^mail:" \<br />
-e "^manager:" -e "^middleName:" -e "^mobile:" -e "^name:" -e "^o:" \<br />
-e "^objectClass" -e "^otherFacsimileTelephoneNumber:" \<br />
-e "^otherHomePhone:" -e "^otherIpPhone:" -e "^otherMailbox:" \<br />
-e "^otherMobile:" -e "^otherPager:" -e "^otherTelephone:" -e "^pager:" \<br />
-e "^personalTitle:" -e "^physicalDeliveryOfficeName:" -e "^postalAddress:" \<br />
-e "^postalCode:" -e "^postOfficeBox:" -e "^proxyAddresses\: SMTP" \<br />
-e "^proxyAddresses: smtp" -e "^referredDeliveryMethod:" \<br />
-e "^primaryInternationalISDNNumber:" -e "^primaryTelexNumber:" \<br />
-e "^profilePath:" -e "^registeredAddress:" -e "^sAMAccountName:" \<br />
-e "^scriptPath:" -e "^sn:" -e "^st:" -e "^street:" -e "^streetAddress:" \<br />
-e "^telephoneNumber:" -e "^teletexTerminalIdentifier:" \<br />
-e "^telexNumber:" -e "^title:" -e "^userAccountControl:" -e "^userPrincipalName:"\<br />
-e "^url:" -e "^userSharedFolder:" -e "^userSharedFolderOther:" -e "^wWWHomePage:" | \<br />
sed '/^dn:.*/ a\changetype: add' | sed '/^# record/ i\\n' > user-export.ldif<br />
<br />
Explanation: Run an ldbsearch in the users container only, using sub-tree search for objectclass=user. If you need the whole directory, you can modify the search base to use the root or some other OU. The output from ldbsearch is then piped into a really long grep command that returns only appropriate attributes to keep in the new directory. This is obviously subjective, and probably should be tailored to your specific use case. Finally, we use sed to insert the changetype line (needed to tell ldbmodify that we are adding a user), and prefix with a blank line (to make it easier to read) for each exported object.<br />
<br />
{{Note|You will need to modify the output file and remove any objects that you do not want transferred. The output file will contain objects (service users, built-ins, etc.) that can break your new directory if you fail to remove them! It will also contain the old domain in both the "dn" and "distinguishedName" attributies that must be changed before import.}}<br />
<br />
To import, after editing the file and transferring to the new server, simply run the following command on your new samba domain controller:<br />
<br />
ldbmodify -H /var/lib/samba/private/sam.ldb user-export.ldif<br />
<br />
=== Password Complexity ===<br />
<br />
By default, Samba requires strong passwords. To disable the complexity check, issue the following command:<br />
<br />
{{bc|# samba-tool domain passwordsettings set --complexity&#61;off}}<br />
<br />
Set [https://wiki.samba.org/index.php/Password_Settings_Objects Password Settings Objects] in the Samba wiki for more information</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Active_Directory_integration&diff=695656Active Directory integration2021-09-13T19:03:12Z<p>Pgoetz: improved wording</p>
<hr />
<div>[[Category:Directory services]]<br />
[[es:Active Directory integration]]<br />
[[ja:Active Directory Integration]]<br />
[[ru:Active Directory integration]]<br />
{{Related articles start}}<br />
{{Related|Samba}}<br />
{{Related|Samba/Active Directory domain controller}}<br />
{{Related|SOGo}}<br />
{{Related articles end}}<br />
<br />
{{Expansion|This page is currently being updated. The original page has been left intact until the rewrite is complete, see the section labeled '''Old Wiki Article''' for the original contents. Sections using the <s>strikethrough</s> in the title, have already been covered in the new sections.}}<br />
<br />
From [[w:Active Directory|Wikipedia]]:<br />
:Active Directory (AD) is a [[Wikipedia:directory service|directory service]] that Microsoft developed for [[Wikipedia:Windows domain|Windows domain]] networks.<br />
<br />
This article describes how to integrate an Arch Linux system with an existing Windows domain network using [[Samba]].<br />
<br />
Before continuing, you must have an existing Active Directory domain, and have a user with the appropriate rights within the domain to: query users and add computer accounts (Domain Join). <br />
<br />
This document is not an intended as a complete guide to Active Directory nor Samba. Refer to the resources section for additional information.<br />
<br />
== Introduction ==<br />
<br />
This article explains how to configure an Arch Linux system to participate in an Active Directory domain. This article was written and tested on a fresh installation, and it is assumed that all configuration files are in their unmodified, post-installation state. For the duration of the article, the example Active Directory domain will use the following configuration:<br />
<br />
* NetBIOS domain name: '''INTERNAL'''<br />
* DNS domain name: '''internal.domain.tld'''<br />
* Kerberos realm: '''INTERNAL.DOMAIN.TLD'''<br />
* First DC: '''server1.internal.domain.tld''' with IP address '''192.168.1.1'''<br />
* Second DC: '''server2.internal.domain.tld''' with IP address '''192.168.1.2'''<br />
<br />
In most small networks, the DCs (domain controllers) also hold the DNS server role. This may not be true in larger networks. Generally, DCs also hold the NTP role, but not always. Consult your network administrator to verify correct values for DNS and NTP servers.<br />
<br />
== Needed Software ==<br />
<br />
In order to use samba effectively, you will need to install the following packages: {{Pkg|samba}}, {{Pkg|smbclient}}, and {{Pkg|ntp}}. (Systemd timedatectl can be used as an alternative to ntp.)<br />
<br />
Additionally, while not required, the following packages will be useful for testing and troubleshooting: {{Pkg|bind}}, {{Pkg|krb5}}, and if a printing is desired (whether you want to share printers, or use printers on another Samba/Windows host), {{Pkg|cups}}.<br />
<br />
== Initial Configuration of Services ==<br />
<br />
=== DNS Configuration ===<br />
<br />
Active Directory depends entirely on DNS for name resolution. It is imperative that the {{ic|/etc/resolv.conf}} file is configured with both the correct DNS servers and a domain search suffix. Whether configured via DHCP or static configuration, ensure that these values are correct for your domain. For the example domain configuration, the following contents are appropriate (be sure to replace '''192.168.1.1''', '''192.168.1.2''', and '''internal.domain.tld''' with appropriate values for your network):<br />
<br />
{{hc|/etc/resolv.conf|<nowiki><br />
nameserver </nowiki>'''192.168.1.1'''<nowiki><br />
nameserver </nowiki>'''192.168.1.2'''<nowiki><br />
search </nowiki>'''internal.domain.tld'''}}<br />
<br />
If you elected to install the {{Pkg|bind}} package, you can test DNS configuration with the following commands (be sure to replace '''server1''' and '''internal.domain.tld''' with appropriate values for your network):<br />
<br />
$ nslookup -type=SRV _kerberos._tcp.'''internal.domain.tld'''.<br />
$ nslookup -type=SRV _ldap._tcp.'''internal.domain.tld'''.<br />
$ nslookup '''server1'''.'''internal.domain.tld'''.<br />
<br />
You should get output similar to the following (adjust appropriately for only one DC, or more than two):<br />
<br />
Server: 192.168.1.1<br />
Address: 192.168.1.1#53<br />
<br />
_kerberos._tcp.internal.domain.tld service = 0 100 88 server1.internal.domain.tld.<br />
_kerberos._tcp.internal.domain.tld service = 0 100 88 server2.internal.domain.tld.<br />
...<br />
_ldap._tcp.internal.domain.tld service = 0 100 389 server1.internal.domain.tld.<br />
_ldap._tcp.internal.domain.tld service = 0 100 389 server2.internal.domain.tld.<br />
...<br />
Name: server1.internal.domain.tld<br />
Address: 192.168.1.1<br />
<br />
=== NTP Configuration ===<br />
<br />
In an Active Directory domain, more specifically for Kerberos ticketing, it is imperative that time is synchronized will all other hosts on the network. A margin of error no more than five minutes is required. For the example domain configuration, an appropriate {{ic|/etc/ntp.conf}} file should have the following contents (be sure to replace '''server1''', '''server2''', and '''internal.domain.tld''' with appropriate values for your network):<br />
<br />
{{hc|/etc/ntp.conf|<nowiki><br />
# Use your domain's NTP servers <br />
server </nowiki>'''server1'''.'''internal.domain.tld'''<nowiki><br />
server </nowiki>'''server2'''.'''internal.domain.tld'''<nowiki><br />
<br />
# Restrictions<br />
restrict default kod limited nomodify nopeer noquery notrap<br />
restrict 127.0.0.1<br />
restrict ::1<br />
<br />
# Location of drift file<br />
driftfile /var/lib/ntp/ntpd.drift</nowiki>}}<br />
<br />
Enable and start the {{ic|ntpd.service}} unit.<br />
<br />
=== Kerberos Configuration ===<br />
<br />
The Samba documentation recommends a minimal Kerberos configuration, with just enough information in the '''[libdefaults]''' section to hand off the work of discovering domain details to DNS. Unfortunately, this does not work well in practice. Continuing with the example domain configuration, modify the {{ic|/etc/krb.conf}} file with the following contents (be sure to replace instances of '''INTERNAL''', '''internal.domain.tld''', '''SERVER1''', and '''INTERNAL.DOMAIN.TLD''' with appropriate values for your network):<br />
<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
default_realm = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
dns_lookup_realm = false<br />
dns_lookup_kdc = true<br />
<br />
[realms]<br />
</nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki> = {<br />
kdc = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
default_domain = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
admin_server = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
}<br />
</nowiki>'''INTERNAL'''<nowiki> = {<br />
kdc = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
default_domain = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
admin_server = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
}<br />
<br />
[domain_realm]<br />
</nowiki>.'''internal.domain.tld'''<nowiki> = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
<br />
[appdefaults]<br />
pam = {<br />
ticket_lifetime = 1d<br />
renew_lifetime = 1d<br />
forwardable = true<br />
proxiable = false<br />
minimum_uid = 1<br />
}<br />
<br />
</nowiki>}}<br />
<br />
=== Samba Configuration ===<br />
<br />
==== Base Samba Configuration File ====<br />
<br />
A default installation of {{Pkg|samba}} does not ship with an example {{ic|/etc/samba/smb.conf}} file. For our example domain configuration, use the following base settings (replace instances of '''INTERNAL''' and '''INTERNAL.DOMAIN.TLD''' with appropriate values for your network):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
workgroup = </nowiki>'''INTERNAL'''<nowiki><br />
security = ADS<br />
realm = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
<br />
winbind refresh tickets = Yes<br />
vfs objects = acl_xattr<br />
map acl inherit = Yes<br />
store dos attributes = Yes<br />
<br />
# Allow a single, unified keytab to store obtained Kerberos tickets<br />
dedicated keytab file = /etc/krb5.keytab<br />
kerberos method = secrets and keytab<br />
<br />
# Do not require that login usernames include the default domain<br />
winbind use default domain = yes</nowiki>}}<br />
<br />
If you do not wish to share local printers configured in {{Pkg|cups}}, then add the following to the [Global] section of the {{ic|/etc/samba/smb.conf}} file:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
load printers = no<br />
printing = bsd<br />
printcap name = /dev/null<br />
disable spoolss = yes<br />
...</nowiki>}}<br />
<br />
The remainder of the configuration depends on whether your domain supports RFC2307 Unix/NFS Attributes. Consult with your domain administrator if unsure.<br />
<br />
===== Adding the idmap Configuration for Domains With RFC2307 Extensions =====<br />
<br />
Be certain that the values below do not overlap with system values, and that all users have at least the ''uidNubmer'' attribute, and that those users' ''PrimaryGroup'' has a ''gid'' attribute. Append to the following to the the [Global] section of the {{ic|/etc/samba/smb.conf}} file (replace '''INTERNAL''' with the NetBIOS domain name):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
<br />
# UID/GID mapping for local users<br />
idmap config * : backend = tdb<br />
idmap config * : range = 3000-7999<br />
<br />
# UID/GID mapping for domain users<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : backend = ad<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : schema_mode = rfc2307<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : range = 10000-999999<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : unix_nss_info = yes<br />
<br />
# Template settings for users without ''unixHomeDir'' and ''loginShell'' attributes <br />
template shell = /bin/bash<br />
template homedir = /home/%U<br />
<br />
# Allow offline/cached credentials and ticket refresh<br />
winbind offline logon = yes<br />
winbind refresh tickets = yes<br />
...</nowiki>}}<br />
<br />
Additionally, if user accounts in AD have a ''gidNumber'' attribute, you can use it instead of the RID for the user's ''Primary Group'' by appending the following setting (again in the [Global] section):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
idmap config </nowiki>'''INTERNAL'''<nowiki>:unix_primary_group = yes<br />
...</nowiki>}}<br />
<br />
===== Adding the idmap Configuration for Domains Without RFC2307 Extensions =====<br />
<br />
If your administrator has not extended the AD schema to include the RFC2307 attributes, use the following idmap configuration in the [Global] section of the {{ic|/etc/samba/smb.conf}} file (replace '''INTERNAL''' with the NetBIOS domain name):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
# UID/GID mapping for local users<br />
idmap config * : backend = tdb<br />
idmap config * : range = 3000-7999<br />
<br />
# UID/GID mapping for domain users<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : backend = rid<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : range = 10000-999999<br />
<br />
# Template settings for users<br />
template shell = /bin/bash<br />
template homedir = /home/%U<br />
<br />
# Allow offline/cached credentials and ticket refresh<br />
winbind offline logon = yes<br />
winbind refresh tickets = yes<br />
...</nowiki>}}<br />
<br />
== Joining the Domain ==<br />
<br />
To join the AD domain, simply issue the following command (be sure to replace '''Administrator''' with a user that has privileges to join the AD domain).<br />
<br />
# net ads join -U Administrator<br />
<br />
== Start the Individual Samba Services ==<br />
<br />
Enable and start the {{ic|smb.service}}, {{ic|nmb.service}}, and {{ic|winbind.service}} services.<br />
<br />
== Configure NSS ==<br />
<br />
Modify the {{ic|/etc/nsswitch.conf}} file to allow Samba to map names to uid and gid:<br />
<br />
{{hc|/etc/nsswitch.conf|<nowiki><br />
...<br />
passwd: files winbind mymachines systemd<br />
group: files winbind mymachines systemd<br />
...</nowiki>}}<br />
<br />
=== Testing NSS ===<br />
<br />
Verify connectivity by listing the AD domain users and groups that system is aware of:<br />
<br />
# wbinfo -u<br />
# wbinfo -g<br />
<br />
You should get a list of AD users followed by AD groups.<br />
<br />
== Configuring PAM authentication ==<br />
<br />
Rather than configuring options directly in the ''Linux-PAM'' configuration files, set defaults for the ''pam_winbind'' module in {{ic|/etc/security/pam_winbind.conf}}:<br />
<br />
{{hc|/etc/security/pam_winbind.conf|<nowiki><br />
[Global]<br />
debug = no<br />
debug_state = no<br />
try_first_pass = yes<br />
krb5_auth = yes<br />
krb5_ccache_type = FILE:/run/user/%u/krb5cc<br />
cached_login = yes<br />
silent = no<br />
mkhomedir = yes</nowiki>}}<br />
<br />
For most services, it will be sufficient to modify only the {{ic|/etc/pam.d/system-auth}} file. Any configuration for programs that do not include this file will also need to be modified directly. Create a backup of the {{ic|/etc/pam.d/system-auth}} file and use the following configuration:<br />
<br />
{{hc|/etc/pam.d/system-auth|<nowiki><br />
#%PAM-1.0<br />
<br />
auth sufficient pam_winbind.so<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
account sufficient pam_winbind.so<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
password sufficient pam_winbind.so<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
session required pam_limits.so<br />
session required pam_winbind.so<br />
session required pam_unix.so<br />
session optional pam_permit.so</nowiki>}}<br />
<br />
If you have other services that do not include the {{ic|/etc/pam.d/system-auth}} file, modify the configuration to mirror all ''pam_unix.so'' entries for ''pam_winbind.so'' and change all ''required'' to ''sufficient''. A good example is the su configuration. Create a backup of the {{ic|/etc/pam.d/su}} file and use the following in its place:<br />
<br />
{{hc|/etc/pam.d/su|<nowiki><br />
#%PAM-1.0<br />
<br />
auth sufficient pam_rootok.so<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth required pam_wheeel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth sufficient pam_winbind.so<br />
auth required pam_unix.so<br />
account sufficient pam_winbind.so<br />
account required pam_unix.so<br />
session sufficient pam_winbind.so<br />
session required pam_unix.so</nowiki>}}<br />
<br />
The above pam_winbind configuration will not use the default location of the Kerberos ticket ({{ic|KRB5CCNAME}}), which is at {{ic|/tmp/krb5cc_''UID''}}. Instead, it stores the automatically refreshed Kerberos ticket to {{ic|/run/user/''UID''/krb5cc}}. Append the following to your krb5.conf to let Kerberos know your new location:<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
...<br />
default_ccache_name = /run/user/%{uid}/krb5cc<br />
...</nowiki>}}<br />
<br />
To test your changes, start a '''new''' console or ssh session (do not exit your existing session until you have tested thoroughly) and try to login using the AD credentials. The domain name is optional, as this was set in the Winbind configuration as 'default realm'. Please note that in the case of ssh, you will need to modify the {{ic|/etc/ssh/sshd_config}} file to allow kerberos authentication (see below). <br />
<br />
Run '''klist''' to verify that you have received a kerberos ticket. You should see something similar to:<br />
{{hc|$ klist|<br />
Ticket cache: FILE:/run/user/20000/krb5cc<br />
Default principal: administrator@INTERNAL.DOMAIN.TLD<br />
<br />
Valid starting Expires Service principal<br />
12/25/2020 03:35:21 12/25/2020 13:35:21 krbtgt/INTERNAL.DOMAIN.TLD@INTERNAL.DOMAIN.TLD<br />
renew until 12/26/2020 03:35:15<br />
}}<br />
<br />
Finally, you should test login as both the root user and a local unprivileged user before logging out of your existing (working) session.<br />
<br />
== Old Wiki Article ==<br />
<br />
Active Directory serves as a central location for network administration and security. It is responsible for authenticating and authorizing all users and computers within a Windows domain network, assigning and enforcing security policies for all computers in a network and installing or updating software on network computers. For example, when a user logs into a computer that is part of a Windows domain, it is Active Directory that verifies his or her password and specifies whether they is a system administrator or normal user. Server computers on which Active Directory is running are called domain controllers.<br />
<br />
Active Directory uses [[Wikipedia:Ldap|Lightweight Directory Access Protocol (LDAP)]] versions 2 and 3, Microsoft's version of [[Kerberos]] and DNS.<br />
<br />
=== Terminology ===<br />
<br />
If you are not familiar with Active Directory, there are a few keywords that are helpful to know.<br />
<br />
* '''Domain''' : The name used to group computers and accounts. <br />
* '''SID''' : Each computer that joins the domain as a member must have a unique SID or System Identifier.<br />
* '''SMB''' : Server Message Block.<br />
* '''NETBIOS''': Network naming protocol used as an alternative to DNS. Mostly legacy, but still used in Windows Networking.<br />
* '''WINS''': Windows Information Naming Service. Used for resolving Netbios names to windows hosts.<br />
* '''Winbind''': Protocol for windows authentication.<br />
<br />
=== <s>Active Directory configuration</s> ===<br />
<br />
This section works with the default configuration of Windows Server 2012 R2.<br />
<br />
==== <s>GPO considerations</s> ====<br />
<br />
Digital signing is enabled by default in Windows Server, and must be enabled at both the client and server level. For certain versions of Samba, Linux clients may experience issues connecting to the domain and/or shares. It's recommended you add the following parameters to your {{ic|smb.conf}} file: <br />
<br />
client signing = auto <br />
server signing = auto<br />
<br />
If that is not successful, you can disable ''Digital Sign Communication (Always)'' in the AD group policies. In your AD Group Policy editor, locate:<br />
<br />
Under ''Local policies > Security policies > Microsoft Network Server > Digital sign communication (Always)'' activate ''define this policy'' and use the ''disable'' radio button.<br />
<br />
If you use Windows Server 2008 R2, you need to modify that in ''GPO for Default Domain Controller Policy > Computer Setting > Policies > Windows Setting > Security Setting > Local Policies > Security Option > Microsoft network client: Digitally sign communications (always)''.<br />
<br />
Please note that disabling this GPO affects the security of all members of the domain.<br />
<br />
=== <s>Linux host configuration</s> ===<br />
<br />
The next few steps will begin the process of configuring the Host. You will need root or sudo access to complete these steps.<br />
<br />
==== <s>Installation</s> ====<br />
<br />
[[Install]] the following packages:<br />
* {{Pkg|samba}}, see also [[Samba]]<br />
* {{Pkg|pam-krb5}}<br />
* {{Pkg|ntp}} or {{Pkg|openntpd}}, see also [[NTPd]] or [[OpenNTPD]]<br />
<br />
==== <s>Updating DNS</s> ====<br />
<br />
Active Directory is heavily dependent upon DNS. You will need to update {{ic|/etc/resolv.conf}} to use one or more of the Active Directory domain controllers:<br />
{{hc|/etc/resolv.conf|<br />
nameserver <IP1><br />
nameserver <IP2><br />
}}<br />
Replacing <IP1> and <IP2> with valid IP addresses for the AD servers. If your AD domains do not permit DNS forwarding or recursion, you may need to add additional resolvers. <br />
<br />
{{Note|If your machine dual boots Windows and Linux, you should use a different DNS hostname and netbios name for the linux configuration if both operating systems will be members of the same domain.}}<br />
<br />
==== <s>Configuring NTP</s> ====<br />
<br />
Read [[System time#Time synchronization]] to configure an NTP service.<br />
<br />
On the NTP servers configuration, use the IP addresses for the AD servers, as they typically run NTP as a service. Alternatively, you can use other known NTP servers provided the Active directory servers sync to the same stratum.<br />
<br />
Ensure that the service is configured to sync the time automatically very early on startup.<br />
<br />
==== <s>Kerberos</s> ====<br />
<br />
Let us assume that your AD is named example.com. Let us further assume your AD is ruled by two domain controllers, the primary and secondary one, which are named PDC and BDC, pdc.example.com and bdc.example.com respectively. Their IP adresses will be 192.168.1.2 and 192.168.1.3 in this example. Take care to watch your syntax; upper-case is very important here.<br />
<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
default_realm = EXAMPLE.COM<br />
clockskew = 300<br />
ticket_lifetime = 1d<br />
forwardable = true<br />
proxiable = true<br />
dns_lookup_realm = true<br />
dns_lookup_kdc = true<br />
<br />
[realms]<br />
EXAMPLE.COM = {<br />
kdc = PDC.EXAMPLE.COM<br />
admin_server = PDC.EXAMPLE.COM<br />
default_domain = EXAMPLE.COM<br />
}<br />
<br />
[domain_realm]<br />
.kerberos.server = EXAMPLE.COM<br />
.example.com = EXAMPLE.COM<br />
example.com = EXAMPLE.COM<br />
example = EXAMPLE.COM<br />
<br />
[appdefaults]<br />
pam = {<br />
ticket_lifetime = 1d<br />
renew_lifetime = 1d<br />
forwardable = true<br />
proxiable = false<br />
retain_after_close = false<br />
minimum_uid = 0<br />
debug = false<br />
}<br />
<br />
[logging]<br />
default = FILE:/var/log/krb5libs.log<br />
kdc = FILE:/var/log/kdc.log<br />
admin_server = FILE:/var/log/kadmind.log<br />
</nowiki>}}<br />
<br />
{{Note|Heimdal 1.3.1 deprecated DES encryption which is required for AD authentication before Windows Server 2008. You will probably have to add {{bc|1=allow_weak_crypto = true}} to the {{Ic|[libdefaults]}} section.}}<br />
<br />
===== <s>Creating a Kerberos ticket</s> =====<br />
<br />
{{note|The keys and commands are user specific: sudo will be root, so your non-elevated account can connect to a different AD user with a separate key. If you only have one domain, it is not necessary to type @EXAMPLE.COM}}<br />
<br />
Now you can query the AD domain controllers and request a kerberos ticket ('''uppercase is necessary'''):<br />
{{bc|kinit administrator@EXAMPLE.COM}}<br />
<br />
You can use any username that has rights as a Domain Administrator.<br />
<br />
===== <s>Validating the Ticket</s> =====<br />
<br />
Run '''klist''' to verify you did receive the token. You should see something similar to:<br />
{{hc|# klist|<br />
Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: administrator@EXAMPLE.COM<br />
<br />
Valid starting Expires Service principal <br />
02/04/12 21:27:47 02/05/12 07:27:42 krbtgt/EXAMPLE.COM@EXAMPLE.COM<br />
renew until 02/05/12 21:27:47<br />
}}<br />
<br />
==== <s>pam_winbind.conf</s> ====<br />
<br />
If you get errors stating that /etc/security/pam_winbind.conf was not found, create the file and add the following:<br />
<br />
{{hc|/etc/security/pam_winbind.conf|<nowiki><br />
[global]<br />
debug = no<br />
debug_state = no<br />
try_first_pass = yes<br />
krb5_auth = yes<br />
krb5_ccache_type = FILE<br />
cached_login = yes<br />
silent = no<br />
mkhomedir = yes<br />
</nowiki>}}<br />
<br />
With this setup, winbind will create user keytabs on the fly (krb5_ccache_type = FILE) at login and maintain them. You can verify this by simply running klist in a shell after logging in as an AD user but without needing to run kinit. You may need to set additional permissions on /etc/krb5.keytab eg 640 instead of 600 to get this to work (see {{Bug|52621}} for example)<br />
<br />
==== <s>Samba</s> ====<br />
<br />
Samba is a free software re-implementation of the SMB/CIFS networking protocol. It also includes tools for Linux machines to act as Windows networking servers and clients.<br />
<br />
{{Note|The configuration can vary greatly depending on how the Windows environment is deployed. Be prepared to troubleshoot and research}}<br />
<br />
In this section, we will focus on getting Authentication to work first by editing the 'Global' section first. Later, we will go back and add shares.<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
netbios name = MYARCHLINUX<br />
workgroup = EXAMPLE<br />
realm = EXAMPLE.COM<br />
server string = %h ArchLinux Host<br />
security = ads<br />
encrypt passwords = yes<br />
password server = pdc.example.com<br />
client signing = auto<br />
server signing = auto<br />
<br />
idmap config * : backend = tdb<br />
idmap config * : range = 10000-20000<br />
<br />
winbind use default domain = Yes<br />
winbind enum users = Yes<br />
winbind enum groups = Yes<br />
winbind nested groups = Yes<br />
winbind separator = +<br />
winbind refresh tickets = yes<br />
winbind offline logon = yes<br />
winbind cache time = 300<br />
<br />
template shell = /bin/bash<br />
template homedir = /home/%D/%U<br />
<br />
preferred master = no<br />
dns proxy = no<br />
wins server = pdc.example.com<br />
wins proxy = no<br />
<br />
inherit acls = Yes<br />
map acl inherit = Yes<br />
acl group control = yes<br />
<br />
load printers = no<br />
debug level = 3<br />
use sendfile = no<br />
</nowiki>}}<br />
<br />
==== <s>Join the domain</s> ====<br />
<br />
You need an AD Administrator account to do this. Let us assume this is named Administrator. The command is 'net ads join'<br />
{{hc|# net ads join -U Administrator|<br />
Administrator's password: xxx<br />
Using short domain name -- EXAMPLE<br />
Joined 'MYARCHLINUX' to realm 'EXAMPLE.COM'<br />
}}<br />
<br />
=== <s>Starting and testing services</s> ===<br />
<br />
==== <s>Starting Samba</s> ====<br />
<br />
Hopefully, you have not rebooted yet! Fine. If you are in an X-session, quit it, so you can test login into another console, while you are still logged in.<br />
<br />
Enable and start the individual Samba daemons {{ic|smbd.service}}, {{ic|nmbd.service}}, and {{ic|winbindd.service}}.<br />
<br />
{{Note|In {{Pkg|samba}} 4.8.0-1, the Samba daemon units have been renamed from {{ic|smbd.service}}, {{ic|nmbd.service}}, and {{ic|winbindd.service}} to {{ic|smb.service}}, {{ic|nmb.service}}, and {{ic|winbind.service}}.}}<br />
<br />
Next we will need to modify the NSSwitch configuration, which tells the Linux host how to retrieve information from various sources and in which order to do so. In this case, we are appending Active Directory as additional sources for Users, Groups, and Hosts.<br />
<br />
{{hc|/etc/nsswitch.conf|<br />
passwd: files winbind<br />
shadow: files winbind<br />
group: files winbind <br />
<br />
hosts: files dns wins<br />
}}<br />
<br />
==== <s>Testing Winbind</s> ====<br />
<br />
Let us check if winbind is able to query the AD. The following command should return a list of AD users:<br />
<br />
{{hc|# wbinfo -u|<br />
administrator<br />
guest<br />
krbtgt<br />
test.user<br />
}}<br />
* Note we created an Active Directory user called 'test.user' on the domain controller<br />
<br />
We can do the same for AD groups:<br />
<br />
{{hc|# wbinfo -g|<br />
domain computers<br />
domain controllers<br />
schema admins<br />
enterprise admins<br />
cert publishers<br />
domain admins<br />
domain users<br />
domain guests<br />
group policy creator owners<br />
ras and ias servers<br />
allowed rodc password replication group<br />
denied rodc password replication group<br />
read-only domain controllers<br />
enterprise read-only domain controllers<br />
dnsadmins<br />
dnsupdateproxy<br />
}}<br />
<br />
==== <s>Testing nsswitch</s> ====<br />
<br />
To ensure that our host is able to query the domain for users and groups, we test nsswitch settings by issuing the 'getent' command.<br />
<br />
The following output shows what a stock ArchLinux install looks like:<br />
<br />
{{hc|# getent passwd|<br />
root:x:0:0:root:/root:/bin/bash<br />
bin:x:1:1:bin:/bin:/bin/false<br />
daemon:x:2:2:daemon:/sbin:/bin/false<br />
mail:x:8:12:mail:/var/spool/mail:/bin/false<br />
ftp:x:14:11:ftp:/srv/ftp:/bin/false<br />
http:x:33:33:http:/srv/http:/bin/false<br />
nobody:x:99:99:nobody:/:/bin/false<br />
dbus:x:81:81:System message bus:/:/bin/false<br />
ntp:x:87:87:Network Time Protocol:/var/empty:/bin/false<br />
avahi:x:84:84:avahi:/:/bin/false<br />
administrator:*:10001:10006:Administrator:/home/EXAMPLE/administrator:/bin/bash<br />
guest:*:10002:10007:Guest:/home/EXAMPLE/guest:/bin/bash<br />
krbtgt:*:10003:10006:krbtgt:/home/EXAMPLE/krbtgt:/bin/bash<br />
test.user:*:10000:10006:Test User:/home/EXAMPLE/test.user:/bin/bash<br />
}}<br />
<br />
And for groups:<br />
{{hc|# getent group|<br />
root:x:0:root<br />
bin:x:1:root,bin,daemon<br />
daemon:x:2:root,bin,daemon<br />
sys:x:3:root,bin<br />
adm:x:4:root,daemon<br />
tty:x:5:<br />
disk:x:6:root<br />
lp:x:7:daemon<br />
mem:x:8:<br />
kmem:x:9:<br />
wheel:x:10:root<br />
ftp:x:11:<br />
mail:x:12:<br />
uucp:x:14:<br />
log:x:19:root<br />
utmp:x:20:<br />
locate:x:21:<br />
rfkill:x:24:<br />
smmsp:x:25:<br />
http:x:33:<br />
games:x:50:<br />
network:x:90:<br />
video:x:91:<br />
audio:x:92:<br />
optical:x:93:<br />
floppy:x:94:<br />
storage:x:95:<br />
scanner:x:96:<br />
power:x:98:<br />
nobody:x:99:<br />
users:x:100:<br />
dbus:x:81:<br />
ntp:x:87:<br />
avahi:x:84:<br />
domain computers:x:10008:<br />
domain controllers:x:10009:<br />
schema admins:x:10010:administrator<br />
enterprise admins:x:10011:administrator<br />
cert publishers:x:10012:<br />
domain admins:x:10013:test.user,administrator<br />
domain users:x:10006:<br />
domain guests:x:10007:<br />
group policy creator owners:x:10014:administrator<br />
ras and ias servers:x:10015:<br />
allowed rodc password replication group:x:10016:<br />
denied rodc password replication group:x:10017:krbtgt<br />
read-only domain controllers:x:10018:<br />
enterprise read-only domain controllers:x:10019:<br />
dnsadmins:x:10020:<br />
dnsupdateproxy:x:10021:<br />
}}<br />
<br />
==== Testing Samba commands ====<br />
<br />
Try out some net commands to see if Samba can communicate with AD:<br />
<br />
{{hc|# net ads info|<nowiki><br />
[2012/02/05 20:21:36.473559, 0] param/loadparm.c:7599(lp_do_parameter)<br />
Ignoring unknown parameter "idmapd backend"<br />
LDAP server: 192.168.1.2<br />
LDAP server name: PDC.example.com<br />
Realm: EXAMPLE.COM<br />
Bind Path: dc=EXAMPLE,dc=COM<br />
LDAP port: 389<br />
Server time: Sun, 05 Feb 2012 20:21:33 CST<br />
KDC server: 192.168.1.2<br />
Server time offset: -3<br />
</nowiki>}}<br />
<br />
{{hc|# net ads lookup|<br />
[2012/02/05 20:22:39.298823, 0] param/loadparm.c:7599(lp_do_parameter)<br />
Ignoring unknown parameter "idmapd backend"<br />
Information for Domain Controller: 192.168.1.2<br />
<br />
Response Type: LOGON_SAM_LOGON_RESPONSE_EX<br />
GUID: 2a098512-4c9f-4fe4-ac22-8f9231fabbad<br />
Flags:<br />
Is a PDC: yes<br />
Is a GC of the forest: yes<br />
Is an LDAP server: yes<br />
Supports DS: yes<br />
Is running a KDC: yes<br />
Is running time services: yes<br />
Is the closest DC: yes<br />
Is writable: yes<br />
Has a hardware clock: yes<br />
Is a non-domain NC serviced by LDAP server: no<br />
Is NT6 DC that has some secrets: no<br />
Is NT6 DC that has all secrets: yes<br />
Forest: example.com<br />
Domain: example.com<br />
Domain Controller: PDC.example.com<br />
Pre-Win2k Domain: EXAMPLE<br />
Pre-Win2k Hostname: PDC<br />
Server Site Name : Office<br />
Client Site Name : Office<br />
NT Version: 5<br />
LMNT Token: ffff<br />
LM20 Token: ffff<br />
}}<br />
<br />
{{hc|<nowiki># net ads status -U administrator%password | less</nowiki>|<nowiki><br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: user<br />
objectClass: computer<br />
cn: myarchlinux<br />
distinguishedName: CN=myarchlinux,CN=Computers,DC=leafscale,DC=inc<br />
instanceType: 4<br />
whenCreated: 20120206043413.0Z<br />
whenChanged: 20120206043414.0Z<br />
uSNCreated: 16556<br />
uSNChanged: 16563<br />
name: myarchlinux<br />
objectGUID: 2c24029c-8422-42b2-83b3-a255b9cb41b3<br />
userAccountControl: 69632<br />
badPwdCount: 0<br />
codePage: 0<br />
countryCode: 0<br />
badPasswordTime: 0<br />
lastLogoff: 0<br />
lastLogon: 129729780312632000<br />
localPolicyFlags: 0<br />
pwdLastSet: 129729764538848000<br />
primaryGroupID: 515<br />
objectSid: S-1-5-21-719106045-3766251393-3909931865-1105<br />
...<snip>...<br />
</nowiki>}}<br />
<br />
=== <s>Configuring PAM</s> ===<br />
<br />
Now we will change various rules in PAM to allow Active Directory users to use the system for things like login and sudo access. When changing the rules, note the order of these items and whether they are marked as '''required''' or '''sufficient''' is critical to things working as expected. You should not deviate from these rules unless you know how to write PAM rules.<br />
<br />
In case of logins, PAM should first ask for AD accounts, and for local accounts if no matching AD account was found. Therefore, we add entries to include {{ic|pam_winbind.so}} into the authentication process.<br />
<br />
The Arch Linux PAM configuration keeps the central auth process in {{ic|/etc/pam.d/system-auth}}. Starting with the stock configuration from {{ic|pambase}}, change it like this:<br />
<br />
==== <s>system-auth</s> ====<br />
<br />
===== <s>"auth" section</s> =====<br />
<br />
Find the line:<br />
<br />
auth required pam_unix.so ...<br />
<br />
Delete it, and replace with:<br />
<br />
auth [success=1 default=ignore] pam_localuser.so<br />
auth [success=2 default=die] pam_winbind.so<br />
auth [success=1 default=die] pam_unix.so nullok<br />
auth requisite pam_deny.so<br />
<br />
===== <s>"account" section</s> =====<br />
<br />
Find the line:<br />
<br />
account required pam_unix.so<br />
<br />
Keep it, and add this below:<br />
<br />
account [success=1 default=ignore] pam_localuser.so<br />
account required pam_winbind.so<br />
<br />
===== <s>"password" section</s> =====<br />
<br />
Find the line:<br />
<br />
password required pam_unix.so ...<br />
<br />
Delete it, and replace with:<br />
<br />
password [success=1 default=ignore] pam_localuser.so<br />
password [success=2 default=die] pam_winbind.so<br />
password [success=1 default=die] pam_unix.so sha512 shadow<br />
password requisite pam_deny.so<br />
<br />
===== <s>"session" section</s> =====<br />
<br />
Find the line:<br />
<br />
session required pam_unix.so<br />
<br />
Keep it, and add this line immediately above it:<br />
<br />
session required pam_mkhomedir.so skel=/etc/skel/ umask=0022<br />
<br />
Below the pam_unix line, add these:<br />
<br />
session [success=1 default=ignore] pam_localuser.so<br />
session required pam_winbind.so<br />
<br />
==== <s>passwd</s> ====<br />
<br />
===== <s>"password" section</s> =====<br />
<br />
In order for logged-in Active Directory users to be able to change their passwords with the 'passwd' command, the file {{ic|/etc/pam.d/passwd}} must include the information from system-auth.<br />
<br />
Find the line:<br />
<br />
password required pam_unix.so sha512 shadow nullok<br />
<br />
Delete it, and replace with:<br />
<br />
password include system-auth<br />
<br />
==== <s>Testing login</s> ====<br />
<br />
Now, start a new console session (or ssh) and try to login using the AD credentials. The domain name is optional, as this was set in the Winbind configuration as 'default realm'. Please note that in the case of ssh, you will need to modify the {{ic|/etc/ssh/sshd_config}} file to allow kerberos authentication {{ic|(KerberosAuthentication yes)}}.<br />
<br />
{{bc|<br />
test.user<br />
EXAMPLE+test.user<br />
}}<br />
<br />
Both should work. You should notice that {{ic|/home/example/test.user}} will be automatically created.<br />
'''Log into another session using an linux account. Check that you still be able to log in as root - but keep in mind to be logged in as root in at least one session!'''<br />
<br />
=== Configuring Shares ===<br />
<br />
Earlier we skipped configuration of the shares. Now that things are working, go back to {{ic|/etc/samba/smb.conf}}, and add the exports for the host that you want available on the windows network. <br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[MyShare]<br />
comment = Example Share<br />
path = /srv/exports/myshare<br />
read only = no<br />
browseable = yes<br />
valid users = @NETWORK+"Domain Admins" NETWORK+test.user<br />
</nowiki>}}<br />
<br />
In the above example, the keyword '''NETWORK''' is to be used. Do not mistakenly substitute this with your domain name. For adding groups, prepend the '@' symbol to the group. Note that {{ic|Domain Admins}} is encapsulated in quotes so Samba correctly parses it when reading the configuration file.<br />
<br />
=== Adding a machine keytab file and activating password-free kerberized ssh to the machine ===<br />
<br />
This explains how to generate a machine keytab file which you will need e.g. to enable password-free kerberized ssh to your machine from other machines in the domain. The scenario in mind is that you have a bunch of systems in your domain and you just added a server/workstation using the above description to your domain onto which a lot of users need to ssh in order to work - e.g. GPU workstation or an OpenMP compute node, etc. In this case you might not want to type your password every time you log in. On the other hand the key authentication used by many users in this case can not give you the necessary credentials to e.g. mount kerberized NFSv4 shares. So this will help you to enable password-free logins from your clients to the machine in question using kerberos ticket forwarding.<br />
<br />
==== <s>Creating a machine key tab file</s> ====<br />
<br />
run 'net ads keytab create -U administrator' as root to create a machine keytab file in /etc/krb5.keytab. It will prompt you with a warning that we need to enable keytab authentication in our configuration file, so we will do that in the next step. In my case it had problems when a key tab file is already in place - the command just did not come back it hang ... In that case you should rename the existing /etc/krb5.keytab and run the command again - it should work now.<br />
<br />
{{bc|# net ads keytab create -U administrator}}<br />
<br />
verify the content of your keytab by running:<br />
<br />
{{hc|# klist -k /etc/krb5.keytab|<nowiki><br />
Keytab name: FILE:/etc/krb5.keytab<br />
KVNO Principal<br />
---- --------------------------------------------------------------------------<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
</nowiki>}}<br />
<br />
==== <s>Enabling keytab authentication</s> ====<br />
<br />
Now you need to tell winbind to use the file by adding these lines to the /etc/samba/smb.conf:<br />
<br />
kerberos method = secrets and keytab<br />
dedicated keytab file = /etc/krb5.keytab<br />
<br />
It should look something like this:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
netbios name = MYARCHLINUX<br />
workgroup = EXAMPLE<br />
realm = EXAMPLE.COM<br />
server string = %h ArchLinux Host<br />
security = ads<br />
encrypt passwords = yes<br />
password server = pdc.example.com<br />
kerberos method = secrets and keytab<br />
dedicated keytab file = /etc/krb5.keytab<br />
<br />
idmap config * : backend = tdb<br />
idmap config * : range = 10000-20000<br />
<br />
winbind use default domain = Yes<br />
winbind enum users = Yes<br />
winbind enum groups = Yes<br />
winbind nested groups = Yes<br />
winbind separator = +<br />
winbind refresh tickets = yes<br />
<br />
template shell = /bin/bash<br />
template homedir = /home/%D/%U<br />
<br />
preferred master = no<br />
dns proxy = no<br />
wins server = pdc.example.com<br />
wins proxy = no<br />
<br />
inherit acls = Yes<br />
map acl inherit = Yes<br />
acl group control = yes<br />
<br />
load printers = no<br />
debug level = 3<br />
use sendfile = no<br />
</nowiki>}}<br />
<br />
Restart the winbind daemon using 'systemctl restart winbindd.service' with root privileges.<br />
<br />
{{bc|# systemctl restart winbindd.service}}<br />
<br />
Check if everything works by getting a machine ticket for your system by running <br />
<br />
{{bc|# kinit MYARCHLINUX$ -kt /etc/krb5.keytab}}<br />
<br />
This should not give you any feedback but running 'klist' should show you sth like:<br />
<br />
{{hc|# klist|<br />
Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: MYARCHLINUX$@EXAMPLE.COM<br />
<br />
Valid starting Expires Service principal <br />
02/04/12 21:27:47 02/05/12 07:27:42 krbtgt/EXAMPLE.COM@EXAMPLE.COM<br />
renew until 02/05/12 21:27:47<br />
}}<br />
<br />
Some common mistakes here are a) forgetting the trailing $ or b) ignoring case sensitivity - it needs to look exactly like the entry in the keytab (usually you cannot to much wrong with all capital)<br />
<br />
==== Preparing sshd on server ====<br />
<br />
All we need to do is add some options to our sshd_config and restart the sshd.service.<br />
<br />
Edit /etc/ssh/sshd_config to look like this in the appropriate places:<br />
<br />
{{hc|# /etc/ssh/sshd_config|<br />
<br />
...<br />
<br />
# Change to no to disable s/key passwords<br />
ChallengeResponseAuthentication no<br />
<br />
# Kerberos options<br />
KerberosAuthentication yes<br />
#KerberosOrLocalPasswd yes<br />
KerberosTicketCleanup yes<br />
KerberosGetAFSToken yes<br />
<br />
# GSSAPI options<br />
GSSAPIAuthentication yes<br />
GSSAPICleanupCredentials yes<br />
<br />
...<br />
<br />
}}<br />
<br />
Restart the sshd.service using:<br />
<br />
{{bc|# systemctl restart sshd.service}}<br />
<br />
==== Adding necessary options on client ====<br />
<br />
First we need to make sure that the tickets on our client are forwardable. This is usually standard but we better check anyways. You have to look for the forwardable option and set it to 'true' in the Kerberos config file /etc/krb5.conf<br />
<br />
{{bc|<nowiki>forwardable = true</nowiki>}}<br />
<br />
Secondly we need to add the options <br />
<br />
GSSAPIAuthentication yes<br />
GSSAPIDelegateCredentials yes<br />
<br />
to our .ssh/config file to tell ssh to use this options - alternatively they can be invoked using the -o options directly in the ssh command (see 'man ssh' for help).<br />
<br />
==== Testing the setup ====<br />
<br />
On Client:<br />
<br />
make sure you have a valid ticket - if in doubt run 'kinit'<br />
<br />
then use ssh to connect to you machine<br />
<br />
{{bc|ssh myarchlinux.example.com }}<br />
<br />
you should get connected without needing to enter your password.<br />
<br />
if you have key authentication additionally activated then you should perform<br />
<br />
{{bc|ssh -v myarchlinux.example.com }}<br />
<br />
to see which authentication method it actually uses.<br />
<br />
For debugging you can enable DEBUG3 on the server and look into the journal using [[journalctl]].<br />
<br />
==== Nifty fine-tuning for complete password-free kerberos handling. ====<br />
<br />
In case your clients are not using domain accounts on their local machines (for whatever reason) it can be hard to actually teach them to kinit before ssh to the workstation. Therefore I came up with a nice workaround:<br />
<br />
=== Generating user Keytabs which are accepted by AD ===<br />
<br />
On a system let the user run:<br />
<br />
{{bc|<nowiki><br />
ktutil<br />
addent -password -p username@EXAMPLE.COM -k 1 -e RC4-HMAC<br />
- enter password for username -<br />
wkt username.keytab<br />
q<br />
</nowiki>}}<br />
<br />
Now test the file by invoking:<br />
<br />
{{bc|kinit username@EXAMPLE.COM -kt username.keytab}}<br />
<br />
It should not promt you to give your password nor should it give any other feedback. If it worked you are basically done - just put the line above into your ~./bashrc - you can now get kerberos tickets without typing a password and with that you can connect to your workstation without typing a password while being completely kerberized and able to authenticate against NFSv4 and CIFS via tickets - pretty neat.<br />
<br />
==== Nice to know ====<br />
<br />
The file 'username.keytab' is not machinespecific and can therefore be copied around. E.g. we created the files on a linux machine and copied them to our Mac clients as the commands on Macs are different ...<br />
<br />
=== See also ===<br />
<br />
* [[wikipedia:Active_Directory|Wikipedia - Active Directory]]<br />
* [[wikipedia:Samba_(software)|Wikipedia - Samba]]<br />
* [[wikipedia:Kerberos_(protocol)|Wikipedia - Kerberos]]<br />
* [https://www.samba.org/samba/docs Samba - Documentation]<br />
* [https://wiki.samba.org/index.php/Samba,_Active_Directory_&_LDAP Samba Wiki - Samba, Active Directory & LDAP]<br />
* {{man|5|smb.conf}}<br />
<br />
==== Using SSSD ====<br />
<br />
{{pkg|sssd}} can be used instead of Samba to integrate with AD. See [https://sssd.io/docs/ad/ad-introduction.html SSSD documentation].<br />
<br />
==== Commercial Solutions ====<br />
<br />
* Centrify<br />
* Likewise<br />
<br />
==== OpenSource version ====<br />
<br />
* [https://github.com/BeyondTrust/pbis-open/ PowerBroker Identity Services Open]: formerly Likewise acquired by BeyondTrust<br />
* [https://www.centrify.com/express/linux/ Centrify Express for Linux]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Active_Directory_integration&diff=695655Active Directory integration2021-09-13T19:02:12Z<p>Pgoetz: domain a -> a domain</p>
<hr />
<div>[[Category:Directory services]]<br />
[[es:Active Directory integration]]<br />
[[ja:Active Directory Integration]]<br />
[[ru:Active Directory integration]]<br />
{{Related articles start}}<br />
{{Related|Samba}}<br />
{{Related|Samba/Active Directory domain controller}}<br />
{{Related|SOGo}}<br />
{{Related articles end}}<br />
<br />
{{Expansion|This page is currently being updated. The original page has been left intact until the rewrite is complete, see the section labeled '''Old Wiki Article''' for the original contents. Sections using the <s>strikethrough</s> in the title, have already been covered in the new sections.}}<br />
<br />
From [[w:Active Directory|Wikipedia]]:<br />
:Active Directory (AD) is a [[Wikipedia:directory service|directory service]] that Microsoft developed for [[Wikipedia:Windows domain|Windows domain]] networks.<br />
<br />
This article describes how to integrate an Arch Linux system with an existing Windows domain network using [[Samba]].<br />
<br />
Before continuing, you must have an existing Active Directory domain, and have a user with the appropriate rights within the domain to: query users and add computer accounts (Domain Join). <br />
<br />
This document is not an intended as a complete guide to Active Directory nor Samba. Refer to the resources section for additional information.<br />
<br />
== Introduction ==<br />
<br />
This article explains how to configure an Arch Linux system to participate in an Active Directory domain. This article was written and tested on a fresh installation, and it is assumed that all configuration files are in their unmodified, post-installation state. For the duration of the article, the example Active Directory domain will use the following configuration:<br />
<br />
* NetBIOS domain name: '''INTERNAL'''<br />
* DNS domain name: '''internal.domain.tld'''<br />
* Kerberos realm: '''INTERNAL.DOMAIN.TLD'''<br />
* First DC: '''server1.internal.domain.tld''' with IP address '''192.168.1.1'''<br />
* Second DC: '''server2.internal.domain.tld''' with IP address '''192.168.1.2'''<br />
<br />
In most small networks, the DCs (domain controllers) also hold the DNS server role. This may not be true in larger networks. Generally, DCs also hold the NTP role, but not always. Consult your network administrator to verify correct values for DNS and NTP servers.<br />
<br />
== Needed Software ==<br />
<br />
In order to use samba effectively, you will need to install the following packages: {{Pkg|samba}}, {{Pkg|smbclient}}, and {{Pkg|ntp}}. (You can use systemd timedatectl as an alternative to ntp.)<br />
<br />
Additionally, while not required, the following packages will be useful for testing and troubleshooting: {{Pkg|bind}}, {{Pkg|krb5}}, and if a printing is desired (whether you want to share printers, or use printers on another Samba/Windows host), {{Pkg|cups}}.<br />
<br />
== Initial Configuration of Services ==<br />
<br />
=== DNS Configuration ===<br />
<br />
Active Directory depends entirely on DNS for name resolution. It is imperative that the {{ic|/etc/resolv.conf}} file is configured with both the correct DNS servers and a domain search suffix. Whether configured via DHCP or static configuration, ensure that these values are correct for your domain. For the example domain configuration, the following contents are appropriate (be sure to replace '''192.168.1.1''', '''192.168.1.2''', and '''internal.domain.tld''' with appropriate values for your network):<br />
<br />
{{hc|/etc/resolv.conf|<nowiki><br />
nameserver </nowiki>'''192.168.1.1'''<nowiki><br />
nameserver </nowiki>'''192.168.1.2'''<nowiki><br />
search </nowiki>'''internal.domain.tld'''}}<br />
<br />
If you elected to install the {{Pkg|bind}} package, you can test DNS configuration with the following commands (be sure to replace '''server1''' and '''internal.domain.tld''' with appropriate values for your network):<br />
<br />
$ nslookup -type=SRV _kerberos._tcp.'''internal.domain.tld'''.<br />
$ nslookup -type=SRV _ldap._tcp.'''internal.domain.tld'''.<br />
$ nslookup '''server1'''.'''internal.domain.tld'''.<br />
<br />
You should get output similar to the following (adjust appropriately for only one DC, or more than two):<br />
<br />
Server: 192.168.1.1<br />
Address: 192.168.1.1#53<br />
<br />
_kerberos._tcp.internal.domain.tld service = 0 100 88 server1.internal.domain.tld.<br />
_kerberos._tcp.internal.domain.tld service = 0 100 88 server2.internal.domain.tld.<br />
...<br />
_ldap._tcp.internal.domain.tld service = 0 100 389 server1.internal.domain.tld.<br />
_ldap._tcp.internal.domain.tld service = 0 100 389 server2.internal.domain.tld.<br />
...<br />
Name: server1.internal.domain.tld<br />
Address: 192.168.1.1<br />
<br />
=== NTP Configuration ===<br />
<br />
In an Active Directory domain, more specifically for Kerberos ticketing, it is imperative that time is synchronized will all other hosts on the network. A margin of error no more than five minutes is required. For the example domain configuration, an appropriate {{ic|/etc/ntp.conf}} file should have the following contents (be sure to replace '''server1''', '''server2''', and '''internal.domain.tld''' with appropriate values for your network):<br />
<br />
{{hc|/etc/ntp.conf|<nowiki><br />
# Use your domain's NTP servers <br />
server </nowiki>'''server1'''.'''internal.domain.tld'''<nowiki><br />
server </nowiki>'''server2'''.'''internal.domain.tld'''<nowiki><br />
<br />
# Restrictions<br />
restrict default kod limited nomodify nopeer noquery notrap<br />
restrict 127.0.0.1<br />
restrict ::1<br />
<br />
# Location of drift file<br />
driftfile /var/lib/ntp/ntpd.drift</nowiki>}}<br />
<br />
Enable and start the {{ic|ntpd.service}} unit.<br />
<br />
=== Kerberos Configuration ===<br />
<br />
The Samba documentation recommends a minimal Kerberos configuration, with just enough information in the '''[libdefaults]''' section to hand off the work of discovering domain details to DNS. Unfortunately, this does not work well in practice. Continuing with the example domain configuration, modify the {{ic|/etc/krb.conf}} file with the following contents (be sure to replace instances of '''INTERNAL''', '''internal.domain.tld''', '''SERVER1''', and '''INTERNAL.DOMAIN.TLD''' with appropriate values for your network):<br />
<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
default_realm = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
dns_lookup_realm = false<br />
dns_lookup_kdc = true<br />
<br />
[realms]<br />
</nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki> = {<br />
kdc = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
default_domain = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
admin_server = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
}<br />
</nowiki>'''INTERNAL'''<nowiki> = {<br />
kdc = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
default_domain = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
admin_server = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
}<br />
<br />
[domain_realm]<br />
</nowiki>.'''internal.domain.tld'''<nowiki> = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
<br />
[appdefaults]<br />
pam = {<br />
ticket_lifetime = 1d<br />
renew_lifetime = 1d<br />
forwardable = true<br />
proxiable = false<br />
minimum_uid = 1<br />
}<br />
<br />
</nowiki>}}<br />
<br />
=== Samba Configuration ===<br />
<br />
==== Base Samba Configuration File ====<br />
<br />
A default installation of {{Pkg|samba}} does not ship with an example {{ic|/etc/samba/smb.conf}} file. For our example domain configuration, use the following base settings (replace instances of '''INTERNAL''' and '''INTERNAL.DOMAIN.TLD''' with appropriate values for your network):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
workgroup = </nowiki>'''INTERNAL'''<nowiki><br />
security = ADS<br />
realm = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
<br />
winbind refresh tickets = Yes<br />
vfs objects = acl_xattr<br />
map acl inherit = Yes<br />
store dos attributes = Yes<br />
<br />
# Allow a single, unified keytab to store obtained Kerberos tickets<br />
dedicated keytab file = /etc/krb5.keytab<br />
kerberos method = secrets and keytab<br />
<br />
# Do not require that login usernames include the default domain<br />
winbind use default domain = yes</nowiki>}}<br />
<br />
If you do not wish to share local printers configured in {{Pkg|cups}}, then add the following to the [Global] section of the {{ic|/etc/samba/smb.conf}} file:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
load printers = no<br />
printing = bsd<br />
printcap name = /dev/null<br />
disable spoolss = yes<br />
...</nowiki>}}<br />
<br />
The remainder of the configuration depends on whether your domain supports RFC2307 Unix/NFS Attributes. Consult with your domain administrator if unsure.<br />
<br />
===== Adding the idmap Configuration for Domains With RFC2307 Extensions =====<br />
<br />
Be certain that the values below do not overlap with system values, and that all users have at least the ''uidNubmer'' attribute, and that those users' ''PrimaryGroup'' has a ''gid'' attribute. Append to the following to the the [Global] section of the {{ic|/etc/samba/smb.conf}} file (replace '''INTERNAL''' with the NetBIOS domain name):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
<br />
# UID/GID mapping for local users<br />
idmap config * : backend = tdb<br />
idmap config * : range = 3000-7999<br />
<br />
# UID/GID mapping for domain users<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : backend = ad<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : schema_mode = rfc2307<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : range = 10000-999999<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : unix_nss_info = yes<br />
<br />
# Template settings for users without ''unixHomeDir'' and ''loginShell'' attributes <br />
template shell = /bin/bash<br />
template homedir = /home/%U<br />
<br />
# Allow offline/cached credentials and ticket refresh<br />
winbind offline logon = yes<br />
winbind refresh tickets = yes<br />
...</nowiki>}}<br />
<br />
Additionally, if user accounts in AD have a ''gidNumber'' attribute, you can use it instead of the RID for the user's ''Primary Group'' by appending the following setting (again in the [Global] section):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
idmap config </nowiki>'''INTERNAL'''<nowiki>:unix_primary_group = yes<br />
...</nowiki>}}<br />
<br />
===== Adding the idmap Configuration for Domains Without RFC2307 Extensions =====<br />
<br />
If your administrator has not extended the AD schema to include the RFC2307 attributes, use the following idmap configuration in the [Global] section of the {{ic|/etc/samba/smb.conf}} file (replace '''INTERNAL''' with the NetBIOS domain name):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
# UID/GID mapping for local users<br />
idmap config * : backend = tdb<br />
idmap config * : range = 3000-7999<br />
<br />
# UID/GID mapping for domain users<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : backend = rid<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : range = 10000-999999<br />
<br />
# Template settings for users<br />
template shell = /bin/bash<br />
template homedir = /home/%U<br />
<br />
# Allow offline/cached credentials and ticket refresh<br />
winbind offline logon = yes<br />
winbind refresh tickets = yes<br />
...</nowiki>}}<br />
<br />
== Joining the Domain ==<br />
<br />
To join the AD domain, simply issue the following command (be sure to replace '''Administrator''' with a user that has privileges to join the AD domain).<br />
<br />
# net ads join -U Administrator<br />
<br />
== Start the Individual Samba Services ==<br />
<br />
Enable and start the {{ic|smb.service}}, {{ic|nmb.service}}, and {{ic|winbind.service}} services.<br />
<br />
== Configure NSS ==<br />
<br />
Modify the {{ic|/etc/nsswitch.conf}} file to allow Samba to map names to uid and gid:<br />
<br />
{{hc|/etc/nsswitch.conf|<nowiki><br />
...<br />
passwd: files winbind mymachines systemd<br />
group: files winbind mymachines systemd<br />
...</nowiki>}}<br />
<br />
=== Testing NSS ===<br />
<br />
Verify connectivity by listing the AD domain users and groups that system is aware of:<br />
<br />
# wbinfo -u<br />
# wbinfo -g<br />
<br />
You should get a list of AD users followed by AD groups.<br />
<br />
== Configuring PAM authentication ==<br />
<br />
Rather than configuring options directly in the ''Linux-PAM'' configuration files, set defaults for the ''pam_winbind'' module in {{ic|/etc/security/pam_winbind.conf}}:<br />
<br />
{{hc|/etc/security/pam_winbind.conf|<nowiki><br />
[Global]<br />
debug = no<br />
debug_state = no<br />
try_first_pass = yes<br />
krb5_auth = yes<br />
krb5_ccache_type = FILE:/run/user/%u/krb5cc<br />
cached_login = yes<br />
silent = no<br />
mkhomedir = yes</nowiki>}}<br />
<br />
For most services, it will be sufficient to modify only the {{ic|/etc/pam.d/system-auth}} file. Any configuration for programs that do not include this file will also need to be modified directly. Create a backup of the {{ic|/etc/pam.d/system-auth}} file and use the following configuration:<br />
<br />
{{hc|/etc/pam.d/system-auth|<nowiki><br />
#%PAM-1.0<br />
<br />
auth sufficient pam_winbind.so<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
account sufficient pam_winbind.so<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
password sufficient pam_winbind.so<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
session required pam_limits.so<br />
session required pam_winbind.so<br />
session required pam_unix.so<br />
session optional pam_permit.so</nowiki>}}<br />
<br />
If you have other services that do not include the {{ic|/etc/pam.d/system-auth}} file, modify the configuration to mirror all ''pam_unix.so'' entries for ''pam_winbind.so'' and change all ''required'' to ''sufficient''. A good example is the su configuration. Create a backup of the {{ic|/etc/pam.d/su}} file and use the following in its place:<br />
<br />
{{hc|/etc/pam.d/su|<nowiki><br />
#%PAM-1.0<br />
<br />
auth sufficient pam_rootok.so<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth required pam_wheeel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth sufficient pam_winbind.so<br />
auth required pam_unix.so<br />
account sufficient pam_winbind.so<br />
account required pam_unix.so<br />
session sufficient pam_winbind.so<br />
session required pam_unix.so</nowiki>}}<br />
<br />
The above pam_winbind configuration will not use the default location of the Kerberos ticket ({{ic|KRB5CCNAME}}), which is at {{ic|/tmp/krb5cc_''UID''}}. Instead, it stores the automatically refreshed Kerberos ticket to {{ic|/run/user/''UID''/krb5cc}}. Append the following to your krb5.conf to let Kerberos know your new location:<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
...<br />
default_ccache_name = /run/user/%{uid}/krb5cc<br />
...</nowiki>}}<br />
<br />
To test your changes, start a '''new''' console or ssh session (do not exit your existing session until you have tested thoroughly) and try to login using the AD credentials. The domain name is optional, as this was set in the Winbind configuration as 'default realm'. Please note that in the case of ssh, you will need to modify the {{ic|/etc/ssh/sshd_config}} file to allow kerberos authentication (see below). <br />
<br />
Run '''klist''' to verify that you have received a kerberos ticket. You should see something similar to:<br />
{{hc|$ klist|<br />
Ticket cache: FILE:/run/user/20000/krb5cc<br />
Default principal: administrator@INTERNAL.DOMAIN.TLD<br />
<br />
Valid starting Expires Service principal<br />
12/25/2020 03:35:21 12/25/2020 13:35:21 krbtgt/INTERNAL.DOMAIN.TLD@INTERNAL.DOMAIN.TLD<br />
renew until 12/26/2020 03:35:15<br />
}}<br />
<br />
Finally, you should test login as both the root user and a local unprivileged user before logging out of your existing (working) session.<br />
<br />
== Old Wiki Article ==<br />
<br />
Active Directory serves as a central location for network administration and security. It is responsible for authenticating and authorizing all users and computers within a Windows domain network, assigning and enforcing security policies for all computers in a network and installing or updating software on network computers. For example, when a user logs into a computer that is part of a Windows domain, it is Active Directory that verifies his or her password and specifies whether they is a system administrator or normal user. Server computers on which Active Directory is running are called domain controllers.<br />
<br />
Active Directory uses [[Wikipedia:Ldap|Lightweight Directory Access Protocol (LDAP)]] versions 2 and 3, Microsoft's version of [[Kerberos]] and DNS.<br />
<br />
=== Terminology ===<br />
<br />
If you are not familiar with Active Directory, there are a few keywords that are helpful to know.<br />
<br />
* '''Domain''' : The name used to group computers and accounts. <br />
* '''SID''' : Each computer that joins the domain as a member must have a unique SID or System Identifier.<br />
* '''SMB''' : Server Message Block.<br />
* '''NETBIOS''': Network naming protocol used as an alternative to DNS. Mostly legacy, but still used in Windows Networking.<br />
* '''WINS''': Windows Information Naming Service. Used for resolving Netbios names to windows hosts.<br />
* '''Winbind''': Protocol for windows authentication.<br />
<br />
=== <s>Active Directory configuration</s> ===<br />
<br />
This section works with the default configuration of Windows Server 2012 R2.<br />
<br />
==== <s>GPO considerations</s> ====<br />
<br />
Digital signing is enabled by default in Windows Server, and must be enabled at both the client and server level. For certain versions of Samba, Linux clients may experience issues connecting to the domain and/or shares. It's recommended you add the following parameters to your {{ic|smb.conf}} file: <br />
<br />
client signing = auto <br />
server signing = auto<br />
<br />
If that is not successful, you can disable ''Digital Sign Communication (Always)'' in the AD group policies. In your AD Group Policy editor, locate:<br />
<br />
Under ''Local policies > Security policies > Microsoft Network Server > Digital sign communication (Always)'' activate ''define this policy'' and use the ''disable'' radio button.<br />
<br />
If you use Windows Server 2008 R2, you need to modify that in ''GPO for Default Domain Controller Policy > Computer Setting > Policies > Windows Setting > Security Setting > Local Policies > Security Option > Microsoft network client: Digitally sign communications (always)''.<br />
<br />
Please note that disabling this GPO affects the security of all members of the domain.<br />
<br />
=== <s>Linux host configuration</s> ===<br />
<br />
The next few steps will begin the process of configuring the Host. You will need root or sudo access to complete these steps.<br />
<br />
==== <s>Installation</s> ====<br />
<br />
[[Install]] the following packages:<br />
* {{Pkg|samba}}, see also [[Samba]]<br />
* {{Pkg|pam-krb5}}<br />
* {{Pkg|ntp}} or {{Pkg|openntpd}}, see also [[NTPd]] or [[OpenNTPD]]<br />
<br />
==== <s>Updating DNS</s> ====<br />
<br />
Active Directory is heavily dependent upon DNS. You will need to update {{ic|/etc/resolv.conf}} to use one or more of the Active Directory domain controllers:<br />
{{hc|/etc/resolv.conf|<br />
nameserver <IP1><br />
nameserver <IP2><br />
}}<br />
Replacing <IP1> and <IP2> with valid IP addresses for the AD servers. If your AD domains do not permit DNS forwarding or recursion, you may need to add additional resolvers. <br />
<br />
{{Note|If your machine dual boots Windows and Linux, you should use a different DNS hostname and netbios name for the linux configuration if both operating systems will be members of the same domain.}}<br />
<br />
==== <s>Configuring NTP</s> ====<br />
<br />
Read [[System time#Time synchronization]] to configure an NTP service.<br />
<br />
On the NTP servers configuration, use the IP addresses for the AD servers, as they typically run NTP as a service. Alternatively, you can use other known NTP servers provided the Active directory servers sync to the same stratum.<br />
<br />
Ensure that the service is configured to sync the time automatically very early on startup.<br />
<br />
==== <s>Kerberos</s> ====<br />
<br />
Let us assume that your AD is named example.com. Let us further assume your AD is ruled by two domain controllers, the primary and secondary one, which are named PDC and BDC, pdc.example.com and bdc.example.com respectively. Their IP adresses will be 192.168.1.2 and 192.168.1.3 in this example. Take care to watch your syntax; upper-case is very important here.<br />
<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
default_realm = EXAMPLE.COM<br />
clockskew = 300<br />
ticket_lifetime = 1d<br />
forwardable = true<br />
proxiable = true<br />
dns_lookup_realm = true<br />
dns_lookup_kdc = true<br />
<br />
[realms]<br />
EXAMPLE.COM = {<br />
kdc = PDC.EXAMPLE.COM<br />
admin_server = PDC.EXAMPLE.COM<br />
default_domain = EXAMPLE.COM<br />
}<br />
<br />
[domain_realm]<br />
.kerberos.server = EXAMPLE.COM<br />
.example.com = EXAMPLE.COM<br />
example.com = EXAMPLE.COM<br />
example = EXAMPLE.COM<br />
<br />
[appdefaults]<br />
pam = {<br />
ticket_lifetime = 1d<br />
renew_lifetime = 1d<br />
forwardable = true<br />
proxiable = false<br />
retain_after_close = false<br />
minimum_uid = 0<br />
debug = false<br />
}<br />
<br />
[logging]<br />
default = FILE:/var/log/krb5libs.log<br />
kdc = FILE:/var/log/kdc.log<br />
admin_server = FILE:/var/log/kadmind.log<br />
</nowiki>}}<br />
<br />
{{Note|Heimdal 1.3.1 deprecated DES encryption which is required for AD authentication before Windows Server 2008. You will probably have to add {{bc|1=allow_weak_crypto = true}} to the {{Ic|[libdefaults]}} section.}}<br />
<br />
===== <s>Creating a Kerberos ticket</s> =====<br />
<br />
{{note|The keys and commands are user specific: sudo will be root, so your non-elevated account can connect to a different AD user with a separate key. If you only have one domain, it is not necessary to type @EXAMPLE.COM}}<br />
<br />
Now you can query the AD domain controllers and request a kerberos ticket ('''uppercase is necessary'''):<br />
{{bc|kinit administrator@EXAMPLE.COM}}<br />
<br />
You can use any username that has rights as a Domain Administrator.<br />
<br />
===== <s>Validating the Ticket</s> =====<br />
<br />
Run '''klist''' to verify you did receive the token. You should see something similar to:<br />
{{hc|# klist|<br />
Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: administrator@EXAMPLE.COM<br />
<br />
Valid starting Expires Service principal <br />
02/04/12 21:27:47 02/05/12 07:27:42 krbtgt/EXAMPLE.COM@EXAMPLE.COM<br />
renew until 02/05/12 21:27:47<br />
}}<br />
<br />
==== <s>pam_winbind.conf</s> ====<br />
<br />
If you get errors stating that /etc/security/pam_winbind.conf was not found, create the file and add the following:<br />
<br />
{{hc|/etc/security/pam_winbind.conf|<nowiki><br />
[global]<br />
debug = no<br />
debug_state = no<br />
try_first_pass = yes<br />
krb5_auth = yes<br />
krb5_ccache_type = FILE<br />
cached_login = yes<br />
silent = no<br />
mkhomedir = yes<br />
</nowiki>}}<br />
<br />
With this setup, winbind will create user keytabs on the fly (krb5_ccache_type = FILE) at login and maintain them. You can verify this by simply running klist in a shell after logging in as an AD user but without needing to run kinit. You may need to set additional permissions on /etc/krb5.keytab eg 640 instead of 600 to get this to work (see {{Bug|52621}} for example)<br />
<br />
==== <s>Samba</s> ====<br />
<br />
Samba is a free software re-implementation of the SMB/CIFS networking protocol. It also includes tools for Linux machines to act as Windows networking servers and clients.<br />
<br />
{{Note|The configuration can vary greatly depending on how the Windows environment is deployed. Be prepared to troubleshoot and research}}<br />
<br />
In this section, we will focus on getting Authentication to work first by editing the 'Global' section first. Later, we will go back and add shares.<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
netbios name = MYARCHLINUX<br />
workgroup = EXAMPLE<br />
realm = EXAMPLE.COM<br />
server string = %h ArchLinux Host<br />
security = ads<br />
encrypt passwords = yes<br />
password server = pdc.example.com<br />
client signing = auto<br />
server signing = auto<br />
<br />
idmap config * : backend = tdb<br />
idmap config * : range = 10000-20000<br />
<br />
winbind use default domain = Yes<br />
winbind enum users = Yes<br />
winbind enum groups = Yes<br />
winbind nested groups = Yes<br />
winbind separator = +<br />
winbind refresh tickets = yes<br />
winbind offline logon = yes<br />
winbind cache time = 300<br />
<br />
template shell = /bin/bash<br />
template homedir = /home/%D/%U<br />
<br />
preferred master = no<br />
dns proxy = no<br />
wins server = pdc.example.com<br />
wins proxy = no<br />
<br />
inherit acls = Yes<br />
map acl inherit = Yes<br />
acl group control = yes<br />
<br />
load printers = no<br />
debug level = 3<br />
use sendfile = no<br />
</nowiki>}}<br />
<br />
==== <s>Join the domain</s> ====<br />
<br />
You need an AD Administrator account to do this. Let us assume this is named Administrator. The command is 'net ads join'<br />
{{hc|# net ads join -U Administrator|<br />
Administrator's password: xxx<br />
Using short domain name -- EXAMPLE<br />
Joined 'MYARCHLINUX' to realm 'EXAMPLE.COM'<br />
}}<br />
<br />
=== <s>Starting and testing services</s> ===<br />
<br />
==== <s>Starting Samba</s> ====<br />
<br />
Hopefully, you have not rebooted yet! Fine. If you are in an X-session, quit it, so you can test login into another console, while you are still logged in.<br />
<br />
Enable and start the individual Samba daemons {{ic|smbd.service}}, {{ic|nmbd.service}}, and {{ic|winbindd.service}}.<br />
<br />
{{Note|In {{Pkg|samba}} 4.8.0-1, the Samba daemon units have been renamed from {{ic|smbd.service}}, {{ic|nmbd.service}}, and {{ic|winbindd.service}} to {{ic|smb.service}}, {{ic|nmb.service}}, and {{ic|winbind.service}}.}}<br />
<br />
Next we will need to modify the NSSwitch configuration, which tells the Linux host how to retrieve information from various sources and in which order to do so. In this case, we are appending Active Directory as additional sources for Users, Groups, and Hosts.<br />
<br />
{{hc|/etc/nsswitch.conf|<br />
passwd: files winbind<br />
shadow: files winbind<br />
group: files winbind <br />
<br />
hosts: files dns wins<br />
}}<br />
<br />
==== <s>Testing Winbind</s> ====<br />
<br />
Let us check if winbind is able to query the AD. The following command should return a list of AD users:<br />
<br />
{{hc|# wbinfo -u|<br />
administrator<br />
guest<br />
krbtgt<br />
test.user<br />
}}<br />
* Note we created an Active Directory user called 'test.user' on the domain controller<br />
<br />
We can do the same for AD groups:<br />
<br />
{{hc|# wbinfo -g|<br />
domain computers<br />
domain controllers<br />
schema admins<br />
enterprise admins<br />
cert publishers<br />
domain admins<br />
domain users<br />
domain guests<br />
group policy creator owners<br />
ras and ias servers<br />
allowed rodc password replication group<br />
denied rodc password replication group<br />
read-only domain controllers<br />
enterprise read-only domain controllers<br />
dnsadmins<br />
dnsupdateproxy<br />
}}<br />
<br />
==== <s>Testing nsswitch</s> ====<br />
<br />
To ensure that our host is able to query the domain for users and groups, we test nsswitch settings by issuing the 'getent' command.<br />
<br />
The following output shows what a stock ArchLinux install looks like:<br />
<br />
{{hc|# getent passwd|<br />
root:x:0:0:root:/root:/bin/bash<br />
bin:x:1:1:bin:/bin:/bin/false<br />
daemon:x:2:2:daemon:/sbin:/bin/false<br />
mail:x:8:12:mail:/var/spool/mail:/bin/false<br />
ftp:x:14:11:ftp:/srv/ftp:/bin/false<br />
http:x:33:33:http:/srv/http:/bin/false<br />
nobody:x:99:99:nobody:/:/bin/false<br />
dbus:x:81:81:System message bus:/:/bin/false<br />
ntp:x:87:87:Network Time Protocol:/var/empty:/bin/false<br />
avahi:x:84:84:avahi:/:/bin/false<br />
administrator:*:10001:10006:Administrator:/home/EXAMPLE/administrator:/bin/bash<br />
guest:*:10002:10007:Guest:/home/EXAMPLE/guest:/bin/bash<br />
krbtgt:*:10003:10006:krbtgt:/home/EXAMPLE/krbtgt:/bin/bash<br />
test.user:*:10000:10006:Test User:/home/EXAMPLE/test.user:/bin/bash<br />
}}<br />
<br />
And for groups:<br />
{{hc|# getent group|<br />
root:x:0:root<br />
bin:x:1:root,bin,daemon<br />
daemon:x:2:root,bin,daemon<br />
sys:x:3:root,bin<br />
adm:x:4:root,daemon<br />
tty:x:5:<br />
disk:x:6:root<br />
lp:x:7:daemon<br />
mem:x:8:<br />
kmem:x:9:<br />
wheel:x:10:root<br />
ftp:x:11:<br />
mail:x:12:<br />
uucp:x:14:<br />
log:x:19:root<br />
utmp:x:20:<br />
locate:x:21:<br />
rfkill:x:24:<br />
smmsp:x:25:<br />
http:x:33:<br />
games:x:50:<br />
network:x:90:<br />
video:x:91:<br />
audio:x:92:<br />
optical:x:93:<br />
floppy:x:94:<br />
storage:x:95:<br />
scanner:x:96:<br />
power:x:98:<br />
nobody:x:99:<br />
users:x:100:<br />
dbus:x:81:<br />
ntp:x:87:<br />
avahi:x:84:<br />
domain computers:x:10008:<br />
domain controllers:x:10009:<br />
schema admins:x:10010:administrator<br />
enterprise admins:x:10011:administrator<br />
cert publishers:x:10012:<br />
domain admins:x:10013:test.user,administrator<br />
domain users:x:10006:<br />
domain guests:x:10007:<br />
group policy creator owners:x:10014:administrator<br />
ras and ias servers:x:10015:<br />
allowed rodc password replication group:x:10016:<br />
denied rodc password replication group:x:10017:krbtgt<br />
read-only domain controllers:x:10018:<br />
enterprise read-only domain controllers:x:10019:<br />
dnsadmins:x:10020:<br />
dnsupdateproxy:x:10021:<br />
}}<br />
<br />
==== Testing Samba commands ====<br />
<br />
Try out some net commands to see if Samba can communicate with AD:<br />
<br />
{{hc|# net ads info|<nowiki><br />
[2012/02/05 20:21:36.473559, 0] param/loadparm.c:7599(lp_do_parameter)<br />
Ignoring unknown parameter "idmapd backend"<br />
LDAP server: 192.168.1.2<br />
LDAP server name: PDC.example.com<br />
Realm: EXAMPLE.COM<br />
Bind Path: dc=EXAMPLE,dc=COM<br />
LDAP port: 389<br />
Server time: Sun, 05 Feb 2012 20:21:33 CST<br />
KDC server: 192.168.1.2<br />
Server time offset: -3<br />
</nowiki>}}<br />
<br />
{{hc|# net ads lookup|<br />
[2012/02/05 20:22:39.298823, 0] param/loadparm.c:7599(lp_do_parameter)<br />
Ignoring unknown parameter "idmapd backend"<br />
Information for Domain Controller: 192.168.1.2<br />
<br />
Response Type: LOGON_SAM_LOGON_RESPONSE_EX<br />
GUID: 2a098512-4c9f-4fe4-ac22-8f9231fabbad<br />
Flags:<br />
Is a PDC: yes<br />
Is a GC of the forest: yes<br />
Is an LDAP server: yes<br />
Supports DS: yes<br />
Is running a KDC: yes<br />
Is running time services: yes<br />
Is the closest DC: yes<br />
Is writable: yes<br />
Has a hardware clock: yes<br />
Is a non-domain NC serviced by LDAP server: no<br />
Is NT6 DC that has some secrets: no<br />
Is NT6 DC that has all secrets: yes<br />
Forest: example.com<br />
Domain: example.com<br />
Domain Controller: PDC.example.com<br />
Pre-Win2k Domain: EXAMPLE<br />
Pre-Win2k Hostname: PDC<br />
Server Site Name : Office<br />
Client Site Name : Office<br />
NT Version: 5<br />
LMNT Token: ffff<br />
LM20 Token: ffff<br />
}}<br />
<br />
{{hc|<nowiki># net ads status -U administrator%password | less</nowiki>|<nowiki><br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: user<br />
objectClass: computer<br />
cn: myarchlinux<br />
distinguishedName: CN=myarchlinux,CN=Computers,DC=leafscale,DC=inc<br />
instanceType: 4<br />
whenCreated: 20120206043413.0Z<br />
whenChanged: 20120206043414.0Z<br />
uSNCreated: 16556<br />
uSNChanged: 16563<br />
name: myarchlinux<br />
objectGUID: 2c24029c-8422-42b2-83b3-a255b9cb41b3<br />
userAccountControl: 69632<br />
badPwdCount: 0<br />
codePage: 0<br />
countryCode: 0<br />
badPasswordTime: 0<br />
lastLogoff: 0<br />
lastLogon: 129729780312632000<br />
localPolicyFlags: 0<br />
pwdLastSet: 129729764538848000<br />
primaryGroupID: 515<br />
objectSid: S-1-5-21-719106045-3766251393-3909931865-1105<br />
...<snip>...<br />
</nowiki>}}<br />
<br />
=== <s>Configuring PAM</s> ===<br />
<br />
Now we will change various rules in PAM to allow Active Directory users to use the system for things like login and sudo access. When changing the rules, note the order of these items and whether they are marked as '''required''' or '''sufficient''' is critical to things working as expected. You should not deviate from these rules unless you know how to write PAM rules.<br />
<br />
In case of logins, PAM should first ask for AD accounts, and for local accounts if no matching AD account was found. Therefore, we add entries to include {{ic|pam_winbind.so}} into the authentication process.<br />
<br />
The Arch Linux PAM configuration keeps the central auth process in {{ic|/etc/pam.d/system-auth}}. Starting with the stock configuration from {{ic|pambase}}, change it like this:<br />
<br />
==== <s>system-auth</s> ====<br />
<br />
===== <s>"auth" section</s> =====<br />
<br />
Find the line:<br />
<br />
auth required pam_unix.so ...<br />
<br />
Delete it, and replace with:<br />
<br />
auth [success=1 default=ignore] pam_localuser.so<br />
auth [success=2 default=die] pam_winbind.so<br />
auth [success=1 default=die] pam_unix.so nullok<br />
auth requisite pam_deny.so<br />
<br />
===== <s>"account" section</s> =====<br />
<br />
Find the line:<br />
<br />
account required pam_unix.so<br />
<br />
Keep it, and add this below:<br />
<br />
account [success=1 default=ignore] pam_localuser.so<br />
account required pam_winbind.so<br />
<br />
===== <s>"password" section</s> =====<br />
<br />
Find the line:<br />
<br />
password required pam_unix.so ...<br />
<br />
Delete it, and replace with:<br />
<br />
password [success=1 default=ignore] pam_localuser.so<br />
password [success=2 default=die] pam_winbind.so<br />
password [success=1 default=die] pam_unix.so sha512 shadow<br />
password requisite pam_deny.so<br />
<br />
===== <s>"session" section</s> =====<br />
<br />
Find the line:<br />
<br />
session required pam_unix.so<br />
<br />
Keep it, and add this line immediately above it:<br />
<br />
session required pam_mkhomedir.so skel=/etc/skel/ umask=0022<br />
<br />
Below the pam_unix line, add these:<br />
<br />
session [success=1 default=ignore] pam_localuser.so<br />
session required pam_winbind.so<br />
<br />
==== <s>passwd</s> ====<br />
<br />
===== <s>"password" section</s> =====<br />
<br />
In order for logged-in Active Directory users to be able to change their passwords with the 'passwd' command, the file {{ic|/etc/pam.d/passwd}} must include the information from system-auth.<br />
<br />
Find the line:<br />
<br />
password required pam_unix.so sha512 shadow nullok<br />
<br />
Delete it, and replace with:<br />
<br />
password include system-auth<br />
<br />
==== <s>Testing login</s> ====<br />
<br />
Now, start a new console session (or ssh) and try to login using the AD credentials. The domain name is optional, as this was set in the Winbind configuration as 'default realm'. Please note that in the case of ssh, you will need to modify the {{ic|/etc/ssh/sshd_config}} file to allow kerberos authentication {{ic|(KerberosAuthentication yes)}}.<br />
<br />
{{bc|<br />
test.user<br />
EXAMPLE+test.user<br />
}}<br />
<br />
Both should work. You should notice that {{ic|/home/example/test.user}} will be automatically created.<br />
'''Log into another session using an linux account. Check that you still be able to log in as root - but keep in mind to be logged in as root in at least one session!'''<br />
<br />
=== Configuring Shares ===<br />
<br />
Earlier we skipped configuration of the shares. Now that things are working, go back to {{ic|/etc/samba/smb.conf}}, and add the exports for the host that you want available on the windows network. <br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[MyShare]<br />
comment = Example Share<br />
path = /srv/exports/myshare<br />
read only = no<br />
browseable = yes<br />
valid users = @NETWORK+"Domain Admins" NETWORK+test.user<br />
</nowiki>}}<br />
<br />
In the above example, the keyword '''NETWORK''' is to be used. Do not mistakenly substitute this with your domain name. For adding groups, prepend the '@' symbol to the group. Note that {{ic|Domain Admins}} is encapsulated in quotes so Samba correctly parses it when reading the configuration file.<br />
<br />
=== Adding a machine keytab file and activating password-free kerberized ssh to the machine ===<br />
<br />
This explains how to generate a machine keytab file which you will need e.g. to enable password-free kerberized ssh to your machine from other machines in the domain. The scenario in mind is that you have a bunch of systems in your domain and you just added a server/workstation using the above description to your domain onto which a lot of users need to ssh in order to work - e.g. GPU workstation or an OpenMP compute node, etc. In this case you might not want to type your password every time you log in. On the other hand the key authentication used by many users in this case can not give you the necessary credentials to e.g. mount kerberized NFSv4 shares. So this will help you to enable password-free logins from your clients to the machine in question using kerberos ticket forwarding.<br />
<br />
==== <s>Creating a machine key tab file</s> ====<br />
<br />
run 'net ads keytab create -U administrator' as root to create a machine keytab file in /etc/krb5.keytab. It will prompt you with a warning that we need to enable keytab authentication in our configuration file, so we will do that in the next step. In my case it had problems when a key tab file is already in place - the command just did not come back it hang ... In that case you should rename the existing /etc/krb5.keytab and run the command again - it should work now.<br />
<br />
{{bc|# net ads keytab create -U administrator}}<br />
<br />
verify the content of your keytab by running:<br />
<br />
{{hc|# klist -k /etc/krb5.keytab|<nowiki><br />
Keytab name: FILE:/etc/krb5.keytab<br />
KVNO Principal<br />
---- --------------------------------------------------------------------------<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
</nowiki>}}<br />
<br />
==== <s>Enabling keytab authentication</s> ====<br />
<br />
Now you need to tell winbind to use the file by adding these lines to the /etc/samba/smb.conf:<br />
<br />
kerberos method = secrets and keytab<br />
dedicated keytab file = /etc/krb5.keytab<br />
<br />
It should look something like this:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
netbios name = MYARCHLINUX<br />
workgroup = EXAMPLE<br />
realm = EXAMPLE.COM<br />
server string = %h ArchLinux Host<br />
security = ads<br />
encrypt passwords = yes<br />
password server = pdc.example.com<br />
kerberos method = secrets and keytab<br />
dedicated keytab file = /etc/krb5.keytab<br />
<br />
idmap config * : backend = tdb<br />
idmap config * : range = 10000-20000<br />
<br />
winbind use default domain = Yes<br />
winbind enum users = Yes<br />
winbind enum groups = Yes<br />
winbind nested groups = Yes<br />
winbind separator = +<br />
winbind refresh tickets = yes<br />
<br />
template shell = /bin/bash<br />
template homedir = /home/%D/%U<br />
<br />
preferred master = no<br />
dns proxy = no<br />
wins server = pdc.example.com<br />
wins proxy = no<br />
<br />
inherit acls = Yes<br />
map acl inherit = Yes<br />
acl group control = yes<br />
<br />
load printers = no<br />
debug level = 3<br />
use sendfile = no<br />
</nowiki>}}<br />
<br />
Restart the winbind daemon using 'systemctl restart winbindd.service' with root privileges.<br />
<br />
{{bc|# systemctl restart winbindd.service}}<br />
<br />
Check if everything works by getting a machine ticket for your system by running <br />
<br />
{{bc|# kinit MYARCHLINUX$ -kt /etc/krb5.keytab}}<br />
<br />
This should not give you any feedback but running 'klist' should show you sth like:<br />
<br />
{{hc|# klist|<br />
Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: MYARCHLINUX$@EXAMPLE.COM<br />
<br />
Valid starting Expires Service principal <br />
02/04/12 21:27:47 02/05/12 07:27:42 krbtgt/EXAMPLE.COM@EXAMPLE.COM<br />
renew until 02/05/12 21:27:47<br />
}}<br />
<br />
Some common mistakes here are a) forgetting the trailing $ or b) ignoring case sensitivity - it needs to look exactly like the entry in the keytab (usually you cannot to much wrong with all capital)<br />
<br />
==== Preparing sshd on server ====<br />
<br />
All we need to do is add some options to our sshd_config and restart the sshd.service.<br />
<br />
Edit /etc/ssh/sshd_config to look like this in the appropriate places:<br />
<br />
{{hc|# /etc/ssh/sshd_config|<br />
<br />
...<br />
<br />
# Change to no to disable s/key passwords<br />
ChallengeResponseAuthentication no<br />
<br />
# Kerberos options<br />
KerberosAuthentication yes<br />
#KerberosOrLocalPasswd yes<br />
KerberosTicketCleanup yes<br />
KerberosGetAFSToken yes<br />
<br />
# GSSAPI options<br />
GSSAPIAuthentication yes<br />
GSSAPICleanupCredentials yes<br />
<br />
...<br />
<br />
}}<br />
<br />
Restart the sshd.service using:<br />
<br />
{{bc|# systemctl restart sshd.service}}<br />
<br />
==== Adding necessary options on client ====<br />
<br />
First we need to make sure that the tickets on our client are forwardable. This is usually standard but we better check anyways. You have to look for the forwardable option and set it to 'true' in the Kerberos config file /etc/krb5.conf<br />
<br />
{{bc|<nowiki>forwardable = true</nowiki>}}<br />
<br />
Secondly we need to add the options <br />
<br />
GSSAPIAuthentication yes<br />
GSSAPIDelegateCredentials yes<br />
<br />
to our .ssh/config file to tell ssh to use this options - alternatively they can be invoked using the -o options directly in the ssh command (see 'man ssh' for help).<br />
<br />
==== Testing the setup ====<br />
<br />
On Client:<br />
<br />
make sure you have a valid ticket - if in doubt run 'kinit'<br />
<br />
then use ssh to connect to you machine<br />
<br />
{{bc|ssh myarchlinux.example.com }}<br />
<br />
you should get connected without needing to enter your password.<br />
<br />
if you have key authentication additionally activated then you should perform<br />
<br />
{{bc|ssh -v myarchlinux.example.com }}<br />
<br />
to see which authentication method it actually uses.<br />
<br />
For debugging you can enable DEBUG3 on the server and look into the journal using [[journalctl]].<br />
<br />
==== Nifty fine-tuning for complete password-free kerberos handling. ====<br />
<br />
In case your clients are not using domain accounts on their local machines (for whatever reason) it can be hard to actually teach them to kinit before ssh to the workstation. Therefore I came up with a nice workaround:<br />
<br />
=== Generating user Keytabs which are accepted by AD ===<br />
<br />
On a system let the user run:<br />
<br />
{{bc|<nowiki><br />
ktutil<br />
addent -password -p username@EXAMPLE.COM -k 1 -e RC4-HMAC<br />
- enter password for username -<br />
wkt username.keytab<br />
q<br />
</nowiki>}}<br />
<br />
Now test the file by invoking:<br />
<br />
{{bc|kinit username@EXAMPLE.COM -kt username.keytab}}<br />
<br />
It should not promt you to give your password nor should it give any other feedback. If it worked you are basically done - just put the line above into your ~./bashrc - you can now get kerberos tickets without typing a password and with that you can connect to your workstation without typing a password while being completely kerberized and able to authenticate against NFSv4 and CIFS via tickets - pretty neat.<br />
<br />
==== Nice to know ====<br />
<br />
The file 'username.keytab' is not machinespecific and can therefore be copied around. E.g. we created the files on a linux machine and copied them to our Mac clients as the commands on Macs are different ...<br />
<br />
=== See also ===<br />
<br />
* [[wikipedia:Active_Directory|Wikipedia - Active Directory]]<br />
* [[wikipedia:Samba_(software)|Wikipedia - Samba]]<br />
* [[wikipedia:Kerberos_(protocol)|Wikipedia - Kerberos]]<br />
* [https://www.samba.org/samba/docs Samba - Documentation]<br />
* [https://wiki.samba.org/index.php/Samba,_Active_Directory_&_LDAP Samba Wiki - Samba, Active Directory & LDAP]<br />
* {{man|5|smb.conf}}<br />
<br />
==== Using SSSD ====<br />
<br />
{{pkg|sssd}} can be used instead of Samba to integrate with AD. See [https://sssd.io/docs/ad/ad-introduction.html SSSD documentation].<br />
<br />
==== Commercial Solutions ====<br />
<br />
* Centrify<br />
* Likewise<br />
<br />
==== OpenSource version ====<br />
<br />
* [https://github.com/BeyondTrust/pbis-open/ PowerBroker Identity Services Open]: formerly Likewise acquired by BeyondTrust<br />
* [https://www.centrify.com/express/linux/ Centrify Express for Linux]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Active_Directory_integration&diff=695654Active Directory integration2021-09-13T19:00:48Z<p>Pgoetz: ntp isn't needed; you can use systemd timedatectl</p>
<hr />
<div>[[Category:Directory services]]<br />
[[es:Active Directory integration]]<br />
[[ja:Active Directory Integration]]<br />
[[ru:Active Directory integration]]<br />
{{Related articles start}}<br />
{{Related|Samba}}<br />
{{Related|Samba/Active Directory domain controller}}<br />
{{Related|SOGo}}<br />
{{Related articles end}}<br />
<br />
{{Expansion|This page is currently being updated. The original page has been left intact until the rewrite is complete, see the section labeled '''Old Wiki Article''' for the original contents. Sections using the <s>strikethrough</s> in the title, have already been covered in the new sections.}}<br />
<br />
From [[w:Active Directory|Wikipedia]]:<br />
:Active Directory (AD) is a [[Wikipedia:directory service|directory service]] that Microsoft developed for [[Wikipedia:Windows domain|Windows domain]] networks.<br />
<br />
This article describes how to integrate an Arch Linux system with an existing Windows domain network using [[Samba]].<br />
<br />
Before continuing, you must have an existing Active Directory domain, and have a user with the appropriate rights within the domain to: query users and add computer accounts (Domain Join). <br />
<br />
This document is not an intended as a complete guide to Active Directory nor Samba. Refer to the resources section for additional information.<br />
<br />
== Introduction ==<br />
<br />
This article explains how to configure an Arch Linux system to participate in an Active Directory domain. This article was written and tested on a fresh installation, and it is assumed that all configuration files are in their unmodified, post-installation state. For the duration of the article, the example Active Directory domain will use the following configuration:<br />
<br />
* NetBIOS domain name: '''INTERNAL'''<br />
* DNS domain name: '''internal.domain.tld'''<br />
* Kerberos realm: '''INTERNAL.DOMAIN.TLD'''<br />
* First DC: '''server1.internal.domain.tld''' with IP address '''192.168.1.1'''<br />
* Second DC: '''server2.internal.domain.tld''' with IP address '''192.168.1.2'''<br />
<br />
In most small networks, the DCs (domain controllers) also hold the DNS server role. This may not be true in larger networks. Generally, DCs also hold the NTP role, but not always. Consult your network administrator to verify correct values for DNS and NTP servers.<br />
<br />
== Needed Software ==<br />
<br />
In order to use samba effectively, you will need to install the following packages: {{Pkg|samba}}, {{Pkg|smbclient}}, and {{Pkg|ntp}}. (You can use systemd timedatectl as an alternative to ntp.)<br />
<br />
Additionally, while not required, the following packages will be useful for testing and troubleshooting: {{Pkg|bind}}, {{Pkg|krb5}}, and if a printing is desired (whether you want to share printers, or use printers on another Samba/Windows host), {{Pkg|cups}}.<br />
<br />
== Initial Configuration of Services ==<br />
<br />
=== DNS Configuration ===<br />
<br />
Active Directory depends entirely on DNS for name resolution. It is imperative that the {{ic|/etc/resolv.conf}} file is configured with both the correct DNS servers and domain a search suffix. Whether configured via DHCP or static configuration, ensure that these values are correct for your domain. For the example domain configuration, the following contents are appropriate (be sure to replace '''192.168.1.1''', '''192.168.1.2''', and '''internal.domain.tld''' with appropriate values for your network):<br />
<br />
{{hc|/etc/resolv.conf|<nowiki><br />
nameserver </nowiki>'''192.168.1.1'''<nowiki><br />
nameserver </nowiki>'''192.168.1.2'''<nowiki><br />
search </nowiki>'''internal.domain.tld'''}}<br />
<br />
If you elected to install the {{Pkg|bind}} package, you can test DNS configuration with the following commands (be sure to replace '''server1''' and '''internal.domain.tld''' with appropriate values for your network):<br />
<br />
$ nslookup -type=SRV _kerberos._tcp.'''internal.domain.tld'''.<br />
$ nslookup -type=SRV _ldap._tcp.'''internal.domain.tld'''.<br />
$ nslookup '''server1'''.'''internal.domain.tld'''.<br />
<br />
You should get output similar to the following (adjust appropriately for only one DC, or more than two):<br />
<br />
Server: 192.168.1.1<br />
Address: 192.168.1.1#53<br />
<br />
_kerberos._tcp.internal.domain.tld service = 0 100 88 server1.internal.domain.tld.<br />
_kerberos._tcp.internal.domain.tld service = 0 100 88 server2.internal.domain.tld.<br />
...<br />
_ldap._tcp.internal.domain.tld service = 0 100 389 server1.internal.domain.tld.<br />
_ldap._tcp.internal.domain.tld service = 0 100 389 server2.internal.domain.tld.<br />
...<br />
Name: server1.internal.domain.tld<br />
Address: 192.168.1.1<br />
<br />
=== NTP Configuration ===<br />
<br />
In an Active Directory domain, more specifically for Kerberos ticketing, it is imperative that time is synchronized will all other hosts on the network. A margin of error no more than five minutes is required. For the example domain configuration, an appropriate {{ic|/etc/ntp.conf}} file should have the following contents (be sure to replace '''server1''', '''server2''', and '''internal.domain.tld''' with appropriate values for your network):<br />
<br />
{{hc|/etc/ntp.conf|<nowiki><br />
# Use your domain's NTP servers <br />
server </nowiki>'''server1'''.'''internal.domain.tld'''<nowiki><br />
server </nowiki>'''server2'''.'''internal.domain.tld'''<nowiki><br />
<br />
# Restrictions<br />
restrict default kod limited nomodify nopeer noquery notrap<br />
restrict 127.0.0.1<br />
restrict ::1<br />
<br />
# Location of drift file<br />
driftfile /var/lib/ntp/ntpd.drift</nowiki>}}<br />
<br />
Enable and start the {{ic|ntpd.service}} unit.<br />
<br />
=== Kerberos Configuration ===<br />
<br />
The Samba documentation recommends a minimal Kerberos configuration, with just enough information in the '''[libdefaults]''' section to hand off the work of discovering domain details to DNS. Unfortunately, this does not work well in practice. Continuing with the example domain configuration, modify the {{ic|/etc/krb.conf}} file with the following contents (be sure to replace instances of '''INTERNAL''', '''internal.domain.tld''', '''SERVER1''', and '''INTERNAL.DOMAIN.TLD''' with appropriate values for your network):<br />
<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
default_realm = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
dns_lookup_realm = false<br />
dns_lookup_kdc = true<br />
<br />
[realms]<br />
</nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki> = {<br />
kdc = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
default_domain = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
admin_server = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
}<br />
</nowiki>'''INTERNAL'''<nowiki> = {<br />
kdc = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
default_domain = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
admin_server = </nowiki>'''SERVER1'''.'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
}<br />
<br />
[domain_realm]<br />
</nowiki>.'''internal.domain.tld'''<nowiki> = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
<br />
[appdefaults]<br />
pam = {<br />
ticket_lifetime = 1d<br />
renew_lifetime = 1d<br />
forwardable = true<br />
proxiable = false<br />
minimum_uid = 1<br />
}<br />
<br />
</nowiki>}}<br />
<br />
=== Samba Configuration ===<br />
<br />
==== Base Samba Configuration File ====<br />
<br />
A default installation of {{Pkg|samba}} does not ship with an example {{ic|/etc/samba/smb.conf}} file. For our example domain configuration, use the following base settings (replace instances of '''INTERNAL''' and '''INTERNAL.DOMAIN.TLD''' with appropriate values for your network):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[global]<br />
workgroup = </nowiki>'''INTERNAL'''<nowiki><br />
security = ADS<br />
realm = </nowiki>'''INTERNAL.DOMAIN.TLD'''<nowiki><br />
<br />
winbind refresh tickets = Yes<br />
vfs objects = acl_xattr<br />
map acl inherit = Yes<br />
store dos attributes = Yes<br />
<br />
# Allow a single, unified keytab to store obtained Kerberos tickets<br />
dedicated keytab file = /etc/krb5.keytab<br />
kerberos method = secrets and keytab<br />
<br />
# Do not require that login usernames include the default domain<br />
winbind use default domain = yes</nowiki>}}<br />
<br />
If you do not wish to share local printers configured in {{Pkg|cups}}, then add the following to the [Global] section of the {{ic|/etc/samba/smb.conf}} file:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
load printers = no<br />
printing = bsd<br />
printcap name = /dev/null<br />
disable spoolss = yes<br />
...</nowiki>}}<br />
<br />
The remainder of the configuration depends on whether your domain supports RFC2307 Unix/NFS Attributes. Consult with your domain administrator if unsure.<br />
<br />
===== Adding the idmap Configuration for Domains With RFC2307 Extensions =====<br />
<br />
Be certain that the values below do not overlap with system values, and that all users have at least the ''uidNubmer'' attribute, and that those users' ''PrimaryGroup'' has a ''gid'' attribute. Append to the following to the the [Global] section of the {{ic|/etc/samba/smb.conf}} file (replace '''INTERNAL''' with the NetBIOS domain name):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
<br />
# UID/GID mapping for local users<br />
idmap config * : backend = tdb<br />
idmap config * : range = 3000-7999<br />
<br />
# UID/GID mapping for domain users<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : backend = ad<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : schema_mode = rfc2307<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : range = 10000-999999<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : unix_nss_info = yes<br />
<br />
# Template settings for users without ''unixHomeDir'' and ''loginShell'' attributes <br />
template shell = /bin/bash<br />
template homedir = /home/%U<br />
<br />
# Allow offline/cached credentials and ticket refresh<br />
winbind offline logon = yes<br />
winbind refresh tickets = yes<br />
...</nowiki>}}<br />
<br />
Additionally, if user accounts in AD have a ''gidNumber'' attribute, you can use it instead of the RID for the user's ''Primary Group'' by appending the following setting (again in the [Global] section):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
idmap config </nowiki>'''INTERNAL'''<nowiki>:unix_primary_group = yes<br />
...</nowiki>}}<br />
<br />
===== Adding the idmap Configuration for Domains Without RFC2307 Extensions =====<br />
<br />
If your administrator has not extended the AD schema to include the RFC2307 attributes, use the following idmap configuration in the [Global] section of the {{ic|/etc/samba/smb.conf}} file (replace '''INTERNAL''' with the NetBIOS domain name):<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
...<br />
# UID/GID mapping for local users<br />
idmap config * : backend = tdb<br />
idmap config * : range = 3000-7999<br />
<br />
# UID/GID mapping for domain users<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : backend = rid<br />
idmap config </nowiki>'''INTERNAL'''<nowiki> : range = 10000-999999<br />
<br />
# Template settings for users<br />
template shell = /bin/bash<br />
template homedir = /home/%U<br />
<br />
# Allow offline/cached credentials and ticket refresh<br />
winbind offline logon = yes<br />
winbind refresh tickets = yes<br />
...</nowiki>}}<br />
<br />
== Joining the Domain ==<br />
<br />
To join the AD domain, simply issue the following command (be sure to replace '''Administrator''' with a user that has privileges to join the AD domain).<br />
<br />
# net ads join -U Administrator<br />
<br />
== Start the Individual Samba Services ==<br />
<br />
Enable and start the {{ic|smb.service}}, {{ic|nmb.service}}, and {{ic|winbind.service}} services.<br />
<br />
== Configure NSS ==<br />
<br />
Modify the {{ic|/etc/nsswitch.conf}} file to allow Samba to map names to uid and gid:<br />
<br />
{{hc|/etc/nsswitch.conf|<nowiki><br />
...<br />
passwd: files winbind mymachines systemd<br />
group: files winbind mymachines systemd<br />
...</nowiki>}}<br />
<br />
=== Testing NSS ===<br />
<br />
Verify connectivity by listing the AD domain users and groups that system is aware of:<br />
<br />
# wbinfo -u<br />
# wbinfo -g<br />
<br />
You should get a list of AD users followed by AD groups.<br />
<br />
== Configuring PAM authentication ==<br />
<br />
Rather than configuring options directly in the ''Linux-PAM'' configuration files, set defaults for the ''pam_winbind'' module in {{ic|/etc/security/pam_winbind.conf}}:<br />
<br />
{{hc|/etc/security/pam_winbind.conf|<nowiki><br />
[Global]<br />
debug = no<br />
debug_state = no<br />
try_first_pass = yes<br />
krb5_auth = yes<br />
krb5_ccache_type = FILE:/run/user/%u/krb5cc<br />
cached_login = yes<br />
silent = no<br />
mkhomedir = yes</nowiki>}}<br />
<br />
For most services, it will be sufficient to modify only the {{ic|/etc/pam.d/system-auth}} file. Any configuration for programs that do not include this file will also need to be modified directly. Create a backup of the {{ic|/etc/pam.d/system-auth}} file and use the following configuration:<br />
<br />
{{hc|/etc/pam.d/system-auth|<nowiki><br />
#%PAM-1.0<br />
<br />
auth sufficient pam_winbind.so<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
account sufficient pam_winbind.so<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
password sufficient pam_winbind.so<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
session required pam_limits.so<br />
session required pam_winbind.so<br />
session required pam_unix.so<br />
session optional pam_permit.so</nowiki>}}<br />
<br />
If you have other services that do not include the {{ic|/etc/pam.d/system-auth}} file, modify the configuration to mirror all ''pam_unix.so'' entries for ''pam_winbind.so'' and change all ''required'' to ''sufficient''. A good example is the su configuration. Create a backup of the {{ic|/etc/pam.d/su}} file and use the following in its place:<br />
<br />
{{hc|/etc/pam.d/su|<nowiki><br />
#%PAM-1.0<br />
<br />
auth sufficient pam_rootok.so<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth required pam_wheeel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth sufficient pam_winbind.so<br />
auth required pam_unix.so<br />
account sufficient pam_winbind.so<br />
account required pam_unix.so<br />
session sufficient pam_winbind.so<br />
session required pam_unix.so</nowiki>}}<br />
<br />
The above pam_winbind configuration will not use the default location of the Kerberos ticket ({{ic|KRB5CCNAME}}), which is at {{ic|/tmp/krb5cc_''UID''}}. Instead, it stores the automatically refreshed Kerberos ticket to {{ic|/run/user/''UID''/krb5cc}}. Append the following to your krb5.conf to let Kerberos know your new location:<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
...<br />
default_ccache_name = /run/user/%{uid}/krb5cc<br />
...</nowiki>}}<br />
<br />
To test your changes, start a '''new''' console or ssh session (do not exit your existing session until you have tested thoroughly) and try to login using the AD credentials. The domain name is optional, as this was set in the Winbind configuration as 'default realm'. Please note that in the case of ssh, you will need to modify the {{ic|/etc/ssh/sshd_config}} file to allow kerberos authentication (see below). <br />
<br />
Run '''klist''' to verify that you have received a kerberos ticket. You should see something similar to:<br />
{{hc|$ klist|<br />
Ticket cache: FILE:/run/user/20000/krb5cc<br />
Default principal: administrator@INTERNAL.DOMAIN.TLD<br />
<br />
Valid starting Expires Service principal<br />
12/25/2020 03:35:21 12/25/2020 13:35:21 krbtgt/INTERNAL.DOMAIN.TLD@INTERNAL.DOMAIN.TLD<br />
renew until 12/26/2020 03:35:15<br />
}}<br />
<br />
Finally, you should test login as both the root user and a local unprivileged user before logging out of your existing (working) session.<br />
<br />
== Old Wiki Article ==<br />
<br />
Active Directory serves as a central location for network administration and security. It is responsible for authenticating and authorizing all users and computers within a Windows domain network, assigning and enforcing security policies for all computers in a network and installing or updating software on network computers. For example, when a user logs into a computer that is part of a Windows domain, it is Active Directory that verifies his or her password and specifies whether they is a system administrator or normal user. Server computers on which Active Directory is running are called domain controllers.<br />
<br />
Active Directory uses [[Wikipedia:Ldap|Lightweight Directory Access Protocol (LDAP)]] versions 2 and 3, Microsoft's version of [[Kerberos]] and DNS.<br />
<br />
=== Terminology ===<br />
<br />
If you are not familiar with Active Directory, there are a few keywords that are helpful to know.<br />
<br />
* '''Domain''' : The name used to group computers and accounts. <br />
* '''SID''' : Each computer that joins the domain as a member must have a unique SID or System Identifier.<br />
* '''SMB''' : Server Message Block.<br />
* '''NETBIOS''': Network naming protocol used as an alternative to DNS. Mostly legacy, but still used in Windows Networking.<br />
* '''WINS''': Windows Information Naming Service. Used for resolving Netbios names to windows hosts.<br />
* '''Winbind''': Protocol for windows authentication.<br />
<br />
=== <s>Active Directory configuration</s> ===<br />
<br />
This section works with the default configuration of Windows Server 2012 R2.<br />
<br />
==== <s>GPO considerations</s> ====<br />
<br />
Digital signing is enabled by default in Windows Server, and must be enabled at both the client and server level. For certain versions of Samba, Linux clients may experience issues connecting to the domain and/or shares. It's recommended you add the following parameters to your {{ic|smb.conf}} file: <br />
<br />
client signing = auto <br />
server signing = auto<br />
<br />
If that is not successful, you can disable ''Digital Sign Communication (Always)'' in the AD group policies. In your AD Group Policy editor, locate:<br />
<br />
Under ''Local policies > Security policies > Microsoft Network Server > Digital sign communication (Always)'' activate ''define this policy'' and use the ''disable'' radio button.<br />
<br />
If you use Windows Server 2008 R2, you need to modify that in ''GPO for Default Domain Controller Policy > Computer Setting > Policies > Windows Setting > Security Setting > Local Policies > Security Option > Microsoft network client: Digitally sign communications (always)''.<br />
<br />
Please note that disabling this GPO affects the security of all members of the domain.<br />
<br />
=== <s>Linux host configuration</s> ===<br />
<br />
The next few steps will begin the process of configuring the Host. You will need root or sudo access to complete these steps.<br />
<br />
==== <s>Installation</s> ====<br />
<br />
[[Install]] the following packages:<br />
* {{Pkg|samba}}, see also [[Samba]]<br />
* {{Pkg|pam-krb5}}<br />
* {{Pkg|ntp}} or {{Pkg|openntpd}}, see also [[NTPd]] or [[OpenNTPD]]<br />
<br />
==== <s>Updating DNS</s> ====<br />
<br />
Active Directory is heavily dependent upon DNS. You will need to update {{ic|/etc/resolv.conf}} to use one or more of the Active Directory domain controllers:<br />
{{hc|/etc/resolv.conf|<br />
nameserver <IP1><br />
nameserver <IP2><br />
}}<br />
Replacing <IP1> and <IP2> with valid IP addresses for the AD servers. If your AD domains do not permit DNS forwarding or recursion, you may need to add additional resolvers. <br />
<br />
{{Note|If your machine dual boots Windows and Linux, you should use a different DNS hostname and netbios name for the linux configuration if both operating systems will be members of the same domain.}}<br />
<br />
==== <s>Configuring NTP</s> ====<br />
<br />
Read [[System time#Time synchronization]] to configure an NTP service.<br />
<br />
On the NTP servers configuration, use the IP addresses for the AD servers, as they typically run NTP as a service. Alternatively, you can use other known NTP servers provided the Active directory servers sync to the same stratum.<br />
<br />
Ensure that the service is configured to sync the time automatically very early on startup.<br />
<br />
==== <s>Kerberos</s> ====<br />
<br />
Let us assume that your AD is named example.com. Let us further assume your AD is ruled by two domain controllers, the primary and secondary one, which are named PDC and BDC, pdc.example.com and bdc.example.com respectively. Their IP adresses will be 192.168.1.2 and 192.168.1.3 in this example. Take care to watch your syntax; upper-case is very important here.<br />
<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
default_realm = EXAMPLE.COM<br />
clockskew = 300<br />
ticket_lifetime = 1d<br />
forwardable = true<br />
proxiable = true<br />
dns_lookup_realm = true<br />
dns_lookup_kdc = true<br />
<br />
[realms]<br />
EXAMPLE.COM = {<br />
kdc = PDC.EXAMPLE.COM<br />
admin_server = PDC.EXAMPLE.COM<br />
default_domain = EXAMPLE.COM<br />
}<br />
<br />
[domain_realm]<br />
.kerberos.server = EXAMPLE.COM<br />
.example.com = EXAMPLE.COM<br />
example.com = EXAMPLE.COM<br />
example = EXAMPLE.COM<br />
<br />
[appdefaults]<br />
pam = {<br />
ticket_lifetime = 1d<br />
renew_lifetime = 1d<br />
forwardable = true<br />
proxiable = false<br />
retain_after_close = false<br />
minimum_uid = 0<br />
debug = false<br />
}<br />
<br />
[logging]<br />
default = FILE:/var/log/krb5libs.log<br />
kdc = FILE:/var/log/kdc.log<br />
admin_server = FILE:/var/log/kadmind.log<br />
</nowiki>}}<br />
<br />
{{Note|Heimdal 1.3.1 deprecated DES encryption which is required for AD authentication before Windows Server 2008. You will probably have to add {{bc|1=allow_weak_crypto = true}} to the {{Ic|[libdefaults]}} section.}}<br />
<br />
===== <s>Creating a Kerberos ticket</s> =====<br />
<br />
{{note|The keys and commands are user specific: sudo will be root, so your non-elevated account can connect to a different AD user with a separate key. If you only have one domain, it is not necessary to type @EXAMPLE.COM}}<br />
<br />
Now you can query the AD domain controllers and request a kerberos ticket ('''uppercase is necessary'''):<br />
{{bc|kinit administrator@EXAMPLE.COM}}<br />
<br />
You can use any username that has rights as a Domain Administrator.<br />
<br />
===== <s>Validating the Ticket</s> =====<br />
<br />
Run '''klist''' to verify you did receive the token. You should see something similar to:<br />
{{hc|# klist|<br />
Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: administrator@EXAMPLE.COM<br />
<br />
Valid starting Expires Service principal <br />
02/04/12 21:27:47 02/05/12 07:27:42 krbtgt/EXAMPLE.COM@EXAMPLE.COM<br />
renew until 02/05/12 21:27:47<br />
}}<br />
<br />
==== <s>pam_winbind.conf</s> ====<br />
<br />
If you get errors stating that /etc/security/pam_winbind.conf was not found, create the file and add the following:<br />
<br />
{{hc|/etc/security/pam_winbind.conf|<nowiki><br />
[global]<br />
debug = no<br />
debug_state = no<br />
try_first_pass = yes<br />
krb5_auth = yes<br />
krb5_ccache_type = FILE<br />
cached_login = yes<br />
silent = no<br />
mkhomedir = yes<br />
</nowiki>}}<br />
<br />
With this setup, winbind will create user keytabs on the fly (krb5_ccache_type = FILE) at login and maintain them. You can verify this by simply running klist in a shell after logging in as an AD user but without needing to run kinit. You may need to set additional permissions on /etc/krb5.keytab eg 640 instead of 600 to get this to work (see {{Bug|52621}} for example)<br />
<br />
==== <s>Samba</s> ====<br />
<br />
Samba is a free software re-implementation of the SMB/CIFS networking protocol. It also includes tools for Linux machines to act as Windows networking servers and clients.<br />
<br />
{{Note|The configuration can vary greatly depending on how the Windows environment is deployed. Be prepared to troubleshoot and research}}<br />
<br />
In this section, we will focus on getting Authentication to work first by editing the 'Global' section first. Later, we will go back and add shares.<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
netbios name = MYARCHLINUX<br />
workgroup = EXAMPLE<br />
realm = EXAMPLE.COM<br />
server string = %h ArchLinux Host<br />
security = ads<br />
encrypt passwords = yes<br />
password server = pdc.example.com<br />
client signing = auto<br />
server signing = auto<br />
<br />
idmap config * : backend = tdb<br />
idmap config * : range = 10000-20000<br />
<br />
winbind use default domain = Yes<br />
winbind enum users = Yes<br />
winbind enum groups = Yes<br />
winbind nested groups = Yes<br />
winbind separator = +<br />
winbind refresh tickets = yes<br />
winbind offline logon = yes<br />
winbind cache time = 300<br />
<br />
template shell = /bin/bash<br />
template homedir = /home/%D/%U<br />
<br />
preferred master = no<br />
dns proxy = no<br />
wins server = pdc.example.com<br />
wins proxy = no<br />
<br />
inherit acls = Yes<br />
map acl inherit = Yes<br />
acl group control = yes<br />
<br />
load printers = no<br />
debug level = 3<br />
use sendfile = no<br />
</nowiki>}}<br />
<br />
==== <s>Join the domain</s> ====<br />
<br />
You need an AD Administrator account to do this. Let us assume this is named Administrator. The command is 'net ads join'<br />
{{hc|# net ads join -U Administrator|<br />
Administrator's password: xxx<br />
Using short domain name -- EXAMPLE<br />
Joined 'MYARCHLINUX' to realm 'EXAMPLE.COM'<br />
}}<br />
<br />
=== <s>Starting and testing services</s> ===<br />
<br />
==== <s>Starting Samba</s> ====<br />
<br />
Hopefully, you have not rebooted yet! Fine. If you are in an X-session, quit it, so you can test login into another console, while you are still logged in.<br />
<br />
Enable and start the individual Samba daemons {{ic|smbd.service}}, {{ic|nmbd.service}}, and {{ic|winbindd.service}}.<br />
<br />
{{Note|In {{Pkg|samba}} 4.8.0-1, the Samba daemon units have been renamed from {{ic|smbd.service}}, {{ic|nmbd.service}}, and {{ic|winbindd.service}} to {{ic|smb.service}}, {{ic|nmb.service}}, and {{ic|winbind.service}}.}}<br />
<br />
Next we will need to modify the NSSwitch configuration, which tells the Linux host how to retrieve information from various sources and in which order to do so. In this case, we are appending Active Directory as additional sources for Users, Groups, and Hosts.<br />
<br />
{{hc|/etc/nsswitch.conf|<br />
passwd: files winbind<br />
shadow: files winbind<br />
group: files winbind <br />
<br />
hosts: files dns wins<br />
}}<br />
<br />
==== <s>Testing Winbind</s> ====<br />
<br />
Let us check if winbind is able to query the AD. The following command should return a list of AD users:<br />
<br />
{{hc|# wbinfo -u|<br />
administrator<br />
guest<br />
krbtgt<br />
test.user<br />
}}<br />
* Note we created an Active Directory user called 'test.user' on the domain controller<br />
<br />
We can do the same for AD groups:<br />
<br />
{{hc|# wbinfo -g|<br />
domain computers<br />
domain controllers<br />
schema admins<br />
enterprise admins<br />
cert publishers<br />
domain admins<br />
domain users<br />
domain guests<br />
group policy creator owners<br />
ras and ias servers<br />
allowed rodc password replication group<br />
denied rodc password replication group<br />
read-only domain controllers<br />
enterprise read-only domain controllers<br />
dnsadmins<br />
dnsupdateproxy<br />
}}<br />
<br />
==== <s>Testing nsswitch</s> ====<br />
<br />
To ensure that our host is able to query the domain for users and groups, we test nsswitch settings by issuing the 'getent' command.<br />
<br />
The following output shows what a stock ArchLinux install looks like:<br />
<br />
{{hc|# getent passwd|<br />
root:x:0:0:root:/root:/bin/bash<br />
bin:x:1:1:bin:/bin:/bin/false<br />
daemon:x:2:2:daemon:/sbin:/bin/false<br />
mail:x:8:12:mail:/var/spool/mail:/bin/false<br />
ftp:x:14:11:ftp:/srv/ftp:/bin/false<br />
http:x:33:33:http:/srv/http:/bin/false<br />
nobody:x:99:99:nobody:/:/bin/false<br />
dbus:x:81:81:System message bus:/:/bin/false<br />
ntp:x:87:87:Network Time Protocol:/var/empty:/bin/false<br />
avahi:x:84:84:avahi:/:/bin/false<br />
administrator:*:10001:10006:Administrator:/home/EXAMPLE/administrator:/bin/bash<br />
guest:*:10002:10007:Guest:/home/EXAMPLE/guest:/bin/bash<br />
krbtgt:*:10003:10006:krbtgt:/home/EXAMPLE/krbtgt:/bin/bash<br />
test.user:*:10000:10006:Test User:/home/EXAMPLE/test.user:/bin/bash<br />
}}<br />
<br />
And for groups:<br />
{{hc|# getent group|<br />
root:x:0:root<br />
bin:x:1:root,bin,daemon<br />
daemon:x:2:root,bin,daemon<br />
sys:x:3:root,bin<br />
adm:x:4:root,daemon<br />
tty:x:5:<br />
disk:x:6:root<br />
lp:x:7:daemon<br />
mem:x:8:<br />
kmem:x:9:<br />
wheel:x:10:root<br />
ftp:x:11:<br />
mail:x:12:<br />
uucp:x:14:<br />
log:x:19:root<br />
utmp:x:20:<br />
locate:x:21:<br />
rfkill:x:24:<br />
smmsp:x:25:<br />
http:x:33:<br />
games:x:50:<br />
network:x:90:<br />
video:x:91:<br />
audio:x:92:<br />
optical:x:93:<br />
floppy:x:94:<br />
storage:x:95:<br />
scanner:x:96:<br />
power:x:98:<br />
nobody:x:99:<br />
users:x:100:<br />
dbus:x:81:<br />
ntp:x:87:<br />
avahi:x:84:<br />
domain computers:x:10008:<br />
domain controllers:x:10009:<br />
schema admins:x:10010:administrator<br />
enterprise admins:x:10011:administrator<br />
cert publishers:x:10012:<br />
domain admins:x:10013:test.user,administrator<br />
domain users:x:10006:<br />
domain guests:x:10007:<br />
group policy creator owners:x:10014:administrator<br />
ras and ias servers:x:10015:<br />
allowed rodc password replication group:x:10016:<br />
denied rodc password replication group:x:10017:krbtgt<br />
read-only domain controllers:x:10018:<br />
enterprise read-only domain controllers:x:10019:<br />
dnsadmins:x:10020:<br />
dnsupdateproxy:x:10021:<br />
}}<br />
<br />
==== Testing Samba commands ====<br />
<br />
Try out some net commands to see if Samba can communicate with AD:<br />
<br />
{{hc|# net ads info|<nowiki><br />
[2012/02/05 20:21:36.473559, 0] param/loadparm.c:7599(lp_do_parameter)<br />
Ignoring unknown parameter "idmapd backend"<br />
LDAP server: 192.168.1.2<br />
LDAP server name: PDC.example.com<br />
Realm: EXAMPLE.COM<br />
Bind Path: dc=EXAMPLE,dc=COM<br />
LDAP port: 389<br />
Server time: Sun, 05 Feb 2012 20:21:33 CST<br />
KDC server: 192.168.1.2<br />
Server time offset: -3<br />
</nowiki>}}<br />
<br />
{{hc|# net ads lookup|<br />
[2012/02/05 20:22:39.298823, 0] param/loadparm.c:7599(lp_do_parameter)<br />
Ignoring unknown parameter "idmapd backend"<br />
Information for Domain Controller: 192.168.1.2<br />
<br />
Response Type: LOGON_SAM_LOGON_RESPONSE_EX<br />
GUID: 2a098512-4c9f-4fe4-ac22-8f9231fabbad<br />
Flags:<br />
Is a PDC: yes<br />
Is a GC of the forest: yes<br />
Is an LDAP server: yes<br />
Supports DS: yes<br />
Is running a KDC: yes<br />
Is running time services: yes<br />
Is the closest DC: yes<br />
Is writable: yes<br />
Has a hardware clock: yes<br />
Is a non-domain NC serviced by LDAP server: no<br />
Is NT6 DC that has some secrets: no<br />
Is NT6 DC that has all secrets: yes<br />
Forest: example.com<br />
Domain: example.com<br />
Domain Controller: PDC.example.com<br />
Pre-Win2k Domain: EXAMPLE<br />
Pre-Win2k Hostname: PDC<br />
Server Site Name : Office<br />
Client Site Name : Office<br />
NT Version: 5<br />
LMNT Token: ffff<br />
LM20 Token: ffff<br />
}}<br />
<br />
{{hc|<nowiki># net ads status -U administrator%password | less</nowiki>|<nowiki><br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: user<br />
objectClass: computer<br />
cn: myarchlinux<br />
distinguishedName: CN=myarchlinux,CN=Computers,DC=leafscale,DC=inc<br />
instanceType: 4<br />
whenCreated: 20120206043413.0Z<br />
whenChanged: 20120206043414.0Z<br />
uSNCreated: 16556<br />
uSNChanged: 16563<br />
name: myarchlinux<br />
objectGUID: 2c24029c-8422-42b2-83b3-a255b9cb41b3<br />
userAccountControl: 69632<br />
badPwdCount: 0<br />
codePage: 0<br />
countryCode: 0<br />
badPasswordTime: 0<br />
lastLogoff: 0<br />
lastLogon: 129729780312632000<br />
localPolicyFlags: 0<br />
pwdLastSet: 129729764538848000<br />
primaryGroupID: 515<br />
objectSid: S-1-5-21-719106045-3766251393-3909931865-1105<br />
...<snip>...<br />
</nowiki>}}<br />
<br />
=== <s>Configuring PAM</s> ===<br />
<br />
Now we will change various rules in PAM to allow Active Directory users to use the system for things like login and sudo access. When changing the rules, note the order of these items and whether they are marked as '''required''' or '''sufficient''' is critical to things working as expected. You should not deviate from these rules unless you know how to write PAM rules.<br />
<br />
In case of logins, PAM should first ask for AD accounts, and for local accounts if no matching AD account was found. Therefore, we add entries to include {{ic|pam_winbind.so}} into the authentication process.<br />
<br />
The Arch Linux PAM configuration keeps the central auth process in {{ic|/etc/pam.d/system-auth}}. Starting with the stock configuration from {{ic|pambase}}, change it like this:<br />
<br />
==== <s>system-auth</s> ====<br />
<br />
===== <s>"auth" section</s> =====<br />
<br />
Find the line:<br />
<br />
auth required pam_unix.so ...<br />
<br />
Delete it, and replace with:<br />
<br />
auth [success=1 default=ignore] pam_localuser.so<br />
auth [success=2 default=die] pam_winbind.so<br />
auth [success=1 default=die] pam_unix.so nullok<br />
auth requisite pam_deny.so<br />
<br />
===== <s>"account" section</s> =====<br />
<br />
Find the line:<br />
<br />
account required pam_unix.so<br />
<br />
Keep it, and add this below:<br />
<br />
account [success=1 default=ignore] pam_localuser.so<br />
account required pam_winbind.so<br />
<br />
===== <s>"password" section</s> =====<br />
<br />
Find the line:<br />
<br />
password required pam_unix.so ...<br />
<br />
Delete it, and replace with:<br />
<br />
password [success=1 default=ignore] pam_localuser.so<br />
password [success=2 default=die] pam_winbind.so<br />
password [success=1 default=die] pam_unix.so sha512 shadow<br />
password requisite pam_deny.so<br />
<br />
===== <s>"session" section</s> =====<br />
<br />
Find the line:<br />
<br />
session required pam_unix.so<br />
<br />
Keep it, and add this line immediately above it:<br />
<br />
session required pam_mkhomedir.so skel=/etc/skel/ umask=0022<br />
<br />
Below the pam_unix line, add these:<br />
<br />
session [success=1 default=ignore] pam_localuser.so<br />
session required pam_winbind.so<br />
<br />
==== <s>passwd</s> ====<br />
<br />
===== <s>"password" section</s> =====<br />
<br />
In order for logged-in Active Directory users to be able to change their passwords with the 'passwd' command, the file {{ic|/etc/pam.d/passwd}} must include the information from system-auth.<br />
<br />
Find the line:<br />
<br />
password required pam_unix.so sha512 shadow nullok<br />
<br />
Delete it, and replace with:<br />
<br />
password include system-auth<br />
<br />
==== <s>Testing login</s> ====<br />
<br />
Now, start a new console session (or ssh) and try to login using the AD credentials. The domain name is optional, as this was set in the Winbind configuration as 'default realm'. Please note that in the case of ssh, you will need to modify the {{ic|/etc/ssh/sshd_config}} file to allow kerberos authentication {{ic|(KerberosAuthentication yes)}}.<br />
<br />
{{bc|<br />
test.user<br />
EXAMPLE+test.user<br />
}}<br />
<br />
Both should work. You should notice that {{ic|/home/example/test.user}} will be automatically created.<br />
'''Log into another session using an linux account. Check that you still be able to log in as root - but keep in mind to be logged in as root in at least one session!'''<br />
<br />
=== Configuring Shares ===<br />
<br />
Earlier we skipped configuration of the shares. Now that things are working, go back to {{ic|/etc/samba/smb.conf}}, and add the exports for the host that you want available on the windows network. <br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[MyShare]<br />
comment = Example Share<br />
path = /srv/exports/myshare<br />
read only = no<br />
browseable = yes<br />
valid users = @NETWORK+"Domain Admins" NETWORK+test.user<br />
</nowiki>}}<br />
<br />
In the above example, the keyword '''NETWORK''' is to be used. Do not mistakenly substitute this with your domain name. For adding groups, prepend the '@' symbol to the group. Note that {{ic|Domain Admins}} is encapsulated in quotes so Samba correctly parses it when reading the configuration file.<br />
<br />
=== Adding a machine keytab file and activating password-free kerberized ssh to the machine ===<br />
<br />
This explains how to generate a machine keytab file which you will need e.g. to enable password-free kerberized ssh to your machine from other machines in the domain. The scenario in mind is that you have a bunch of systems in your domain and you just added a server/workstation using the above description to your domain onto which a lot of users need to ssh in order to work - e.g. GPU workstation or an OpenMP compute node, etc. In this case you might not want to type your password every time you log in. On the other hand the key authentication used by many users in this case can not give you the necessary credentials to e.g. mount kerberized NFSv4 shares. So this will help you to enable password-free logins from your clients to the machine in question using kerberos ticket forwarding.<br />
<br />
==== <s>Creating a machine key tab file</s> ====<br />
<br />
run 'net ads keytab create -U administrator' as root to create a machine keytab file in /etc/krb5.keytab. It will prompt you with a warning that we need to enable keytab authentication in our configuration file, so we will do that in the next step. In my case it had problems when a key tab file is already in place - the command just did not come back it hang ... In that case you should rename the existing /etc/krb5.keytab and run the command again - it should work now.<br />
<br />
{{bc|# net ads keytab create -U administrator}}<br />
<br />
verify the content of your keytab by running:<br />
<br />
{{hc|# klist -k /etc/krb5.keytab|<nowiki><br />
Keytab name: FILE:/etc/krb5.keytab<br />
KVNO Principal<br />
---- --------------------------------------------------------------------------<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
</nowiki>}}<br />
<br />
==== <s>Enabling keytab authentication</s> ====<br />
<br />
Now you need to tell winbind to use the file by adding these lines to the /etc/samba/smb.conf:<br />
<br />
kerberos method = secrets and keytab<br />
dedicated keytab file = /etc/krb5.keytab<br />
<br />
It should look something like this:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
netbios name = MYARCHLINUX<br />
workgroup = EXAMPLE<br />
realm = EXAMPLE.COM<br />
server string = %h ArchLinux Host<br />
security = ads<br />
encrypt passwords = yes<br />
password server = pdc.example.com<br />
kerberos method = secrets and keytab<br />
dedicated keytab file = /etc/krb5.keytab<br />
<br />
idmap config * : backend = tdb<br />
idmap config * : range = 10000-20000<br />
<br />
winbind use default domain = Yes<br />
winbind enum users = Yes<br />
winbind enum groups = Yes<br />
winbind nested groups = Yes<br />
winbind separator = +<br />
winbind refresh tickets = yes<br />
<br />
template shell = /bin/bash<br />
template homedir = /home/%D/%U<br />
<br />
preferred master = no<br />
dns proxy = no<br />
wins server = pdc.example.com<br />
wins proxy = no<br />
<br />
inherit acls = Yes<br />
map acl inherit = Yes<br />
acl group control = yes<br />
<br />
load printers = no<br />
debug level = 3<br />
use sendfile = no<br />
</nowiki>}}<br />
<br />
Restart the winbind daemon using 'systemctl restart winbindd.service' with root privileges.<br />
<br />
{{bc|# systemctl restart winbindd.service}}<br />
<br />
Check if everything works by getting a machine ticket for your system by running <br />
<br />
{{bc|# kinit MYARCHLINUX$ -kt /etc/krb5.keytab}}<br />
<br />
This should not give you any feedback but running 'klist' should show you sth like:<br />
<br />
{{hc|# klist|<br />
Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: MYARCHLINUX$@EXAMPLE.COM<br />
<br />
Valid starting Expires Service principal <br />
02/04/12 21:27:47 02/05/12 07:27:42 krbtgt/EXAMPLE.COM@EXAMPLE.COM<br />
renew until 02/05/12 21:27:47<br />
}}<br />
<br />
Some common mistakes here are a) forgetting the trailing $ or b) ignoring case sensitivity - it needs to look exactly like the entry in the keytab (usually you cannot to much wrong with all capital)<br />
<br />
==== Preparing sshd on server ====<br />
<br />
All we need to do is add some options to our sshd_config and restart the sshd.service.<br />
<br />
Edit /etc/ssh/sshd_config to look like this in the appropriate places:<br />
<br />
{{hc|# /etc/ssh/sshd_config|<br />
<br />
...<br />
<br />
# Change to no to disable s/key passwords<br />
ChallengeResponseAuthentication no<br />
<br />
# Kerberos options<br />
KerberosAuthentication yes<br />
#KerberosOrLocalPasswd yes<br />
KerberosTicketCleanup yes<br />
KerberosGetAFSToken yes<br />
<br />
# GSSAPI options<br />
GSSAPIAuthentication yes<br />
GSSAPICleanupCredentials yes<br />
<br />
...<br />
<br />
}}<br />
<br />
Restart the sshd.service using:<br />
<br />
{{bc|# systemctl restart sshd.service}}<br />
<br />
==== Adding necessary options on client ====<br />
<br />
First we need to make sure that the tickets on our client are forwardable. This is usually standard but we better check anyways. You have to look for the forwardable option and set it to 'true' in the Kerberos config file /etc/krb5.conf<br />
<br />
{{bc|<nowiki>forwardable = true</nowiki>}}<br />
<br />
Secondly we need to add the options <br />
<br />
GSSAPIAuthentication yes<br />
GSSAPIDelegateCredentials yes<br />
<br />
to our .ssh/config file to tell ssh to use this options - alternatively they can be invoked using the -o options directly in the ssh command (see 'man ssh' for help).<br />
<br />
==== Testing the setup ====<br />
<br />
On Client:<br />
<br />
make sure you have a valid ticket - if in doubt run 'kinit'<br />
<br />
then use ssh to connect to you machine<br />
<br />
{{bc|ssh myarchlinux.example.com }}<br />
<br />
you should get connected without needing to enter your password.<br />
<br />
if you have key authentication additionally activated then you should perform<br />
<br />
{{bc|ssh -v myarchlinux.example.com }}<br />
<br />
to see which authentication method it actually uses.<br />
<br />
For debugging you can enable DEBUG3 on the server and look into the journal using [[journalctl]].<br />
<br />
==== Nifty fine-tuning for complete password-free kerberos handling. ====<br />
<br />
In case your clients are not using domain accounts on their local machines (for whatever reason) it can be hard to actually teach them to kinit before ssh to the workstation. Therefore I came up with a nice workaround:<br />
<br />
=== Generating user Keytabs which are accepted by AD ===<br />
<br />
On a system let the user run:<br />
<br />
{{bc|<nowiki><br />
ktutil<br />
addent -password -p username@EXAMPLE.COM -k 1 -e RC4-HMAC<br />
- enter password for username -<br />
wkt username.keytab<br />
q<br />
</nowiki>}}<br />
<br />
Now test the file by invoking:<br />
<br />
{{bc|kinit username@EXAMPLE.COM -kt username.keytab}}<br />
<br />
It should not promt you to give your password nor should it give any other feedback. If it worked you are basically done - just put the line above into your ~./bashrc - you can now get kerberos tickets without typing a password and with that you can connect to your workstation without typing a password while being completely kerberized and able to authenticate against NFSv4 and CIFS via tickets - pretty neat.<br />
<br />
==== Nice to know ====<br />
<br />
The file 'username.keytab' is not machinespecific and can therefore be copied around. E.g. we created the files on a linux machine and copied them to our Mac clients as the commands on Macs are different ...<br />
<br />
=== See also ===<br />
<br />
* [[wikipedia:Active_Directory|Wikipedia - Active Directory]]<br />
* [[wikipedia:Samba_(software)|Wikipedia - Samba]]<br />
* [[wikipedia:Kerberos_(protocol)|Wikipedia - Kerberos]]<br />
* [https://www.samba.org/samba/docs Samba - Documentation]<br />
* [https://wiki.samba.org/index.php/Samba,_Active_Directory_&_LDAP Samba Wiki - Samba, Active Directory & LDAP]<br />
* {{man|5|smb.conf}}<br />
<br />
==== Using SSSD ====<br />
<br />
{{pkg|sssd}} can be used instead of Samba to integrate with AD. See [https://sssd.io/docs/ad/ad-introduction.html SSSD documentation].<br />
<br />
==== Commercial Solutions ====<br />
<br />
* Centrify<br />
* Likewise<br />
<br />
==== OpenSource version ====<br />
<br />
* [https://github.com/BeyondTrust/pbis-open/ PowerBroker Identity Services Open]: formerly Likewise acquired by BeyondTrust<br />
* [https://www.centrify.com/express/linux/ Centrify Express for Linux]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Samba&diff=694460Samba2021-09-05T16:55:59Z<p>Pgoetz: Clarified that adding local Samba users is just one way to handle authentication with Samba</p>
<hr />
<div>[[Category:Network sharing]]<br />
[[Category:Servers]]<br />
[[de:Samba]]<br />
[[fr:Samba]]<br />
[[it:Samba]]<br />
[[ja:Samba]]<br />
[[ru:Samba]]<br />
[[zh-hans:Samba]]<br />
[[zh-hant:Samba]]<br />
{{Related articles start}}<br />
{{Related|Active Directory Integration}}<br />
{{Related|Samba/Active Directory domain controller}}<br />
{{Related|NFS}}<br />
{{Related articles end}}<br />
[https://www.samba.org/ Samba] is the standard Windows interoperability suite of programs for Linux and Unix. Since 1992, Samba has provided secure, stable and fast file and print services for all clients using the [[wikipedia:Server_Message_Block|SMB/CIFS]] protocol, such as all versions of DOS and Windows, OS/2, Linux and many others.<br />
<br />
To share files through Samba, see [[#Server]] section; to access files shared through Samba on other machines, please see [[#Client]] section.<br />
<br />
== Server ==<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{Pkg|samba}} package.<br />
<br />
Samba is configured in the {{ic|/etc/samba/smb.conf}} configuration file, which is extensively documented in {{man|5|smb.conf}}.<br />
<br />
Because the {{Pkg|samba}} package does not provide this file, one needs to create it '''before''' starting {{ic|smb.service}}.<br />
<br />
A documented example as in {{ic|smb.conf.default}} from the [https://git.samba.org/samba.git/?p=samba.git;a=blob_plain;f=examples/smb.conf.default;hb=HEAD Samba git repository] may be used to setup {{ic|/etc/samba/smb.conf}}. <br />
<br />
{{Note|<br />
* The default configuration sets {{ic|log file}} to a non-writable location, which will cause errors - apply one of the following workarounds:<br />
** Change the log file location to a writable path: {{ic|1=log file = /var/log/samba/%m.log}}<br />
** Change logging to a non-file backend solution: {{ic|1=logging = syslog}} with {{ic|1=syslog only = yes}}, or use {{ic|1=logging = systemd}}<br />
* If required; the {{ic|workgroup}} specified in the {{ic|[global]}} section has to match the Windows workgroup (default {{ic|WORKGROUP}}).<br />
}}<br />
<br />
{{Tip|Whenever you modify the {{ic|smb.conf}} file, run the {{man|1|testparm}} command to check for syntactic errors.}}<br />
<br />
==== Enabling and starting services ====<br />
<br />
To provide basic file sharing through SMB, [[enable/start]] {{ic|smb.service}} and {{ic|nmb.service}}. See {{man|8|smbd}} and {{man|8|nmbd}} for details.<br />
<br />
{{Note|{{ic|nmb.service}} is not required. However, it is needed to access Samba servers by hostname (e.g. {{ic|smb://hostname/}}).}}<br />
<br />
==== Configure firewall ====<br />
<br />
If you are using a [[firewall]], do not forget to open required ports (usually 137-139 + 445). For a complete list, see [https://www.samba.org/~tpot/articles/firewall.html Samba port usage].<br />
<br />
===== UFW Rule =====<br />
<br />
A [[Ufw]] App Profile for SMB/CIFS is included by default with the default installation of UFW in {{ic|ufw-fileserver}}.<br />
<br />
Allow Samba by running {{ic|ufw allow CIFS}} as root.<br />
<br />
If you deleted the profile, create/edit {{ic|/etc/ufw/applications.d/samba}} and add the following content:<br />
<br />
[Samba]<br />
title=LanManager-like file and printer server for Unix<br />
description=The Samba software suite is a collection of programs that implements the SMB/CIFS protocol for unix systems, allowing you to serve files and printers to Windows, NT, OS/2 and DOS clients. This protocol is sometimes also referred to as the LanManager or NetBIOS protocol.<br />
ports=137,138/udp|139,445/tcp<br />
<br />
Then load the profile into UFW run {{ic|ufw app update Samba}} as root.<br />
<br />
Then finally, allow Samba by running {{ic|ufw allow Samba}} as root.<br />
<br />
===== firewalld service =====<br />
<br />
To configure [[firewalld]] to allow Samba in the '''home''' zone, run:<br />
<br />
# firewall-cmd --permanent --add-service={samba,samba-client,samba-dc} --zone=home<br />
<br />
The three service listed are:<br />
<br />
* {{ic|samba}}: for sharing files with others.<br />
* {{ic|samba-client}}: to browse shares on other machines on the network.<br />
* {{ic|samba-dc}}: for [[Samba/Active Directory domain controller]].<br />
<br />
{{ic|--permanent}} ensures the changes remain after {{ic|firewalld.service}} is [[restart]]ed.<br />
<br />
=== Usage ===<br />
<br />
==== User management ====<br />
<br />
The following section describes creating a local (tdbsam) database of Samba users. For user authentication and other purposes, Samba can also be bound to an Active Directory domain, can itself serve as an Active Directory domain controller, or can be used with an LDAP server.<br />
<br />
===== Adding a user =====<br />
<br />
Samba requires a Linux user account - you may use an existing user account or create a [[Users and groups#User management|new one]].<br />
<br />
{{Note|The [[user]]/[[user group]] ''nobody'' should already exist on the system, it's used as the default {{ic|guest account}} and may be used for shares containing {{ic|1=guest ok = yes}}, thus preventing the need of user login on that share.}}<br />
<br />
Although the user name is shared with Linux system, Samba uses a password separate from that of the Linux user accounts. Replace {{ic|samba_user}} with the chosen Samba user account:<br />
<br />
# smbpasswd -a ''samba_user''<br />
<br />
Depending on the [https://www.samba.org/samba/docs/man/manpages-3/smb.conf.5.html#SERVERROLE server role], existing [[File permissions and attributes]] may need to be altered for the Samba user account.<br />
<br />
If you want the new user only to be allowed to remotely access the file server shares through Samba, you can restrict other login options:<br />
<br />
* disabling shell - {{ic|usermod --shell /usr/bin/nologin --lock ''samba_user''}}<br />
* disabling SSH logons - edit {{ic|/etc/ssh/sshd_config}}, change option {{ic|AllowUsers}}<br />
<br />
Also see [[Security]] for hardening your system.<br />
<br />
===== Listing users =====<br />
<br />
Samba users can be listed using the {{man|8|pdbedit}} command:<br />
<br />
# pdbedit -L -v<br />
<br />
===== Changing user password =====<br />
<br />
To change a user password, use {{ic|smbpasswd}}:<br />
<br />
# smbpasswd ''samba_user''<br />
<br />
==== Creating an anonymous share ====<br />
<br />
1. Create a Linux user which anonymous Samba users will be mapped to.<br />
<br />
# useradd guest -s /bin/nologin<br />
<br />
{{Note|The username can be any valid Linux username, not just "guest". This user does not need to be a Samba user.}}<br />
<br />
2. Add the following to {{ic|/etc/samba/smb.conf}}:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
[global]<br />
security = user<br />
map to guest = bad user<br />
guest account = guest<br />
<br />
[guest]<br />
comment = guest<br />
path = /tmp/<br />
public = yes<br />
only guest = yes<br />
writable = yes<br />
printable = no<br />
}}<br />
<br />
Any anonymous users will now be mapped to the Linux user {{ic|guest}} and have the ability to access any directories defined in {{ic|guest.path}}, for example, {{ic|/tmp/}} in the configuration above.<br />
<br />
Make sure shares have been properly defined as per the ''Share Definitions'' section of [https://git.samba.org/samba.git/?p=samba.git;a=blob_plain;f=examples/smb.conf.default;hb=HEAD smb.conf.default].<br />
<br />
=== Enable symlink following ===<br />
<br />
{{Warning|Enabling the {{ic|follow symlinks}} option can be a security risk.}}<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
[global]<br />
follow symlinks = yes<br />
wide links = yes<br />
unix extensions = no<br />
}}<br />
<br />
Then, [[restart]] {{ic|smb.service}}.<br />
<br />
{{Note|When using [[AppArmor]], if the symlink points to a directory outside the user's home or the [[#Enable Usershares|usershare]] directory, then you need to [[#Permission issues on AppArmor|modify the AppArmor profile permissions]].}}<br />
<br />
=== Advanced Configuration ===<br />
<br />
==== Enable Usershares ====<br />
<br />
{{Note|This is an optional feature. Skip this section if you do not need it.}}<br />
<br />
[https://www.samba.org/samba/docs/current/man-html/smb.conf.5.html Usershares]<br />
is a feature that gives non-root users the capability to add, modify, and delete their own share definitions. <br />
<br />
# Create a directory for usershares: {{bc|# mkdir /var/lib/samba/usershares}}<br />
# Create a [[user group]]: {{bc|# groupadd -r sambashare}}<br />
# Change the owner of the directory to {{ic|root}} and the group to {{ic|sambashare}}: {{bc|# chown root:sambashare /var/lib/samba/usershares}}<br />
# Change the permissions of the {{ic|usershares}} directory so that users in the group {{ic|sambashare}} can read, write and execute files: {{bc|# chmod 1770 /var/lib/samba/usershares}}<br />
<br />
Set the following parameters in the {{ic|smb.conf}} configuration file: <br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
usershare path = /var/lib/samba/usershares<br />
usershare max shares = 100<br />
usershare allow guests = yes<br />
usershare owner only = yes<br />
}}<br />
<br />
Add the user to the ''sambashare'' group. Replace {{ic|''your_username''}} with the name of your user:<br />
<br />
# gpasswd sambashare -a ''your_username''<br />
<br />
[[Restart]] {{ic|smb.service}} and {{ic|nmb.service}} services.<br />
<br />
Log out and log back in.<br />
<br />
If you want to share paths inside your home directory you must make it accessible for the group ''others''.<br />
<br />
In the GUI, for example in [[Thunar]], you can right click on any directory and share it on the network. <br />
<br />
In the CLI, use one of the following commands, replacing italic ''sharename'', ''user'', ... :<br />
<br />
# net usershare add ''sharename'' ''abspath'' [''comment''] [''user'':{R|D|F}] [guest_ok={y|n}]<br />
# net usershare delete ''sharename''<br />
# net usershare list ''wildcard-sharename''<br />
# net usershare info ''wildcard-sharename''<br />
<br />
==== Set and forcing permissions ====<br />
<br />
Permissions may be applied to both the server and shares:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
;inherit owner = unix only ; Inherit ownership of the parent directory for new files and directories<br />
;inherit permissions = yes ; Inherit permissions of the parent directory for new files and directories<br />
create mask = 0664<br />
directory mask = 2755<br />
force create mode = 0644<br />
force directory mode = 2755<br />
...<br />
<br />
[media]<br />
comment = Media share accessible by ''greg'' and ''pcusers''<br />
path = ''/path/to/media''<br />
valid users = ''greg @pcusers''<br />
force group = ''+pcusers''<br />
public = no<br />
writable = yes<br />
create mask = 0664<br />
directory mask = 2775<br />
force create mode = 0664<br />
force directory mode = 2775<br />
<br />
[public]<br />
comment = Public share where ''archie'' has write access<br />
path = ''/path/to/public''<br />
public = yes<br />
read only = yes<br />
write list = ''archie''<br />
printable = no<br />
<br />
[guests]<br />
comment = Allow all users to read/write<br />
path = ''/path/to/guests''<br />
public = yes<br />
only guest = yes<br />
writable = yes<br />
printable = no<br />
}}<br />
<br />
See {{man|5|smb.conf}} for a full overview of possible permission flags and settings.<br />
<br />
==== Restrict protocols for better security ====<br />
<br />
{{Warning|By default, Samba versions prior to 4.11 allow connections using the outdated and insecure SMB1 protocol. When using one these Samba versions, it is highly recommended to set {{ic|1=server min protocol = SMB2_02}} to protect yourself from ransomware attacks. In Samba 4.11 and newer, SMB2 is the default min protocol, so no changes are required there.}}<br />
<br />
[[Append]] {{ic|server min protocol}} and {{ic|server max protocol}} in {{ic|/etc/samba/smb.conf}} to force usage of a minimum and maximum protocol:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
server min protocol = SMB2_02<br />
; server max protocol = SMB3<br />
}}<br />
<br />
See {{ic|server max protocol}} in {{man|5|smb.conf}} for an overview of supported protocols.<br />
<br />
For compatibility with older clients and/or servers, you might need to set {{ic|1=client min protocol = CORE}} or {{ic|1=server min protocol = CORE}}, but please note that this makes you vulnerable to exploits in SMB1 including ransomware attacks.<br />
<br />
{{Tip|Use {{ic|1=server min protocol = SMB3_00}} when clients should only connect using the latest SMB3 protocol, e.g. on clients running Windows 8 and later.}}<br />
<br />
[[#Manual mounting|Clients]] using {{ic|mount.cifs}} may need to specify the correct {{ic|1=vers=*}}, e.g.:<br />
<br />
# mount -t cifs //''SERVER''/''sharename'' /mnt/''mountpoint'' -o username=''username'',password=''password'',iocharset=''utf8'',vers=''3.1.1''<br />
<br />
See {{man|8|mount.cifs}} for more information.<br />
<br />
==== Use native SMB transport encryption ====<br />
<br />
Native SMB transport encryption is available in SMB version 3.0 or newer. Clients supporting this type of encryption include Windows 8 and newer, Windows server 2012 and newer, and smbclient of Samba 4.1 and newer.<br />
<br />
To use native SMB transport encryption by default, set the {{ic|server smb encrypt}} parameter globally and/or by share. Possible values are {{ic|off}}, {{ic|enabled}} (default value), {{ic|desired}}, or {{ic|required}}:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
server smb encrypt = desired<br />
}}<br />
<br />
To configure encryption for on the client side, use the option {{ic|client smb encrypt}}.<br />
<br />
See {{man|5|smb.conf}} for more information, especially the paragraphs ''Effects for SMB1'' and ''Effects for SMB2''.<br />
<br />
{{Tip|When [[#Manual mounting|mounting]] a share, specify the {{ic|seal}} mount option to force usage of encryption.}}<br />
<br />
==== Disable printer sharing ====<br />
<br />
By default Samba shares printers configured using [[CUPS]].<br />
<br />
If you do not want printers to be shared, use the following settings:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
load printers = no<br />
printing = bsd<br />
printcap name = /dev/null<br />
disable spoolss = yes<br />
show add printer wizard = no<br />
}}<br />
<br />
==== Block certain file extensions on Samba share ====<br />
<br />
{{Note|Setting this parameter will affect the performance of Samba, as it will be forced to check all files and directories for a match as they are scanned.}}<br />
<br />
Samba offers an option to block files with certain patterns, like file extensions. This option can be used to prevent dissemination of viruses or to dissuade users from wasting space with certain files. More information about this option can be found in {{man|5|smb.conf}}.<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
[myshare]<br />
comment = Private<br />
path = /mnt/data<br />
read only = no<br />
veto files = /*.exe/*.com/*.dll/*.bat/*.vbs/*.tmp/*.mp3/*.avi/*.mp4/*.wmv/*.wma/<br />
}}<br />
<br />
==== Improve throughput ====<br />
<br />
{{Warning|Beware this may lead to corruption/connection issues and potentially cripple your TCP/IP stack.}}<br />
<br />
The default settings should be sufficient for most users. However setting the 'socket options' correct can improve performance, but getting them wrong can degrade it by just as much. Test the effect before making any large changes.<br />
<br />
Read the {{man|5|smb.conf}} man page before applying any of the options listed below.<br />
<br />
The following settings should be [[Append|appended]] to the {{ic|[global]}} section of {{ic|/etc/samba/smb.conf}}.<br />
<br />
SMB3 multi-channel may improve performance, however it may result in data corruption under some rare conditions. Future releases may improve this situation:<br />
<br />
server multi channel support = yes<br />
<br />
Setting a deadtime is useful to stop a server's resources from being exhausted by a large number of inactive connections:<br />
<br />
deadtime = 30<br />
<br />
The usage of sendfile may make more efficient use of the system CPU's and cause Samba to be faster:<br />
<br />
use sendfile = yes<br />
<br />
Setting min receivefile size allows zero-copy writes directly from network socket buffers into the filesystem buffer cache (if available). It may improve performance but user testing is recommended:<br />
<br />
min receivefile size = 16384<br />
<br />
Reading/writing files asynchronously may improve performance instead of using synchronously writes:<br />
<br />
aio read size = 1<br />
aio write size = 1<br />
<br />
Increasing the receive/send buffers size and socket optimize flags might be useful to improve throughput. It is recommended to test each flag separately as it may cause issues on some networks:<br />
<br />
socket options = IPTOS_LOWDELAY TCP_NODELAY IPTOS_THROUGHPUT SO_RCVBUF=131072 SO_SNDBUF=131072<br />
<br />
{{Note|Network-interface adjustments may be needed for some options to work, see [[Sysctl#Networking]].}}<br />
<br />
==== Enable access for old clients/devices ====<br />
<br />
Latest versions of Samba no longer offer older authentication methods and protocols which are still used by some older clients (IP cameras, etc). These devices usually require Samba server to allow NTMLv1 authentication and NT1 version of the protocol, known as CIFS. For these devices to work with latest Samba, you need to add these two configuration parameters into {{ic|[global]}} section:<br />
<br />
server min protocol = NT1<br />
ntlm auth = yes<br />
<br />
Anonymous/guest access to a share requires just the first parameter. If the old device will access with username and password, you also need the add the second line too.<br />
<br />
== Client ==<br />
<br />
Install {{Pkg|smbclient}} for an {{ic|ftp}}-like command line interface. See {{man|1|smbclient}} for commonly used commands.<br />
<br />
For a lightweight alternative (without support for listing public shares, etc.), [[install]] {{Pkg|cifs-utils}} that provides {{ic|/usr/bin/mount.cifs}}.<br />
<br />
Depending on the [[desktop environment]], GUI methods may be available. See [[#File manager configuration]] for use with a file manager.<br />
<br />
{{Note|<br />
* {{Pkg|smbclient}} requires a {{ic|/etc/samba/smb.conf}} file (see [[#Installation]]), which you can create as an empty file using the {{ic|touch}} utility.<br />
* After installing {{Pkg|cifs-utils}} or {{Pkg|smbclient}}, load the {{ic|cifs}} [[kernel module]] or reboot to prevent mount fails.<br />
}}<br />
<br />
=== List public shares ===<br />
<br />
The following command lists public shares on a server:<br />
<br />
$ smbclient -L ''hostname'' -U%<br />
<br />
Alternatively, running ''smbtree'' will show a tree diagram of all the shares. This is not advisable on a network with a lot of computers, but can be helpful for diagnosing if you have the correct sharename.<br />
<br />
$ smbtree -b -N<br />
<br />
Where the options are {{ic|-b}} ({{ic|--broadcast}}) to use broadcast instead of using the master browser and {{ic|-N}} ({{ic|-no-pass}}) to not ask for a password.<br />
<br />
=== NetBIOS/WINS host names ===<br />
<br />
You may need to [[start]] {{ic|winbind.service}} and {{ic|nmb.service}} in order to resolve host names with e.g., {{ic|mount.cifs}}<br />
{{Note|Due to a current mistake in {{ic|winbind.service}}, you may have to modify the unit file as described in this [https://bugs.launchpad.net/ubuntu/+source/samba/+bug/1789097 bug-report]}}<br />
<br />
The {{pkg|smbclient}} package provides a driver to resolve host names using WINS. To enable it, add {{ic|wins}} to the “hosts” line in {{ic|/etc/nsswitch.conf}}.<br />
<br />
If it is not already there, add it to look roughly like this:<br />
<br />
{{hc|/etc/nsswitch.conf|2=<br />
...<br />
hosts: files mymachines myhostname mdns_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] dns wins<br />
...<br />
}}<br />
<br />
You can test WINS resolution with {{ic|nmblookup}}. Note that WINS resolution requires incoming traffic originating from port 137.<br />
<br />
==== Disable NetBIOS/WINS support ====<br />
<br />
When not using NetBIOS/WINS host name resolution, it may be preferred to disable this protocol:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
disable netbios = yes<br />
dns proxy = no<br />
}}<br />
<br />
Finally [[disable]]/[[stop]] {{ic|winbind.service}}.<br />
<br />
=== Manual mounting ===<br />
<br />
Create a mount point for the share:<br />
<br />
# mkdir /mnt/''mountpoint''<br />
<br />
Mount the share using {{ic|mount.cifs}} as {{ic|type}}. Not all the options listed below are needed or desirable:<br />
<br />
# mount -t cifs //''SERVER''/''sharename'' /mnt/''mountpoint'' -o username=''username'',password=''password'',workgroup=''workgroup'',iocharset=''utf8'',uid=''username'',gid=''group''<br />
<br />
The options {{ic|uid}} and {{ic|gid}} corresponds to the local (e.g. client) [[user]]/[[user group]] to have read/write access on the given path.<br />
<br />
{{Note|<br />
* If the {{ic|uid}} and {{ic|gid}} being used does not match the user of the server, the {{ic|forceuid}} and {{ic|forcegid}} options may be helpful. However note permissions assigned to a file when {{ic|forceuid}} or {{ic|forcegid}} are in effect may not reflect the the real (server) permissions. See the ''File And Directory Ownership And Permissions'' section in {{man|8|mount.cifs|FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS}} for more information.<br />
* To allow users to mount it as long as the mount point resides in a directory controllable by the user; i.e. the user's home, append the {{ic|users}} mount option. The option is user'''s''' (plural). For other filesystem types handled by mount, this option is usually ''user''; sans the "'''s'''".<br />
* To mount a Windows share without authentication, use {{ic|1="username=*"}}.<br />
}}<br />
<br />
{{Warning|Using {{ic|uid}} and/or {{ic|gid}} as mount options may cause I/O errors, it is recommended to set/check correct [[File permissions and attributes]] instead.}}<br />
<br />
* {{ic|''SERVER''}} — The server name.<br />
* {{ic|''sharename''}} — The shared directory.<br />
* {{ic|''mountpoint''}} — The local directory where the share will be mounted.<br />
* {{ic|[-o ''options'']}} — See {{man|8|mount.cifs}} for more information.<br />
<br />
{{Note|<br />
* Abstain from using a trailing {{ic|/}}. {{ic|//''SERVER''/''sharename'''''/'''}} will not work.<br />
* If your mount does not work stable, stutters or freezes, try to enable different SMB protocol version with {{ic|1=vers=}} option. For example, {{ic|1=vers=2.0}} for Windows Vista mount.<br />
* If having timeouts on a mounted network share with cifs on a shutdown, see [[wpa_supplicant#Problem with mounted network shares (cifs) and shutdown]].<br />
}}<br />
<br />
==== Storing share passwords ====<br />
<br />
Storing passwords in a world readable file is not recommended. A safer method is to use a credentials file instead, e.g. inside {{ic|/etc/samba/credentials}}:<br />
<br />
{{hc|/etc/samba/credentials/share|2=<br />
username=''myuser''<br />
password=''mypass''<br />
}}<br />
<br />
For the mount command replace {{ic|1=username=myuser,password=mypass}} with {{ic|1=credentials=/etc/samba/credentials/share}}.<br />
<br />
The credential file should explicitly readable/writeable to root:<br />
<br />
# chown root:root /etc/samba/credentials<br />
# chmod 700 /etc/samba/credentials<br />
# chmod 600 /etc/samba/credentials/share<br />
<br />
=== Automatic mounting ===<br />
<br />
{{Note|You may need to [[enable]] {{ic|systemd-networkd-wait-online.service}} or {{ic| NetworkManager-wait-online.service}} (depending on your setup) to proper enable booting on start-up.}}<br />
<br />
==== Using NetworkManager and GIO/gvfs ====<br />
<br />
[[NetworkManager#Network services with NetworkManager dispatcher|NetworkManager]] can be configured to run a script on network status change. This script uses the ''gio'' command so that it mounts the Samba shares automatically, the same way your file manager does, as explained [[#File manager configuration|below]]. The script also safely unmounts the Samba shares before the relevant network connection is disabled by listening for the {{ic|pre-down}} and {{ic|vpn-pre-down}} events. Make the script is [[executable]] after creating it.<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/30-samba.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 />
# The user the share will be mounted under<br />
USER="yourusername"<br />
# The path that appears in your file manager when you manually mount the share you want<br />
SMB_URL="smb://servername/share"<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 />
su $USER -c "DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus gio mount $SMB_URL"<br />
;;<br />
"pre-down");&<br />
"vpn-pre-down")<br />
su $USER -c "DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus gio mount -uf $SMB_URL"<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
Create a symlink inside {{ic|/etc/NetworkManager/dispatcher.d/pre-down}} to catch the {{ic|pre-down}} events:<br />
<br />
# ln -s /etc/NetworkManager/dispatcher.d/30-samba.sh /etc/NetworkManager/dispatcher.d/pre-down.d/30-samba.sh<br />
<br />
==== As mount entry ====<br />
<br />
This is a simple example of a {{ic|cifs}} [[fstab|mount entry]] that requires authentication:<br />
<br />
{{hc|/etc/fstab|2=<br />
//''SERVER''/''sharename'' /mnt/''mountpoint'' cifs _netdev,nofail,username=''myuser'',password=''mypass'' 0 0<br />
}}<br />
<br />
{{Note|Spaces in sharename should be replaced by {{ic|\040}} (ASCII code for space in octal). For example, {{ic|//''SERVER''/share name}} on the command line should be {{ic|//''SERVER''/share\040name}} in {{ic|/etc/fstab}}.}}<br />
<br />
{{Tip|Use {{ic|x-systemd.automount}} if you want them to be mounted only upon access. See [[Fstab#Remote filesystem]] for details.}}<br />
<br />
==== As systemd unit ====<br />
<br />
Create a new {{ic|.mount}} file inside {{ic|/etc/systemd/system}}, e.g. {{ic|mnt-myshare.mount}}. See {{man|5|systemd.mount}} for details.<br />
<br />
{{Note|Make sure the filename corresponds to the mountpoint you want to use.<br />
E.g. the unit name {{ic|mnt-myshare.mount}} can only be used if are going to mount the share under {{ic|/mnt/myshare}}. Otherwise the following error might occur: {{ic|1=systemd[1]: mnt-myshare.mount: Where= setting does not match unit name. Refusing.}}.}}<br />
<br />
{{ic|1=What=}} path to share<br />
<br />
{{ic|1=Where=}} path to mount the share<br />
<br />
{{ic|1=Options=}} share mounting options<br />
<br />
{{Note|<br />
* Network mount units automatically acquire {{ic|After}} dependencies on {{ic|remote-fs-pre.target}}, {{ic|network.target}} and {{ic|network-online.target}}, and gain a {{ic|Before}} dependency on {{ic|remote-fs.target}} unless {{ic|nofail}} mount option is set. Towards the latter a {{ic|Wants}} unit is added as well.<br />
* [[Append]] {{ic|noauto}} to {{ic|Options}} preventing automatically mount during boot (unless it is pulled in by some other unit).<br />
* If you want to use a hostname for the server you want to share (instead of an IP address), add {{ic|1=nss-lookup.target}} to {{ic|1=After}}. This might avoid mount errors at boot time that do not arise when testing the unit.<br />
}} <br />
<br />
{{hc|/etc/systemd/system/mnt-myshare.mount|2=<br />
[Unit]<br />
Description=Mount Share at boot<br />
<br />
[Mount]<br />
What=//server/share<br />
Where=/mnt/myshare<br />
Options=_netdev,credentials=/etc/samba/credentials/myshare,iocharset=utf8,rw<br />
Type=cifs<br />
TimeoutSec=30<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{Tip|<br />
* In case of an unreachable system, [[append]] {{ic|1=ForceUnmount=true}} to {{ic|[Mount]}}, allowing the share to be (force-)unmounted.<br />
* If your share has groups with read-only access, [[append]] {{ic|1=uid=''username''}} or {{ic|1=gid=''group''}} to {{ic|1=Options=}}, to specify your user / group allowing writing to the share.<br />
}}<br />
<br />
To use {{ic|mnt-myshare.mount}}, [[start]] the unit and [[enable]] it to run on system boot.<br />
<br />
===== automount =====<br />
<br />
To automatically mount a share (when accessed, like autofs), one may use the following automount unit:<br />
<br />
{{hc|/etc/systemd/system/mnt-myshare.automount|2=<br />
[Unit]<br />
Description=Automount myshare<br />
<br />
[Automount]<br />
Where=/mnt/myshare<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
[[Disable]]/[[stop]] the {{ic|mnt-myshare.mount}} unit, and [[enable]]/[[start]] {{ic|mnt-myshare.automount}} to automount the share when the mount path is being accessed.<br />
<br />
{{Tip|[[Append]] {{ic|TimeoutIdleSec}} to enable auto unmount. See {{man|5|systemd.automount}} for details.}}<br />
<br />
==== smbnetfs ====<br />
<br />
{{Note|1=smbnetfs needs an intact Samba server setup.<br />
<br />
See above on how to do that.}}<br />
<br />
First, check if you can see all the shares you are interested in mounting:<br />
<br />
$ smbtree -U ''remote_user''<br />
<br />
If that does not work, find and modify the following line<br />
in {{ic|/etc/samba/smb.conf}} accordingly:<br />
<br />
domain master = auto<br />
<br />
Now [[restart]] {{ic|smb.service}} and {{ic|nmb.service}}.<br />
<br />
If everything works as expected, [[pacman#Installing specific packages|install]] {{Pkg|smbnetfs}} from the official repositories.<br />
<br />
Then, add the following line to {{ic|/etc/fuse.conf}}:<br />
<br />
user_allow_other<br />
<br />
Now copy the directory {{ic|/etc/smbnetfs/.smb}} to your home directory:<br />
<br />
$ cp -a /etc/smbnetfs/.smb ~<br />
<br />
Then create a link to {{ic|smb.conf}}:<br />
<br />
$ ln -sf /etc/samba/smb.conf ~/.smb/smb.conf<br />
<br />
If a username and a password are required to access some of the shared folders, edit {{ic|~/.smb/smbnetfs.auth}}<br />
to include one or more entries like this:<br />
<br />
{{hc|~/.smb/smbnetfs.auth|<br />
auth "hostname" "username" "password"<br />
}}<br />
<br />
It is also possible to add entries for specific hosts to be mounted by smbnetfs, if necessary.<br />
More details can be found in {{ic|~/.smb/smbnetfs.conf}}.<br />
<br />
If you are using the [[Dolphin]] or [[GNOME Files]], you may want to add the following to {{ic|~/.smb/smbnetfs.conf}} to avoid "Disk full" errors as smbnetfs by default will report 0 bytes of free space:<br />
<br />
{{hc|~/.smb/smbnetfs.conf|<br />
free_space_size 1073741824<br />
}}<br />
<br />
When you are done with the configuration, you need to run<br />
<br />
$ chmod 600 ~/.smb/smbnetfs.*<br />
<br />
Otherwise, smbnetfs complains about 'insecure config file permissions'.<br />
<br />
Finally, to mount your Samba network neighbourhood to a directory of your choice, call<br />
<br />
$ smbnetfs ''mount_point''<br />
<br />
===== Daemon =====<br />
<br />
The Arch Linux package also maintains an additional system-wide operation mode for smbnetfs. To enable it, you need to make the<br />
said modifications in the directory {{ic|/etc/smbnetfs/.smb}}.<br />
<br />
Then, you can start and/or enable the {{ic|smbnetfs}} [[daemon]] as usual. The system-wide mount point is at {{ic|/mnt/smbnet/}}.<br />
<br />
==== autofs ====<br />
<br />
See [[Autofs]] for information on the kernel-based automounter for Linux.<br />
<br />
=== File manager configuration ===<br />
<br />
==== GNOME Files, Nemo, Caja, Thunar and PCManFM ====<br />
<br />
In order to access samba shares through GNOME Files, Nemo, Caja, Thunar or PCManFM, install the {{Pkg|gvfs-smb}} package, available in the [[official repositories]].<br />
<br />
Press {{ic|Ctrl+l}} and enter {{ic|smb://''servername''/''share''}} in the location bar to access your share.<br />
<br />
The mounted share is likely to be present at {{ic|/run/user/''your_UID''/gvfs}} or {{ic|~/.gvfs}} in the filesystem.<br />
<br />
==== KDE ====<br />
<br />
KDE applications (like Dolphin) has the ability to browse Samba shares built in. Use the path {{ic|smb://''servername''/''share''}} to browse the files. If you want to access files from on non-KDE application, you can install {{Pkg|kio-fuse}}.<br />
<br />
To use a GUI in the KDE System Settings, you will need to install the {{Pkg|kdenetwork-filesharing}} package.<br />
<br />
==== Other graphical environments ====<br />
<br />
There are a number of useful programs, but they may need to have packages created for them. This can be done with the Arch package build system. The good thing about these others is that they do not require a particular environment to be installed to support them, and so they bring along less baggage.<br />
<br />
* {{AUR|pyneighborhood}} is available in the official repositories.<br />
* LinNeighborhood, RUmba, xffm-samba plugin for Xffm are not available in the official repositories or the AUR. As they are not officially (or even unofficially supported), they may be obsolete and may not work at all.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Discovering network shares ===<br />
<br />
If nothing is known about other systems on the local network, and automated tools such as [[#smbnetfs|smbnetfs]] are not available, the following methods allow one to manually probe for Samba shares.<br />
<br />
1. First, [[install]] the {{Pkg|nmap}} and {{Pkg|smbclient}} packages.<br />
<br />
2. {{ic|nmap}} checks which ports are open:<br />
<br />
# nmap -p 139 -sT "192.168.1.*"<br />
<br />
In this case, a scan on the 192.168.1.* IP address range and port 139 has been performed, resulting in:<br />
<br />
{{hc|$ nmap -sT "192.168.1.*"|<nowiki><br />
Starting nmap 3.78 ( http://www.insecure.org/nmap/ ) at 2005-02-15 11:45 PHT<br />
Interesting ports on 192.168.1.1:<br />
(The 1661 ports scanned but not shown below are in state: closed)<br />
PORT STATE SERVICE<br />
'''139/tcp open netbios-ssn'''<br />
5000/tcp open UPnP<br />
<br />
Interesting ports on 192.168.1.5:<br />
(The 1662 ports scanned but not shown below are in state: closed)<br />
PORT STATE SERVICE<br />
6000/tcp open X11<br />
<br />
Nmap run completed -- 256 IP addresses (2 hosts up) scanned in 7.255 seconds<br />
</nowiki>}}<br />
<br />
The first result is another system; the second happens to be the client from where this scan was performed.<br />
<br />
3. Now that systems with port 139 open are revealed, use {{man|1|nmblookup}} to check for NetBIOS names: <br />
<br />
{{hc|$ nmblookup -A 192.168.1.1|<br />
Looking up status of 192.168.1.1<br />
PUTER <00> - B <ACTIVE><br />
HOMENET <00> - <GROUP> B <ACTIVE><br />
PUTER <03> - B <ACTIVE><br />
'''PUTER <20> - B <ACTIVE>'''<br />
HOMENET <1e> - <GROUP> B <ACTIVE><br />
USERNAME <03> - B <ACTIVE><br />
HOMENET <1d> - B <ACTIVE><br />
MSBROWSE <01> - <GROUP> B <ACTIVE><br />
}}<br />
<br />
Regardless of the output, look for '''<20>''', which shows the host with open services.<br />
<br />
4. Use {{ic|smbclient}} to list which services are shared on ''PUTER''. If prompted for a password, pressing enter should still display the list:<br />
<br />
{{hc|$ smbclient -L \\PUTER|<nowiki><br />
Sharename Type Comment<br />
--------- ---- -------<br />
MY_MUSIC Disk<br />
SHAREDDOCS Disk<br />
PRINTER$ Disk<br />
PRINTER Printer<br />
IPC$ IPC Remote Inter Process Communication<br />
<br />
Server Comment<br />
--------- -------<br />
PUTER<br />
<br />
Workgroup Master<br />
--------- -------<br />
HOMENET PUTER<br />
</nowiki>}}<br />
<br />
=== Remote control of Windows computer ===<br />
<br />
Samba offers a set of tools for communication with Windows. These can be handy if access to a Windows computer through remote desktop is not an option, as shown by some examples.<br />
<br />
Send shutdown command with a comment:<br />
<br />
$ net rpc shutdown -C "comment" -I IPADDRESS -U USERNAME%PASSWORD<br />
<br />
A forced shutdown instead can be invoked by changing -C with comment to a single -f. For a restart, only add -r, followed by a -C or -f.<br />
<br />
Stop and start services:<br />
<br />
$ net rpc service stop SERVICENAME -I IPADDRESS -U USERNAME%PASSWORD<br />
<br />
To see all possible net rpc command:<br />
<br />
$ net rpc<br />
<br />
== Troubleshooting ==<br />
<br />
=== Failed to start Samba SMB/CIFS server ===<br />
<br />
Possible solutions:<br />
<br />
* Check {{ic|smb.conf}} on syntactic errors with {{man|1|testparm}}.<br />
* Set correct permissions for {{ic|/var/cache/samba/}} and [[restart]] {{ic|smb.service}}:<br />
<br />
# chmod 0755 /var/cache/samba/msg<br />
<br />
=== Permission issues on SELinux ===<br />
<br />
[[SELinux]] not allow samba to access user home directories by default, to solve this, run:<br />
<br />
# setsebool -P samba_enable_home_dirs 1<br />
<br />
Similarly, {{ic|samba_export_all_ro}} and {{ic|samba_export_all_rw}} make [[Samba]] has the ability to read or "read and write" all files.<br />
<br />
=== Permission issues on AppArmor ===<br />
<br />
If using a [[#Creating an anonymous share|share path]] located outside of a home or usershares directory, whitelist it in {{ic|/etc/apparmor.d/local/usr.sbin.smbd}}. E.g.:<br />
<br />
{{hc|/etc/apparmor.d/local/usr.sbin.smbd|<br />
"/data/" rk,<br />
"/data/**" lrwk,<br />
}}<br />
<br />
=== No dialect specified on mount ===<br />
<br />
The client is using an unsupported SMB/CIFS version that is required by the server.<br />
<br />
See [[#Restrict protocols for better security]] for more information.<br />
<br />
=== Unable to overwrite files, permissions errors ===<br />
<br />
{{Accuracy|An user should set/check for server/client permissions, instead of using incorrect/possible insecure flags.}}<br />
<br />
Possible solutions:<br />
<br />
* Append the mount option {{ic|nodfs}} to the {{ic|/etc/fstab}} [[#As mount entry|entry]].<br />
* Add {{ic|1=msdfs root = no}} to the {{ic|[global]}} section of the server's {{ic|/etc/samba/smb.conf}}.<br />
<br />
=== Windows clients keep asking for password even if Samba shares are created with guest permissions ===<br />
<br />
Set {{ic|map to guest}} inside the {{ic|global}} section of {{ic|/etc/samba/smb.conf}}:<br />
<br />
map to guest = Bad User<br />
<br />
From Samba 4.10.10 you should use {{ic|Bad Password}} instead {{ic|Bad User}}.<br />
<br />
=== Windows 7 connectivity problems - mount error(12): cannot allocate memory ===<br />
<br />
A known Windows 7 bug that causes "mount error(12): cannot allocate memory" on an otherwise perfect cifs share on the Linux end can be fixed by setting a few registry keys on the Windows box as follows:<br />
<br />
* {{ic|HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\LargeSystemCache}} (set to {{ic|1}})<br />
* {{ic|HKLM\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters\Size}} (set to {{ic|3}})<br />
<br />
Alternatively, start Command Prompt in Admin Mode and execute the following:<br />
<br />
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management" /v "LargeSystemCache" /t REG_DWORD /d 1 /f<br />
reg add "HKLM\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters" /v "Size" /t REG_DWORD /d 3 /f<br />
<br />
Do one of the following for the settings to take effect:<br />
<br />
* Restart Windows<br />
* Restart the Server service via services.msc<br />
* From the Command Prompt run: 'net stop lanmanserver' and 'net start lanmanserver' - The server may automatically restart after stopping it.<br />
<br />
{{Note|Googling will reveal another tweak recommending users to add a key modifying the "IRPStackSize" size. This is incorrect for fixing this issue under Windows 7. Do not attempt it.}}<br />
<br />
[https://web.archive.org/web/20150819153712/http://alan.lamielle.net/2009/09/03/windows-7-nonpaged-pool-srv-error-2017/ Original article].<br />
<br />
=== Windows 10 1709 and up connectivity problems - "Windows cannot access" 0x80004005 ===<br />
<br />
This error affects some machines running Windows 10 version 1709 and later. It is not related to SMB1 being disabled in this version but to the fact that Microsoft disabled insecure logons for guests on this version for some, but not others.<br />
<br />
To fix, open Group Policy Editor ({{ic|gpedit.msc}}). Navigate to ''Computer configuration\administrative templates\network\Lanman Workstation > Enable insecure guest logons'' and enable it.<br />
Alternatively,change the following value in the registry:<br />
<br />
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters]<br />
"AllowInsecureGuestAuth"=dword:1<br />
<br />
=== Error: Failed to retrieve printer list: NT_STATUS_UNSUCCESSFUL ===<br />
<br />
If you are a home user and using samba purely for file sharing from a server or NAS, you are probably not interested in sharing printers through it. If so, you can prevent this error from occurring by adding the following lines to your {{ic|/etc/samba/smb.conf}}:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
load printers = No<br />
printing = bsd<br />
printcap name = /dev/null<br />
disable spoolss = Yes<br />
}}<br />
<br />
[[Restart]] the samba service, {{ic|smb.service}}, and then check your logs:<br />
<br />
# cat /var/log/samba/smbd.log<br />
<br />
and the error should now no longer be appearing.<br />
<br />
=== Sharing a folder fails ===<br />
<br />
It means that while you are sharing a folder from ''Dolphin'' (file manager) and everything seems ok at first, after restarting ''Dolphin'' the share icon is gone from the shared folder, and also some output like this in terminal (''Konsole'') output:<br />
<br />
‘net usershare’ returned error 255: net usershare: usershares are currently disabled<br />
<br />
To fix it, enable usershare as described in [[#Enable Usershares]].<br />
<br />
=== "Browsing" network fails with "Failed to retrieve share list from server" ===<br />
<br />
And you are using a firewall (iptables) because you do not trust your local (school, university, hotel) network. This may be due to the following: When the smbclient is browsing the local network it sends out a broadcast request on udp port 137. The servers on the network then reply to your client but as the source address of this reply is different from the destination address iptables saw when sending the request for the listing out, iptables will not recognize the reply as being "ESTABLISHED" or "RELATED", and hence the packet is dropped. A possible solution is to add:<br />
<br />
iptables -t raw -A OUTPUT -p udp -m udp --dport 137 -j CT --helper netbios-ns<br />
<br />
to your iptables setup.<br />
<br />
For [[Uncomplicated Firewall]], you need to add {{ic|nf_conntrack_netbios_ns}} to the end of the following line in {{ic|/etc/default/ufw}}<br />
<br />
IPT_MODULES="nf_conntrack_ftp nf_nat_ftp nf_conntrack_irc nf_nat_irc"<br />
<br />
and then run the following commands as root:<br />
<br />
echo 1 > /proc/sys/net/netfilter/nf_conntrack_helper<br />
ufw allow CIFS<br />
ufw reload<br />
<br />
To make this change persistent across reboots, add the following line at the end of {{ic|/etc/ufw/sysctl.conf}}:<br />
<br />
net.netfilter.nf_conntrack_helper=1<br />
<br />
=== Protocol negotiation failed: NT_STATUS_INVALID_NETWORK_RESPONSE ===<br />
<br />
The client probably does not have access to shares. Make sure clients' IP address is in {{ic|1=hosts allow =}} line in {{ic|/etc/samba/smb.conf}}.<br />
<br />
Another problem could be, that the client uses an invalid protocol version. To check this try to connect with the {{ic|smbclient}} where you specify the maximum protocol version manually:<br />
<br />
$ smbclient -U <user name> -L //<server name> -m <protocol version: e. g. SMB2> -W <domain name><br />
<br />
If the command was successful then create a configuration file:<br />
<br />
{{hc|~/.smb/smb.conf|output=<br />
[global]<br />
workgroup = <domain name><br />
client max protocol = SMB2<br />
}}<br />
<br />
=== Connection to SERVER failed: (Error NT_STATUS_UNSUCCESSFUL) ===<br />
<br />
You are probably passing a wrong server name to {{ic|smbclient}}. To find out the server name, run {{ic|hostnamectl}} on the server and look at "Transient hostname" line<br />
<br />
=== Connection to SERVER failed: (Error NT_STATUS_CONNECTION_REFUSED) ===<br />
<br />
Make sure that the server has started. The shared directories should exist and be accessible.<br />
<br />
=== Protocol negotiation failed: NT_STATUS_CONNECTION_RESET ===<br />
<br />
Probably the server is configured not to accept protocol SMB1. Add option {{ic|1=client max protocol = SMB2}} in {{ic|/etc/samba/smb.conf}}.<br />
Or just pass argument {{ic|-m SMB2}} to {{ic|smbclient}}.<br />
<br />
=== Password Error when correct credentials are given (error 1326) ===<br />
<br />
[https://www.samba.org/samba/history/samba-4.5.0.html Samba 4.5] has NTLMv1 authentication disabled by default. It is recommend to install the latest available upgrades on clients and deny access for unsupported clients.<br />
<br />
If you still need support for very old clients without NTLMv2 support (e.g. Windows XP), it is possible force enable NTLMv1, although this is '''not recommend''' for security reasons:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
lanman auth = yes<br />
ntlm auth = yes<br />
}}<br />
<br />
If NTLMv2 clients are unable to authenticate when NTLMv1 has been enabled, create the following file on the client:<br />
{{hc|/home/user/.smb/smb.conf|2=<br />
[global]<br />
sec = ntlmv2<br />
client ntlmv2 auth = yes<br />
}}<br />
<br />
This change also affects samba shares mounted with '''mount.cifs'''. If after upgrade to Samba 4.5 your mount fails, add the '''sec=ntlmssp''' option to your mount command, e.g.<br />
<br />
mount.cifs //server/share /mnt/point -o sec=ntlmssp,...<br />
<br />
See the {{man|8|mount.cifs}} man page: '''ntlmssp''' - Use NTLMv2 password hashing encapsulated in Raw NTLMSSP message. The default in mainline kernel versions prior to v3.8 was '''sec=ntlm'''. In v3.8, the default was changed to '''sec=ntlmssp'''.<br />
<br />
=== Mapping reserved Windows characters ===<br />
<br />
Starting with kernel 3.18, the cifs module uses the [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=2baa2682531ff02928e2d3904800696d9e7193db "mapposix" option by default].<br />
When mounting a share using unix extensions and a default Samba configuration, files and directories containing one of the seven reserved Windows characters {{ic|: \ * < > ? |}} are listed but cannot be accessed.<br />
<br />
Possible solutions are:<br />
<br />
* Use the undocumented {{ic|nomapposix}} mount option for cifs<br />
<br />
# mount.cifs //server/share /mnt/point -o nomapposix<br />
<br />
* Configure Samba to remap {{ic|mapposix}} ("SFM", Services for Mac) style characters to the correct native ones using [https://www.mankier.com/8/vfs_fruit fruit]<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
vfs objects = catia fruit<br />
fruit:encoding = native<br />
}}<br />
<br />
* Manually remap forbidden characters using [https://www.mankier.com/8/vfs_catia catia]<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
vfs objects = catia<br />
catia:mappings = 0x22:0xf022, 0x2a:0xf02a, 0x2f:0xf02f, 0x3a:0xf03a, 0x3c:0xf03c, 0x3e:0xf03e, 0x3f:0xf03f, 0x5c:0xf05c, 0x7c:0xf07c, 0x20:0xf020<br />
}}<br />
<br />
The latter approach (using catia or fruit) has the drawback of filtering files with unprintable characters.<br />
<br />
=== Folder shared inside graphical environment is not available to guests ===<br />
<br />
This section presupposes:<br />
<br />
# Usershares are configured following [[#Enable Usershares|previous section]]<br />
# A shared folder has been created as a non-root user from GUI<br />
# Guests access has been set to shared folder during creation<br />
# Samba service has been restarted at least once since last {{ic|/etc/samba/smb.conf}} file modification<br />
<br />
For clarification purpose only, in the following sub-sections is assumed:<br />
<br />
* Shared folder is located inside user home directory path ({{ic|/home/yourUser/Shared}})<br />
* Shared folder name is ''MySharedFiles''<br />
* Guest access is read-only.<br />
* Windows users will access shared folder content without login prompt<br />
<br />
==== Verify correct samba configuration ====<br />
<br />
Run the following command from a terminal to test configuration file correctness:<br />
<br />
$ testparm<br />
<br />
==== Verify correct shared folder creation ====<br />
<br />
Run the following commands from a terminal:<br />
<br />
$ cd /var/lib/samba/usershare<br />
$ ls<br />
<br />
If everything is fine, you will notice a file named {{ic|mysharedfiles}}<br />
<br />
Read the file contents using the following command:<br />
<br />
$ cat mysharedfiles<br />
<br />
The terminal output should display something like this:<br />
<br />
{{hc|/var/lib/samba/usershare/mysharedfiles|2=<br />
path=/home/yourUser/Shared<br />
comment=<br />
usershare_acl=S-1-1-0:r<br />
guest_ok=y<br />
sharename=MySharedFiles<br />
}}<br />
<br />
==== Verify folder access by guest ====<br />
<br />
Run the following command from a terminal. If prompted for a password, just press Enter:<br />
<br />
$ smbclient -L localhost<br />
<br />
If everything is fine, MySharedFiles should be displayed under {{ic|Sharename}} column<br />
<br />
Run the following command in order to access the shared folder as guest (anonymous login)<br />
<br />
$ smbclient -N //localhost/MySharedFiles<br />
<br />
If everything is fine samba client prompt will be displayed:<br />
<br />
smb: \><br />
<br />
From samba prompt verify guest can list directory contents:<br />
<br />
smb: \> ls<br />
<br />
If the {{ic|NTFS_STATUS_ACCESS_DENIED}} error is displayed, the issue is likely to be with Unix directory permissions. Ensure that your samba user has access to the folder and all parent folders. You can test this by sudoing to the user and attempting to list the mount directory, and all of its parents.<br />
<br />
=== Mount error: Host is down ===<br />
<br />
This error might be seen when mounting shares of Synology NAS servers. Use the mount option {{ic|1=vers=1.0}} to solve it.<br />
<br />
{{Note|SMB version 1 is known to have security vulnerabilities and was used in successful ransomware attacks.}}<br />
<br />
=== Software caused connection abort ===<br />
<br />
File managers that utilizes {{Pkg|gvfs-smb}} can show the error {{ic|Software caused connection abort}} when writing a file to a share/server. This may be due to the server running SMB/CIFS version 1, which many routers use for USB drive sharing (e.g. Belkin routers). To write to these shares specify the CIFS version with the option {{ic|1=vers=1.0}}. E.g.:<br />
<br />
{{hc|/etc/fstab|2=<br />
//SERVER/sharename /mnt/mountpoint cifs _netdev,guest,file_mode=0777,dir_mode=0777,vers=1.0 0 0<br />
}}<br />
<br />
This can also happen after updating Samba to version 4.11, which deactivates SMB1 as default, and accessing any Samba share. You can reenable it by adding<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
client min protocol = CORE<br />
}}<br />
<br />
=== Connection problem (due to authentification error) ===<br />
<br />
Be sure that you do not leave any space characters before your username in Samba client configuration file as follows:<br />
<br />
{{hc|~/.samba|2=<br />
username= user<br />
password=pass<br />
}}<br />
<br />
The correct format is:<br />
<br />
{{hc|~/.samba|2=<br />
username=user<br />
password=pass<br />
}}<br />
<br />
=== Windows 1709 or up does not discover the samba server in Network view ===<br />
<br />
With Windows 10 version 1511, support for SMBv1 and thus NetBIOS device discovery was disabled by default. Depending on the actual edition, later versions of Windows starting from version 1709 ("Fall Creators Update") do not allow the installation of the SMBv1 client anymore. This causes hosts running Samba not to be listed in the Explorer's "Network (Neighborhood)" views. While there is no connectivity problem and Samba will still run fine, users might want to have their Samba hosts to be listed by Windows automatically. {{AUR|wsdd}} implements a Web Service Discovery host daemon. This enables (Samba) hosts, like your local NAS device, to be found by Web Service Discovery Clients like Windows. After the installation, no configuration is needed. You just need to start and enable {{ic|wsdd.service}}<br />
<br />
== See also ==<br />
<br />
* [https://www.samba.org/ Official website]<br />
* [https://www.samba.org/samba/docs/SambaIntro.html Samba: An Introduction]<br />
* [https://www.samba.org/samba/docs/Samba-HOWTO-Collection.pdf Samba 3.2.x HOWTO and Reference Guide] (outdated but still most extensive documentation)<br />
* [[Wikipedia:Samba (software)|Wikipedia]]<br />
* [[Gentoo:Samba/Guide]]<br />
* [[Debian:Samba/ServerSimple]]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Samba&diff=694456Samba2021-09-05T16:45:57Z<p>Pgoetz: clarified what automatically means</p>
<hr />
<div>[[Category:Network sharing]]<br />
[[Category:Servers]]<br />
[[de:Samba]]<br />
[[fr:Samba]]<br />
[[it:Samba]]<br />
[[ja:Samba]]<br />
[[ru:Samba]]<br />
[[zh-hans:Samba]]<br />
[[zh-hant:Samba]]<br />
{{Related articles start}}<br />
{{Related|Active Directory Integration}}<br />
{{Related|Samba/Active Directory domain controller}}<br />
{{Related|NFS}}<br />
{{Related articles end}}<br />
[https://www.samba.org/ Samba] is the standard Windows interoperability suite of programs for Linux and Unix. Since 1992, Samba has provided secure, stable and fast file and print services for all clients using the [[wikipedia:Server_Message_Block|SMB/CIFS]] protocol, such as all versions of DOS and Windows, OS/2, Linux and many others.<br />
<br />
To share files through Samba, see [[#Server]] section; to access files shared through Samba on other machines, please see [[#Client]] section.<br />
<br />
== Server ==<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{Pkg|samba}} package.<br />
<br />
Samba is configured in the {{ic|/etc/samba/smb.conf}} configuration file, which is extensively documented in {{man|5|smb.conf}}.<br />
<br />
Because the {{Pkg|samba}} package does not provide this file, one needs to create it '''before''' starting {{ic|smb.service}}.<br />
<br />
A documented example as in {{ic|smb.conf.default}} from the [https://git.samba.org/samba.git/?p=samba.git;a=blob_plain;f=examples/smb.conf.default;hb=HEAD Samba git repository] may be used to setup {{ic|/etc/samba/smb.conf}}. <br />
<br />
{{Note|<br />
* The default configuration sets {{ic|log file}} to a non-writable location, which will cause errors - apply one of the following workarounds:<br />
** Change the log file location to a writable path: {{ic|1=log file = /var/log/samba/%m.log}}<br />
** Change logging to a non-file backend solution: {{ic|1=logging = syslog}} with {{ic|1=syslog only = yes}}, or use {{ic|1=logging = systemd}}<br />
* If required; the {{ic|workgroup}} specified in the {{ic|[global]}} section has to match the Windows workgroup (default {{ic|WORKGROUP}}).<br />
}}<br />
<br />
{{Tip|Whenever you modify the {{ic|smb.conf}} file, run the {{man|1|testparm}} command to check for syntactic errors.}}<br />
<br />
==== Enabling and starting services ====<br />
<br />
To provide basic file sharing through SMB, [[enable/start]] {{ic|smb.service}} and {{ic|nmb.service}}. See {{man|8|smbd}} and {{man|8|nmbd}} for details.<br />
<br />
{{Note|{{ic|nmb.service}} is not required. However, it is needed to access Samba servers by hostname (e.g. {{ic|smb://hostname/}}).}}<br />
<br />
==== Configure firewall ====<br />
<br />
If you are using a [[firewall]], do not forget to open required ports (usually 137-139 + 445). For a complete list, see [https://www.samba.org/~tpot/articles/firewall.html Samba port usage].<br />
<br />
===== UFW Rule =====<br />
<br />
A [[Ufw]] App Profile for SMB/CIFS is included by default with the default installation of UFW in {{ic|ufw-fileserver}}.<br />
<br />
Allow Samba by running {{ic|ufw allow CIFS}} as root.<br />
<br />
If you deleted the profile, create/edit {{ic|/etc/ufw/applications.d/samba}} and add the following content:<br />
<br />
[Samba]<br />
title=LanManager-like file and printer server for Unix<br />
description=The Samba software suite is a collection of programs that implements the SMB/CIFS protocol for unix systems, allowing you to serve files and printers to Windows, NT, OS/2 and DOS clients. This protocol is sometimes also referred to as the LanManager or NetBIOS protocol.<br />
ports=137,138/udp|139,445/tcp<br />
<br />
Then load the profile into UFW run {{ic|ufw app update Samba}} as root.<br />
<br />
Then finally, allow Samba by running {{ic|ufw allow Samba}} as root.<br />
<br />
===== firewalld service =====<br />
<br />
To configure [[firewalld]] to allow Samba in the '''home''' zone, run:<br />
<br />
# firewall-cmd --permanent --add-service={samba,samba-client,samba-dc} --zone=home<br />
<br />
The three service listed are:<br />
<br />
* {{ic|samba}}: for sharing files with others.<br />
* {{ic|samba-client}}: to browse shares on other machines on the network.<br />
* {{ic|samba-dc}}: for [[Samba/Active Directory domain controller]].<br />
<br />
{{ic|--permanent}} ensures the changes remain after {{ic|firewalld.service}} is [[restart]]ed.<br />
<br />
=== Usage ===<br />
<br />
==== User management ====<br />
<br />
===== Adding a user =====<br />
<br />
Samba requires a Linux user account - you may use an existing user account or create a [[Users and groups#User management|new one]].<br />
<br />
{{Note|The [[user]]/[[user group]] ''nobody'' should already exist on the system, it's used as the default {{ic|guest account}} and may be used for shares containing {{ic|1=guest ok = yes}}, thus preventing the need of user login on that share.}}<br />
<br />
Although the user name is shared with Linux system, Samba uses a password separate from that of the Linux user accounts. Replace {{ic|samba_user}} with the chosen Samba user account:<br />
<br />
# smbpasswd -a ''samba_user''<br />
<br />
Depending on the [https://www.samba.org/samba/docs/man/manpages-3/smb.conf.5.html#SERVERROLE server role], existing [[File permissions and attributes]] may need to be altered for the Samba user account.<br />
<br />
If you want the new user only to be allowed to remotely access the file server shares through Samba, you can restrict other login options:<br />
<br />
* disabling shell - {{ic|usermod --shell /usr/bin/nologin --lock ''samba_user''}}<br />
* disabling SSH logons - edit {{ic|/etc/ssh/sshd_config}}, change option {{ic|AllowUsers}}<br />
<br />
Also see [[Security]] for hardening your system.<br />
<br />
===== Listing users =====<br />
<br />
Samba users can be listed using the {{man|8|pdbedit}} command:<br />
<br />
# pdbedit -L -v<br />
<br />
===== Changing user password =====<br />
<br />
To change a user password, use {{ic|smbpasswd}}:<br />
<br />
# smbpasswd ''samba_user''<br />
<br />
==== Creating an anonymous share ====<br />
<br />
1. Create a Linux user which anonymous Samba users will be mapped to.<br />
<br />
# useradd guest -s /bin/nologin<br />
<br />
{{Note|The username can be any valid Linux username, not just "guest". This user does not need to be a Samba user.}}<br />
<br />
2. Add the following to {{ic|/etc/samba/smb.conf}}:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
[global]<br />
security = user<br />
map to guest = bad user<br />
guest account = guest<br />
<br />
[guest]<br />
comment = guest<br />
path = /tmp/<br />
public = yes<br />
only guest = yes<br />
writable = yes<br />
printable = no<br />
}}<br />
<br />
Any anonymous users will now be mapped to the Linux user {{ic|guest}} and have the ability to access any directories defined in {{ic|guest.path}}, for example, {{ic|/tmp/}} in the configuration above.<br />
<br />
Make sure shares have been properly defined as per the ''Share Definitions'' section of [https://git.samba.org/samba.git/?p=samba.git;a=blob_plain;f=examples/smb.conf.default;hb=HEAD smb.conf.default].<br />
<br />
=== Enable symlink following ===<br />
<br />
{{Warning|Enabling the {{ic|follow symlinks}} option can be a security risk.}}<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
[global]<br />
follow symlinks = yes<br />
wide links = yes<br />
unix extensions = no<br />
}}<br />
<br />
Then, [[restart]] {{ic|smb.service}}.<br />
<br />
{{Note|When using [[AppArmor]], if the symlink points to a directory outside the user's home or the [[#Enable Usershares|usershare]] directory, then you need to [[#Permission issues on AppArmor|modify the AppArmor profile permissions]].}}<br />
<br />
=== Advanced Configuration ===<br />
<br />
==== Enable Usershares ====<br />
<br />
{{Note|This is an optional feature. Skip this section if you do not need it.}}<br />
<br />
[https://www.samba.org/samba/docs/current/man-html/smb.conf.5.html Usershares]<br />
is a feature that gives non-root users the capability to add, modify, and delete their own share definitions. <br />
<br />
# Create a directory for usershares: {{bc|# mkdir /var/lib/samba/usershares}}<br />
# Create a [[user group]]: {{bc|# groupadd -r sambashare}}<br />
# Change the owner of the directory to {{ic|root}} and the group to {{ic|sambashare}}: {{bc|# chown root:sambashare /var/lib/samba/usershares}}<br />
# Change the permissions of the {{ic|usershares}} directory so that users in the group {{ic|sambashare}} can read, write and execute files: {{bc|# chmod 1770 /var/lib/samba/usershares}}<br />
<br />
Set the following parameters in the {{ic|smb.conf}} configuration file: <br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
usershare path = /var/lib/samba/usershares<br />
usershare max shares = 100<br />
usershare allow guests = yes<br />
usershare owner only = yes<br />
}}<br />
<br />
Add the user to the ''sambashare'' group. Replace {{ic|''your_username''}} with the name of your user:<br />
<br />
# gpasswd sambashare -a ''your_username''<br />
<br />
[[Restart]] {{ic|smb.service}} and {{ic|nmb.service}} services.<br />
<br />
Log out and log back in.<br />
<br />
If you want to share paths inside your home directory you must make it accessible for the group ''others''.<br />
<br />
In the GUI, for example in [[Thunar]], you can right click on any directory and share it on the network. <br />
<br />
In the CLI, use one of the following commands, replacing italic ''sharename'', ''user'', ... :<br />
<br />
# net usershare add ''sharename'' ''abspath'' [''comment''] [''user'':{R|D|F}] [guest_ok={y|n}]<br />
# net usershare delete ''sharename''<br />
# net usershare list ''wildcard-sharename''<br />
# net usershare info ''wildcard-sharename''<br />
<br />
==== Set and forcing permissions ====<br />
<br />
Permissions may be applied to both the server and shares:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
;inherit owner = unix only ; Inherit ownership of the parent directory for new files and directories<br />
;inherit permissions = yes ; Inherit permissions of the parent directory for new files and directories<br />
create mask = 0664<br />
directory mask = 2755<br />
force create mode = 0644<br />
force directory mode = 2755<br />
...<br />
<br />
[media]<br />
comment = Media share accessible by ''greg'' and ''pcusers''<br />
path = ''/path/to/media''<br />
valid users = ''greg @pcusers''<br />
force group = ''+pcusers''<br />
public = no<br />
writable = yes<br />
create mask = 0664<br />
directory mask = 2775<br />
force create mode = 0664<br />
force directory mode = 2775<br />
<br />
[public]<br />
comment = Public share where ''archie'' has write access<br />
path = ''/path/to/public''<br />
public = yes<br />
read only = yes<br />
write list = ''archie''<br />
printable = no<br />
<br />
[guests]<br />
comment = Allow all users to read/write<br />
path = ''/path/to/guests''<br />
public = yes<br />
only guest = yes<br />
writable = yes<br />
printable = no<br />
}}<br />
<br />
See {{man|5|smb.conf}} for a full overview of possible permission flags and settings.<br />
<br />
==== Restrict protocols for better security ====<br />
<br />
{{Warning|By default, Samba versions prior to 4.11 allow connections using the outdated and insecure SMB1 protocol. When using one these Samba versions, it is highly recommended to set {{ic|1=server min protocol = SMB2_02}} to protect yourself from ransomware attacks. In Samba 4.11 and newer, SMB2 is the default min protocol, so no changes are required there.}}<br />
<br />
[[Append]] {{ic|server min protocol}} and {{ic|server max protocol}} in {{ic|/etc/samba/smb.conf}} to force usage of a minimum and maximum protocol:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
server min protocol = SMB2_02<br />
; server max protocol = SMB3<br />
}}<br />
<br />
See {{ic|server max protocol}} in {{man|5|smb.conf}} for an overview of supported protocols.<br />
<br />
For compatibility with older clients and/or servers, you might need to set {{ic|1=client min protocol = CORE}} or {{ic|1=server min protocol = CORE}}, but please note that this makes you vulnerable to exploits in SMB1 including ransomware attacks.<br />
<br />
{{Tip|Use {{ic|1=server min protocol = SMB3_00}} when clients should only connect using the latest SMB3 protocol, e.g. on clients running Windows 8 and later.}}<br />
<br />
[[#Manual mounting|Clients]] using {{ic|mount.cifs}} may need to specify the correct {{ic|1=vers=*}}, e.g.:<br />
<br />
# mount -t cifs //''SERVER''/''sharename'' /mnt/''mountpoint'' -o username=''username'',password=''password'',iocharset=''utf8'',vers=''3.1.1''<br />
<br />
See {{man|8|mount.cifs}} for more information.<br />
<br />
==== Use native SMB transport encryption ====<br />
<br />
Native SMB transport encryption is available in SMB version 3.0 or newer. Clients supporting this type of encryption include Windows 8 and newer, Windows server 2012 and newer, and smbclient of Samba 4.1 and newer.<br />
<br />
To use native SMB transport encryption by default, set the {{ic|server smb encrypt}} parameter globally and/or by share. Possible values are {{ic|off}}, {{ic|enabled}} (default value), {{ic|desired}}, or {{ic|required}}:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
server smb encrypt = desired<br />
}}<br />
<br />
To configure encryption for on the client side, use the option {{ic|client smb encrypt}}.<br />
<br />
See {{man|5|smb.conf}} for more information, especially the paragraphs ''Effects for SMB1'' and ''Effects for SMB2''.<br />
<br />
{{Tip|When [[#Manual mounting|mounting]] a share, specify the {{ic|seal}} mount option to force usage of encryption.}}<br />
<br />
==== Disable printer sharing ====<br />
<br />
By default Samba shares printers configured using [[CUPS]].<br />
<br />
If you do not want printers to be shared, use the following settings:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
load printers = no<br />
printing = bsd<br />
printcap name = /dev/null<br />
disable spoolss = yes<br />
show add printer wizard = no<br />
}}<br />
<br />
==== Block certain file extensions on Samba share ====<br />
<br />
{{Note|Setting this parameter will affect the performance of Samba, as it will be forced to check all files and directories for a match as they are scanned.}}<br />
<br />
Samba offers an option to block files with certain patterns, like file extensions. This option can be used to prevent dissemination of viruses or to dissuade users from wasting space with certain files. More information about this option can be found in {{man|5|smb.conf}}.<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
[myshare]<br />
comment = Private<br />
path = /mnt/data<br />
read only = no<br />
veto files = /*.exe/*.com/*.dll/*.bat/*.vbs/*.tmp/*.mp3/*.avi/*.mp4/*.wmv/*.wma/<br />
}}<br />
<br />
==== Improve throughput ====<br />
<br />
{{Warning|Beware this may lead to corruption/connection issues and potentially cripple your TCP/IP stack.}}<br />
<br />
The default settings should be sufficient for most users. However setting the 'socket options' correct can improve performance, but getting them wrong can degrade it by just as much. Test the effect before making any large changes.<br />
<br />
Read the {{man|5|smb.conf}} man page before applying any of the options listed below.<br />
<br />
The following settings should be [[Append|appended]] to the {{ic|[global]}} section of {{ic|/etc/samba/smb.conf}}.<br />
<br />
SMB3 multi-channel may improve performance, however it may result in data corruption under some rare conditions. Future releases may improve this situation:<br />
<br />
server multi channel support = yes<br />
<br />
Setting a deadtime is useful to stop a server's resources from being exhausted by a large number of inactive connections:<br />
<br />
deadtime = 30<br />
<br />
The usage of sendfile may make more efficient use of the system CPU's and cause Samba to be faster:<br />
<br />
use sendfile = yes<br />
<br />
Setting min receivefile size allows zero-copy writes directly from network socket buffers into the filesystem buffer cache (if available). It may improve performance but user testing is recommended:<br />
<br />
min receivefile size = 16384<br />
<br />
Reading/writing files asynchronously may improve performance instead of using synchronously writes:<br />
<br />
aio read size = 1<br />
aio write size = 1<br />
<br />
Increasing the receive/send buffers size and socket optimize flags might be useful to improve throughput. It is recommended to test each flag separately as it may cause issues on some networks:<br />
<br />
socket options = IPTOS_LOWDELAY TCP_NODELAY IPTOS_THROUGHPUT SO_RCVBUF=131072 SO_SNDBUF=131072<br />
<br />
{{Note|Network-interface adjustments may be needed for some options to work, see [[Sysctl#Networking]].}}<br />
<br />
==== Enable access for old clients/devices ====<br />
<br />
Latest versions of Samba no longer offer older authentication methods and protocols which are still used by some older clients (IP cameras, etc). These devices usually require Samba server to allow NTMLv1 authentication and NT1 version of the protocol, known as CIFS. For these devices to work with latest Samba, you need to add these two configuration parameters into {{ic|[global]}} section:<br />
<br />
server min protocol = NT1<br />
ntlm auth = yes<br />
<br />
Anonymous/guest access to a share requires just the first parameter. If the old device will access with username and password, you also need the add the second line too.<br />
<br />
== Client ==<br />
<br />
Install {{Pkg|smbclient}} for an {{ic|ftp}}-like command line interface. See {{man|1|smbclient}} for commonly used commands.<br />
<br />
For a lightweight alternative (without support for listing public shares, etc.), [[install]] {{Pkg|cifs-utils}} that provides {{ic|/usr/bin/mount.cifs}}.<br />
<br />
Depending on the [[desktop environment]], GUI methods may be available. See [[#File manager configuration]] for use with a file manager.<br />
<br />
{{Note|<br />
* {{Pkg|smbclient}} requires a {{ic|/etc/samba/smb.conf}} file (see [[#Installation]]), which you can create as an empty file using the {{ic|touch}} utility.<br />
* After installing {{Pkg|cifs-utils}} or {{Pkg|smbclient}}, load the {{ic|cifs}} [[kernel module]] or reboot to prevent mount fails.<br />
}}<br />
<br />
=== List public shares ===<br />
<br />
The following command lists public shares on a server:<br />
<br />
$ smbclient -L ''hostname'' -U%<br />
<br />
Alternatively, running ''smbtree'' will show a tree diagram of all the shares. This is not advisable on a network with a lot of computers, but can be helpful for diagnosing if you have the correct sharename.<br />
<br />
$ smbtree -b -N<br />
<br />
Where the options are {{ic|-b}} ({{ic|--broadcast}}) to use broadcast instead of using the master browser and {{ic|-N}} ({{ic|-no-pass}}) to not ask for a password.<br />
<br />
=== NetBIOS/WINS host names ===<br />
<br />
You may need to [[start]] {{ic|winbind.service}} and {{ic|nmb.service}} in order to resolve host names with e.g., {{ic|mount.cifs}}<br />
{{Note|Due to a current mistake in {{ic|winbind.service}}, you may have to modify the unit file as described in this [https://bugs.launchpad.net/ubuntu/+source/samba/+bug/1789097 bug-report]}}<br />
<br />
The {{pkg|smbclient}} package provides a driver to resolve host names using WINS. To enable it, add {{ic|wins}} to the “hosts” line in {{ic|/etc/nsswitch.conf}}.<br />
<br />
If it is not already there, add it to look roughly like this:<br />
<br />
{{hc|/etc/nsswitch.conf|2=<br />
...<br />
hosts: files mymachines myhostname mdns_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] dns wins<br />
...<br />
}}<br />
<br />
You can test WINS resolution with {{ic|nmblookup}}. Note that WINS resolution requires incoming traffic originating from port 137.<br />
<br />
==== Disable NetBIOS/WINS support ====<br />
<br />
When not using NetBIOS/WINS host name resolution, it may be preferred to disable this protocol:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
disable netbios = yes<br />
dns proxy = no<br />
}}<br />
<br />
Finally [[disable]]/[[stop]] {{ic|winbind.service}}.<br />
<br />
=== Manual mounting ===<br />
<br />
Create a mount point for the share:<br />
<br />
# mkdir /mnt/''mountpoint''<br />
<br />
Mount the share using {{ic|mount.cifs}} as {{ic|type}}. Not all the options listed below are needed or desirable:<br />
<br />
# mount -t cifs //''SERVER''/''sharename'' /mnt/''mountpoint'' -o username=''username'',password=''password'',workgroup=''workgroup'',iocharset=''utf8'',uid=''username'',gid=''group''<br />
<br />
The options {{ic|uid}} and {{ic|gid}} corresponds to the local (e.g. client) [[user]]/[[user group]] to have read/write access on the given path.<br />
<br />
{{Note|<br />
* If the {{ic|uid}} and {{ic|gid}} being used does not match the user of the server, the {{ic|forceuid}} and {{ic|forcegid}} options may be helpful. However note permissions assigned to a file when {{ic|forceuid}} or {{ic|forcegid}} are in effect may not reflect the the real (server) permissions. See the ''File And Directory Ownership And Permissions'' section in {{man|8|mount.cifs|FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS}} for more information.<br />
* To allow users to mount it as long as the mount point resides in a directory controllable by the user; i.e. the user's home, append the {{ic|users}} mount option. The option is user'''s''' (plural). For other filesystem types handled by mount, this option is usually ''user''; sans the "'''s'''".<br />
* To mount a Windows share without authentication, use {{ic|1="username=*"}}.<br />
}}<br />
<br />
{{Warning|Using {{ic|uid}} and/or {{ic|gid}} as mount options may cause I/O errors, it is recommended to set/check correct [[File permissions and attributes]] instead.}}<br />
<br />
* {{ic|''SERVER''}} — The server name.<br />
* {{ic|''sharename''}} — The shared directory.<br />
* {{ic|''mountpoint''}} — The local directory where the share will be mounted.<br />
* {{ic|[-o ''options'']}} — See {{man|8|mount.cifs}} for more information.<br />
<br />
{{Note|<br />
* Abstain from using a trailing {{ic|/}}. {{ic|//''SERVER''/''sharename'''''/'''}} will not work.<br />
* If your mount does not work stable, stutters or freezes, try to enable different SMB protocol version with {{ic|1=vers=}} option. For example, {{ic|1=vers=2.0}} for Windows Vista mount.<br />
* If having timeouts on a mounted network share with cifs on a shutdown, see [[wpa_supplicant#Problem with mounted network shares (cifs) and shutdown]].<br />
}}<br />
<br />
==== Storing share passwords ====<br />
<br />
Storing passwords in a world readable file is not recommended. A safer method is to use a credentials file instead, e.g. inside {{ic|/etc/samba/credentials}}:<br />
<br />
{{hc|/etc/samba/credentials/share|2=<br />
username=''myuser''<br />
password=''mypass''<br />
}}<br />
<br />
For the mount command replace {{ic|1=username=myuser,password=mypass}} with {{ic|1=credentials=/etc/samba/credentials/share}}.<br />
<br />
The credential file should explicitly readable/writeable to root:<br />
<br />
# chown root:root /etc/samba/credentials<br />
# chmod 700 /etc/samba/credentials<br />
# chmod 600 /etc/samba/credentials/share<br />
<br />
=== Automatic mounting ===<br />
<br />
{{Note|You may need to [[enable]] {{ic|systemd-networkd-wait-online.service}} or {{ic| NetworkManager-wait-online.service}} (depending on your setup) to proper enable booting on start-up.}}<br />
<br />
==== Using NetworkManager and GIO/gvfs ====<br />
<br />
[[NetworkManager#Network services with NetworkManager dispatcher|NetworkManager]] can be configured to run a script on network status change. This script uses the ''gio'' command so that it mounts the Samba shares automatically, the same way your file manager does, as explained [[#File manager configuration|below]]. The script also safely unmounts the Samba shares before the relevant network connection is disabled by listening for the {{ic|pre-down}} and {{ic|vpn-pre-down}} events. Make the script is [[executable]] after creating it.<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/30-samba.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 />
# The user the share will be mounted under<br />
USER="yourusername"<br />
# The path that appears in your file manager when you manually mount the share you want<br />
SMB_URL="smb://servername/share"<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 />
su $USER -c "DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus gio mount $SMB_URL"<br />
;;<br />
"pre-down");&<br />
"vpn-pre-down")<br />
su $USER -c "DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus gio mount -uf $SMB_URL"<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
Create a symlink inside {{ic|/etc/NetworkManager/dispatcher.d/pre-down}} to catch the {{ic|pre-down}} events:<br />
<br />
# ln -s /etc/NetworkManager/dispatcher.d/30-samba.sh /etc/NetworkManager/dispatcher.d/pre-down.d/30-samba.sh<br />
<br />
==== As mount entry ====<br />
<br />
This is a simple example of a {{ic|cifs}} [[fstab|mount entry]] that requires authentication:<br />
<br />
{{hc|/etc/fstab|2=<br />
//''SERVER''/''sharename'' /mnt/''mountpoint'' cifs _netdev,nofail,username=''myuser'',password=''mypass'' 0 0<br />
}}<br />
<br />
{{Note|Spaces in sharename should be replaced by {{ic|\040}} (ASCII code for space in octal). For example, {{ic|//''SERVER''/share name}} on the command line should be {{ic|//''SERVER''/share\040name}} in {{ic|/etc/fstab}}.}}<br />
<br />
{{Tip|Use {{ic|x-systemd.automount}} if you want them to be mounted only upon access. See [[Fstab#Remote filesystem]] for details.}}<br />
<br />
==== As systemd unit ====<br />
<br />
Create a new {{ic|.mount}} file inside {{ic|/etc/systemd/system}}, e.g. {{ic|mnt-myshare.mount}}. See {{man|5|systemd.mount}} for details.<br />
<br />
{{Note|Make sure the filename corresponds to the mountpoint you want to use.<br />
E.g. the unit name {{ic|mnt-myshare.mount}} can only be used if are going to mount the share under {{ic|/mnt/myshare}}. Otherwise the following error might occur: {{ic|1=systemd[1]: mnt-myshare.mount: Where= setting does not match unit name. Refusing.}}.}}<br />
<br />
{{ic|1=What=}} path to share<br />
<br />
{{ic|1=Where=}} path to mount the share<br />
<br />
{{ic|1=Options=}} share mounting options<br />
<br />
{{Note|<br />
* Network mount units automatically acquire {{ic|After}} dependencies on {{ic|remote-fs-pre.target}}, {{ic|network.target}} and {{ic|network-online.target}}, and gain a {{ic|Before}} dependency on {{ic|remote-fs.target}} unless {{ic|nofail}} mount option is set. Towards the latter a {{ic|Wants}} unit is added as well.<br />
* [[Append]] {{ic|noauto}} to {{ic|Options}} preventing automatically mount during boot (unless it is pulled in by some other unit).<br />
* If you want to use a hostname for the server you want to share (instead of an IP address), add {{ic|1=nss-lookup.target}} to {{ic|1=After}}. This might avoid mount errors at boot time that do not arise when testing the unit.<br />
}} <br />
<br />
{{hc|/etc/systemd/system/mnt-myshare.mount|2=<br />
[Unit]<br />
Description=Mount Share at boot<br />
<br />
[Mount]<br />
What=//server/share<br />
Where=/mnt/myshare<br />
Options=_netdev,credentials=/etc/samba/credentials/myshare,iocharset=utf8,rw<br />
Type=cifs<br />
TimeoutSec=30<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{Tip|<br />
* In case of an unreachable system, [[append]] {{ic|1=ForceUnmount=true}} to {{ic|[Mount]}}, allowing the share to be (force-)unmounted.<br />
* If your share has groups with read-only access, [[append]] {{ic|1=uid=''username''}} or {{ic|1=gid=''group''}} to {{ic|1=Options=}}, to specify your user / group allowing writing to the share.<br />
}}<br />
<br />
To use {{ic|mnt-myshare.mount}}, [[start]] the unit and [[enable]] it to run on system boot.<br />
<br />
===== automount =====<br />
<br />
To automatically mount a share (when accessed, like autofs), one may use the following automount unit:<br />
<br />
{{hc|/etc/systemd/system/mnt-myshare.automount|2=<br />
[Unit]<br />
Description=Automount myshare<br />
<br />
[Automount]<br />
Where=/mnt/myshare<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
[[Disable]]/[[stop]] the {{ic|mnt-myshare.mount}} unit, and [[enable]]/[[start]] {{ic|mnt-myshare.automount}} to automount the share when the mount path is being accessed.<br />
<br />
{{Tip|[[Append]] {{ic|TimeoutIdleSec}} to enable auto unmount. See {{man|5|systemd.automount}} for details.}}<br />
<br />
==== smbnetfs ====<br />
<br />
{{Note|1=smbnetfs needs an intact Samba server setup.<br />
<br />
See above on how to do that.}}<br />
<br />
First, check if you can see all the shares you are interested in mounting:<br />
<br />
$ smbtree -U ''remote_user''<br />
<br />
If that does not work, find and modify the following line<br />
in {{ic|/etc/samba/smb.conf}} accordingly:<br />
<br />
domain master = auto<br />
<br />
Now [[restart]] {{ic|smb.service}} and {{ic|nmb.service}}.<br />
<br />
If everything works as expected, [[pacman#Installing specific packages|install]] {{Pkg|smbnetfs}} from the official repositories.<br />
<br />
Then, add the following line to {{ic|/etc/fuse.conf}}:<br />
<br />
user_allow_other<br />
<br />
Now copy the directory {{ic|/etc/smbnetfs/.smb}} to your home directory:<br />
<br />
$ cp -a /etc/smbnetfs/.smb ~<br />
<br />
Then create a link to {{ic|smb.conf}}:<br />
<br />
$ ln -sf /etc/samba/smb.conf ~/.smb/smb.conf<br />
<br />
If a username and a password are required to access some of the shared folders, edit {{ic|~/.smb/smbnetfs.auth}}<br />
to include one or more entries like this:<br />
<br />
{{hc|~/.smb/smbnetfs.auth|<br />
auth "hostname" "username" "password"<br />
}}<br />
<br />
It is also possible to add entries for specific hosts to be mounted by smbnetfs, if necessary.<br />
More details can be found in {{ic|~/.smb/smbnetfs.conf}}.<br />
<br />
If you are using the [[Dolphin]] or [[GNOME Files]], you may want to add the following to {{ic|~/.smb/smbnetfs.conf}} to avoid "Disk full" errors as smbnetfs by default will report 0 bytes of free space:<br />
<br />
{{hc|~/.smb/smbnetfs.conf|<br />
free_space_size 1073741824<br />
}}<br />
<br />
When you are done with the configuration, you need to run<br />
<br />
$ chmod 600 ~/.smb/smbnetfs.*<br />
<br />
Otherwise, smbnetfs complains about 'insecure config file permissions'.<br />
<br />
Finally, to mount your Samba network neighbourhood to a directory of your choice, call<br />
<br />
$ smbnetfs ''mount_point''<br />
<br />
===== Daemon =====<br />
<br />
The Arch Linux package also maintains an additional system-wide operation mode for smbnetfs. To enable it, you need to make the<br />
said modifications in the directory {{ic|/etc/smbnetfs/.smb}}.<br />
<br />
Then, you can start and/or enable the {{ic|smbnetfs}} [[daemon]] as usual. The system-wide mount point is at {{ic|/mnt/smbnet/}}.<br />
<br />
==== autofs ====<br />
<br />
See [[Autofs]] for information on the kernel-based automounter for Linux.<br />
<br />
=== File manager configuration ===<br />
<br />
==== GNOME Files, Nemo, Caja, Thunar and PCManFM ====<br />
<br />
In order to access samba shares through GNOME Files, Nemo, Caja, Thunar or PCManFM, install the {{Pkg|gvfs-smb}} package, available in the [[official repositories]].<br />
<br />
Press {{ic|Ctrl+l}} and enter {{ic|smb://''servername''/''share''}} in the location bar to access your share.<br />
<br />
The mounted share is likely to be present at {{ic|/run/user/''your_UID''/gvfs}} or {{ic|~/.gvfs}} in the filesystem.<br />
<br />
==== KDE ====<br />
<br />
KDE applications (like Dolphin) has the ability to browse Samba shares built in. Use the path {{ic|smb://''servername''/''share''}} to browse the files. If you want to access files from on non-KDE application, you can install {{Pkg|kio-fuse}}.<br />
<br />
To use a GUI in the KDE System Settings, you will need to install the {{Pkg|kdenetwork-filesharing}} package.<br />
<br />
==== Other graphical environments ====<br />
<br />
There are a number of useful programs, but they may need to have packages created for them. This can be done with the Arch package build system. The good thing about these others is that they do not require a particular environment to be installed to support them, and so they bring along less baggage.<br />
<br />
* {{AUR|pyneighborhood}} is available in the official repositories.<br />
* LinNeighborhood, RUmba, xffm-samba plugin for Xffm are not available in the official repositories or the AUR. As they are not officially (or even unofficially supported), they may be obsolete and may not work at all.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Discovering network shares ===<br />
<br />
If nothing is known about other systems on the local network, and automated tools such as [[#smbnetfs|smbnetfs]] are not available, the following methods allow one to manually probe for Samba shares.<br />
<br />
1. First, [[install]] the {{Pkg|nmap}} and {{Pkg|smbclient}} packages.<br />
<br />
2. {{ic|nmap}} checks which ports are open:<br />
<br />
# nmap -p 139 -sT "192.168.1.*"<br />
<br />
In this case, a scan on the 192.168.1.* IP address range and port 139 has been performed, resulting in:<br />
<br />
{{hc|$ nmap -sT "192.168.1.*"|<nowiki><br />
Starting nmap 3.78 ( http://www.insecure.org/nmap/ ) at 2005-02-15 11:45 PHT<br />
Interesting ports on 192.168.1.1:<br />
(The 1661 ports scanned but not shown below are in state: closed)<br />
PORT STATE SERVICE<br />
'''139/tcp open netbios-ssn'''<br />
5000/tcp open UPnP<br />
<br />
Interesting ports on 192.168.1.5:<br />
(The 1662 ports scanned but not shown below are in state: closed)<br />
PORT STATE SERVICE<br />
6000/tcp open X11<br />
<br />
Nmap run completed -- 256 IP addresses (2 hosts up) scanned in 7.255 seconds<br />
</nowiki>}}<br />
<br />
The first result is another system; the second happens to be the client from where this scan was performed.<br />
<br />
3. Now that systems with port 139 open are revealed, use {{man|1|nmblookup}} to check for NetBIOS names: <br />
<br />
{{hc|$ nmblookup -A 192.168.1.1|<br />
Looking up status of 192.168.1.1<br />
PUTER <00> - B <ACTIVE><br />
HOMENET <00> - <GROUP> B <ACTIVE><br />
PUTER <03> - B <ACTIVE><br />
'''PUTER <20> - B <ACTIVE>'''<br />
HOMENET <1e> - <GROUP> B <ACTIVE><br />
USERNAME <03> - B <ACTIVE><br />
HOMENET <1d> - B <ACTIVE><br />
MSBROWSE <01> - <GROUP> B <ACTIVE><br />
}}<br />
<br />
Regardless of the output, look for '''<20>''', which shows the host with open services.<br />
<br />
4. Use {{ic|smbclient}} to list which services are shared on ''PUTER''. If prompted for a password, pressing enter should still display the list:<br />
<br />
{{hc|$ smbclient -L \\PUTER|<nowiki><br />
Sharename Type Comment<br />
--------- ---- -------<br />
MY_MUSIC Disk<br />
SHAREDDOCS Disk<br />
PRINTER$ Disk<br />
PRINTER Printer<br />
IPC$ IPC Remote Inter Process Communication<br />
<br />
Server Comment<br />
--------- -------<br />
PUTER<br />
<br />
Workgroup Master<br />
--------- -------<br />
HOMENET PUTER<br />
</nowiki>}}<br />
<br />
=== Remote control of Windows computer ===<br />
<br />
Samba offers a set of tools for communication with Windows. These can be handy if access to a Windows computer through remote desktop is not an option, as shown by some examples.<br />
<br />
Send shutdown command with a comment:<br />
<br />
$ net rpc shutdown -C "comment" -I IPADDRESS -U USERNAME%PASSWORD<br />
<br />
A forced shutdown instead can be invoked by changing -C with comment to a single -f. For a restart, only add -r, followed by a -C or -f.<br />
<br />
Stop and start services:<br />
<br />
$ net rpc service stop SERVICENAME -I IPADDRESS -U USERNAME%PASSWORD<br />
<br />
To see all possible net rpc command:<br />
<br />
$ net rpc<br />
<br />
== Troubleshooting ==<br />
<br />
=== Failed to start Samba SMB/CIFS server ===<br />
<br />
Possible solutions:<br />
<br />
* Check {{ic|smb.conf}} on syntactic errors with {{man|1|testparm}}.<br />
* Set correct permissions for {{ic|/var/cache/samba/}} and [[restart]] {{ic|smb.service}}:<br />
<br />
# chmod 0755 /var/cache/samba/msg<br />
<br />
=== Permission issues on SELinux ===<br />
<br />
[[SELinux]] not allow samba to access user home directories by default, to solve this, run:<br />
<br />
# setsebool -P samba_enable_home_dirs 1<br />
<br />
Similarly, {{ic|samba_export_all_ro}} and {{ic|samba_export_all_rw}} make [[Samba]] has the ability to read or "read and write" all files.<br />
<br />
=== Permission issues on AppArmor ===<br />
<br />
If using a [[#Creating an anonymous share|share path]] located outside of a home or usershares directory, whitelist it in {{ic|/etc/apparmor.d/local/usr.sbin.smbd}}. E.g.:<br />
<br />
{{hc|/etc/apparmor.d/local/usr.sbin.smbd|<br />
"/data/" rk,<br />
"/data/**" lrwk,<br />
}}<br />
<br />
=== No dialect specified on mount ===<br />
<br />
The client is using an unsupported SMB/CIFS version that is required by the server.<br />
<br />
See [[#Restrict protocols for better security]] for more information.<br />
<br />
=== Unable to overwrite files, permissions errors ===<br />
<br />
{{Accuracy|An user should set/check for server/client permissions, instead of using incorrect/possible insecure flags.}}<br />
<br />
Possible solutions:<br />
<br />
* Append the mount option {{ic|nodfs}} to the {{ic|/etc/fstab}} [[#As mount entry|entry]].<br />
* Add {{ic|1=msdfs root = no}} to the {{ic|[global]}} section of the server's {{ic|/etc/samba/smb.conf}}.<br />
<br />
=== Windows clients keep asking for password even if Samba shares are created with guest permissions ===<br />
<br />
Set {{ic|map to guest}} inside the {{ic|global}} section of {{ic|/etc/samba/smb.conf}}:<br />
<br />
map to guest = Bad User<br />
<br />
From Samba 4.10.10 you should use {{ic|Bad Password}} instead {{ic|Bad User}}.<br />
<br />
=== Windows 7 connectivity problems - mount error(12): cannot allocate memory ===<br />
<br />
A known Windows 7 bug that causes "mount error(12): cannot allocate memory" on an otherwise perfect cifs share on the Linux end can be fixed by setting a few registry keys on the Windows box as follows:<br />
<br />
* {{ic|HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\LargeSystemCache}} (set to {{ic|1}})<br />
* {{ic|HKLM\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters\Size}} (set to {{ic|3}})<br />
<br />
Alternatively, start Command Prompt in Admin Mode and execute the following:<br />
<br />
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management" /v "LargeSystemCache" /t REG_DWORD /d 1 /f<br />
reg add "HKLM\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters" /v "Size" /t REG_DWORD /d 3 /f<br />
<br />
Do one of the following for the settings to take effect:<br />
<br />
* Restart Windows<br />
* Restart the Server service via services.msc<br />
* From the Command Prompt run: 'net stop lanmanserver' and 'net start lanmanserver' - The server may automatically restart after stopping it.<br />
<br />
{{Note|Googling will reveal another tweak recommending users to add a key modifying the "IRPStackSize" size. This is incorrect for fixing this issue under Windows 7. Do not attempt it.}}<br />
<br />
[https://web.archive.org/web/20150819153712/http://alan.lamielle.net/2009/09/03/windows-7-nonpaged-pool-srv-error-2017/ Original article].<br />
<br />
=== Windows 10 1709 and up connectivity problems - "Windows cannot access" 0x80004005 ===<br />
<br />
This error affects some machines running Windows 10 version 1709 and later. It is not related to SMB1 being disabled in this version but to the fact that Microsoft disabled insecure logons for guests on this version for some, but not others.<br />
<br />
To fix, open Group Policy Editor ({{ic|gpedit.msc}}). Navigate to ''Computer configuration\administrative templates\network\Lanman Workstation > Enable insecure guest logons'' and enable it.<br />
Alternatively,change the following value in the registry:<br />
<br />
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters]<br />
"AllowInsecureGuestAuth"=dword:1<br />
<br />
=== Error: Failed to retrieve printer list: NT_STATUS_UNSUCCESSFUL ===<br />
<br />
If you are a home user and using samba purely for file sharing from a server or NAS, you are probably not interested in sharing printers through it. If so, you can prevent this error from occurring by adding the following lines to your {{ic|/etc/samba/smb.conf}}:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
load printers = No<br />
printing = bsd<br />
printcap name = /dev/null<br />
disable spoolss = Yes<br />
}}<br />
<br />
[[Restart]] the samba service, {{ic|smb.service}}, and then check your logs:<br />
<br />
# cat /var/log/samba/smbd.log<br />
<br />
and the error should now no longer be appearing.<br />
<br />
=== Sharing a folder fails ===<br />
<br />
It means that while you are sharing a folder from ''Dolphin'' (file manager) and everything seems ok at first, after restarting ''Dolphin'' the share icon is gone from the shared folder, and also some output like this in terminal (''Konsole'') output:<br />
<br />
‘net usershare’ returned error 255: net usershare: usershares are currently disabled<br />
<br />
To fix it, enable usershare as described in [[#Enable Usershares]].<br />
<br />
=== "Browsing" network fails with "Failed to retrieve share list from server" ===<br />
<br />
And you are using a firewall (iptables) because you do not trust your local (school, university, hotel) network. This may be due to the following: When the smbclient is browsing the local network it sends out a broadcast request on udp port 137. The servers on the network then reply to your client but as the source address of this reply is different from the destination address iptables saw when sending the request for the listing out, iptables will not recognize the reply as being "ESTABLISHED" or "RELATED", and hence the packet is dropped. A possible solution is to add:<br />
<br />
iptables -t raw -A OUTPUT -p udp -m udp --dport 137 -j CT --helper netbios-ns<br />
<br />
to your iptables setup.<br />
<br />
For [[Uncomplicated Firewall]], you need to add {{ic|nf_conntrack_netbios_ns}} to the end of the following line in {{ic|/etc/default/ufw}}<br />
<br />
IPT_MODULES="nf_conntrack_ftp nf_nat_ftp nf_conntrack_irc nf_nat_irc"<br />
<br />
and then run the following commands as root:<br />
<br />
echo 1 > /proc/sys/net/netfilter/nf_conntrack_helper<br />
ufw allow CIFS<br />
ufw reload<br />
<br />
To make this change persistent across reboots, add the following line at the end of {{ic|/etc/ufw/sysctl.conf}}:<br />
<br />
net.netfilter.nf_conntrack_helper=1<br />
<br />
=== Protocol negotiation failed: NT_STATUS_INVALID_NETWORK_RESPONSE ===<br />
<br />
The client probably does not have access to shares. Make sure clients' IP address is in {{ic|1=hosts allow =}} line in {{ic|/etc/samba/smb.conf}}.<br />
<br />
Another problem could be, that the client uses an invalid protocol version. To check this try to connect with the {{ic|smbclient}} where you specify the maximum protocol version manually:<br />
<br />
$ smbclient -U <user name> -L //<server name> -m <protocol version: e. g. SMB2> -W <domain name><br />
<br />
If the command was successful then create a configuration file:<br />
<br />
{{hc|~/.smb/smb.conf|output=<br />
[global]<br />
workgroup = <domain name><br />
client max protocol = SMB2<br />
}}<br />
<br />
=== Connection to SERVER failed: (Error NT_STATUS_UNSUCCESSFUL) ===<br />
<br />
You are probably passing a wrong server name to {{ic|smbclient}}. To find out the server name, run {{ic|hostnamectl}} on the server and look at "Transient hostname" line<br />
<br />
=== Connection to SERVER failed: (Error NT_STATUS_CONNECTION_REFUSED) ===<br />
<br />
Make sure that the server has started. The shared directories should exist and be accessible.<br />
<br />
=== Protocol negotiation failed: NT_STATUS_CONNECTION_RESET ===<br />
<br />
Probably the server is configured not to accept protocol SMB1. Add option {{ic|1=client max protocol = SMB2}} in {{ic|/etc/samba/smb.conf}}.<br />
Or just pass argument {{ic|-m SMB2}} to {{ic|smbclient}}.<br />
<br />
=== Password Error when correct credentials are given (error 1326) ===<br />
<br />
[https://www.samba.org/samba/history/samba-4.5.0.html Samba 4.5] has NTLMv1 authentication disabled by default. It is recommend to install the latest available upgrades on clients and deny access for unsupported clients.<br />
<br />
If you still need support for very old clients without NTLMv2 support (e.g. Windows XP), it is possible force enable NTLMv1, although this is '''not recommend''' for security reasons:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
lanman auth = yes<br />
ntlm auth = yes<br />
}}<br />
<br />
If NTLMv2 clients are unable to authenticate when NTLMv1 has been enabled, create the following file on the client:<br />
{{hc|/home/user/.smb/smb.conf|2=<br />
[global]<br />
sec = ntlmv2<br />
client ntlmv2 auth = yes<br />
}}<br />
<br />
This change also affects samba shares mounted with '''mount.cifs'''. If after upgrade to Samba 4.5 your mount fails, add the '''sec=ntlmssp''' option to your mount command, e.g.<br />
<br />
mount.cifs //server/share /mnt/point -o sec=ntlmssp,...<br />
<br />
See the {{man|8|mount.cifs}} man page: '''ntlmssp''' - Use NTLMv2 password hashing encapsulated in Raw NTLMSSP message. The default in mainline kernel versions prior to v3.8 was '''sec=ntlm'''. In v3.8, the default was changed to '''sec=ntlmssp'''.<br />
<br />
=== Mapping reserved Windows characters ===<br />
<br />
Starting with kernel 3.18, the cifs module uses the [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=2baa2682531ff02928e2d3904800696d9e7193db "mapposix" option by default].<br />
When mounting a share using unix extensions and a default Samba configuration, files and directories containing one of the seven reserved Windows characters {{ic|: \ * < > ? |}} are listed but cannot be accessed.<br />
<br />
Possible solutions are:<br />
<br />
* Use the undocumented {{ic|nomapposix}} mount option for cifs<br />
<br />
# mount.cifs //server/share /mnt/point -o nomapposix<br />
<br />
* Configure Samba to remap {{ic|mapposix}} ("SFM", Services for Mac) style characters to the correct native ones using [https://www.mankier.com/8/vfs_fruit fruit]<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
vfs objects = catia fruit<br />
fruit:encoding = native<br />
}}<br />
<br />
* Manually remap forbidden characters using [https://www.mankier.com/8/vfs_catia catia]<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
vfs objects = catia<br />
catia:mappings = 0x22:0xf022, 0x2a:0xf02a, 0x2f:0xf02f, 0x3a:0xf03a, 0x3c:0xf03c, 0x3e:0xf03e, 0x3f:0xf03f, 0x5c:0xf05c, 0x7c:0xf07c, 0x20:0xf020<br />
}}<br />
<br />
The latter approach (using catia or fruit) has the drawback of filtering files with unprintable characters.<br />
<br />
=== Folder shared inside graphical environment is not available to guests ===<br />
<br />
This section presupposes:<br />
<br />
# Usershares are configured following [[#Enable Usershares|previous section]]<br />
# A shared folder has been created as a non-root user from GUI<br />
# Guests access has been set to shared folder during creation<br />
# Samba service has been restarted at least once since last {{ic|/etc/samba/smb.conf}} file modification<br />
<br />
For clarification purpose only, in the following sub-sections is assumed:<br />
<br />
* Shared folder is located inside user home directory path ({{ic|/home/yourUser/Shared}})<br />
* Shared folder name is ''MySharedFiles''<br />
* Guest access is read-only.<br />
* Windows users will access shared folder content without login prompt<br />
<br />
==== Verify correct samba configuration ====<br />
<br />
Run the following command from a terminal to test configuration file correctness:<br />
<br />
$ testparm<br />
<br />
==== Verify correct shared folder creation ====<br />
<br />
Run the following commands from a terminal:<br />
<br />
$ cd /var/lib/samba/usershare<br />
$ ls<br />
<br />
If everything is fine, you will notice a file named {{ic|mysharedfiles}}<br />
<br />
Read the file contents using the following command:<br />
<br />
$ cat mysharedfiles<br />
<br />
The terminal output should display something like this:<br />
<br />
{{hc|/var/lib/samba/usershare/mysharedfiles|2=<br />
path=/home/yourUser/Shared<br />
comment=<br />
usershare_acl=S-1-1-0:r<br />
guest_ok=y<br />
sharename=MySharedFiles<br />
}}<br />
<br />
==== Verify folder access by guest ====<br />
<br />
Run the following command from a terminal. If prompted for a password, just press Enter:<br />
<br />
$ smbclient -L localhost<br />
<br />
If everything is fine, MySharedFiles should be displayed under {{ic|Sharename}} column<br />
<br />
Run the following command in order to access the shared folder as guest (anonymous login)<br />
<br />
$ smbclient -N //localhost/MySharedFiles<br />
<br />
If everything is fine samba client prompt will be displayed:<br />
<br />
smb: \><br />
<br />
From samba prompt verify guest can list directory contents:<br />
<br />
smb: \> ls<br />
<br />
If the {{ic|NTFS_STATUS_ACCESS_DENIED}} error is displayed, the issue is likely to be with Unix directory permissions. Ensure that your samba user has access to the folder and all parent folders. You can test this by sudoing to the user and attempting to list the mount directory, and all of its parents.<br />
<br />
=== Mount error: Host is down ===<br />
<br />
This error might be seen when mounting shares of Synology NAS servers. Use the mount option {{ic|1=vers=1.0}} to solve it.<br />
<br />
{{Note|SMB version 1 is known to have security vulnerabilities and was used in successful ransomware attacks.}}<br />
<br />
=== Software caused connection abort ===<br />
<br />
File managers that utilizes {{Pkg|gvfs-smb}} can show the error {{ic|Software caused connection abort}} when writing a file to a share/server. This may be due to the server running SMB/CIFS version 1, which many routers use for USB drive sharing (e.g. Belkin routers). To write to these shares specify the CIFS version with the option {{ic|1=vers=1.0}}. E.g.:<br />
<br />
{{hc|/etc/fstab|2=<br />
//SERVER/sharename /mnt/mountpoint cifs _netdev,guest,file_mode=0777,dir_mode=0777,vers=1.0 0 0<br />
}}<br />
<br />
This can also happen after updating Samba to version 4.11, which deactivates SMB1 as default, and accessing any Samba share. You can reenable it by adding<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
[global]<br />
client min protocol = CORE<br />
}}<br />
<br />
=== Connection problem (due to authentification error) ===<br />
<br />
Be sure that you do not leave any space characters before your username in Samba client configuration file as follows:<br />
<br />
{{hc|~/.samba|2=<br />
username= user<br />
password=pass<br />
}}<br />
<br />
The correct format is:<br />
<br />
{{hc|~/.samba|2=<br />
username=user<br />
password=pass<br />
}}<br />
<br />
=== Windows 1709 or up does not discover the samba server in Network view ===<br />
<br />
With Windows 10 version 1511, support for SMBv1 and thus NetBIOS device discovery was disabled by default. Depending on the actual edition, later versions of Windows starting from version 1709 ("Fall Creators Update") do not allow the installation of the SMBv1 client anymore. This causes hosts running Samba not to be listed in the Explorer's "Network (Neighborhood)" views. While there is no connectivity problem and Samba will still run fine, users might want to have their Samba hosts to be listed by Windows automatically. {{AUR|wsdd}} implements a Web Service Discovery host daemon. This enables (Samba) hosts, like your local NAS device, to be found by Web Service Discovery Clients like Windows. After the installation, no configuration is needed. You just need to start and enable {{ic|wsdd.service}}<br />
<br />
== See also ==<br />
<br />
* [https://www.samba.org/ Official website]<br />
* [https://www.samba.org/samba/docs/SambaIntro.html Samba: An Introduction]<br />
* [https://www.samba.org/samba/docs/Samba-HOWTO-Collection.pdf Samba 3.2.x HOWTO and Reference Guide] (outdated but still most extensive documentation)<br />
* [[Wikipedia:Samba (software)|Wikipedia]]<br />
* [[Gentoo:Samba/Guide]]<br />
* [[Debian:Samba/ServerSimple]]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Systemd-nspawn&diff=687640Systemd-nspawn2021-07-11T20:22:49Z<p>Pgoetz: Fix link to non-existent wiki page and removed dangling text from link</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Virtualization]]<br />
[[Category:Sandboxing]]<br />
[[es:Systemd-nspawn]]<br />
[[ja:Systemd-nspawn]]<br />
[[zh-hans:Systemd-nspawn]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|Linux Containers}}<br />
{{Related|systemd-networkd}}<br />
{{Related|Docker}}<br />
{{Related|Lxc-systemd}}<br />
{{Related articles end}}<br />
<br />
''systemd-nspawn'' is like the [[chroot]] command, but it is a ''chroot on steroids''.<br />
<br />
''systemd-nspawn'' may be used to run a command or OS in a light-weight namespace container. It is more powerful than [[chroot]] since it fully virtualizes the file system hierarchy, as well as the process tree, the various IPC subsystems and the host and domain name.<br />
<br />
''systemd-nspawn'' limits access to various kernel interfaces in the container to read-only, such as {{ic|/sys}}, {{ic|/proc/sys}} or {{ic|/sys/fs/selinux}}. Network interfaces and the system clock may not be changed from within the container. Device nodes may not be created. The host system cannot be rebooted and kernel modules may not be loaded from within the container.<br />
<br />
''systemd-nspawn'' is a simpler tool to configure than [[LXC]] or [[Libvirt]].<br />
<br />
== Installation ==<br />
<br />
''systemd-nspawn'' is part of and packaged with {{Pkg|systemd}}.<br />
<br />
== Examples ==<br />
<br />
=== Create and boot a minimal Arch Linux container ===<br />
<br />
First install {{Pkg|arch-install-scripts}}.<br />
<br />
Next, create a directory to hold the container. In this example we will use {{ic|~/MyContainer}}. <br />
<br />
Next, we use ''pacstrap'' to install a basic Arch system into the container. At minimum we need to install the {{Pkg|base}} package. <br />
<br />
# pacstrap -c ~/MyContainer base ''[additional packages/groups]''<br />
<br />
{{Tip|The {{Pkg|base}} package does not depend on the {{Pkg|linux}} kernel package and is container-ready.}}<br />
<br />
Once your installation is finished, chroot into the container, and set a root password:<br />
<br />
# systemd-nspawn -D ~/MyContainer<br />
# passwd<br />
# logout<br />
<br />
Finally, boot into the container:<br />
<br />
# systemd-nspawn -b -D ~/MyContainer<br />
<br />
The {{ic|-b}} option will boot the container (i.e. run {{ic|systemd}} as PID=1), instead of just running a shell, and {{ic|-D}} specifies the directory that becomes the container's root directory.<br />
<br />
After the container starts, log in as "root" with your password.<br />
<br />
{{Note|If the login fails with "Login incorrect", the problem is likely the {{ic|securetty}} TTY device whitelist. See [[#Root login fails]].}}<br />
<br />
The container can be powered off by running {{ic|poweroff}} from within the container. From the host, containers can be controlled by the [[#machinectl|machinectl]] tool.<br />
<br />
{{Note|To terminate the ''session'' from within the container, hold {{ic|Ctrl}} and rapidly press {{ic|]}} three times. Non-US keyboard users should use {{ic|%}} instead of {{ic|]}}.}}<br />
<br />
=== Create a Debian or Ubuntu environment ===<br />
<br />
Install {{Pkg|debootstrap}}, and one or both of {{Pkg|debian-archive-keyring}} and {{Pkg|ubuntu-keyring}} depending on which distribution you want.<br />
<br />
{{Note|''systemd-nspawn'' requires that the operating system in the container uses ''systemd'' init (has it running as PID 1) and ''systemd-nspawn'' is installed in the container. Make sure that the ''systemd-container'' package is installed on the container system.}}<br />
<br />
From there it is rather easy to set up Debian or Ubuntu environments:<br />
<br />
# cd /var/lib/machines<br />
# debootstrap --include=systemd-container --components=main,universe ''codename'' ''container-name'' ''repository-url''<br />
<br />
For Debian valid code names are either the rolling names like "stable" and "testing" or release names like "stretch" and "sid", for Ubuntu the code name like "xenial" or "zesty" should be used. A complete list of code names is in {{ic|/usr/share/debootstrap/scripts}}. In case of a Debian image the "repository-url" can be https://deb.debian.org/debian/. For an Ubuntu image, the "repository-url" can be http://archive.ubuntu.com/ubuntu/. "repository-url" should ''not'' contain a trailing slash.<br />
<br />
Just like Arch, Debian and Ubuntu will not let you log in without a password. To set the root password, run ''systemd-nspawn'' without the {{ic|-b}} option:<br />
<br />
# cd /var/lib/machines<br />
# systemd-nspawn -D ./''container-name''<br />
# passwd<br />
# logout<br />
<br />
=== Build and test packages ===<br />
<br />
See [[Creating packages for other distributions]] for example uses.<br />
<br />
== Management ==<br />
<br />
Containers located in {{ic|/var/lib/machines/}} can be controlled by the ''machinectl'' command, which internally controls instances of the {{ic|systemd-nspawn@.service}} unit. The subdirectories in {{ic|/var/lib/machines/}} correspond to the container names, i.e. {{ic|/var/lib/machines/''container-name''/}}.<br />
<br />
{{Note|If the container cannot be moved into {{ic|/var/lib/machines/}} for some reason, it can be symlinked. See {{man|1|machinectl|FILES AND DIRECTORIES}} for details.}}<br />
<br />
=== Default systemd-nspawn options ===<br />
<br />
It is important to realize that containers started via ''machinectl'' or {{ic|systemd-nspawn@.service}} use different default options than containers started manually by the ''systemd-nspawn'' command. The extra options used by the service are:<br />
<br />
* {{ic|-b}}/{{ic|--boot}} – Managed containers automatically search for an init program and invoke it as PID 1.<br />
* {{ic|--network-veth}} which implies {{ic|--private-network}} – Managed containers get a virtual network interface and are disconnected from the host network. See [[#Networking]] for details.<br />
* {{ic|-U}} – Managed containers use the {{man|7|user_namespaces}} feature by default if supported by the kernel. See [[#Unprivileged containers]] for implications.<br />
* {{ic|1=--link-journal=try-guest}}<br />
<br />
The behaviour can be overridden in per-container configuration files, see [[#Configuration]] for details.<br />
<br />
=== machinectl ===<br />
<br />
{{Note|The ''machinectl'' tool requires [[systemd]] and {{Pkg|dbus}} to be installed in the container. See [https://github.com/systemd/systemd/issues/685] for detailed discussion.}}<br />
<br />
Containers can be managed by the {{ic|machinectl ''subcommand'' ''container-name''}} command. For example, to start a container:<br />
<br />
$ machinectl start ''container-name''<br />
<br />
Similarly, there are subcommands such as {{ic|poweroff}}, {{ic|reboot}}, {{ic|status}} and {{ic|show}}. See {{man|1|machinectl|Machine Commands}} for detailed explanations.<br />
<br />
{{Tip|Poweroff and reboot operations can be performed from within the container using the {{ic|poweroff}} and {{ic|reboot}} commands.}}<br />
<br />
Other common commands are:<br />
<br />
* {{ic|machinectl list}} – show a list of currently running containers<br />
* {{ic|machinectl login ''container-name''}} – open an interactive login session in a container<br />
* {{ic|machinectl shell ''[username@]container-name''}} – open an interactive shell session in a container (this immediately invokes a user process without going through the login process in the container)<br />
* {{ic|machinectl enable ''container-name''}} and {{ic|machinectl disable ''container-name''}} – enable or disable a container to start at boot, see [[#Enable container to start at boot]] for details<br />
<br />
''machinectl'' also has subcommands for managing container (or virtual machine) images and image transfers. See {{man|1|machinectl|Image Commands}} and {{man|1|machinectl|Image Transfer Commands}} for details.<br />
<br />
{{Expansion|Add some explicit examples how to use the image transfer commands. Most importantly, where to find suitable images.}}<br />
<br />
=== systemd toolchain ===<br />
<br />
Much of the core systemd toolchain has been updated to work with containers. Tools that do usually provide a {{ic|1=-M, --machine=}} option which will take a container name as argument.<br />
<br />
Examples:<br />
<br />
See journal logs for a particular machine:<br />
<br />
# journalctl -M ''container-name''<br />
<br />
Show control group contents:<br />
<br />
$ systemd-cgls -M ''container-name''<br />
<br />
See startup time of container:<br />
<br />
$ systemd-analyze -M ''container-name''<br />
<br />
For an overview of resource usage:<br />
<br />
$ systemd-cgtop<br />
<br />
== Configuration ==<br />
<br />
=== Per-container settings ===<br />
<br />
To specify per-container settings and not global overrides, the ''.nspawn'' files can be used. See {{man|5|systemd.nspawn}} for details.<br />
<br />
{{Note|<br />
* ''.nspawn'' files may be removed unexpectedly from {{ic|/etc/systemd/nspawn/}} when you run {{ic|machinectl remove}}. [https://github.com/systemd/systemd/issues/15900]<br />
* The interaction of network options specified in the ''.nspawn'' file and on the command line does not work correctly when there is {{ic|1=--settings=override}} (which is specified in the {{ic|systemd-nspawn@.service}} file). [https://github.com/systemd/systemd/issues/12313#issuecomment-681116926] As a workaround, you need to include the option {{ic|1=VirtualEthernet=on}}, even though the service specifies {{ic|1=--network-veth}}.<br />
}}<br />
<br />
=== Enable container to start at boot ===<br />
<br />
When using a container frequently, you may want to start it at boot.<br />
<br />
First make sure that the {{ic|machines.target}} is [[enabled]].<br />
<br />
Containers discoverable by [[#machinectl|machinectl]] can be enabled or disabled:<br />
<br />
$ machinectl enable ''container-name''<br />
<br />
{{Note|<br />
* This has the effect of enabling the {{ic|systemd-nspawn@''container-name''.service}} systemd unit.<br />
* As mentioned in [[#Default systemd-nspawn options]], containers started by ''machinectl'' get a virtual Ethernet interface. To disable private networking, see [[#Use host networking]].<br />
}}<br />
<br />
=== Resource control ===<br />
<br />
You can take advantage of control groups to implement limits and resource management of your containers with {{ic|systemctl set-property}}, see {{man|5|systemd.resource-control}}. For example, you may want to limit the memory amount or CPU usage. To limit the memory consumption of your container to 2 GiB:<br />
<br />
# systemctl set-property systemd-nspawn@''container-name''.service MemoryMax=2G<br />
<br />
Or to limit the CPU time usage to roughly the equivalent of 2 cores:<br />
<br />
# systemctl set-property systemd-nspawn@''container-name''.service CPUQuota=200%<br />
<br />
This will create permanent files in {{ic|/etc/systemd/system.control/systemd-nspawn@''container-name''.service.d/}}.<br />
<br />
According to the documentation, {{ic|MemoryHigh}} is the preferred method to keep in check memory consumption, but it will not be hard-limited as is the case with {{ic|MemoryMax}}. You can use both options leaving {{ic|MemoryMax}} as the last line of defense. Also take in consideration that you will not limit the number of CPUs the container can see, but you will achieve similar results by limiting how much time the container will get at maximum, relative to the total CPU time.<br />
<br />
{{Tip|If you want these changes to be only temporary, you can pass the option {{ic|--runtime}}. You can check their results with ''systemd-cgtop''.}}<br />
<br />
=== Networking ===<br />
<br />
''systemd-nspawn'' containers can use either ''host networking'' or ''private networking'':<br />
<br />
* In the host networking mode, the container has full access to the host network. This means that the container will be able to access all network services on the host and packets coming from the container will appear to the outside network as coming from the host (i.e. sharing the same IP address).<br />
* In the private networking mode, the container is disconnected from the host's network. This makes all network interfaces unavailable to the container, with the exception of the loopback device and those explicitly assigned to the container. There is a number of different ways to set up network interfaces for the container:<br />
** an existing interface can be assigned to the container (e.g. if you have multiple Ethernet devices),<br />
** a virtual network interface associated with an existing interface (i.e. [[VLAN]] interface) can be created and assigned to the container,<br />
** a virtual Ethernet link between the host and the container can be created.<br />
: In the latter case the container's network is fully isolated (from the outside network as well as other containers) and it is up to the administrator to configure networking between the host and the containers. This typically involves creating a [[network bridge]] to connect multiple (physical or virtual) interfaces or setting up a [[Wikipedia:Network Address Translation|Network Address Translation]] between multiple interfaces.<br />
<br />
The host networking mode is suitable for ''application containers'' which do not run any networking software that would configure the interface assigned to the container. Host networking is the default mode when you run ''systemd-nspawn'' from the shell.<br />
<br />
On the other hand, the private networking mode is suitable for ''system containers'' that should be isolated from the host system. The creation of virtual Ethernet links is a very flexible tool allowing to create complex virtual networks. This is the default mode for containers started by ''machinectl'' or {{ic|systemd-nspawn@.service}}.<br />
<br />
The following subsections describe common scenarios. See {{man|1|systemd-nspawn|Networking Options}} for details about the available ''systemd-nspawn'' options.<br />
<br />
==== Use host networking ====<br />
<br />
To disable private networking and the creation of a virtual Ethernet link used by containers started with ''machinectl'', add a ''.nspawn'' file with the following option:<br />
<br />
{{hc|/etc/systemd/nspawn/''container-name''.nspawn|2=<br />
[Network]<br />
VirtualEthernet=no<br />
}}<br />
<br />
This will override the {{ic|-n}}/{{ic|--network-veth}} option used in {{ic|systemd-nspawn@.service}} and the newly started containers will use the host networking mode.<br />
<br />
==== Use a virtual Ethernet link ====<br />
<br />
If a container is started with the {{ic|-n}}/{{ic|--network-veth}} option, ''systemd-nspawn'' will create a virtual Ethernet link between the host and the container. The host side of the link will be available as a network interface named {{ic|ve-''container-name''}}. The container side of the link will be named {{ic|host0}}. Note that this option implies {{ic|--private-network}}.<br />
<br />
{{Note|<br />
* If the container name is too long, the interface name will be shortened (e.g. {{ic|ve-long-conKQGh}} instead of {{ic|ve-long-container-name}}) to fit into the [https://stackoverflow.com/a/29398765 15-characters limit]. The full name will be set as the {{ic|altname}} property of the interface (see {{man|8|ip-link}}) and can be still used to reference the interface.<br />
* When examining the interfaces with {{ic|ip link}}, interface names will be shown with a suffix, such as {{ic|ve-''container-name''@if2}} and {{ic|host0@if9}}. The {{ic|@if''N''}} is not actually part of the interface name; instead, {{ic|ip link}} appends this information to indicate which "slot" the virtual Ethernet cable connects to on the other end.<br />
: For example, a host virtual Ethernet interface shown as {{ic|ve-''foo''@if2}} is connected to the container {{ic|''foo''}}, and inside the container to the second network interface – the one shown with index 2 when running {{ic|ip link}} inside the container. Similarly, the interface named {{ic|host0@if9}} in the container is connected to the 9th network interface on the host.<br />
}}<br />
<br />
When you start the container, an IP address has to be assigned to both interfaces (on the host and in the container). If you use [[systemd-networkd]] on the host as well as in the container, this is done out-of-the-box:<br />
<br />
* the {{ic|/usr/lib/systemd/network/80-container-ve.network}} file on the host matches the {{ic|ve-''container-name''}} interface and starts a DHCP server, which assigns IP addresses to the host interface as well as the container,<br />
* the {{ic|/usr/lib/systemd/network/80-container-host0.network}} file in the container matches the {{ic|host0}} interface and starts a DHCP client, which receives an IP address from the host.<br />
<br />
If you do not use [[systemd-networkd]], you can configure static IP addresses or start a DHCP server on the host interface and a DHCP client in the container. See [[Network configuration]] for details.<br />
<br />
To give the container access to the outside network, you can configure NAT as described in [[Internet sharing#Enable NAT]]. If you use [[systemd-networkd]], this is done (partially) automatically via the {{ic|1=IPMasquerade=both}} option in {{ic|/usr/lib/systemd/network/80-container-ve.network}}. However, this issues just one [[iptables]] (or [[nftables]]) rule such as<br />
<br />
-t nat -A POSTROUTING -s 192.168.163.192/28 -j MASQUERADE<br />
<br />
The {{ic|filter}} table has to be configured manually as shown in [[Internet sharing#Enable NAT]]. You can use a wildcard to match all interfaces starting with {{ic|ve-}}:<br />
<br />
# iptables -A FORWARD -i ve-+ -o ''internet0'' -j ACCEPT<br />
<br />
{{Note|''systemd-networkd'' and ''systemd-nspawn'' can interface with [[iptables]] (using the [https://tldp.org/HOWTO/Querying-libiptc-HOWTO/whatis.html libiptc] library) as well as with [[nftables]] [https://github.com/systemd/systemd/issues/13307][https://github.com/systemd/systemd/blob/9ca34cf5a4a20d48f829b2a36824255aac29078c/NEWS#L295-L304]. In both cases IPv4 and IPv6 NAT is supported.}}<br />
<br />
{{Accuracy|Investigate if/why the following is necessary.}}<br />
<br />
Additionally, the rule {{ic|-A FORWARD -i ve-+ -o ''internet0'' -j ACCEPT}} may not work as described in [[Internet sharing#Enable NAT]]. If that is the case, try {{ic|-A FORWARD -i ve-+ -j ACCEPT}}.<br />
<br />
==== Use a network bridge ====<br />
<br />
If you have configured a [[network bridge]] on the host system, you can create a virtual Ethernet link for the container and add its host side to the network bridge. This is done with the {{ic|1=--network-bridge=''bridge-name''}} option. Note that {{ic|--network-bridge}} implies {{ic|--network-veth}}, i.e. the virtual Ethernet link is created automatically. However, the host side of the link will use the {{ic|vb-}} prefix instead of {{ic|ve-}}, so the [[systemd-networkd]] options for starting the DHCP server and IP masquerading will not be applied.<br />
<br />
The bridge management is left to the administrator. For example, the bridge can connect virtual interfaces with a physical interface, or it can connect only virtual interfaces of several containers. See [[systemd-networkd#Network bridge with DHCP]] and [[systemd-networkd#Network bridge with static IP addresses]] for example configurations using [[systemd-networkd]].<br />
<br />
There is also a {{ic|1=--network-zone=''zone-name''}} option which is similar to {{ic|--network-bridge}} but the network bridge is managed automatically by ''systemd-nspawn'' and ''systemd-networkd''. The bridge interface named {{ic|vz-''zone-name''}} is automatically created when the first container configured with {{ic|1=--network-zone=''zone-name''}} is started, and is automatically removed when the last container configured with {{ic|1=--network-zone=''zone-name''}} exits. Hence, this option makes it easy to place multiple related containers on a common virtual network. Note that {{ic|vz-*}} interfaces are managed by [[systemd-networkd]] same way as {{ic|ve-*}} interfaces using the options from the {{ic|/usr/lib/systemd/network/80-container-vz.network}} file.<br />
<br />
==== Use a "macvlan" or "ipvlan" interface ====<br />
<br />
Instead of creating a virtual Ethernet link (whose host side may or may not be added to a bridge), you can create a virtual interface on an existing physical interface (i.e. [[VLAN]] interface) and add it to the container. The virtual interface will be bridged with the underlying host interface and thus the container will be exposed to the outside network, which allows it to obtain a distinct IP address via DHCP from the same LAN as the host is connected to.<br />
<br />
''systemd-nspawn'' offers 2 options:<br />
<br />
* {{ic|1=--network-macvlan=''interface''}} – the virtual interface will have a different MAC address than the underlying physical {{ic|''interface''}} and will be named {{ic|mv-''interface''}}.<br />
* {{ic|1=--network-ipvlan=''interface''}} – the virtual interface will have the same MAC address as the underlying physical {{ic|''interface''}} and will be named {{ic|iv-''interface''}}.<br />
<br />
Both options imply {{ic|--private-network}}.<br />
<br />
==== Use an existing interface ====<br />
<br />
If the host system has multiple physical network interfaces, you can use the {{ic|1=--network-interface=''interface''}} to assign {{ic|''interface''}} to the container (and make it unavailable to the host while the container is started). Note that {{ic|--network-interface}} implies {{ic|--private-network}}.<br />
<br />
{{Note|Passing wireless network interfaces to ''systemd-nspawn'' containers is currently not supported. [https://github.com/systemd/systemd/issues/7873]}}<br />
<br />
=== Port mapping ===<br />
<br />
When private networking is enabled, individual ports on the host can be mapped to ports on the container using the {{ic|-p}}/{{ic|--port}} option or by using the {{ic|Port}} setting in an ''.nspawn'' file. This is done by issuing [[iptables]] rules to the {{ic|nat}} table, but the {{ic|FORWARD}} chain in the {{ic|filter}} table needs to be configured manually as shown in [[#Use a virtual Ethernet link]].<br />
<br />
For example, to map a TCP port 8000 on the host to the TCP port 80 in the container:<br />
<br />
{{hc|/etc/systemd/nspawn/''container-name''.nspawn|2=<br />
[Network]<br />
Port=tcp:8000:80<br />
}}<br />
<br />
{{Note|''systemd-nspawn'' explicitly excludes the {{ic|loopback}} interface when mapping ports. Hence, for the example above, {{ic|localhost:8000}} connects to the host and not to the container. Only connections to other interfaces are subjected to port mapping. See [https://github.com/systemd/systemd/issues/6106] for details.}}<br />
<br />
=== Domain name resolution ===<br />
<br />
[[Domain name resolution]] in the container can be configured by the {{ic|--resolv-conf}} option of ''systemd-nspawn'' or the corresponding option {{ic|1=ResolvConf=}} for the ''.nspawn'' files. There are many possible values which are described in {{man|1|systemd-nspawn|Integration Options}}.<br />
<br />
The default value is {{ic|auto}}, which means that:<br />
<br />
* If {{ic|--private-network}} is enabled, the {{ic|/etc/resolv.conf}} is left as it is in the container.<br />
* Otherwise, if [[systemd-resolved]] is running on the host, its stub {{ic|resolv.conf}} file is copied or bind-mounted into the container.<br />
* Otherwise, the {{ic|/etc/resolv.conf}} file is copied or bind-mounted from the host to the container.<br />
<br />
In the last two cases, the file is copied, if the container root is writeable, and bind-mounted if it is read-only.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Unprivileged containers ===<br />
<br />
''systemd-nspawn'' supports unprivileged containers, though the containers need to be booted as root.<br />
<br />
{{Style|Very little of [[Linux Containers#Enable support to run unprivileged containers (optional)]] applies to systemd-nspawn.}}<br />
<br />
{{Note|This feature requires {{man|7|user_namespaces}}, for further info see [[Linux Containers#Enable support to run unprivileged containers (optional)]].}}<br />
<br />
The easiest way to do this is to let ''systemd-nspawn'' automatically choose an unused range of UIDs/GIDs by using the {{ic|-U}} option:<br />
<br />
# systemd-nspawn -bUD ~/MyContainer<br />
<br />
If kernel supports user namespaces, the {{ic|-U}} option is equivalent to {{ic|1=--private-users=pick --private-users-chown}}. This implies that files and directories in the container are [[chown]]ed to the selected range of private UIDs/GIDs when the container starts. See {{man|1|systemd-nspawn|User Namespacing Options}} for details.<br />
<br />
{{Note|You can also specify the UID/GID range of the container manually, however, this is rarely useful.}}<br />
<br />
Once you have started a container with a private UID/GID range, you need to keep using it that way to avoid permission errors. Alternatively, it is possible to undo the effect of {{ic|--private-users-chown}} (or {{ic|-U}}) on the file system by specifying a range of IDs starting at 0:<br />
<br />
# systemd-nspawn -D ~/MyContainer --private-users=0 --private-users-chown<br />
<br />
=== Use an X environment ===<br />
<br />
{{Accuracy|The note about the systemd version at the end of this section seems to be obsolete. For me (systemd version 239) X applications also work if {{ic|/tmp/.X11-unix}} is bound rw.|section=/tmp/.X11-unix contents have to be bind-mounted as read-only - still relevant?}}<br />
<br />
See [[Xhost]] and [[Change root#Run graphical applications from chroot]].<br />
<br />
You will need to set the {{ic|DISPLAY}} environment variable inside your container session to connect to the external X server.<br />
<br />
X stores some required files in the {{ic|/tmp}} directory. In order for your container to display anything, it needs access to those files. To do so, append the {{ic|--bind-ro<nowiki>=</nowiki>/tmp/.X11-unix}} option when starting the container.<br />
<br />
{{Note|Since systemd version 235, {{ic|/tmp/.X11-unix}} contents [https://github.com/systemd/systemd/issues/7093 have to be bind-mounted as read-only], otherwise they will disappear from the filesystem. The read-only mount flag does not prevent using {{ic|connect()}} syscall on the socket. If you binded also {{ic|/run/user/1000}} then you might want to explicitly bind {{ic|/run/user/1000/bus}} as read-only to protect the dbus socket from being deleted. }}<br />
<br />
==== Avoiding xhost ====<br />
<br />
{{ic|xhost}} only provides rather coarse access rights to the X server. More fine-grained access control is possible via the {{ic|$XAUTHORITY}} file. Unfortunately, just making the {{ic|$XAUTHORITY}} file accessible in the container will not do the job:<br />
your {{ic|$XAUTHORITY}} file is specific to your host, but the container is a different host.<br />
The following trick adapted from [https://stackoverflow.com/a/25280523 stackoverflow] can be used to make your X server accept the {{ic|$XAUTHORITY}} file from an X application run inside the container:<br />
<br />
$ XAUTH=/tmp/container_xauth<br />
$ xauth nextract - "$DISPLAY" | sed -e 's/^..../ffff/' | xauth -f "$XAUTH" nmerge -<br />
# systemd-nspawn -D myContainer --bind=/tmp/.X11-unix --bind="$XAUTH" -E DISPLAY="$DISPLAY" -E XAUTHORITY="$XAUTH" --as-pid2 /usr/bin/xeyes<br />
<br />
The second line above sets the connection family to "FamilyWild", value {{ic|65535}}, which causes the entry to match every display. See {{man|7|Xsecurity}} for more information.<br />
<br />
==== Using X nesting/Xephyr ====<br />
<br />
Another simple way to run X applications and avoid the risks of a shared X desktop is using X nesting.<br />
The advantages here are avoiding interaction between in-container applications and non-container applications entirely and being able to run a different [[desktop environment]] or [[window manager]], the downsides are less performance and the lack of hardware acceleration when using [[Xephyr]].<br />
<br />
Start Xephyr outside of the container using:<br />
<br />
# Xephyr :1 -resizeable<br />
<br />
Then start the container with the following options:<br />
<br />
--setenv=DISPLAY=:1 --bind-ro<nowiki>=</nowiki>/tmp/.X11-unix/X1<br />
<br />
No other binds are necessary.<br />
<br />
You might still need to manually set {{ic|1=DISPLAY=:1}} in the container under some circumstances (mostly if used with {{ic|-b}}).<br />
<br />
==== Run Firefox ====<br />
<br />
To run as PID 1<br />
<br />
# systemd-nspawn --setenv=DISPLAY=:0 \<br />
--setenv=XAUTHORITY=~/.Xauthority \<br />
--bind-ro=$HOME/.Xauthority:/root/.Xauthority \<br />
--bind=/tmp/.X11-unix \<br />
-D ~/containers/firefox \<br />
firefox<br />
<br />
Alternatively you can boot the container and let e.g. [[systemd-networkd]] set up the virtual network interface:<br />
<br />
# systemd-nspawn --bind-ro=$HOME/.Xauthority:/root/.Xauthority \<br />
--bind=/tmp/.X11-unix \<br />
-D ~/containers/firefox \<br />
--network-veth -b<br />
<br />
Once your container is booted, run the Xorg binary like so:<br />
<br />
# systemd-run -M firefox --setenv=DISPLAY=:0 firefox<br />
<br />
=== Access host filesystem ===<br />
<br />
See {{ic|--bind}} and {{ic|--bind-ro}} in {{man|1|systemd-nspawn}}.<br />
<br />
If both the host and the container are Arch Linux, then one could, for example, share the pacman cache:<br />
<br />
# systemd-nspawn --bind=/var/cache/pacman/pkg<br />
<br />
Or you can specify per-container bind using the file:<br />
<br />
{{hc|/etc/systemd/nspawn/''my-container''.nspawn|<nowiki><br />
[Files]<br />
Bind=/var/cache/pacman/pkg<br />
</nowiki>}}<br />
<br />
See [[#Per-container settings]].<br />
<br />
To bind the directory to a different path within the container, add the path be separated by a colon. For example:<br />
<br />
# systemd-nspawn --bind=''/path/to/host_dir:/path/to/container_dir''<br />
<br />
=== Run on a non-systemd system ===<br />
<br />
See [[Init#systemd-nspawn]].<br />
<br />
=== Use Btrfs subvolume as container root ===<br />
<br />
To use a [[Btrfs#Subvolumes|Btrfs subvolume]] as a template for the container's root, use the {{ic|--template}} flag. This takes a snapshot of the subvolume and populates the root directory for the container with it.<br />
<br />
{{Note|If the template path specified is not the root of a subvolume, the '''entire''' tree is copied. This will be very time consuming.}}<br />
<br />
For example, to use a snapshot located at {{ic|/.snapshots/403/snapshot}}:<br />
<br />
# systemd-nspawn --template=/.snapshots/403/snapshots -b -D ''my-container''<br />
<br />
where {{ic|''my-container''}} is the name of the directory that will be created for the container. After powering off, the newly created subvolume is retained.<br />
<br />
=== Use temporary Btrfs snapshot of container ===<br />
<br />
One can use the {{ic|--ephemeral}} or {{ic|-x}} flag to create a temporary btrfs snapshot of the container and use it as the container root. Any changes made while booted in the container will be lost. For example:<br />
<br />
# systemd-nspawn -D ''my-container'' -xb<br />
<br />
where ''my-container'' is the directory of an '''existing''' container or system. For example, if {{ic|/}} is a btrfs subvolume one could create an ephemeral container of the currently running host system by doing:<br />
<br />
# systemd-nspawn -D / -xb <br />
<br />
After powering off the container, the btrfs subvolume that was created is immediately removed.<br />
<br />
=== Run docker in systemd-nspawn ===<br />
<br />
[[Docker]] requires {{ic|rw}} permission of {{ic|/sys/fs/cgroup}} to run its containers, which is mounted read-only by ''systemd-nspawn'' by default due to cgroup namespace. However, it is possible to run Docker in a ''systemd-nspawn'' container by bind-mounting {{ic|/sys/fs/cgroup}} from the host system and enabling necessary capabilities and permissions.<br />
<br />
{{Note|The following steps are essentially sharing the cgroup / user namespace to the container, giving kernel keyring permissions and making it a privileged container, which is likely to increase the attack surface and decrease security level. You should always evaluate the actual benefits by doing so before following the steps.}}<br />
<br />
First, cgroup namespace should be disabled by {{ic|systemctl edit systemd-nspawn@myContainer}}<br />
<br />
{{hc|systemctl edit systemd-nspawn@myContainer|<nowiki><br />
[Service]<br />
Environment=SYSTEMD_NSPAWN_USE_CGNS=0<br />
</nowiki>}}<br />
<br />
Then, edit {{ic|/etc/systemd/nspawn/myContainer.nspawn}} (create if absent) and add the following configurations.<br />
<br />
{{hc|/etc/systemd/nspawn/myContainer.nspawn|<nowiki><br />
[Exec]<br />
Capability=all<br />
SystemCallFilter=add_key keyctl<br />
PrivateUsers=no<br />
<br />
[Files]<br />
Bind=/sys/fs/cgroup<br />
</nowiki>}}<br />
<br />
This grants all capabilities to the container, disables user namespacing, whitelists two system calls {{ic|add_key}} and {{ic|keyctl}} (related to kernel keyring and required by Docker), and bind-mounts {{ic|/sys/fs/cgroup}} from host to the container. After editing these files, you need to poweroff and restart your container for them to take effect. If your container had user namespaces enabled before this change (which is the default if the {{ic|systemd-nspawn@.service}} unit is used), you will also need to undo permission changes caused by user namespacing to avoid permission errors. See [[#Unprivileged containers]] for details.<br />
<br />
{{Note|<br />
* You might need to load the {{ic|overlay}} module on the host before starting Docker inside the systemd-nspawn to use the {{ic|overlay2}} storage driver (default storage driver of Docker) properly. Failure to load the driver will cause Docker to choose the inefficient driver {{ic|vfs}} which copies everything for every layer of Docker containers. Consult [[Kernel modules#Automatic module loading with systemd]] on how to load the module automatically.<br />
* As of November 2020, cgroups v2 seems to break Docker inside ''systemd-nspawn''. If you want to use Docker in this way, do not set the kernel parameter {{ic|1=systemd.unified_cgroup_hierarchy=1}}.<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Root login fails ===<br />
<br />
If you get the following error when you try to login (i.e. using {{ic|machinectl login <name>}}):<br />
<br />
arch-nspawn login: root<br />
Login incorrect<br />
<br />
And the [[journal]] shows:<br />
<br />
pam_securetty(login:auth): access denied: tty 'pts/0' is not secure !<br />
<br />
Delete {{ic|/etc/securetty}}[https://unix.stackexchange.com/questions/41840/effect-of-entries-in-etc-securetty/41939#41939] and {{ic|/usr/share/factory/etc/securetty}} on the '''container''' file system. Optionally add them to [[pacman#Skip files from being installed to system|NoExtract]] in {{ic|/etc/pacman.conf}} to prevent them from getting reinstalled. See {{Bug|45903}} for details.<br />
<br />
=== execv(...) failed: Permission denied ===<br />
<br />
When trying to boot the container via {{ic|systemd-nspawn -bD ''/path/to/container''}} (or executing something in the container), and the following error comes up:<br />
<br />
execv(/usr/lib/systemd/systemd, /lib/systemd/systemd, /sbin/init) failed: Permission denied<br />
<br />
even though the permissions of the files in question (i.e. {{ic|/lib/systemd/systemd}}) are correct, this can be the result of having mounted the file system on which the container is stored as non-root user. For example, if you mount your disk manually with an entry in [[fstab]] that has the options {{ic|noauto,user,...}}, ''systemd-nspawn'' will not allow executing the files even if they are owned by root.<br />
<br />
=== Terminal type in TERM is incorrect (broken colors) ===<br />
<br />
When logging into the container via {{ic|machinectl login}}, the colors and keystrokes in the terminal within the container might be broken. This may be due to an incorrect terminal type in {{ic|TERM}} environment variable. The environment variable is not inherited from the shell on the host, but falls back to a default fixed in systemd ({{ic|vt220}}), unless explicitly configured. To configure, within the container create a configuration overlay for the {{ic|container-getty@.service}} systemd service that launches the login getty for {{ic|machinectl login}}, and set {{ic|TERM}} to the value that matches the host terminal you are logging in from:<br />
<br />
{{hc|/etc/systemd/system/container-getty@.service.d/term.conf|2=<br />
[Service]<br />
Environment=TERM=xterm-256color<br />
}}<br />
<br />
Alternatively use {{ic|machinectl shell}}. It properly inherits the {{ic|TERM}} environment variable from the terminal.<br />
<br />
=== Mounting a NFS share inside the container ===<br />
<br />
Not possible at this time (June 2019).<br />
<br />
== See also ==<br />
<br />
* [[Getty#Nspawn_console|Automatic console login]]<br />
* [https://lwn.net/Articles/572957/ Creating containers with systemd-nspawn]<br />
* [https://www.youtube.com/results?search_query=systemd-nspawn&aq=f Presentation by Lennart Poettering on systemd-nspawn]<br />
* [https://dabase.com/e/12009/ Running Firefox in a systemd-nspawn container]<br />
* [https://web.archive.org/web/20190925003151/https://patrickskiba.com/sysytemd-nspawn/2019/03/21/graphical-applications-in-systemd-nspawn.html Graphical applications in systemd-nspawn]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=684705GnuPG2021-07-01T00:45:10Z<p>Pgoetz: Added an out of date warning regarding dirmngr.conf</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ko:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [[RFC:4880|RFC 4880]] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set the {{ic|GNUPGHOME}} [[environment variable]].<br />
<br />
=== Configuration files ===<br />
{{Out of date| ~/.gnupg/dirmngr.conf is no longer created; perhaps because no skeleton file can be found in usr/share/doc/gnupg/}}<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/doc/gnupg/}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular the newer ECC cipher ([[Wikipedia:Elliptic-curve cryptography]]).<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''RSA and RSA'' for sign and encrypt keys.<br />
* A keysize of the default 3072 value. A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot" (see [https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096 why doesn’t GnuPG default to using RSA-4096]).<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public.key''}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public.key'' ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use_OpenPGP_with_external_GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server. The reason is explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lkml.org/lkml/2016/8/15/445 fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://sks-keyservers.net SKS Keyserver Pool]{{Dead link|2021|05|13|status=SSL error}}: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted.<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://pool.sks-keyservers.net<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver hkps://keys.openpgp.org/ --search-keys 931FF8E79F0876134EDDBDCCA87FF9DF48BF1C90<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If your network blocks connection to port 11371 used for hkp, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}. Alternatively, some HKPS servers provide access through port 443, for example, {{ic|hkps://hkps.pool.sks-keyservers.net:443}}.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.}}<br />
<br />
=== Web Key Directory ===<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''privkey.asc'' ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''privkey.asc''<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert.asc'' ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''user-id''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys ''[subkey id]''! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert.asc''<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} to communicate with ''gpg-agent'' and replace the default ''ssh-agent''. User-based configuration of [[Environment_variables#Using_pam_env|pam_env]] allows you to set environment variables by user, instead of shell.<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually (such as in this pam_env example), keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disable keyring daemon components|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
If you use multiple terminals simultaneously and want gpg-agent to ask for passphrase from same terminal where ssh command was run, add the following to ssh config. This will make the TTY to be refreshed everytime ssh command is run [https://unix.stackexchange.com/a/499133]:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host * exec "gpg-connect-agent UPDATESTARTUPTTY /bye"<br />
}}<br />
<br />
Note that GPG_TTY environment variable has to be set for this to work.<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It's possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
And select an option that allows you to set your own capabilities.<br />
<br />
Comparably, to specify custom capabilities for subkeys, add the {{ic|--expert}} flag to {{ic|gpg --edit-key}}, see [[#Edit your key]] for more information.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
<br />
When generating a key, gpg can run into this error:<br />
<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
<br />
To check the available entropy, check the kernel parameters:<br />
<br />
$ cat /proc/sys/kernel/random/entropy_avail<br />
<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
See [[GNOME/Keyring#Disable keyring daemon components]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
{{Accuracy|The {{ic|gpg-agent*.socket}} systemd sockets provided by the {{Pkg|gnupg}} package create the sockets in {{ic|/run/user/$UID/gnupg/}} which is guaranteed to be an appropriate file system.}}<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
If your keyring is stored on a vFat filesystem (e.g. a USB drive), {{ic|gpg-agent}} will fail to create the required sockets (vFat does not support sockets), you can create redirects to a location that handles sockets, e.g. {{ic|/dev/shm}}:<br />
<br />
# export GNUPGHOME=/custom/gpg/home<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent\n' > $GNUPGHOME/S.gpg-agent<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.browser\n' > $GNUPGHOME/S.gpg-agent.browser<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.extra\n' > $GNUPGHOME/S.gpg-agent.extra<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.ssh\n' > $GNUPGHOME/S.gpg-agent.ssh<br />
<br />
Test that gpg-agent starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [[RFC:4880|RFC 4880]] — "OpenPGP Message Format"<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [[Fedora:Creating GPG Keys]]<br />
* [[Debian:Subkeys]]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=User_talk:Lahwaacz&diff=678329User talk:Lahwaacz2021-06-09T16:51:54Z<p>Pgoetz: /* USB flash installation medium (BIOS bootable) */ Comment on editing reversions</p>
<hr />
<div>== bot checking links after move ==<br />
<br />
Hi, re [[Talk:Touchpad Synaptics#adding libinput alternative]]. [[Touchpad Synaptics]] has 100+ backlinks and the more important ones - a bit tedious task. I was just glancing over your clever github bot scripts. It would be handy to have a script after such moves: walk over the backlinks of [[Touchpad Synaptics]] and just replace "[[Touchpad Synaptics" with "[[Synaptics" from the links. That would leave all links to subsections intact. Leaving out the translations to handle manually, there would not be much to go wrong, or? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 07:36, 26 September 2015 (UTC)<br />
<br />
:Hi, thanks for the suggestion. It would be indeed handy in this case, but most likely not generally. Imagine that there was a [[UUID]] page, which was later generalized and renamed to [[Persistent block device naming]] and content about UUID is now only a section on the page. In this case using the naive replacement would likely change the meaning of many sentences, and using shorter redirects for convenience is actually encouraged. There would have to be a list of whitelisted "harmless" replacements, which could even help to replace <nowiki>[[pacman|Install]]</nowiki> with <nowiki>[[Install]]</nowiki> etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:01, 26 September 2015 (UTC)<br />
<br />
::Yes, good examples, but you are thinking universal already :) I did not mean it could be that. For example, if you take the time when the bulk of the title case moves were done. With such a script one could avoid a lot of internal redirects as well. E.g. [https://wiki.archlinux.org/index.php/Special:WhatLinksHere/Beginners'_Guide]. But it's ok, just an idea. Please close this, if you think it's too singular cases with a simple enough replacement where it could be applied. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:02, 26 September 2015 (UTC)<br />
<br />
== mkosi ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=Systemd-nspawn&diff=0&oldid=491975 revert]: You can use mkosi also to create a container/directory tree (-t directory). So it can do the same and more. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 11:33, 1 October 2017 (UTC)<br />
<br />
:Alright, how is the "more" relevant to systemd-nspawn though? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:30, 3 October 2017 (UTC)<br />
<br />
::Hi, mkosi let's you create images (or directory trees) of various different distributions and allows you to do things like setting the root-password or installing additional packages. systemd-nspawn alows you to boot such images/directory trees. So I thought mentioning mkosi as alternative to manually creating a container with pacstrap or debootstrap would be worth it. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 22:23, 5 October 2017 (UTC)<br />
<br />
== Waking from suspend with USB device ==<br />
<br />
Hi Lahwaacz, thanks for your input on this topic.<br />
Can you help me a bit further, I know the USB host controller and the USB device are different things but I thought that enabling the host controller was not necessary anymore, see [https://www.spinics.net/lists/linux-usb/msg53661.html].<br />
In my case all the {{ic|driver/*/power/wakeup}} are all enabled by default and the {{ic|/proc/acpi/wakeup}} as well.<br />
Anyway I have added a step in my explanations to identify the path awaiting for more clarity.<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 21:57, 16 January 2018 (UTC)<br />
<br />
:Hi, thanks for the link, it's entirely possible that something changed since the section was written. However, in my case only the keyboard device has wakeup enabled by default: {{bc|<nowiki><br />
$ for f in /sys/bus/usb/drivers/usb/*/power/wakeup; do echo "$f: $(cat $f)"; done<br />
/sys/bus/usb/drivers/usb/1-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/2-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-11/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-12/power/wakeup: enabled<br />
/sys/bus/usb/drivers/usb/3-13/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-4/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb2/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb4/power/wakeup: disabled<br />
</nowiki>}}<br />
:But in practice it seems to wake up the system even without the host controllers enabled for wakeup... It might also depend on some BIOS/firmware settings but if it works by default on most systems then I think the host controller settings could be removed again.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:14, 19 January 2018 (UTC)<br />
<br />
== Are supported local/remote destinations important for choosing a backup program? ==<br />
<br />
You [[Special:Diff/525550|reverted]] my edit adding supported backup destinations to [[Synchronization_and_backup_programs]]. This is puzzling to me. Here are some thoughts:<br />
* if choosing any backup program, the ability to send the backup off-site vs only on a local disk is a key feature consideration. Perhaps *the* key feature: one helps me recover in case my house gets burglarized or burns down, and the other does not. This is a much more important feature consideration than, say, whether the program is written in Go or Mono (something that has a full column). I think it's hard to disagree on that.<br />
* Given this, I am very puzzled you would use the term "useless" in the revert message.<br />
* I assume you didn't like that the table got even bigger (it didn't fit into the layout even before). I don't like it either, but perhaps the revert should have said "can you put this somewhere else, not in this already-too-big table?"<br />
* On a personal note, when I provide feedback or give opinion on somebody else's work, I'd like to be constructive and kind, instead of aggressive and putting people down. Just a thought. Thanks for listening.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 17:38, 11 June 2018 (UTC)<br />
<br />
:No because you can use any remote back-end with any backup application by just running one command / writing the backups to a [[FUSE]] (if available).--[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 04:39, 12 June 2018 (UTC)<br />
<br />
::Hmm, by that reasoning we don't need the Arch package repository, as long as we have source code and makepkg. Or Perl, if we have bash and awk. But even then, and if all the fuse backends existed (I doubt they do), and if it were easy to set all of them up (another thing I doubt), do you indeed believe that running something written to read/write local files will be just as efficient backing up gigabytes of data to a remote repository as something that is specifically optimized for that use case? Note that backing up, say, daily, a typical hard drive via tpyical consumer broadband is still quite a bandwidth challenge in many places today. What about we add this info, and remove (or merge) some other columns to make the table smaller? {{Unsigned|18:08, 12 June 2018|Jernst}}<br />
<br />
:::Your comparisons don't make sense. Mind the slash in my response, you do not need a FUSE implementation, a simple CLI suffices. You do not need to "set all of them up", you only need one. --[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 18:47, 12 June 2018 (UTC)<br />
<br />
::::If you ever attempt to help a normal user set up a reliably-working off-site backup strategy, think of this discussion. In the meantime, this is all the time I'm going to spend on a discussion that has such repeated gems in it as "makes no sense" without explaining why you think so. Have a nice day. [[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 18:54, 12 June 2018 (UTC)<br />
<br />
== The pip section in [[Python package guidelines]] ==<br />
<br />
Hi, you wanted the warning about using pip or wheels restored but accidentally(?) reverted my whole set of changes. I redid them, leaving the warning in place. – [[User:Flying sheep|flying sheep]] 08:17, 8 March 2019 (UTC)<br />
<br />
:Full revert was intentional, because the "wheel" section is not a full replacement for "pip" because there are packages which don't provide wheel files. As I said in the edit summary, there is no reason to recommend one or the other due to the warning. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:21, 8 March 2019 (UTC)<br />
::That still doesn’t explain why you reverted the first part, that had nothing to do with the pip/wheel section and simple improves the files.pythonhosted.org URLs. I restored that one while we’re discussing the pip/wheel section. And about that: There’s no reason to use pip for anything else, and pip is only used because some people (me included) didn’t understand that you can install most wheels by just extracting them to the correct location. So what do you think is missing from my wheels section that the former pip section had? – [[User:Flying_sheep|flying sheep]] 11:41, 11 March 2019 (UTC)<br />
<br />
:::If you didn't notice, the page includes "guidelines" in the title. So the page should contain only common and recommended ways to do things, not everything that is possible to do. If you think that your way to install "wheels" should be followed by everybody, feel free to discuss it on the talk page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:26, 11 March 2019 (UTC)<br />
::::Well, extracting static archives sounds much more recommended than running pip with like 7 options to make it behave. I added a talk item: [[Talk:Python package guidelines#Remove_pip_section_in_favor_of_wheels_section?]] – [[User:Flying_sheep|flying sheep]]<br />
<br />
== wpa_supplicant ==<br />
<br />
Regarding https://wiki.archlinux.org/index.php?title=WPA_supplicant&diff=577215&oldid=577167, one person ran into this problem in March of this year and spent too much time diagnosing it:<br />
<br />
https://bbs.archlinux.org/viewtopic.php?id=244950<br />
<br />
It took me a few days to find the problem. I want to make sure the next time someone encounters it, they easily find relevant information about what the cause is. Since you've reverted my edits to both netctl and wpa_supplicant, what do you suggest?<br />
<br />
--<br />
<br />
[[User:Pooryorick|Pooryorick]] ([[User talk:Pooryorick|talk]]) 08:24, 18 July 2019 (UTC)<br />
<br />
== F2FS and GRUB ==<br />
<br />
Hello. :) I'm here to address a recent disagreement. I noticed a reversion of my edit regarding the F2FS filesystem, in particular regarding the configuration file to edit (with you representing /boot/grub/grub.cfg and me representing /etc/default/grub). I run F2FS on my daily driver with an encrypted root filesystem and encrypted boot on a separate partition, and have never had to touch grub.cfg. I only automatically generate it. It's possible to use either, but /etc/default/grub would make more sense as a recommendation in my mind because grub.cfg has the potential to be overwritten during updates, whereas /etc/default/grub doesn't. <br />
<br />
If there's a compelling reason to use grub.cfg over /etc/default/grub, please let me know. ^^ I'm always eager to learn more about Arch. I don't want to get in a reversion war so I've left your change untouched for the time being.<br />
<br />
[[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 00:17, 8 September 2019 (UTC)<br />
<br />
:The reason is explained in the section: "If GRUB is used with an unsupported filesystem it is not able to extract the UUID of your drive so it uses classic non-persistent /dev/sdXx names instead." If it does not apply to F2FS, it should be made clear. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:29, 8 September 2019 (UTC)<br />
<br />
::You can specify UUID's in GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, so my proposed solution would work for F2FS and other unsupported filesystems, without the burden of manually editing grub.cfg. If there's anything I need to clarify or something else I'm missing, just let me know. :) [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 19:37, 8 September 2019 (UTC)<br />
<br />
:::The {{ic|1=root=}} parameter is not supposed to be in GRUB_CMDLINE_LINUX_DEFAULT, regardless if UUID is used or not. ''grub-mkconfig'' automatically detects the root filesystem and adds the appropriate {{ic|1=root=}} parameter based on GRUB_DISABLE_LINUX_UUID. In any case, your change to the paragraph does not make sense. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:02, 8 September 2019 (UTC)<br />
<br />
::::It could simply be because I use full disk encryption, and adding a kernel parameter for the encrypted disk's UUID is correct in that situation. You're more experienced with contributing to the wiki, so I guess I'll defer to your judgment. It felt like a reasonable edit and solution to me and I don't see the downside to including it in GRUB_CMDLINE_LINUX_DEFAULT. [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 05:38, 9 September 2019 (UTC)<br />
<br />
== dracut executable link ==<br />
<br />
Hello, your last edit on the dracut page (https://wiki.archlinux.org/index.php?title=Dracut&oldid=596388) that undid my 'Link to direct "make executable" section for executable link' commit states: "the redirect executable points exactly to that section", but it doesn't. Following the [[executable]] link just points to the top of the Help:Reading page.<br />
<br />
{{unsigned|17:06, 28 January 2020|Krathalan}}<br />
<br />
:In that case your browser probably does not work correctly, because the redirect [https://wiki.archlinux.org/index.php?title=Executable&redirect=no really points to the section]. Or MediaWiki, there was a bug several years ago... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:41, 28 January 2020 (UTC)<br />
<br />
:: How strange... thanks for pointing that out. It does indeed appear to be some issue with my Firefox configuration. [[User:Krathalan|Krathalan]] ([[User talk:Krathalan|talk]]) 19:51, 28 January 2020 (UTC)<br />
<br />
== Getting install.php work in DokuWiki ==<br />
<br />
Hi, than you for having undone my contribution and pointed to the right solution on [[Dokuwiki#Configuration]]. Indeed I had read this solution before, but I was misled by the condition "if you are using lighttpd or nginx and your PHP version is lower than 7": as I use Apache with php v. 7.4.3 I didn't take it into account. Do you know what a correct rephrasing could be? Maybe it should be deleted?<br />
<br />
Also, I think that, at the end of this same section, one should add something like "verify that {{Pkg|php-gd}} is installed and restart {{ic|php-fpm.service}}".<br />
<br />
Naturally I can do it myself, but I prefer to ask before.<br />
[[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 17:31, 19 February 2020 (UTC)<br />
<br />
:Hi, apparently it depends on whether you had {{ic|open_basedir}} set previously or not. I've changed the page, feel free to update the gd extension. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:16, 19 February 2020 (UTC)<br />
<br />
::Thank you! However, while, I didn't have {{ic|open_basedir}} set previously, I couldn't access ''install.php''. I suspect there is another thing to do, since the configuration editor in DokuWiki complains that it cannot modify the configuration files although ownership and permissions are correctly set for the relevant symlinks, directories and files, and so is {{ic|open_basedir}}. However I can edit my pages. Maybe a return from a new user with a fresh installation would be more useful, though. [[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 08:20, 20 February 2020 (UTC)<br />
<br />
== Dead link in Simple stateful firewall#See Also ==<br />
<br />
Hi, Jakub. I am about [https://wiki.archlinux.org/index.php?title=Simple_stateful_firewall&diff=599725&oldid=599717 this] edit. I tried to follow that link one more time and it is not require entering captcha. I am not see any content limitations and my colleague (he uses Tor) does not see them too. I am not sure how it works, so I leave it on your descision. -- [[User:Duodai|Duodai]] ([[User talk:Duodai|talk]]) 14:29, 1 March 2020 (UTC)<br />
<br />
:Well, maybe it depends on the location from which the request comes. But I don't know how it works either... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:33, 1 March 2020 (UTC)<br />
<br />
::my guess is it returns captcha for crawlers only -- [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 01:59, 2 March 2020 (UTC)<br />
<br />
:::I'm getting it in my browser... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:14, 2 March 2020 (UTC)<br />
<br />
== SystemD user units depending on graphical session ==<br />
Hi,<br />
regarding reverting my addition to [[Systemd/User]], could you please explain why? I referenced [[https://www.freedesktop.org/software/systemd/man/systemd.special.html]] which directly contradicts what you said in your summary.<br />
<br />
{{unsigned|19:53, 5 May 2020|Fuero}}<br />
<br />
:The note in [[Systemd/User#How it works]] still applies - systemd services are never per-session, but per-user. The service does not magically get the correct DISPLAY or WAYLAND_DISPLAY variable, it does not work if you have multiple sessions per user, etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:45, 6 May 2020 (UTC)<br />
<br />
== Plymouth ==<br />
<br />
Actually with just Plymouth it does not work properly. Even 0dd17y had the same issue in https://bbs.archlinux.org/viewtopic.php?id=220900.<br />
<br />
The reason I did not file a bug report is that it is anyway fixed in the git version and the latest release (0.9.4) is around 2 years behind master<br />
<br />
{{unsigned|09:50, 6 May 2020|M.Srikanth}}<br />
<br />
:So if you don't have to file a bug report, add a full troubleshooting entry or at least properly reference your inline note instead of resorting to plain "if that does not work, try this instead". -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:15, 6 May 2020 (UTC)<br />
<br />
== [Bitcoin core] build the code and run the test suites ==<br />
<br />
Hello,<br />
<br />
This week, I managed to build the Bitcoin code and run all the test suites with the help of this page: https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests<br />
<br />
Archlinux has two particularities:<br />
* being in rolling release, it takes to manually use the library {{ic|Berkeley DB (BDB) v4.8}}<br />
* the {{ic|/tmp}} directory is by default limited to half the size of the Ram<br />
<br />
For these reason, maybe it could be interesting to have a page in the wiki to explain how to build the Bitcoin core?<br />
<br />
Cheers,<br />
<br />
Thomas<br />
<br />
[[User:Thomasb|Thomasb]] ([[User talk:Thomasb|talk]]) 20:29, 9 May 2020 (UTC)<br />
<br />
:I don't think that this is useful. There is the {{AUR|bitcoin-core-git}} package and nothing more should be needed. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:53, 26 May 2020 (UTC)<br />
<br />
== Double linefeed results in extra line ==<br />
<br />
If you look at templates that end with double linefeed before noinclude this would result in extra line in resulting page.<br />
<br />
It may be a minor point but since you are perfectionist about wikitext I should mention this is a tradeoff and it results in slightly worse result.<br />
<br />
Removing just one linefeed removes the problem while still allowing it to not jumble all the tags into same line.<br />
<br />
-- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 16:30, 11 May 2020 (UTC)<br />
<br />
:If this is about [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=next&oldid=612179], the spaces I added back are not included when the template is used elsewhere, because the spaces are inside the noinclude tags. The extra space is only on the template page itself, but it does not result from template inclusion. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:41, 11 May 2020 (UTC)<br />
<br />
::OFC, I mean the template page render has extra line. -- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 21:21, 11 May 2020 (UTC)<br />
<br />
:::I agree with [[User:Svito|Svito]], isn't it good to delete the extra blank lines? -- [[User:Blackteahamburger|Blackteahamburger]] ([[User talk:Blackteahamburger|talk]]) 05:39, 12 May 2020 (UTC)<br />
<br />
::::OK, let's do it. [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=616382&oldid=612181] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:47, 26 May 2020 (UTC)<br />
<br />
== Re: lighttpd: remove python2 version ==<br />
<br />
Instead of removing the example we could as well add an example using a Python3 library like https://pypi.org/project/flup6/.<br />
<br />
{{unsigned|15:23, 18 May 2020|Gruentee}}<br />
<br />
:Feel free to add it if you find it useful. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:56, 18 May 2020 (UTC)<br />
<br />
== Xbindkeys removal ==<br />
<br />
Hi, just wondering why you [https://wiki.archlinux.org/index.php?title=Xbindkeys&diff=617675&oldid=617670 removed my edit] from [[Xbindkeys]]? The xbindkeys page has a number of quick tips but no mention of how to bind anything to the Print Screen key so I thought it would be useful to add. -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 02:27, 3 June 2020 (UTC)<br />
<br />
:Giving examples for all keys on the keyboard is useless, there is [[Xbindkeys#Identifying keycodes]] which teaches how to find the keycodes and keysyms of any key. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 3 June 2020 (UTC)<br />
<br />
:: So how come you left the examples for the volume up/down and brightness? What is different between those examples and a screenshot example? Aren't more examples better to save people from hunting all over the place trying to piece things together themselves? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 14:03, 4 June 2020 (UTC)<br />
<br />
:::The difference is that when it comes to volume control, there are 1 or 2 options for the 99% most common cases, but for screenshot taking there are dozens of different options. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:15, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for edit to XDG Base Directory page regarding python_history ==<br />
<br />
I understand the justification for reverting the change I made, however I would like to point out that similar entries on the page (such as Maven) also have instructions for what contents to put in files (even though there is native documentation for those settings). Additionally, it took me a bit of re-reading on the linked Python documentation to reason out how the documentation's example needed to be modified, since it's not clear from the Python documentation whether placing such code in the PYTHONSTARTUP file will actually ''override'' the default behavior. [[User:Varriount|Varriount]] ([[User talk:Varriount|talk]]) 20:44, 20 June 2020 (UTC)<br />
<br />
:Even maven's note can be [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&diff=631704&oldid=631630 shortened]. The notes in the table must be as short as possible, there is no place for extended explanations or long code snippets like in the upstream documentation. If the Python's documentation is not clear enough, I don't think any note in a massive convoluted table will ever be better. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:47, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for Backlight page ==<br />
<br />
Hi, you reverted my change to [[Backlight]] page that mentioned WIP patches for controlling OLED panel brightness. I don't really understand justification for reverting it since currently the page says that OLED brightness can be controlled only by changing gamma ramp. That is wrong - since it's not the only way - these panels can control brightness with a PWM. Moreover controlling brightness with gamma ramp is not optimal - it essentially reduces dynamic range, i.e. at 50% you have 7 bits per pixel, at 25% - 6 bit per pixel, etc. That results in banding artifacts at lower brightness level.<br />
<br />
As far waiting for the patches to be merged before mentioning it there - it'll take ~3-6 months (yes, that's the process) and I haven't found *any* reference to these changes on the internet - everyone recommends using gamma ramp instead of fixing it properly. I'm absolutely sure that having information about these patches would not hurt [[User:Anarsoul|Anarsoul]] ([[User talk:Anarsoul|talk]]) 15:56, 30 June 2020 (UTC)<br />
<br />
:Linking to a repo which which has 2 custom commits on top of some arbitrary development version of the Linux kernel tree is not helpful for users. Nobody will compile directly from this repo which is already significantly outdated compared to recent kernel versions and there is no indication if the patches actually work with newer (or older) kernels. We can mention the PWM control as a general concept though. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:32, 12 August 2020 (UTC)<br />
<br />
== Automatic template correction ==<br />
<br />
Per [[Help:Template#Style]], templates should be used with the capitalization shown in the examples in their pages, so {{ic|&#123;{AUR&#124;...}} is correct, while {{ic|&#123;{aur&#124;...}} is not.<br />
<br />
However, there are pages that don't respect that rule (e.g. [[Android_Debug_Bridge]] until recently).<br />
<br />
I beleive this correction should be easy to implement using a bot. What do you think?<br />
<br />
{{unsigned|07:24, 25 August 2020|Relrel}}<br />
<br />
:Yes, this should be easy, but the bot should not make a huge amount of simple style-only changes - they should be combined with corrections for more complex rules. Anyway, there is an idea to create a [https://github.com/lahwaacz/wiki-scripts/issues/22 style linter] for the ArchWiki rules. Would you like to help? ;-) – [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:21, 25 August 2020 (UTC)<br />
<br />
== Failed to create tun device ==<br />
<br />
I don't understand your reason for [[https://wiki.archlinux.org/index.php?title=NetworkManager&diff=0&oldid=634880 removing my section in NetworkManager]]. Could you elaborate?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 07:40, 11 September 2020 (UTC)<br />
<br />
:You can't use [[systemd-networkd]] and [[NetworkManager]] at the same time. Even if you don't have any ''.network'' file for systemd-networkd, you can't solve NetworkManager's problems with systemd-networkd. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:43, 11 September 2020 (UTC)<br />
<br />
::Ok, thanks, in this case it solved the error I got. Now the VPN works. Do you have an idea about how to solve it without systemd-networkd?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 22:27, 11 September 2020 (UTC)<br />
<br />
:::You should really fix the permission problem for {{Pkg|networkmanager-openvpn}}. The tun interface should be managed by OpenVPN which needs rights to create it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 12 September 2020 (UTC)<br />
<br />
::I don't think this statement is entirely correct. [[systemd-networkd]] and [[NetworkManager]] can happily co-exist together if they are managing different interfaces. I unfortunately don't have a reference to point to this, but I came across this being mentioned a couple of times on forums. I personally use [[NetworkManager]] on my laptop to handle wifi, while [[systemd-networkd]] is in control of virtual ethernet and bridges for all my [[systemd-nspawn]] instances. [[User:Romstor|Romstor]] ([[User talk:Romstor|talk]]) 03:24, 12 September 2020 (UTC)<br />
<br />
== [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&oldid=636526/ XDG Base Directory]: Undo revision 636525 ==<br />
<br />
Dear Lahwaacz,<br />
<br />
maybe my changes were to rushed and from my point of view only. But I have two points to consider:<br />
<br />
# If I put the quotes around my vimrc and source it from my .bash_profile, I get the vim-error E471 (Argument required). Without quotes, this doesn't happen. So this change based on experience.<br />
# The rtp should includes directories, which are needed at runtime. (in plain vim e.g. ~/.vim). This is not a typical configuration directory. My mistake was, that I supposed that everyone put their vim plug-ins in $XDG_DATA_HOME and not in $XDG_CONFIG_HOME, because from my point of view a plug-in doesn't belong to the configuration. Maybe it is a good idea to add a remark, which explains the addition of $XDG_CONFIG_HOME to the rtp.<br />
<br />
[[User:Grrr|Grrr]] ([[User talk:Grrr|talk]]) 13:53, 26 September 2020 (UTC)<br />
<br />
# Quotes are there because $XDG_CONFIG_HOME may contain spaces.<br />
# It's not only about quotes - the runtimepath has subdirectories for color schemes, keymaps, autoload scripts etc.<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 26 September 2020 (UTC)<br />
<br />
== Readability in Wiki ==<br />
<br />
I noticed that you and the other admins and moderators often want sentences to continue endlessly, without line breaks.<br />
For example in the introduction of [[Wayland]].<br />
<br />
I think it would be better to have more seperated sentences, so it is easier to read and "important" information is easier visible for people.<br />
I don't know who is responsible, but maybe some options in MediaWiki (or whatever this wiki software is) could be changed as well, to make make line breaks etc. easier and reduce the height-space (if you know what I mean) between sentences, so it looks better, even though line breaks are used.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:38, 15 October 2020 (UTC) G3ro<br />
<br />
:I don't know exactly what you mean. Is it about the readability of the rendered HTML or the "source code" of the page? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:15, 15 October 2020 (UTC)<br />
<br />
:: Well I guess it can be about both. But mainly it is about what people see on the page.<br />
:: There are three seperate topics I mentioned:<br />
<br />
:: 1. Use line breaks: I would like to use more line breaks, because if you have long sentences that are written after each other without line breaks, it gets "harder" to recognize when the next sentence starts.<br />
:: While I agree to what you said somewhere, that sentences that belong directly together, should be written in one "paragraph", it would be useful for sentences that cover (slightly) different "topics" to be visibly parted.<br />
<br />
:: 2. Adjust margin options: I notice that when line breaks are used, there is a vertical space added between two sentences. Just like in this post. If you would use line breaks more often, this is a little too much spacing in my oppinion.<br />
<br />
:: 3. Potential options to make line breaks easier: It would be very convenient if a line break in the source code would lead to a line break in displayed text as well, instead of needing to add an empty line.<br />
<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:33, 15 October 2020 (UTC) G3ro<br />
<br />
:::OK, now I understand. I agree that splitting different topics usually improves legibility, but they should be split into separate paragraphs and not just by line breaks (e.g. using the &lt;br> tags). Paragraphs are semantic units whereas line breaks inside a paragraph are usually typographic errors.<br />
:::Also note that such splitting alone may not be enough to improve the text flow. For example, if we consider the intro for [[Wayland]], the second sentence about XWayland would not constitute a good paragraph - it is just a plain statement and the new topic is not nicely introduced. Ideally, you'd split the topic and make some wording changes for the second paragraph.<br />
:::As for the margin options, that is the difference between paragraph splitting and non-semantic line breaks. In my opinion, the styling is correct in this respect, as paragraphs should be discernible. You mentioned that you like line breaks to easily recognize where a sentence ends - but reading should be based on whole paragraphs, not sentences. There should be no reason to skip anything in the middle of a paragraph, otherwise it should be probably split into multiple paragraphs or otherwise rephrased.<br />
:::If you find it hard to follow a long sentence horizontally on a wide screen, we might consider enforcing some maximum width for the whole content. I think the readability would be better, since there would be more top-to-bottom eye movement at the cost of left-to-right-and-back.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:59, 15 October 2020 (UTC)<br />
<br />
== Xorg parentheses ==<br />
<br />
I actually think that X(org) is very useful to imply that it is one and the same thing.<br />
<br />
It might even be more confusing now, as we use both Xorg and X, because the wiki title and the package titles are Xorg.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:30, 17 October 2020 (UTC) G3ro<br />
<br />
:Well the conventions should be established on the [[Xorg]] page, not anywhere else... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:36, 17 October 2020 (UTC)<br />
<br />
:: Imo the conventions are established by upstream and they use a wide variety of X, X.org, X(org), Xorg etc.<br />
:: As I said I always prefer X(org) because then it is clear, that both are same thing.<br />
:: But ultimately it's your decision. <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:43, 17 October 2020 (UTC) G3ro<br />
<br />
:::When upstream is not capable of making a unambiguous decision, it makes sense that other projects pick some option and stick with it wherever they can to keep at least some consistency. So for this wiki, pages should use the same style as the [[Xorg]] page. But feel free to start a discussion about this in [[Talk:Xorg]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:56, 17 October 2020 (UTC)<br />
<br />
== SSHFS - systemd edit ==<br />
<br />
The edit was removed because "there is no advantage over using fstab entries".<br />
<br />
Is not only about the dis/advantages of the systemd option, is about that it is another possibility to achieve the task, that is why it was created in another level and the fstab section was left alone.<br />
<br />
Reconsider the edit as it presents another option which people can use.<br />
<br />
[[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 16:22, 22 October 2020 (UTC)<br />
<br />
:There is no need to use anything else, fstab just works well enough. Configuring mounts with systemd services is not a good idea - it is much more bloated than fstab and not the right tool for it. If anything, a different type of systemd units should be used: {{man|5|systemd.mount}}. But creating the mount units manually is still pretty useless since everything can be configured in fstab and systemd will generate the unit for you. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:22, 22 October 2020 (UTC)<br />
<br />
:: It is about the ability to use the user's .config file and all the proper options that are saved there. Also systemd gives the possibility to use different targets, so the user could mount it when an specific user logs in or when a graphical session starts. I could argue that bad a modification of fstab could lead to a system that doesnt boot, but such poorly configured systemd unit file just fails and the system is fine. Just give the user the information and let it decide what they can use depending on their use case. [[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 08:08, 24 October 2020 (UTC)<br />
<br />
:::You can configure systemd targets in fstab using the {{ic|x-systemd.wanted-by}} and {{ic|x-systemd.required-by}} options, there are also {{ic|nofail}} and {{ic|noauto}} options. Please read the {{man|5|systemd.mount}} manual.<br />
:::Using hosts from the user's {{ic|.ssh/config}} is the only thing which is not possible with fstab, but this does not warrant using the wrong tool for the task. Simple copy the full {{ic|user@hostname}} into fstab and you're done.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:47, 24 October 2020 (UTC)<br />
<br />
== [[Self-encrypting drives]] ==<br />
<br />
Hi, I'd like to respectfully disagree with the rollback. It's specific to sedutil that with most commands you need to input /dev/nvme0 (when encrypting the device) but for the sleep commands it requires /dev/nvme0n1 or it fails with a very unspecific error (Error saving the password to the kernel errno = 25), as found out in the discussion https://github.com/Drive-Trust-Alliance/sedutil/issues/90<br />
<br />
All in all I believe that it is important to keep this piece of information which was found out in a long discussion between the reporter and the developers. I ran into it and I believe many people may run into it, considering most of the new SSD will be NVMe. Best, [[User:Przemub|Przemub]] ([[User talk:Przemub|talk]]) 13:34, 28 October 2020 (UTC)<br />
<br />
:OK, then it makes sense. But it should be probably explained before, not in the section about the sleep command. Also please add the link to the note as a reference. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:27, 28 October 2020 (UTC)<br />
<br />
== Nvidia Installation ==<br />
<br />
The whole guide is unnecessary long and overcomplicated formulated.<br />
Shorter is better, most people will know their graphic card for example, so the determination etc. is only optional.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:21, 10 November 2020 (UTC) G3ro<br />
<br />
:Moving some info to some other page and leaving a tip behind does not make it shorter, but harder to follow. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:36, 10 November 2020 (UTC)<br />
<br />
== Btrfs layout ==<br />
<br />
Hi, Lahwaacz<br />
<br />
Thanks for maintaining [[Snapper]]! However I think the layout is not openSUSE specific and beneficial to all btrfs users. Can you elaborate your reason of undoing the edits? IMO the previous 'simple layout' complicates the rollback procedure.<br />
<br />
Cheers,<br />
[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 07:26, 3 December 2020 (UTC)<br />
<br />
:It is not overcomplicated, it is just doing things right. You can read about that in the forum thread, see the first note in [[Snapper#Suggested filesystem layout]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:24, 3 December 2020 (UTC)<br />
<br />
::Anyway I've moved the guides to my user page. It's not that I haven't read the 5-year-old forum post, it's that before the current layout I followed that post and resulted in a not fully rolled-back system. That post also sourced (then current) information from openSUSE. openSUSE has since massively overhauled the layout, as I pointed out in an edit you undid earlier.[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 09:02, 3 December 2020 (UTC)<br />
<br />
::Since last message I've extensively documented the new layout at [[User:I2Oc9/Btrfs_subvolumes]] and [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption]]. Have a look for yourself. Nothing new really, but IMO [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my take]] is much more simpler and complete than the supposedly [[Snapper#Restoring_/_to_a_previous_snapshot_of_@|simpler one]]. That one does not leverage native {{ic|snapper rollback}} or {{Pkg|grub-btrfs}}, among other things. I strongly suggest you try if you have time. [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 11:55, 3 December 2020 (UTC)<br />
<br />
::Actually if you look closely, none of [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my recovery methods]] is specific to [[User:I2Oc9/Btrfs_subvolumes#A_new_kind_of_layout|the new 'complex' layout]], it will work totally fine with the old one. I just don't think moving @ around in live environment is appropriate.<br />
<br />
::On the other hand, the layout recommendation has been updated by openSUSE [https://en.opensuse.org/SDB:BTRFS], why stick with the old one? [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 12:37, 3 December 2020 (UTC)<br />
<br />
:::The main reasons why I reverted your edits on the [[Snapper]] page are: 1) it was a huge change which was not discussed previously as required by [[ArchWiki:Contributing#The 3 fundamental rules]], and 2) it has some elements which do not apply to Arch (see below). If you wish to propose a better layout of the subvolumes, it should be discussed in [[Talk:Snapper]] first. Your user pages would serve as great drafts.<br />
:::Note that the current suggested layout is not ''flat'' in the sense of [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|your section]] - it has a separate subvolume for {{ic|.snapshots}} so it does not lead to the recursive mess. So your proposed layout seemed very similar to the current suggested layout. The real difference is which subvolume gets mounted at {{ic|/}}, but I did not find it explained anywhere on the Snapper page before I reverted the changes (I get it now from your user page). I also did not find a proper documentation of the openSUSE's layout - it seems to be just the product of their installer and the documentation only deals with the result, saying at most that [https://doc.opensuse.org/documentation/leap/reference/html/book.opensuse.reference/cha-snapper.html#sec-snapper-snapshot-boot the subvolume configuration must not be changed] for rollbacks to work.<br />
:::Now the openSUSE-specific elements: some Arch packages actually install software into {{ic|/opt}}, so the recommended layout should not suggest a separate subvolume for this path. Even more importantly, the pacman database is located at {{ic|/var/lib/pacman/local/}} and it must be rolled back along with the system, so there should be no separate subvolume for {{ic|/var}}. Instead, users should be encouraged to create (even nested) subvolumes for specific data directories under {{ic|/var}}, such as {{ic|/var/log}}, {{ic|/var/tmp}}, {{ic|/var/cache/pacman}}, {{ic|/var/lib/machines}}, etc.<br />
:::Finally, the suggested layout should not be GRUB-specific, there should be no recommendations regarding a boot loader. Sure it is useful to include non-trivial tips, but people may actually use a different boot loader.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:31, 4 December 2020 (UTC)<br />
<br />
::::Thanks for your detailed reply. I admit that I'm not knowledgeable on the intricate differences between distributions and shouldn't have made the changes without properly discussing them first.<br />
::::Yes, I get that the current layout is not [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|the one described in this section]] and indeed properly separates {{ic|/.snapshot}} and {{ic|/}}. The layout I proposed attempts to add some "niceties" such as supporting multi-distribution installations (complex and unnecessary, I agree) and bring the openSUSE layout here, which is a mistake, as you've pointed out.<br />
::::As for GRUB, since I use LUKS all the time and it's the only bootloader supporting encrypted {{ic|/boot}} on Btrfs on LUKS1, I really didn't think of any other possibilities.<br />
::::I will incorporate your recommendations to my user page and add a new section in [[Talk:Snapper]] pointing to those pages.<br />
::::Cheers -- [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:09, 4 December 2020 (UTC)<br />
<br />
:::::I've adopted [[Install_Arch_Linux_on_ZFS#System_datasets|Archlinux Root on ZFS layout]] to [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Create_subvolumes|my proposal]]. [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:56, 4 December 2020 (UTC)<br />
<br />
== Reflector Revert ==<br />
<br />
Hi Lahwaacz, about your [https://wiki.archlinux.org/index.php?title=Reflector&oldid=643749 revert], it seems like there's precedence for including AUR packages that replicate the code on the wiki. For example, in [[dash#Relinking /bin/sh]].<br />
<br />
In addition, I believe that there's value for linking the AUR package because it allows a simpler user experience where the AUR package is maintained for them. That way, if it is ever updated, they can easily fetch the update instead of religiously checking the wiki page (which most users probably don't do).<br />
<br />
Thanks!<br />
<br />
[[User:Denton-l|Denton-l]] ([[User talk:Denton-l|talk]]) 01:52, 7 December 2020 (UTC)<br />
<br />
:That precedence was only created by [https://wiki.archlinux.org/index.php?title=Dash&type=revision&diff=561587&oldid=518398 yourself]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:35, 5 May 2021 (UTC)<br />
<br />
== firefox zoom ==<br />
<br />
"no reason to zoom manually, see HiDPI)" - fractional scaling doesn't work [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 02:38, 26 December 2020 (UTC)<br />
<br />
:That should be explained in [[HiDPI#Firefox]] anyway. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:48, 26 December 2020 (UTC)<br />
<br />
::it's good to have this mentioned somewhere clearly so people know about it before they say "fonts on linux suck" [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 15:51, 29 December 2020 (UTC)<br />
<br />
== Intel GVT-g edits ==<br />
<br />
Hello Lahwaacz,<br />
<br />
I have noticed that you reverted one of the edits I have performed on [[Intel_GVT-g]].<br />
<br />
About this revert: [https://wiki.archlinux.org/index.php?title=Intel_GVT-g&oldid=648062 Windows problems are out of scope]<br />
<br />
While I understand that the ArchWiki is about ArchLinux, this article in particular mentions Windows in the introduction, and already includes another troubleshooting point about Windows. The issue I have encountered with the black bars is somewhat common, as I have found other people discussing it online, and I really fail to see why not including this piece of information in this article would be better than including it.<br />
<br />
Please, let me know your thoughts. If you think that the point can be improved, I will be happy to do that.<br />
<br />
Ciao,<br />
<br />
[[User:Wilcomir|Wilcomir]] ([[User talk:Wilcomir|talk]]) 09:14, 3 January 2021 (UTC)<br />
<br />
:Well, the existing section about a Windows problem is actually solved by configuring the Linux host. I think anything involving configuration or installation of programs in Windows is not appropriate for long troubleshooting sections. At most, they could be mentioned in a short reference to other sites which describe the problem in detail. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:34, 3 January 2021 (UTC)<br />
<br />
== XDG configuration for Vim ==<br />
<br />
Hi Lahwaacz,<br />
<br />
You have reverted the updated Notes for Vim on [[XDG Base Directory]], because "copy-pasted from a blog post".<br />
<br />
The problem is, not only is the configuration presented currently also copied from a blog post too, but is already 10 years old.<br />
<br />
Would it be OK, if we bring back the more up to date version? Or at least remove the obsolete one and leave link to newer?<br><br />
(Although I think a copy on wiki would be beneficial in case my blog ceases to exist)<br />
<br />
[[User:Jorengarenar|Jorengarenar]] ([[User talk:Jorengarenar|talk]]) 02:05, 12 January 2021 (UTC)<br />
<br />
== Root on ZFS draft ==<br />
<br />
Hi, I submitted [https://github.com/openzfs/openzfs-docs/pull/104 a Root on ZFS draft] to official doc repo.<br />
<br />
In the draft, the following directories are separated from root filesystem:<br />
home,root,srv,usr/local,var/log,var/spool,var/tmp<br />
<br />
Is this appropriate for Arch Linux? Or do you have any suggestion on the draft?<br />
Any comment is appreciated.<br />
[[User:M0p|M0p]] ([[User talk:M0p|talk]]) 01:28, 23 January 2021 (UTC)<br />
<br />
== Re: undo GRUB - Common installation errors ==<br />
<br />
Concerning your undo of [https://wiki.archlinux.org/index.php?title=GRUB&diff=next&oldid=649799 Add the error message `Could not prepare Boot variable: No space left on device`)]<br />
Is there a better place to for this Information? One can find the solution in various forums, but I thought it could be helpful to have it in this wiki somewhere. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 12:51, 25 January 2021 (UTC)<br />
<br />
:The error message is not specific to the {{ic|/sys/fs/pstore/}} filesystem (which does not even seem to be used by default on Arch...) Where did you find that? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:16, 25 January 2021 (UTC)<br />
<br />
::I did not find anything Arch specific, but this post about Debian helped: [https://donjajo.com/fix-grub-efibootmgr-not-set-variable-no-space-left-device/ Post]. I also found something about [https://askubuntu.com/questions/1072618/could-not-prepare-boot-variable-no-space-left-on-device-grub-install-error-ef /sys/fs/efi/efivars/dump-*] The problem is that the actual efi-partition does not seam to be the problem, there is more than 70% space left. If there is better information to guide the user in the right direction that wuld be more helpful. This is what I found worked, but I admit that I don't know much about how grub operates. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 16:20, 25 January 2021 (UTC)<br />
<br />
:::This wiki ''is'' Arch specific so old posts about Debian or Ubuntu do not apply. Even if they did, this is hardly a ''common'' installation problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:29, 26 January 2021 (UTC)<br />
<br />
::::I know that, and would not have put it there if it didn't occur on my Arch Linux installation. If this is something that should not be documented in this wiki, I understand that. Is there any other place you would recommend? An issue for grub-install maybe? [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 22:24, 26 January 2021 (UTC)<br />
<br />
== Kernel Compilation time ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Kernel&diff=next&oldid=650896 link]<br />
<br />
I don't think we should judge information by what is obvious to experts.<br />
People might have experience with compilation of other programs, which mostly is fast, and then there is the kernel which takes forever to compile.<br />
I think it does not hurt anyone to make people aware of it.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:03, 6 February 2021 (UTC)<br />
<br />
:It is an unnecessary information without a definite answer which can even be [https://html.duckduckgo.com/html?q=how%20long%20does%20it%20take%20to%20compile%20Linux%20kernel searched elsewhere]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:23, 6 February 2021 (UTC)<br />
<br />
:: I disagree, with that argument nearly any tip and note is unnecessary. These things are intended to inform users about things that should be taken into consideration and that are different from the norm.<br />
:: Also do you search for the compilation time for every program you intend to compile? I don't.<br />
:: Furthermore this info is included, why not tell it to people directly on the start, so they don't read over it? <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:36, 6 February 2021 (UTC)<br />
<br />
:::If someone wants to compile the Linux kernel, they should obviously expect that it will take ''some time''. Stating that it "can take up to several hours" does not make sense without referring to a specific hardware. Obviously, it will take much longer on a poor laptop than on a powerful workstation with a many-core processor, but people can assume that themselves. Without a reference to a specific hardware, the note is unnecessarily discouraging because the compilation can be as fast as some tens of minutes - it is by far not the most expensive package to compile...<br />
:::As you said, people can find better notes later along with advices to enable parallel build etc. which is all that's needed IMO.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:03, 6 February 2021 (UTC)<br />
<br />
== Wayland style ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Wayland&diff=prev&oldid=650979 link]<br />
<br />
I think in the old version it was much easier to read the "source code", so I don't see why there can't be spaces between it.<br />
Things shouldn't be complicated more than necessary.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:11, 6 February 2021 (UTC)<br />
<br />
:Most templates on the wiki are written without spaces around the |. When we [https://github.com/archlinux/archwiki/pull/32 switch the editor], there will even be syntax highlighting. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:25, 6 February 2021 (UTC)<br />
<br />
== Bluetooth keyboard ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php/Bluetooth_keyboard link]<br />
<br />
On your last change you said "not specific to keyboards, all of this is already mentioned on the Bluetooth page", the point is that this is extremely relevant for bluetooth keyboard since it is required to perform the login! If this little piece cannot be duplicated I would suggest at least to leave a link saying "If you want to autoconnect at boot please refer to...". I'm new here and I would not touch it further, but please evaluate the suggestion (this is because after reading bluetooth keyboard page and not finding the solution I had to look for it on forums)<br />
<br />
{{unsigned|21:17, 20 February 2021|Stevexyz}}<br />
<br />
:Well, basically the whole page is flagged to be merged with the main [[Bluetooth]] page, so it's expected to be incomplete. Other tips may always be found on a more general page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:40, 21 February 2021 (UTC)<br />
<br />
== Re: Steam Needs to be online error ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Steam/Troubleshooting&diff=next&oldid=653073 link]<br />
<br />
The problem here is that DNS resolution in general works already (yes even outside browsers), i.e. <br />
<br />
dig media.steampowered.com<br />
<br />
would run successfully, but the Steam client couldn’t resolve it. The DNS request from 'dig' shows up in my nameserver’s log, the one Steam should send doesn’t. This indicates it might indeed a problem specific to Steam, and it’s not as easy as just say "go fix your DNS resolution", as it already may work correctly for everything but Steam.<br />
<br />
Additionally, at no point does [[Domain name resolution]] even mention nscd, so you effectively removed a fix/workaround for the problem from the Wiki. So I was definitely not "duplicating an article" here. [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 08:12, 22 February 2021 (UTC)<br />
<br />
:Could I please hear your opinion on this? I’d be happy to just add something along the lines of "if you made sure DNS resolution works but Steam still can’t resolve it, try additionally enabling the nscd service" to the Steam troubleshooting page. Unfortounately I don’t know why running the service helps, but I’d still like to give others an easier time finding this solution than I had myself. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 09:15, 28 February 2021 (UTC)<br />
<br />
::Hi, I'm sorry for the delay. Could you test if using a different program for DNS caching (e.g. [[systemd-resolved]]) instead of {{ic|nscd.service}} fixes the problem? If not, then it's probably not due to DNS - {{man|8|nscd}} actually caches more than just DNS. Also if you have a reference to some website where you found about nscd, it would be nice to add it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 28 February 2021 (UTC)<br />
<br />
:::No worries. Using [[systemd-resolved]] for DNS resolution (and caching I guess, I wasn’t aware it does that, too) was a thing I did try, but that didn’t fix it for me. The place I found out about nscd fixing it was actually the [https://bbs.archlinux.org/viewtopic.php?id=263356 Arch forums]. When I search the web for Steam in combination with nscd, all I can seem to find are more forum entries of people that don’t know why that fixes it either. I can try a bit to find out what nscd does to make it work, but I’m not too confident I will be successful. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 14:51, 28 February 2021 (UTC)<br />
<br />
::::Okay, so {{ic|nscd}} allows to [https://man7.org/linux/man-pages/man5/nscd.conf.5.html dis-/enable caching per service], and it’s indeed enabling it for {{ic|hosts}} that makes it work. That’s weird though, since [[systemd-resolved]] has caching enabled by default, and using it for resolution didn’t make {{ic|steam}} work for me. Leads me to think that I didn’t set it up correctly, although resolving via {{ic|dig}} *did* work. Since [[steam]] depends on [[Name Service Switch]], I tried resolving using {{ic|getent}} manually with nscd disabled, but that worked while steam did not. I’m not really sure what to make of this, since I have no idea how this low level networking/resolving stuff works really. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 15:39, 28 February 2021 (UTC)<br />
<br />
:::::Hmm, I don't know the details either. Steam needs the multilib packages so maybe that's part of the problem. Could you add your findings to the section and use [[Template:Expansion]] for the missing details? Maybe someone can figure it out. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:44, 28 February 2021 (UTC)<br />
<br />
::::::Sure, I can do that. I’ll probably need a minute to figure out how to use the template though, but I should have the time later today. Thanks for your input on this. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 17:56, 28 February 2021 (UTC)<br />
<br />
== Removal of website link ==<br />
<br />
Refers to this: https://wiki.archlinux.org/index.php?title=PipeWire&diff=next&oldid=653701<br />
<br />
I don't understand why that has to be removed. The official website should be always worth a mention, even if it is somehow mentioned in the text already.<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:02, 28 February 2021 (UTC)<br />
<br />
:The "See also" section is for additional links, it is not intended as a collection of all links used on a page. Adding links which are clearly mentioned in the appropriate place only clutters the list. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:24, 28 February 2021 (UTC)<br />
<br />
:: There are just three links and only one of them is really useful, the others could maybe even be removed as they link to old blog posts.<br />
:: I can only repeat myself, that things don't always have to be made more complicated than necessary.<br />
:: The official website is a central point which links to many more useful ressources, so it's one link for much information.<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:34, 28 February 2021 (UTC)<br />
<br />
== Removal of bootia32.efi generation procedure from X205TA install page. ==<br />
<br />
Those [https://wiki.archlinux.org/index.php?title=ASUS_x205ta&diff=596239&oldid=562734 instructions] were really straightforward and useful, imho in comparison present ones require too much material to be confident with. I think it's (paradoxically) way easier to generate the file than to configure a `grub.cfg` from zero to boot a live cd. Can we undo the edit? Otherwise we could put them in a new page or section in the GRUB page and link to them maybe. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 05:07, 4 March 2021 (UTC)<br />
<br />
:If there is something wrong with the information on the [https://wiki.archlinux.org/index.php/Unified_Extensible_Firmware_Interface#Booting_64-bit_kernel_on_32-bit_UEFI general page], it should be improved instead of describing the same procedure in a different way on a completely unrelated page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:16, 6 March 2021 (UTC)<br />
<br />
:: I didn't know we had that info in the UEFI article. I think it could be appropriate to insert the [https://en.wikipedia.org/wiki/Template:See_also#Examples See also] archwiki equivalent (which I couldn't find) for UEFI page on top of the aforementioned section, what do you think? [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 13:28, 7 March 2021 (UTC)<br />
<br />
:::Well, the removed section was previously flagged with "Duplicates [[Unified Extensible Firmware Interface#Booting 64-bit kernel on 32-bit UEFI]]"...<br />
:::Also the laptops pages are usually related to most of the general pages on this wiki, adding all of them would be pretty useless. Users should not expect to find everything on a single laptop page, they should always check if there is a general page for their topic with more details.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:58, 7 March 2021 (UTC)<br />
<br />
== Re: Show how to use systemd/Timers with wg-quick@.service ==<br />
<br />
I don't think using service is the appropriate when you want to start Wireguard at boot. For most people connecting to a VPN is not exactly part system startup.<br />
A timer should more appropriate.<br />
[[User:ENV25|ENV25]] ([[User talk:ENV25|talk]]) 10:03, 11 April 2021 (UTC)<br />
<br />
:I don't see how OnBootSec=1min is more appropriate than an automatically starting service. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:19, 11 April 2021 (UTC)<br />
<br />
'''Bold text'''== USB flash installation medium (BIOS bootable) ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=USB_flash_installation_medium&diff=next&oldid=673926 revert]: "making the partition bootable is discussed below"<br />
Do you mean installing syslinux and `dd` the [gpt]mbr with "discussed below"? This was not enought for my setup (Sandisk Ultra 64GB, Dell XPS 9370) to make the partition BIOS bootable. It did work right after I checked "Legacy BIOS Bootable" checkbox using gnome-disks.<br />
<br />
{{Unsigned|13:42, 30 May 2021 (UTC)|Auipga}}<br />
<br />
:Yes, that's what I meant. If it does not work, it should be fixed rather than providing a duplicate instruction without a reason. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:16, 30 May 2021 (UTC)<br />
<br />
== Systemd-networkd systemd-networkd-wait-online.service discussion modifications ==<br />
<br />
I'm not sure why you're reverting my edits.<br />
<br />
You said: "''empty ExecStart is explained in Systemd#Examples''"<br />
<br />
Exactly: Systemd#Examples clearly states "''As another example, in order to replace the ExecStart directive for a unit that is '''not of type oneshot'''''"<br />
<br />
'''systemd-networkd-wait-online''' is a oneshot service. By having the superfluous empty ExecStart you're just confusing people.<br />
<br />
Regarding the file naming, yes the name is irrelevant, but it's generally helpful to non-expert users to stick to canonical naming conventions.<br />
<br />
Please make sure you're on solid ground before reverting edits; you're just discouraging people from engaging with the Wiki. Thanks. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 16:51, 9 June 2021 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Systemd-networkd&diff=678327Systemd-networkd2021-06-09T16:33:29Z<p>Pgoetz: /* systemd-networkd-wait-online */ Modified text to be more inline with the directives outlined in the man page.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network managers]]<br />
[[Category:Virtualization]]<br />
[[de:Systemd/systemd-networkd]]<br />
[[es:Systemd-networkd]]<br />
[[ja:systemd-networkd]]<br />
[[ru:Systemd-networkd]]<br />
[[zh-hans:Systemd-networkd]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|systemd-resolved}}<br />
{{Related|systemd-nspawn}}<br />
{{Related|Network bridge}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|:Category:Network configuration}}<br />
{{Related articles end}}<br />
<br />
''systemd-networkd'' is a system daemon that manages network configurations. It detects and configures network devices as they appear; it can also create virtual network devices. This service can be especially useful to set up complex network configurations for a container managed by [[systemd-nspawn]] or for virtual machines. It also works fine on simple connections.<br />
<br />
== Basic usage ==<br />
<br />
The {{Pkg|systemd}} package is part of the default Arch installation and contains all needed files to operate a wired network. Wireless adapters, covered later in this article, can be set up by services, such as [[wpa_supplicant]] or [[iwd]].<br />
<br />
=== Required services and setup ===<br />
<br />
To use ''systemd-networkd'', [[start/enable]] {{ic|systemd-networkd.service}}.<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.}}<br />
<br />
It is optional to also configure [[systemd-resolved]], which is a network name resolution service to local applications, considering the following points:<br />
<br />
* It is important to understand how [[resolv.conf]] and ''systemd-resolved'' interact to properly configure the DNS that will be used, some explanations are provided in [[systemd-resolved]].<br />
* ''systemd-resolved'' is required if DNS entries are specified in ''.network'' files.<br />
* ''systemd-resolved'' is also required if you want to obtain DNS addresses from DHCP servers or IPv6 router advertisements.<br>(by setting ({{ic|1=DHCP=}} and/or {{ic|1=IPv6AcceptRA=}} in the {{ic|[Network]}} section, and {{ic|1=UseDNS=yes}} (the default) in the corresponding section(s) {{ic|[DHCPv4]}}, {{ic|[DHCPv6]}}, {{ic|[IPv6AcceptRA]}}, see {{man|5|systemd.network}}).<br />
* Note that ''systemd-resolved'' can also be used without ''systemd-networkd''.<br />
<br />
=== systemd-networkd-wait-online ===<br />
<br />
Enabling {{ic|systemd-networkd.service}} also enables {{ic|systemd-networkd-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 be started 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|systemd-networkd-wait-online.service}} waits for all links it is aware of and which are managed by ''systemd-networkd'' to be fully configured or failed, and for at least one link to be online.<br />
<br />
If your system has multiple network interfaces, but some are not expected to be connected all the time (e.g. if you have a dual-port Ethernet card, but only one cable plugged in), starting {{ic|systemd-networkd-wait-online.service}} will fail after the default timeout of 2 minutes. This may cause an unwanted delay in the startup process. To change the behaviour to wait for ''any'' interface rather than ''all'' interfaces to become online, [[edit]] the service and add the {{ic|--any}} parameter to the {{ic|ExecStart}} line:<br />
<br />
{{hc|/etc/systemd/system/systemd-networkd-wait-online.service.d/wait-for-only-one-interface.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --any<br />
}}<br />
<br />
Other behaviour such as which specific interface(s) to wait for or the operational state can be configured as well. See {{man|8|systemd-networkd-wait-online}} for the available parameters.<br />
<br />
=== Configuration examples ===<br />
<br />
All configurations in this section are stored as {{ic|foo.network}} in {{ic|/etc/systemd/network/}}. For a full listing of options and processing order, see [[#Configuration files]] and {{man|5|systemd.network}}.<br />
<br />
systemd/udev automatically assigns predictable, stable network interface names for all local Ethernet, WLAN, and WWAN interfaces. Use {{ic|networkctl list}} to list the devices on the system.<br />
<br />
After making changes to a configuration file, [[restart]] {{ic|systemd-networkd.service}}.<br />
<br />
{{Note|<br />
* The options specified in the configuration files are case sensitive.<br />
* In the examples below, {{ic|enp1s0}} is the wired adapter and {{ic|wlp2s0}} is the wireless adapter. These names can be different on different systems. See [[Network configuration#Network interfaces]] for checking your adapter names.<br />
* It is also possible to use a wildcard, e.g. {{ic|1=Name=en*}} or {{ic|1=Name=wl*}}.<br />
* Devices can also be matched by their type. E.g. {{ic|1=Type=ether}} for Ethernet, {{ic|1=Type=wlan}} for Wi-Fi and {{ic|1=Type=wwan}} for WWAN. Note that {{ic|1=Type=ether}} will also match virtual Ethernet interfaces ({{ic|veth*}}), which may be undesirable.<br />
* If you want to disable IPv6, see [[IPv6#systemd-networkd_3|IPv6#systemd-networkd]].<br />
}}<br />
<br />
==== Wired adapter using DHCP ====<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
DHCP=yes<br />
}}<br />
<br />
==== Wired adapter using a static IP ====<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
Address=10.1.10.9/24<br />
Gateway=10.1.10.1<br />
DNS=10.1.10.1<br />
}}<br />
<br />
{{ic|1=Address=}} can be used more than once to configure multiple IPv4 or IPv6 addresses. See [[#network files]] or {{man|5|systemd.network}} for more options.<br />
<br />
==== Wireless adapter ====<br />
<br />
In order to connect to a wireless network with ''systemd-networkd'', a wireless adapter configured with another application such as [[wpa_supplicant]] or [[iwd]] is required.<br />
<br />
{{hc|/etc/systemd/network/25-wireless.network|2=<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=yes<br />
}}<br />
<br />
If the wireless adapter has a static IP address, the configuration is the same (except for the interface name) as in a [[#Wired adapter using a static IP|wired adapter]].<br />
<br />
To authenticate to the wireless network, use e.g. [[wpa_supplicant]] or [[iwd]].<br />
<br />
==== Wired and wireless adapters on the same machine ====<br />
<br />
This setup will enable a DHCP IP for both a wired and wireless connection making use of the metric directive to allow the kernel to decide on-the-fly which one to use. This way, no connection downtime is observed when the wired connection is unplugged.<br />
<br />
The kernel's route metric (same as configured with ''ip'') decides which route to use for outgoing packets, in cases when several match. This will be the case when both wireless and wired devices on the system have active connections. To break the tie, the kernel uses the metric. If one of the connections is terminated, the other automatically wins without there being a gap with nothing configured (ongoing transfers may still not deal with this nicely but that is at a different OSI layer).<br />
<br />
{{Note|The {{ic|Metric}} option is for static routes while the {{ic|RouteMetric}} option is for setups not using static routes. See {{man|5|systemd.network}} for more details.}}<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
DHCP=yes<br />
<br />
[DHCP]<br />
RouteMetric=10}}<br />
<br />
{{hc|/etc/systemd/network/25-wireless.network|2=<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=yes<br />
<br />
[DHCP]<br />
RouteMetric=20<br />
}}<br />
<br />
==== Renaming an interface ====<br />
<br />
Instead of [[Network configuration#Change interface name|editing udev rules]], a ''.link'' file can be used to rename an interface. A useful example is to set a predictable interface name for a USB-to-Ethernet adapter based on its MAC address, as those adapters are usually given different names depending on which USB port they are plugged into.<br />
<br />
{{hc|head=/etc/systemd/network/10-ethusb0.link|output=<br />
[Match]<br />
MACAddress=12:34:56:78:90:ab<br />
<br />
[Link]<br />
Description=USB to Ethernet Adapter<br />
Name=ethusb0<br />
}}<br />
<br />
{{Note|Any user-supplied ''.link'' '''must''' have a lexically earlier file name than the default config {{ic|99-default.link}} in order to be considered at all. For example, name the file {{ic|10-ethusb0.link}} and not {{ic|ethusb0.link}}.}}<br />
<br />
== Configuration files ==<br />
<br />
Configuration files are located in {{ic|/usr/lib/systemd/network/}}, the volatile runtime network directory {{ic|/run/systemd/network/}} and the local administration network directory {{ic|/etc/systemd/network/}}. Files in {{ic|/etc/systemd/network/}} have the highest priority.<br />
<br />
There are three types of configuration files. They all use a format similar to [[systemd#Writing unit files|systemd unit files]]. <br />
<br />
* ''.network'' files. They will apply a network configuration for a ''matching'' device<br />
* ''.netdev'' files. They will create a ''virtual network device'' for a ''matching'' environment<br />
* ''.link'' files. When a network device appears, [[udev]] will look for the first ''matching'' ''.link'' file<br />
<br />
They all follow the same rules: <br />
<br />
* If '''all''' conditions in the {{ic|[Match]}} section are matched, the profile will be activated<br />
* an empty {{ic|[Match]}} section means the profile will apply in any case (can be compared to the {{ic|*}} wildcard)<br />
* all configuration files are collectively sorted and processed in lexical order, regardless of the directory in which they live<br />
* files with identical name replace each other<br />
<br />
{{Tip|<br />
* Files in {{ic|/etc/systemd/network/}} override the corresponding system-supplied file in {{ic|/usr/lib/systemd/network/}}. You can also create a symlink to {{ic|/dev/null}} to "mask" a system file.<br />
* systemd accepts the values {{ic|1, true, yes, on}} for a true boolean, and the values {{ic|0, false, no, off}} for a false boolean<br />
}}<br />
<br />
=== network files ===<br />
<br />
{{Remove|Duplicates the {{man|5|systemd.network}} man page.}}<br />
<br />
These files are aimed at setting network configuration variables, especially for servers and containers.<br />
<br />
''.network'' files have the following sections: {{ic|[Match]}}, {{ic|[Link]}}, {{ic|[Network]}}, {{ic|[Address]}}, {{ic|[Route]}}, and {{ic|[DHCP]}}. Below are commonly configured keys for each section. See {{man|5|systemd.network}} for more information and examples.<br />
<br />
==== [Match] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=Name=}} || Match device names, e.g. {{ic|en*}}. By prefixing with {{ic|!}}, the list can be inverted. || white-space separated device names with globs, logical negation ({{ic|!}}) ||<br />
|-<br />
| {{ic|1=MACAddress=}} || Match MAC addresses, e.g. {{ic|1=MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF}} || whitespace-separated MAC addresses in full colon-, hyphen- or dot-delimited hexadecimal || <br />
|-<br />
| {{ic|1=Host=}} || Match the hostname or machine ID of the host. || hostname string with globs, {{man|5|machine-id}} ||<br />
|-<br />
| {{ic|1=Virtualization=}} || Check whether the system is executed in a virtualized environment. {{ic|1=Virtualization=false}} will only match your host machine, while {{ic|1=Virtualization=true}} matches any container or VM. It is possible to check for a specific virtualization type or implementation, or for a user namespace (with {{ic|private-users}}). || boolean, logical negation ({{ic|!}}), type ({{ic|vm}}, {{ic|container}}), implementation ({{ic|qemu}}, {{ic|kvm}}, {{ic|zvm}}, {{ic|vmware}}, {{ic|microsoft}}, {{ic|oracle}}, {{ic|powervm}}, {{ic|xen}}, {{ic|bochs}}, {{ic|uml}}, {{ic|bhyve}}, {{ic|qnx}}, {{ic|openvz}}, {{ic|lxc}}, {{ic|lxc-libvirt}}, {{ic|systemd-nspawn}}, {{ic|docker}}, {{ic|podman}}, {{ic|rkt}}, {{ic|wsl}}, {{ic|proot}}, {{ic|pouch}}, {{ic|acrn}}), {{ic|private-users}} ||<br />
|}<br />
<br />
==== [Link] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=MACAddress=}} || Assign a hardware address to the device. Useful for [[MAC_address_spoofing#systemd-networkd|MAC address spoofing]]. || full colon-, hyphen- or dot-delimited hexadecimal MAC addresses ||<br />
|-<br />
| {{ic|1=MTUBytes=}} || Maximum transmission unit in bytes to set for the device. Note that if IPv6 is enabled on the interface, and the MTU is chosen below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value. Setting a larger MTU value (e.g. when using [[jumbo frames]]) can significantly speed up your network transfers || integer (usual suffixes K, M, G, are supported and are understood to the base of 1024) ||<br />
|-<br />
| {{ic|1=Multicast=}} || allows the usage of [[wikipedia:Multicast_address|multicast]] || boolean || ? not documented ?<br />
|}<br />
<br />
==== [Network] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=DHCP=}} || Controls DHCPv4 and/or DHCPv6 client support. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DHCPServer=}} || If enabled, a DHCPv4 server will be started. || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=MulticastDNS=}} || Enables [https://tools.ietf.org/html/rfc6762 multicast DNS] support. When set to {{ic|resolve}}, only resolution is enabled, but not host or service registration and announcement. || boolean, {{ic|resolve}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DNSSEC=}} || Controls DNSSEC DNS validation support on the link. When set to {{ic|allow-downgrade}}, compatibility with non-DNSSEC capable networks is increased, by automatically turning off DNSSEC in this case. || boolean, {{ic|allow-downgrade}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DNS=}} || Configure static [[DNS]] addresses. May be specified more than once. || {{man|3|inet_pton}} ||<br />
|-<br />
| {{ic|1=Domains=}} || A list of domains which should be resolved using the DNS servers on this link. [https://www.freedesktop.org/software/systemd/man/systemd.network.html#Domains= more information] || domain name, optionally prefixed with a tilde ({{ic|~}}) ||<br />
|-<br />
| {{ic|1=IPForward=}} || If enabled, incoming packets on any network interface will be forwarded to any other interfaces according to the routing table. See [[Internet sharing#Enable packet forwarding]] for details. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}<br />
|-<br />
| {{ic|1=IPMasquerade=}} || If enabled, packets forwarded from the network interface will appear as coming from the local host. Depending on the value, implies {{ic|1=IPForward=ipv4}}, {{ic|1=IPForward=ipv6}} or {{ic|1=IPForward=yes}}. || {{ic|ipv4}}, {{ic|ipv6}}, {{ic|both}}, {{ic|no}} || {{ic|no}}<br />
|-<br />
| {{ic|1=IPv6PrivacyExtensions=}} || Configures use of stateless temporary addresses that change over time (see [https://tools.ietf.org/html/rfc4941 RFC 4941]). When {{ic|prefer-public}}, enables the privacy extensions, but prefers public addresses over temporary addresses. When {{ic|kernel}}, the kernel's default setting will be left in place. || boolean, {{ic|prefer-public}}, {{ic|kernel}} || {{ic|false}}<br />
|}<br />
<br />
==== [Address] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=Address=}} || Specify this key more than once to configure several addresses. Mandatory unless DHCP is used. If the specified address is {{ic|0.0.0.0}} (for IPv4) or {{ic|::}} (for IPv6), a new address range of the requested size is automatically allocated from a system-wide pool of unused ranges. || static IPv4 or IPv6 address and its prefix length (see {{man|3|inet_pton}}) ||<br />
|}<br />
<br />
==== [Route] ====<br />
<br />
* {{ic|1=Gateway=}} this option is '''mandatory''' unless DHCP is used<br />
* {{ic|1=Destination=}} the destination prefix of the route, possibly followed by a slash and the prefix length <br />
<br />
If {{ic|Destination}} is not present in {{ic|[Route]}} section this section is treated as a default route.<br />
<br />
{{Tip|You can put the {{ic|1=Address=}} and {{ic|1=Gateway=}} keys in the {{ic|[Network]}} section as a short-hand if {{ic|[Address]}} section contains only an {{ic|Address}} key and {{ic|[Route]}} section contains only a {{ic|Gateway}} key.}}<br />
<br />
==== [DHCP] ====<br />
<br />
{{Out of date|{{ic|[DHCP]}} [https://github.com/systemd/systemd/pull/13006 has been split] into {{ic|[DHCPv4]}} and {{ic|[DHCPv6]}}.}}<br />
<br />
{| class = "wikitable<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=UseDNS=}} || controls whether the DNS servers advertised by the DHCP server are used || boolean || {{ic|true}}<br />
|-<br />
| {{ic|1=Anonymize=}} || when true, the options sent to the DHCP server will follow the [https://tools.ietf.org/html/rfc7844 RFC7844] (Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=UseDomains=}} || controls whether the domain name received from the DHCP server will be used as DNS search domain. If set to {{ic|route}}, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching. This option can sometimes fix local name resolving when using [[systemd-resolved]] || boolean, {{ic|route}} || {{ic|false}}<br />
|}<br />
<br />
==== [DHCPServer] ====<br />
<br />
This is an example of a DHCP server configuration which works well with [[hostapd]] to create a wireless hotspot. {{ic|IPMasquerade}} adds the firewall rules for [[Internet sharing#Enable NAT|NAT]] and implies {{ic|1=IPForward=ipv4}} to enable [[Internet sharing#Enable packet forwarding|packet forwarding]].<br />
<br />
{{Accuracy|{{ic|1=IPMasquerade=true}} does not add the rules for the {{ic|filter}} table, they have to be added manually. See [[systemd-nspawn#Use a virtual Ethernet link]].}}<br />
<br />
{{hc|/etc/systemd/network/''wlan0''.network|<nowiki><br />
[Match]<br />
Name=wlan0<br />
<br />
[Network]<br />
Address=10.1.1.1/24<br />
DHCPServer=true<br />
IPMasquerade=true<br />
<br />
[DHCPServer]<br />
PoolOffset=100<br />
PoolSize=20<br />
EmitDNS=yes<br />
DNS=9.9.9.9<br />
</nowiki>}}<br />
<br />
=== netdev files ===<br />
<br />
{{Remove|Duplicates the {{man|5|systemd.netdev}} man page.}}<br />
<br />
These files will create virtual network devices. They have two sections: {{ic|[Match]}} and {{ic|[NetDev]}}. Below are commonly configured keys for each section. See {{man|5|systemd.netdev}} for more information and examples.<br />
<br />
==== [Match] section ====<br />
<br />
* {{ic|1=Host=}} the hostname<br />
* {{ic|1=Virtualization=}} check if the system is running in a virtualized environment<br />
<br />
==== [NetDev] section ====<br />
<br />
Most common keys are:<br />
<br />
* {{ic|1=Name=}} the interface name. '''mandatory'''<br />
* {{ic|1=Kind=}} e.g. ''bridge'', ''bond'', ''vlan'', ''veth'', ''sit'', etc. '''mandatory'''<br />
<br />
=== link files ===<br />
<br />
{{Remove|Duplicates the {{man|5|systemd.link}} man page.}}<br />
<br />
These files are an alternative to custom udev rules and will be applied by [[udev]] as the device appears. They have two sections: {{ic|[Match]}} and {{ic|[Link]}}. Below are commonly configured keys for each section. See {{man|5|systemd.link}} for more information and examples.<br />
<br />
{{Tip|Use {{ic|udevadm test-builtin net_setup_link /sys/path/to/network/device}} as the root user to diagnose problems with ''.link'' files.}}<br />
<br />
==== [Match] section ====<br />
<br />
* {{ic|1=MACAddress=}} the MAC address<br />
* {{ic|1=Host=}} the host name<br />
* {{ic|1=Virtualization=}} <br />
* {{ic|1=Type=}} the device type e.g. vlan<br />
<br />
==== [Link] section ====<br />
<br />
* {{ic|1=MACAddressPolicy=}} persistent or random addresses, or<br />
* {{ic|1=MACAddress=}} a specific address<br />
* {{ic|1=NamePolicy=}} list of policies by which the interface name should be set, e.g. kernel, keep<br />
<br />
{{Note|the system {{ic|/usr/lib/systemd/network/99-default.link}} is generally sufficient for most of the basic cases.}}<br />
<br />
== Usage with containers ==<br />
<br />
''systemd-networkd'' can provide fully automatic configuration of networking for [[systemd-nspawn]] containers when it is used on the host system as well as inside the container. See [[systemd-nspawn#Networking]] for a comprehensive overview.<br />
<br />
For the examples below, <br />
* we will limit the output of the {{ic|ip a}} command to the concerned interfaces.<br />
* we assume the ''host'' is your main OS you are booting to and the ''container'' is your guest virtual machine.<br />
* all interface names and IP addresses are only examples.<br />
<br />
=== Network bridge with DHCP ===<br />
<br />
==== Bridge interface ====<br />
<br />
First, create a virtual [[bridge]] interface. We tell systemd to create a device named ''br0'' that functions as an ethernet bridge.<br />
<br />
{{hc|/etc/systemd/network/''mybridge''.netdev|2=<br />
[NetDev]<br />
Name=br0<br />
Kind=bridge}}<br />
<br />
{{Tip|''systemd-networkd'' assigns a MAC address generated based on the interface name and the machine ID to the bridge. This may cause connection issues, for example in case of routing based on MAC filtering. To circumvent such problems you may assign a MAC address to your bridge, probably the same as your physical device, adding the line {{ic|1=MACAddress=xx:xx:xx:xx:xx:xx}} in the ''NetDev'' section above.}}<br />
<br />
[[Restart]] {{ic|systemd-networkd.service}} to have systemd create the bridge.<br />
<br />
To see the newly created bridge on the host and on the container, type:<br />
<br />
{{hc|$ ip a|<br />
3: br0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default <br />
link/ether ae:bd:35:ea:0c:c9 brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
Note that the interface ''br0'' is listed but is still DOWN at this stage.<br />
<br />
==== Bind Ethernet to bridge ====<br />
<br />
The next step is to add to the newly created bridge a network interface. In the example below, we add any interface that matches the name ''en*'' into the bridge ''br0''.<br />
<br />
{{hc|/etc/systemd/network/''bind''.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
Bridge=br0<br />
}}<br />
<br />
The Ethernet interface must not have DHCP or an IP address associated as the bridge requires an interface to bind to with no IP: modify the corresponding {{ic|/etc/systemd/network/''MyEth''.network}} accordingly to remove the addressing.<br />
<br />
==== Bridge network ====<br />
<br />
Now that the bridge has been created and has been bound to an existing network interface, the IP configuration of the bridge interface must be specified. This is defined in a third ''.network'' file, the example below uses DHCP.<br />
<br />
{{hc|/etc/systemd/network/''mybridge''.network|2=<br />
[Match]<br />
Name=br0<br />
<br />
[Network]<br />
DHCP=ipv4}}<br />
<br />
==== Configure the container ====<br />
<br />
Use the {{ic|1=--networkd-bridge=br0}} option when starting the container. See [[systemd-nspawn#Use a network bridge]] for details.<br />
<br />
==== Result ====<br />
<br />
* on host<br />
<br />
{{hc|$ ip a|<br />
3: br0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default <br />
link/ether 14:da:e9:b5:7a:88 brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.1.87/24 brd 192.168.1.255 scope global br0<br />
valid_lft forever preferred_lft forever<br />
inet6 fe80::16da:e9ff:feb5:7a88/64 scope link <br />
valid_lft forever preferred_lft forever<br />
6: vb-''MyContainer'': <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master br0 state UP group default qlen 1000<br />
link/ether d2:7c:97:97:37:25 brd ff:ff:ff:ff:ff:ff<br />
inet6 fe80::d07c:97ff:fe97:3725/64 scope link <br />
valid_lft forever preferred_lft forever<br />
}}<br />
<br />
* on container<br />
<br />
{{hc|$ ip a|<br />
2: host0: <BROADCAST,MULTICAST,ALLMULTI,AUTOMEDIA,NOTRAILERS,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000<br />
link/ether 5e:96:85:83:a8:5d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.1.73/24 brd 192.168.1.255 scope global host0<br />
valid_lft forever preferred_lft forever<br />
inet6 fe80::5c96:85ff:fe83:a85d/64 scope link <br />
valid_lft forever preferred_lft forever<br />
}}<br />
<br />
==== Notice ====<br />
<br />
* we have now one IP address for {{ic|br0}} on the host, and one for {{ic|host0}} in the container<br />
* two new interfaces have appeared: {{ic|vb-''MyContainer''}} in the host and {{ic|host0}} in the container. This comes as a result of the {{ic|1=--network-bridge=br0}} option as explained in [[systemd-nspawn#Use a network bridge]] for details.<br />
* the DHCP address on {{ic|host0}} comes from the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file.<br />
* on host<br />
<br />
{{Out of date|''brctl'' is deprecated, use {{ic|bridge link}}. See [[Network bridge#With iproute2]].}}<br />
{{hc|$ brctl show|<br />
bridge name bridge id STP enabled interfaces<br />
br0 8000.14dae9b57a88 no enp7s0<br />
vb-''MyContainer''<br />
}}<br />
<br />
the above command output confirms we have a bridge with two interfaces binded to.<br />
<br />
* on host<br />
<br />
{{hc|$ ip route|<br />
default via 192.168.1.254 dev br0 <br />
192.168.1.0/24 dev br0 proto kernel scope link src 192.168.1.87<br />
}}<br />
<br />
* on container<br />
<br />
{{hc|$ ip route|<br />
default via 192.168.1.254 dev host0 <br />
192.168.1.0/24 dev host0 proto kernel scope link src 192.168.1.73<br />
}}<br />
<br />
the above command outputs confirm we have activated {{ic|br0}} and {{ic|host0}} interfaces with an IP address and Gateway 192.168.1.254. The gateway address has been automatically grabbed by ''systemd-networkd''.<br />
<br />
=== Network bridge with static IP addresses ===<br />
<br />
Setting a static IP address for each device can be helpful in case of deployed web services (e.g FTP, http, SSH). Each device will keep the same MAC address across reboots if your system {{ic|/usr/lib/systemd/network/99-default.link}} file has the {{ic|1=MACAddressPolicy=persistent}} option (it has by default). Thus, you will easily route any service on your Gateway to the desired device.<br />
<br />
The following configuration needs to be done for this setup:<br />
<br />
* on host <br />
<br />
The configuration is very similar to the [[#Network bridge with DHCP]] section. First, a virtual bridge interface needs to be created and the main physical interface needs to be bound to it. This task can be accomplished with the following two files, with contents equal to those available in the DHCP section.<br />
<br />
/etc/systemd/network/''MyBridge''.netdev<br />
/etc/systemd/network/''MyEth''.network<br />
<br />
Next, you need to configure the IP and DNS of the newly created virtual bridge interface. For example:<br />
<br />
{{hc|/etc/systemd/network/''MyBridge''.network|<nowiki><br />
[Match]<br />
Name=br0<br />
<br />
[Network]<br />
DNS=192.168.1.254<br />
Address=192.168.1.87/24<br />
Gateway=192.168.1.254<br />
</nowiki>}}<br />
<br />
* on container<br />
<br />
To get configure a static IP address on the container, we need to override the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file, which provides a DHCP configuration for the {{ic|host0}} network interface of the container. This can be done by placing the configuration into {{ic|/etc/systemd/network/80-container-host0.network}}. For example:<br />
<br />
{{hc|/etc/systemd/network/80-container-host0.network|2=<br />
[Match]<br />
Name=host0<br />
<br />
[Network]<br />
DNS=192.168.1.254<br />
Address=192.168.1.94/24<br />
Gateway=192.168.1.254<br />
}}<br />
<br />
Make sure that {{ic|systemd-networkd.service}} is [[enabled]] in the container.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Interface and desktop integration ===<br />
<br />
''systemd-networkd'' does not have a proper interactive management interface neither via [[command-line shell]] nor graphical.<br />
<br />
Still, some tools are available to either display the current state of the network, receive notifications or interact with the wireless configuration:<br />
<br />
* ''networkctl'' (via CLI) offers a simple dump of the network interface states.<br />
* When ''networkd'' is configured with [[wpa_supplicant]], both ''wpa_cli'' and ''wpa_gui'' offer the ability to associate and configure WLAN interfaces dynamically.<br />
* {{AUR|networkd-notify-git}} can generate simple notifications in response to network interface state changes (such as connection/disconnection and re-association).<br />
* The {{AUR|networkd-dispatcher}} daemon allows executing scripts in response to network interface state changes, similar to ''NetworkManager-dispatcher''.<br />
* As for the DNS resolver ''systemd-resolved'', information about current DNS servers can be visualized with {{ic|resolvectl status}}.<br />
<br />
=== Configuring static IP or DHCP based on SSID (location) ===<br />
<br />
Often there is a situation where your home wireless network uses DHCP and office wireless network uses static IP. This mixed setup can be configured as follows:<br />
<br />
{{Note|Number in the file name decides the order in which the files are processed. You can [Match] based on SSID or BSSID or both.}}<br />
<br />
{{hc|/etc/systemd/network/24-wireless-office.network|<nowiki><br />
# special configuration for office WiFi network<br />
[Match]<br />
Name=wlp2s0<br />
SSID=office_ap_name<br />
#BSSID=aa:bb:cc:dd:ee:ff<br />
<br />
[Network]<br />
Address=10.1.10.9/24<br />
Gateway=10.1.10.1<br />
DNS=10.1.10.1<br />
#DNS=8.8.8.8<br />
</nowiki>}}<br />
<br />
{{hc|/etc/systemd/network/25-wireless-dhcp.network|<nowiki><br />
# use DHCP for any other WiFi network<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=ipv4<br />
</nowiki>}}<br />
<br />
=== Bonding a wired and wireless interface ===<br />
<br />
See also [[Wireless bonding]].<br />
<br />
Bonding allows connection sharing through multiple interfaces, so if e.g. the wired interface is unplugged, the wireless is still connected and the network connectivity remains up seamlessly.<br />
<br />
Create a bond interface. In this case the mode is ''active-backup'', which means packets are routed through a secondary interface if the primary interface goes down.<br />
<br />
{{hc|/etc/systemd/network/30-bond0.netdev|<nowiki><br />
[NetDev]<br />
Name=bond0<br />
Kind=bond<br />
<br />
[Bond]<br />
Mode=active-backup<br />
PrimaryReselectPolicy=always<br />
MIIMonitorSec=1s<br />
</nowiki>}}<br />
<br />
Set the wired interface as the primary:<br />
<br />
{{hc|/etc/systemd/network/30-ethernet-bond0.network|<nowiki><br />
[Match]<br />
Name=enp0s25<br />
<br />
[Network]<br />
Bond=bond0<br />
PrimarySlave=true<br />
</nowiki>}}<br />
<br />
Set the wireless as the secondary:<br />
<br />
{{hc|/etc/systemd/network/30-wifi-bond0.network|<nowiki><br />
[Match]<br />
Name=wlan0<br />
<br />
[Network]<br />
Bond=bond0<br />
</nowiki>}}<br />
<br />
Configure the bond interface as you would a normal interface:<br />
<br />
{{hc|/etc/systemd/network/30-bond0.network|<nowiki><br />
[Match]<br />
Name=bond0<br />
<br />
[Network]<br />
DHCP=ipv4<br />
</nowiki>}}<br />
<br />
Now if the wired network is unplugged, the connection should remain through the wireless:<br />
<br />
{{hc|$ networkctl|<nowiki><br />
IDX LINK TYPE OPERATIONAL SETUP <br />
1 lo loopback carrier unmanaged <br />
2 enp0s25 ether no-carrier configured<br />
3 bond0 bond degraded-carrier configured<br />
5 wlan0 wlan enslaved configured<br />
<br />
4 links listed.<br />
</nowiki>}}<br />
<br />
=== Speeding up TCP slow-start ===<br />
<br />
On a higher bandwidth link with moderate latency (typically a home Internet connection that is above 10 Mbit/s) the default settings for the TCP Slow Start algorithm are somewhat conservative. This issue exhibits as downloads starting slowly and taking a number of seconds to speed up before they reach the connection's full bandwidth. It is particularly noticeable with a pacman upgrade, where each package downloaded starts off slowly and often finishes before it has reached the connection's full speed.<br />
<br />
These settings can be adjusted to make TCP connections start with larger window sizes than the defaults, avoiding the time it takes for them to automatically increase on each new TCP connection[https://www.cdnplanet.com/blog/tune-tcp-initcwnd-for-optimum-performance/]. While this will usually decrease performance on slow connections (or if the values are increased too far) due to having to retransmit a larger number of lost packets, they can substantially increase performance on connections with sufficient bandwidth.<br />
<br />
It is important to benchmark before and after changing these values to ensure it is improving network speed and not reducing it. If you are not seeing downloads begin slowly and gradually speed up, then there is no need to change these values as they are already optimal for your connection speed. When benchmarking, be sure to test against both a high speed and low speed remote server to ensure you are not speeding up access to fast machines at the expense of making access to slow servers even slower.<br />
<br />
To adjust these values, edit the ''.network'' file for the connection:<br />
<br />
{{hc|/etc/systemd/network/eth0.network|2=<br />
[Match]<br />
Name=eth0<br />
<br />
#[Network]<br />
#Gateway=... <-- Remove this if you have it, and put it in the Gateway= line below<br />
<br />
[Route]<br />
# This will apply to the gateway supplied via DHCP. If you manually specify<br />
# your gateway, put it here instead.<br />
Gateway=_dhcp4<br />
<br />
# The defaults for these values is 10. They are a multiple of the MSS (1460 bytes).<br />
InitialCongestionWindow=10<br />
InitialAdvertisedReceiveWindow=10<br />
}}<br />
<br />
The defaults of {{ic|10}} work well for connections slower than 10 Mbit/s. For a 100 Mbit/s connection, a value of {{ic|30}} works well. The manual page {{man|5|systemd.network|<nowiki>[ROUTE] SECTION OPTIONS</nowiki>|fragment=%5BROUTE%5D_SECTION_OPTIONS}} says a value of {{ic|100}} is considered excessive.<br />
<br />
If the [[sysctl]] setting {{ic|net.ipv4.tcp_slow_start_after_idle}} is enabled then the connection will return to these initial settings after it has been idle for some time (and often a very small amount of time). If this setting is disabled then the connection will maintain a higher window if a larger one was negotiated during packet transfer. Regardless of the setting, each new TCP connection will begin with the {{ic|Initial*}} settings set above.<br />
<br />
The sysctl setting {{ic|net.ipv4.tcp_congestion_control}} is not directly related to these values, as it controls how the congestion and receive windows are adjusted while a TCP link is active, and particularly when the path between the two hosts is congested and throughput must be reduced. The above {{ic|Initial*}} values simply set the default window values selected for each new connection, before any congestion algorithm takes over and adjusts them as needed. Setting higher initial values simply shortcuts some negotiation while the congestion algorithm tries to find the optimum values (or, conversely, setting the wrong initial values adds additional negotiation time while the congestion algorithm works towards correcting them, slowing down each newly established TCP connection for a few seconds extra).<br />
<br />
== See also ==<br />
<br />
* {{man|8|systemd-networkd}}<br />
* [https://coreos.com/blog/intro-to-systemd-networkd/ Tom Gundersen posts on Core OS blog]<br />
* [https://bbs.archlinux.org/viewtopic.php?pid=1393759#p1393759 How to set up systemd-networkd with wpa_supplicant] (WonderWoofy's walkthrough on Arch forums)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Systemd-networkd&diff=678310Systemd-networkd2021-06-09T14:49:57Z<p>Pgoetz: /* systemd-networkd-wait-online */ This is a somewhat nonstandard way of fixing this problem, the canonical way is to create an override.conf file; but in any case, I'm pretty sure the blank ExecStart= line was superfluous.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network managers]]<br />
[[Category:Virtualization]]<br />
[[de:Systemd/systemd-networkd]]<br />
[[es:Systemd-networkd]]<br />
[[ja:systemd-networkd]]<br />
[[ru:Systemd-networkd]]<br />
[[zh-hans:Systemd-networkd]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|systemd-resolved}}<br />
{{Related|systemd-nspawn}}<br />
{{Related|Network bridge}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|:Category:Network configuration}}<br />
{{Related articles end}}<br />
<br />
''systemd-networkd'' is a system daemon that manages network configurations. It detects and configures network devices as they appear; it can also create virtual network devices. This service can be especially useful to set up complex network configurations for a container managed by [[systemd-nspawn]] or for virtual machines. It also works fine on simple connections.<br />
<br />
== Basic usage ==<br />
<br />
The {{Pkg|systemd}} package is part of the default Arch installation and contains all needed files to operate a wired network. Wireless adapters, covered later in this article, can be set up by services, such as [[wpa_supplicant]] or [[iwd]].<br />
<br />
=== Required services and setup ===<br />
<br />
To use ''systemd-networkd'', [[start/enable]] {{ic|systemd-networkd.service}}.<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.}}<br />
<br />
It is optional to also configure [[systemd-resolved]], which is a network name resolution service to local applications, considering the following points:<br />
<br />
* It is important to understand how [[resolv.conf]] and ''systemd-resolved'' interact to properly configure the DNS that will be used, some explanations are provided in [[systemd-resolved]].<br />
* ''systemd-resolved'' is required if DNS entries are specified in ''.network'' files.<br />
* ''systemd-resolved'' is also required if you want to obtain DNS addresses from DHCP servers or IPv6 router advertisements.<br>(by setting ({{ic|1=DHCP=}} and/or {{ic|1=IPv6AcceptRA=}} in the {{ic|[Network]}} section, and {{ic|1=UseDNS=yes}} (the default) in the corresponding section(s) {{ic|[DHCPv4]}}, {{ic|[DHCPv6]}}, {{ic|[IPv6AcceptRA]}}, see {{man|5|systemd.network}}).<br />
* Note that ''systemd-resolved'' can also be used without ''systemd-networkd''.<br />
<br />
=== systemd-networkd-wait-online ===<br />
<br />
Enabling {{ic|systemd-networkd.service}} also enables {{ic|systemd-networkd-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 be started 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|systemd-networkd-wait-online.service}} waits for all links it is aware of and which are managed by ''systemd-networkd'' to be fully configured or failed, and for at least one link to be online.<br />
<br />
If your system has multiple network interfaces, but some are not expected to be connected all the time (e.g. if you have a dual-port Ethernet card, but only one cable plugged in), starting {{ic|systemd-networkd-wait-online.service}} will fail after the default timeout of 2 minutes. This may cause an unwanted delay in the startup process. To change the behaviour to wait for ''any'' interface rather than ''all'' interfaces to become online, [[edit]] the service and add the {{ic|--any}} parameter to the {{ic|ExecStart}} line:<br />
<br />
{{hc|/etc/systemd/system/systemd-networkd-wait-online.service.d/wait-for-only-one-interface.conf|2=<br />
[Service]<br />
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --any<br />
}}<br />
<br />
Other behaviour such as ignored interfaces or the operational state can be configured as well. See {{man|8|systemd-networkd-wait-online}} for the available parameters.<br />
<br />
=== Configuration examples ===<br />
<br />
All configurations in this section are stored as {{ic|foo.network}} in {{ic|/etc/systemd/network/}}. For a full listing of options and processing order, see [[#Configuration files]] and {{man|5|systemd.network}}.<br />
<br />
systemd/udev automatically assigns predictable, stable network interface names for all local Ethernet, WLAN, and WWAN interfaces. Use {{ic|networkctl list}} to list the devices on the system.<br />
<br />
After making changes to a configuration file, [[restart]] {{ic|systemd-networkd.service}}.<br />
<br />
{{Note|<br />
* The options specified in the configuration files are case sensitive.<br />
* In the examples below, {{ic|enp1s0}} is the wired adapter and {{ic|wlp2s0}} is the wireless adapter. These names can be different on different systems. See [[Network configuration#Network interfaces]] for checking your adapter names.<br />
* It is also possible to use a wildcard, e.g. {{ic|1=Name=en*}} or {{ic|1=Name=wl*}}.<br />
* Devices can also be matched by their type. E.g. {{ic|1=Type=ether}} for Ethernet, {{ic|1=Type=wlan}} for Wi-Fi and {{ic|1=Type=wwan}} for WWAN. Note that {{ic|1=Type=ether}} will also match virtual Ethernet interfaces ({{ic|veth*}}), which may be undesirable.<br />
* If you want to disable IPv6, see [[IPv6#systemd-networkd_3|IPv6#systemd-networkd]].<br />
}}<br />
<br />
==== Wired adapter using DHCP ====<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
DHCP=yes<br />
}}<br />
<br />
==== Wired adapter using a static IP ====<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
Address=10.1.10.9/24<br />
Gateway=10.1.10.1<br />
DNS=10.1.10.1<br />
}}<br />
<br />
{{ic|1=Address=}} can be used more than once to configure multiple IPv4 or IPv6 addresses. See [[#network files]] or {{man|5|systemd.network}} for more options.<br />
<br />
==== Wireless adapter ====<br />
<br />
In order to connect to a wireless network with ''systemd-networkd'', a wireless adapter configured with another application such as [[wpa_supplicant]] or [[iwd]] is required.<br />
<br />
{{hc|/etc/systemd/network/25-wireless.network|2=<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=yes<br />
}}<br />
<br />
If the wireless adapter has a static IP address, the configuration is the same (except for the interface name) as in a [[#Wired adapter using a static IP|wired adapter]].<br />
<br />
To authenticate to the wireless network, use e.g. [[wpa_supplicant]] or [[iwd]].<br />
<br />
==== Wired and wireless adapters on the same machine ====<br />
<br />
This setup will enable a DHCP IP for both a wired and wireless connection making use of the metric directive to allow the kernel to decide on-the-fly which one to use. This way, no connection downtime is observed when the wired connection is unplugged.<br />
<br />
The kernel's route metric (same as configured with ''ip'') decides which route to use for outgoing packets, in cases when several match. This will be the case when both wireless and wired devices on the system have active connections. To break the tie, the kernel uses the metric. If one of the connections is terminated, the other automatically wins without there being a gap with nothing configured (ongoing transfers may still not deal with this nicely but that is at a different OSI layer).<br />
<br />
{{Note|The {{ic|Metric}} option is for static routes while the {{ic|RouteMetric}} option is for setups not using static routes. See {{man|5|systemd.network}} for more details.}}<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
DHCP=yes<br />
<br />
[DHCP]<br />
RouteMetric=10}}<br />
<br />
{{hc|/etc/systemd/network/25-wireless.network|2=<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=yes<br />
<br />
[DHCP]<br />
RouteMetric=20<br />
}}<br />
<br />
==== Renaming an interface ====<br />
<br />
Instead of [[Network configuration#Change interface name|editing udev rules]], a ''.link'' file can be used to rename an interface. A useful example is to set a predictable interface name for a USB-to-Ethernet adapter based on its MAC address, as those adapters are usually given different names depending on which USB port they are plugged into.<br />
<br />
{{hc|head=/etc/systemd/network/10-ethusb0.link|output=<br />
[Match]<br />
MACAddress=12:34:56:78:90:ab<br />
<br />
[Link]<br />
Description=USB to Ethernet Adapter<br />
Name=ethusb0<br />
}}<br />
<br />
{{Note|Any user-supplied ''.link'' '''must''' have a lexically earlier file name than the default config {{ic|99-default.link}} in order to be considered at all. For example, name the file {{ic|10-ethusb0.link}} and not {{ic|ethusb0.link}}.}}<br />
<br />
== Configuration files ==<br />
<br />
Configuration files are located in {{ic|/usr/lib/systemd/network/}}, the volatile runtime network directory {{ic|/run/systemd/network/}} and the local administration network directory {{ic|/etc/systemd/network/}}. Files in {{ic|/etc/systemd/network/}} have the highest priority.<br />
<br />
There are three types of configuration files. They all use a format similar to [[systemd#Writing unit files|systemd unit files]]. <br />
<br />
* ''.network'' files. They will apply a network configuration for a ''matching'' device<br />
* ''.netdev'' files. They will create a ''virtual network device'' for a ''matching'' environment<br />
* ''.link'' files. When a network device appears, [[udev]] will look for the first ''matching'' ''.link'' file<br />
<br />
They all follow the same rules: <br />
<br />
* If '''all''' conditions in the {{ic|[Match]}} section are matched, the profile will be activated<br />
* an empty {{ic|[Match]}} section means the profile will apply in any case (can be compared to the {{ic|*}} wildcard)<br />
* all configuration files are collectively sorted and processed in lexical order, regardless of the directory in which they live<br />
* files with identical name replace each other<br />
<br />
{{Tip|<br />
* Files in {{ic|/etc/systemd/network/}} override the corresponding system-supplied file in {{ic|/usr/lib/systemd/network/}}. You can also create a symlink to {{ic|/dev/null}} to "mask" a system file.<br />
* systemd accepts the values {{ic|1, true, yes, on}} for a true boolean, and the values {{ic|0, false, no, off}} for a false boolean<br />
}}<br />
<br />
=== network files ===<br />
<br />
{{Remove|Duplicates the {{man|5|systemd.network}} man page.}}<br />
<br />
These files are aimed at setting network configuration variables, especially for servers and containers.<br />
<br />
''.network'' files have the following sections: {{ic|[Match]}}, {{ic|[Link]}}, {{ic|[Network]}}, {{ic|[Address]}}, {{ic|[Route]}}, and {{ic|[DHCP]}}. Below are commonly configured keys for each section. See {{man|5|systemd.network}} for more information and examples.<br />
<br />
==== [Match] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=Name=}} || Match device names, e.g. {{ic|en*}}. By prefixing with {{ic|!}}, the list can be inverted. || white-space separated device names with globs, logical negation ({{ic|!}}) ||<br />
|-<br />
| {{ic|1=MACAddress=}} || Match MAC addresses, e.g. {{ic|1=MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF}} || whitespace-separated MAC addresses in full colon-, hyphen- or dot-delimited hexadecimal || <br />
|-<br />
| {{ic|1=Host=}} || Match the hostname or machine ID of the host. || hostname string with globs, {{man|5|machine-id}} ||<br />
|-<br />
| {{ic|1=Virtualization=}} || Check whether the system is executed in a virtualized environment. {{ic|1=Virtualization=false}} will only match your host machine, while {{ic|1=Virtualization=true}} matches any container or VM. It is possible to check for a specific virtualization type or implementation, or for a user namespace (with {{ic|private-users}}). || boolean, logical negation ({{ic|!}}), type ({{ic|vm}}, {{ic|container}}), implementation ({{ic|qemu}}, {{ic|kvm}}, {{ic|zvm}}, {{ic|vmware}}, {{ic|microsoft}}, {{ic|oracle}}, {{ic|powervm}}, {{ic|xen}}, {{ic|bochs}}, {{ic|uml}}, {{ic|bhyve}}, {{ic|qnx}}, {{ic|openvz}}, {{ic|lxc}}, {{ic|lxc-libvirt}}, {{ic|systemd-nspawn}}, {{ic|docker}}, {{ic|podman}}, {{ic|rkt}}, {{ic|wsl}}, {{ic|proot}}, {{ic|pouch}}, {{ic|acrn}}), {{ic|private-users}} ||<br />
|}<br />
<br />
==== [Link] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=MACAddress=}} || Assign a hardware address to the device. Useful for [[MAC_address_spoofing#systemd-networkd|MAC address spoofing]]. || full colon-, hyphen- or dot-delimited hexadecimal MAC addresses ||<br />
|-<br />
| {{ic|1=MTUBytes=}} || Maximum transmission unit in bytes to set for the device. Note that if IPv6 is enabled on the interface, and the MTU is chosen below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value. Setting a larger MTU value (e.g. when using [[jumbo frames]]) can significantly speed up your network transfers || integer (usual suffixes K, M, G, are supported and are understood to the base of 1024) ||<br />
|-<br />
| {{ic|1=Multicast=}} || allows the usage of [[wikipedia:Multicast_address|multicast]] || boolean || ? not documented ?<br />
|}<br />
<br />
==== [Network] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=DHCP=}} || Controls DHCPv4 and/or DHCPv6 client support. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DHCPServer=}} || If enabled, a DHCPv4 server will be started. || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=MulticastDNS=}} || Enables [https://tools.ietf.org/html/rfc6762 multicast DNS] support. When set to {{ic|resolve}}, only resolution is enabled, but not host or service registration and announcement. || boolean, {{ic|resolve}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DNSSEC=}} || Controls DNSSEC DNS validation support on the link. When set to {{ic|allow-downgrade}}, compatibility with non-DNSSEC capable networks is increased, by automatically turning off DNSSEC in this case. || boolean, {{ic|allow-downgrade}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DNS=}} || Configure static [[DNS]] addresses. May be specified more than once. || {{man|3|inet_pton}} ||<br />
|-<br />
| {{ic|1=Domains=}} || A list of domains which should be resolved using the DNS servers on this link. [https://www.freedesktop.org/software/systemd/man/systemd.network.html#Domains= more information] || domain name, optionally prefixed with a tilde ({{ic|~}}) ||<br />
|-<br />
| {{ic|1=IPForward=}} || If enabled, incoming packets on any network interface will be forwarded to any other interfaces according to the routing table. See [[Internet sharing#Enable packet forwarding]] for details. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}<br />
|-<br />
| {{ic|1=IPMasquerade=}} || If enabled, packets forwarded from the network interface will appear as coming from the local host. Depending on the value, implies {{ic|1=IPForward=ipv4}}, {{ic|1=IPForward=ipv6}} or {{ic|1=IPForward=yes}}. || {{ic|ipv4}}, {{ic|ipv6}}, {{ic|both}}, {{ic|no}} || {{ic|no}}<br />
|-<br />
| {{ic|1=IPv6PrivacyExtensions=}} || Configures use of stateless temporary addresses that change over time (see [https://tools.ietf.org/html/rfc4941 RFC 4941]). When {{ic|prefer-public}}, enables the privacy extensions, but prefers public addresses over temporary addresses. When {{ic|kernel}}, the kernel's default setting will be left in place. || boolean, {{ic|prefer-public}}, {{ic|kernel}} || {{ic|false}}<br />
|}<br />
<br />
==== [Address] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=Address=}} || Specify this key more than once to configure several addresses. Mandatory unless DHCP is used. If the specified address is {{ic|0.0.0.0}} (for IPv4) or {{ic|::}} (for IPv6), a new address range of the requested size is automatically allocated from a system-wide pool of unused ranges. || static IPv4 or IPv6 address and its prefix length (see {{man|3|inet_pton}}) ||<br />
|}<br />
<br />
==== [Route] ====<br />
<br />
* {{ic|1=Gateway=}} this option is '''mandatory''' unless DHCP is used<br />
* {{ic|1=Destination=}} the destination prefix of the route, possibly followed by a slash and the prefix length <br />
<br />
If {{ic|Destination}} is not present in {{ic|[Route]}} section this section is treated as a default route.<br />
<br />
{{Tip|You can put the {{ic|1=Address=}} and {{ic|1=Gateway=}} keys in the {{ic|[Network]}} section as a short-hand if {{ic|[Address]}} section contains only an {{ic|Address}} key and {{ic|[Route]}} section contains only a {{ic|Gateway}} key.}}<br />
<br />
==== [DHCP] ====<br />
<br />
{{Out of date|{{ic|[DHCP]}} [https://github.com/systemd/systemd/pull/13006 has been split] into {{ic|[DHCPv4]}} and {{ic|[DHCPv6]}}.}}<br />
<br />
{| class = "wikitable<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=UseDNS=}} || controls whether the DNS servers advertised by the DHCP server are used || boolean || {{ic|true}}<br />
|-<br />
| {{ic|1=Anonymize=}} || when true, the options sent to the DHCP server will follow the [https://tools.ietf.org/html/rfc7844 RFC7844] (Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=UseDomains=}} || controls whether the domain name received from the DHCP server will be used as DNS search domain. If set to {{ic|route}}, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching. This option can sometimes fix local name resolving when using [[systemd-resolved]] || boolean, {{ic|route}} || {{ic|false}}<br />
|}<br />
<br />
==== [DHCPServer] ====<br />
<br />
This is an example of a DHCP server configuration which works well with [[hostapd]] to create a wireless hotspot. {{ic|IPMasquerade}} adds the firewall rules for [[Internet sharing#Enable NAT|NAT]] and implies {{ic|1=IPForward=ipv4}} to enable [[Internet sharing#Enable packet forwarding|packet forwarding]].<br />
<br />
{{Accuracy|{{ic|1=IPMasquerade=true}} does not add the rules for the {{ic|filter}} table, they have to be added manually. See [[systemd-nspawn#Use a virtual Ethernet link]].}}<br />
<br />
{{hc|/etc/systemd/network/''wlan0''.network|<nowiki><br />
[Match]<br />
Name=wlan0<br />
<br />
[Network]<br />
Address=10.1.1.1/24<br />
DHCPServer=true<br />
IPMasquerade=true<br />
<br />
[DHCPServer]<br />
PoolOffset=100<br />
PoolSize=20<br />
EmitDNS=yes<br />
DNS=9.9.9.9<br />
</nowiki>}}<br />
<br />
=== netdev files ===<br />
<br />
{{Remove|Duplicates the {{man|5|systemd.netdev}} man page.}}<br />
<br />
These files will create virtual network devices. They have two sections: {{ic|[Match]}} and {{ic|[NetDev]}}. Below are commonly configured keys for each section. See {{man|5|systemd.netdev}} for more information and examples.<br />
<br />
==== [Match] section ====<br />
<br />
* {{ic|1=Host=}} the hostname<br />
* {{ic|1=Virtualization=}} check if the system is running in a virtualized environment<br />
<br />
==== [NetDev] section ====<br />
<br />
Most common keys are:<br />
<br />
* {{ic|1=Name=}} the interface name. '''mandatory'''<br />
* {{ic|1=Kind=}} e.g. ''bridge'', ''bond'', ''vlan'', ''veth'', ''sit'', etc. '''mandatory'''<br />
<br />
=== link files ===<br />
<br />
{{Remove|Duplicates the {{man|5|systemd.link}} man page.}}<br />
<br />
These files are an alternative to custom udev rules and will be applied by [[udev]] as the device appears. They have two sections: {{ic|[Match]}} and {{ic|[Link]}}. Below are commonly configured keys for each section. See {{man|5|systemd.link}} for more information and examples.<br />
<br />
{{Tip|Use {{ic|udevadm test-builtin net_setup_link /sys/path/to/network/device}} as the root user to diagnose problems with ''.link'' files.}}<br />
<br />
==== [Match] section ====<br />
<br />
* {{ic|1=MACAddress=}} the MAC address<br />
* {{ic|1=Host=}} the host name<br />
* {{ic|1=Virtualization=}} <br />
* {{ic|1=Type=}} the device type e.g. vlan<br />
<br />
==== [Link] section ====<br />
<br />
* {{ic|1=MACAddressPolicy=}} persistent or random addresses, or<br />
* {{ic|1=MACAddress=}} a specific address<br />
* {{ic|1=NamePolicy=}} list of policies by which the interface name should be set, e.g. kernel, keep<br />
<br />
{{Note|the system {{ic|/usr/lib/systemd/network/99-default.link}} is generally sufficient for most of the basic cases.}}<br />
<br />
== Usage with containers ==<br />
<br />
''systemd-networkd'' can provide fully automatic configuration of networking for [[systemd-nspawn]] containers when it is used on the host system as well as inside the container. See [[systemd-nspawn#Networking]] for a comprehensive overview.<br />
<br />
For the examples below, <br />
* we will limit the output of the {{ic|ip a}} command to the concerned interfaces.<br />
* we assume the ''host'' is your main OS you are booting to and the ''container'' is your guest virtual machine.<br />
* all interface names and IP addresses are only examples.<br />
<br />
=== Network bridge with DHCP ===<br />
<br />
==== Bridge interface ====<br />
<br />
First, create a virtual [[bridge]] interface. We tell systemd to create a device named ''br0'' that functions as an ethernet bridge.<br />
<br />
{{hc|/etc/systemd/network/''mybridge''.netdev|2=<br />
[NetDev]<br />
Name=br0<br />
Kind=bridge}}<br />
<br />
{{Tip|''systemd-networkd'' assigns a MAC address generated based on the interface name and the machine ID to the bridge. This may cause connection issues, for example in case of routing based on MAC filtering. To circumvent such problems you may assign a MAC address to your bridge, probably the same as your physical device, adding the line {{ic|1=MACAddress=xx:xx:xx:xx:xx:xx}} in the ''NetDev'' section above.}}<br />
<br />
[[Restart]] {{ic|systemd-networkd.service}} to have systemd create the bridge.<br />
<br />
To see the newly created bridge on the host and on the container, type:<br />
<br />
{{hc|$ ip a|<br />
3: br0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default <br />
link/ether ae:bd:35:ea:0c:c9 brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
Note that the interface ''br0'' is listed but is still DOWN at this stage.<br />
<br />
==== Bind Ethernet to bridge ====<br />
<br />
The next step is to add to the newly created bridge a network interface. In the example below, we add any interface that matches the name ''en*'' into the bridge ''br0''.<br />
<br />
{{hc|/etc/systemd/network/''bind''.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
Bridge=br0<br />
}}<br />
<br />
The Ethernet interface must not have DHCP or an IP address associated as the bridge requires an interface to bind to with no IP: modify the corresponding {{ic|/etc/systemd/network/''MyEth''.network}} accordingly to remove the addressing.<br />
<br />
==== Bridge network ====<br />
<br />
Now that the bridge has been created and has been bound to an existing network interface, the IP configuration of the bridge interface must be specified. This is defined in a third ''.network'' file, the example below uses DHCP.<br />
<br />
{{hc|/etc/systemd/network/''mybridge''.network|2=<br />
[Match]<br />
Name=br0<br />
<br />
[Network]<br />
DHCP=ipv4}}<br />
<br />
==== Configure the container ====<br />
<br />
Use the {{ic|1=--networkd-bridge=br0}} option when starting the container. See [[systemd-nspawn#Use a network bridge]] for details.<br />
<br />
==== Result ====<br />
<br />
* on host<br />
<br />
{{hc|$ ip a|<br />
3: br0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default <br />
link/ether 14:da:e9:b5:7a:88 brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.1.87/24 brd 192.168.1.255 scope global br0<br />
valid_lft forever preferred_lft forever<br />
inet6 fe80::16da:e9ff:feb5:7a88/64 scope link <br />
valid_lft forever preferred_lft forever<br />
6: vb-''MyContainer'': <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master br0 state UP group default qlen 1000<br />
link/ether d2:7c:97:97:37:25 brd ff:ff:ff:ff:ff:ff<br />
inet6 fe80::d07c:97ff:fe97:3725/64 scope link <br />
valid_lft forever preferred_lft forever<br />
}}<br />
<br />
* on container<br />
<br />
{{hc|$ ip a|<br />
2: host0: <BROADCAST,MULTICAST,ALLMULTI,AUTOMEDIA,NOTRAILERS,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000<br />
link/ether 5e:96:85:83:a8:5d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.1.73/24 brd 192.168.1.255 scope global host0<br />
valid_lft forever preferred_lft forever<br />
inet6 fe80::5c96:85ff:fe83:a85d/64 scope link <br />
valid_lft forever preferred_lft forever<br />
}}<br />
<br />
==== Notice ====<br />
<br />
* we have now one IP address for {{ic|br0}} on the host, and one for {{ic|host0}} in the container<br />
* two new interfaces have appeared: {{ic|vb-''MyContainer''}} in the host and {{ic|host0}} in the container. This comes as a result of the {{ic|1=--network-bridge=br0}} option as explained in [[systemd-nspawn#Use a network bridge]] for details.<br />
* the DHCP address on {{ic|host0}} comes from the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file.<br />
* on host<br />
<br />
{{Out of date|''brctl'' is deprecated, use {{ic|bridge link}}. See [[Network bridge#With iproute2]].}}<br />
{{hc|$ brctl show|<br />
bridge name bridge id STP enabled interfaces<br />
br0 8000.14dae9b57a88 no enp7s0<br />
vb-''MyContainer''<br />
}}<br />
<br />
the above command output confirms we have a bridge with two interfaces binded to.<br />
<br />
* on host<br />
<br />
{{hc|$ ip route|<br />
default via 192.168.1.254 dev br0 <br />
192.168.1.0/24 dev br0 proto kernel scope link src 192.168.1.87<br />
}}<br />
<br />
* on container<br />
<br />
{{hc|$ ip route|<br />
default via 192.168.1.254 dev host0 <br />
192.168.1.0/24 dev host0 proto kernel scope link src 192.168.1.73<br />
}}<br />
<br />
the above command outputs confirm we have activated {{ic|br0}} and {{ic|host0}} interfaces with an IP address and Gateway 192.168.1.254. The gateway address has been automatically grabbed by ''systemd-networkd''.<br />
<br />
=== Network bridge with static IP addresses ===<br />
<br />
Setting a static IP address for each device can be helpful in case of deployed web services (e.g FTP, http, SSH). Each device will keep the same MAC address across reboots if your system {{ic|/usr/lib/systemd/network/99-default.link}} file has the {{ic|1=MACAddressPolicy=persistent}} option (it has by default). Thus, you will easily route any service on your Gateway to the desired device.<br />
<br />
The following configuration needs to be done for this setup:<br />
<br />
* on host <br />
<br />
The configuration is very similar to the [[#Network bridge with DHCP]] section. First, a virtual bridge interface needs to be created and the main physical interface needs to be bound to it. This task can be accomplished with the following two files, with contents equal to those available in the DHCP section.<br />
<br />
/etc/systemd/network/''MyBridge''.netdev<br />
/etc/systemd/network/''MyEth''.network<br />
<br />
Next, you need to configure the IP and DNS of the newly created virtual bridge interface. For example:<br />
<br />
{{hc|/etc/systemd/network/''MyBridge''.network|<nowiki><br />
[Match]<br />
Name=br0<br />
<br />
[Network]<br />
DNS=192.168.1.254<br />
Address=192.168.1.87/24<br />
Gateway=192.168.1.254<br />
</nowiki>}}<br />
<br />
* on container<br />
<br />
To get configure a static IP address on the container, we need to override the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file, which provides a DHCP configuration for the {{ic|host0}} network interface of the container. This can be done by placing the configuration into {{ic|/etc/systemd/network/80-container-host0.network}}. For example:<br />
<br />
{{hc|/etc/systemd/network/80-container-host0.network|2=<br />
[Match]<br />
Name=host0<br />
<br />
[Network]<br />
DNS=192.168.1.254<br />
Address=192.168.1.94/24<br />
Gateway=192.168.1.254<br />
}}<br />
<br />
Make sure that {{ic|systemd-networkd.service}} is [[enabled]] in the container.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Interface and desktop integration ===<br />
<br />
''systemd-networkd'' does not have a proper interactive management interface neither via [[command-line shell]] nor graphical.<br />
<br />
Still, some tools are available to either display the current state of the network, receive notifications or interact with the wireless configuration:<br />
<br />
* ''networkctl'' (via CLI) offers a simple dump of the network interface states.<br />
* When ''networkd'' is configured with [[wpa_supplicant]], both ''wpa_cli'' and ''wpa_gui'' offer the ability to associate and configure WLAN interfaces dynamically.<br />
* {{AUR|networkd-notify-git}} can generate simple notifications in response to network interface state changes (such as connection/disconnection and re-association).<br />
* The {{AUR|networkd-dispatcher}} daemon allows executing scripts in response to network interface state changes, similar to ''NetworkManager-dispatcher''.<br />
* As for the DNS resolver ''systemd-resolved'', information about current DNS servers can be visualized with {{ic|resolvectl status}}.<br />
<br />
=== Configuring static IP or DHCP based on SSID (location) ===<br />
<br />
Often there is a situation where your home wireless network uses DHCP and office wireless network uses static IP. This mixed setup can be configured as follows:<br />
<br />
{{Note|Number in the file name decides the order in which the files are processed. You can [Match] based on SSID or BSSID or both.}}<br />
<br />
{{hc|/etc/systemd/network/24-wireless-office.network|<nowiki><br />
# special configuration for office WiFi network<br />
[Match]<br />
Name=wlp2s0<br />
SSID=office_ap_name<br />
#BSSID=aa:bb:cc:dd:ee:ff<br />
<br />
[Network]<br />
Address=10.1.10.9/24<br />
Gateway=10.1.10.1<br />
DNS=10.1.10.1<br />
#DNS=8.8.8.8<br />
</nowiki>}}<br />
<br />
{{hc|/etc/systemd/network/25-wireless-dhcp.network|<nowiki><br />
# use DHCP for any other WiFi network<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=ipv4<br />
</nowiki>}}<br />
<br />
=== Bonding a wired and wireless interface ===<br />
<br />
See also [[Wireless bonding]].<br />
<br />
Bonding allows connection sharing through multiple interfaces, so if e.g. the wired interface is unplugged, the wireless is still connected and the network connectivity remains up seamlessly.<br />
<br />
Create a bond interface. In this case the mode is ''active-backup'', which means packets are routed through a secondary interface if the primary interface goes down.<br />
<br />
{{hc|/etc/systemd/network/30-bond0.netdev|<nowiki><br />
[NetDev]<br />
Name=bond0<br />
Kind=bond<br />
<br />
[Bond]<br />
Mode=active-backup<br />
PrimaryReselectPolicy=always<br />
MIIMonitorSec=1s<br />
</nowiki>}}<br />
<br />
Set the wired interface as the primary:<br />
<br />
{{hc|/etc/systemd/network/30-ethernet-bond0.network|<nowiki><br />
[Match]<br />
Name=enp0s25<br />
<br />
[Network]<br />
Bond=bond0<br />
PrimarySlave=true<br />
</nowiki>}}<br />
<br />
Set the wireless as the secondary:<br />
<br />
{{hc|/etc/systemd/network/30-wifi-bond0.network|<nowiki><br />
[Match]<br />
Name=wlan0<br />
<br />
[Network]<br />
Bond=bond0<br />
</nowiki>}}<br />
<br />
Configure the bond interface as you would a normal interface:<br />
<br />
{{hc|/etc/systemd/network/30-bond0.network|<nowiki><br />
[Match]<br />
Name=bond0<br />
<br />
[Network]<br />
DHCP=ipv4<br />
</nowiki>}}<br />
<br />
Now if the wired network is unplugged, the connection should remain through the wireless:<br />
<br />
{{hc|$ networkctl|<nowiki><br />
IDX LINK TYPE OPERATIONAL SETUP <br />
1 lo loopback carrier unmanaged <br />
2 enp0s25 ether no-carrier configured<br />
3 bond0 bond degraded-carrier configured<br />
5 wlan0 wlan enslaved configured<br />
<br />
4 links listed.<br />
</nowiki>}}<br />
<br />
=== Speeding up TCP slow-start ===<br />
<br />
On a higher bandwidth link with moderate latency (typically a home Internet connection that is above 10 Mbit/s) the default settings for the TCP Slow Start algorithm are somewhat conservative. This issue exhibits as downloads starting slowly and taking a number of seconds to speed up before they reach the connection's full bandwidth. It is particularly noticeable with a pacman upgrade, where each package downloaded starts off slowly and often finishes before it has reached the connection's full speed.<br />
<br />
These settings can be adjusted to make TCP connections start with larger window sizes than the defaults, avoiding the time it takes for them to automatically increase on each new TCP connection[https://www.cdnplanet.com/blog/tune-tcp-initcwnd-for-optimum-performance/]. While this will usually decrease performance on slow connections (or if the values are increased too far) due to having to retransmit a larger number of lost packets, they can substantially increase performance on connections with sufficient bandwidth.<br />
<br />
It is important to benchmark before and after changing these values to ensure it is improving network speed and not reducing it. If you are not seeing downloads begin slowly and gradually speed up, then there is no need to change these values as they are already optimal for your connection speed. When benchmarking, be sure to test against both a high speed and low speed remote server to ensure you are not speeding up access to fast machines at the expense of making access to slow servers even slower.<br />
<br />
To adjust these values, edit the ''.network'' file for the connection:<br />
<br />
{{hc|/etc/systemd/network/eth0.network|2=<br />
[Match]<br />
Name=eth0<br />
<br />
#[Network]<br />
#Gateway=... <-- Remove this if you have it, and put it in the Gateway= line below<br />
<br />
[Route]<br />
# This will apply to the gateway supplied via DHCP. If you manually specify<br />
# your gateway, put it here instead.<br />
Gateway=_dhcp4<br />
<br />
# The defaults for these values is 10. They are a multiple of the MSS (1460 bytes).<br />
InitialCongestionWindow=10<br />
InitialAdvertisedReceiveWindow=10<br />
}}<br />
<br />
The defaults of {{ic|10}} work well for connections slower than 10 Mbit/s. For a 100 Mbit/s connection, a value of {{ic|30}} works well. The manual page {{man|5|systemd.network|<nowiki>[ROUTE] SECTION OPTIONS</nowiki>|fragment=%5BROUTE%5D_SECTION_OPTIONS}} says a value of {{ic|100}} is considered excessive.<br />
<br />
If the [[sysctl]] setting {{ic|net.ipv4.tcp_slow_start_after_idle}} is enabled then the connection will return to these initial settings after it has been idle for some time (and often a very small amount of time). If this setting is disabled then the connection will maintain a higher window if a larger one was negotiated during packet transfer. Regardless of the setting, each new TCP connection will begin with the {{ic|Initial*}} settings set above.<br />
<br />
The sysctl setting {{ic|net.ipv4.tcp_congestion_control}} is not directly related to these values, as it controls how the congestion and receive windows are adjusted while a TCP link is active, and particularly when the path between the two hosts is congested and throughput must be reduced. The above {{ic|Initial*}} values simply set the default window values selected for each new connection, before any congestion algorithm takes over and adjusts them as needed. Setting higher initial values simply shortcuts some negotiation while the congestion algorithm tries to find the optimum values (or, conversely, setting the wrong initial values adds additional negotiation time while the congestion algorithm works towards correcting them, slowing down each newly established TCP connection for a few seconds extra).<br />
<br />
== See also ==<br />
<br />
* {{man|8|systemd-networkd}}<br />
* [https://coreos.com/blog/intro-to-systemd-networkd/ Tom Gundersen posts on Core OS blog]<br />
* [https://bbs.archlinux.org/viewtopic.php?pid=1393759#p1393759 How to set up systemd-networkd with wpa_supplicant] (WonderWoofy's walkthrough on Arch forums)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Improving_performance&diff=653542Improving performance2021-02-26T18:39:36Z<p>Pgoetz: fixed a minor typo; the alternatives are below, not above.</p>
<hr />
<div>[[Category:Hardware]]<br />
[[Category:System administration]]<br />
[[ar:Improving performance]]<br />
[[es:Improving performance]]<br />
[[ja:パフォーマンスの最大化]]<br />
[[pt:Improving performance]]<br />
[[ru:Improving performance]]<br />
[[zh-hans:Improving performance]]<br />
{{Related articles start}}<br />
{{Related|/Boot process}}<br />
{{Related|Pacman/Tips and tricks#Performance}}<br />
{{Related|OpenSSH#Speeding up SSH}}<br />
{{Related|Openoffice#Speed up OpenOffice}}<br />
{{Related|Laptop}}<br />
{{Related|Preload}}<br />
{{Related articles end}}<br />
This article provides information on basic system diagnostics relating to performance as well as steps that may be taken to reduce resource consumption or to otherwise optimize the system with the end-goal being either perceived or documented improvements to a system's performance.<br />
<br />
== The basics ==<br />
<br />
=== Know your system ===<br />
<br />
The best way to tune a system is to target bottlenecks, or subsystems which limit overall speed. The system specifications can help identify them.<br />
<br />
* If the computer becomes slow when large applications (such as LibreOffice and Firefox) run at the same time, check if the amount of RAM is sufficient. Use the following command, and check the "available" column:<br />
<br />
$ free -h<br />
<br />
* If boot time is slow, and applications take a long time to load at first launch (only), then the hard drive is likely to blame. The speed of a hard drive can be measured with the {{ic|hdparm}} command:<br />
{{Note|{{Pkg|hdparm}} indicates only the pure read speed of a hard drive, and is not a valid benchmark. A value higher than 40MB/s (while idle) is however acceptable on an average system.}}<br />
<br />
# hdparm -t /dev/sdX<br />
<br />
* If CPU load is consistently high even with enough RAM available, then try to lower CPU usage by disabling running [[daemons]] and/or processes. This can be monitored in several ways, for example with {{Pkg|htop}}, {{ic|pstree}} or any other [[List_of_applications#System monitors|system monitoring]] tool:<br />
<br />
$ htop<br />
<br />
* If applications using direct rendering are slow (i.e those which use the GPU, such as video players, games, or even a [[window manager]]), then improving GPU performance should help. The first step is to verify if direct rendering is actually enabled. This is indicated by the {{ic|glxinfo}} command, part of the {{Pkg|mesa-demos}} package:<br />
<br />
{{hc|<nowiki>$ glxinfo | grep "direct rendering"</nowiki>|<br />
direct rendering: Yes<br />
}}<br />
<br />
* When running a [[desktop environment]], disabling (unused) visual desktop effects may reduce GPU usage. Use a more lightweight environment or create a [[Desktop_environment#Custom_environments|custom environment]] if the current does not meet the hardware and/or personal requirements.<br />
<br />
=== Benchmarking ===<br />
<br />
The effects of optimization are often difficult to judge. They can however be measured by [[benchmarking]] tools.<br />
<br />
== Storage devices ==<br />
<br />
=== Multiple hardware paths ===<br />
<br />
{{Style|Subjective writing}}<br />
<br />
An internal hardware path is how the storage device is connected to your motherboard. There are different ways to connect to the motherboard such as TCP/IP through a NIC, plugged in directly using PCIe/PCI, Firewire, Raid Card, USB, etc. By spreading your storage devices across these multiple connection points you maximize the capabilities of your motherboard, for example 6 hard-drives connected via USB would be much much slower than 3 over USB and 3 over Firewire. The reason is that each entry path into the motherboard is like a pipe, and there is a set limit to how much can go through that pipe at any one time. The good news is that the motherboard usually has several pipes.<br />
<br />
More Examples<br />
<br />
# Directly to the motherboard using PCI/PCIe/ATA<br />
# Using an external enclosure to house the disk over USB/Firewire<br />
# Turn the device into a network storage device by connecting over TCP/IP<br />
<br />
Note also that if you have a 2 USB ports on the front of your machine, and 4 USB ports on the back, and you have 4 disks, it would probably be fastest to put 2 on front/2 on back than 3 on back/1 on front. This is because internally the front ports are likely a separate Root Hub than the back, meaning you can send twice as much data by using both than just 1. Use the following commands to determine the various paths on your machine.<br />
<br />
{{hc|USB Device Tree|$ lsusb -t}}<br />
<br />
{{hc|PCI Device Tree|$ lspci -tv}}<br />
<br />
=== Partitioning ===<br />
<br />
Make sure that your partitions are [[Partitioning#Partition_alignment|properly aligned]].<br />
<br />
==== Multiple drives ====<br />
<br />
If you have multiple disks available, you can set them up as a software [[RAID]] for serious speed improvements.<br />
<br />
Creating [[swap]] on a separate disk can also help quite a bit, especially if your machine swaps frequently.<br />
<br />
==== Layout on HDDs ====<br />
<br />
If using a traditional spinning HDD, your partition layout can influence the system's performance. Sectors at the beginning of the drive (closer to the outside of the disk) are faster than those at the end. Also, a smaller partition requires less movements from the drive's head, and so speed up disk operations. Therefore, it is advised to create a small partition (10GB, more or less depending on your needs) only for your system, as near to the beginning of the drive as possible. Other data (pictures, videos) should be kept on a separate partition, and this is usually achieved by separating the home directory ({{ic|/home/''user''}}) from the system ({{ic|/}}).<br />
<br />
=== Choosing and tuning your filesystem ===<br />
<br />
Choosing the best filesystem for a specific system is very important because each has its own strengths. The [[File systems]] article provides a short summary of the most popular ones. You can also find relevant articles in [[:Category:File systems]].<br />
<br />
==== Mount options ====<br />
<br />
The [[fstab#atime options|noatime]] option is known to improve performance of the filesystem.<br />
<br />
Other mount options are filesystem specific, therefore see the relevant articles for the filesystems:<br />
<br />
* [[Ext3]]<br />
* [[Ext4#Improving performance]]<br />
* [[JFS Filesystem#Optimizations]]<br />
* [[XFS#Performance]]<br />
* [[Btrfs#Defragmentation]], [[Btrfs#Compression]], and {{man|5|btrfs}}<br />
* [[ZFS#Tuning]]<br />
<br />
===== Reiserfs =====<br />
<br />
The {{Ic|1=data=writeback}} mount option improves speed, but may corrupt data during power loss. The {{Ic|notail}} mount option increases the space used by the filesystem by about 5%, but also improves overall speed. You can also reduce disk load by putting the journal and data on separate drives. This is done when creating the filesystem: <br />
<br />
# mkreiserfs –j /dev/sd'''a1''' /dev/sd'''b1'''<br />
<br />
Replace {{ic|/dev/sd'''a1'''}} with the partition reserved for the journal, and {{ic|/dev/sd'''b1'''}} with the partition for data. You can learn more about reiserfs with this [http://www.funtoo.org/Funtoo_Filesystem_Guide,_Part_2 article].<br />
<br />
=== Tuning kernel parameters ===<br />
<br />
There are several key tunables affecting the performance of block devices, see [[sysctl#Virtual memory]] for more information.<br />
<br />
=== Input/output schedulers ===<br />
<br />
==== Background information ====<br />
<br />
The input/output ''(I/O)'' scheduler is the kernel component that decides in which order the block I/O operations are submitted to storage devices. It is useful to remind here some specifications of two main drive types because the goal of the I/O scheduler is to optimize the way these are able to deal with read requests:<br />
<br />
* An HDD has spinning disks and a head that moves physically to the required location. Therefore, random latency is quite high ranging between 3 and 12ms (whether it is a high end server drive or a laptop drive and bypassing the disk controller write buffer) while sequential access provides much higher throughput. The typical HDD throughput is about 200 I/O operations per second ''(IOPS)''.<br />
<br />
* An SSD does not have moving parts, random access is as fast as sequential one, typically under 0.1ms, and it can handle multiple concurrent requests. The typical SSD throughput is greater than 10,000 IOPS, which is more than needed in common workload situations.<br />
<br />
If there are many processes making I/O requests to different storage parts, thousands of IOPS can be generated while a typical HDD can handle only about 200 IOPS. There is a queue of requests that have to wait for access to the storage. This is where the I/O schedulers plays an optimization role.<br />
<br />
==== The scheduling algorithms ====<br />
<br />
One way to improve throughput is to linearize access: by ordering waiting requests by their logical address and grouping the closest ones. Historically this was the first Linux I/O scheduler called [[Wikipedia:Elevator algorithm|elevator]].<br />
<br />
One issue with the elevator algorithm is that it is not optimal for a process doing sequential access: reading a block of data, processing it for several microseconds then reading next block and so on. The elevator scheduler does not know that the process is about to read another block nearby and, thus, moves to another request by another process at some other location. The [[Wikipedia:Anticipatory scheduling|anticipatory]] I/O scheduler overcomes the problem: it pauses for a few milliseconds in anticipation of another close-by read operation before dealing with another request.<br />
<br />
While these schedulers try to improve total throughput, they might leave some unlucky requests waiting for a very long time. As an example, imagine the majority of processes make requests at the beginning of the storage space while an unlucky process makes a request at the other end of storage. This potentially infinite postponement of the process is called starvation. To improve fairness, the [[Wikipedia:Deadline scheduler|deadline]] algorithm was developed. It has a queue ordered by address, similar to the elevator, but if some request sits in this queue for too long then it moves to an "expired" queue ordered by expire time. The scheduler checks the expire queue first and processes requests from there and only then moves to the elevator queue. Note that this fairness has a negative impact on overall throughput.<br />
<br />
The [[Wikipedia:CFQ|Completely Fair Queuing (CFQ)]] approaches the problem differently by allocating a timeslice and a number of allowed requests by queue depending on the priority of the process submitting them. It supports [[cgroup]] that allows to reserve some amount of I/O to a specific collection of processes. It is in particular useful for shared and cloud hosting: users who paid for some IOPS want to get their share whenever needed. Also, it idles at the end of synchronous I/O waiting for other nearby operations, taking over this feature from the ''anticipatory'' scheduler and bringing some enhancements. Both the ''anticipatory'' and the ''elevator'' schedulers were decommissioned from the Linux kernel replaced by the more advanced alternatives presented below.<br />
<br />
The [https://algo.ing.unimo.it/people/paolo/disk_sched/ Budget Fair Queuing (BFQ)] is based on CFQ code and brings some enhancements. It does not grant the disk to each process for a fixed time-slice but assigns a "budget" measured in number of sectors to the process and uses heuristics. It is a relatively complex scheduler, it may be more adapted to rotational drives and slow SSDs because its high per-operation overhead, especially if associated with a slow CPU, can slow down fast devices. The objective of BFQ on personal systems is that for interactive tasks, the storage device is virtually as responsive as if it was idle. In its default configuration it focuses on delivering the lowest latency rather than achieving the maximum throughput.<br />
<br />
[https://lwn.net/Articles/720675/ Kyber] is a recent scheduler inspired by active queue management techniques used for network routing. The implementation is based on "tokens" that serve as a mechanism for limiting requests. A queuing token is required to allocate a request, this is used to prevent starvation of requests. A dispatch token is also needed and limits the operations of a certain priority on a given device. Finally, a target read latency is defined and the scheduler tunes itself to reach this latency goal. The implementation of the algorithm is relatively simple and it is deemed efficient for fast devices.<br />
<br />
==== Kernel's I/O schedulers ====<br />
<br />
While some of the early algorithms have now been decommissioned, the official Linux kernel supports a number of I/O schedulers which can be split into two categories:<br />
<br />
*The '''multi-queue schedulers''' are available by default with the kernel. The [https://www.thomas-krenn.com/en/wiki/Linux_Multi-Queue_Block_IO_Queueing_Mechanism_(blk-mq) Multi-Queue Block I/O Queuing Mechanism (blk-mq)] maps I/O queries to multiple queues, the tasks are distributed across threads and therefore CPU cores. Within this framework the following schedulers are available:<br />
**''None'', where no queuing algorithm is applied.<br />
**''mq-deadline'', the adaptation of the deadline scheduler (see below) to multi-threading.<br />
**''Kyber''<br />
**''BFQ''<br />
<br />
*The '''single-queue schedulers''' are legacy schedulers:<br />
**[[w:Noop scheduler|NOOP]] is the simplest scheduler, it inserts all incoming I/O requests into a simple FIFO queue and implements request merging. In this algorithm, there is no re-ordering of the request based on the sector number. Therefore it can be used if the ordering is dealt with at another layer, at the device level for example, or if it does not matter, for SSDs for instance.<br />
**[[w:Deadline scheduler|Deadline]]<br />
**[[w:CFQ|CFQ]]<br />
<br />
:{{Note|1=Single-queue schedulers [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f382fb0bcef4c37dc049e9f6963e3baf204d815c were removed from kernel since Linux 5.0].}}<br />
<br />
==== Changing I/O scheduler ====<br />
<br />
{{Note|The best choice of scheduler depends on both the device and the exact nature of the workload. Also, the throughput in MB/s is not the only measure of performance: deadline or fairness deteriorate the overall throughput but may improve system responsiveness. [[Benchmarking]] may be useful to indicate each I/O scheduler performance.}}<br />
<br />
To list the available schedulers for a device and the active scheduler (in brackets):<br />
<br />
{{hc|$ cat /sys/block/'''''sda'''''/queue/scheduler|<br />
mq-deadline kyber [bfq] none<br />
}}<br />
<br />
To list the available schedulers for all devices:<br />
<br />
{{hc|$ grep "" /sys/block/'''*'''/queue/scheduler|<br />
/sys/block/pktcdvd0/queue/scheduler:none<br />
/sys/block/sda/queue/scheduler:mq-deadline kyber [bfq] none<br />
/sys/block/sr0/queue/scheduler:[mq-deadline] kyber bfq none<br />
}}<br />
<br />
To change the active I/O scheduler to ''bfq'' for device ''sda'', use:<br />
<br />
# echo '''''bfq''''' > /sys/block/'''''sda'''''/queue/scheduler<br />
<br />
The process to change I/O scheduler, depending on whether the disk is rotating or not can be automated and persist across reboots. For example the [[udev]] rule below sets the scheduler to ''none'' for [[NVMe]], ''mq-deadline'' for [[SSD]]/eMMC, and ''bfq'' for rotational drives:<br />
<br />
{{hc|/etc/udev/rules.d/60-ioschedulers.rules|2=<br />
# set scheduler for NVMe<br />
ACTION=="add{{!}}change", KERNEL=="nvme[0-9]n[0-9]", ATTR{queue/scheduler}="none"<br />
# set scheduler for SSD and eMMC<br />
ACTION=="add{{!}}change", KERNEL=="sd[a-z]{{!}}mmcblk[0-9]*", ATTR{queue/rotational}=="0", ATTR{queue/scheduler}="mq-deadline"<br />
# set scheduler for rotating disks<br />
ACTION=="add{{!}}change", KERNEL=="sd[a-z]", ATTR{queue/rotational}=="1", ATTR{queue/scheduler}="bfq"<br />
}}<br />
<br />
Reboot or force [[udev#Loading new rules]].<br />
<br />
==== Tuning I/O scheduler ====<br />
<br />
Each of the kernel's I/O scheduler has its own tunables, such as the latency time, the expiry time or the FIFO parameters. They are helpful in adjusting the algorithm to a particular combination of device and workload. This is typically to achieve a higher throughput or a lower latency for a given utilization.<br />
The tunables and their description can be found within the [https://www.kernel.org/doc/html/latest/block/index.html kernel documentation].<br />
<br />
To list the available tunables for a device, in the example below ''sdb'' which is using ''deadline'', use:<br />
<br />
{{hc|$ ls /sys/block/'''''sdb'''''/queue/iosched|<br />
fifo_batch front_merges read_expire write_expire writes_starved}}<br />
<br />
To improve ''deadline'''s throughput at the cost of latency, one can increase {{ic|fifo_batch}} with the command:<br />
<br />
{{bc|# echo ''32'' > /sys/block/'''''sdb'''''/queue/iosched/'''fifo_batch'''}}<br />
<br />
=== Power management configuration ===<br />
<br />
When dealing with traditional rotational disks (HDD's) you may want to [[Hdparm#Power_management_configuration|lower or disable power saving features]] completely.<br />
<br />
=== Reduce disk reads/writes ===<br />
<br />
Avoiding unnecessary access to slow storage drives is good for performance and also increasing lifetime of the devices, although on modern hardware the difference in life expectancy is usually negligible.<br />
<br />
{{Note|A 32GB SSD with a mediocre 10x write amplification factor, a standard 10000 write/erase cycle, and '''10GB of data written per day''', would get an '''8 years life expectancy'''. It gets better with bigger SSDs and modern controllers with less write amplification. Also compare [http://techreport.com/review/25889/the-ssd-endurance-experiment-500tb-update] when considering whether any particular strategy to limit disk writes is actually needed.}}<br />
<br />
==== Show disk writes ====<br />
<br />
The {{Pkg|iotop}} package can sort by disk writes, and show how much and how frequently programs are writing to the disk. See {{man|8|iotop}} for details.<br />
<br />
==== Relocate files to tmpfs ====<br />
<br />
Relocate files, such as your browser profile, to a [[tmpfs]] file system, for improvements in application response as all the files are now stored in RAM:<br />
<br />
* Refer to [[Profile-sync-daemon]] for syncing browser profiles. Certain browsers might need special attention, see e.g. [[Firefox on RAM]].<br />
* Refer to [[Anything-sync-daemon]] for syncing any specified folder.<br />
* Refer to [[Makepkg#Improving compile times]] for improving compile times by building packages in tmpfs.<br />
<br />
==== File systems ====<br />
<br />
Refer to corresponding [[file system]] page in case there were performance improvements instructions, e.g. [[Ext4#Improving performance]] and [[XFS#Performance]].<br />
<br />
==== Swap space ====<br />
<br />
See [[Swap#Performance]].<br />
<br />
==== Writeback interval and buffer size ====<br />
<br />
See [[Sysctl#Virtual memory]] for details.<br />
<br />
=== Storage I/O scheduling with ionice ===<br />
<br />
Many tasks such as backups do not rely on a short storage I/O delay or high storage I/O bandwidth to fulfil their task, they can be classified as background tasks. On the other hand quick I/O is necessary for good UI responsiveness on the desktop. Therefore it is beneficial to reduce the amount of storage bandwidth available to background tasks, whilst other tasks are in need of storage I/O. This can be achieved by making use of the linux I/O scheduler CFQ, which allows setting different priorities for processes.<br />
<br />
The I/O priority of a background process can be reduced to the "Idle" level by starting it with<br />
<br />
# ionice -c 3 command<br />
<br />
See {{man|1|ionice}} and [https://www.cyberciti.biz/tips/linux-set-io-scheduling-class-priority.html] for more information.<br />
<br />
== CPU ==<br />
<br />
=== Overclocking ===<br />
<br />
[[Wikipedia:Overclocking|Overclocking]] improves the computational performance of the CPU by increasing its peak clock frequency. The ability to overclock depends on the combination of CPU model and motherboard model. It is most frequently done through the BIOS. Overclocking also has disadvantages and risks. It is neither recommended nor discouraged here.<br />
<br />
Many Intel chips will not correctly report their clock frequency to acpi_cpufreq and most other utilities. This will result in excessive messages in dmesg, which can be avoided by unloading and blacklisting the kernel module {{ic|acpi_cpufreq}}.<br />
To read their clock speed use ''i7z'' from the {{Pkg|i7z}} package. To check for correct operation of an overclocked CPU, it is recommended to do [[stress testing]].<br />
<br />
=== Frequency scaling ===<br />
<br />
See [[CPU frequency scaling]].<br />
<br />
=== Alternative CPU schedulers ===<br />
<br />
{{Expansion|MuQSS is not the only alternative scheduler.}}<br />
<br />
The default CPU scheduler in the mainline Linux kernel is [[Wikipedia:Completely_Fair_Scheduler|CFS]]. Alternative schedulers are available.<br />
<br />
{{Accuracy|The official {{Pkg|linux-zen}} package does not enable MuQSS ([https://bugs.archlinux.org/task/56312 Bug Report])}}<br />
<br />
One alternative scheduler focused on desktop interactivity and responsiveness is [http://ck.kolivas.org/patches/muqss/sched-MuQSS.txt MuQSS], developed by [http://kernel.kolivas.org/ Con Kolivas]. MuQSS is included in the {{Pkg|linux-zen}} kernel package. It is also available as a stand-alone patch or as part of the wider '''-ck''' patchset. See [[Linux-ck]] and [[Linux-pf]] for more information on the patchset.<br />
<br />
=== Real-time kernel ===<br />
<br />
Some applications such as running a TV tuner card at full HD resolution (1080p) may benefit from using a [[realtime kernel]].<br />
<br />
=== Adjusting priorities of processes ===<br />
<br />
See also {{man|1|nice}} and {{man|1|renice}}.<br />
<br />
==== Ananicy ====<br />
<br />
[https://github.com/Nefelim4ag/Ananicy Ananicy] is a daemon, available in the {{AUR|ananicy-git}} package, for auto adjusting the nice levels of executables. The nice level represents the priority of the executable when allocating CPU resources.<br />
<br />
==== cgroups ====<br />
<br />
See [[cgroups]].<br />
<br />
==== Cpulimit ====<br />
<br />
[https://github.com/opsengine/cpulimit Cpulimit] is a program to limit the CPU usage percentage of a specific process. After installing {{Pkg|cpulimit}}, you may limit the CPU usage of a processes' PID using a scale of 0 to 100 times the number of CPU cores that the computer has. For example, with eight CPU cores the precentage range will be 0 to 800. Usage:<br />
<br />
$ cpulimit -l 50 -p 5081<br />
<br />
=== irqbalance ===<br />
<br />
The purpose of {{Pkg|irqbalance}} is distribute hardware interrupts across processors on a multiprocessor system in order to increase performance. It can be [[systemd#Using units|controlled]] by the provided {{ic|irqbalance.service}}.<br />
<br />
=== Turn off CPU exploit mitigations ===<br />
<br />
{{Warning|1=Do not apply this setting without considering the vulnerabilities it opens up. See [https://phoronix.com/scan.php?page=news_item&px=Linux-Improve-CPU-Spec-Switches this] and [https://linuxreviews.org/HOWTO_make_Linux_run_blazing_fast_(again)_on_Intel_CPUs this] for more information.}}<br />
<br />
Turning off CPU exploit mitigations improves performance (sometimes up to 50%). Use below [[kernel parameter]] to disable them all:<br />
<br />
mitigations=off<br />
<br />
The explanations of all the switches it toggles are given at [https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html kernel.org]. You can use {{AUR|spectre-meltdown-checker}} for vulnerability check.<br />
<br />
== Graphics ==<br />
<br />
=== Xorg configuration ===<br />
<br />
Graphics performance may depend on the settings in {{man|5|xorg.conf}}; see the [[NVIDIA]], [[ATI]], [[AMDGPU]] and [[Intel]] articles. Improper settings may stop Xorg from working, so caution is advised.<br />
<br />
=== Mesa configuration ===<br />
<br />
The performance of the Mesa drivers can be configured via [https://dri.freedesktop.org/wiki/ConfigurationInfrastructure/ drirc]. GUI configuration tools are available:<br />
<br />
* {{App|adriconf (Advanced DRI Configurator)|GUI tool to configure Mesa drivers by setting options and writing them to the standard drirc file.|https://gitlab.freedesktop.org/mesa/adriconf/|{{Pkg|adriconf}}}}<br />
* {{App|DRIconf|Configuration applet for the Direct Rendering Infrastructure. It allows customizing performance and visual quality settings of OpenGL drivers on a per-driver, per-screen and/or per-application level.|https://dri.freedesktop.org/wiki/DriConf/|{{AUR|driconf}}}}<br />
<br />
=== Overclocking ===<br />
<br />
As with CPUs, overclocking can directly improve performance, but is generally recommended against. There are several packages in the [[AUR]], such as {{AUR|amdoverdrivectrl}} (old AMD/ATI cards), {{AUR|rocm-smi}} (recent AMD cards), {{AUR|nvclock}} (old NVIDIA - up to Geforce 9), and {{Pkg|nvidia-utils}} for recent NVIDIA cards.<br />
<br />
See [[AMDGPU#Overclocking]] or [[NVIDIA/Tips and tricks#Enabling overclocking]].<br />
<br />
=== Enabling PCI Resizable BAR ===<br />
<br />
The PCI specification allows larger [[wikipedia:PCI_configuration_space#Standardized_registers|Base Address Registers]] to be used for exposing PCI devices memory to the PCI Controller. This can result in a performance increase for video cards. Having access to the the full vRAM improves performance, but also enables optimizations in the graphics driver. The combination of resizable BAR, above 4G encoding and these driver optimizations are what AMD calls [https://www.amd.com/en/technologies/smart-access-memory AMD Smart Access Memory], currently available on AMD Series 500 chipset motherboards. This setting may not be available on all motherboards, and is known to sometimes cause boot problems on certain boards.<br />
<br />
If the BAR has a 256M size, the feature is not enabled or not supported:<br />
<br />
{{hc|1=$ dmesg {{!}} grep BAR=|2=<br />
[drm] Detected VRAM RAM=8176M, BAR=256M}}<br />
<br />
To enable it, enable the setting named "Above 4G Decode" or ">4GB MMIO" in your motherboard settings. Verify that the BAR is now larger:<br />
<br />
{{hc|1=$ dmesg {{!}} grep BAR=|2=<br />
[drm] Detected VRAM RAM=8176M, BAR=8192M}}<br />
<br />
== RAM, swap and OOM handling ==<br />
<br />
=== Clock frequency and timings ===<br />
<br />
RAM can run at different clock frequencies and timings, which can be configured in the BIOS. Memory performance depends on both values. Selecting the highest preset presented by the BIOS usually improves the performance over the default setting. Note that increasing the frequency to values not supported by both motherboard and RAM vendor is overclocking, and similar risks and disadvantages apply, see [[#Overclocking]].<br />
<br />
=== Root on RAM overlay ===<br />
<br />
If running off a slow writing medium (USB, spinning HDDs) and storage requirements are low, the root may be run on a RAM overlay ontop of read only root (on disk). This can vastly improve performance at the cost of a limited writable space to root. See {{AUR|liveroot}}.<br />
<br />
=== Zram or zswap ===<br />
<br />
The [https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html zram] kernel module (previously called '''compcache''') provides a compressed block device in RAM. If you use it as swap device, the RAM can hold much more information but uses more CPU. Still, it is much quicker than swapping to a hard drive. If a system often falls back to swap, this could improve responsiveness. Using zram is also a good way to reduce disk read/write cycles due to swap on SSDs.<br />
<br />
Similar benefits (at similar costs) can be achieved using [[zswap]] rather than zram. The two are generally similar in intent although not operation: zswap operates as a compressed RAM cache and neither requires (nor permits) extensive userspace configuration.<br />
<br />
Example: To set up one lz4 compressed zram device with 32GiB capacity and a higher-than-normal priority (only for the current session):<br />
<br />
# modprobe zram<br />
# echo lz4 > /sys/block/zram0/comp_algorithm<br />
# echo 32G > /sys/block/zram0/disksize<br />
# mkswap --label zram0 /dev/zram0<br />
# swapon --priority 100 /dev/zram0<br />
<br />
To disable it again, either reboot or run<br />
<br />
# swapoff /dev/zram0<br />
# rmmod zram<br />
<br />
A detailed explanation of all steps, options and potential problems is provided in the [https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html official documentation of the zram module].<br />
<br />
The {{Pkg|systemd-swap}} package provides a {{ic|systemd-swap.service}} unit to automatically initialize zram devices. Configuration is possible in {{ic|/etc/systemd/swap.conf}}.<br />
<br />
The package {{AUR|zramswap}} provides an automated script for setting up a swap with a higher priority and a default size of 20% of the RAM size of your system. To do this automatically on every boot, [[enable]] {{ic|zramswap.service}}.<br />
<br />
==== Swap on zRAM using a udev rule ====<br />
<br />
The example below describes how to set up swap on zRAM automatically at boot with a single udev rule. No extra package should be needed to make this work.<br />
<br />
First, enable the module:<br />
<br />
{{hc|/etc/modules-load.d/zram.conf|<nowiki><br />
zram<br />
</nowiki>}}<br />
<br />
Configure the number of /dev/zram nodes you need.<br />
<br />
{{hc|/etc/modprobe.d/zram.conf|<nowiki><br />
options zram num_devices=2<br />
</nowiki>}}<br />
<br />
Create the udev rule as shown in the example.<br />
<br />
{{hc|/etc/udev/rules.d/99-zram.rules|<nowiki><br />
KERNEL=="zram0", ATTR{disksize}="512M" RUN="/usr/bin/mkswap /dev/zram0", TAG+="systemd"<br />
KERNEL=="zram1", ATTR{disksize}="512M" RUN="/usr/bin/mkswap /dev/zram1", TAG+="systemd"<br />
</nowiki>}}<br />
<br />
Add /dev/zram to your fstab.<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
/dev/zram0 none swap defaults 0 0<br />
/dev/zram1 none swap defaults 0 0<br />
</nowiki>}}<br />
<br />
=== Using the graphic card's RAM ===<br />
<br />
In the unlikely case that you have very little RAM and a surplus of video RAM, you can use the latter as swap. See [[Swap on video RAM]].<br />
<br />
=== Improving system responsiveness under low-memory conditions ===<br />
<br />
On traditional GNU/Linux system, especially for graphical workstations, when allocated memory is overcommitted, the overall system's responsiveness may degrade to a nearly unusable state before either triggering the in-kernel OOM-killer or a sufficient amount of memory got free (which is unlikely to happen quickly when the system is unresponsive, as you can hardly close any memory-hungry applications which may continue to allocate more memory). The behaviour also depends on specific setups and conditions, returning to a normal responsive state may take from a few seconds to more than half an hour, which could be a pain to wait in serious scenario like during a conference presentation.<br />
<br />
While the behaviour of the kernel as well as the userspace things under low-memory conditions may improve in the future as discussed on kernel[https://lore.kernel.org/lkml/d9802b6a-949b-b327-c4a6-3dbca485ec20@gmx.com/T/] and fedora[https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/thread/XUZLHJ5O32OX24LG44R7UZ2TMN6NY47N/] mailing list, users can use more feasible and effective options than hard-resetting the system or tuning the {{ic|vm.overcommit_*}} [[sysctl]] parameters:<br />
<br />
* Manually trigger the kernel OOM-killer with [https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html Magic SysRq key], namely {{ic|Alt+SysRq+f}}.<br />
* Use a userspace OOM daemon to tackle these automatically (or interactively).<br />
<br />
{{Warning|Triggering OOM killer to kill running applications may lose your unsaved works. It is up to you that either you are patient enough to wait in hope that applications will finally free the memory normally, or you want to bring back unresponsive system as soon as possible.}}<br />
<br />
Sometimes a user may prefer OOM daemon to SysRq because with kernel OOM-killer you cannot prioritize the process to (or not) terminate. To list some OOM daemons:<br />
<br />
* {{App|earlyoom|Simple userspace OOM-killer implementation written in C. Fedora is going to have this in their default Workstation installation [https://pagure.io/fedora-workstation/issue/119].|https://github.com/rfjakob/earlyoom|{{Pkg|earlyoom}}}}<br />
* {{App|oomd|OOM-killer implementation based on [https://lwn.net/Articles/759781/ PSI], requires Linux kernel version 4.20+. Configuration is in JSON and is quite complex. Confirmed to work in Facebook's production environment.|https://github.com/facebookincubator/oomd|{{aur|oomd}}}}<br />
* {{App|nohang|Sophisticated OOM handler written in Python, with optional PSI support, more configurable than earlyoom.|https://github.com/hakavlad/nohang|{{aur|nohang-git}}}}<br />
* {{App|low-memory-monitor|GNOME developer's effort that aims to provides better communication to userspace applications to indicate the low memory state, besides that it could be configured to trigger the kernel OOM-killer. Based on PSI, requires Linux 5.2+.|https://gitlab.freedesktop.org/hadess/low-memory-monitor/|{{aur|low-memory-monitor-git}}}}<br />
<br />
== Network ==<br />
<br />
* Kernel networking: see [[Sysctl#Improving performance]]<br />
* NIC: see [[Network configuration#Set device MTU and queue length]]<br />
* DNS: consider using a caching DNS resolver, see [[Domain name resolution#DNS servers]]<br />
* Samba: see [[Samba#Improve throughput]]<br />
<br />
== Watchdogs ==<br />
<br />
According to [[Wikipedia:Watchdog timer]]:<br />
<br />
:A watchdog timer [...] is an electronic timer that is used to detect and recover from computer malfunctions. During normal operation, the computer regularly resets the watchdog timer [...]. If, [...], the computer fails to reset the watchdog, the timer will elapse and generate a timeout signal [...] used to initiate corrective [...] actions [...] typically include placing the computer system in a safe state and restoring normal system operation.<br />
<br />
Many users need this feature due to their system's mission-critical role (i.e. servers), or because of the lack of power reset (i.e. embedded devices). Thus, this feature is required for a good operation in some situations. On the other hand, normal users (i.e. desktop and laptop) do not need this feature and can disable it.<br />
<br />
To disable watchdog timers (both software and hardware), append {{ic|nowatchdog}} to your boot parameters.<br />
<br />
To check the new configuration do:<br />
<br />
# cat /proc/sys/kernel/watchdog<br />
<br />
or use:<br />
<br />
# wdctl<br />
<br />
After you disabled watchdogs, you can ''optionally'' avoid the loading of the module responsible of the hardware watchdog, too. Do it by [[blacklisting]] the related module, e.g. {{ic|iTCO_wdt}}.<br />
<br />
{{Note|1=Some users [https://bbs.archlinux.org/viewtopic.php?id=221239 reported] the {{ic|nowatchdog}} parameter does not work as expected but they have successfully disabled the watchdog (at least the hardware one) by blacklisting the above-mentioned module.}}<br />
<br />
Either action will speed up your boot and shutdown, because one less module is loaded. Additionally disabling watchdog timers increases performance and [[Power management#Disabling NMI watchdog|lowers power consumption]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?id=163768], [https://bbs.archlinux.org/viewtopic.php?id=165834], [http://0pointer.de/blog/projects/watchdog.html], and [https://www.kernel.org/doc/html/latest/watchdog/watchdog-parameters.html] for more information.<br />
<br />
== See also ==<br />
<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Performance_Tuning_Guide/index.html Red Hat Performance Tuning Guide]<br />
* [https://www.thomas-krenn.com/en/wiki/Linux_Performance_Measurements_using_vmstat Linux Performance Measurements using vmstat]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Access_Control_Lists&diff=634501Talk:Access Control Lists2020-09-06T15:52:08Z<p>Pgoetz: Explanation of the original changes to the "mask" note on the POSIX ACL page</p>
<hr />
<div>== Increase security of your web server ==<br />
<br />
Just as an aside, using root in an authorization example is maybe not the best way to test. For example, I recently got burned by the fact that sometimes the system treats a user's matching group the same as the user; e.g. if you restrict the access of user '''foo''' in /etc/security/access.conf, it will apply the same restrictions to the group '''foo'''.<br />
<br />
Here is my real world example:<br />
<br />
root@kraken:/EM# ls -ld acltest<br />
drwxr-s---+ 2 mclellanimages mclellanlab 10 Sep 6 09:51 acltest<br />
root@kraken:/EM# getfacl acltest<br />
# file: acltest<br />
# owner: mclellanimages<br />
# group: mclellanlab<br />
# flags: -s-<br />
user::rwx<br />
group::r-x<br />
other::---<br />
default:user::rwx<br />
default:user:jmclellan:rwx<br />
default:group::r-x<br />
default:mask::rwx<br />
default:other::---<br />
<br />
I created a default ACL for this folder using<br />
<br />
# setfacl -d -m u:jmclellan:rwX acltest<br />
<br />
Now:<br />
<br />
root@kraken:/EM# cd acltest<br />
root@kraken:/EM/acltest# touch a<br />
root@kraken:/EM/acltest# ls -l<br />
total 0<br />
-rw-rw----+ 1 root mclellanlab 0 Sep 6 09:54 a<br />
root@kraken:/EM/acltest# getfacl a<br />
# file: a<br />
# owner: root<br />
# group: mclellanlab<br />
user::rw-<br />
user:jmclellan:rwx #effective:rw-<br />
group::r-x #effective:r--<br />
mask::rw-<br />
other::---<br />
<br />
Notice that it gave the group write permissions even though the umask for root is 755. The files in the actual data folder are placed there by a script, and the group should only have read permissions. The ''mclellanimages'' user is programmatic; the actual human who should be able to edit the files is ''jmclellan'', and so far that permission is intact. But watch what happens if write permission is removed from the group:<br />
<br />
root@kraken:/EM/acltest# chmod g-w a<br />
root@kraken:/EM/acltest# ls -l<br />
total 0<br />
-rw-r-----+ 1 root mclellanlab 0 Sep 6 09:54 a<br />
root@kraken:/EM/acltest# getfacl a<br />
# file: a<br />
# owner: root<br />
# group: mclellanlab<br />
user::rw-<br />
user:jmclellan:rwx #effective:r--<br />
group::r-x #effective:r--<br />
mask::r--<br />
other::---<br />
<br />
Notice that jmclellan's effective permissions on this file are now r--, and he can no longer edit the file. This is what my editing of the note on the Wiki page was intended to illustrate. This surely is one of the most common use cases for extended POSIX ACLs. N people have full privileges (in this case, 2), but read access is afforded to a much larger group. I found the way this works endlessly confusing until I figured out what was going on, which is why I was trying save the next POSIX ACL user the same frustration by updating this note.<br />
<br />
'''(In the example above I did not reset the ownership of the file to ''mclellanimages'', but the behavior is exactly the same when I do.)'''<br />
<br />
This is what the setfacl man page says:<br />
<br />
The default behavior of setfacl is to recalculate the ACL mask entry, unless a mask<br />
entry was explicitly given. The mask entry is set to the union of all permissions of the owning group,<br />
and all named user and group entries.''<br />
<br />
As you can see from my example, that is absolutely not correct: the mask entry is set to the '''intersection''' of all permissions.<br />
<br />
Note further that the ''--no-mask'' flag doesn't seem to work, either:<br />
<br />
root@kraken:/EM/acltest# setfacl --no-mask -m u:pgoetz:rw- a<br />
root@kraken:/EM/acltest# getfacl a<br />
# file: a<br />
# owner: root<br />
# group: mclellanlab<br />
user::rw-<br />
user:jmclellan:rw- #effective:r--<br />
user:pgoetz:rw- #effective:r--<br />
group::r-x #effective:r--<br />
mask::r--<br />
other::---<br />
<br />
So, what's not documented anywhere is the way to get around this. What you do is set very permissive minimal POSIX permissions for a group which consists of just the user, and then use POSIX extended ACLs for all actual permissions:<br />
<br />
root@kraken:/EM# ls -ld acltest<br />
drwxrws--- 2 mclellanimages mclellanimages 10 Sep 6 10:33 acltest<br />
root@kraken:/EM# setfacl -d -m u:jmclellan:rwX acltest<br />
root@kraken:/EM# setfacl -d -m g:mclellanlab:rX acltest<br />
root@kraken:/EM# cd acltest<br />
root@kraken:/EM/acltest# touch a<br />
root@kraken:/EM/acltest# ls -l<br />
total 0<br />
-rw-rw----+ 1 root mclellanimages 0 Sep 6 10:33 a<br />
root@kraken:/EM/acltest# chown mclellanimages a<br />
root@kraken:/EM/acltest# ls -l<br />
total 0<br />
-rw-rw----+ 1 mclellanimages mclellanimages 0 Sep 6 10:33 a<br />
root@kraken:/EM/acltest# getfacl a<br />
# file: a<br />
# owner: mclellanimages<br />
# group: mclellanimages<br />
user::rw-<br />
user:jmclellan:rwx #effective:rw-<br />
group::rwx #effective:rw-<br />
group:mclellanlab:r-x #effective:r--<br />
mask::rw-<br />
other::---<br />
<br />
[[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 15:52, 6 September 2020 (UTC)<br />
<br />
<br />
I struggled understanding the last revision of this section. I tried to reproduce it in a more clear way, but I'm not sure I achieved what the original author was trying to do.<br />
<br />
I still think that the example lacks necessary real world applicability. If at all, the web server should only have access to a specific folder within the user's home directory. <br />
<br />
Any more suggestions?<br />
<br />
=== Original section ===<br />
<br />
You can now add permissions to our home directory and/or site directory only to nobody user any anyone else - without "whole world" to increase your security.<br />
<br />
Add permissions '''+x''' for nobody user on your home directory via ACL:<br />
# setfacl -m "u:nobody:--x" /home/homeusername/<br />
Now you can remove whole world rx permissions:<br />
# chmod o-rx /home/homeusername/<br />
Check our changes:<br />
<br />
# file: username/<br />
# owner: username<br />
# group: users<br />
user::rwx<br />
user:nobody:--x<br />
group::r-x<br />
mask::r-x<br />
other::---<br />
<br />
As we can see others do not have any permissions but user nobody have "x" permission so they can "look" into users directory and give access to users pages from their home directories to www server. Of course if www server work as nobody user. But - whole world except nobody - do not have any permissions.<br />
<br />
{{unsigned|13 April 2015 20:46|Foggs}}<br />
<br />
:Is the section relevant only for [[Apache_HTTP_Server#User_directories|Apache]] or also other web servers? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:16, 17 April 2015 (UTC)<br />
<br />
== ACL mask entry ==<br />
<br />
The original note about the {{ic|--mask}} option (which was taken from {{man|1|setfacl}}) was determined as [https://wiki.archlinux.org/index.php?title=Access_Control_Lists&diff=next&oldid=634053 inaccurate], but the new note does not seem correct either.<br />
<br />
Let's do a quick test:<br />
<br />
{{hc|<br />
$ touch test<br />
$ chmod 755 test<br />
$ getfacl test<br />
|<br />
# file: test<br />
# owner: lahwaacz<br />
# group: lahwaacz<br />
user::rwx<br />
group::r-x<br />
other::r-x<br />
}}<br />
<br />
So the group has r-x permissions, which is what the note talks about. Let's add an ACL for user root with rwx permissions:<br />
<br />
{{hc|<br />
$ setfacl -m u:root:rwx test<br />
$ getfacl test<br />
|<br />
# file: test<br />
# owner: lahwaacz<br />
# group: lahwaacz<br />
user::rwx<br />
user:root:rwx<br />
group::r-x<br />
mask::rwx<br />
other::r-x<br />
}}<br />
<br />
The result is not what the note says: root has full rwx access to the file, there is no "effective" r-x permission. Especially, getfacl says the mask is rwx, not r-x.<br />
<br />
Interestingly, note that the (effective?) group permissions changed:<br />
<br />
{{hc|$ ls -lah test|<br />
-rwxrwxr-x+ 1 lahwaacz lahwaacz 0 Sep 2 10:12 test<br />
}}<br />
<br />
When you run {{ic|setfacl -b test}}, it will be the original 755 again. Or when you {{ic|chmod 755 test}}, the mask entry will change and result in effective r-x permission for user root:<br />
<br />
{{hc|<br />
$ chmod 755 test<br />
$ getfacl test<br />
|<br />
# file: test<br />
# owner: lahwaacz<br />
# group: lahwaacz<br />
user::rwx<br />
user:root:rwx #effective:r-x<br />
group::r-x<br />
mask::r-x<br />
other::r-x<br />
}}<br />
<br />
This is completely different behaviour than what the note currently says.<br />
<br />
– [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:21, 2 September 2020 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Access_Control_Lists&diff=634054Access Control Lists2020-09-01T21:42:50Z<p>Pgoetz: Clarified how POSIX ACL masks work -- the man page is flat out wrong on this, and I have no idea why this wasn't fixed long ago.</p>
<hr />
<div>[[Category:Access control]]<br />
[[es:Access Control Lists]]<br />
[[ja:アクセス制御リスト]]<br />
[[pt:Access Control Lists]]<br />
[[ru:Access Control Lists]]<br />
[[zh-hans:Access Control Lists]]<br />
[[Wikipedia:Access Control List|Access control list]] (ACL) provides an additional, more flexible permission mechanism for [[file systems]]. It is designed to assist with UNIX file permissions. ACL allows you to give permissions for any user or group to any disk resource.<br />
<br />
== Installation ==<br />
<br />
The {{Pkg|acl}} package is a dependency of [[systemd]], it should already be installed.<br />
<br />
== Enable ACL ==<br />
<br />
To enable ACL, the filesystem must be mounted with the {{ic|acl}} option. You can use [[fstab]] to make it permanent on your system.<br />
<br />
There is a possibility that the {{ic|acl}} option is already active as default mount option on the filesystem. [[Btrfs]] does and Ext2/[[Ext3|3]]/[[Ext4|4]] filesystems do too. Use the following command to check ext* formatted partitions for the option:<br />
<br />
{{hc|# tune2fs -l /dev/sd''XY'' {{!}} grep "Default mount options:"|<br />
Default mount options: user_xattr acl<br />
}}<br />
<br />
Also check that the default mount option is not overridden, in such case you will see {{ic|noacl}} in {{ic|/proc/mounts}} in the relevant line.<br />
<br />
You can set the default mount options of a filesystem using the {{ic|tune2fs -o ''option'' ''partition''}} command, for example:<br />
<br />
# tune2fs -o acl /dev/sd''XY''<br />
<br />
Using the default mount options instead of an entry in {{ic|/etc/fstab}} is very useful for external drives, such partition will be mounted with {{ic|acl}} option also on other Linux machines. There is no need to edit {{ic|/etc/fstab}} on every machine.<br />
<br />
{{Note|<br />
* {{ic|acl}} is specified as default mount option when creating an ext2/3/4 filesystem. This is configured in {{ic|/etc/mke2fs.conf}}.<br />
* The default mount options are not listed in {{ic|/proc/mounts}}.<br />
}}<br />
<br />
== Usage ==<br />
<br />
=== Set ACL ===<br />
<br />
The ACL can be modified using the ''setfacl'' command.<br />
<br />
{{Tip|You can list file/directory permission changes without modifying the permissions (i.e. dry-run) by appending the {{ic|--test}} flag.}}<br />
<br />
To set permissions for a user ({{ic|''user''}} is either the user name or ID):<br />
<br />
# setfacl -m "u:''user:permissions''" <file/dir><br />
<br />
To set permissions for a group ({{ic|''group''}} is either the group name or ID):<br />
<br />
# setfacl -m "g:''group:permissions''" <file/dir><br />
<br />
To set permissions for others:<br />
<br />
# setfacl -m "other:''permissions''" <file/dir><br />
<br />
To allow all ''newly created'' files or directories to inherit entries from the parent directory (this will not affect files which will be ''copied'' into the directory):<br />
<br />
# setfacl -dm "''entry''" <dir><br />
<br />
To remove a specific entry:<br />
<br />
# setfacl -x "''entry''" <file/dir><br />
<br />
To remove the default entries:<br />
<br />
# setfacl -k <file/dir><br />
<br />
To remove all entries (entries of the owner, group and others are retained):<br />
<br />
# setfacl -b <file/dir><br />
<br />
{{Note|The default behavior of ''setfacl'' is to recalculate the ACL mask entry, unless a {{ic|--mask}} entry was explicitly given. The mask entry indicates the maximum permissions allowed for users (other than the owner) and for groups. Unless explicitly set, this will match the permissions of the default group. To clarify what this means, suppose the group owning a directory has r-x permissions. If you add an extended ACL user or group with rwx permissions, the ''effective'' permissions of this user or group will be r-x. The reason for this is so that there are no surprises when a file from a system which doesn't support extended POSIX ACLs is made available on a system which does..}}<br />
<br />
{{Tip|To apply operations to all files and directories recursively, append the {{ic|-R}} argument.}}<br />
<br />
=== Show ACL ===<br />
<br />
To show permissions, use:<br />
<br />
# getfacl <file/dir><br />
<br />
== Examples ==<br />
<br />
Set all permissions for user {{ic|johnny}} to file named {{ic|abc}}:<br />
<br />
# setfacl -m "u:johnny:rwx" abc<br />
<br />
Check permissions:<br />
<br />
{{hc|# getfacl abc|<br />
# file: abc<br />
# owner: someone<br />
# group: someone<br />
user::rw-<br />
user:johnny:rwx<br />
group::r--<br />
mask::rwx<br />
other::r--<br />
}}<br />
<br />
Change permissions for user {{ic|johnny}}:<br />
<br />
# setfacl -m "u:johnny:r-x" abc<br />
<br />
Check permissions:<br />
<br />
{{hc|# getfacl abc|<br />
# file: abc<br />
# owner: someone<br />
# group: someone<br />
user::rw-<br />
user:johnny:r-x<br />
group::r--<br />
mask::r-x<br />
other::r--<br />
}}<br />
<br />
Remove all extended ACL entries:<br />
<br />
# setfacl -b abc<br />
<br />
Check permissions:<br />
<br />
{{hc|# getfacl abc|<br />
# file: abc<br />
# owner: someone<br />
# group: someone<br />
user::rw-<br />
group::r--<br />
other::r--<br />
}}<br />
<br />
=== Output of ls command ===<br />
<br />
You will notice that there is an ACL for a given file because it will exhibit a {{ic|'''+'''}} (plus sign) after its Unix permissions in the output of {{ic|ls -l}}.<br />
<br />
{{hc|$ ls -l /dev/audio|<br />
crw-rw----+ 1 root audio 14, 4 nov. 9 12:49 /dev/audio<br />
}}<br />
<br />
{{hc|$ getfacl /dev/audio|<br />
getfacl: Removing leading '/' from absolute path names<br />
# file: dev/audio<br />
# owner: root<br />
# group: audio<br />
user::rw-<br />
user:solstice:rw-<br />
group::rw-<br />
mask::rw-<br />
other::---<br />
}}<br />
<br />
=== Granting execution permissions for private files to a web server ===<br />
<br />
The following technique describes how a process like a [[web server]] can be granted access to files that reside in a user's home directory, without compromising security by giving the whole world access.<br />
<br />
In the following we assume that the web server runs as the user {{ic|http}} and grant it access to {{ic|geoffrey}}'s home directory {{ic|/home/geoffrey}}.<br />
<br />
The first step is granting execution permissions for the user {{ic|http}}:<br />
<br />
# setfacl -m "u:http:--x" /home/geoffrey<br />
<br />
{{Note|Execution permissions to a directory are necessary for a process to list the directory's content.}}<br />
<br />
Since the user {{ic|http}} is now able to access files in {{ic|/home/geoffrey}}, others no longer need access:<br />
<br />
# chmod o-rx /home/geoffrey<br />
<br />
Use {{ic|getfacl}} to verify the changes:<br />
<br />
{{hc|$ getfacl /home/geoffrey|<br />
getfacl: Removing leading '/' from absolute path names<br />
# file: home/geoffrey<br />
# owner: geoffrey<br />
# group: geoffrey<br />
user::rwx<br />
user:http:--x<br />
group::r-x<br />
mask::r-x<br />
other::---<br />
}}<br />
<br />
As the above output shows, {{ic|other}}'s no longer have any permissions, but the user {{ic|http}} is still able to access the files, thus security might be considered increased.<br />
<br />
{{Note|One may need to give write access for the user {{ic|http}} on specific directories and/or files:<br />
# setfacl -dm "u:http:rwx" /home/geoffrey/project1/cache<br />
}}<br />
<br />
== See also ==<br />
<br />
* {{man|1|getfacl}}<br />
* {{man|1|setfacl}}<br />
* [https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html POSIX Access Control Lists on Linux]<br />
* [https://unix.stackexchange.com/questions/1314/how-to-set-default-file-permissions-for-all-folders-files-in-a-directory How to set default file permissions for all folders/files in a directory?]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Access_Control_Lists&diff=634052Access Control Lists2020-09-01T21:13:00Z<p>Pgoetz: Added cautionary note about the most cited reference on POSIX ACLs</p>
<hr />
<div>[[Category:Access control]]<br />
[[es:Access Control Lists]]<br />
[[ja:アクセス制御リスト]]<br />
[[pt:Access Control Lists]]<br />
[[ru:Access Control Lists]]<br />
[[zh-hans:Access Control Lists]]<br />
[[Wikipedia:Access Control List|Access control list]] (ACL) provides an additional, more flexible permission mechanism for [[file systems]]. It is designed to assist with UNIX file permissions. ACL allows you to give permissions for any user or group to any disk resource.<br />
<br />
== Installation ==<br />
<br />
The {{Pkg|acl}} package is a dependency of [[systemd]], it should already be installed.<br />
<br />
== Enable ACL ==<br />
<br />
To enable ACL, the filesystem must be mounted with the {{ic|acl}} option. You can use [[fstab]] to make it permanent on your system.<br />
<br />
There is a possibility that the {{ic|acl}} option is already active as default mount option on the filesystem. [[Btrfs]] does and Ext2/[[Ext3|3]]/[[Ext4|4]] filesystems do too. Use the following command to check ext* formatted partitions for the option:<br />
<br />
{{hc|# tune2fs -l /dev/sd''XY'' {{!}} grep "Default mount options:"|<br />
Default mount options: user_xattr acl<br />
}}<br />
<br />
Also check that the default mount option is not overridden, in such case you will see {{ic|noacl}} in {{ic|/proc/mounts}} in the relevant line.<br />
<br />
You can set the default mount options of a filesystem using the {{ic|tune2fs -o ''option'' ''partition''}} command, for example:<br />
<br />
# tune2fs -o acl /dev/sd''XY''<br />
<br />
Using the default mount options instead of an entry in {{ic|/etc/fstab}} is very useful for external drives, such partition will be mounted with {{ic|acl}} option also on other Linux machines. There is no need to edit {{ic|/etc/fstab}} on every machine.<br />
<br />
{{Note|<br />
* {{ic|acl}} is specified as default mount option when creating an ext2/3/4 filesystem. This is configured in {{ic|/etc/mke2fs.conf}}.<br />
* The default mount options are not listed in {{ic|/proc/mounts}}.<br />
}}<br />
<br />
== Usage ==<br />
<br />
=== Set ACL ===<br />
<br />
The ACL can be modified using the ''setfacl'' command.<br />
<br />
{{Tip|You can list file/directory permission changes without modifying the permissions (i.e. dry-run) by appending the {{ic|--test}} flag.}}<br />
<br />
To set permissions for a user ({{ic|''user''}} is either the user name or ID):<br />
<br />
# setfacl -m "u:''user:permissions''" <file/dir><br />
<br />
To set permissions for a group ({{ic|''group''}} is either the group name or ID):<br />
<br />
# setfacl -m "g:''group:permissions''" <file/dir><br />
<br />
To set permissions for others:<br />
<br />
# setfacl -m "other:''permissions''" <file/dir><br />
<br />
To allow all ''newly created'' files or directories to inherit entries from the parent directory (this will not affect files which will be ''copied'' into the directory):<br />
<br />
# setfacl -dm "''entry''" <dir><br />
<br />
To remove a specific entry:<br />
<br />
# setfacl -x "''entry''" <file/dir><br />
<br />
To remove the default entries:<br />
<br />
# setfacl -k <file/dir><br />
<br />
To remove all entries (entries of the owner, group and others are retained):<br />
<br />
# setfacl -b <file/dir><br />
<br />
{{Note|The default behavior of ''setfacl'' is to recalculate the ACL mask entry, unless a {{ic|--mask}} entry was explicitly given. The mask entry is set to the union of all permissions of the owning group, and all named user and group entries (These are exactly the entries affected by the mask entry).}}<br />
<br />
{{Tip|To apply operations to all files and directories recursively, append the {{ic|-R}} argument.}}<br />
<br />
=== Show ACL ===<br />
<br />
To show permissions, use:<br />
<br />
# getfacl <file/dir><br />
<br />
== Examples ==<br />
<br />
Set all permissions for user {{ic|johnny}} to file named {{ic|abc}}:<br />
<br />
# setfacl -m "u:johnny:rwx" abc<br />
<br />
Check permissions:<br />
<br />
{{hc|# getfacl abc|<br />
# file: abc<br />
# owner: someone<br />
# group: someone<br />
user::rw-<br />
user:johnny:rwx<br />
group::r--<br />
mask::rwx<br />
other::r--<br />
}}<br />
<br />
Change permissions for user {{ic|johnny}}:<br />
<br />
# setfacl -m "u:johnny:r-x" abc<br />
<br />
Check permissions:<br />
<br />
{{hc|# getfacl abc|<br />
# file: abc<br />
# owner: someone<br />
# group: someone<br />
user::rw-<br />
user:johnny:r-x<br />
group::r--<br />
mask::r-x<br />
other::r--<br />
}}<br />
<br />
Remove all extended ACL entries:<br />
<br />
# setfacl -b abc<br />
<br />
Check permissions:<br />
<br />
{{hc|# getfacl abc|<br />
# file: abc<br />
# owner: someone<br />
# group: someone<br />
user::rw-<br />
group::r--<br />
other::r--<br />
}}<br />
<br />
=== Output of ls command ===<br />
<br />
You will notice that there is an ACL for a given file because it will exhibit a {{ic|'''+'''}} (plus sign) after its Unix permissions in the output of {{ic|ls -l}}.<br />
<br />
{{hc|$ ls -l /dev/audio|<br />
crw-rw----+ 1 root audio 14, 4 nov. 9 12:49 /dev/audio<br />
}}<br />
<br />
{{hc|$ getfacl /dev/audio|<br />
getfacl: Removing leading '/' from absolute path names<br />
# file: dev/audio<br />
# owner: root<br />
# group: audio<br />
user::rw-<br />
user:solstice:rw-<br />
group::rw-<br />
mask::rw-<br />
other::---<br />
}}<br />
<br />
=== Granting execution permissions for private files to a web server ===<br />
<br />
The following technique describes how a process like a [[web server]] can be granted access to files that reside in a user's home directory, without compromising security by giving the whole world access.<br />
<br />
In the following we assume that the web server runs as the user {{ic|http}} and grant it access to {{ic|geoffrey}}'s home directory {{ic|/home/geoffrey}}.<br />
<br />
The first step is granting execution permissions for the user {{ic|http}}:<br />
<br />
# setfacl -m "u:http:--x" /home/geoffrey<br />
<br />
{{Note|Execution permissions to a directory are necessary for a process to list the directory's content.}}<br />
<br />
Since the user {{ic|http}} is now able to access files in {{ic|/home/geoffrey}}, others no longer need access:<br />
<br />
# chmod o-rx /home/geoffrey<br />
<br />
Use {{ic|getfacl}} to verify the changes:<br />
<br />
{{hc|$ getfacl /home/geoffrey|<br />
getfacl: Removing leading '/' from absolute path names<br />
# file: home/geoffrey<br />
# owner: geoffrey<br />
# group: geoffrey<br />
user::rwx<br />
user:http:--x<br />
group::r-x<br />
mask::r-x<br />
other::---<br />
}}<br />
<br />
As the above output shows, {{ic|other}}'s no longer have any permissions, but the user {{ic|http}} is still able to access the files, thus security might be considered increased.<br />
<br />
{{Note|One may need to give write access for the user {{ic|http}} on specific directories and/or files:<br />
# setfacl -dm "u:http:rwx" /home/geoffrey/project1/cache<br />
}}<br />
<br />
{{Note| The classic Gruenbacher article cited below (which will be the first hit in a Google seach) is riddled with typos/errors, which can be confusing when you're first learning about POSIX ACLs. Reader beware.}}<br />
<br />
== See also ==<br />
<br />
* {{man|1|getfacl}}<br />
* {{man|1|setfacl}}<br />
* [https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html POSIX Access Control Lists on Linux]<br />
* [https://unix.stackexchange.com/questions/1314/how-to-set-default-file-permissions-for-all-folders-files-in-a-directory How to set default file permissions for all folders/files in a directory?]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Network_bridge&diff=625730Network bridge2020-07-17T21:31:49Z<p>Pgoetz: Re-added deprecation note, but now with reference.</p>
<hr />
<div>[[Category:Networking]]<br />
[[ja:ネットワークブリッジ]]<br />
[[zh-hans:Network bridge]]<br />
{{Related articles start}}<br />
{{Related|Bridge with netctl}}<br />
{{Related|Network configuration#Bonding or LAG}}<br />
{{Related articles end}}<br />
A bridge is a piece of software used to unite two or more network segments. A bridge behaves like a virtual network switch, working transparently (the other machines do not need to know or care about its existence). Any real devices (e.g. {{ic|eth0}}) and virtual devices (e.g. {{ic|tap0}}) can be connected to it.<br />
<br />
This article explains how to create a bridge that contains at least an ethernet device. This is useful for things like the bridge mode of [[QEMU]], setting a software based access point, etc.<br />
<br />
== Creating a bridge ==<br />
<br />
There are a number of ways to create a bridge.<br />
<br />
=== With iproute2 ===<br />
<br />
This section describes the management of a network bridge using the ''ip'' tool from the {{Pkg|iproute2}} package, which is required by the {{Pkg|base}} [[meta package]].<br />
<br />
Create a new bridge and change its state to up:<br />
<br />
# ip link add name ''bridge_name'' type bridge<br />
# ip link set ''bridge_name'' up<br />
<br />
To add an interface (e.g. eth0) into the bridge, its state must be up:<br />
<br />
# ip link set eth0 up<br />
<br />
Adding the interface into the bridge is done by setting its master to {{ic|''bridge_name''}}:<br />
<br />
# ip link set eth0 master ''bridge_name''<br />
<br />
To show the existing bridges and associated interfaces, use the ''bridge'' utility (also part of {{Pkg|iproute2}}). See {{man|8|bridge}} for details.<br />
<br />
# bridge link<br />
<br />
This is how to remove an interface from a bridge:<br />
<br />
# ip link set eth0 nomaster<br />
<br />
The interface will still be up, so you may also want to bring it down:<br />
<br />
# ip link set eth0 down<br />
<br />
To delete a bridge issue the following command:<br />
<br />
# ip link delete ''bridge_name'' type bridge<br />
<br />
This will automatically remove all interfaces from the bridge. The slave interfaces will still be up, though, so you may also want to bring them down after.<br />
<br />
=== With bridge-utils ===<br />
<br />
This section describes the management of a network bridge using the legacy ''brctl'' tool from the {{Pkg|bridge-utils}} package, which is available in the [[official repositories]]. See {{man|8|brctl}} for full listing of options.<br />
<br />
<br />
{{Note| The use of brctl is deprecated and is considered obsolete. See the Notes section of {{man|8|brctl}} for details.}}<br />
<br />
Create a new bridge:<br />
<br />
# brctl addbr ''bridge_name''<br />
<br />
Add a device to a bridge, for example {{ic|eth0}}:<br />
<br />
{{Note|Adding an interface to a bridge will cause the interface to lose its existing IP address. If you are connected remotely via the interface you intend to add to the bridge, you will lose your connection. This problem can be worked around by scripting the bridge to be created at system startup.}}<br />
<br />
# brctl addif ''bridge_name'' eth0<br />
<br />
Show current bridges and what interfaces they are connected to:<br />
<br />
$ brctl show<br />
<br />
Set the bridge device up:<br />
<br />
# ip link set dev ''bridge_name'' up<br />
<br />
Delete a bridge, you need to first set it to ''down'':<br />
<br />
# ip link set dev ''bridge_name'' down<br />
# brctl delbr ''bridge_name''<br />
<br />
{{Note|To enable the [http://ebtables.netfilter.org/documentation/bridge-nf.html bridge-netfilter] functionality, you need to manually load the {{ic|br_netfilter}} module:<br />
<br />
# modprobe br_netfilter<br />
<br />
See also [[Kernel modules#Automatic module loading with systemd]].<br />
}}<br />
<br />
=== With netctl ===<br />
<br />
See [[Bridge with netctl]].<br />
<br />
=== With systemd-networkd ===<br />
<br />
See [[systemd-networkd#Bridge interface]].<br />
<br />
=== With NetworkManager ===<br />
<br />
[[GNOME]]'s Network settings can create bridges, but currently will not auto-connect to them or slave/attached interfaces. Open Network Settings, add a new interface of type Bridge, add a new bridged connection, and select the MAC address of the device to attach to the bridge.<br />
<br />
[[KDE]]'s {{Pkg|plasma-nm}} can create bridges. In order to view, create and modify bridge interfaces open the Connections window either by right clicking the Networks applet in the system tray and selecting ''Configure Network Connections...'' or from ''System Settings > Connections''. Click the ''Configuration'' button in the lower left corner of the module and enable "Show virtual connections". A session restart will be necessary to use the enabled functionality.<br />
<br />
{{Pkg|nm-connection-editor}} can create bridges in the same manner as GNOME's Network settings.<br />
<br />
{{ic|nmcli}} from {{Pkg|networkmanager}} can create bridges. Creating a bridge with [[Wikipedia:Spanning Tree Protocol|STP]] disabled (to avoid the bridge being advertised on the network):<br />
<br />
$ nmcli connection add type bridge ifname br0 stp no<br />
<br />
Making interface {{ic|enp30s0}} a slave to the bridge:<br />
<br />
$ nmcli connection add type bridge-slave ifname enp30s0 master br0<br />
<br />
Setting the existing connection as down:<br />
<br />
$ nmcli connection down ''Connection''<br />
<br />
Setting the new bridge as up:<br />
<br />
$ nmcli connection up bridge-br0<br />
<br />
If NetworkManager's default interface for the device you added to the bridge connects automatically, you may want to disable that by clicking the gear next to it in Network Settings, and unchecking "Connect automatically" under "Identity."<br />
<br />
== Assigning an IP address ==<br />
<br />
When the bridge is fully set up, it can be assigned an IP address:<br />
<br />
# ip addr add dev ''bridge_name'' 192.168.66.66/24<br />
<br />
{{Expansion|This section needs to be connected to the link-level part described in [[QEMU#Tap networking with QEMU]]. For now, see the instructions given there.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Wireless interface on a bridge ===<br />
<br />
To add a wireless interface to a bridge, you first have to assign the wireless interface to an access point or start an access point with [[Software access point|hostapd]]. Otherwise the wireless interface will not be added to the bridge.<br />
<br />
See also [[Debian:BridgeNetworkConnections#Bridging with a wireless NIC]].<br />
<br />
=== Speeding up traffic destinated to the bridge itself ===<br />
<br />
In some situations the bridge not only serves as a bridge box, but also talks to other hosts. Packets that arrive on a bridge port and that are destinated to the bridge box itself will by default enter the iptables INPUT chain with the logical bridge port as input device. These packets will be queued twice by the network code, the first time they are queued after they are received by the network device. The second time after the bridge code examined the destination MAC address and determined it was a locally destinated packet and therefore decided to pass the frame up to the higher protocol stack.[http://ebtables.netfilter.org/examples/basic.html#ex_speed]<br />
<br />
The way to let locally destinated packets be queued only once is by brouting them in the BROUTING chain of the broute table. Suppose br0 has an IP address and that br0's bridge ports do not have an IP address. Using the following rule should make all locally directed traffic be queued only once: <br />
<br />
# ebtables -t broute -A BROUTING -d $MAC_OF_BR0 -p ipv4 -j redirect --redirect-target DROP<br />
<br />
The replies from the bridge will be sent out through the br0 device (assuming your routing table is correct and sends all traffic through br0), so everything keeps working neatly, without the performance loss caused by the packet being queued twice. <br />
<br />
The redirect target is needed because the MAC address of the bridge port is not necessarily equal to the MAC address of the bridge device. The packets destinated to the bridge box will have a destination MAC address equal to that of the bridge br0, so that destination address must be changed to that of the bridge port.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No networking after bridge configuration ===<br />
<br />
{{Style|This problem is pointed out as a note in [[#With bridge-utils]]. It should be made clear in all other sections and running a DHCP client should be added to [[#Assigning an IP address]].}}<br />
<br />
It may help to remove all IP addresses and routes from the interface (e.g. {{ic|eth0}}) that was added to the bridge and configure these parameters for the bridge instead.<br />
<br />
First of all, make sure there is no [[dhcpcd]] instance running for {{ic|eth0}}, otherwise the deleted addresses may be reassigned.<br />
<br />
Remove address and route from the {{ic|eth0}} interface:<br />
<br />
# ip addr del ''address'' dev eth0<br />
# ip route del ''address'' dev eth0<br />
<br />
Now IP address and route for the earlier configured bridge must be set. This is usually done by starting a DHCP client for this interface. Otherwise, consult [[Network configuration]] for manual configuration.<br />
<br />
== See also ==<br />
<br />
* [http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge Official documentation for bridge-utils]<br />
* [http://www.linuxfoundation.org/collaborate/workgroups/networking/iproute2 Official documentation for iproute2]<br />
* [http://ebtables.netfilter.org/br_fw_ia/br_fw_ia.html ebtables/iptables interaction on a Linux-based bridge]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Network_bridge&diff=625717Network bridge2020-07-17T17:52:23Z<p>Pgoetz: Add note that brctl is considered obsolete.</p>
<hr />
<div>[[Category:Networking]]<br />
[[ja:ネットワークブリッジ]]<br />
[[zh-hans:Network bridge]]<br />
{{Related articles start}}<br />
{{Related|Bridge with netctl}}<br />
{{Related|Network configuration#Bonding or LAG}}<br />
{{Related articles end}}<br />
A bridge is a piece of software used to unite two or more network segments. A bridge behaves like a virtual network switch, working transparently (the other machines do not need to know or care about its existence). Any real devices (e.g. {{ic|eth0}}) and virtual devices (e.g. {{ic|tap0}}) can be connected to it.<br />
<br />
This article explains how to create a bridge that contains at least an ethernet device. This is useful for things like the bridge mode of [[QEMU]], setting a software based access point, etc.<br />
<br />
== Creating a bridge ==<br />
<br />
There are a number of ways to create a bridge.<br />
<br />
=== With iproute2 ===<br />
<br />
This section describes the management of a network bridge using the ''ip'' tool from the {{Pkg|iproute2}} package, which is required by the {{Pkg|base}} [[meta package]].<br />
<br />
Create a new bridge and change its state to up:<br />
<br />
# ip link add name ''bridge_name'' type bridge<br />
# ip link set ''bridge_name'' up<br />
<br />
To add an interface (e.g. eth0) into the bridge, its state must be up:<br />
<br />
# ip link set eth0 up<br />
<br />
Adding the interface into the bridge is done by setting its master to {{ic|''bridge_name''}}:<br />
<br />
# ip link set eth0 master ''bridge_name''<br />
<br />
To show the existing bridges and associated interfaces, use the ''bridge'' utility (also part of {{Pkg|iproute2}}). See {{man|8|bridge}} for details.<br />
<br />
# bridge link<br />
<br />
This is how to remove an interface from a bridge:<br />
<br />
# ip link set eth0 nomaster<br />
<br />
The interface will still be up, so you may also want to bring it down:<br />
<br />
# ip link set eth0 down<br />
<br />
To delete a bridge issue the following command:<br />
<br />
# ip link delete ''bridge_name'' type bridge<br />
<br />
This will automatically remove all interfaces from the bridge. The slave interfaces will still be up, though, so you may also want to bring them down after.<br />
<br />
=== With bridge-utils ===<br />
<br />
This section describes the management of a network bridge using the legacy ''brctl'' tool from the {{Pkg|bridge-utils}} package, which is available in the [[official repositories]]. See {{man|8|brctl}} for full listing of options.<br />
<br />
{{Note| The use of brctl is deprecated and is considered obsolete. Some features such as STP guard, harpin mode,<br />
fastleave and root block are intentionally not implemented in this command.}}<br />
<br />
Create a new bridge:<br />
<br />
# brctl addbr ''bridge_name''<br />
<br />
Add a device to a bridge, for example {{ic|eth0}}:<br />
<br />
{{Note|Adding an interface to a bridge will cause the interface to lose its existing IP address. If you are connected remotely via the interface you intend to add to the bridge, you will lose your connection. This problem can be worked around by scripting the bridge to be created at system startup.}}<br />
<br />
# brctl addif ''bridge_name'' eth0<br />
<br />
<br />
Show current bridges and what interfaces they are connected to:<br />
<br />
$ brctl show<br />
<br />
Set the bridge device up:<br />
<br />
# ip link set dev ''bridge_name'' up<br />
<br />
Delete a bridge, you need to first set it to ''down'':<br />
<br />
# ip link set dev ''bridge_name'' down<br />
# brctl delbr ''bridge_name''<br />
<br />
{{Note|To enable the [http://ebtables.netfilter.org/documentation/bridge-nf.html bridge-netfilter] functionality, you need to manually load the {{ic|br_netfilter}} module:<br />
<br />
# modprobe br_netfilter<br />
<br />
See also [[Kernel modules#Automatic module loading with systemd]].<br />
}}<br />
<br />
=== With netctl ===<br />
<br />
See [[Bridge with netctl]].<br />
<br />
=== With systemd-networkd ===<br />
<br />
See [[systemd-networkd#Bridge interface]].<br />
<br />
=== With NetworkManager ===<br />
<br />
[[GNOME]]'s Network settings can create bridges, but currently will not auto-connect to them or slave/attached interfaces. Open Network Settings, add a new interface of type Bridge, add a new bridged connection, and select the MAC address of the device to attach to the bridge.<br />
<br />
[[KDE]]'s {{Pkg|plasma-nm}} can create bridges. In order to view, create and modify bridge interfaces open the Connections window either by right clicking the Networks applet in the system tray and selecting ''Configure Network Connections...'' or from ''System Settings > Connections''. Click the ''Configuration'' button in the lower left corner of the module and enable "Show virtual connections". A session restart will be necessary to use the enabled functionality.<br />
<br />
{{Pkg|nm-connection-editor}} can create bridges in the same manner as GNOME's Network settings.<br />
<br />
{{ic|nmcli}} from {{Pkg|networkmanager}} can create bridges. Creating a bridge with [[Wikipedia:Spanning Tree Protocol|STP]] disabled (to avoid the bridge being advertised on the network):<br />
<br />
$ nmcli connection add type bridge ifname br0 stp no<br />
<br />
Making interface {{ic|enp30s0}} a slave to the bridge:<br />
<br />
$ nmcli connection add type bridge-slave ifname enp30s0 master br0<br />
<br />
Setting the existing connection as down:<br />
<br />
$ nmcli connection down ''Connection''<br />
<br />
Setting the new bridge as up:<br />
<br />
$ nmcli connection up bridge-br0<br />
<br />
If NetworkManager's default interface for the device you added to the bridge connects automatically, you may want to disable that by clicking the gear next to it in Network Settings, and unchecking "Connect automatically" under "Identity."<br />
<br />
== Assigning an IP address ==<br />
<br />
When the bridge is fully set up, it can be assigned an IP address:<br />
<br />
# ip addr add dev ''bridge_name'' 192.168.66.66/24<br />
<br />
{{Expansion|This section needs to be connected to the link-level part described in [[QEMU#Tap networking with QEMU]]. For now, see the instructions given there.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Wireless interface on a bridge ===<br />
<br />
To add a wireless interface to a bridge, you first have to assign the wireless interface to an access point or start an access point with [[Software access point|hostapd]]. Otherwise the wireless interface will not be added to the bridge.<br />
<br />
See also [[Debian:BridgeNetworkConnections#Bridging with a wireless NIC]].<br />
<br />
=== Speeding up traffic destinated to the bridge itself ===<br />
<br />
In some situations the bridge not only serves as a bridge box, but also talks to other hosts. Packets that arrive on a bridge port and that are destinated to the bridge box itself will by default enter the iptables INPUT chain with the logical bridge port as input device. These packets will be queued twice by the network code, the first time they are queued after they are received by the network device. The second time after the bridge code examined the destination MAC address and determined it was a locally destinated packet and therefore decided to pass the frame up to the higher protocol stack.[http://ebtables.netfilter.org/examples/basic.html#ex_speed]<br />
<br />
The way to let locally destinated packets be queued only once is by brouting them in the BROUTING chain of the broute table. Suppose br0 has an IP address and that br0's bridge ports do not have an IP address. Using the following rule should make all locally directed traffic be queued only once: <br />
<br />
# ebtables -t broute -A BROUTING -d $MAC_OF_BR0 -p ipv4 -j redirect --redirect-target DROP<br />
<br />
The replies from the bridge will be sent out through the br0 device (assuming your routing table is correct and sends all traffic through br0), so everything keeps working neatly, without the performance loss caused by the packet being queued twice. <br />
<br />
The redirect target is needed because the MAC address of the bridge port is not necessarily equal to the MAC address of the bridge device. The packets destinated to the bridge box will have a destination MAC address equal to that of the bridge br0, so that destination address must be changed to that of the bridge port.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No networking after bridge configuration ===<br />
<br />
{{Style|This problem is pointed out as a note in [[#With bridge-utils]]. It should be made clear in all other sections and running a DHCP client should be added to [[#Assigning an IP address]].}}<br />
<br />
It may help to remove all IP addresses and routes from the interface (e.g. {{ic|eth0}}) that was added to the bridge and configure these parameters for the bridge instead.<br />
<br />
First of all, make sure there is no [[dhcpcd]] instance running for {{ic|eth0}}, otherwise the deleted addresses may be reassigned.<br />
<br />
Remove address and route from the {{ic|eth0}} interface:<br />
<br />
# ip addr del ''address'' dev eth0<br />
# ip route del ''address'' dev eth0<br />
<br />
Now IP address and route for the earlier configured bridge must be set. This is usually done by starting a DHCP client for this interface. Otherwise, consult [[Network configuration]] for manual configuration.<br />
<br />
== See also ==<br />
<br />
* [http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge Official documentation for bridge-utils]<br />
* [http://www.linuxfoundation.org/collaborate/workgroups/networking/iproute2 Official documentation for iproute2]<br />
* [http://ebtables.netfilter.org/br_fw_ia/br_fw_ia.html ebtables/iptables interaction on a Linux-based bridge]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=KVM&diff=601835KVM2020-03-16T16:57:43Z<p>Pgoetz: reverted previous, incorrect edit.</p>
<hr />
<div>[[Category:Hypervisors]]<br />
[[Category:Kernel]]<br />
[[it:KVM]]<br />
[[ja:KVM]]<br />
[[zh-hans:KVM]]<br />
[[zh-hant:KVM]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
'''KVM''', [[Wikipedia:Kernel-based Virtual Machine|Kernel-based Virtual Machine]], is a [[Wikipedia:hypervisor|hypervisor]] built into the Linux kernel. It is similar to [[Xen]] in purpose but much simpler to get running. Unlike native [[QEMU]], which uses emulation, KVM is a special operating mode of QEMU that uses CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization via a kernel module.<br />
<br />
Using KVM, one can run multiple virtual machines running unmodified GNU/Linux, Windows, or any other operating system. (See [http://www.linux-kvm.org/page/Guest_Support_Status Guest Support Status] for more information.) Each virtual machine has private virtualized hardware: a network card, disk, graphics card, etc.<br />
<br />
Differences between KVM and [[Xen]], [[VMware]], or QEMU can be found at the [http://www.linux-kvm.org/page/FAQ#General_KVM_information KVM FAQ].<br />
<br />
This article does not cover features common to multiple emulators using KVM as a backend. You should see related articles for such information.<br />
<br />
== Checking support for KVM ==<br />
<br />
=== Hardware support ===<br />
<br />
KVM requires that the virtual machine host's processor has virtualization support (named VT-x for Intel processors and AMD-V for AMD processors). You can check whether your processor supports hardware virtualization with the following command:<br />
$ LC_ALL=C lscpu | grep Virtualization<br />
<br />
Alternatively:<br />
<br />
$ grep -E --color=auto 'vmx|svm|0xc0f' /proc/cpuinfo<br />
<br />
If nothing is displayed after running either command, then your processor does '''not''' support hardware virtualization, and you will '''not''' be able to use KVM.<br />
<br />
{{Note|You may need to enable virtualization support in your BIOS. All x86_64 processors manufactured by AMD and Intel in the last 10 years support virtualization. If it looks like your processor does not support virtualization, it's almost certainly turned off in the BIOS.}}<br />
<br />
=== Kernel support ===<br />
<br />
Arch Linux kernels provide the required [[kernel modules]] to support KVM.<br />
<br />
* One can check if the necessary modules, {{ic|kvm}} and either {{ic|kvm_amd}} or {{ic|kvm_intel}}, are available in the kernel with the following command:<br />
<br />
$ zgrep CONFIG_KVM /proc/config.gz<br />
<br />
The module is available only if it is set to either {{ic|y}} or {{ic|m}}.<br />
<br />
* Then, ensure that the kernel modules are automatically loaded, with the command:<br />
<br />
{{hc|$ lsmod {{!}} grep kvm|<br />
kvm_intel 245760 0<br />
kvmgt 28672 0<br />
mdev 20480 2 kvmgt,vfio_mdev<br />
vfio 32768 3 kvmgt,vfio_mdev,vfio_iommu_type1<br />
kvm 737280 2 kvmgt,kvm_intel<br />
irqbypass 16384 1 kvm<br />
}}<br />
<br />
If the command returns nothing, the module needs to be loaded manually, see [[Kernel modules#Manual module handling]].<br />
<br />
{{Tip|If modprobing {{Ic|kvm_intel}} or {{Ic|kvm_amd}} fails but modprobing {{Ic|kvm}} succeeds, and {{ic|lscpu}} claims that hardware acceleration is supported, check the BIOS settings. Some vendors, especially laptop vendors, disable these processor extensions by default. To determine whether there is no hardware support or whether the extensions are disabled in BIOS, the output from {{ic|dmesg}} after having failed to modprobe will tell.}}<br />
<br />
== Para-virtualization with Virtio ==<br />
<br />
Para-virtualization provides a fast and efficient means of communication for guests to use devices on the host machine. KVM provides para-virtualized devices to virtual machines using the '''Virtio''' API as a layer between the hypervisor and guest.<br />
<br />
All Virtio devices have two parts: the host device and the guest driver. <br />
<br />
=== Kernel support ===<br />
<br />
* Use the following command to check if the VIRTIO modules are available in the kernel: {{bc|$ zgrep VIRTIO /proc/config.gz}}<br />
* Then, check if the kernel modules are automatically loaded with the command: {{bc|$ lsmod {{!}} grep virtio}}<br />
<br />
In case the above commands return nothing, you need to [[Kernel modules#Manual module handling]] kernel modules.<br />
<br />
=== List of para-virtualized devices ===<br />
<br />
* network device (virtio-net)<br />
* block device (virtio-blk)<br />
* controller device (virtio-scsi)<br />
* serial device (virtio-serial)<br />
* balloon device (virtio-balloon)<br />
<br />
== How to use KVM ==<br />
<br />
See the main article: [[QEMU]].<br />
<br />
== Tips and tricks ==<br />
<br />
{{Note|See [[QEMU#Tips and tricks]] and [[QEMU#Troubleshooting]] for general tips and tricks.}}<br />
<br />
=== Nested virtualization ===<br />
<br />
{{Expansion|Is it possible also with {{ic|kvm_amd}}?}}<br />
<br />
Nested virtualization enables existing virtual machines to be run on third-party hypervisors and on other clouds without any modifications to the original virtual machines or their networking.<br />
<br />
On host, enable nested feature for {{ic|kvm_intel}}:<br />
<br />
# modprobe -r kvm_intel<br />
# modprobe kvm_intel nested=1<br />
<br />
To make it permanent (see [[Kernel modules#Setting module options]]):<br />
<br />
{{hc|/etc/modprobe.d/kvm_intel.conf|2=<br />
options kvm_intel nested=1<br />
}}<br />
<br />
Verify that feature is activated: <br />
<br />
{{hc|$ systool -m kvm_intel -v {{!}} grep nested|2=<br />
nested = "Y"<br />
}}<br />
<br />
Enable the "host passthrough" mode to forward all CPU features to the guest system:<br />
<br />
# If using [[QEMU]], run the guest virtual machine with the following command: {{ic|qemu-system-x86_64 -enable-kvm -cpu host}}.<br />
# If using ''virt-manager'', change the CPU model to {{ic|host-passthrough}} (it will not be in the list, just write it in the box).<br />
# If using ''virsh'', use {{ic|virsh edit ''vm-name''}} and change the CPU line to {{ic|1=<cpu mode='host-passthrough' check='partial'/>}}<br />
<br />
Boot VM and check if vmx flag is present:<br />
<br />
$ grep -E --color=auto 'vmx|svm' /proc/cpuinfo<br />
<br />
=== Enabling huge pages ===<br />
<br />
{{Merge|QEMU|qemu-kvm no longer exists as all of its features have been merged into {{Pkg|qemu}}. After the above issue is cleared, I suggest merging this section into [[QEMU]].}}<br />
<br />
You may also want to enable hugepages to improve the performance of your virtual machine.<br />
With an up to date Arch Linux and a running KVM you probably already have everything you need. Check if you have the directory {{ic|/dev/hugepages}}. If not, create it. <br />
Now we need the right permissions to use this directory. The default permission is root's uid and gid with 0755, but we want anyone in the kvm group to have access to hugepages.<br />
<br />
Add to your {{ic|/etc/fstab}}:<br />
<br />
hugetlbfs /dev/hugepages hugetlbfs mode=01770,gid=78 0 0<br />
<br />
Of course the gid must match that of the {{ic|kvm}} group. The mode of {{ic|1770}} allows anyone in the group to create files but not unlink or rename each other's files. Make sure {{ic|/dev/hugepages}} is mounted properly:<br />
<br />
{{hc|# umount /dev/hugepages<br />
# mount /dev/hugepages<br />
$ mount {{!}} grep huge|2=<br />
hugetlbfs on /dev/hugepages type hugetlbfs (rw,relatime,mode=1770,gid=78)<br />
}}<br />
<br />
Now you can calculate how many hugepages you need. Check how large your hugepages are:<br />
<br />
$ grep Hugepagesize /proc/meminfo<br />
<br />
Normally that should be 2048 kB ≙ 2 MB. Let us say you want to run your virtual machine with 1024 MB. 1024 / 2 = 512. Add a few extra so we can round this up to 550. Now tell your machine how many hugepages you want:<br />
<br />
# echo 550 > /proc/sys/vm/nr_hugepages<br />
<br />
If you had enough free memory you should see:<br />
<br />
{{hc|$ grep HugePages_Total /proc/meminfo|<br />
HugesPages_Total: 550<br />
}}<br />
<br />
If the number is smaller, close some applications or start your virtual machine with less memory (number_of_pages x 2):<br />
<br />
$ qemu-system-x86_64 -enable-kvm -m 1024 -mem-path /dev/hugepages -hda <disk_image> [...]<br />
<br />
Note the {{ic|-mem-path}} parameter. This will make use of the hugepages.<br />
<br />
Now you can check, while your virtual machine is running, how many pages are used:<br />
<br />
{{hc|$ grep HugePages /proc/meminfo|<br />
HugePages_Total: 550<br />
HugePages_Free: 48<br />
HugePages_Rsvd: 6<br />
HugePages_Surp: 0<br />
}}<br />
<br />
Now that everything seems to work you can enable hugepages by default if you like. Add to your {{ic|/etc/sysctl.d/40-hugepage.conf}}:<br />
<br />
vm.nr_hugepages = 550<br />
<br />
See also:<br />
<br />
* [https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt summary of hugetlbpage support in the Linux kernel]<br />
* [[debian:Hugepages|Debian Wiki - Hugepages]]<br />
<br />
== See also ==<br />
<br />
* [http://www.linux-kvm.org/page/HOWTO KVM Howto]<br />
* [http://www.linux-kvm.org/page/FAQ#General_KVM_information KVM FAQ]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=KVM&diff=601686KVM2020-03-16T08:38:27Z<p>Pgoetz: fixed minor typo: hugetlbfs --> hugetblfs</p>
<hr />
<div>[[Category:Hypervisors]]<br />
[[Category:Kernel]]<br />
[[it:KVM]]<br />
[[ja:KVM]]<br />
[[zh-hans:KVM]]<br />
[[zh-hant:KVM]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
'''KVM''', [[Wikipedia:Kernel-based Virtual Machine|Kernel-based Virtual Machine]], is a [[Wikipedia:hypervisor|hypervisor]] built into the Linux kernel. It is similar to [[Xen]] in purpose but much simpler to get running. Unlike native [[QEMU]], which uses emulation, KVM is a special operating mode of QEMU that uses CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization via a kernel module.<br />
<br />
Using KVM, one can run multiple virtual machines running unmodified GNU/Linux, Windows, or any other operating system. (See [http://www.linux-kvm.org/page/Guest_Support_Status Guest Support Status] for more information.) Each virtual machine has private virtualized hardware: a network card, disk, graphics card, etc.<br />
<br />
Differences between KVM and [[Xen]], [[VMware]], or QEMU can be found at the [http://www.linux-kvm.org/page/FAQ#General_KVM_information KVM FAQ].<br />
<br />
This article does not cover features common to multiple emulators using KVM as a backend. You should see related articles for such information.<br />
<br />
== Checking support for KVM ==<br />
<br />
=== Hardware support ===<br />
<br />
KVM requires that the virtual machine host's processor has virtualization support (named VT-x for Intel processors and AMD-V for AMD processors). You can check whether your processor supports hardware virtualization with the following command:<br />
$ LC_ALL=C lscpu | grep Virtualization<br />
<br />
Alternatively:<br />
<br />
$ grep -E --color=auto 'vmx|svm|0xc0f' /proc/cpuinfo<br />
<br />
If nothing is displayed after running either command, then your processor does '''not''' support hardware virtualization, and you will '''not''' be able to use KVM.<br />
<br />
{{Note|You may need to enable virtualization support in your BIOS. All x86_64 processors manufactured by AMD and Intel in the last 10 years support virtualization. If it looks like your processor does not support virtualization, it's almost certainly turned off in the BIOS.}}<br />
<br />
=== Kernel support ===<br />
<br />
Arch Linux kernels provide the required [[kernel modules]] to support KVM.<br />
<br />
* One can check if the necessary modules, {{ic|kvm}} and either {{ic|kvm_amd}} or {{ic|kvm_intel}}, are available in the kernel with the following command:<br />
<br />
$ zgrep CONFIG_KVM /proc/config.gz<br />
<br />
The module is available only if it is set to either {{ic|y}} or {{ic|m}}.<br />
<br />
* Then, ensure that the kernel modules are automatically loaded, with the command:<br />
<br />
{{hc|$ lsmod {{!}} grep kvm|<br />
kvm_intel 245760 0<br />
kvmgt 28672 0<br />
mdev 20480 2 kvmgt,vfio_mdev<br />
vfio 32768 3 kvmgt,vfio_mdev,vfio_iommu_type1<br />
kvm 737280 2 kvmgt,kvm_intel<br />
irqbypass 16384 1 kvm<br />
}}<br />
<br />
If the command returns nothing, the module needs to be loaded manually, see [[Kernel modules#Manual module handling]].<br />
<br />
{{Tip|If modprobing {{Ic|kvm_intel}} or {{Ic|kvm_amd}} fails but modprobing {{Ic|kvm}} succeeds, and {{ic|lscpu}} claims that hardware acceleration is supported, check the BIOS settings. Some vendors, especially laptop vendors, disable these processor extensions by default. To determine whether there is no hardware support or whether the extensions are disabled in BIOS, the output from {{ic|dmesg}} after having failed to modprobe will tell.}}<br />
<br />
== Para-virtualization with Virtio ==<br />
<br />
Para-virtualization provides a fast and efficient means of communication for guests to use devices on the host machine. KVM provides para-virtualized devices to virtual machines using the '''Virtio''' API as a layer between the hypervisor and guest.<br />
<br />
All Virtio devices have two parts: the host device and the guest driver. <br />
<br />
=== Kernel support ===<br />
<br />
* Use the following command to check if the VIRTIO modules are available in the kernel: {{bc|$ zgrep VIRTIO /proc/config.gz}}<br />
* Then, check if the kernel modules are automatically loaded with the command: {{bc|$ lsmod {{!}} grep virtio}}<br />
<br />
In case the above commands return nothing, you need to [[Kernel modules#Manual module handling]] kernel modules.<br />
<br />
=== List of para-virtualized devices ===<br />
<br />
* network device (virtio-net)<br />
* block device (virtio-blk)<br />
* controller device (virtio-scsi)<br />
* serial device (virtio-serial)<br />
* balloon device (virtio-balloon)<br />
<br />
== How to use KVM ==<br />
<br />
See the main article: [[QEMU]].<br />
<br />
== Tips and tricks ==<br />
<br />
{{Note|See [[QEMU#Tips and tricks]] and [[QEMU#Troubleshooting]] for general tips and tricks.}}<br />
<br />
=== Nested virtualization ===<br />
<br />
{{Expansion|Is it possible also with {{ic|kvm_amd}}?}}<br />
<br />
Nested virtualization enables existing virtual machines to be run on third-party hypervisors and on other clouds without any modifications to the original virtual machines or their networking.<br />
<br />
On host, enable nested feature for {{ic|kvm_intel}}:<br />
<br />
# modprobe -r kvm_intel<br />
# modprobe kvm_intel nested=1<br />
<br />
To make it permanent (see [[Kernel modules#Setting module options]]):<br />
<br />
{{hc|/etc/modprobe.d/kvm_intel.conf|2=<br />
options kvm_intel nested=1<br />
}}<br />
<br />
Verify that feature is activated: <br />
<br />
{{hc|$ systool -m kvm_intel -v {{!}} grep nested|2=<br />
nested = "Y"<br />
}}<br />
<br />
Enable the "host passthrough" mode to forward all CPU features to the guest system:<br />
<br />
# If using [[QEMU]], run the guest virtual machine with the following command: {{ic|qemu-system-x86_64 -enable-kvm -cpu host}}.<br />
# If using ''virt-manager'', change the CPU model to {{ic|host-passthrough}} (it will not be in the list, just write it in the box).<br />
# If using ''virsh'', use {{ic|virsh edit ''vm-name''}} and change the CPU line to {{ic|1=<cpu mode='host-passthrough' check='partial'/>}}<br />
<br />
Boot VM and check if vmx flag is present:<br />
<br />
$ grep -E --color=auto 'vmx|svm' /proc/cpuinfo<br />
<br />
=== Enabling huge pages ===<br />
<br />
{{Merge|QEMU|qemu-kvm no longer exists as all of its features have been merged into {{Pkg|qemu}}. After the above issue is cleared, I suggest merging this section into [[QEMU]].}}<br />
<br />
You may also want to enable hugepages to improve the performance of your virtual machine.<br />
With an up to date Arch Linux and a running KVM you probably already have everything you need. Check if you have the directory {{ic|/dev/hugepages}}. If not, create it. <br />
Now we need the right permissions to use this directory. The default permission is root's uid and gid with 0755, but we want anyone in the kvm group to have access to hugepages.<br />
<br />
Add to your {{ic|/etc/fstab}}:<br />
<br />
hugetblfs /dev/hugepages hugetlbfs mode=01770,gid=78 0 0<br />
<br />
Of course the gid must match that of the {{ic|kvm}} group. The mode of {{ic|1770}} allows anyone in the group to create files but not unlink or rename each other's files. Make sure {{ic|/dev/hugepages}} is mounted properly:<br />
<br />
{{hc|# umount /dev/hugepages<br />
# mount /dev/hugepages<br />
$ mount {{!}} grep huge|2=<br />
hugetblfs on /dev/hugepages type hugetblfs (rw,relatime,mode=1770,gid=78)<br />
}}<br />
<br />
Now you can calculate how many hugepages you need. Check how large your hugepages are:<br />
<br />
$ grep Hugepagesize /proc/meminfo<br />
<br />
Normally that should be 2048 kB ≙ 2 MB. Let us say you want to run your virtual machine with 1024 MB. 1024 / 2 = 512. Add a few extra so we can round this up to 550. Now tell your machine how many hugepages you want:<br />
<br />
# echo 550 > /proc/sys/vm/nr_hugepages<br />
<br />
If you had enough free memory you should see:<br />
<br />
{{hc|$ grep HugePages_Total /proc/meminfo|<br />
HugesPages_Total: 550<br />
}}<br />
<br />
If the number is smaller, close some applications or start your virtual machine with less memory (number_of_pages x 2):<br />
<br />
$ qemu-system-x86_64 -enable-kvm -m 1024 -mem-path /dev/hugepages -hda <disk_image> [...]<br />
<br />
Note the {{ic|-mem-path}} parameter. This will make use of the hugepages.<br />
<br />
Now you can check, while your virtual machine is running, how many pages are used:<br />
<br />
{{hc|$ grep HugePages /proc/meminfo|<br />
HugePages_Total: 550<br />
HugePages_Free: 48<br />
HugePages_Rsvd: 6<br />
HugePages_Surp: 0<br />
}}<br />
<br />
Now that everything seems to work you can enable hugepages by default if you like. Add to your {{ic|/etc/sysctl.d/40-hugepage.conf}}:<br />
<br />
vm.nr_hugepages = 550<br />
<br />
See also:<br />
<br />
* [https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt summary of hugetlbpage support in the Linux kernel]<br />
* [[debian:Hugepages|Debian Wiki - Hugepages]]<br />
<br />
== See also ==<br />
<br />
* [http://www.linux-kvm.org/page/HOWTO KVM Howto]<br />
* [http://www.linux-kvm.org/page/FAQ#General_KVM_information KVM FAQ]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=KVM&diff=601685KVM2020-03-16T08:34:33Z<p>Pgoetz: fixed minor typo: hugetlbfs --> hugetblfs</p>
<hr />
<div>[[Category:Hypervisors]]<br />
[[Category:Kernel]]<br />
[[it:KVM]]<br />
[[ja:KVM]]<br />
[[zh-hans:KVM]]<br />
[[zh-hant:KVM]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
'''KVM''', [[Wikipedia:Kernel-based Virtual Machine|Kernel-based Virtual Machine]], is a [[Wikipedia:hypervisor|hypervisor]] built into the Linux kernel. It is similar to [[Xen]] in purpose but much simpler to get running. Unlike native [[QEMU]], which uses emulation, KVM is a special operating mode of QEMU that uses CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization via a kernel module.<br />
<br />
Using KVM, one can run multiple virtual machines running unmodified GNU/Linux, Windows, or any other operating system. (See [http://www.linux-kvm.org/page/Guest_Support_Status Guest Support Status] for more information.) Each virtual machine has private virtualized hardware: a network card, disk, graphics card, etc.<br />
<br />
Differences between KVM and [[Xen]], [[VMware]], or QEMU can be found at the [http://www.linux-kvm.org/page/FAQ#General_KVM_information KVM FAQ].<br />
<br />
This article does not cover features common to multiple emulators using KVM as a backend. You should see related articles for such information.<br />
<br />
== Checking support for KVM ==<br />
<br />
=== Hardware support ===<br />
<br />
KVM requires that the virtual machine host's processor has virtualization support (named VT-x for Intel processors and AMD-V for AMD processors). You can check whether your processor supports hardware virtualization with the following command:<br />
$ LC_ALL=C lscpu | grep Virtualization<br />
<br />
Alternatively:<br />
<br />
$ grep -E --color=auto 'vmx|svm|0xc0f' /proc/cpuinfo<br />
<br />
If nothing is displayed after running either command, then your processor does '''not''' support hardware virtualization, and you will '''not''' be able to use KVM.<br />
<br />
{{Note|You may need to enable virtualization support in your BIOS. All x86_64 processors manufactured by AMD and Intel in the last 10 years support virtualization. If it looks like your processor does not support virtualization, it's almost certainly turned off in the BIOS.}}<br />
<br />
=== Kernel support ===<br />
<br />
Arch Linux kernels provide the required [[kernel modules]] to support KVM.<br />
<br />
* One can check if the necessary modules, {{ic|kvm}} and either {{ic|kvm_amd}} or {{ic|kvm_intel}}, are available in the kernel with the following command:<br />
<br />
$ zgrep CONFIG_KVM /proc/config.gz<br />
<br />
The module is available only if it is set to either {{ic|y}} or {{ic|m}}.<br />
<br />
* Then, ensure that the kernel modules are automatically loaded, with the command:<br />
<br />
{{hc|$ lsmod {{!}} grep kvm|<br />
kvm_intel 245760 0<br />
kvmgt 28672 0<br />
mdev 20480 2 kvmgt,vfio_mdev<br />
vfio 32768 3 kvmgt,vfio_mdev,vfio_iommu_type1<br />
kvm 737280 2 kvmgt,kvm_intel<br />
irqbypass 16384 1 kvm<br />
}}<br />
<br />
If the command returns nothing, the module needs to be loaded manually, see [[Kernel modules#Manual module handling]].<br />
<br />
{{Tip|If modprobing {{Ic|kvm_intel}} or {{Ic|kvm_amd}} fails but modprobing {{Ic|kvm}} succeeds, and {{ic|lscpu}} claims that hardware acceleration is supported, check the BIOS settings. Some vendors, especially laptop vendors, disable these processor extensions by default. To determine whether there is no hardware support or whether the extensions are disabled in BIOS, the output from {{ic|dmesg}} after having failed to modprobe will tell.}}<br />
<br />
== Para-virtualization with Virtio ==<br />
<br />
Para-virtualization provides a fast and efficient means of communication for guests to use devices on the host machine. KVM provides para-virtualized devices to virtual machines using the '''Virtio''' API as a layer between the hypervisor and guest.<br />
<br />
All Virtio devices have two parts: the host device and the guest driver. <br />
<br />
=== Kernel support ===<br />
<br />
* Use the following command to check if the VIRTIO modules are available in the kernel: {{bc|$ zgrep VIRTIO /proc/config.gz}}<br />
* Then, check if the kernel modules are automatically loaded with the command: {{bc|$ lsmod {{!}} grep virtio}}<br />
<br />
In case the above commands return nothing, you need to [[Kernel modules#Manual module handling]] kernel modules.<br />
<br />
=== List of para-virtualized devices ===<br />
<br />
* network device (virtio-net)<br />
* block device (virtio-blk)<br />
* controller device (virtio-scsi)<br />
* serial device (virtio-serial)<br />
* balloon device (virtio-balloon)<br />
<br />
== How to use KVM ==<br />
<br />
See the main article: [[QEMU]].<br />
<br />
== Tips and tricks ==<br />
<br />
{{Note|See [[QEMU#Tips and tricks]] and [[QEMU#Troubleshooting]] for general tips and tricks.}}<br />
<br />
=== Nested virtualization ===<br />
<br />
{{Expansion|Is it possible also with {{ic|kvm_amd}}?}}<br />
<br />
Nested virtualization enables existing virtual machines to be run on third-party hypervisors and on other clouds without any modifications to the original virtual machines or their networking.<br />
<br />
On host, enable nested feature for {{ic|kvm_intel}}:<br />
<br />
# modprobe -r kvm_intel<br />
# modprobe kvm_intel nested=1<br />
<br />
To make it permanent (see [[Kernel modules#Setting module options]]):<br />
<br />
{{hc|/etc/modprobe.d/kvm_intel.conf|2=<br />
options kvm_intel nested=1<br />
}}<br />
<br />
Verify that feature is activated: <br />
<br />
{{hc|$ systool -m kvm_intel -v {{!}} grep nested|2=<br />
nested = "Y"<br />
}}<br />
<br />
Enable the "host passthrough" mode to forward all CPU features to the guest system:<br />
<br />
# If using [[QEMU]], run the guest virtual machine with the following command: {{ic|qemu-system-x86_64 -enable-kvm -cpu host}}.<br />
# If using ''virt-manager'', change the CPU model to {{ic|host-passthrough}} (it will not be in the list, just write it in the box).<br />
# If using ''virsh'', use {{ic|virsh edit ''vm-name''}} and change the CPU line to {{ic|1=<cpu mode='host-passthrough' check='partial'/>}}<br />
<br />
Boot VM and check if vmx flag is present:<br />
<br />
$ grep -E --color=auto 'vmx|svm' /proc/cpuinfo<br />
<br />
=== Enabling huge pages ===<br />
<br />
{{Merge|QEMU|qemu-kvm no longer exists as all of its features have been merged into {{Pkg|qemu}}. After the above issue is cleared, I suggest merging this section into [[QEMU]].}}<br />
<br />
You may also want to enable hugepages to improve the performance of your virtual machine.<br />
With an up to date Arch Linux and a running KVM you probably already have everything you need. Check if you have the directory {{ic|/dev/hugepages}}. If not, create it. <br />
Now we need the right permissions to use this directory. The default permission is root's uid and gid with 0755, but we want anyone in the kvm group to have access to hugepages.<br />
<br />
Add to your {{ic|/etc/fstab}}:<br />
<br />
hugetblfs /dev/hugepages hugetlbfs mode=01770,gid=78 0 0<br />
<br />
Of course the gid must match that of the {{ic|kvm}} group. The mode of {{ic|1770}} allows anyone in the group to create files but not unlink or rename each other's files. Make sure {{ic|/dev/hugepages}} is mounted properly:<br />
<br />
{{hc|# umount /dev/hugepages<br />
# mount /dev/hugepages<br />
$ mount {{!}} grep huge|2=<br />
hugetlbfs on /dev/hugepages type hugetlbfs (rw,relatime,mode=1770,gid=78)<br />
}}<br />
<br />
Now you can calculate how many hugepages you need. Check how large your hugepages are:<br />
<br />
$ grep Hugepagesize /proc/meminfo<br />
<br />
Normally that should be 2048 kB ≙ 2 MB. Let us say you want to run your virtual machine with 1024 MB. 1024 / 2 = 512. Add a few extra so we can round this up to 550. Now tell your machine how many hugepages you want:<br />
<br />
# echo 550 > /proc/sys/vm/nr_hugepages<br />
<br />
If you had enough free memory you should see:<br />
<br />
{{hc|$ grep HugePages_Total /proc/meminfo|<br />
HugesPages_Total: 550<br />
}}<br />
<br />
If the number is smaller, close some applications or start your virtual machine with less memory (number_of_pages x 2):<br />
<br />
$ qemu-system-x86_64 -enable-kvm -m 1024 -mem-path /dev/hugepages -hda <disk_image> [...]<br />
<br />
Note the {{ic|-mem-path}} parameter. This will make use of the hugepages.<br />
<br />
Now you can check, while your virtual machine is running, how many pages are used:<br />
<br />
{{hc|$ grep HugePages /proc/meminfo|<br />
HugePages_Total: 550<br />
HugePages_Free: 48<br />
HugePages_Rsvd: 6<br />
HugePages_Surp: 0<br />
}}<br />
<br />
Now that everything seems to work you can enable hugepages by default if you like. Add to your {{ic|/etc/sysctl.d/40-hugepage.conf}}:<br />
<br />
vm.nr_hugepages = 550<br />
<br />
See also:<br />
<br />
* [https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt summary of hugetlbpage support in the Linux kernel]<br />
* [[debian:Hugepages|Debian Wiki - Hugepages]]<br />
<br />
== See also ==<br />
<br />
* [http://www.linux-kvm.org/page/HOWTO KVM Howto]<br />
* [http://www.linux-kvm.org/page/FAQ#General_KVM_information KVM FAQ]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=KVM&diff=590602KVM2019-11-30T16:33:45Z<p>Pgoetz: added a note of reassurance</p>
<hr />
<div>[[Category:Hypervisors]]<br />
[[Category:Kernel]]<br />
[[it:KVM]]<br />
[[ja:KVM]]<br />
[[zh-hans:KVM]]<br />
[[zh-hant:KVM]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
'''KVM''', [[Wikipedia:Kernel-based Virtual Machine|Kernel-based Virtual Machine]], is a [[Wikipedia:hypervisor|hypervisor]] built into the Linux kernel. It is similar to [[Xen]] in purpose but much simpler to get running. Unlike native [[QEMU]], which uses emulation, KVM is a special operating mode of QEMU that uses CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization via a kernel module.<br />
<br />
Using KVM, one can run multiple virtual machines running unmodified GNU/Linux, Windows, or any other operating system. (See [http://www.linux-kvm.org/page/Guest_Support_Status Guest Support Status] for more information.) Each virtual machine has private virtualized hardware: a network card, disk, graphics card, etc.<br />
<br />
Differences between KVM and [[Xen]], [[VMware]], or QEMU can be found at the [http://www.linux-kvm.org/page/FAQ#General_KVM_information KVM FAQ].<br />
<br />
This article does not cover features common to multiple emulators using KVM as a backend. You should see related articles for such information.<br />
<br />
== Checking support for KVM ==<br />
<br />
=== Hardware support ===<br />
<br />
KVM requires that the virtual machine host's processor has virtualization support (named VT-x for Intel processors and AMD-V for AMD processors). You can check whether your processor supports hardware virtualization with the following command:<br />
$ LC_ALL=C lscpu | grep Virtualization<br />
<br />
Alternatively:<br />
<br />
$ grep -E --color=auto 'vmx|svm|0xc0f' /proc/cpuinfo<br />
<br />
If nothing is displayed after running either command, then your processor does '''not''' support hardware virtualization, and you will '''not''' be able to use KVM.<br />
<br />
{{Note|You may need to enable virtualization support in your BIOS. All x86_64 processors manufactured by AMD and Intel in the last 10 years support virtualization. If it looks like your processor does not support virtualization, it's almost certainly turned off in the BIOS.}}<br />
<br />
=== Kernel support ===<br />
<br />
Arch Linux kernels provide the required [[kernel modules]] to support KVM.<br />
<br />
* One can check if the necessary modules, {{ic|kvm}} and either {{ic|kvm_amd}} or {{ic|kvm_intel}}, are available in the kernel with the following command:<br />
<br />
$ zgrep CONFIG_KVM /proc/config.gz<br />
<br />
The module is available only if it is set to either {{ic|y}} or {{ic|m}}.<br />
<br />
* Then, ensure that the kernel modules are automatically loaded, with the command:<br />
<br />
{{hc|$ lsmod {{!}} grep kvm|<br />
kvm_intel 245760 0<br />
kvmgt 28672 0<br />
mdev 20480 2 kvmgt,vfio_mdev<br />
vfio 32768 3 kvmgt,vfio_mdev,vfio_iommu_type1<br />
kvm 737280 2 kvmgt,kvm_intel<br />
irqbypass 16384 1 kvm<br />
}}<br />
<br />
If the command returns nothing, the module needs to be loaded manually, see [[Kernel modules#Manual module handling]].<br />
<br />
{{Tip|If modprobing {{Ic|kvm_intel}} or {{Ic|kvm_amd}} fails but modprobing {{Ic|kvm}} succeeds, and {{ic|lscpu}} claims that hardware acceleration is supported, check the BIOS settings. Some vendors, especially laptop vendors, disable these processor extensions by default. To determine whether there is no hardware support or whether the extensions are disabled in BIOS, the output from {{ic|dmesg}} after having failed to modprobe will tell.}}<br />
<br />
== Para-virtualization with Virtio ==<br />
<br />
Para-virtualization provides a fast and efficient means of communication for guests to use devices on the host machine. KVM provides para-virtualized devices to virtual machines using the '''Virtio''' API as a layer between the hypervisor and guest.<br />
<br />
All Virtio devices have two parts: the host device and the guest driver. <br />
<br />
=== Kernel support ===<br />
<br />
* Use the following command to check if the VIRTIO modules are available in the kernel: {{bc|$ zgrep VIRTIO /proc/config.gz}}<br />
* Then, check if the kernel modules are automatically loaded with the command: {{bc|$ lsmod {{!}} grep virtio}}<br />
<br />
In case the above commands return nothing, you need to [[Kernel modules#Manual module handling]] kernel modules.<br />
<br />
=== List of para-virtualized devices ===<br />
<br />
* network device (virtio-net)<br />
* block device (virtio-blk)<br />
* controller device (virtio-scsi)<br />
* serial device (virtio-serial)<br />
* balloon device (virtio-balloon)<br />
<br />
== How to use KVM ==<br />
<br />
See the main article: [[QEMU]].<br />
<br />
== Tips and tricks ==<br />
<br />
{{Note|See [[QEMU#Tips and tricks]] and [[QEMU#Troubleshooting]] for general tips and tricks.}}<br />
<br />
=== Nested virtualization ===<br />
<br />
{{Expansion|Is it possible also with {{ic|kvm_amd}}?}}<br />
<br />
Nested virtualization enables existing virtual machines to be run on third-party hypervisors and on other clouds without any modifications to the original virtual machines or their networking.<br />
<br />
On host, enable nested feature for {{ic|kvm_intel}}:<br />
<br />
# modprobe -r kvm_intel<br />
# modprobe kvm_intel nested=1<br />
<br />
To make it permanent (see [[Kernel modules#Setting module options]]):<br />
<br />
{{hc|/etc/modprobe.d/kvm_intel.conf|2=<br />
options kvm_intel nested=1<br />
}}<br />
<br />
Verify that feature is activated: <br />
<br />
{{hc|$ systool -m kvm_intel -v {{!}} grep nested|2=<br />
nested = "Y"<br />
}}<br />
<br />
Enable the "host passthrough" mode to forward all CPU features to the guest system:<br />
<br />
# If using [[QEMU]], run the guest virtual machine with the following command: {{ic|qemu-system-x86_64 -enable-kvm -cpu host}}.<br />
# If using ''virt-manager'', change the CPU model to {{ic|host-passthrough}} (it will not be in the list, just write it in the box).<br />
# If using ''virsh'', use {{ic|virsh edit ''vm-name''}} and change the CPU line to {{ic|1=<cpu mode='host-passthrough' check='partial'/>}}<br />
<br />
Boot VM and check if vmx flag is present:<br />
<br />
$ grep -E --color=auto 'vmx|svm' /proc/cpuinfo<br />
<br />
=== Enabling huge pages ===<br />
<br />
{{Merge|QEMU|qemu-kvm no longer exists as all of its features have been merged into {{Pkg|qemu}}. After the above issue is cleared, I suggest merging this section into [[QEMU]].}}<br />
<br />
You may also want to enable hugepages to improve the performance of your virtual machine.<br />
With an up to date Arch Linux and a running KVM you probably already have everything you need. Check if you have the directory {{ic|/dev/hugepages}}. If not, create it. <br />
Now we need the right permissions to use this directory. The default permission is root's uid and gid with 0755, but we want anyone in the kvm group to have access to hugepages.<br />
<br />
Add to your {{ic|/etc/fstab}}:<br />
<br />
hugetlbfs /dev/hugepages hugetlbfs mode=1770,gid=78 0 0<br />
<br />
Of course the gid must match that of the {{ic|kvm}} group. The mode of {{ic|1770}} allows anyone in the group to create files but not unlink or rename each other's files. Make sure {{ic|/dev/hugepages}} is mounted properly:<br />
<br />
{{hc|# umount /dev/hugepages<br />
# mount /dev/hugepages<br />
$ mount {{!}} grep huge|2=<br />
hugetlbfs on /dev/hugepages type hugetlbfs (rw,relatime,mode=1770,gid=78)<br />
}}<br />
<br />
Now you can calculate how many hugepages you need. Check how large your hugepages are:<br />
<br />
$ grep Hugepagesize /proc/meminfo<br />
<br />
Normally that should be 2048 kB ≙ 2 MB. Let us say you want to run your virtual machine with 1024 MB. 1024 / 2 = 512. Add a few extra so we can round this up to 550. Now tell your machine how many hugepages you want:<br />
<br />
# echo 550 > /proc/sys/vm/nr_hugepages<br />
<br />
If you had enough free memory you should see:<br />
<br />
{{hc|$ grep HugePages_Total /proc/meminfo|<br />
HugesPages_Total: 550<br />
}}<br />
<br />
If the number is smaller, close some applications or start your virtual machine with less memory (number_of_pages x 2):<br />
<br />
$ qemu-system-x86_64 -enable-kvm -m 1024 -mem-path /dev/hugepages -hda <disk_image> [...]<br />
<br />
Note the {{ic|-mem-path}} parameter. This will make use of the hugepages.<br />
<br />
Now you can check, while your virtual machine is running, how many pages are used:<br />
<br />
{{hc|$ grep HugePages /proc/meminfo|<br />
HugePages_Total: 550<br />
HugePages_Free: 48<br />
HugePages_Rsvd: 6<br />
HugePages_Surp: 0<br />
}}<br />
<br />
Now that everything seems to work you can enable hugepages by default if you like. Add to your {{ic|/etc/sysctl.d/40-hugepage.conf}}:<br />
<br />
vm.nr_hugepages = 550<br />
<br />
See also:<br />
<br />
* [https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt summary of hugetlbpage support in the Linux kernel]<br />
* [[debian:Hugepages|Debian Wiki - Hugepages]]<br />
<br />
== See also ==<br />
<br />
* [http://www.linux-kvm.org/page/HOWTO KVM Howto]<br />
* [http://www.linux-kvm.org/page/FAQ#General_KVM_information KVM FAQ]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Network_configuration/Wireless&diff=577389Talk:Network configuration/Wireless2019-07-13T17:11:11Z<p>Pgoetz: formatting</p>
<hr />
<div>== wireless_tools ==<br />
iwlist uses outdated interfaces, and iw works better with modern wireless drivers. Can we remove the wireless_tools options from [[Wireless_network_configuration#Manual_setup]]? [[User:Pid1|Pid1]] ([[User talk:Pid1|talk]]) 15:11, 3 October 2015 (UTC)<br />
<br />
:Many sections in [[Wireless_network_configuration#Troubleshooting]] still suggest only iwconfig commands. We need to find equivalent iw options first... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:21, 3 October 2015 (UTC)<br />
<br />
== "your key" ==<br />
<br />
What is ''my key''? [[Wireless_network_configuration#Association]] --[[User:Kete|Kete]] ([[User talk:Kete|talk]]) 00:38, 11 March 2016 (UTC)<br />
<br />
:I believe it is the security password configured on the router. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 12:47, 11 March 2016 (UTC)<br />
<br />
== Setting regulatory domain ==<br />
<br />
In the section ''Respecting the regulatory domain'' in my opinion the following information should be added:<br />
<br />
Another reason for an unchanged regulatory domain after adjusting the settings can be the fact, that linux uses information about the regulatory domain provided by the access point.<br />
As far as I unterstand these information are only retrieved, if the PC is associated with the access point.<br />
For details see: [https://wireless.wiki.kernel.org/en/developers/regulatory/processing_rules] (subsection: ''Country IE processing'')<br />
<br />
{{unsigned|15:21, 7 May 2016|Aluser1137}}<br />
<br />
It says "WPA supplicant can also use a regdomain in the country= line of /etc/wpa_supplicant/wpa_supplicant.conf." I cannot find such a setting in the man page for either wpa_supplicant or wpa_supplicant.conf.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 23:49, 3 January 2018 (UTC)<br />
<br />
== rtl8812au/8814au/8821au ==<br />
<br />
I have updated the section on the Realtek USB chipsets for AC1200/1750/1900, respectively 8812au/8821au/8814au.<br />
<br />
I maintain two of them on the AUR and situation is complicated. But I was asked to give some insights on the state of these drivers.<br />
<br />
Realtek drivers are a mess. Three things to consider:<br />
# the driver version (4, 5.1.5, 5.2.9). It is a fair bet that the higher the better, considering the feedbacks we see on Github. However, not all chipsets are at the same level due to hal code missing (see point 3).<br />
# the kernel patching level. A lot of these drivers do not work anymore because the upstream maintainer (on Github mostly) do not patch their code for the latest kernels. Thankfully the solutions are available, and it is easy to patch, but we probably need to nuke all those outdated Github repositories.<br />
# the hal code. Realtek do not provide unified drivers. Hence the chipsets not having the same capabilities. So 8812, 8821 and 8814 have not been dispatched with the whole hal code for every chipset and versions are not in sync. Some people on github have done some work to add the various hal branches, but there is no one-for-all solution since it is not guaranteed that they all work with the same driver revision. Adding to that, I only have a 8812 dongle, so am unable to test for other chipsets before patching.<br />
<br />
As of today, and to the best of my knowledge, there are a few Github repos that have the latest possible driver AND the latest kernel patches (hence do work with a rolling release distro like ArchLinux):<br />
<br />
* 8812au: my repo (zebulon2), forked from gordboy's repo. Firmware 5.2.9, hal code for 8812 only. I just tried to change txpower but realtek have modified the config options, so there is a bit of a power issue there. Otherwise it works fine.<br />
* 8821au: my repo, forked from paspro's repo. Firmware 5.1.5, hal code for both 8821 and 8812. We are stuck at 5.1.5 because of the lack of hal code for 8821 and 5.2.9. Note this also works for unint where it is more difficult. bsdfirst repo has firmware 4.3.21 and this is working for kernels 4.12/4.11 (AUR https://aur.archlinux.org/packages/edimax_ac1750_8814au-dkms/). There is however a 5.1.5 repo tree from astsam. It seems he has been abale to merge the 5.1.5 and hal code for 8814 from previous series. I have suggested to the maintainer he tries this. However, he would need to add the kernel patches 4.11/4.12 because astsam has not done this yet. But if it were working 8814 users would have the driver 5 series too (which is much better). I would be happy to open a repo on Github and do this. However I have no 8814 device for testing myself, so we would have to release and ask people to give feedback.<br />
<br />
Sorry for being very complicated, but it is indeed complicated.<br />
<br />
Finally I'll need some guidance on how to handle the renaming scheme (I suppose we need to use 'replace' in the PKGBUILD)? Is there a guidance for naming kernel drivers? <br />
<br />
--[[User:Zeb|zeb]] ([[User talk:Zeb|talk]]) 10:57, 6 September 2017 (UTC)<br />
<br />
<br />
== rtl8723bu ==<br />
<br />
Having experienced issues with the default install of unified kernel module rtl8xxxu, I am able to confirm the apparent flawless functioning of the third party rtl8723bu module, as provided by lwfinger in his repo collection. This has been the case for the last few kernel releases, and remains so, for 4.14.14-1. It should be noted that by default, the driver operates the hardware as a station and access point simultaneously. Thus will show two wireless devices when you run the 'iwconfig' or 'ip link show' commands.<br />
<br />
Should anyone else be having issues with this particular chipset, the above is well worth trying. I'd also be interested to receive feedback.<br />
<br />
[[User:ChrisP|ChrisP]] ([[User talk:ChrisP|talk]]) 14:08, 15 January 2018 (UTC)<br />
<br />
== WPA2 enterprise and NetworkManager CLI ==<br />
<br />
According to [[Wireless_network_configuration#NetworkManager]], NetworkManager cannot create a WPA2 Enterprise profile with any frontend other than the graphical ones. But when googling this for someone in #archlinux-newbie, I hit [https://unix.stackexchange.com/questions/145366/how-to-connect-to-an-802-1x-wireless-network-via-nmcli/334675#334675 this link] before I saw the wiki here.<br />
<br />
Is this or isn't this possible? (I cannot test this myself.) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 17:40, 12 November 2017 (UTC)<br />
<br />
:Neither can I, but best way to get attention is to add [[Template:Accuracy]] with the stack overflow link. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 18:10, 13 November 2017 (UTC)<br />
<br />
== Wireless management rewrite ==<br />
<br />
The original [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=519817#Wireless_management Wireless management] section ceased to exist, instead, the page describes only the "manual setup". The only reference to the "automatic setup" (currently [[Network configuration#Network managers]]) is in the introduction, something along the way "if you want to use a network manager, go there and don't come back". There should still be an explicit section to avoid this, and also to mention combinations like (wpa_supplicant or iwd) + (dhcpcd or systemd-networkd), which you won't find on these two pages. Maybe overly long, but the intro from [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=473928#Wireless_management 2017] had a purpose which should be restored. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:14, 22 May 2018 (UTC)<br />
<br />
== WPA2 Personal section in Wireless Network Configuration ==<br />
<br />
I rarely use wireless, but needed to set up an Arch system on my daughter's system, which is wireless only. I spent a couple of hours trying to figure out how to get networking working from the ISO live boot, and thought it would be helpful to add a section to the Wiki page (which I found to be of little help). Let me also note that WPA2 Personal is the most likely thing someone is going to encounter outside the enterprise.<br />
<br />
Now I see a notice<br />
<br />
``This section is being considered for removal.``<br />
''Reason: Duplicates WPA supplicant. (Discuss in Talk:Wireless network configuration#)''<br />
<br />
That's extremely frustrating: yes, this is some sense duplicates contents from the WPA Supplicant wiki page, but this page isn't helpful '''unless you already know you need to use wpa_supplicant.'''<br />
<br />
If some duplication is entirely intolerable at least leave this:<br />
<br />
== WPA2 Personal ==<br />
<br />
To connect to a WPA2 Personal mode wireless router from the command line, you will need to use [[WPA Supplicant]].<br />
<br />
[[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 17:10, 13 July 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Network_configuration/Wireless&diff=577388Talk:Network configuration/Wireless2019-07-13T17:10:29Z<p>Pgoetz: moved signature for readability</p>
<hr />
<div>== wireless_tools ==<br />
iwlist uses outdated interfaces, and iw works better with modern wireless drivers. Can we remove the wireless_tools options from [[Wireless_network_configuration#Manual_setup]]? [[User:Pid1|Pid1]] ([[User talk:Pid1|talk]]) 15:11, 3 October 2015 (UTC)<br />
<br />
:Many sections in [[Wireless_network_configuration#Troubleshooting]] still suggest only iwconfig commands. We need to find equivalent iw options first... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:21, 3 October 2015 (UTC)<br />
<br />
== "your key" ==<br />
<br />
What is ''my key''? [[Wireless_network_configuration#Association]] --[[User:Kete|Kete]] ([[User talk:Kete|talk]]) 00:38, 11 March 2016 (UTC)<br />
<br />
:I believe it is the security password configured on the router. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 12:47, 11 March 2016 (UTC)<br />
<br />
== Setting regulatory domain ==<br />
<br />
In the section ''Respecting the regulatory domain'' in my opinion the following information should be added:<br />
<br />
Another reason for an unchanged regulatory domain after adjusting the settings can be the fact, that linux uses information about the regulatory domain provided by the access point.<br />
As far as I unterstand these information are only retrieved, if the PC is associated with the access point.<br />
For details see: [https://wireless.wiki.kernel.org/en/developers/regulatory/processing_rules] (subsection: ''Country IE processing'')<br />
<br />
{{unsigned|15:21, 7 May 2016|Aluser1137}}<br />
<br />
It says "WPA supplicant can also use a regdomain in the country= line of /etc/wpa_supplicant/wpa_supplicant.conf." I cannot find such a setting in the man page for either wpa_supplicant or wpa_supplicant.conf.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 23:49, 3 January 2018 (UTC)<br />
<br />
== rtl8812au/8814au/8821au ==<br />
<br />
I have updated the section on the Realtek USB chipsets for AC1200/1750/1900, respectively 8812au/8821au/8814au.<br />
<br />
I maintain two of them on the AUR and situation is complicated. But I was asked to give some insights on the state of these drivers.<br />
<br />
Realtek drivers are a mess. Three things to consider:<br />
# the driver version (4, 5.1.5, 5.2.9). It is a fair bet that the higher the better, considering the feedbacks we see on Github. However, not all chipsets are at the same level due to hal code missing (see point 3).<br />
# the kernel patching level. A lot of these drivers do not work anymore because the upstream maintainer (on Github mostly) do not patch their code for the latest kernels. Thankfully the solutions are available, and it is easy to patch, but we probably need to nuke all those outdated Github repositories.<br />
# the hal code. Realtek do not provide unified drivers. Hence the chipsets not having the same capabilities. So 8812, 8821 and 8814 have not been dispatched with the whole hal code for every chipset and versions are not in sync. Some people on github have done some work to add the various hal branches, but there is no one-for-all solution since it is not guaranteed that they all work with the same driver revision. Adding to that, I only have a 8812 dongle, so am unable to test for other chipsets before patching.<br />
<br />
As of today, and to the best of my knowledge, there are a few Github repos that have the latest possible driver AND the latest kernel patches (hence do work with a rolling release distro like ArchLinux):<br />
<br />
* 8812au: my repo (zebulon2), forked from gordboy's repo. Firmware 5.2.9, hal code for 8812 only. I just tried to change txpower but realtek have modified the config options, so there is a bit of a power issue there. Otherwise it works fine.<br />
* 8821au: my repo, forked from paspro's repo. Firmware 5.1.5, hal code for both 8821 and 8812. We are stuck at 5.1.5 because of the lack of hal code for 8821 and 5.2.9. Note this also works for unint where it is more difficult. bsdfirst repo has firmware 4.3.21 and this is working for kernels 4.12/4.11 (AUR https://aur.archlinux.org/packages/edimax_ac1750_8814au-dkms/). There is however a 5.1.5 repo tree from astsam. It seems he has been abale to merge the 5.1.5 and hal code for 8814 from previous series. I have suggested to the maintainer he tries this. However, he would need to add the kernel patches 4.11/4.12 because astsam has not done this yet. But if it were working 8814 users would have the driver 5 series too (which is much better). I would be happy to open a repo on Github and do this. However I have no 8814 device for testing myself, so we would have to release and ask people to give feedback.<br />
<br />
Sorry for being very complicated, but it is indeed complicated.<br />
<br />
Finally I'll need some guidance on how to handle the renaming scheme (I suppose we need to use 'replace' in the PKGBUILD)? Is there a guidance for naming kernel drivers? <br />
<br />
--[[User:Zeb|zeb]] ([[User talk:Zeb|talk]]) 10:57, 6 September 2017 (UTC)<br />
<br />
<br />
== rtl8723bu ==<br />
<br />
Having experienced issues with the default install of unified kernel module rtl8xxxu, I am able to confirm the apparent flawless functioning of the third party rtl8723bu module, as provided by lwfinger in his repo collection. This has been the case for the last few kernel releases, and remains so, for 4.14.14-1. It should be noted that by default, the driver operates the hardware as a station and access point simultaneously. Thus will show two wireless devices when you run the 'iwconfig' or 'ip link show' commands.<br />
<br />
Should anyone else be having issues with this particular chipset, the above is well worth trying. I'd also be interested to receive feedback.<br />
<br />
[[User:ChrisP|ChrisP]] ([[User talk:ChrisP|talk]]) 14:08, 15 January 2018 (UTC)<br />
<br />
== WPA2 enterprise and NetworkManager CLI ==<br />
<br />
According to [[Wireless_network_configuration#NetworkManager]], NetworkManager cannot create a WPA2 Enterprise profile with any frontend other than the graphical ones. But when googling this for someone in #archlinux-newbie, I hit [https://unix.stackexchange.com/questions/145366/how-to-connect-to-an-802-1x-wireless-network-via-nmcli/334675#334675 this link] before I saw the wiki here.<br />
<br />
Is this or isn't this possible? (I cannot test this myself.) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 17:40, 12 November 2017 (UTC)<br />
<br />
:Neither can I, but best way to get attention is to add [[Template:Accuracy]] with the stack overflow link. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 18:10, 13 November 2017 (UTC)<br />
<br />
== Wireless management rewrite ==<br />
<br />
The original [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=519817#Wireless_management Wireless management] section ceased to exist, instead, the page describes only the "manual setup". The only reference to the "automatic setup" (currently [[Network configuration#Network managers]]) is in the introduction, something along the way "if you want to use a network manager, go there and don't come back". There should still be an explicit section to avoid this, and also to mention combinations like (wpa_supplicant or iwd) + (dhcpcd or systemd-networkd), which you won't find on these two pages. Maybe overly long, but the intro from [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=473928#Wireless_management 2017] had a purpose which should be restored. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:14, 22 May 2018 (UTC)<br />
<br />
== WPA2 Personal section in Wireless Network Configuration ==<br />
<br />
I rarely use wireless, but needed to set up an Arch system on my daughter's system, which is wireless only. I spent a couple of hours trying to figure out how to get networking working from the ISO live boot, and thought it would be helpful to add a section to the Wiki page (which I found to be of little help). Let me also note that WPA2 Personal is the most likely thing someone is going to encounter outside the enterprise.<br />
<br />
Now I see a notice<br />
<br />
``This section is being considered for removal.``<br />
''Reason: Duplicates WPA supplicant. (Discuss in Talk:Wireless network configuration#)''<br />
<br />
That's extremely frustrating: yes, this is some sense duplicates contents from the WPA Supplicant wiki page, but this page isn't helpful ```unless you already know you need to use wpa_supplicant.'''<br />
<br />
If some duplication is entirely intolerable at least leave this:<br />
<br />
== WPA2 Personal ==<br />
<br />
To connect to a WPA2 Personal mode wireless router from the command line, you will need to use [[WPA Supplicant]].<br />
<br />
[[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 17:10, 13 July 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Network_configuration/Wireless&diff=577387Talk:Network configuration/Wireless2019-07-13T17:10:04Z<p>Pgoetz: moved signature to end</p>
<hr />
<div>== wireless_tools ==<br />
iwlist uses outdated interfaces, and iw works better with modern wireless drivers. Can we remove the wireless_tools options from [[Wireless_network_configuration#Manual_setup]]? [[User:Pid1|Pid1]] ([[User talk:Pid1|talk]]) 15:11, 3 October 2015 (UTC)<br />
<br />
:Many sections in [[Wireless_network_configuration#Troubleshooting]] still suggest only iwconfig commands. We need to find equivalent iw options first... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:21, 3 October 2015 (UTC)<br />
<br />
== "your key" ==<br />
<br />
What is ''my key''? [[Wireless_network_configuration#Association]] --[[User:Kete|Kete]] ([[User talk:Kete|talk]]) 00:38, 11 March 2016 (UTC)<br />
<br />
:I believe it is the security password configured on the router. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 12:47, 11 March 2016 (UTC)<br />
<br />
== Setting regulatory domain ==<br />
<br />
In the section ''Respecting the regulatory domain'' in my opinion the following information should be added:<br />
<br />
Another reason for an unchanged regulatory domain after adjusting the settings can be the fact, that linux uses information about the regulatory domain provided by the access point.<br />
As far as I unterstand these information are only retrieved, if the PC is associated with the access point.<br />
For details see: [https://wireless.wiki.kernel.org/en/developers/regulatory/processing_rules] (subsection: ''Country IE processing'')<br />
<br />
{{unsigned|15:21, 7 May 2016|Aluser1137}}<br />
<br />
It says "WPA supplicant can also use a regdomain in the country= line of /etc/wpa_supplicant/wpa_supplicant.conf." I cannot find such a setting in the man page for either wpa_supplicant or wpa_supplicant.conf.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 23:49, 3 January 2018 (UTC)<br />
<br />
== rtl8812au/8814au/8821au ==<br />
<br />
I have updated the section on the Realtek USB chipsets for AC1200/1750/1900, respectively 8812au/8821au/8814au.<br />
<br />
I maintain two of them on the AUR and situation is complicated. But I was asked to give some insights on the state of these drivers.<br />
<br />
Realtek drivers are a mess. Three things to consider:<br />
# the driver version (4, 5.1.5, 5.2.9). It is a fair bet that the higher the better, considering the feedbacks we see on Github. However, not all chipsets are at the same level due to hal code missing (see point 3).<br />
# the kernel patching level. A lot of these drivers do not work anymore because the upstream maintainer (on Github mostly) do not patch their code for the latest kernels. Thankfully the solutions are available, and it is easy to patch, but we probably need to nuke all those outdated Github repositories.<br />
# the hal code. Realtek do not provide unified drivers. Hence the chipsets not having the same capabilities. So 8812, 8821 and 8814 have not been dispatched with the whole hal code for every chipset and versions are not in sync. Some people on github have done some work to add the various hal branches, but there is no one-for-all solution since it is not guaranteed that they all work with the same driver revision. Adding to that, I only have a 8812 dongle, so am unable to test for other chipsets before patching.<br />
<br />
As of today, and to the best of my knowledge, there are a few Github repos that have the latest possible driver AND the latest kernel patches (hence do work with a rolling release distro like ArchLinux):<br />
<br />
* 8812au: my repo (zebulon2), forked from gordboy's repo. Firmware 5.2.9, hal code for 8812 only. I just tried to change txpower but realtek have modified the config options, so there is a bit of a power issue there. Otherwise it works fine.<br />
* 8821au: my repo, forked from paspro's repo. Firmware 5.1.5, hal code for both 8821 and 8812. We are stuck at 5.1.5 because of the lack of hal code for 8821 and 5.2.9. Note this also works for unint where it is more difficult. bsdfirst repo has firmware 4.3.21 and this is working for kernels 4.12/4.11 (AUR https://aur.archlinux.org/packages/edimax_ac1750_8814au-dkms/). There is however a 5.1.5 repo tree from astsam. It seems he has been abale to merge the 5.1.5 and hal code for 8814 from previous series. I have suggested to the maintainer he tries this. However, he would need to add the kernel patches 4.11/4.12 because astsam has not done this yet. But if it were working 8814 users would have the driver 5 series too (which is much better). I would be happy to open a repo on Github and do this. However I have no 8814 device for testing myself, so we would have to release and ask people to give feedback.<br />
<br />
Sorry for being very complicated, but it is indeed complicated.<br />
<br />
Finally I'll need some guidance on how to handle the renaming scheme (I suppose we need to use 'replace' in the PKGBUILD)? Is there a guidance for naming kernel drivers? <br />
<br />
--[[User:Zeb|zeb]] ([[User talk:Zeb|talk]]) 10:57, 6 September 2017 (UTC)<br />
<br />
<br />
== rtl8723bu ==<br />
<br />
Having experienced issues with the default install of unified kernel module rtl8xxxu, I am able to confirm the apparent flawless functioning of the third party rtl8723bu module, as provided by lwfinger in his repo collection. This has been the case for the last few kernel releases, and remains so, for 4.14.14-1. It should be noted that by default, the driver operates the hardware as a station and access point simultaneously. Thus will show two wireless devices when you run the 'iwconfig' or 'ip link show' commands.<br />
<br />
Should anyone else be having issues with this particular chipset, the above is well worth trying. I'd also be interested to receive feedback.<br />
<br />
[[User:ChrisP|ChrisP]] ([[User talk:ChrisP|talk]]) 14:08, 15 January 2018 (UTC)<br />
<br />
== WPA2 enterprise and NetworkManager CLI ==<br />
<br />
According to [[Wireless_network_configuration#NetworkManager]], NetworkManager cannot create a WPA2 Enterprise profile with any frontend other than the graphical ones. But when googling this for someone in #archlinux-newbie, I hit [https://unix.stackexchange.com/questions/145366/how-to-connect-to-an-802-1x-wireless-network-via-nmcli/334675#334675 this link] before I saw the wiki here.<br />
<br />
Is this or isn't this possible? (I cannot test this myself.) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 17:40, 12 November 2017 (UTC)<br />
<br />
:Neither can I, but best way to get attention is to add [[Template:Accuracy]] with the stack overflow link. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 18:10, 13 November 2017 (UTC)<br />
<br />
== Wireless management rewrite ==<br />
<br />
The original [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=519817#Wireless_management Wireless management] section ceased to exist, instead, the page describes only the "manual setup". The only reference to the "automatic setup" (currently [[Network configuration#Network managers]]) is in the introduction, something along the way "if you want to use a network manager, go there and don't come back". There should still be an explicit section to avoid this, and also to mention combinations like (wpa_supplicant or iwd) + (dhcpcd or systemd-networkd), which you won't find on these two pages. Maybe overly long, but the intro from [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=473928#Wireless_management 2017] had a purpose which should be restored. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:14, 22 May 2018 (UTC)<br />
<br />
== WPA2 Personal section in Wireless Network Configuration ==<br />
<br />
I rarely use wireless, but needed to set up an Arch system on my daughter's system, which is wireless only. I spent a couple of hours trying to figure out how to get networking working from the ISO live boot, and thought it would be helpful to add a section to the Wiki page (which I found to be of little help). Let me also note that WPA2 Personal is the most likely thing someone is going to encounter outside the enterprise.<br />
<br />
Now I see a notice<br />
<br />
``This section is being considered for removal.``<br />
''Reason: Duplicates WPA supplicant. (Discuss in Talk:Wireless network configuration#)''<br />
<br />
That's extremely frustrating: yes, this is some sense duplicates contents from the WPA Supplicant wiki page, but this page isn't helpful ```unless you already know you need to use wpa_supplicant.'''<br />
<br />
If some duplication is entirely intolerable at least leave this:<br />
<br />
== WPA2 Personal ==<br />
<br />
To connect to a WPA2 Personal mode wireless router from the command line, you will need to use [[WPA Supplicant]].[[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 17:10, 13 July 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Network_configuration/Wireless&diff=577386Talk:Network configuration/Wireless2019-07-13T17:09:22Z<p>Pgoetz: merge with previous section</p>
<hr />
<div>== wireless_tools ==<br />
iwlist uses outdated interfaces, and iw works better with modern wireless drivers. Can we remove the wireless_tools options from [[Wireless_network_configuration#Manual_setup]]? [[User:Pid1|Pid1]] ([[User talk:Pid1|talk]]) 15:11, 3 October 2015 (UTC)<br />
<br />
:Many sections in [[Wireless_network_configuration#Troubleshooting]] still suggest only iwconfig commands. We need to find equivalent iw options first... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:21, 3 October 2015 (UTC)<br />
<br />
== "your key" ==<br />
<br />
What is ''my key''? [[Wireless_network_configuration#Association]] --[[User:Kete|Kete]] ([[User talk:Kete|talk]]) 00:38, 11 March 2016 (UTC)<br />
<br />
:I believe it is the security password configured on the router. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 12:47, 11 March 2016 (UTC)<br />
<br />
== Setting regulatory domain ==<br />
<br />
In the section ''Respecting the regulatory domain'' in my opinion the following information should be added:<br />
<br />
Another reason for an unchanged regulatory domain after adjusting the settings can be the fact, that linux uses information about the regulatory domain provided by the access point.<br />
As far as I unterstand these information are only retrieved, if the PC is associated with the access point.<br />
For details see: [https://wireless.wiki.kernel.org/en/developers/regulatory/processing_rules] (subsection: ''Country IE processing'')<br />
<br />
{{unsigned|15:21, 7 May 2016|Aluser1137}}<br />
<br />
It says "WPA supplicant can also use a regdomain in the country= line of /etc/wpa_supplicant/wpa_supplicant.conf." I cannot find such a setting in the man page for either wpa_supplicant or wpa_supplicant.conf.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 23:49, 3 January 2018 (UTC)<br />
<br />
== rtl8812au/8814au/8821au ==<br />
<br />
I have updated the section on the Realtek USB chipsets for AC1200/1750/1900, respectively 8812au/8821au/8814au.<br />
<br />
I maintain two of them on the AUR and situation is complicated. But I was asked to give some insights on the state of these drivers.<br />
<br />
Realtek drivers are a mess. Three things to consider:<br />
# the driver version (4, 5.1.5, 5.2.9). It is a fair bet that the higher the better, considering the feedbacks we see on Github. However, not all chipsets are at the same level due to hal code missing (see point 3).<br />
# the kernel patching level. A lot of these drivers do not work anymore because the upstream maintainer (on Github mostly) do not patch their code for the latest kernels. Thankfully the solutions are available, and it is easy to patch, but we probably need to nuke all those outdated Github repositories.<br />
# the hal code. Realtek do not provide unified drivers. Hence the chipsets not having the same capabilities. So 8812, 8821 and 8814 have not been dispatched with the whole hal code for every chipset and versions are not in sync. Some people on github have done some work to add the various hal branches, but there is no one-for-all solution since it is not guaranteed that they all work with the same driver revision. Adding to that, I only have a 8812 dongle, so am unable to test for other chipsets before patching.<br />
<br />
As of today, and to the best of my knowledge, there are a few Github repos that have the latest possible driver AND the latest kernel patches (hence do work with a rolling release distro like ArchLinux):<br />
<br />
* 8812au: my repo (zebulon2), forked from gordboy's repo. Firmware 5.2.9, hal code for 8812 only. I just tried to change txpower but realtek have modified the config options, so there is a bit of a power issue there. Otherwise it works fine.<br />
* 8821au: my repo, forked from paspro's repo. Firmware 5.1.5, hal code for both 8821 and 8812. We are stuck at 5.1.5 because of the lack of hal code for 8821 and 5.2.9. Note this also works for unint where it is more difficult. bsdfirst repo has firmware 4.3.21 and this is working for kernels 4.12/4.11 (AUR https://aur.archlinux.org/packages/edimax_ac1750_8814au-dkms/). There is however a 5.1.5 repo tree from astsam. It seems he has been abale to merge the 5.1.5 and hal code for 8814 from previous series. I have suggested to the maintainer he tries this. However, he would need to add the kernel patches 4.11/4.12 because astsam has not done this yet. But if it were working 8814 users would have the driver 5 series too (which is much better). I would be happy to open a repo on Github and do this. However I have no 8814 device for testing myself, so we would have to release and ask people to give feedback.<br />
<br />
Sorry for being very complicated, but it is indeed complicated.<br />
<br />
Finally I'll need some guidance on how to handle the renaming scheme (I suppose we need to use 'replace' in the PKGBUILD)? Is there a guidance for naming kernel drivers? <br />
<br />
--[[User:Zeb|zeb]] ([[User talk:Zeb|talk]]) 10:57, 6 September 2017 (UTC)<br />
<br />
<br />
== rtl8723bu ==<br />
<br />
Having experienced issues with the default install of unified kernel module rtl8xxxu, I am able to confirm the apparent flawless functioning of the third party rtl8723bu module, as provided by lwfinger in his repo collection. This has been the case for the last few kernel releases, and remains so, for 4.14.14-1. It should be noted that by default, the driver operates the hardware as a station and access point simultaneously. Thus will show two wireless devices when you run the 'iwconfig' or 'ip link show' commands.<br />
<br />
Should anyone else be having issues with this particular chipset, the above is well worth trying. I'd also be interested to receive feedback.<br />
<br />
[[User:ChrisP|ChrisP]] ([[User talk:ChrisP|talk]]) 14:08, 15 January 2018 (UTC)<br />
<br />
== WPA2 enterprise and NetworkManager CLI ==<br />
<br />
According to [[Wireless_network_configuration#NetworkManager]], NetworkManager cannot create a WPA2 Enterprise profile with any frontend other than the graphical ones. But when googling this for someone in #archlinux-newbie, I hit [https://unix.stackexchange.com/questions/145366/how-to-connect-to-an-802-1x-wireless-network-via-nmcli/334675#334675 this link] before I saw the wiki here.<br />
<br />
Is this or isn't this possible? (I cannot test this myself.) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 17:40, 12 November 2017 (UTC)<br />
<br />
:Neither can I, but best way to get attention is to add [[Template:Accuracy]] with the stack overflow link. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 18:10, 13 November 2017 (UTC)<br />
<br />
== Wireless management rewrite ==<br />
<br />
The original [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=519817#Wireless_management Wireless management] section ceased to exist, instead, the page describes only the "manual setup". The only reference to the "automatic setup" (currently [[Network configuration#Network managers]]) is in the introduction, something along the way "if you want to use a network manager, go there and don't come back". There should still be an explicit section to avoid this, and also to mention combinations like (wpa_supplicant or iwd) + (dhcpcd or systemd-networkd), which you won't find on these two pages. Maybe overly long, but the intro from [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=473928#Wireless_management 2017] had a purpose which should be restored. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:14, 22 May 2018 (UTC)<br />
<br />
== WPA2 Personal section in Wireless Network Configuration ==<br />
<br />
I rarely use wireless, but needed to set up an Arch system on my daughter's system, which is wireless only. I spent a couple of hours trying to figure out how to get networking working from the ISO live boot, and thought it would be helpful to add a section to the Wiki page (which I found to be of little help). Let me also note that WPA2 Personal is the most likely thing someone is going to encounter outside the enterprise.<br />
<br />
Now I see a notice<br />
<br />
``This section is being considered for removal.``<br />
''Reason: Duplicates WPA supplicant. (Discuss in Talk:Wireless network configuration#)''<br />
<br />
That's extremely frustrating: yes, this is some sense duplicates contents from the WPA Supplicant wiki page, but this page isn't helpful ```unless you already know you need to use wpa_supplicant.'''<br />
<br />
If some duplication is entirely intolerable at least leave this:[[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 17:08, 13 July 2019 (UTC)<br />
<br />
== WPA2 Personal ==<br />
<br />
To connect to a WPA2 Personal mode wireless router from the command line, you will need to use [[WPA Supplicant]].</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Network_configuration/Wireless&diff=577385Talk:Network configuration/Wireless2019-07-13T17:08:58Z<p>Pgoetz: added signature</p>
<hr />
<div>== wireless_tools ==<br />
iwlist uses outdated interfaces, and iw works better with modern wireless drivers. Can we remove the wireless_tools options from [[Wireless_network_configuration#Manual_setup]]? [[User:Pid1|Pid1]] ([[User talk:Pid1|talk]]) 15:11, 3 October 2015 (UTC)<br />
<br />
:Many sections in [[Wireless_network_configuration#Troubleshooting]] still suggest only iwconfig commands. We need to find equivalent iw options first... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:21, 3 October 2015 (UTC)<br />
<br />
== "your key" ==<br />
<br />
What is ''my key''? [[Wireless_network_configuration#Association]] --[[User:Kete|Kete]] ([[User talk:Kete|talk]]) 00:38, 11 March 2016 (UTC)<br />
<br />
:I believe it is the security password configured on the router. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 12:47, 11 March 2016 (UTC)<br />
<br />
== Setting regulatory domain ==<br />
<br />
In the section ''Respecting the regulatory domain'' in my opinion the following information should be added:<br />
<br />
Another reason for an unchanged regulatory domain after adjusting the settings can be the fact, that linux uses information about the regulatory domain provided by the access point.<br />
As far as I unterstand these information are only retrieved, if the PC is associated with the access point.<br />
For details see: [https://wireless.wiki.kernel.org/en/developers/regulatory/processing_rules] (subsection: ''Country IE processing'')<br />
<br />
{{unsigned|15:21, 7 May 2016|Aluser1137}}<br />
<br />
It says "WPA supplicant can also use a regdomain in the country= line of /etc/wpa_supplicant/wpa_supplicant.conf." I cannot find such a setting in the man page for either wpa_supplicant or wpa_supplicant.conf.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 23:49, 3 January 2018 (UTC)<br />
<br />
== rtl8812au/8814au/8821au ==<br />
<br />
I have updated the section on the Realtek USB chipsets for AC1200/1750/1900, respectively 8812au/8821au/8814au.<br />
<br />
I maintain two of them on the AUR and situation is complicated. But I was asked to give some insights on the state of these drivers.<br />
<br />
Realtek drivers are a mess. Three things to consider:<br />
# the driver version (4, 5.1.5, 5.2.9). It is a fair bet that the higher the better, considering the feedbacks we see on Github. However, not all chipsets are at the same level due to hal code missing (see point 3).<br />
# the kernel patching level. A lot of these drivers do not work anymore because the upstream maintainer (on Github mostly) do not patch their code for the latest kernels. Thankfully the solutions are available, and it is easy to patch, but we probably need to nuke all those outdated Github repositories.<br />
# the hal code. Realtek do not provide unified drivers. Hence the chipsets not having the same capabilities. So 8812, 8821 and 8814 have not been dispatched with the whole hal code for every chipset and versions are not in sync. Some people on github have done some work to add the various hal branches, but there is no one-for-all solution since it is not guaranteed that they all work with the same driver revision. Adding to that, I only have a 8812 dongle, so am unable to test for other chipsets before patching.<br />
<br />
As of today, and to the best of my knowledge, there are a few Github repos that have the latest possible driver AND the latest kernel patches (hence do work with a rolling release distro like ArchLinux):<br />
<br />
* 8812au: my repo (zebulon2), forked from gordboy's repo. Firmware 5.2.9, hal code for 8812 only. I just tried to change txpower but realtek have modified the config options, so there is a bit of a power issue there. Otherwise it works fine.<br />
* 8821au: my repo, forked from paspro's repo. Firmware 5.1.5, hal code for both 8821 and 8812. We are stuck at 5.1.5 because of the lack of hal code for 8821 and 5.2.9. Note this also works for unint where it is more difficult. bsdfirst repo has firmware 4.3.21 and this is working for kernels 4.12/4.11 (AUR https://aur.archlinux.org/packages/edimax_ac1750_8814au-dkms/). There is however a 5.1.5 repo tree from astsam. It seems he has been abale to merge the 5.1.5 and hal code for 8814 from previous series. I have suggested to the maintainer he tries this. However, he would need to add the kernel patches 4.11/4.12 because astsam has not done this yet. But if it were working 8814 users would have the driver 5 series too (which is much better). I would be happy to open a repo on Github and do this. However I have no 8814 device for testing myself, so we would have to release and ask people to give feedback.<br />
<br />
Sorry for being very complicated, but it is indeed complicated.<br />
<br />
Finally I'll need some guidance on how to handle the renaming scheme (I suppose we need to use 'replace' in the PKGBUILD)? Is there a guidance for naming kernel drivers? <br />
<br />
--[[User:Zeb|zeb]] ([[User talk:Zeb|talk]]) 10:57, 6 September 2017 (UTC)<br />
<br />
<br />
== rtl8723bu ==<br />
<br />
Having experienced issues with the default install of unified kernel module rtl8xxxu, I am able to confirm the apparent flawless functioning of the third party rtl8723bu module, as provided by lwfinger in his repo collection. This has been the case for the last few kernel releases, and remains so, for 4.14.14-1. It should be noted that by default, the driver operates the hardware as a station and access point simultaneously. Thus will show two wireless devices when you run the 'iwconfig' or 'ip link show' commands.<br />
<br />
Should anyone else be having issues with this particular chipset, the above is well worth trying. I'd also be interested to receive feedback.<br />
<br />
[[User:ChrisP|ChrisP]] ([[User talk:ChrisP|talk]]) 14:08, 15 January 2018 (UTC)<br />
<br />
== WPA2 enterprise and NetworkManager CLI ==<br />
<br />
According to [[Wireless_network_configuration#NetworkManager]], NetworkManager cannot create a WPA2 Enterprise profile with any frontend other than the graphical ones. But when googling this for someone in #archlinux-newbie, I hit [https://unix.stackexchange.com/questions/145366/how-to-connect-to-an-802-1x-wireless-network-via-nmcli/334675#334675 this link] before I saw the wiki here.<br />
<br />
Is this or isn't this possible? (I cannot test this myself.) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 17:40, 12 November 2017 (UTC)<br />
<br />
:Neither can I, but best way to get attention is to add [[Template:Accuracy]] with the stack overflow link. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 18:10, 13 November 2017 (UTC)<br />
<br />
== Wireless management rewrite ==<br />
<br />
The original [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=519817#Wireless_management Wireless management] section ceased to exist, instead, the page describes only the "manual setup". The only reference to the "automatic setup" (currently [[Network configuration#Network managers]]) is in the introduction, something along the way "if you want to use a network manager, go there and don't come back". There should still be an explicit section to avoid this, and also to mention combinations like (wpa_supplicant or iwd) + (dhcpcd or systemd-networkd), which you won't find on these two pages. Maybe overly long, but the intro from [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=473928#Wireless_management 2017] had a purpose which should be restored. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:14, 22 May 2018 (UTC)<br />
<br />
== WPA2 Personal section in Wireless Network Configuration ==<br />
<br />
I rarely use wireless, but needed to set up an Arch system on my daughter's system, which is wireless only. I spent a couple of hours trying to figure out how to get networking working from the ISO live boot, and thought it would be helpful to add a section to the Wiki page (which I found to be of little help). Let me also note that WPA2 Personal is the most likely thing someone is going to encounter outside the enterprise.<br />
<br />
Now I see a notice<br />
<br />
``This section is being considered for removal.``<br />
''Reason: Duplicates WPA supplicant. (Discuss in Talk:Wireless network configuration#)''<br />
<br />
That's extremely frustrating: yes, this is some sense duplicates contents from the WPA Supplicant wiki page, but this page isn't helpful ```unless you already know you need to use wpa_supplicant.'''<br />
<br />
If some duplication is entirely intolerable at least leave this:[[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 17:08, 13 July 2019 (UTC)<br />
<br />
== WPA2 Personal ==<br />
<br />
To connect to a WPA2 Personal mode wireless router from the command line, you will need to use [[WPA Supplicant]].</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Network_configuration/Wireless&diff=577384Talk:Network configuration/Wireless2019-07-13T17:08:16Z<p>Pgoetz: /* WPA2 Personal section in Wireless Network Configuration */ new section</p>
<hr />
<div>== wireless_tools ==<br />
iwlist uses outdated interfaces, and iw works better with modern wireless drivers. Can we remove the wireless_tools options from [[Wireless_network_configuration#Manual_setup]]? [[User:Pid1|Pid1]] ([[User talk:Pid1|talk]]) 15:11, 3 October 2015 (UTC)<br />
<br />
:Many sections in [[Wireless_network_configuration#Troubleshooting]] still suggest only iwconfig commands. We need to find equivalent iw options first... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:21, 3 October 2015 (UTC)<br />
<br />
== "your key" ==<br />
<br />
What is ''my key''? [[Wireless_network_configuration#Association]] --[[User:Kete|Kete]] ([[User talk:Kete|talk]]) 00:38, 11 March 2016 (UTC)<br />
<br />
:I believe it is the security password configured on the router. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 12:47, 11 March 2016 (UTC)<br />
<br />
== Setting regulatory domain ==<br />
<br />
In the section ''Respecting the regulatory domain'' in my opinion the following information should be added:<br />
<br />
Another reason for an unchanged regulatory domain after adjusting the settings can be the fact, that linux uses information about the regulatory domain provided by the access point.<br />
As far as I unterstand these information are only retrieved, if the PC is associated with the access point.<br />
For details see: [https://wireless.wiki.kernel.org/en/developers/regulatory/processing_rules] (subsection: ''Country IE processing'')<br />
<br />
{{unsigned|15:21, 7 May 2016|Aluser1137}}<br />
<br />
It says "WPA supplicant can also use a regdomain in the country= line of /etc/wpa_supplicant/wpa_supplicant.conf." I cannot find such a setting in the man page for either wpa_supplicant or wpa_supplicant.conf.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 23:49, 3 January 2018 (UTC)<br />
<br />
== rtl8812au/8814au/8821au ==<br />
<br />
I have updated the section on the Realtek USB chipsets for AC1200/1750/1900, respectively 8812au/8821au/8814au.<br />
<br />
I maintain two of them on the AUR and situation is complicated. But I was asked to give some insights on the state of these drivers.<br />
<br />
Realtek drivers are a mess. Three things to consider:<br />
# the driver version (4, 5.1.5, 5.2.9). It is a fair bet that the higher the better, considering the feedbacks we see on Github. However, not all chipsets are at the same level due to hal code missing (see point 3).<br />
# the kernel patching level. A lot of these drivers do not work anymore because the upstream maintainer (on Github mostly) do not patch their code for the latest kernels. Thankfully the solutions are available, and it is easy to patch, but we probably need to nuke all those outdated Github repositories.<br />
# the hal code. Realtek do not provide unified drivers. Hence the chipsets not having the same capabilities. So 8812, 8821 and 8814 have not been dispatched with the whole hal code for every chipset and versions are not in sync. Some people on github have done some work to add the various hal branches, but there is no one-for-all solution since it is not guaranteed that they all work with the same driver revision. Adding to that, I only have a 8812 dongle, so am unable to test for other chipsets before patching.<br />
<br />
As of today, and to the best of my knowledge, there are a few Github repos that have the latest possible driver AND the latest kernel patches (hence do work with a rolling release distro like ArchLinux):<br />
<br />
* 8812au: my repo (zebulon2), forked from gordboy's repo. Firmware 5.2.9, hal code for 8812 only. I just tried to change txpower but realtek have modified the config options, so there is a bit of a power issue there. Otherwise it works fine.<br />
* 8821au: my repo, forked from paspro's repo. Firmware 5.1.5, hal code for both 8821 and 8812. We are stuck at 5.1.5 because of the lack of hal code for 8821 and 5.2.9. Note this also works for unint where it is more difficult. bsdfirst repo has firmware 4.3.21 and this is working for kernels 4.12/4.11 (AUR https://aur.archlinux.org/packages/edimax_ac1750_8814au-dkms/). There is however a 5.1.5 repo tree from astsam. It seems he has been abale to merge the 5.1.5 and hal code for 8814 from previous series. I have suggested to the maintainer he tries this. However, he would need to add the kernel patches 4.11/4.12 because astsam has not done this yet. But if it were working 8814 users would have the driver 5 series too (which is much better). I would be happy to open a repo on Github and do this. However I have no 8814 device for testing myself, so we would have to release and ask people to give feedback.<br />
<br />
Sorry for being very complicated, but it is indeed complicated.<br />
<br />
Finally I'll need some guidance on how to handle the renaming scheme (I suppose we need to use 'replace' in the PKGBUILD)? Is there a guidance for naming kernel drivers? <br />
<br />
--[[User:Zeb|zeb]] ([[User talk:Zeb|talk]]) 10:57, 6 September 2017 (UTC)<br />
<br />
<br />
== rtl8723bu ==<br />
<br />
Having experienced issues with the default install of unified kernel module rtl8xxxu, I am able to confirm the apparent flawless functioning of the third party rtl8723bu module, as provided by lwfinger in his repo collection. This has been the case for the last few kernel releases, and remains so, for 4.14.14-1. It should be noted that by default, the driver operates the hardware as a station and access point simultaneously. Thus will show two wireless devices when you run the 'iwconfig' or 'ip link show' commands.<br />
<br />
Should anyone else be having issues with this particular chipset, the above is well worth trying. I'd also be interested to receive feedback.<br />
<br />
[[User:ChrisP|ChrisP]] ([[User talk:ChrisP|talk]]) 14:08, 15 January 2018 (UTC)<br />
<br />
== WPA2 enterprise and NetworkManager CLI ==<br />
<br />
According to [[Wireless_network_configuration#NetworkManager]], NetworkManager cannot create a WPA2 Enterprise profile with any frontend other than the graphical ones. But when googling this for someone in #archlinux-newbie, I hit [https://unix.stackexchange.com/questions/145366/how-to-connect-to-an-802-1x-wireless-network-via-nmcli/334675#334675 this link] before I saw the wiki here.<br />
<br />
Is this or isn't this possible? (I cannot test this myself.) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 17:40, 12 November 2017 (UTC)<br />
<br />
:Neither can I, but best way to get attention is to add [[Template:Accuracy]] with the stack overflow link. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 18:10, 13 November 2017 (UTC)<br />
<br />
== Wireless management rewrite ==<br />
<br />
The original [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=519817#Wireless_management Wireless management] section ceased to exist, instead, the page describes only the "manual setup". The only reference to the "automatic setup" (currently [[Network configuration#Network managers]]) is in the introduction, something along the way "if you want to use a network manager, go there and don't come back". There should still be an explicit section to avoid this, and also to mention combinations like (wpa_supplicant or iwd) + (dhcpcd or systemd-networkd), which you won't find on these two pages. Maybe overly long, but the intro from [https://wiki.archlinux.org/index.php?title=Wireless_network_configuration&oldid=473928#Wireless_management 2017] had a purpose which should be restored. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:14, 22 May 2018 (UTC)<br />
<br />
== WPA2 Personal section in Wireless Network Configuration ==<br />
<br />
I rarely use wireless, but needed to set up an Arch system on my daughter's system, which is wireless only. I spent a couple of hours trying to figure out how to get networking working from the ISO live boot, and thought it would be helpful to add a section to the Wiki page (which I found to be of little help). Let me also note that WPA2 Personal is the most likely thing someone is going to encounter outside the enterprise.<br />
<br />
Now I see a notice<br />
<br />
``This section is being considered for removal.``<br />
''Reason: Duplicates WPA supplicant. (Discuss in Talk:Wireless network configuration#)''<br />
<br />
That's extremely frustrating: yes, this is some sense duplicates contents from the WPA Supplicant wiki page, but this page isn't helpful ```unless you already know you need to use wpa_supplicant.'''<br />
<br />
If some duplication is entirely intolerable at least leave this:<br />
<br />
== WPA2 Personal ==<br />
<br />
To connect to a WPA2 Personal mode wireless router from the command line, you will need to use [[WPA Supplicant]].</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=577383Network configuration/Wireless2019-07-13T17:01:26Z<p>Pgoetz: added wiki link to WPA Supplicant</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[cs:Wireless network configuration]]<br />
[[de:(W)LAN und Arch Linux]]<br />
[[el:Wireless network configuration]]<br />
[[es:Wireless network configuration]]<br />
[[fa:تنظیمات شبکه ی بی سیم]]<br />
[[fr:Wifi]]<br />
[[it:Wireless network configuration]]<br />
[[ja:ワイヤレス設定]]<br />
[[nl:Wireless network configuration]]<br />
[[pt:Wireless network configuration]]<br />
[[ru:Wireless network configuration]]<br />
[[th:Wireless network configuration]]<br />
[[zh-hans:Wireless network configuration]]<br />
{{Related articles start}}<br />
{{Related|Software access point}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related|Wireless bonding}}<br />
{{Related|Network Debugging}}<br />
{{Related|Bluetooth}}<br />
{{Related articles end}}<br />
{{Move|Network configuration/Wireless|Page depends on [[Network configuration]].|Talk:Network configuration#Moving Ethernet-specific sections to Wired subpage}}<br />
The main article on network configuration is [[Network configuration]].<br />
<br />
Configuring wireless is a two-part process; the first part is to identify and ensure the correct driver for your wireless device is installed (they are available on the installation media, but often have to be installed explicitly), and to configure the interface. The second is choosing a method of managing wireless connections. This article covers both parts, and provides additional links to wireless management tools.<br />
<br />
The [[#iw]] section describes how to manually manage your wireless network interface / your wireless LANs using {{Pkg|iw}}. The [[Network configuration#Network managers]] section describes several programs that can be used to automatically manage your wireless interface, some of which include a GUI and all of which include support for network profiles (useful when frequently switching wireless networks, like with laptops).<br />
<br />
== Device driver ==<br />
<br />
The default Arch Linux kernel is ''modular'', meaning many of the drivers for machine hardware reside on the hard drive and are available as [[Kernel modules|modules]]. At boot, [[udev]] takes an inventory of your hardware and loads appropriate modules (drivers) for your corresponding hardware, which will in turn allow creation of a network ''interface''.<br />
<br />
Some wireless chipsets also require firmware, in addition to a corresponding driver. Many firmware images are provided by the {{Pkg|linux-firmware}} package which is installed by default, however, proprietary firmware images are not included and have to be installed separately. This is described in [[#Installing driver/firmware]].<br />
<br />
{{Note|If the proper module is not loaded by udev on boot, simply [[Kernel modules#Manual module handling|load it manually]]. If udev loads more than one driver for a device, the resulting conflict may prevent successful configuration. Make sure to [[blacklist]] the unwanted module.}}<br />
<br />
=== Check the driver status ===<br />
<br />
To check if the driver for your card has been loaded, check the output of the {{ic|lspci -k}} or {{ic|lsusb -v}} command, depending on if the card is connected by PCI(e) or USB. You should see that some kernel driver is in use, for example:<br />
<br />
{{hc|$ lspci -k|<nowiki><br />
06:00.0 Network controller: Intel Corporation WiFi Link 5100<br />
Subsystem: Intel Corporation WiFi Link 5100 AGN<br />
Kernel driver in use: iwlwifi<br />
Kernel modules: iwlwifi<br />
</nowiki>}}<br />
<br />
{{Note|If the card is a USB device, running {{ic|dmesg {{!}} grep usbcore}} should give something like {{ic|usbcore: registered new interface driver rtl8187}} as output.}}<br />
<br />
Also check the output of the {{ic|ip link}} command to see if a wireless interface was created; usually the naming of the wireless [[network interfaces]] starts with the letter "w", e.g. {{ic|wlan0}} or {{ic|wlp2s0}}. Then bring the interface up with:<br />
<br />
# ip link set ''interface'' up<br />
<br />
For example, assuming the interface is {{ic|wlan0}}, this is {{ic|ip link set wlan0 up}}.<br />
<br />
If you get the error message {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means that your wireless chipset requires a firmware to function.<br />
<br />
Check kernel messages for firmware being loaded:<br />
<br />
{{hc|<nowiki>$ dmesg | grep firmware</nowiki>|<nowiki><br />
[ 7.148259] iwlwifi 0000:02:00.0: loaded firmware version 39.30.4.1 build 35138 op_mode iwldvm<br />
</nowiki>}}<br />
<br />
If there is no relevant output, check the messages for the full output for the module you identified earlier ({{ic|iwlwifi}} in this example) to identify the relevant message or further issues:<br />
<br />
{{hc|<nowiki>$ dmesg | grep iwlwifi</nowiki>|<nowiki><br />
[ 12.342694] iwlwifi 0000:02:00.0: irq 44 for MSI/MSI-X<br />
[ 12.353466] iwlwifi 0000:02:00.0: loaded firmware version 39.31.5.1 build 35138 op_mode iwldvm<br />
[ 12.430317] iwlwifi 0000:02:00.0: CONFIG_IWLWIFI_DEBUG disabled<br />
...<br />
[ 12.430341] iwlwifi 0000:02:00.0: Detected Intel(R) Corporation WiFi Link 5100 AGN, REV=0x6B<br />
</nowiki>}}<br />
<br />
If the kernel module is successfully loaded and the interface is up, you can skip the next section.<br />
<br />
=== Installing driver/firmware ===<br />
<br />
Check the following lists to discover if your card is supported:<br />
<br />
* See the table of [https://wireless.wiki.kernel.org/en/users/drivers existing Linux wireless drivers] and follow to the specific driver's page, which contains a list of supported devices. There is also a [https://wikidevi.com/wiki/List_of_Wi-Fi_Device_IDs_in_Linux List of Wi-Fi Device IDs in Linux].<br />
* The [https://help.ubuntu.com/community/WifiDocs/WirelessCardsSupported Ubuntu Wiki] has a good list of wireless cards and whether or not they are supported either in the Linux kernel or by a user-space driver (includes driver name).<br />
* [http://linux-wless.passys.nl/ Linux Wireless Support] and The Linux Questions' [http://www.linuxquestions.org/hcl/index.php?cat=10 Hardware Compatibility List] (HCL) also have a good database of kernel-friendly hardware.<br />
<br />
Note that some vendors ship products that may contain different chip sets, even if the product identifier is the same. Only the usb-id (for USB devices) or pci-id (for PCI devices) is authoritative.<br />
<br />
If your wireless card is listed above, follow the [[#Troubleshooting drivers and firmware]] subsection of this page, which contains information about installing drivers and firmware of some specific wireless cards. Then [[#Check the driver status|check the driver status]] again.<br />
<br />
If your wireless card is not listed above, it is likely supported only under Windows (some Broadcom, 3com, etc). For these, you can try to use [[#ndiswrapper]].<br />
<br />
== Utilities ==<br />
<br />
Just like other network interfaces, the wireless ones are controlled with ''ip'' from the {{Pkg|iproute2}} package.<br />
<br />
Managing a wireless connection requires a basic set of tools. Either use a [[network manager]] or use one of the following directly:<br />
<br />
{| class="wikitable"<br />
! Software !! Package !! [https://wireless.wiki.kernel.org/en/developers/documentation/wireless-extensions WEXT] !! [https://wireless.wiki.kernel.org/en/developers/documentation/nl80211 nl80211] !! WEP !! WPA/WPA2 !! [[Archiso]] [https://git.archlinux.org/archiso.git/tree/configs/releng/packages.x86_64]<br />
|-<br />
| [http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html wireless_tools]<sup>1</sup> || {{pkg|wireless_tools}} || {{yes}} || {{no}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [https://wireless.kernel.org/en/users/Documentation/iw iw] || {{Pkg|iw}} || {{No}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [[WPA supplicant]] || {{Pkg|wpa_supplicant}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|-<br />
| [[iwd]] || {{Pkg|iwd}} || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
# Deprecated.<br />
<br />
Note that some cards only support WEXT.<br />
<br />
=== iw and wireless_tools comparison ===<br />
<br />
The table below gives an overview of comparable commands for ''iw'' and ''wireless_tools''. See [http://wireless.kernel.org/en/users/Documentation/iw/replace-iwconfig iw replaces iwconfig] for more examples.<br />
<br />
{| class="wikitable"<br />
! ''iw'' command<br />
! ''wireless_tools'' command<br />
! Description<br />
|-<br />
| iw dev ''wlan0'' link<br />
| iwconfig ''wlan0''<br />
| Getting link status.<br />
|-<br />
| iw dev ''wlan0'' scan<br />
| iwlist ''wlan0'' scan<br />
| Scanning for available access points.<br />
|-<br />
| iw dev ''wlan0'' set type ibss<br />
| iwconfig ''wlan0'' mode ad-hoc<br />
| Setting the operation mode to ''ad-hoc''.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid''<br />
| iwconfig ''wlan0'' essid ''your_essid''<br />
| Connecting to open network.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid'' 2432<br />
| iwconfig ''wlan0'' essid ''your_essid'' freq 2432M<br />
| Connecting to open network specifying channel.<br />
|-<br />
| rowspan="2" | iw dev ''wlan0'' connect ''your_essid'' key 0:''your_key''<br />
| iwconfig ''wlan0'' essid ''your_essid'' key ''your_key''<br />
| Connecting to WEP encrypted network using hexadecimal key.<br />
|-<br />
| iwconfig ''wlan0'' essid ''your_essid'' key s:''your_key''<br />
| Connecting to WEP encrypted network using ASCII key.<br />
|-<br />
| iw dev ''wlan0'' set power_save on<br />
| iwconfig ''wlan0'' power on<br />
| Enabling power save.<br />
|}<br />
<br />
== iw ==<br />
<br />
{{Note|<br />
* Note that most of the commands have to be executed with [[Users and groups|root permissions]]. Executed with normal user rights, some of the commands (e.g. ''iwlist''), will exit without error but not produce the correct output either, which can be confusing.<br />
* Depending on your hardware and encryption type, some of these steps may not be necessary. Some cards are known to require interface activation and/or access point scanning before being associated to an access point and being given an IP address. Some experimentation may be required. For instance, WPA/WPA2 users may try to directly activate their wireless network from step [[#Connect to an access point]].}}<br />
<br />
Examples in this section assume that your wireless device interface is {{ic|''interface''}} and that you are connecting to {{ic|''your_essid''}} wifi access point. Replace both accordingly.<br />
<br />
=== Get the name of the interface ===<br />
<br />
{{Tip|See [http://wireless.kernel.org/en/users/Documentation/iw official documentation] of the ''iw'' tool for more examples.}}<br />
<br />
To get the name of your wireless interface do:<br />
<br />
$ iw dev<br />
<br />
The name of the interface will be output after the word "Interface". For example, it is commonly {{ic|wlan0}}.<br />
<br />
=== Get the status of the interface ===<br />
<br />
To check link status, use following command.<br />
<br />
$ iw dev ''interface'' link<br />
<br />
You can get statistic information, such as the amount of tx/rx bytes, signal strength etc., with following command:<br />
<br />
$ iw dev ''interface'' station dump<br />
<br />
=== Activate the interface ===<br />
<br />
{{Tip|Usually this step is not required.}}<br />
<br />
Some cards require that the kernel interface be activated before you can use ''iw'' or ''wireless_tools'':<br />
<br />
# ip link set ''interface'' up<br />
<br />
{{Note|If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.}}<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|$ ip link show ''interface''|<br />
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 12:34:56:78:9a:bc brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
=== Discover access points ===<br />
<br />
To see what access points are available:<br />
<br />
# iw dev ''interface'' scan | less<br />
<br />
{{Note|If it displays {{ic|Interface does not support scanning}}, then you probably forgot to install the firmware. In some cases this message is also displayed when not running ''iw'' as root.}}<br />
<br />
{{Tip|Depending on your location, you might need to set the correct [[#Respecting the regulatory domain|regulatory domain]] in order to see all available networks.}}<br />
<br />
The important points to check:<br />
* '''SSID:''' the name of the network.<br />
* '''Signal:''' is reported in a wireless power ratio in dBm (e.g. from -100 to 0). The closer the negative value gets to zero, the better the signal. Observing the reported power on a good quality link and a bad one should give an idea about the individual range. <br />
* '''Security:''' it is not reported directly, check the line starting with {{ic|capability}}. If there is {{ic|Privacy}}, for example {{ic|capability: ESS Privacy ShortSlotTime (0x0411)}}, then the network is protected somehow.<br />
** If you see an {{ic|RSN}} information block, then the network is protected by [[Wikipedia:IEEE 802.11i-2004|Robust Security Network]] protocol, also known as WPA2.<br />
** If you see an {{ic|WPA}} information block, then the network is protected by [[Wikipedia:Wi-Fi Protected Access|Wi-Fi Protected Access]] protocol.<br />
** In the {{ic|RSN}} and {{ic|WPA}} blocks you may find the following information:<br />
*** '''Group cipher:''' value in TKIP, CCMP, both, others.<br />
*** '''Pairwise ciphers:''' value in TKIP, CCMP, both, others. Not necessarily the same value than Group cipher.<br />
*** '''Authentication suites:''' value in PSK, 802.1x, others. For home router, you will usually find PSK (''i.e.'' passphrase). In universities, you are more likely to find 802.1x suite which requires login and password. Then you will need to know which key management is in use (e.g. EAP), and what encapsulation it uses (e.g. PEAP). See [[#WPA2 Enterprise]] and [[Wikipedia:Authentication protocol]] for details.<br />
** If you see neither {{ic|RSN}} nor {{ic|WPA}} blocks but there is {{ic|Privacy}}, then WEP is used.<br />
<br />
=== Set operating mode ===<br />
<br />
You might need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an [[Ad-hoc networking|ad-hoc network]], you need to set the operating mode to {{ic|ibss}}:<br />
<br />
# iw dev ''interface'' set type ibss<br />
<br />
{{Note|Changing the operating mode on some cards might require the wireless interface to be ''down'' ({{ic|ip link set ''interface'' down}}).}}<br />
<br />
=== Connect to an access point ===<br />
<br />
Depending on the encryption, you need to associate your wireless device with the access point to use and pass the encryption key:<br />
<br />
* '''No encryption''' {{bc|# iw dev ''interface'' connect "''your_essid''"}}<br />
* '''WEP'''<br />
** using a hexadecimal or ASCII key (the format is distinguished automatically, because a WEP key has a fixed length): {{bc|# iw dev ''interface'' connect "''your_essid''" key 0:''your_key''}}<br />
** using a hexadecimal or ASCII key, specifying the third set up key as default (keys are counted from zero, four are possible): {{bc|# iw dev ''interface'' connect "''your_essid''" key d:2:''your_key''}}<br />
<br />
Regardless of the method used, you can check if you have associated successfully:<br />
<br />
# iw dev ''interface'' link<br />
<br />
== WPA2 Personal ==<br />
<br />
{{Remove|Duplicates [[WPA supplicant]].}}<br />
<br />
To connect to a WPA2 Personal mode wireless router from the command line, you will need to use [[WPA Supplicant]]. This method is particularly suitable for installing from the Arch linux ISO over wireless. All necessary commands are already included in the live session.<br />
<br />
First, encrypt the passphrase for your router:<br />
<br />
# wpa_passphrase ''my_essid'' ''my_passphrase'' > /etc/wpa_supplicant/''my_essid.conf''<br />
<br />
Before running wpa_supplicant in the background, test to make sure you get a connection:<br />
<br />
# wpa_supplicant -c /etc/wpa_supplicant/''my_essid.conf'' -i ''my_wireless_device''<br />
<br />
You might get some errors, but should see a "connected" message at the end. If so, <Ctrl>-c, and run wpa_supplicant in the background:<br />
<br />
# wpa_supplicant -B -c /etc/wpa_supplicant/''my_essid.conf'' -i ''my_wireless_device''<br />
<br />
You will still need to assign an IP address. If using DHCP:<br />
<br />
# dhclient ''my_wireless_device''<br />
<br />
That's it. Wireless networking should now be fully functional.<br />
<br />
== WPA2 Enterprise ==<br />
<br />
''WPA2 Enterprise'' is a mode of [[Wikipedia:Wi-Fi_Protected_Access|Wi-Fi Protected Access]]. It provides better security and key management than ''WPA2 Personal'', and supports other enterprise-type functionality, such as VLANs and [[wikipedia:Network Access Protection|NAP]]. However, it requires an external authentication server, called [[wikipedia:RADIUS|RADIUS]] server to handle the authentication of users. This is in contrast to Personal mode which does not require anything beyond the wireless router or access points (APs), and uses a single passphrase or password for all users.<br />
<br />
The Enterprise mode enables users to log onto the Wi-Fi network with a username and password and/or a digital certificate. Since each user has a dynamic and unique encryption key, it also helps to prevent user-to-user snooping on the wireless network, and improves encryption strength.<br />
<br />
This section describes the configuration of [[List of applications#Network managers|network clients]] to connect to a wireless access point with WPA2 Enterprise mode. See [[Software access point#RADIUS]] for information on setting up an access point itself. <br />
<br />
{{Note|Enterprise mode requires a more complex client configuration, whereas Personal mode only requires entering a passphrase when prompted. Clients likely need to install the server’s CA certificate (plus per-user certificates if using EAP-TLS), and then manually configure the wireless security and 802.1X authentication settings.}}<br />
<br />
For a comparison of protocols see the following [http://deployingradius.com/documents/protocols/compatibility.html table].<br />
<br />
{{Warning|It is possible to use WPA2 Enterprise without the client checking the server CA certificate. However, you should always seek to do so, because without authenticating the access point the connection can be subject to a man-in-the-middle attack. This may happen because while the connection handshake itself may be encrypted, the most widely used setups transmit the password itself either in plain text or the easily breakable [[#MS-CHAPv2]]. Hence, the client might send the password to a malicious access point which then proxies the connection.}}<br />
<br />
=== eduroam ===<br />
<br />
[[Wikipedia:eduroam|eduroam]] is an international roaming service for users in research, higher education and further education, based on WPA2 Enterprise.<br />
<br />
{{Note|<br />
* Check connection details '''first''' with your institution before applying any profiles listed in this section. Example profiles are not guaranteed to work or match any security requirements.<br />
* When storing connection profiles unencrypted, it is recommended restrict read access to the root account by specifying {{ic|chmod 600 ''profile''}} as root.<br />
}}<br />
<br />
{{Tip|Configuration for [[NetworkManager]] and [[#wpa_supplicant]] can be generated with the [https://cat.eduroam.org/ eduroam Configuration Assistant Tool].}}<br />
<br />
=== Manual/automatic setup ===<br />
<br />
==== wpa_supplicant ====<br />
<br />
[[WPA supplicant#Advanced usage|WPA supplicant]] can be configured directly by its configuration file or using its CLI/GUI front ends and used in combination with a DHCP client. See the examples in {{ic|/usr/share/doc/wpa_supplicant/wpa_supplicant.conf}} for configuring the connection details.<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] can generate WPA2 Enterprise profiles with [[NetworkManager#Front-ends|graphical front ends]]. ''nmcli'' and ''nmtui'' do not support this, but may use existing profiles.<br />
<br />
==== connman ====<br />
<br />
[[ConnMan]] needs a separate configuration file before [[ConnMan#Wi-Fi|connecting]] to the network. See {{man|5|connman-service.config}} and [[ConnMan#Connecting_to_eduroam_.28802.1X.29|Connman#Connecting to eduroam]] for details.<br />
<br />
==== netctl ====<br />
<br />
[[netctl]] supports [[#wpa_supplicant]] configuration through blocks included with {{ic|1=WPAConfigSection=}}. See {{man|5|netctl.profile}} for details.<br />
<br />
{{Warning|Special quoting rules apply: see the {{ic|''SPECIAL QUOTING RULES''}} section in {{man|5|netctl.profile}}.}}<br />
<br />
{{Tip|Custom certificates can be specified by adding the line {{ic|1='ca_cert="/path/to/special/certificate.cer"'}} in {{ic|WPAConfigSection}}.}}<br />
<br />
=== Troubleshooting ===<br />
<br />
==== MS-CHAPv2 ====<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require {{Pkg|pptpclient}} in addition to the stock {{Pkg|ppp}} package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option. See also [https://www.cloudcracker.com/blog/2012/07/29/cracking-ms-chap-v2/] and [http://research.edm.uhasselt.be/~bbonne/docs/robyns14wpa2enterprise.pdf].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Respecting the regulatory domain ===<br />
<br />
The [[wikipedia:IEEE_802.11#Regulatory_domains_and_legal_compliance|regulatory domain]], or "regdomain", is used to reconfigure wireless drivers to make sure that wireless hardware usage complies with local laws set by the FCC, ETSI and other organizations. Regdomains use [[wikipedia:ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]]. For example, the regdomain of the United States would be "US", China would be "CN", etc.<br />
<br />
Regdomains affect the availability of wireless channels. In the 2.4GHz band, the allowed channels are 1-11 for the US, 1-14 for Japan, and 1-13 for most of the rest of the world. In the 5GHz band, the rules for allowed channels are much more complex. In either case, consult [[wikipedia:List_of_WLAN_channels|this list of WLAN channels]] for more detailed information.<br />
<br />
Regdomains also affect the limit on the [[wikipedia:Equivalent_isotropically_radiated_power|effective isotropic radiated power (EIRP)]] from wireless devices. This is derived from transmit power/"tx power", and is measured in [[wikipedia:DBm|dBm/mBm (1dBm=100mBm) or mW (log scale)]]. In the 2.4GHz band, the maximum is 30dBm in the US and Canada, 20dBm in most of Europe, and 20dB-30dBm for the rest of the world. In the 5GHz band, maximums are usually lower. Consult the [http://git.kernel.org/cgit/linux/kernel/git/linville/wireless-regdb.git/tree/db.txt wireless-regdb] for more detailed information (EIRP dBm values are in the second set of brackets for each line).<br />
<br />
Misconfiguring the regdomain can be useful - for example, by allowing use of an unused channel when other channels are crowded, or by allowing an increase in tx power to widen transmitter range. However, '''this is not recommended''' as it could break local laws and cause interference with other radio devices.<br />
<br />
To configure the regdomain, install {{Pkg|crda}} and reboot (to reload the {{ic|cfg80211}} module and all related drivers). Check the boot log to make sure that CRDA is being called by {{ic|cfg80211}}:<br />
<br />
$ dmesg | grep cfg80211<br />
<br />
The current regdomain can be set to the United States with:<br />
<br />
# iw reg set US<br />
<br />
And queried with:<br />
<br />
$ iw reg get<br />
<br />
{{Note|Your device may be set to country "00", which is the "world regulatory domain" and contains generic settings. If this cannot be unset, CRDA may be misconfigured.}}<br />
<br />
However, setting the regdomain may not alter your settings. Some devices have a regdomain set in firmware/EEPROM, which dictates the limits of the device, meaning that setting regdomain in software [http://wiki.openwrt.org/doc/howto/wireless.utilities#iw can only increase restrictions], not decrease them. For example, a CN device could be set in software to the US regdomain, but because CN has an EIRP maximum of 20dBm, the device will not be able to transmit at the US maximum of 30dBm.<br />
<br />
For example, to see if the regdomain is being set in firmware for an Atheros device:<br />
<br />
$ dmesg | grep ath:<br />
<br />
For other chipsets, it may help to search for "EEPROM", "regdomain", or simply the name of the device driver.<br />
<br />
To see if your regdomain change has been successful, and to query the number of available channels and their allowed transmit power:<br />
<br />
$ iw list | grep -A 15 Frequencies:<br />
<br />
A more permanent configuration of the regdomain can be achieved through editing {{ic|/etc/conf.d/wireless-regdom}} and uncommenting the appropriate domain.<br />
<br />
[[WPA supplicant]] can also use a regdomain in the {{ic|1=country=}} line of {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.<br />
<br />
It is also possible to configure the [http://wireless.kernel.org/en/developers/Documentation/cfg80211 cfg80211] kernel module to use a specific regdomain by adding, for example, {{ic|1=options cfg80211 ieee80211_regdom=EU}} as [[Kernel_modules#Setting module options|module options]]. However, this is part of the [http://wireless.kernel.org/en/developers/Regulatory#The_ieee80211_regdom_module_parameter old regulatory implementation].<br />
<br />
For further information, read the [http://wireless.kernel.org/en/developers/Regulatory/ wireless.kernel.org regulatory documentation].<br />
<br />
== Troubleshooting ==<br />
<br />
This section contains general troubleshooting tips, not strictly related to problems with drivers or firmware. For such topics, see next section [[#Troubleshooting drivers and firmware]].<br />
<br />
=== Temporary internet access ===<br />
<br />
If you have problematic hardware and need internet access to, for example, download some software or get help in forums, you can make use of Android's built-in feature for internet sharing via USB cable. See [[Android tethering#USB tethering]] for more information.<br />
<br />
=== Rfkill caveat ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by kernel. This can be handled by ''rfkill''. To show the current status:<br />
<br />
{{hc|# rfkill list|<br />
0: phy0: Wireless LAN<br />
Soft blocked: yes<br />
Hard blocked: yes<br />
}}<br />
<br />
If the card is ''hard-blocked'', use the hardware button (switch) to unblock it. If the card is not ''hard-blocked'' but ''soft-blocked'', use the following command:<br />
<br />
# rfkill unblock wifi<br />
<br />
{{Note|It is possible that the card will go from ''hard-blocked'' and ''soft-unblocked'' state into ''hard-unblocked'' and ''soft-blocked'' state by pressing the hardware button (i.e. the ''soft-blocked'' bit is just switched no matter what). This can be adjusted by tuning some options of the {{ic|rfkill}} [[kernel module]].}}<br />
<br />
Hardware buttons to toggle wireless cards are handled by a vendor specific [[kernel module]], frequently these are [https://lwn.net/Articles/391230/ WMI] modules. Particularly for very new hardware models, it happens that the model is not fully supported in the latest stable kernel yet. In this case it often helps to search the kernel bug tracker for information and report the model to the maintainer of the respective vendor kernel module, if it has not happened already. <br />
<br />
See also [http://askubuntu.com/questions/62166/siocsifflags-operation-not-possible-due-to-rf-kill].<br />
<br />
=== Observing Logs ===<br />
<br />
A good first measure to troubleshoot is to analyze the system's logfiles first. In order not to manually parse through them all, it can help to open a second terminal/console window and watch the kernels messages with <br />
$ dmesg -w<br />
while performing the action, e.g. the wireless association attempt. <br />
<br />
When using a tool for network management, the same can be done for systemd with <br />
# journalctl -f <br />
<br />
Frequently a wireless error is accompanied by a deauthentication with a particular reason code, for example: <br />
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)<br />
<br />
Looking up [http://www.aboutcher.co.uk/2012/07/linux-wifi-deauthenticated-reason-codes/ the reason code] might give a first hint. Maybe it also helps you to look at the control message [https://wireless.wiki.kernel.org/en/developers/documentation/mac80211/auth-assoc-deauth flowchart], the journal messages will follow it. <br />
<br />
The individual tools used in this article further provide options for more detailed debugging output, which can be used in a second step of the analysis, if required.<br />
<br />
=== Power saving ===<br />
<br />
See [[Power saving#Network interfaces]].<br />
<br />
=== Failed to get IP address ===<br />
<br />
* If getting an IP address repeatedly fails using the default {{Pkg|dhcpcd}} client, try installing and using {{Pkg|dhclient}} instead. Do not forget to select ''dhclient'' as the primary DHCP client in the [[#Manual/automatic setup|connection manager]].<br />
<br />
* If you can get an IP address for a wired interface and not for a wireless interface, try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
* If you get a timeout error due to a ''waiting for carrier'' problem, then you might have to set the channel mode to {{ic|auto}} for the specific device:<br />
<br />
# iwconfig wlan0 channel auto<br />
<br />
Before changing the channel to auto, make sure your wireless interface is down. After it has successfully changed it, you can bring the interface up again and continue from there.<br />
<br />
=== Valid IP address but cannot resolve host ===<br />
<br />
If you are on a public wireless network that may have a [[wikipedia:Captive_portal|captive portal]], make sure to query an HTTP page (not an HTTPS page) from your web browser, as some captive portals only redirect HTTP.<br />
If this is not the issue, [[check if you can resolve domain names]], it may be necessary to use the DNS server advertised via DHCP.<br />
<br />
=== Setting RTS and fragmentation thresholds ===<br />
<br />
Wireless hardware disables RTS and fragmentation by default. These are two different methods of increasing throughput at the expense of bandwidth (i.e. reliability at the expense of speed). These are useful in environments with wireless noise or many adjacent access points, which may create interference leading to timeouts or failing connections. <br />
<br />
Packet fragmentation improves throughput by splitting up packets with size exceeding the fragmentation threshold. The maximum value (2346) effectively disables fragmentation since no packet can exceed it. The minimum value (256) maximizes throughput, but may carry a significant bandwidth cost.<br />
<br />
# iw phy0 set frag 512<br />
<br />
[[Wikipedia:IEEE 802.11 RTS/CTS|RTS]] improves throughput by performing a handshake with the access point before transmitting packets with size exceeding the RTS threshold. The maximum threshold (2347) effectively disables RTS since no packet can exceed it. The minimum threshold (0) enables RTS for all packets, which is probably excessive for most situations.<br />
<br />
# iw phy0 set rts 500<br />
<br />
{{Note|{{ic|phy0}} is the name of the wireless device as listed by {{ic|$ iw phy}}.}}<br />
<br />
=== Random disconnections ===<br />
<br />
==== Cause #1 ====<br />
<br />
If dmesg says {{ic|1=wlan0: deauthenticating from MAC by local choice (reason=3)}} and you lose your Wi-Fi connection, it is likely that you have a bit too aggressive power-saving on your Wi-Fi card[http://us.generation-nt.com/answer/gentoo-user-wireless-deauthenticating-by-local-choice-help-204640041.html]. Try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
If your card does not support enabling/disabling power save mode, check the BIOS for power management options. Disabling PCI-Express power management in the BIOS of a Lenovo W520 resolved this issue.<br />
<br />
==== Cause #2 ====<br />
<br />
If you are experiencing frequent disconnections and dmesg shows messages such as <br />
<br />
{{ic|1=ieee80211 phy0: wlan0: No probe response from AP xx:xx:xx:xx:xx:xx after 500ms, disconnecting}}<br />
<br />
try changing the channel bandwidth to {{ic|20MHz}} through your router's settings page.<br />
<br />
==== Cause #3 ====<br />
<br />
On some laptop models with hardware rfkill switches (e.g., Thinkpad X200 series), due to wear or bad design, the switch (or its connection to the mainboard) might become loose over time resulting in seemingly random hardblocks/disconnects when you accidentally touch the switch or move the laptop.<br />
There is no software solution to this, unless your switch is electrical and the BIOS offers the option to disable the switch.<br />
If your switch is mechanical (most are), there are lots of possible solutions, most of which aim to disable the switch: Soldering the contact point on the mainboard/wifi-card, glueing or blocking the switch, using a screw nut to tighten the switch or removing it altogether.<br />
<br />
==== Cause #4 ====<br />
<br />
Another cause for frequent disconnects or a complete failure to connect may also be a sub-standard router, incomplete settings of the router, or interference by other wireless devices. <br />
<br />
To troubleshoot, first best try to connect to the router with no authentication. <br />
<br />
If that works, enable WPA/WPA2 again but choose fixed and/or limited router settings. For example: <br />
* If the router is considerably older than the wireless device you use for the client, test if it works with setting the router to one wireless mode <br />
* Disable mixed-mode authentication (e.g. only WPA2 with AES, or TKIP if the router is old) <br />
* Try a fixed/free channel rather than "auto" channel (maybe the router next door is old and interfering) <br />
* Disable [[Wikipedia:Wi-Fi Protected Setup|WPS]]<br />
* Disable {{ic|40Mhz}} channel bandwidth (lower throughput but less likely collisions) <br />
* If the router has quality of service settings, check completeness of settings (e.g. Wi-Fi Multimedia (WMM) is part of optional QoS flow control. An erroneous router firmware may advertise its existence although the setting is not enabled)<br />
<br />
=== Wi-Fi networks invisible because of incorrect regulatory domain===<br />
<br />
If the computer's Wi-Fi channels do not match those of the user's country, that may result in some in-range Wi-Fi networks becoming invisible, because they use wireless channels that aren't allowed by default. The solution is to configure the regulatory domain correctly, see [[#Respecting the regulatory domain]].<br />
<br />
== Troubleshooting drivers and firmware ==<br />
<br />
This section covers methods and procedures for installing kernel modules and ''firmware'' for specific chipsets, that differ from generic method.<br />
<br />
See [[Kernel modules]] for general information on operations with modules.<br />
<br />
=== Ralink/Mediatek ===<br />
<br />
==== rt2x00 ====<br />
<br />
Unified driver for Ralink chipsets (it replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, you only need to load the right module for the chip: {{ic|rt2400pci}}, {{ic|rt2500pci}}, {{ic|rt2500usb}}, {{ic|rt61pci}} or {{ic|rt73usb}} which will autoload the respective {{ic|rt2x00}} modules too.<br />
<br />
A list of devices supported by the modules is available at the project's [https://web.archive.org/web/20150507023412/http://rt2x00.serialmonkey.com/wiki/index.php/Hardware homepage].<br />
<br />
; Additional notes<br />
* Since kernel 3.0, rt2x00 includes also these drivers: {{ic|rt2800pci}}, {{ic|rt2800usb}}.<br />
* Since kernel 3.0, the staging drivers {{ic|rt2860sta}} and {{ic|rt2870sta}} are replaced by the mainline drivers {{ic|rt2800pci}} and {{ic|rt2800usb}}<sup>[https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3]</sup>.<br />
* Some devices have a wide range of options that can be configured with {{ic|iwpriv}}. These are documented in the [http://web.ralinktech.com/ralink/Home/Support/Linux.html source tarballs]{{Dead link|2018|08|15}} available from Ralink.<br />
<br />
==== rt3090 ====<br />
<br />
For devices which are using the rt3090 chipset it should be possible to use {{ic|rt2800pci}} driver, however, is not working with this chipset very well (e.g. sometimes it is not possible to use higher rate than 2Mb/s).<br />
<br />
==== rt3290 ====<br />
<br />
The rt3290 chipset is recognised by the kernel {{ic|rt2800pci}} module. However, some users experience problems and reverting to a patched Ralink driver seems to be beneficial in these [https://bbs.archlinux.org/viewtopic.php?id=161952 cases].<br />
<br />
==== rt3573 ====<br />
<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it, see the [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 DB wireless usb adapter] forums thread.<br />
<br />
==== rt5572 ====<br />
<br />
New chipset as of 2012 with support for 5 Ghz bands. It may require proprietary drivers from Ralink and some effort to compile them. At the time of writing a how-to on compilation is available for a DLINK DWA-160 rev. B2 [http://bernaerts.dyndns.org/linux/229-ubuntu-precise-dlink-dwa160-revb2 here].<br />
<br />
==== mt7612u ====<br />
<br />
New chipset as of 2014, released under their new commercial name Mediatek. It is an AC1200 or AC1300 chipset. Manufacturer provides drivers for Linux on their [https://www.mediatek.com/products/broadbandWifi/mt7612u support page]<br />
<br />
=== Realtek ===<br />
<br />
See [https://wikidevi.com/wiki/Realtek] for a list of Realtek chipsets and specifications.<br />
<br />
==== rtl8192cu ====<br />
<br />
The driver is now in the kernel, but many users have reported being unable to make a connection although scanning for networks does work.<br />
<br />
{{AUR|8192cu-dkms}} includes many patches, try this if it does not work fine with the driver in kernel.<br />
<br />
==== rtl8723ae/rtl8723be ====<br />
<br />
The {{ic|rtl8723ae}} and {{ic|rtl8723be}} modules are included in the mainline Linux kernel.<br />
<br />
Some users may encounter errors with powersave on this card. This is shown with occasional disconnects that are not recognized by high level network managers ([[netctl]], [[NetworkManager]]). This error can be confirmed by running {{ic|dmesg -w}} or {{ic|journalctl -f}} and looking for output related to powersave and the {{ic|rtl8723ae}}/{{ic|rtl8723be}} module. If you are having this issue, use the {{ic|1=fwlps=0}} kernel option, which should prevent the WiFi card from automatically sleeping and halting connection.<br />
<br />
{{hc|/etc/modprobe.d/rtl8723ae.conf|2=<br />
options rtl8723ae fwlps=0<br />
}}<br />
or<br />
{{hc|/etc/modprobe.d/rtl8723be.conf|2=<br />
options rtl8723be fwlps=0<br />
}}<br />
<br />
If you have poor signal, perhaps your device has only one physical antenna connected, and antenna autoselection is broken. You can force the choice of antenna with {{ic|1=ant_sel=1}} or {{ic|1=ant_sel=2}} kernel option. [https://bbs.archlinux.org/viewtopic.php?id=208472]<br />
<br />
==== rtl88xxau ====<br />
<br />
Realtek chipsets rtl8811au/rtl8812au/rtl8814au/rtl8821au designed for various USB adapters ranging from AC600 to AC1900.<br />
<br />
Several packages provide the kernel drivers:<br />
<br />
{| class="wikitable"<br />
! Chipset || Driver version || Package || Notes<br />
|-<br />
| rtl8811au, rtl8812au, rtl8814au and rtl8821au || 5.2.20 (possibility of using 5.3.4 base)|| {{AUR|rtl88xxau-aircrack-dkms-git}} || Aircrack-ng kernel module for 8811au, 8812au, 8814au and 8821au chipsets with monitor mode and injection support. Possibility to use experimental v5.3.4 of the driver by editing PKGBUILD file.<br />
|-<br />
| rtl8812au || 5.2.20 || {{AUR|rtl8812au-dkms-git}} || Latest official Realtek driver version for rtl8812au ''only''.<br />
|-<br />
| rtl8811au, rtl8812au and rtl8821au || 5.1.5 || {{AUR|rtl8821au-dkms-git}} || For rtl8812au the latest version 5.2.20 is recommended instead.<br />
|-<br />
| rtl8814au || 4.3.21 || {{AUR|rtl8814au-dkms-git}} || Possibly works for rtl8813au too.<br />
|}<br />
<br />
These require [[DKMS]] so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8822bu ====<br />
<br />
{{AUR|rtl8822bu-dkms-git}} provides a kernel module for the Realtek 8822bu chipset found in the Edimax EW7822ULC USB3 and Asus AC53 Nano USB 802.11ac adapter.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8xxxu ====<br />
<br />
{{Expansion|Specific issues with the mainline module and kernel versions should be stated.}}<br />
<br />
Issues with the {{ic|rtl8xxxu}} mainline kernel module may be solved by compiling a third-party module for the specific chipset. The source code can be found in [https://github.com/lwfinger?tab=repositories GitHub repositories].<br />
<br />
Some drivers may be already prepared in the AUR, e.g. {{AUR|rtl8723bu-git}} and {{AUR|rtl8723bu-git-dkms}}.<br />
<br />
=== Atheros ===<br />
<br />
The [http://madwifi-project.org/ MadWifi team] currently maintains three different drivers for devices with Atheros chipset:<br />
<br />
* {{ic|madwifi}} is an old, obsolete driver. Not present in Arch kernel since 2.6.39.1<sup>[https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html]</sup>.<br />
* {{ic|ath5k}} is newer driver, which replaces the {{ic|madwifi}} driver. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* {{ic|ath9k}} is the newest of these three drivers, it is intended for newer Atheros chipsets. All of the chips with 802.11n capabilities are supported.<br />
<br />
There are some other drivers for some Atheros devices. See [http://wireless.kernel.org/en/users/Drivers/Atheros#PCI_.2F_PCI-E_.2F_AHB_Drivers Linux Wireless documentation] for details.<br />
<br />
==== ath5k ====<br />
<br />
External resources:<br />
* http://wireless.kernel.org/en/users/Drivers/ath5k<br />
* http://wiki.debian.org/ath5k<br />
<br />
If you find web pages randomly loading very slow, or if the device is unable to lease an IP address, try to switch from hardware to software encryption by loading the {{ic|ath5k}} module with {{ic|1=nohwcrypt=1}} option. See [[Kernel modules#Setting module options]] for details.<br />
<br />
Some laptops may have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
<br />
# echo none > /sys/class/leds/ath5k-phy0::tx/trigger<br />
# echo none > /sys/class/leds/ath5k-phy0::rx/trigger<br />
<br />
For alternatives, see [https://bugzilla.redhat.com/show_bug.cgi?id=618232 this bug report].<br />
<br />
==== ath9k ====<br />
<br />
External resources:<br />
* http://wireless.kernel.org/en/users/Drivers/ath9k<br />
* http://wiki.debian.org/ath9k<br />
<br />
As of Linux 3.15.1, some users have been experiencing a decrease in bandwidth. In some cases this can fixed by editing {{ic|/etc/modprobe.d/ath9k.conf}} and adding the line:<br />
options ath9k nohwcrypt=1<br />
<br />
{{Note|Check with the command lsmod what module(-name) is in use and change it if named otherwise (e.g. ath9k_htc).}}<br />
<br />
In the unlikely event that you have stability issues that trouble you, you could try using the {{AUR|backports-patched}} package. An [https://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list] exists for support and development related discussions.<br />
<br />
===== Power saving =====<br />
<br />
Although [http://wireless.kernel.org/en/users/Documentation/dynamic-power-save Linux Wireless] says that dynamic power saving is enabled for Atheros ath9k single-chips newer than AR9280, for some devices (e.g. AR9285) {{Pkg|powertop}} might still report that power saving is disabled. In this case enable it manually.<br />
<br />
On some devices (e.g. AR9285), enabling the power saving might result in the following error:<br />
<br />
{{hc|# iw dev wlan0 set power_save on|<br />
command failed: Operation not supported (-95)<br />
}}<br />
<br />
The solution is to set the {{ic|1=ps_enable=1}} option for the {{ic|ath9k}} module:<br />
<br />
{{hc|/etc/modprobe.d/ath9k.conf|2=<br />
options ath9k ps_enable=1<br />
}}<br />
<br />
=== Intel ===<br />
<br />
==== ipw2100 and ipw2200 ====<br />
<br />
These modules are fully supported in the kernel, but they require additional firmware. Depending on which of the chipsets you have, [[install]] either {{Pkg|ipw2100-fw}} or {{Pkg|ipw2200-fw}}. Then [[Kernel modules#Manual module handling|reload]] the appropriate module.<br />
<br />
{{Tip|You may use the following [[Kernel modules#Setting module options|module options]]:<br />
* use the {{ic|1=rtap_iface=1}} option to enable the radiotap interface<br />
* use the {{ic|1=led=1}} option to enable a front LED indicating when the wireless is connected or not<br />
}}<br />
<br />
==== iwlegacy ====<br />
<br />
[http://wireless.kernel.org/en/users/Drivers/iwlegacy iwlegacy] is the wireless driver for Intel's 3945 and 4965 wireless chips. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
[[udev]] should load the driver automatically, otherwise load {{ic|iwl3945}} or {{ic|iwl4965}} manually. See [[Kernel modules]] for details.<br />
<br />
If you have problems connecting to networks in general, random failures with your card on bootup or your link quality is very poor, try to disable 802.11n:<br />
<br />
{{hc|/etc/modprobe.d/iwl4965.conf|2=<br />
options iwl4965 11n_disable=1<br />
}}<br />
<br />
If the failures persist during bootup and you are using Nouveau driver, try [[Nouveau#Enable_early_KMS|enabling early KMS]] to prevent the conflict [https://bbs.archlinux.org/viewtopic.php?pid=1748667#p1748667].<br />
<br />
==== iwlwifi ====<br />
<br />
[http://wireless.kernel.org/en/users/Drivers/iwlwifi iwlwifi] is the wireless driver for Intel's current wireless chips, such as 5100AGN, 5300AGN, and 5350AGN. See the [http://wireless.kernel.org/en/users/Drivers/iwlwifi#Supported_Devices full list of supported devices]. The firmware is included in the {{Pkg|linux-firmware}} package. The {{Aur|linux-firmware-iwlwifi-git}} may contain some updates sooner.<br />
<br />
If you have problems connecting to networks in general or your link quality is very poor, try to disable 802.11n, and perhaps also enable software encryption:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=1 swcrypto=1<br />
}}<br />
<br />
If you have a problem with slow uplink speed in 802.11n mode, for example 20Mbps, try to enable antenna aggregation:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=8<br />
}}<br />
<br />
Do not be confused with the option name, when the value is set to {{ic|8}} it does not disable anything but re-enables transmission antenna aggregation.[http://forums.gentoo.org/viewtopic-t-996692.html?sid=81bdfa435c089360bdfd9368fe0339a9] [https://bugzilla.kernel.org/show_bug.cgi?id=81571]<br />
<br />
In case this does not work for you, you may try disabling [[Power saving#Network interfaces|power saving]] for your wireless adapter.<br />
<br />
[http://ubuntuforums.org/showthread.php?t=2183486&p=12845473#post12845473 Some] have never gotten this to work. [http://ubuntuforums.org/showthread.php?t=2205733&p=12935783#post12935783 Others] found salvation by disabling N in their router settings after trying everything. This is known to have be the only solution on more than one occasion. The second link there mentions a 5ghz option that might be worth exploring.<br />
<br />
===== Bluetooth coexistence =====<br />
<br />
If you have difficulty connecting a bluetooth headset and maintaining good downlink speed, try disabling bluetooth coexistence [https://wireless.wiki.kernel.org/en/users/Drivers/iwlwifi#wifibluetooth_coexistence]:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi bt_coex_active=0<br />
}}<br />
<br />
==== Disabling LED blink ====<br />
<br />
{{Note|This works with the {{ic|iwlegacy}} and {{ic|iwlwifi}} drivers.}}<br />
<br />
The default settings on the module are to have the LED blink on activity. Some people find this extremely annoying. To have the LED on solid when Wi-Fi is active, you can use the [[systemd#Temporary files|systemd-tmpfiles]]:<br />
<br />
{{hc|/etc/tmpfiles.d/phy0-led.conf|<br />
w /sys/class/leds/phy0-led/trigger - - - - phy0radio<br />
}}<br />
<br />
Run {{ic|systemd-tmpfiles --create phy0-led.conf}} for the change to take effect, or reboot.<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
{{Tip|If you do not have {{ic|/sys/class/leds/phy0-led}}, you may try to use the {{ic|1=led_mode="1"}} [[Kernel modules#Setting module options|module option]]. It should be valid for both {{ic|iwlwifi}} and {{ic|iwlegacy}} drivers.}}<br />
<br />
=== Broadcom ===<br />
<br />
See [[Broadcom wireless]].<br />
<br />
=== Other drivers/devices ===<br />
<br />
==== Tenda w322u ====<br />
<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See [[#rt2x00]].<br />
<br />
==== orinoco ====<br />
<br />
This should be a part of the kernel package and be installed already.<br />
<br />
Some Orinoco chipsets are Hermes II. You can use the {{ic|wlags49_h2_cs}} driver instead of {{ic|orinoco_cs}} and gain WPA support. To use the driver, [[blacklist]] {{ic|orinoco_cs}} first.<br />
<br />
==== prism54 ====<br />
<br />
The driver {{ic|p54}} is included in kernel, but you have to download the appropriate firmware for your card from [http://linuxwireless.org/en/users/Drivers/p54#firmware this site] and install it into the {{ic|/usr/lib/firmware}} directory.<br />
<br />
{{Note|There is also older, deprecated driver {{ic|prism54}}, which might conflict with the newer driver ({{ic|p54pci}} or {{ic|p54usb}}). Make sure to [[blacklist]] {{ic|prism54}}.}}<br />
<br />
==== ACX100/111 ====<br />
<br />
{{Warning|The drivers for these devices [https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html are broken] and do not work with newer kernel versions.}}<br />
<br />
Packages: {{ic|tiacx}} {{ic|tiacx-firmware}} (deleted from official repositories and AUR)<br />
<br />
See [http://sourceforge.net/apps/mediawiki/acx100/index.php?title=Main_Page official wiki]{{dead link|2018|09|23}} for details.<br />
<br />
==== zd1211rw ====<br />
<br />
[http://zd1211.wiki.sourceforge.net/ {{ic|zd1211rw}}] is a driver for the ZyDAS ZD1211 802.11b/g USB WLAN chipset, and it is included in recent versions of the Linux kernel. See [http://www.linuxwireless.org/en/users/Drivers/zd1211rw/devices] for a list of supported devices. You only need to [[install]] the firmware for the device, provided by the {{AUR|zd1211-firmware}} package.<br />
<br />
==== hostap_cs ====<br />
<br />
[http://hostap.epitest.fi/ Host AP] is a Linux driver for wireless LAN cards based on Intersil's Prism2/2.5/3 chipset. The driver is included in Linux kernel.<br />
<br />
{{Note|Make sure to [[blacklist]] the {{ic|orinico_cs}} driver, it may cause problems.}}<br />
<br />
=== ndiswrapper ===<br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. You will need the {{ic|.inf}} and {{ic|.sys}} files from your Windows driver. <br />
{{Warning|Be sure to use drivers appropriate to your architecture (x86 vs. x86_64).}}<br />
<br />
{{Tip|If you need to extract these files from an {{ic|*.exe}} file, you can use {{Pkg|cabextract}}.}}<br />
<br />
Follow these steps to configure ndiswrapper.<br />
<br />
1. Install {{pkg|ndiswrapper-dkms}}<br />
<br />
2. Install the driver to {{ic|/etc/ndiswrapper/*}}<br />
# ndiswrapper -i filename.inf<br />
<br />
3. List all installed drivers for ndiswrapper<br />
$ ndiswrapper -l<br />
<br />
4. Let ndiswrapper write its configuration in {{ic|/etc/modprobe.d/ndiswrapper.conf}}:<br />
# ndiswrapper -m<br />
# depmod -a<br />
<br />
Now the ndiswrapper install is almost finished; follow the instructions on [[Kernel modules#Automatic module loading with systemd]] to automatically load the module at boot.<br />
<br />
The important part is making sure that ndiswrapper exists on this line, so just add it alongside the other modules. It would be best to test that ndiswrapper will load now, so:<br />
# modprobe ndiswrapper<br />
# iwconfig<br />
<br />
and ''wlan0'' should now exist. If you have problems, some help is available at:<br />
[http://sourceforge.net/p/ndiswrapper/ndiswrapper/HowTos/ ndiswrapper howto] and [http://sourceforge.net/p/ndiswrapper/ndiswrapper/FAQ/ ndiswrapper FAQ].<br />
<br />
=== backports-patched ===<br />
<br />
{{AUR|backports-patched}} provide drivers released on newer kernels backported for usage on older kernels. The project started since 2007 and was originally known as compat-wireless, evolved to compat-drivers and was recently renamed simply to backports. <br />
<br />
If you are using old kernel and have wireless issue, drivers in this package may help.<br />
<br />
== See also ==<br />
<br />
* [http://wireless.kernel.org/ The Linux Wireless project]<br />
* [http://aircrack-ng.org/doku.php?id=install_drivers Aircrack-ng guide on installing drivers]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=577381Network configuration/Wireless2019-07-13T16:51:52Z<p>Pgoetz: added comment about included commands</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[cs:Wireless network configuration]]<br />
[[de:(W)LAN und Arch Linux]]<br />
[[el:Wireless network configuration]]<br />
[[es:Wireless network configuration]]<br />
[[fa:تنظیمات شبکه ی بی سیم]]<br />
[[fr:Wifi]]<br />
[[it:Wireless network configuration]]<br />
[[ja:ワイヤレス設定]]<br />
[[nl:Wireless network configuration]]<br />
[[pt:Wireless network configuration]]<br />
[[ru:Wireless network configuration]]<br />
[[th:Wireless network configuration]]<br />
[[zh-hans:Wireless network configuration]]<br />
{{Related articles start}}<br />
{{Related|Software access point}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related|Wireless bonding}}<br />
{{Related|Network Debugging}}<br />
{{Related|Bluetooth}}<br />
{{Related articles end}}<br />
{{Move|Network configuration/Wireless|Page depends on [[Network configuration]].|Talk:Network configuration#Moving Ethernet-specific sections to Wired subpage}}<br />
The main article on network configuration is [[Network configuration]].<br />
<br />
Configuring wireless is a two-part process; the first part is to identify and ensure the correct driver for your wireless device is installed (they are available on the installation media, but often have to be installed explicitly), and to configure the interface. The second is choosing a method of managing wireless connections. This article covers both parts, and provides additional links to wireless management tools.<br />
<br />
The [[#iw]] section describes how to manually manage your wireless network interface / your wireless LANs using {{Pkg|iw}}. The [[Network configuration#Network managers]] section describes several programs that can be used to automatically manage your wireless interface, some of which include a GUI and all of which include support for network profiles (useful when frequently switching wireless networks, like with laptops).<br />
<br />
== Device driver ==<br />
<br />
The default Arch Linux kernel is ''modular'', meaning many of the drivers for machine hardware reside on the hard drive and are available as [[Kernel modules|modules]]. At boot, [[udev]] takes an inventory of your hardware and loads appropriate modules (drivers) for your corresponding hardware, which will in turn allow creation of a network ''interface''.<br />
<br />
Some wireless chipsets also require firmware, in addition to a corresponding driver. Many firmware images are provided by the {{Pkg|linux-firmware}} package which is installed by default, however, proprietary firmware images are not included and have to be installed separately. This is described in [[#Installing driver/firmware]].<br />
<br />
{{Note|If the proper module is not loaded by udev on boot, simply [[Kernel modules#Manual module handling|load it manually]]. If udev loads more than one driver for a device, the resulting conflict may prevent successful configuration. Make sure to [[blacklist]] the unwanted module.}}<br />
<br />
=== Check the driver status ===<br />
<br />
To check if the driver for your card has been loaded, check the output of the {{ic|lspci -k}} or {{ic|lsusb -v}} command, depending on if the card is connected by PCI(e) or USB. You should see that some kernel driver is in use, for example:<br />
<br />
{{hc|$ lspci -k|<nowiki><br />
06:00.0 Network controller: Intel Corporation WiFi Link 5100<br />
Subsystem: Intel Corporation WiFi Link 5100 AGN<br />
Kernel driver in use: iwlwifi<br />
Kernel modules: iwlwifi<br />
</nowiki>}}<br />
<br />
{{Note|If the card is a USB device, running {{ic|dmesg {{!}} grep usbcore}} should give something like {{ic|usbcore: registered new interface driver rtl8187}} as output.}}<br />
<br />
Also check the output of the {{ic|ip link}} command to see if a wireless interface was created; usually the naming of the wireless [[network interfaces]] starts with the letter "w", e.g. {{ic|wlan0}} or {{ic|wlp2s0}}. Then bring the interface up with:<br />
<br />
# ip link set ''interface'' up<br />
<br />
For example, assuming the interface is {{ic|wlan0}}, this is {{ic|ip link set wlan0 up}}.<br />
<br />
If you get the error message {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means that your wireless chipset requires a firmware to function.<br />
<br />
Check kernel messages for firmware being loaded:<br />
<br />
{{hc|<nowiki>$ dmesg | grep firmware</nowiki>|<nowiki><br />
[ 7.148259] iwlwifi 0000:02:00.0: loaded firmware version 39.30.4.1 build 35138 op_mode iwldvm<br />
</nowiki>}}<br />
<br />
If there is no relevant output, check the messages for the full output for the module you identified earlier ({{ic|iwlwifi}} in this example) to identify the relevant message or further issues:<br />
<br />
{{hc|<nowiki>$ dmesg | grep iwlwifi</nowiki>|<nowiki><br />
[ 12.342694] iwlwifi 0000:02:00.0: irq 44 for MSI/MSI-X<br />
[ 12.353466] iwlwifi 0000:02:00.0: loaded firmware version 39.31.5.1 build 35138 op_mode iwldvm<br />
[ 12.430317] iwlwifi 0000:02:00.0: CONFIG_IWLWIFI_DEBUG disabled<br />
...<br />
[ 12.430341] iwlwifi 0000:02:00.0: Detected Intel(R) Corporation WiFi Link 5100 AGN, REV=0x6B<br />
</nowiki>}}<br />
<br />
If the kernel module is successfully loaded and the interface is up, you can skip the next section.<br />
<br />
=== Installing driver/firmware ===<br />
<br />
Check the following lists to discover if your card is supported:<br />
<br />
* See the table of [https://wireless.wiki.kernel.org/en/users/drivers existing Linux wireless drivers] and follow to the specific driver's page, which contains a list of supported devices. There is also a [https://wikidevi.com/wiki/List_of_Wi-Fi_Device_IDs_in_Linux List of Wi-Fi Device IDs in Linux].<br />
* The [https://help.ubuntu.com/community/WifiDocs/WirelessCardsSupported Ubuntu Wiki] has a good list of wireless cards and whether or not they are supported either in the Linux kernel or by a user-space driver (includes driver name).<br />
* [http://linux-wless.passys.nl/ Linux Wireless Support] and The Linux Questions' [http://www.linuxquestions.org/hcl/index.php?cat=10 Hardware Compatibility List] (HCL) also have a good database of kernel-friendly hardware.<br />
<br />
Note that some vendors ship products that may contain different chip sets, even if the product identifier is the same. Only the usb-id (for USB devices) or pci-id (for PCI devices) is authoritative.<br />
<br />
If your wireless card is listed above, follow the [[#Troubleshooting drivers and firmware]] subsection of this page, which contains information about installing drivers and firmware of some specific wireless cards. Then [[#Check the driver status|check the driver status]] again.<br />
<br />
If your wireless card is not listed above, it is likely supported only under Windows (some Broadcom, 3com, etc). For these, you can try to use [[#ndiswrapper]].<br />
<br />
== Utilities ==<br />
<br />
Just like other network interfaces, the wireless ones are controlled with ''ip'' from the {{Pkg|iproute2}} package.<br />
<br />
Managing a wireless connection requires a basic set of tools. Either use a [[network manager]] or use one of the following directly:<br />
<br />
{| class="wikitable"<br />
! Software !! Package !! [https://wireless.wiki.kernel.org/en/developers/documentation/wireless-extensions WEXT] !! [https://wireless.wiki.kernel.org/en/developers/documentation/nl80211 nl80211] !! WEP !! WPA/WPA2 !! [[Archiso]] [https://git.archlinux.org/archiso.git/tree/configs/releng/packages.x86_64]<br />
|-<br />
| [http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html wireless_tools]<sup>1</sup> || {{pkg|wireless_tools}} || {{yes}} || {{no}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [https://wireless.kernel.org/en/users/Documentation/iw iw] || {{Pkg|iw}} || {{No}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [[WPA supplicant]] || {{Pkg|wpa_supplicant}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|-<br />
| [[iwd]] || {{Pkg|iwd}} || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
# Deprecated.<br />
<br />
Note that some cards only support WEXT.<br />
<br />
=== iw and wireless_tools comparison ===<br />
<br />
The table below gives an overview of comparable commands for ''iw'' and ''wireless_tools''. See [http://wireless.kernel.org/en/users/Documentation/iw/replace-iwconfig iw replaces iwconfig] for more examples.<br />
<br />
{| class="wikitable"<br />
! ''iw'' command<br />
! ''wireless_tools'' command<br />
! Description<br />
|-<br />
| iw dev ''wlan0'' link<br />
| iwconfig ''wlan0''<br />
| Getting link status.<br />
|-<br />
| iw dev ''wlan0'' scan<br />
| iwlist ''wlan0'' scan<br />
| Scanning for available access points.<br />
|-<br />
| iw dev ''wlan0'' set type ibss<br />
| iwconfig ''wlan0'' mode ad-hoc<br />
| Setting the operation mode to ''ad-hoc''.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid''<br />
| iwconfig ''wlan0'' essid ''your_essid''<br />
| Connecting to open network.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid'' 2432<br />
| iwconfig ''wlan0'' essid ''your_essid'' freq 2432M<br />
| Connecting to open network specifying channel.<br />
|-<br />
| rowspan="2" | iw dev ''wlan0'' connect ''your_essid'' key 0:''your_key''<br />
| iwconfig ''wlan0'' essid ''your_essid'' key ''your_key''<br />
| Connecting to WEP encrypted network using hexadecimal key.<br />
|-<br />
| iwconfig ''wlan0'' essid ''your_essid'' key s:''your_key''<br />
| Connecting to WEP encrypted network using ASCII key.<br />
|-<br />
| iw dev ''wlan0'' set power_save on<br />
| iwconfig ''wlan0'' power on<br />
| Enabling power save.<br />
|}<br />
<br />
== iw ==<br />
<br />
{{Note|<br />
* Note that most of the commands have to be executed with [[Users and groups|root permissions]]. Executed with normal user rights, some of the commands (e.g. ''iwlist''), will exit without error but not produce the correct output either, which can be confusing.<br />
* Depending on your hardware and encryption type, some of these steps may not be necessary. Some cards are known to require interface activation and/or access point scanning before being associated to an access point and being given an IP address. Some experimentation may be required. For instance, WPA/WPA2 users may try to directly activate their wireless network from step [[#Connect to an access point]].}}<br />
<br />
Examples in this section assume that your wireless device interface is {{ic|''interface''}} and that you are connecting to {{ic|''your_essid''}} wifi access point. Replace both accordingly.<br />
<br />
=== Get the name of the interface ===<br />
<br />
{{Tip|See [http://wireless.kernel.org/en/users/Documentation/iw official documentation] of the ''iw'' tool for more examples.}}<br />
<br />
To get the name of your wireless interface do:<br />
<br />
$ iw dev<br />
<br />
The name of the interface will be output after the word "Interface". For example, it is commonly {{ic|wlan0}}.<br />
<br />
=== Get the status of the interface ===<br />
<br />
To check link status, use following command.<br />
<br />
$ iw dev ''interface'' link<br />
<br />
You can get statistic information, such as the amount of tx/rx bytes, signal strength etc., with following command:<br />
<br />
$ iw dev ''interface'' station dump<br />
<br />
=== Activate the interface ===<br />
<br />
{{Tip|Usually this step is not required.}}<br />
<br />
Some cards require that the kernel interface be activated before you can use ''iw'' or ''wireless_tools'':<br />
<br />
# ip link set ''interface'' up<br />
<br />
{{Note|If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.}}<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|$ ip link show ''interface''|<br />
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 12:34:56:78:9a:bc brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
=== Discover access points ===<br />
<br />
To see what access points are available:<br />
<br />
# iw dev ''interface'' scan | less<br />
<br />
{{Note|If it displays {{ic|Interface does not support scanning}}, then you probably forgot to install the firmware. In some cases this message is also displayed when not running ''iw'' as root.}}<br />
<br />
{{Tip|Depending on your location, you might need to set the correct [[#Respecting the regulatory domain|regulatory domain]] in order to see all available networks.}}<br />
<br />
The important points to check:<br />
* '''SSID:''' the name of the network.<br />
* '''Signal:''' is reported in a wireless power ratio in dBm (e.g. from -100 to 0). The closer the negative value gets to zero, the better the signal. Observing the reported power on a good quality link and a bad one should give an idea about the individual range. <br />
* '''Security:''' it is not reported directly, check the line starting with {{ic|capability}}. If there is {{ic|Privacy}}, for example {{ic|capability: ESS Privacy ShortSlotTime (0x0411)}}, then the network is protected somehow.<br />
** If you see an {{ic|RSN}} information block, then the network is protected by [[Wikipedia:IEEE 802.11i-2004|Robust Security Network]] protocol, also known as WPA2.<br />
** If you see an {{ic|WPA}} information block, then the network is protected by [[Wikipedia:Wi-Fi Protected Access|Wi-Fi Protected Access]] protocol.<br />
** In the {{ic|RSN}} and {{ic|WPA}} blocks you may find the following information:<br />
*** '''Group cipher:''' value in TKIP, CCMP, both, others.<br />
*** '''Pairwise ciphers:''' value in TKIP, CCMP, both, others. Not necessarily the same value than Group cipher.<br />
*** '''Authentication suites:''' value in PSK, 802.1x, others. For home router, you will usually find PSK (''i.e.'' passphrase). In universities, you are more likely to find 802.1x suite which requires login and password. Then you will need to know which key management is in use (e.g. EAP), and what encapsulation it uses (e.g. PEAP). See [[#WPA2 Enterprise]] and [[Wikipedia:Authentication protocol]] for details.<br />
** If you see neither {{ic|RSN}} nor {{ic|WPA}} blocks but there is {{ic|Privacy}}, then WEP is used.<br />
<br />
=== Set operating mode ===<br />
<br />
You might need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an [[Ad-hoc networking|ad-hoc network]], you need to set the operating mode to {{ic|ibss}}:<br />
<br />
# iw dev ''interface'' set type ibss<br />
<br />
{{Note|Changing the operating mode on some cards might require the wireless interface to be ''down'' ({{ic|ip link set ''interface'' down}}).}}<br />
<br />
=== Connect to an access point ===<br />
<br />
Depending on the encryption, you need to associate your wireless device with the access point to use and pass the encryption key:<br />
<br />
* '''No encryption''' {{bc|# iw dev ''interface'' connect "''your_essid''"}}<br />
* '''WEP'''<br />
** using a hexadecimal or ASCII key (the format is distinguished automatically, because a WEP key has a fixed length): {{bc|# iw dev ''interface'' connect "''your_essid''" key 0:''your_key''}}<br />
** using a hexadecimal or ASCII key, specifying the third set up key as default (keys are counted from zero, four are possible): {{bc|# iw dev ''interface'' connect "''your_essid''" key d:2:''your_key''}}<br />
<br />
Regardless of the method used, you can check if you have associated successfully:<br />
<br />
# iw dev ''interface'' link<br />
<br />
== WPA2 Personal ==<br />
<br />
To connect to a WPA2 Personal mode wireless router from the command line, you will need to use wpa_supplicant. This method is particularly suitable for installing from the Arch linux ISO over wireless. All necessary commands are already included in the live session.<br />
<br />
First, encrypt the passphrase for your router:<br />
<br />
# wpa_passphrase ''my_essid'' ''my_passphrase'' > /etc/wpa_supplicant/''my_essid.conf''<br />
<br />
Before running wpa_supplicant in the background, test to make sure you get a connection:<br />
<br />
# wpa_supplicant -c /etc/wpa_supplicant/''my_essid.conf'' -i ''my_wireless_device''<br />
<br />
You might get some errors, but should see a "connected" message at the end. If so, <Ctrl>-c, and run wpa_supplicant in the background:<br />
<br />
# wpa_supplicant -B -c /etc/wpa_supplicant/''my_essid.conf'' -i ''my_wireless_device''<br />
<br />
You will still need to assign an IP address. If using DHCP:<br />
<br />
# dhclient ''my_wireless_device''<br />
<br />
That's it. Wireless networking should now be fully functional.<br />
<br />
== WPA2 Enterprise ==<br />
<br />
''WPA2 Enterprise'' is a mode of [[Wikipedia:Wi-Fi_Protected_Access|Wi-Fi Protected Access]]. It provides better security and key management than ''WPA2 Personal'', and supports other enterprise-type functionality, such as VLANs and [[wikipedia:Network Access Protection|NAP]]. However, it requires an external authentication server, called [[wikipedia:RADIUS|RADIUS]] server to handle the authentication of users. This is in contrast to Personal mode which does not require anything beyond the wireless router or access points (APs), and uses a single passphrase or password for all users.<br />
<br />
The Enterprise mode enables users to log onto the Wi-Fi network with a username and password and/or a digital certificate. Since each user has a dynamic and unique encryption key, it also helps to prevent user-to-user snooping on the wireless network, and improves encryption strength.<br />
<br />
This section describes the configuration of [[List of applications#Network managers|network clients]] to connect to a wireless access point with WPA2 Enterprise mode. See [[Software access point#RADIUS]] for information on setting up an access point itself. <br />
<br />
{{Note|Enterprise mode requires a more complex client configuration, whereas Personal mode only requires entering a passphrase when prompted. Clients likely need to install the server’s CA certificate (plus per-user certificates if using EAP-TLS), and then manually configure the wireless security and 802.1X authentication settings.}}<br />
<br />
For a comparison of protocols see the following [http://deployingradius.com/documents/protocols/compatibility.html table].<br />
<br />
{{Warning|It is possible to use WPA2 Enterprise without the client checking the server CA certificate. However, you should always seek to do so, because without authenticating the access point the connection can be subject to a man-in-the-middle attack. This may happen because while the connection handshake itself may be encrypted, the most widely used setups transmit the password itself either in plain text or the easily breakable [[#MS-CHAPv2]]. Hence, the client might send the password to a malicious access point which then proxies the connection.}}<br />
<br />
=== eduroam ===<br />
<br />
[[Wikipedia:eduroam|eduroam]] is an international roaming service for users in research, higher education and further education, based on WPA2 Enterprise.<br />
<br />
{{Note|<br />
* Check connection details '''first''' with your institution before applying any profiles listed in this section. Example profiles are not guaranteed to work or match any security requirements.<br />
* When storing connection profiles unencrypted, it is recommended restrict read access to the root account by specifying {{ic|chmod 600 ''profile''}} as root.<br />
}}<br />
<br />
{{Tip|Configuration for [[NetworkManager]] and [[#wpa_supplicant]] can be generated with the [https://cat.eduroam.org/ eduroam Configuration Assistant Tool].}}<br />
<br />
=== Manual/automatic setup ===<br />
<br />
==== wpa_supplicant ====<br />
<br />
[[WPA supplicant#Advanced usage|WPA supplicant]] can be configured directly by its configuration file or using its CLI/GUI front ends and used in combination with a DHCP client. See the examples in {{ic|/usr/share/doc/wpa_supplicant/wpa_supplicant.conf}} for configuring the connection details.<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] can generate WPA2 Enterprise profiles with [[NetworkManager#Front-ends|graphical front ends]]. ''nmcli'' and ''nmtui'' do not support this, but may use existing profiles.<br />
<br />
==== connman ====<br />
<br />
[[ConnMan]] needs a separate configuration file before [[ConnMan#Wi-Fi|connecting]] to the network. See {{man|5|connman-service.config}} and [[ConnMan#Connecting_to_eduroam_.28802.1X.29|Connman#Connecting to eduroam]] for details.<br />
<br />
==== netctl ====<br />
<br />
[[netctl]] supports [[#wpa_supplicant]] configuration through blocks included with {{ic|1=WPAConfigSection=}}. See {{man|5|netctl.profile}} for details.<br />
<br />
{{Warning|Special quoting rules apply: see the {{ic|''SPECIAL QUOTING RULES''}} section in {{man|5|netctl.profile}}.}}<br />
<br />
{{Tip|Custom certificates can be specified by adding the line {{ic|1='ca_cert="/path/to/special/certificate.cer"'}} in {{ic|WPAConfigSection}}.}}<br />
<br />
=== Troubleshooting ===<br />
<br />
==== MS-CHAPv2 ====<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require {{Pkg|pptpclient}} in addition to the stock {{Pkg|ppp}} package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option. See also [https://www.cloudcracker.com/blog/2012/07/29/cracking-ms-chap-v2/] and [http://research.edm.uhasselt.be/~bbonne/docs/robyns14wpa2enterprise.pdf].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Respecting the regulatory domain ===<br />
<br />
The [[wikipedia:IEEE_802.11#Regulatory_domains_and_legal_compliance|regulatory domain]], or "regdomain", is used to reconfigure wireless drivers to make sure that wireless hardware usage complies with local laws set by the FCC, ETSI and other organizations. Regdomains use [[wikipedia:ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]]. For example, the regdomain of the United States would be "US", China would be "CN", etc.<br />
<br />
Regdomains affect the availability of wireless channels. In the 2.4GHz band, the allowed channels are 1-11 for the US, 1-14 for Japan, and 1-13 for most of the rest of the world. In the 5GHz band, the rules for allowed channels are much more complex. In either case, consult [[wikipedia:List_of_WLAN_channels|this list of WLAN channels]] for more detailed information.<br />
<br />
Regdomains also affect the limit on the [[wikipedia:Equivalent_isotropically_radiated_power|effective isotropic radiated power (EIRP)]] from wireless devices. This is derived from transmit power/"tx power", and is measured in [[wikipedia:DBm|dBm/mBm (1dBm=100mBm) or mW (log scale)]]. In the 2.4GHz band, the maximum is 30dBm in the US and Canada, 20dBm in most of Europe, and 20dB-30dBm for the rest of the world. In the 5GHz band, maximums are usually lower. Consult the [http://git.kernel.org/cgit/linux/kernel/git/linville/wireless-regdb.git/tree/db.txt wireless-regdb] for more detailed information (EIRP dBm values are in the second set of brackets for each line).<br />
<br />
Misconfiguring the regdomain can be useful - for example, by allowing use of an unused channel when other channels are crowded, or by allowing an increase in tx power to widen transmitter range. However, '''this is not recommended''' as it could break local laws and cause interference with other radio devices.<br />
<br />
To configure the regdomain, install {{Pkg|crda}} and reboot (to reload the {{ic|cfg80211}} module and all related drivers). Check the boot log to make sure that CRDA is being called by {{ic|cfg80211}}:<br />
<br />
$ dmesg | grep cfg80211<br />
<br />
The current regdomain can be set to the United States with:<br />
<br />
# iw reg set US<br />
<br />
And queried with:<br />
<br />
$ iw reg get<br />
<br />
{{Note|Your device may be set to country "00", which is the "world regulatory domain" and contains generic settings. If this cannot be unset, CRDA may be misconfigured.}}<br />
<br />
However, setting the regdomain may not alter your settings. Some devices have a regdomain set in firmware/EEPROM, which dictates the limits of the device, meaning that setting regdomain in software [http://wiki.openwrt.org/doc/howto/wireless.utilities#iw can only increase restrictions], not decrease them. For example, a CN device could be set in software to the US regdomain, but because CN has an EIRP maximum of 20dBm, the device will not be able to transmit at the US maximum of 30dBm.<br />
<br />
For example, to see if the regdomain is being set in firmware for an Atheros device:<br />
<br />
$ dmesg | grep ath:<br />
<br />
For other chipsets, it may help to search for "EEPROM", "regdomain", or simply the name of the device driver.<br />
<br />
To see if your regdomain change has been successful, and to query the number of available channels and their allowed transmit power:<br />
<br />
$ iw list | grep -A 15 Frequencies:<br />
<br />
A more permanent configuration of the regdomain can be achieved through editing {{ic|/etc/conf.d/wireless-regdom}} and uncommenting the appropriate domain.<br />
<br />
[[WPA supplicant]] can also use a regdomain in the {{ic|1=country=}} line of {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.<br />
<br />
It is also possible to configure the [http://wireless.kernel.org/en/developers/Documentation/cfg80211 cfg80211] kernel module to use a specific regdomain by adding, for example, {{ic|1=options cfg80211 ieee80211_regdom=EU}} as [[Kernel_modules#Setting module options|module options]]. However, this is part of the [http://wireless.kernel.org/en/developers/Regulatory#The_ieee80211_regdom_module_parameter old regulatory implementation].<br />
<br />
For further information, read the [http://wireless.kernel.org/en/developers/Regulatory/ wireless.kernel.org regulatory documentation].<br />
<br />
== Troubleshooting ==<br />
<br />
This section contains general troubleshooting tips, not strictly related to problems with drivers or firmware. For such topics, see next section [[#Troubleshooting drivers and firmware]].<br />
<br />
=== Temporary internet access ===<br />
<br />
If you have problematic hardware and need internet access to, for example, download some software or get help in forums, you can make use of Android's built-in feature for internet sharing via USB cable. See [[Android tethering#USB tethering]] for more information.<br />
<br />
=== Rfkill caveat ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by kernel. This can be handled by ''rfkill''. To show the current status:<br />
<br />
{{hc|# rfkill list|<br />
0: phy0: Wireless LAN<br />
Soft blocked: yes<br />
Hard blocked: yes<br />
}}<br />
<br />
If the card is ''hard-blocked'', use the hardware button (switch) to unblock it. If the card is not ''hard-blocked'' but ''soft-blocked'', use the following command:<br />
<br />
# rfkill unblock wifi<br />
<br />
{{Note|It is possible that the card will go from ''hard-blocked'' and ''soft-unblocked'' state into ''hard-unblocked'' and ''soft-blocked'' state by pressing the hardware button (i.e. the ''soft-blocked'' bit is just switched no matter what). This can be adjusted by tuning some options of the {{ic|rfkill}} [[kernel module]].}}<br />
<br />
Hardware buttons to toggle wireless cards are handled by a vendor specific [[kernel module]], frequently these are [https://lwn.net/Articles/391230/ WMI] modules. Particularly for very new hardware models, it happens that the model is not fully supported in the latest stable kernel yet. In this case it often helps to search the kernel bug tracker for information and report the model to the maintainer of the respective vendor kernel module, if it has not happened already. <br />
<br />
See also [http://askubuntu.com/questions/62166/siocsifflags-operation-not-possible-due-to-rf-kill].<br />
<br />
=== Observing Logs ===<br />
<br />
A good first measure to troubleshoot is to analyze the system's logfiles first. In order not to manually parse through them all, it can help to open a second terminal/console window and watch the kernels messages with <br />
$ dmesg -w<br />
while performing the action, e.g. the wireless association attempt. <br />
<br />
When using a tool for network management, the same can be done for systemd with <br />
# journalctl -f <br />
<br />
Frequently a wireless error is accompanied by a deauthentication with a particular reason code, for example: <br />
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)<br />
<br />
Looking up [http://www.aboutcher.co.uk/2012/07/linux-wifi-deauthenticated-reason-codes/ the reason code] might give a first hint. Maybe it also helps you to look at the control message [https://wireless.wiki.kernel.org/en/developers/documentation/mac80211/auth-assoc-deauth flowchart], the journal messages will follow it. <br />
<br />
The individual tools used in this article further provide options for more detailed debugging output, which can be used in a second step of the analysis, if required.<br />
<br />
=== Power saving ===<br />
<br />
See [[Power saving#Network interfaces]].<br />
<br />
=== Failed to get IP address ===<br />
<br />
* If getting an IP address repeatedly fails using the default {{Pkg|dhcpcd}} client, try installing and using {{Pkg|dhclient}} instead. Do not forget to select ''dhclient'' as the primary DHCP client in the [[#Manual/automatic setup|connection manager]].<br />
<br />
* If you can get an IP address for a wired interface and not for a wireless interface, try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
* If you get a timeout error due to a ''waiting for carrier'' problem, then you might have to set the channel mode to {{ic|auto}} for the specific device:<br />
<br />
# iwconfig wlan0 channel auto<br />
<br />
Before changing the channel to auto, make sure your wireless interface is down. After it has successfully changed it, you can bring the interface up again and continue from there.<br />
<br />
=== Valid IP address but cannot resolve host ===<br />
<br />
If you are on a public wireless network that may have a [[wikipedia:Captive_portal|captive portal]], make sure to query an HTTP page (not an HTTPS page) from your web browser, as some captive portals only redirect HTTP.<br />
If this is not the issue, [[check if you can resolve domain names]], it may be necessary to use the DNS server advertised via DHCP.<br />
<br />
=== Setting RTS and fragmentation thresholds ===<br />
<br />
Wireless hardware disables RTS and fragmentation by default. These are two different methods of increasing throughput at the expense of bandwidth (i.e. reliability at the expense of speed). These are useful in environments with wireless noise or many adjacent access points, which may create interference leading to timeouts or failing connections. <br />
<br />
Packet fragmentation improves throughput by splitting up packets with size exceeding the fragmentation threshold. The maximum value (2346) effectively disables fragmentation since no packet can exceed it. The minimum value (256) maximizes throughput, but may carry a significant bandwidth cost.<br />
<br />
# iw phy0 set frag 512<br />
<br />
[[Wikipedia:IEEE 802.11 RTS/CTS|RTS]] improves throughput by performing a handshake with the access point before transmitting packets with size exceeding the RTS threshold. The maximum threshold (2347) effectively disables RTS since no packet can exceed it. The minimum threshold (0) enables RTS for all packets, which is probably excessive for most situations.<br />
<br />
# iw phy0 set rts 500<br />
<br />
{{Note|{{ic|phy0}} is the name of the wireless device as listed by {{ic|$ iw phy}}.}}<br />
<br />
=== Random disconnections ===<br />
<br />
==== Cause #1 ====<br />
<br />
If dmesg says {{ic|1=wlan0: deauthenticating from MAC by local choice (reason=3)}} and you lose your Wi-Fi connection, it is likely that you have a bit too aggressive power-saving on your Wi-Fi card[http://us.generation-nt.com/answer/gentoo-user-wireless-deauthenticating-by-local-choice-help-204640041.html]. Try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
If your card does not support enabling/disabling power save mode, check the BIOS for power management options. Disabling PCI-Express power management in the BIOS of a Lenovo W520 resolved this issue.<br />
<br />
==== Cause #2 ====<br />
<br />
If you are experiencing frequent disconnections and dmesg shows messages such as <br />
<br />
{{ic|1=ieee80211 phy0: wlan0: No probe response from AP xx:xx:xx:xx:xx:xx after 500ms, disconnecting}}<br />
<br />
try changing the channel bandwidth to {{ic|20MHz}} through your router's settings page.<br />
<br />
==== Cause #3 ====<br />
<br />
On some laptop models with hardware rfkill switches (e.g., Thinkpad X200 series), due to wear or bad design, the switch (or its connection to the mainboard) might become loose over time resulting in seemingly random hardblocks/disconnects when you accidentally touch the switch or move the laptop.<br />
There is no software solution to this, unless your switch is electrical and the BIOS offers the option to disable the switch.<br />
If your switch is mechanical (most are), there are lots of possible solutions, most of which aim to disable the switch: Soldering the contact point on the mainboard/wifi-card, glueing or blocking the switch, using a screw nut to tighten the switch or removing it altogether.<br />
<br />
==== Cause #4 ====<br />
<br />
Another cause for frequent disconnects or a complete failure to connect may also be a sub-standard router, incomplete settings of the router, or interference by other wireless devices. <br />
<br />
To troubleshoot, first best try to connect to the router with no authentication. <br />
<br />
If that works, enable WPA/WPA2 again but choose fixed and/or limited router settings. For example: <br />
* If the router is considerably older than the wireless device you use for the client, test if it works with setting the router to one wireless mode <br />
* Disable mixed-mode authentication (e.g. only WPA2 with AES, or TKIP if the router is old) <br />
* Try a fixed/free channel rather than "auto" channel (maybe the router next door is old and interfering) <br />
* Disable [[Wikipedia:Wi-Fi Protected Setup|WPS]]<br />
* Disable {{ic|40Mhz}} channel bandwidth (lower throughput but less likely collisions) <br />
* If the router has quality of service settings, check completeness of settings (e.g. Wi-Fi Multimedia (WMM) is part of optional QoS flow control. An erroneous router firmware may advertise its existence although the setting is not enabled)<br />
<br />
=== Wi-Fi networks invisible because of incorrect regulatory domain===<br />
<br />
If the computer's Wi-Fi channels do not match those of the user's country, that may result in some in-range Wi-Fi networks becoming invisible, because they use wireless channels that aren't allowed by default. The solution is to configure the regulatory domain correctly, see [[#Respecting the regulatory domain]].<br />
<br />
== Troubleshooting drivers and firmware ==<br />
<br />
This section covers methods and procedures for installing kernel modules and ''firmware'' for specific chipsets, that differ from generic method.<br />
<br />
See [[Kernel modules]] for general information on operations with modules.<br />
<br />
=== Ralink/Mediatek ===<br />
<br />
==== rt2x00 ====<br />
<br />
Unified driver for Ralink chipsets (it replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, you only need to load the right module for the chip: {{ic|rt2400pci}}, {{ic|rt2500pci}}, {{ic|rt2500usb}}, {{ic|rt61pci}} or {{ic|rt73usb}} which will autoload the respective {{ic|rt2x00}} modules too.<br />
<br />
A list of devices supported by the modules is available at the project's [https://web.archive.org/web/20150507023412/http://rt2x00.serialmonkey.com/wiki/index.php/Hardware homepage].<br />
<br />
; Additional notes<br />
* Since kernel 3.0, rt2x00 includes also these drivers: {{ic|rt2800pci}}, {{ic|rt2800usb}}.<br />
* Since kernel 3.0, the staging drivers {{ic|rt2860sta}} and {{ic|rt2870sta}} are replaced by the mainline drivers {{ic|rt2800pci}} and {{ic|rt2800usb}}<sup>[https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3]</sup>.<br />
* Some devices have a wide range of options that can be configured with {{ic|iwpriv}}. These are documented in the [http://web.ralinktech.com/ralink/Home/Support/Linux.html source tarballs]{{Dead link|2018|08|15}} available from Ralink.<br />
<br />
==== rt3090 ====<br />
<br />
For devices which are using the rt3090 chipset it should be possible to use {{ic|rt2800pci}} driver, however, is not working with this chipset very well (e.g. sometimes it is not possible to use higher rate than 2Mb/s).<br />
<br />
==== rt3290 ====<br />
<br />
The rt3290 chipset is recognised by the kernel {{ic|rt2800pci}} module. However, some users experience problems and reverting to a patched Ralink driver seems to be beneficial in these [https://bbs.archlinux.org/viewtopic.php?id=161952 cases].<br />
<br />
==== rt3573 ====<br />
<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it, see the [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 DB wireless usb adapter] forums thread.<br />
<br />
==== rt5572 ====<br />
<br />
New chipset as of 2012 with support for 5 Ghz bands. It may require proprietary drivers from Ralink and some effort to compile them. At the time of writing a how-to on compilation is available for a DLINK DWA-160 rev. B2 [http://bernaerts.dyndns.org/linux/229-ubuntu-precise-dlink-dwa160-revb2 here].<br />
<br />
==== mt7612u ====<br />
<br />
New chipset as of 2014, released under their new commercial name Mediatek. It is an AC1200 or AC1300 chipset. Manufacturer provides drivers for Linux on their [https://www.mediatek.com/products/broadbandWifi/mt7612u support page]<br />
<br />
=== Realtek ===<br />
<br />
See [https://wikidevi.com/wiki/Realtek] for a list of Realtek chipsets and specifications.<br />
<br />
==== rtl8192cu ====<br />
<br />
The driver is now in the kernel, but many users have reported being unable to make a connection although scanning for networks does work.<br />
<br />
{{AUR|8192cu-dkms}} includes many patches, try this if it does not work fine with the driver in kernel.<br />
<br />
==== rtl8723ae/rtl8723be ====<br />
<br />
The {{ic|rtl8723ae}} and {{ic|rtl8723be}} modules are included in the mainline Linux kernel.<br />
<br />
Some users may encounter errors with powersave on this card. This is shown with occasional disconnects that are not recognized by high level network managers ([[netctl]], [[NetworkManager]]). This error can be confirmed by running {{ic|dmesg -w}} or {{ic|journalctl -f}} and looking for output related to powersave and the {{ic|rtl8723ae}}/{{ic|rtl8723be}} module. If you are having this issue, use the {{ic|1=fwlps=0}} kernel option, which should prevent the WiFi card from automatically sleeping and halting connection.<br />
<br />
{{hc|/etc/modprobe.d/rtl8723ae.conf|2=<br />
options rtl8723ae fwlps=0<br />
}}<br />
or<br />
{{hc|/etc/modprobe.d/rtl8723be.conf|2=<br />
options rtl8723be fwlps=0<br />
}}<br />
<br />
If you have poor signal, perhaps your device has only one physical antenna connected, and antenna autoselection is broken. You can force the choice of antenna with {{ic|1=ant_sel=1}} or {{ic|1=ant_sel=2}} kernel option. [https://bbs.archlinux.org/viewtopic.php?id=208472]<br />
<br />
==== rtl88xxau ====<br />
<br />
Realtek chipsets rtl8811au/rtl8812au/rtl8814au/rtl8821au designed for various USB adapters ranging from AC600 to AC1900.<br />
<br />
Several packages provide the kernel drivers:<br />
<br />
{| class="wikitable"<br />
! Chipset || Driver version || Package || Notes<br />
|-<br />
| rtl8811au, rtl8812au, rtl8814au and rtl8821au || 5.2.20 (possibility of using 5.3.4 base)|| {{AUR|rtl88xxau-aircrack-dkms-git}} || Aircrack-ng kernel module for 8811au, 8812au, 8814au and 8821au chipsets with monitor mode and injection support. Possibility to use experimental v5.3.4 of the driver by editing PKGBUILD file.<br />
|-<br />
| rtl8812au || 5.2.20 || {{AUR|rtl8812au-dkms-git}} || Latest official Realtek driver version for rtl8812au ''only''.<br />
|-<br />
| rtl8811au, rtl8812au and rtl8821au || 5.1.5 || {{AUR|rtl8821au-dkms-git}} || For rtl8812au the latest version 5.2.20 is recommended instead.<br />
|-<br />
| rtl8814au || 4.3.21 || {{AUR|rtl8814au-dkms-git}} || Possibly works for rtl8813au too.<br />
|}<br />
<br />
These require [[DKMS]] so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8822bu ====<br />
<br />
{{AUR|rtl8822bu-dkms-git}} provides a kernel module for the Realtek 8822bu chipset found in the Edimax EW7822ULC USB3 and Asus AC53 Nano USB 802.11ac adapter.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8xxxu ====<br />
<br />
{{Expansion|Specific issues with the mainline module and kernel versions should be stated.}}<br />
<br />
Issues with the {{ic|rtl8xxxu}} mainline kernel module may be solved by compiling a third-party module for the specific chipset. The source code can be found in [https://github.com/lwfinger?tab=repositories GitHub repositories].<br />
<br />
Some drivers may be already prepared in the AUR, e.g. {{AUR|rtl8723bu-git}} and {{AUR|rtl8723bu-git-dkms}}.<br />
<br />
=== Atheros ===<br />
<br />
The [http://madwifi-project.org/ MadWifi team] currently maintains three different drivers for devices with Atheros chipset:<br />
<br />
* {{ic|madwifi}} is an old, obsolete driver. Not present in Arch kernel since 2.6.39.1<sup>[https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html]</sup>.<br />
* {{ic|ath5k}} is newer driver, which replaces the {{ic|madwifi}} driver. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* {{ic|ath9k}} is the newest of these three drivers, it is intended for newer Atheros chipsets. All of the chips with 802.11n capabilities are supported.<br />
<br />
There are some other drivers for some Atheros devices. See [http://wireless.kernel.org/en/users/Drivers/Atheros#PCI_.2F_PCI-E_.2F_AHB_Drivers Linux Wireless documentation] for details.<br />
<br />
==== ath5k ====<br />
<br />
External resources:<br />
* http://wireless.kernel.org/en/users/Drivers/ath5k<br />
* http://wiki.debian.org/ath5k<br />
<br />
If you find web pages randomly loading very slow, or if the device is unable to lease an IP address, try to switch from hardware to software encryption by loading the {{ic|ath5k}} module with {{ic|1=nohwcrypt=1}} option. See [[Kernel modules#Setting module options]] for details.<br />
<br />
Some laptops may have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
<br />
# echo none > /sys/class/leds/ath5k-phy0::tx/trigger<br />
# echo none > /sys/class/leds/ath5k-phy0::rx/trigger<br />
<br />
For alternatives, see [https://bugzilla.redhat.com/show_bug.cgi?id=618232 this bug report].<br />
<br />
==== ath9k ====<br />
<br />
External resources:<br />
* http://wireless.kernel.org/en/users/Drivers/ath9k<br />
* http://wiki.debian.org/ath9k<br />
<br />
As of Linux 3.15.1, some users have been experiencing a decrease in bandwidth. In some cases this can fixed by editing {{ic|/etc/modprobe.d/ath9k.conf}} and adding the line:<br />
options ath9k nohwcrypt=1<br />
<br />
{{Note|Check with the command lsmod what module(-name) is in use and change it if named otherwise (e.g. ath9k_htc).}}<br />
<br />
In the unlikely event that you have stability issues that trouble you, you could try using the {{AUR|backports-patched}} package. An [https://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list] exists for support and development related discussions.<br />
<br />
===== Power saving =====<br />
<br />
Although [http://wireless.kernel.org/en/users/Documentation/dynamic-power-save Linux Wireless] says that dynamic power saving is enabled for Atheros ath9k single-chips newer than AR9280, for some devices (e.g. AR9285) {{Pkg|powertop}} might still report that power saving is disabled. In this case enable it manually.<br />
<br />
On some devices (e.g. AR9285), enabling the power saving might result in the following error:<br />
<br />
{{hc|# iw dev wlan0 set power_save on|<br />
command failed: Operation not supported (-95)<br />
}}<br />
<br />
The solution is to set the {{ic|1=ps_enable=1}} option for the {{ic|ath9k}} module:<br />
<br />
{{hc|/etc/modprobe.d/ath9k.conf|2=<br />
options ath9k ps_enable=1<br />
}}<br />
<br />
=== Intel ===<br />
<br />
==== ipw2100 and ipw2200 ====<br />
<br />
These modules are fully supported in the kernel, but they require additional firmware. Depending on which of the chipsets you have, [[install]] either {{Pkg|ipw2100-fw}} or {{Pkg|ipw2200-fw}}. Then [[Kernel modules#Manual module handling|reload]] the appropriate module.<br />
<br />
{{Tip|You may use the following [[Kernel modules#Setting module options|module options]]:<br />
* use the {{ic|1=rtap_iface=1}} option to enable the radiotap interface<br />
* use the {{ic|1=led=1}} option to enable a front LED indicating when the wireless is connected or not<br />
}}<br />
<br />
==== iwlegacy ====<br />
<br />
[http://wireless.kernel.org/en/users/Drivers/iwlegacy iwlegacy] is the wireless driver for Intel's 3945 and 4965 wireless chips. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
[[udev]] should load the driver automatically, otherwise load {{ic|iwl3945}} or {{ic|iwl4965}} manually. See [[Kernel modules]] for details.<br />
<br />
If you have problems connecting to networks in general, random failures with your card on bootup or your link quality is very poor, try to disable 802.11n:<br />
<br />
{{hc|/etc/modprobe.d/iwl4965.conf|2=<br />
options iwl4965 11n_disable=1<br />
}}<br />
<br />
If the failures persist during bootup and you are using Nouveau driver, try [[Nouveau#Enable_early_KMS|enabling early KMS]] to prevent the conflict [https://bbs.archlinux.org/viewtopic.php?pid=1748667#p1748667].<br />
<br />
==== iwlwifi ====<br />
<br />
[http://wireless.kernel.org/en/users/Drivers/iwlwifi iwlwifi] is the wireless driver for Intel's current wireless chips, such as 5100AGN, 5300AGN, and 5350AGN. See the [http://wireless.kernel.org/en/users/Drivers/iwlwifi#Supported_Devices full list of supported devices]. The firmware is included in the {{Pkg|linux-firmware}} package. The {{Aur|linux-firmware-iwlwifi-git}} may contain some updates sooner.<br />
<br />
If you have problems connecting to networks in general or your link quality is very poor, try to disable 802.11n, and perhaps also enable software encryption:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=1 swcrypto=1<br />
}}<br />
<br />
If you have a problem with slow uplink speed in 802.11n mode, for example 20Mbps, try to enable antenna aggregation:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=8<br />
}}<br />
<br />
Do not be confused with the option name, when the value is set to {{ic|8}} it does not disable anything but re-enables transmission antenna aggregation.[http://forums.gentoo.org/viewtopic-t-996692.html?sid=81bdfa435c089360bdfd9368fe0339a9] [https://bugzilla.kernel.org/show_bug.cgi?id=81571]<br />
<br />
In case this does not work for you, you may try disabling [[Power saving#Network interfaces|power saving]] for your wireless adapter.<br />
<br />
[http://ubuntuforums.org/showthread.php?t=2183486&p=12845473#post12845473 Some] have never gotten this to work. [http://ubuntuforums.org/showthread.php?t=2205733&p=12935783#post12935783 Others] found salvation by disabling N in their router settings after trying everything. This is known to have be the only solution on more than one occasion. The second link there mentions a 5ghz option that might be worth exploring.<br />
<br />
===== Bluetooth coexistence =====<br />
<br />
If you have difficulty connecting a bluetooth headset and maintaining good downlink speed, try disabling bluetooth coexistence [https://wireless.wiki.kernel.org/en/users/Drivers/iwlwifi#wifibluetooth_coexistence]:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi bt_coex_active=0<br />
}}<br />
<br />
==== Disabling LED blink ====<br />
<br />
{{Note|This works with the {{ic|iwlegacy}} and {{ic|iwlwifi}} drivers.}}<br />
<br />
The default settings on the module are to have the LED blink on activity. Some people find this extremely annoying. To have the LED on solid when Wi-Fi is active, you can use the [[systemd#Temporary files|systemd-tmpfiles]]:<br />
<br />
{{hc|/etc/tmpfiles.d/phy0-led.conf|<br />
w /sys/class/leds/phy0-led/trigger - - - - phy0radio<br />
}}<br />
<br />
Run {{ic|systemd-tmpfiles --create phy0-led.conf}} for the change to take effect, or reboot.<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
{{Tip|If you do not have {{ic|/sys/class/leds/phy0-led}}, you may try to use the {{ic|1=led_mode="1"}} [[Kernel modules#Setting module options|module option]]. It should be valid for both {{ic|iwlwifi}} and {{ic|iwlegacy}} drivers.}}<br />
<br />
=== Broadcom ===<br />
<br />
See [[Broadcom wireless]].<br />
<br />
=== Other drivers/devices ===<br />
<br />
==== Tenda w322u ====<br />
<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See [[#rt2x00]].<br />
<br />
==== orinoco ====<br />
<br />
This should be a part of the kernel package and be installed already.<br />
<br />
Some Orinoco chipsets are Hermes II. You can use the {{ic|wlags49_h2_cs}} driver instead of {{ic|orinoco_cs}} and gain WPA support. To use the driver, [[blacklist]] {{ic|orinoco_cs}} first.<br />
<br />
==== prism54 ====<br />
<br />
The driver {{ic|p54}} is included in kernel, but you have to download the appropriate firmware for your card from [http://linuxwireless.org/en/users/Drivers/p54#firmware this site] and install it into the {{ic|/usr/lib/firmware}} directory.<br />
<br />
{{Note|There is also older, deprecated driver {{ic|prism54}}, which might conflict with the newer driver ({{ic|p54pci}} or {{ic|p54usb}}). Make sure to [[blacklist]] {{ic|prism54}}.}}<br />
<br />
==== ACX100/111 ====<br />
<br />
{{Warning|The drivers for these devices [https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html are broken] and do not work with newer kernel versions.}}<br />
<br />
Packages: {{ic|tiacx}} {{ic|tiacx-firmware}} (deleted from official repositories and AUR)<br />
<br />
See [http://sourceforge.net/apps/mediawiki/acx100/index.php?title=Main_Page official wiki]{{dead link|2018|09|23}} for details.<br />
<br />
==== zd1211rw ====<br />
<br />
[http://zd1211.wiki.sourceforge.net/ {{ic|zd1211rw}}] is a driver for the ZyDAS ZD1211 802.11b/g USB WLAN chipset, and it is included in recent versions of the Linux kernel. See [http://www.linuxwireless.org/en/users/Drivers/zd1211rw/devices] for a list of supported devices. You only need to [[install]] the firmware for the device, provided by the {{AUR|zd1211-firmware}} package.<br />
<br />
==== hostap_cs ====<br />
<br />
[http://hostap.epitest.fi/ Host AP] is a Linux driver for wireless LAN cards based on Intersil's Prism2/2.5/3 chipset. The driver is included in Linux kernel.<br />
<br />
{{Note|Make sure to [[blacklist]] the {{ic|orinico_cs}} driver, it may cause problems.}}<br />
<br />
=== ndiswrapper ===<br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. You will need the {{ic|.inf}} and {{ic|.sys}} files from your Windows driver. <br />
{{Warning|Be sure to use drivers appropriate to your architecture (x86 vs. x86_64).}}<br />
<br />
{{Tip|If you need to extract these files from an {{ic|*.exe}} file, you can use {{Pkg|cabextract}}.}}<br />
<br />
Follow these steps to configure ndiswrapper.<br />
<br />
1. Install {{pkg|ndiswrapper-dkms}}<br />
<br />
2. Install the driver to {{ic|/etc/ndiswrapper/*}}<br />
# ndiswrapper -i filename.inf<br />
<br />
3. List all installed drivers for ndiswrapper<br />
$ ndiswrapper -l<br />
<br />
4. Let ndiswrapper write its configuration in {{ic|/etc/modprobe.d/ndiswrapper.conf}}:<br />
# ndiswrapper -m<br />
# depmod -a<br />
<br />
Now the ndiswrapper install is almost finished; follow the instructions on [[Kernel modules#Automatic module loading with systemd]] to automatically load the module at boot.<br />
<br />
The important part is making sure that ndiswrapper exists on this line, so just add it alongside the other modules. It would be best to test that ndiswrapper will load now, so:<br />
# modprobe ndiswrapper<br />
# iwconfig<br />
<br />
and ''wlan0'' should now exist. If you have problems, some help is available at:<br />
[http://sourceforge.net/p/ndiswrapper/ndiswrapper/HowTos/ ndiswrapper howto] and [http://sourceforge.net/p/ndiswrapper/ndiswrapper/FAQ/ ndiswrapper FAQ].<br />
<br />
=== backports-patched ===<br />
<br />
{{AUR|backports-patched}} provide drivers released on newer kernels backported for usage on older kernels. The project started since 2007 and was originally known as compat-wireless, evolved to compat-drivers and was recently renamed simply to backports. <br />
<br />
If you are using old kernel and have wireless issue, drivers in this package may help.<br />
<br />
== See also ==<br />
<br />
* [http://wireless.kernel.org/ The Linux Wireless project]<br />
* [http://aircrack-ng.org/doku.php?id=install_drivers Aircrack-ng guide on installing drivers]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=577380Network configuration/Wireless2019-07-13T16:50:48Z<p>Pgoetz: Added a section for WPA2 Personal</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[cs:Wireless network configuration]]<br />
[[de:(W)LAN und Arch Linux]]<br />
[[el:Wireless network configuration]]<br />
[[es:Wireless network configuration]]<br />
[[fa:تنظیمات شبکه ی بی سیم]]<br />
[[fr:Wifi]]<br />
[[it:Wireless network configuration]]<br />
[[ja:ワイヤレス設定]]<br />
[[nl:Wireless network configuration]]<br />
[[pt:Wireless network configuration]]<br />
[[ru:Wireless network configuration]]<br />
[[th:Wireless network configuration]]<br />
[[zh-hans:Wireless network configuration]]<br />
{{Related articles start}}<br />
{{Related|Software access point}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related|Wireless bonding}}<br />
{{Related|Network Debugging}}<br />
{{Related|Bluetooth}}<br />
{{Related articles end}}<br />
{{Move|Network configuration/Wireless|Page depends on [[Network configuration]].|Talk:Network configuration#Moving Ethernet-specific sections to Wired subpage}}<br />
The main article on network configuration is [[Network configuration]].<br />
<br />
Configuring wireless is a two-part process; the first part is to identify and ensure the correct driver for your wireless device is installed (they are available on the installation media, but often have to be installed explicitly), and to configure the interface. The second is choosing a method of managing wireless connections. This article covers both parts, and provides additional links to wireless management tools.<br />
<br />
The [[#iw]] section describes how to manually manage your wireless network interface / your wireless LANs using {{Pkg|iw}}. The [[Network configuration#Network managers]] section describes several programs that can be used to automatically manage your wireless interface, some of which include a GUI and all of which include support for network profiles (useful when frequently switching wireless networks, like with laptops).<br />
<br />
== Device driver ==<br />
<br />
The default Arch Linux kernel is ''modular'', meaning many of the drivers for machine hardware reside on the hard drive and are available as [[Kernel modules|modules]]. At boot, [[udev]] takes an inventory of your hardware and loads appropriate modules (drivers) for your corresponding hardware, which will in turn allow creation of a network ''interface''.<br />
<br />
Some wireless chipsets also require firmware, in addition to a corresponding driver. Many firmware images are provided by the {{Pkg|linux-firmware}} package which is installed by default, however, proprietary firmware images are not included and have to be installed separately. This is described in [[#Installing driver/firmware]].<br />
<br />
{{Note|If the proper module is not loaded by udev on boot, simply [[Kernel modules#Manual module handling|load it manually]]. If udev loads more than one driver for a device, the resulting conflict may prevent successful configuration. Make sure to [[blacklist]] the unwanted module.}}<br />
<br />
=== Check the driver status ===<br />
<br />
To check if the driver for your card has been loaded, check the output of the {{ic|lspci -k}} or {{ic|lsusb -v}} command, depending on if the card is connected by PCI(e) or USB. You should see that some kernel driver is in use, for example:<br />
<br />
{{hc|$ lspci -k|<nowiki><br />
06:00.0 Network controller: Intel Corporation WiFi Link 5100<br />
Subsystem: Intel Corporation WiFi Link 5100 AGN<br />
Kernel driver in use: iwlwifi<br />
Kernel modules: iwlwifi<br />
</nowiki>}}<br />
<br />
{{Note|If the card is a USB device, running {{ic|dmesg {{!}} grep usbcore}} should give something like {{ic|usbcore: registered new interface driver rtl8187}} as output.}}<br />
<br />
Also check the output of the {{ic|ip link}} command to see if a wireless interface was created; usually the naming of the wireless [[network interfaces]] starts with the letter "w", e.g. {{ic|wlan0}} or {{ic|wlp2s0}}. Then bring the interface up with:<br />
<br />
# ip link set ''interface'' up<br />
<br />
For example, assuming the interface is {{ic|wlan0}}, this is {{ic|ip link set wlan0 up}}.<br />
<br />
If you get the error message {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means that your wireless chipset requires a firmware to function.<br />
<br />
Check kernel messages for firmware being loaded:<br />
<br />
{{hc|<nowiki>$ dmesg | grep firmware</nowiki>|<nowiki><br />
[ 7.148259] iwlwifi 0000:02:00.0: loaded firmware version 39.30.4.1 build 35138 op_mode iwldvm<br />
</nowiki>}}<br />
<br />
If there is no relevant output, check the messages for the full output for the module you identified earlier ({{ic|iwlwifi}} in this example) to identify the relevant message or further issues:<br />
<br />
{{hc|<nowiki>$ dmesg | grep iwlwifi</nowiki>|<nowiki><br />
[ 12.342694] iwlwifi 0000:02:00.0: irq 44 for MSI/MSI-X<br />
[ 12.353466] iwlwifi 0000:02:00.0: loaded firmware version 39.31.5.1 build 35138 op_mode iwldvm<br />
[ 12.430317] iwlwifi 0000:02:00.0: CONFIG_IWLWIFI_DEBUG disabled<br />
...<br />
[ 12.430341] iwlwifi 0000:02:00.0: Detected Intel(R) Corporation WiFi Link 5100 AGN, REV=0x6B<br />
</nowiki>}}<br />
<br />
If the kernel module is successfully loaded and the interface is up, you can skip the next section.<br />
<br />
=== Installing driver/firmware ===<br />
<br />
Check the following lists to discover if your card is supported:<br />
<br />
* See the table of [https://wireless.wiki.kernel.org/en/users/drivers existing Linux wireless drivers] and follow to the specific driver's page, which contains a list of supported devices. There is also a [https://wikidevi.com/wiki/List_of_Wi-Fi_Device_IDs_in_Linux List of Wi-Fi Device IDs in Linux].<br />
* The [https://help.ubuntu.com/community/WifiDocs/WirelessCardsSupported Ubuntu Wiki] has a good list of wireless cards and whether or not they are supported either in the Linux kernel or by a user-space driver (includes driver name).<br />
* [http://linux-wless.passys.nl/ Linux Wireless Support] and The Linux Questions' [http://www.linuxquestions.org/hcl/index.php?cat=10 Hardware Compatibility List] (HCL) also have a good database of kernel-friendly hardware.<br />
<br />
Note that some vendors ship products that may contain different chip sets, even if the product identifier is the same. Only the usb-id (for USB devices) or pci-id (for PCI devices) is authoritative.<br />
<br />
If your wireless card is listed above, follow the [[#Troubleshooting drivers and firmware]] subsection of this page, which contains information about installing drivers and firmware of some specific wireless cards. Then [[#Check the driver status|check the driver status]] again.<br />
<br />
If your wireless card is not listed above, it is likely supported only under Windows (some Broadcom, 3com, etc). For these, you can try to use [[#ndiswrapper]].<br />
<br />
== Utilities ==<br />
<br />
Just like other network interfaces, the wireless ones are controlled with ''ip'' from the {{Pkg|iproute2}} package.<br />
<br />
Managing a wireless connection requires a basic set of tools. Either use a [[network manager]] or use one of the following directly:<br />
<br />
{| class="wikitable"<br />
! Software !! Package !! [https://wireless.wiki.kernel.org/en/developers/documentation/wireless-extensions WEXT] !! [https://wireless.wiki.kernel.org/en/developers/documentation/nl80211 nl80211] !! WEP !! WPA/WPA2 !! [[Archiso]] [https://git.archlinux.org/archiso.git/tree/configs/releng/packages.x86_64]<br />
|-<br />
| [http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html wireless_tools]<sup>1</sup> || {{pkg|wireless_tools}} || {{yes}} || {{no}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [https://wireless.kernel.org/en/users/Documentation/iw iw] || {{Pkg|iw}} || {{No}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [[WPA supplicant]] || {{Pkg|wpa_supplicant}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|-<br />
| [[iwd]] || {{Pkg|iwd}} || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
# Deprecated.<br />
<br />
Note that some cards only support WEXT.<br />
<br />
=== iw and wireless_tools comparison ===<br />
<br />
The table below gives an overview of comparable commands for ''iw'' and ''wireless_tools''. See [http://wireless.kernel.org/en/users/Documentation/iw/replace-iwconfig iw replaces iwconfig] for more examples.<br />
<br />
{| class="wikitable"<br />
! ''iw'' command<br />
! ''wireless_tools'' command<br />
! Description<br />
|-<br />
| iw dev ''wlan0'' link<br />
| iwconfig ''wlan0''<br />
| Getting link status.<br />
|-<br />
| iw dev ''wlan0'' scan<br />
| iwlist ''wlan0'' scan<br />
| Scanning for available access points.<br />
|-<br />
| iw dev ''wlan0'' set type ibss<br />
| iwconfig ''wlan0'' mode ad-hoc<br />
| Setting the operation mode to ''ad-hoc''.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid''<br />
| iwconfig ''wlan0'' essid ''your_essid''<br />
| Connecting to open network.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid'' 2432<br />
| iwconfig ''wlan0'' essid ''your_essid'' freq 2432M<br />
| Connecting to open network specifying channel.<br />
|-<br />
| rowspan="2" | iw dev ''wlan0'' connect ''your_essid'' key 0:''your_key''<br />
| iwconfig ''wlan0'' essid ''your_essid'' key ''your_key''<br />
| Connecting to WEP encrypted network using hexadecimal key.<br />
|-<br />
| iwconfig ''wlan0'' essid ''your_essid'' key s:''your_key''<br />
| Connecting to WEP encrypted network using ASCII key.<br />
|-<br />
| iw dev ''wlan0'' set power_save on<br />
| iwconfig ''wlan0'' power on<br />
| Enabling power save.<br />
|}<br />
<br />
== iw ==<br />
<br />
{{Note|<br />
* Note that most of the commands have to be executed with [[Users and groups|root permissions]]. Executed with normal user rights, some of the commands (e.g. ''iwlist''), will exit without error but not produce the correct output either, which can be confusing.<br />
* Depending on your hardware and encryption type, some of these steps may not be necessary. Some cards are known to require interface activation and/or access point scanning before being associated to an access point and being given an IP address. Some experimentation may be required. For instance, WPA/WPA2 users may try to directly activate their wireless network from step [[#Connect to an access point]].}}<br />
<br />
Examples in this section assume that your wireless device interface is {{ic|''interface''}} and that you are connecting to {{ic|''your_essid''}} wifi access point. Replace both accordingly.<br />
<br />
=== Get the name of the interface ===<br />
<br />
{{Tip|See [http://wireless.kernel.org/en/users/Documentation/iw official documentation] of the ''iw'' tool for more examples.}}<br />
<br />
To get the name of your wireless interface do:<br />
<br />
$ iw dev<br />
<br />
The name of the interface will be output after the word "Interface". For example, it is commonly {{ic|wlan0}}.<br />
<br />
=== Get the status of the interface ===<br />
<br />
To check link status, use following command.<br />
<br />
$ iw dev ''interface'' link<br />
<br />
You can get statistic information, such as the amount of tx/rx bytes, signal strength etc., with following command:<br />
<br />
$ iw dev ''interface'' station dump<br />
<br />
=== Activate the interface ===<br />
<br />
{{Tip|Usually this step is not required.}}<br />
<br />
Some cards require that the kernel interface be activated before you can use ''iw'' or ''wireless_tools'':<br />
<br />
# ip link set ''interface'' up<br />
<br />
{{Note|If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.}}<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|$ ip link show ''interface''|<br />
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 12:34:56:78:9a:bc brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
=== Discover access points ===<br />
<br />
To see what access points are available:<br />
<br />
# iw dev ''interface'' scan | less<br />
<br />
{{Note|If it displays {{ic|Interface does not support scanning}}, then you probably forgot to install the firmware. In some cases this message is also displayed when not running ''iw'' as root.}}<br />
<br />
{{Tip|Depending on your location, you might need to set the correct [[#Respecting the regulatory domain|regulatory domain]] in order to see all available networks.}}<br />
<br />
The important points to check:<br />
* '''SSID:''' the name of the network.<br />
* '''Signal:''' is reported in a wireless power ratio in dBm (e.g. from -100 to 0). The closer the negative value gets to zero, the better the signal. Observing the reported power on a good quality link and a bad one should give an idea about the individual range. <br />
* '''Security:''' it is not reported directly, check the line starting with {{ic|capability}}. If there is {{ic|Privacy}}, for example {{ic|capability: ESS Privacy ShortSlotTime (0x0411)}}, then the network is protected somehow.<br />
** If you see an {{ic|RSN}} information block, then the network is protected by [[Wikipedia:IEEE 802.11i-2004|Robust Security Network]] protocol, also known as WPA2.<br />
** If you see an {{ic|WPA}} information block, then the network is protected by [[Wikipedia:Wi-Fi Protected Access|Wi-Fi Protected Access]] protocol.<br />
** In the {{ic|RSN}} and {{ic|WPA}} blocks you may find the following information:<br />
*** '''Group cipher:''' value in TKIP, CCMP, both, others.<br />
*** '''Pairwise ciphers:''' value in TKIP, CCMP, both, others. Not necessarily the same value than Group cipher.<br />
*** '''Authentication suites:''' value in PSK, 802.1x, others. For home router, you will usually find PSK (''i.e.'' passphrase). In universities, you are more likely to find 802.1x suite which requires login and password. Then you will need to know which key management is in use (e.g. EAP), and what encapsulation it uses (e.g. PEAP). See [[#WPA2 Enterprise]] and [[Wikipedia:Authentication protocol]] for details.<br />
** If you see neither {{ic|RSN}} nor {{ic|WPA}} blocks but there is {{ic|Privacy}}, then WEP is used.<br />
<br />
=== Set operating mode ===<br />
<br />
You might need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an [[Ad-hoc networking|ad-hoc network]], you need to set the operating mode to {{ic|ibss}}:<br />
<br />
# iw dev ''interface'' set type ibss<br />
<br />
{{Note|Changing the operating mode on some cards might require the wireless interface to be ''down'' ({{ic|ip link set ''interface'' down}}).}}<br />
<br />
=== Connect to an access point ===<br />
<br />
Depending on the encryption, you need to associate your wireless device with the access point to use and pass the encryption key:<br />
<br />
* '''No encryption''' {{bc|# iw dev ''interface'' connect "''your_essid''"}}<br />
* '''WEP'''<br />
** using a hexadecimal or ASCII key (the format is distinguished automatically, because a WEP key has a fixed length): {{bc|# iw dev ''interface'' connect "''your_essid''" key 0:''your_key''}}<br />
** using a hexadecimal or ASCII key, specifying the third set up key as default (keys are counted from zero, four are possible): {{bc|# iw dev ''interface'' connect "''your_essid''" key d:2:''your_key''}}<br />
<br />
Regardless of the method used, you can check if you have associated successfully:<br />
<br />
# iw dev ''interface'' link<br />
<br />
== WPA2 Personal ==<br />
<br />
To connect to a WPA2 Personal mode wireless router from the command line, you will need to use wpa_supplicant. This method is particularly suitable for installing from the Arch linux ISO over wireless.<br />
<br />
First, encrypt the passphrase for your router:<br />
<br />
# wpa_passphrase ''my_essid'' ''my_passphrase'' > /etc/wpa_supplicant/''my_essid.conf''<br />
<br />
Before running wpa_supplicant in the background, test to make sure you get a connection:<br />
<br />
# wpa_supplicant -c /etc/wpa_supplicant/''my_essid.conf'' -i ''my_wireless_device''<br />
<br />
You might get some errors, but should see a "connected" message at the end. If so, <Ctrl>-c, and run wpa_supplicant in the background:<br />
<br />
# wpa_supplicant -B -c /etc/wpa_supplicant/''my_essid.conf'' -i ''my_wireless_device''<br />
<br />
You will still need to assign an IP address. If using DHCP:<br />
<br />
# dhclient ''my_wireless_device''<br />
<br />
That's it. Wireless networking should now be fully functional.<br />
<br />
== WPA2 Enterprise ==<br />
<br />
''WPA2 Enterprise'' is a mode of [[Wikipedia:Wi-Fi_Protected_Access|Wi-Fi Protected Access]]. It provides better security and key management than ''WPA2 Personal'', and supports other enterprise-type functionality, such as VLANs and [[wikipedia:Network Access Protection|NAP]]. However, it requires an external authentication server, called [[wikipedia:RADIUS|RADIUS]] server to handle the authentication of users. This is in contrast to Personal mode which does not require anything beyond the wireless router or access points (APs), and uses a single passphrase or password for all users.<br />
<br />
The Enterprise mode enables users to log onto the Wi-Fi network with a username and password and/or a digital certificate. Since each user has a dynamic and unique encryption key, it also helps to prevent user-to-user snooping on the wireless network, and improves encryption strength.<br />
<br />
This section describes the configuration of [[List of applications#Network managers|network clients]] to connect to a wireless access point with WPA2 Enterprise mode. See [[Software access point#RADIUS]] for information on setting up an access point itself. <br />
<br />
{{Note|Enterprise mode requires a more complex client configuration, whereas Personal mode only requires entering a passphrase when prompted. Clients likely need to install the server’s CA certificate (plus per-user certificates if using EAP-TLS), and then manually configure the wireless security and 802.1X authentication settings.}}<br />
<br />
For a comparison of protocols see the following [http://deployingradius.com/documents/protocols/compatibility.html table].<br />
<br />
{{Warning|It is possible to use WPA2 Enterprise without the client checking the server CA certificate. However, you should always seek to do so, because without authenticating the access point the connection can be subject to a man-in-the-middle attack. This may happen because while the connection handshake itself may be encrypted, the most widely used setups transmit the password itself either in plain text or the easily breakable [[#MS-CHAPv2]]. Hence, the client might send the password to a malicious access point which then proxies the connection.}}<br />
<br />
=== eduroam ===<br />
<br />
[[Wikipedia:eduroam|eduroam]] is an international roaming service for users in research, higher education and further education, based on WPA2 Enterprise.<br />
<br />
{{Note|<br />
* Check connection details '''first''' with your institution before applying any profiles listed in this section. Example profiles are not guaranteed to work or match any security requirements.<br />
* When storing connection profiles unencrypted, it is recommended restrict read access to the root account by specifying {{ic|chmod 600 ''profile''}} as root.<br />
}}<br />
<br />
{{Tip|Configuration for [[NetworkManager]] and [[#wpa_supplicant]] can be generated with the [https://cat.eduroam.org/ eduroam Configuration Assistant Tool].}}<br />
<br />
=== Manual/automatic setup ===<br />
<br />
==== wpa_supplicant ====<br />
<br />
[[WPA supplicant#Advanced usage|WPA supplicant]] can be configured directly by its configuration file or using its CLI/GUI front ends and used in combination with a DHCP client. See the examples in {{ic|/usr/share/doc/wpa_supplicant/wpa_supplicant.conf}} for configuring the connection details.<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] can generate WPA2 Enterprise profiles with [[NetworkManager#Front-ends|graphical front ends]]. ''nmcli'' and ''nmtui'' do not support this, but may use existing profiles.<br />
<br />
==== connman ====<br />
<br />
[[ConnMan]] needs a separate configuration file before [[ConnMan#Wi-Fi|connecting]] to the network. See {{man|5|connman-service.config}} and [[ConnMan#Connecting_to_eduroam_.28802.1X.29|Connman#Connecting to eduroam]] for details.<br />
<br />
==== netctl ====<br />
<br />
[[netctl]] supports [[#wpa_supplicant]] configuration through blocks included with {{ic|1=WPAConfigSection=}}. See {{man|5|netctl.profile}} for details.<br />
<br />
{{Warning|Special quoting rules apply: see the {{ic|''SPECIAL QUOTING RULES''}} section in {{man|5|netctl.profile}}.}}<br />
<br />
{{Tip|Custom certificates can be specified by adding the line {{ic|1='ca_cert="/path/to/special/certificate.cer"'}} in {{ic|WPAConfigSection}}.}}<br />
<br />
=== Troubleshooting ===<br />
<br />
==== MS-CHAPv2 ====<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require {{Pkg|pptpclient}} in addition to the stock {{Pkg|ppp}} package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option. See also [https://www.cloudcracker.com/blog/2012/07/29/cracking-ms-chap-v2/] and [http://research.edm.uhasselt.be/~bbonne/docs/robyns14wpa2enterprise.pdf].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Respecting the regulatory domain ===<br />
<br />
The [[wikipedia:IEEE_802.11#Regulatory_domains_and_legal_compliance|regulatory domain]], or "regdomain", is used to reconfigure wireless drivers to make sure that wireless hardware usage complies with local laws set by the FCC, ETSI and other organizations. Regdomains use [[wikipedia:ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]]. For example, the regdomain of the United States would be "US", China would be "CN", etc.<br />
<br />
Regdomains affect the availability of wireless channels. In the 2.4GHz band, the allowed channels are 1-11 for the US, 1-14 for Japan, and 1-13 for most of the rest of the world. In the 5GHz band, the rules for allowed channels are much more complex. In either case, consult [[wikipedia:List_of_WLAN_channels|this list of WLAN channels]] for more detailed information.<br />
<br />
Regdomains also affect the limit on the [[wikipedia:Equivalent_isotropically_radiated_power|effective isotropic radiated power (EIRP)]] from wireless devices. This is derived from transmit power/"tx power", and is measured in [[wikipedia:DBm|dBm/mBm (1dBm=100mBm) or mW (log scale)]]. In the 2.4GHz band, the maximum is 30dBm in the US and Canada, 20dBm in most of Europe, and 20dB-30dBm for the rest of the world. In the 5GHz band, maximums are usually lower. Consult the [http://git.kernel.org/cgit/linux/kernel/git/linville/wireless-regdb.git/tree/db.txt wireless-regdb] for more detailed information (EIRP dBm values are in the second set of brackets for each line).<br />
<br />
Misconfiguring the regdomain can be useful - for example, by allowing use of an unused channel when other channels are crowded, or by allowing an increase in tx power to widen transmitter range. However, '''this is not recommended''' as it could break local laws and cause interference with other radio devices.<br />
<br />
To configure the regdomain, install {{Pkg|crda}} and reboot (to reload the {{ic|cfg80211}} module and all related drivers). Check the boot log to make sure that CRDA is being called by {{ic|cfg80211}}:<br />
<br />
$ dmesg | grep cfg80211<br />
<br />
The current regdomain can be set to the United States with:<br />
<br />
# iw reg set US<br />
<br />
And queried with:<br />
<br />
$ iw reg get<br />
<br />
{{Note|Your device may be set to country "00", which is the "world regulatory domain" and contains generic settings. If this cannot be unset, CRDA may be misconfigured.}}<br />
<br />
However, setting the regdomain may not alter your settings. Some devices have a regdomain set in firmware/EEPROM, which dictates the limits of the device, meaning that setting regdomain in software [http://wiki.openwrt.org/doc/howto/wireless.utilities#iw can only increase restrictions], not decrease them. For example, a CN device could be set in software to the US regdomain, but because CN has an EIRP maximum of 20dBm, the device will not be able to transmit at the US maximum of 30dBm.<br />
<br />
For example, to see if the regdomain is being set in firmware for an Atheros device:<br />
<br />
$ dmesg | grep ath:<br />
<br />
For other chipsets, it may help to search for "EEPROM", "regdomain", or simply the name of the device driver.<br />
<br />
To see if your regdomain change has been successful, and to query the number of available channels and their allowed transmit power:<br />
<br />
$ iw list | grep -A 15 Frequencies:<br />
<br />
A more permanent configuration of the regdomain can be achieved through editing {{ic|/etc/conf.d/wireless-regdom}} and uncommenting the appropriate domain.<br />
<br />
[[WPA supplicant]] can also use a regdomain in the {{ic|1=country=}} line of {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.<br />
<br />
It is also possible to configure the [http://wireless.kernel.org/en/developers/Documentation/cfg80211 cfg80211] kernel module to use a specific regdomain by adding, for example, {{ic|1=options cfg80211 ieee80211_regdom=EU}} as [[Kernel_modules#Setting module options|module options]]. However, this is part of the [http://wireless.kernel.org/en/developers/Regulatory#The_ieee80211_regdom_module_parameter old regulatory implementation].<br />
<br />
For further information, read the [http://wireless.kernel.org/en/developers/Regulatory/ wireless.kernel.org regulatory documentation].<br />
<br />
== Troubleshooting ==<br />
<br />
This section contains general troubleshooting tips, not strictly related to problems with drivers or firmware. For such topics, see next section [[#Troubleshooting drivers and firmware]].<br />
<br />
=== Temporary internet access ===<br />
<br />
If you have problematic hardware and need internet access to, for example, download some software or get help in forums, you can make use of Android's built-in feature for internet sharing via USB cable. See [[Android tethering#USB tethering]] for more information.<br />
<br />
=== Rfkill caveat ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by kernel. This can be handled by ''rfkill''. To show the current status:<br />
<br />
{{hc|# rfkill list|<br />
0: phy0: Wireless LAN<br />
Soft blocked: yes<br />
Hard blocked: yes<br />
}}<br />
<br />
If the card is ''hard-blocked'', use the hardware button (switch) to unblock it. If the card is not ''hard-blocked'' but ''soft-blocked'', use the following command:<br />
<br />
# rfkill unblock wifi<br />
<br />
{{Note|It is possible that the card will go from ''hard-blocked'' and ''soft-unblocked'' state into ''hard-unblocked'' and ''soft-blocked'' state by pressing the hardware button (i.e. the ''soft-blocked'' bit is just switched no matter what). This can be adjusted by tuning some options of the {{ic|rfkill}} [[kernel module]].}}<br />
<br />
Hardware buttons to toggle wireless cards are handled by a vendor specific [[kernel module]], frequently these are [https://lwn.net/Articles/391230/ WMI] modules. Particularly for very new hardware models, it happens that the model is not fully supported in the latest stable kernel yet. In this case it often helps to search the kernel bug tracker for information and report the model to the maintainer of the respective vendor kernel module, if it has not happened already. <br />
<br />
See also [http://askubuntu.com/questions/62166/siocsifflags-operation-not-possible-due-to-rf-kill].<br />
<br />
=== Observing Logs ===<br />
<br />
A good first measure to troubleshoot is to analyze the system's logfiles first. In order not to manually parse through them all, it can help to open a second terminal/console window and watch the kernels messages with <br />
$ dmesg -w<br />
while performing the action, e.g. the wireless association attempt. <br />
<br />
When using a tool for network management, the same can be done for systemd with <br />
# journalctl -f <br />
<br />
Frequently a wireless error is accompanied by a deauthentication with a particular reason code, for example: <br />
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)<br />
<br />
Looking up [http://www.aboutcher.co.uk/2012/07/linux-wifi-deauthenticated-reason-codes/ the reason code] might give a first hint. Maybe it also helps you to look at the control message [https://wireless.wiki.kernel.org/en/developers/documentation/mac80211/auth-assoc-deauth flowchart], the journal messages will follow it. <br />
<br />
The individual tools used in this article further provide options for more detailed debugging output, which can be used in a second step of the analysis, if required.<br />
<br />
=== Power saving ===<br />
<br />
See [[Power saving#Network interfaces]].<br />
<br />
=== Failed to get IP address ===<br />
<br />
* If getting an IP address repeatedly fails using the default {{Pkg|dhcpcd}} client, try installing and using {{Pkg|dhclient}} instead. Do not forget to select ''dhclient'' as the primary DHCP client in the [[#Manual/automatic setup|connection manager]].<br />
<br />
* If you can get an IP address for a wired interface and not for a wireless interface, try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
* If you get a timeout error due to a ''waiting for carrier'' problem, then you might have to set the channel mode to {{ic|auto}} for the specific device:<br />
<br />
# iwconfig wlan0 channel auto<br />
<br />
Before changing the channel to auto, make sure your wireless interface is down. After it has successfully changed it, you can bring the interface up again and continue from there.<br />
<br />
=== Valid IP address but cannot resolve host ===<br />
<br />
If you are on a public wireless network that may have a [[wikipedia:Captive_portal|captive portal]], make sure to query an HTTP page (not an HTTPS page) from your web browser, as some captive portals only redirect HTTP.<br />
If this is not the issue, [[check if you can resolve domain names]], it may be necessary to use the DNS server advertised via DHCP.<br />
<br />
=== Setting RTS and fragmentation thresholds ===<br />
<br />
Wireless hardware disables RTS and fragmentation by default. These are two different methods of increasing throughput at the expense of bandwidth (i.e. reliability at the expense of speed). These are useful in environments with wireless noise or many adjacent access points, which may create interference leading to timeouts or failing connections. <br />
<br />
Packet fragmentation improves throughput by splitting up packets with size exceeding the fragmentation threshold. The maximum value (2346) effectively disables fragmentation since no packet can exceed it. The minimum value (256) maximizes throughput, but may carry a significant bandwidth cost.<br />
<br />
# iw phy0 set frag 512<br />
<br />
[[Wikipedia:IEEE 802.11 RTS/CTS|RTS]] improves throughput by performing a handshake with the access point before transmitting packets with size exceeding the RTS threshold. The maximum threshold (2347) effectively disables RTS since no packet can exceed it. The minimum threshold (0) enables RTS for all packets, which is probably excessive for most situations.<br />
<br />
# iw phy0 set rts 500<br />
<br />
{{Note|{{ic|phy0}} is the name of the wireless device as listed by {{ic|$ iw phy}}.}}<br />
<br />
=== Random disconnections ===<br />
<br />
==== Cause #1 ====<br />
<br />
If dmesg says {{ic|1=wlan0: deauthenticating from MAC by local choice (reason=3)}} and you lose your Wi-Fi connection, it is likely that you have a bit too aggressive power-saving on your Wi-Fi card[http://us.generation-nt.com/answer/gentoo-user-wireless-deauthenticating-by-local-choice-help-204640041.html]. Try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
If your card does not support enabling/disabling power save mode, check the BIOS for power management options. Disabling PCI-Express power management in the BIOS of a Lenovo W520 resolved this issue.<br />
<br />
==== Cause #2 ====<br />
<br />
If you are experiencing frequent disconnections and dmesg shows messages such as <br />
<br />
{{ic|1=ieee80211 phy0: wlan0: No probe response from AP xx:xx:xx:xx:xx:xx after 500ms, disconnecting}}<br />
<br />
try changing the channel bandwidth to {{ic|20MHz}} through your router's settings page.<br />
<br />
==== Cause #3 ====<br />
<br />
On some laptop models with hardware rfkill switches (e.g., Thinkpad X200 series), due to wear or bad design, the switch (or its connection to the mainboard) might become loose over time resulting in seemingly random hardblocks/disconnects when you accidentally touch the switch or move the laptop.<br />
There is no software solution to this, unless your switch is electrical and the BIOS offers the option to disable the switch.<br />
If your switch is mechanical (most are), there are lots of possible solutions, most of which aim to disable the switch: Soldering the contact point on the mainboard/wifi-card, glueing or blocking the switch, using a screw nut to tighten the switch or removing it altogether.<br />
<br />
==== Cause #4 ====<br />
<br />
Another cause for frequent disconnects or a complete failure to connect may also be a sub-standard router, incomplete settings of the router, or interference by other wireless devices. <br />
<br />
To troubleshoot, first best try to connect to the router with no authentication. <br />
<br />
If that works, enable WPA/WPA2 again but choose fixed and/or limited router settings. For example: <br />
* If the router is considerably older than the wireless device you use for the client, test if it works with setting the router to one wireless mode <br />
* Disable mixed-mode authentication (e.g. only WPA2 with AES, or TKIP if the router is old) <br />
* Try a fixed/free channel rather than "auto" channel (maybe the router next door is old and interfering) <br />
* Disable [[Wikipedia:Wi-Fi Protected Setup|WPS]]<br />
* Disable {{ic|40Mhz}} channel bandwidth (lower throughput but less likely collisions) <br />
* If the router has quality of service settings, check completeness of settings (e.g. Wi-Fi Multimedia (WMM) is part of optional QoS flow control. An erroneous router firmware may advertise its existence although the setting is not enabled)<br />
<br />
=== Wi-Fi networks invisible because of incorrect regulatory domain===<br />
<br />
If the computer's Wi-Fi channels do not match those of the user's country, that may result in some in-range Wi-Fi networks becoming invisible, because they use wireless channels that aren't allowed by default. The solution is to configure the regulatory domain correctly, see [[#Respecting the regulatory domain]].<br />
<br />
== Troubleshooting drivers and firmware ==<br />
<br />
This section covers methods and procedures for installing kernel modules and ''firmware'' for specific chipsets, that differ from generic method.<br />
<br />
See [[Kernel modules]] for general information on operations with modules.<br />
<br />
=== Ralink/Mediatek ===<br />
<br />
==== rt2x00 ====<br />
<br />
Unified driver for Ralink chipsets (it replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, you only need to load the right module for the chip: {{ic|rt2400pci}}, {{ic|rt2500pci}}, {{ic|rt2500usb}}, {{ic|rt61pci}} or {{ic|rt73usb}} which will autoload the respective {{ic|rt2x00}} modules too.<br />
<br />
A list of devices supported by the modules is available at the project's [https://web.archive.org/web/20150507023412/http://rt2x00.serialmonkey.com/wiki/index.php/Hardware homepage].<br />
<br />
; Additional notes<br />
* Since kernel 3.0, rt2x00 includes also these drivers: {{ic|rt2800pci}}, {{ic|rt2800usb}}.<br />
* Since kernel 3.0, the staging drivers {{ic|rt2860sta}} and {{ic|rt2870sta}} are replaced by the mainline drivers {{ic|rt2800pci}} and {{ic|rt2800usb}}<sup>[https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3]</sup>.<br />
* Some devices have a wide range of options that can be configured with {{ic|iwpriv}}. These are documented in the [http://web.ralinktech.com/ralink/Home/Support/Linux.html source tarballs]{{Dead link|2018|08|15}} available from Ralink.<br />
<br />
==== rt3090 ====<br />
<br />
For devices which are using the rt3090 chipset it should be possible to use {{ic|rt2800pci}} driver, however, is not working with this chipset very well (e.g. sometimes it is not possible to use higher rate than 2Mb/s).<br />
<br />
==== rt3290 ====<br />
<br />
The rt3290 chipset is recognised by the kernel {{ic|rt2800pci}} module. However, some users experience problems and reverting to a patched Ralink driver seems to be beneficial in these [https://bbs.archlinux.org/viewtopic.php?id=161952 cases].<br />
<br />
==== rt3573 ====<br />
<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it, see the [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 DB wireless usb adapter] forums thread.<br />
<br />
==== rt5572 ====<br />
<br />
New chipset as of 2012 with support for 5 Ghz bands. It may require proprietary drivers from Ralink and some effort to compile them. At the time of writing a how-to on compilation is available for a DLINK DWA-160 rev. B2 [http://bernaerts.dyndns.org/linux/229-ubuntu-precise-dlink-dwa160-revb2 here].<br />
<br />
==== mt7612u ====<br />
<br />
New chipset as of 2014, released under their new commercial name Mediatek. It is an AC1200 or AC1300 chipset. Manufacturer provides drivers for Linux on their [https://www.mediatek.com/products/broadbandWifi/mt7612u support page]<br />
<br />
=== Realtek ===<br />
<br />
See [https://wikidevi.com/wiki/Realtek] for a list of Realtek chipsets and specifications.<br />
<br />
==== rtl8192cu ====<br />
<br />
The driver is now in the kernel, but many users have reported being unable to make a connection although scanning for networks does work.<br />
<br />
{{AUR|8192cu-dkms}} includes many patches, try this if it does not work fine with the driver in kernel.<br />
<br />
==== rtl8723ae/rtl8723be ====<br />
<br />
The {{ic|rtl8723ae}} and {{ic|rtl8723be}} modules are included in the mainline Linux kernel.<br />
<br />
Some users may encounter errors with powersave on this card. This is shown with occasional disconnects that are not recognized by high level network managers ([[netctl]], [[NetworkManager]]). This error can be confirmed by running {{ic|dmesg -w}} or {{ic|journalctl -f}} and looking for output related to powersave and the {{ic|rtl8723ae}}/{{ic|rtl8723be}} module. If you are having this issue, use the {{ic|1=fwlps=0}} kernel option, which should prevent the WiFi card from automatically sleeping and halting connection.<br />
<br />
{{hc|/etc/modprobe.d/rtl8723ae.conf|2=<br />
options rtl8723ae fwlps=0<br />
}}<br />
or<br />
{{hc|/etc/modprobe.d/rtl8723be.conf|2=<br />
options rtl8723be fwlps=0<br />
}}<br />
<br />
If you have poor signal, perhaps your device has only one physical antenna connected, and antenna autoselection is broken. You can force the choice of antenna with {{ic|1=ant_sel=1}} or {{ic|1=ant_sel=2}} kernel option. [https://bbs.archlinux.org/viewtopic.php?id=208472]<br />
<br />
==== rtl88xxau ====<br />
<br />
Realtek chipsets rtl8811au/rtl8812au/rtl8814au/rtl8821au designed for various USB adapters ranging from AC600 to AC1900.<br />
<br />
Several packages provide the kernel drivers:<br />
<br />
{| class="wikitable"<br />
! Chipset || Driver version || Package || Notes<br />
|-<br />
| rtl8811au, rtl8812au, rtl8814au and rtl8821au || 5.2.20 (possibility of using 5.3.4 base)|| {{AUR|rtl88xxau-aircrack-dkms-git}} || Aircrack-ng kernel module for 8811au, 8812au, 8814au and 8821au chipsets with monitor mode and injection support. Possibility to use experimental v5.3.4 of the driver by editing PKGBUILD file.<br />
|-<br />
| rtl8812au || 5.2.20 || {{AUR|rtl8812au-dkms-git}} || Latest official Realtek driver version for rtl8812au ''only''.<br />
|-<br />
| rtl8811au, rtl8812au and rtl8821au || 5.1.5 || {{AUR|rtl8821au-dkms-git}} || For rtl8812au the latest version 5.2.20 is recommended instead.<br />
|-<br />
| rtl8814au || 4.3.21 || {{AUR|rtl8814au-dkms-git}} || Possibly works for rtl8813au too.<br />
|}<br />
<br />
These require [[DKMS]] so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8822bu ====<br />
<br />
{{AUR|rtl8822bu-dkms-git}} provides a kernel module for the Realtek 8822bu chipset found in the Edimax EW7822ULC USB3 and Asus AC53 Nano USB 802.11ac adapter.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8xxxu ====<br />
<br />
{{Expansion|Specific issues with the mainline module and kernel versions should be stated.}}<br />
<br />
Issues with the {{ic|rtl8xxxu}} mainline kernel module may be solved by compiling a third-party module for the specific chipset. The source code can be found in [https://github.com/lwfinger?tab=repositories GitHub repositories].<br />
<br />
Some drivers may be already prepared in the AUR, e.g. {{AUR|rtl8723bu-git}} and {{AUR|rtl8723bu-git-dkms}}.<br />
<br />
=== Atheros ===<br />
<br />
The [http://madwifi-project.org/ MadWifi team] currently maintains three different drivers for devices with Atheros chipset:<br />
<br />
* {{ic|madwifi}} is an old, obsolete driver. Not present in Arch kernel since 2.6.39.1<sup>[https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html]</sup>.<br />
* {{ic|ath5k}} is newer driver, which replaces the {{ic|madwifi}} driver. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* {{ic|ath9k}} is the newest of these three drivers, it is intended for newer Atheros chipsets. All of the chips with 802.11n capabilities are supported.<br />
<br />
There are some other drivers for some Atheros devices. See [http://wireless.kernel.org/en/users/Drivers/Atheros#PCI_.2F_PCI-E_.2F_AHB_Drivers Linux Wireless documentation] for details.<br />
<br />
==== ath5k ====<br />
<br />
External resources:<br />
* http://wireless.kernel.org/en/users/Drivers/ath5k<br />
* http://wiki.debian.org/ath5k<br />
<br />
If you find web pages randomly loading very slow, or if the device is unable to lease an IP address, try to switch from hardware to software encryption by loading the {{ic|ath5k}} module with {{ic|1=nohwcrypt=1}} option. See [[Kernel modules#Setting module options]] for details.<br />
<br />
Some laptops may have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
<br />
# echo none > /sys/class/leds/ath5k-phy0::tx/trigger<br />
# echo none > /sys/class/leds/ath5k-phy0::rx/trigger<br />
<br />
For alternatives, see [https://bugzilla.redhat.com/show_bug.cgi?id=618232 this bug report].<br />
<br />
==== ath9k ====<br />
<br />
External resources:<br />
* http://wireless.kernel.org/en/users/Drivers/ath9k<br />
* http://wiki.debian.org/ath9k<br />
<br />
As of Linux 3.15.1, some users have been experiencing a decrease in bandwidth. In some cases this can fixed by editing {{ic|/etc/modprobe.d/ath9k.conf}} and adding the line:<br />
options ath9k nohwcrypt=1<br />
<br />
{{Note|Check with the command lsmod what module(-name) is in use and change it if named otherwise (e.g. ath9k_htc).}}<br />
<br />
In the unlikely event that you have stability issues that trouble you, you could try using the {{AUR|backports-patched}} package. An [https://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list] exists for support and development related discussions.<br />
<br />
===== Power saving =====<br />
<br />
Although [http://wireless.kernel.org/en/users/Documentation/dynamic-power-save Linux Wireless] says that dynamic power saving is enabled for Atheros ath9k single-chips newer than AR9280, for some devices (e.g. AR9285) {{Pkg|powertop}} might still report that power saving is disabled. In this case enable it manually.<br />
<br />
On some devices (e.g. AR9285), enabling the power saving might result in the following error:<br />
<br />
{{hc|# iw dev wlan0 set power_save on|<br />
command failed: Operation not supported (-95)<br />
}}<br />
<br />
The solution is to set the {{ic|1=ps_enable=1}} option for the {{ic|ath9k}} module:<br />
<br />
{{hc|/etc/modprobe.d/ath9k.conf|2=<br />
options ath9k ps_enable=1<br />
}}<br />
<br />
=== Intel ===<br />
<br />
==== ipw2100 and ipw2200 ====<br />
<br />
These modules are fully supported in the kernel, but they require additional firmware. Depending on which of the chipsets you have, [[install]] either {{Pkg|ipw2100-fw}} or {{Pkg|ipw2200-fw}}. Then [[Kernel modules#Manual module handling|reload]] the appropriate module.<br />
<br />
{{Tip|You may use the following [[Kernel modules#Setting module options|module options]]:<br />
* use the {{ic|1=rtap_iface=1}} option to enable the radiotap interface<br />
* use the {{ic|1=led=1}} option to enable a front LED indicating when the wireless is connected or not<br />
}}<br />
<br />
==== iwlegacy ====<br />
<br />
[http://wireless.kernel.org/en/users/Drivers/iwlegacy iwlegacy] is the wireless driver for Intel's 3945 and 4965 wireless chips. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
[[udev]] should load the driver automatically, otherwise load {{ic|iwl3945}} or {{ic|iwl4965}} manually. See [[Kernel modules]] for details.<br />
<br />
If you have problems connecting to networks in general, random failures with your card on bootup or your link quality is very poor, try to disable 802.11n:<br />
<br />
{{hc|/etc/modprobe.d/iwl4965.conf|2=<br />
options iwl4965 11n_disable=1<br />
}}<br />
<br />
If the failures persist during bootup and you are using Nouveau driver, try [[Nouveau#Enable_early_KMS|enabling early KMS]] to prevent the conflict [https://bbs.archlinux.org/viewtopic.php?pid=1748667#p1748667].<br />
<br />
==== iwlwifi ====<br />
<br />
[http://wireless.kernel.org/en/users/Drivers/iwlwifi iwlwifi] is the wireless driver for Intel's current wireless chips, such as 5100AGN, 5300AGN, and 5350AGN. See the [http://wireless.kernel.org/en/users/Drivers/iwlwifi#Supported_Devices full list of supported devices]. The firmware is included in the {{Pkg|linux-firmware}} package. The {{Aur|linux-firmware-iwlwifi-git}} may contain some updates sooner.<br />
<br />
If you have problems connecting to networks in general or your link quality is very poor, try to disable 802.11n, and perhaps also enable software encryption:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=1 swcrypto=1<br />
}}<br />
<br />
If you have a problem with slow uplink speed in 802.11n mode, for example 20Mbps, try to enable antenna aggregation:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=8<br />
}}<br />
<br />
Do not be confused with the option name, when the value is set to {{ic|8}} it does not disable anything but re-enables transmission antenna aggregation.[http://forums.gentoo.org/viewtopic-t-996692.html?sid=81bdfa435c089360bdfd9368fe0339a9] [https://bugzilla.kernel.org/show_bug.cgi?id=81571]<br />
<br />
In case this does not work for you, you may try disabling [[Power saving#Network interfaces|power saving]] for your wireless adapter.<br />
<br />
[http://ubuntuforums.org/showthread.php?t=2183486&p=12845473#post12845473 Some] have never gotten this to work. [http://ubuntuforums.org/showthread.php?t=2205733&p=12935783#post12935783 Others] found salvation by disabling N in their router settings after trying everything. This is known to have be the only solution on more than one occasion. The second link there mentions a 5ghz option that might be worth exploring.<br />
<br />
===== Bluetooth coexistence =====<br />
<br />
If you have difficulty connecting a bluetooth headset and maintaining good downlink speed, try disabling bluetooth coexistence [https://wireless.wiki.kernel.org/en/users/Drivers/iwlwifi#wifibluetooth_coexistence]:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi bt_coex_active=0<br />
}}<br />
<br />
==== Disabling LED blink ====<br />
<br />
{{Note|This works with the {{ic|iwlegacy}} and {{ic|iwlwifi}} drivers.}}<br />
<br />
The default settings on the module are to have the LED blink on activity. Some people find this extremely annoying. To have the LED on solid when Wi-Fi is active, you can use the [[systemd#Temporary files|systemd-tmpfiles]]:<br />
<br />
{{hc|/etc/tmpfiles.d/phy0-led.conf|<br />
w /sys/class/leds/phy0-led/trigger - - - - phy0radio<br />
}}<br />
<br />
Run {{ic|systemd-tmpfiles --create phy0-led.conf}} for the change to take effect, or reboot.<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
{{Tip|If you do not have {{ic|/sys/class/leds/phy0-led}}, you may try to use the {{ic|1=led_mode="1"}} [[Kernel modules#Setting module options|module option]]. It should be valid for both {{ic|iwlwifi}} and {{ic|iwlegacy}} drivers.}}<br />
<br />
=== Broadcom ===<br />
<br />
See [[Broadcom wireless]].<br />
<br />
=== Other drivers/devices ===<br />
<br />
==== Tenda w322u ====<br />
<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See [[#rt2x00]].<br />
<br />
==== orinoco ====<br />
<br />
This should be a part of the kernel package and be installed already.<br />
<br />
Some Orinoco chipsets are Hermes II. You can use the {{ic|wlags49_h2_cs}} driver instead of {{ic|orinoco_cs}} and gain WPA support. To use the driver, [[blacklist]] {{ic|orinoco_cs}} first.<br />
<br />
==== prism54 ====<br />
<br />
The driver {{ic|p54}} is included in kernel, but you have to download the appropriate firmware for your card from [http://linuxwireless.org/en/users/Drivers/p54#firmware this site] and install it into the {{ic|/usr/lib/firmware}} directory.<br />
<br />
{{Note|There is also older, deprecated driver {{ic|prism54}}, which might conflict with the newer driver ({{ic|p54pci}} or {{ic|p54usb}}). Make sure to [[blacklist]] {{ic|prism54}}.}}<br />
<br />
==== ACX100/111 ====<br />
<br />
{{Warning|The drivers for these devices [https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html are broken] and do not work with newer kernel versions.}}<br />
<br />
Packages: {{ic|tiacx}} {{ic|tiacx-firmware}} (deleted from official repositories and AUR)<br />
<br />
See [http://sourceforge.net/apps/mediawiki/acx100/index.php?title=Main_Page official wiki]{{dead link|2018|09|23}} for details.<br />
<br />
==== zd1211rw ====<br />
<br />
[http://zd1211.wiki.sourceforge.net/ {{ic|zd1211rw}}] is a driver for the ZyDAS ZD1211 802.11b/g USB WLAN chipset, and it is included in recent versions of the Linux kernel. See [http://www.linuxwireless.org/en/users/Drivers/zd1211rw/devices] for a list of supported devices. You only need to [[install]] the firmware for the device, provided by the {{AUR|zd1211-firmware}} package.<br />
<br />
==== hostap_cs ====<br />
<br />
[http://hostap.epitest.fi/ Host AP] is a Linux driver for wireless LAN cards based on Intersil's Prism2/2.5/3 chipset. The driver is included in Linux kernel.<br />
<br />
{{Note|Make sure to [[blacklist]] the {{ic|orinico_cs}} driver, it may cause problems.}}<br />
<br />
=== ndiswrapper ===<br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. You will need the {{ic|.inf}} and {{ic|.sys}} files from your Windows driver. <br />
{{Warning|Be sure to use drivers appropriate to your architecture (x86 vs. x86_64).}}<br />
<br />
{{Tip|If you need to extract these files from an {{ic|*.exe}} file, you can use {{Pkg|cabextract}}.}}<br />
<br />
Follow these steps to configure ndiswrapper.<br />
<br />
1. Install {{pkg|ndiswrapper-dkms}}<br />
<br />
2. Install the driver to {{ic|/etc/ndiswrapper/*}}<br />
# ndiswrapper -i filename.inf<br />
<br />
3. List all installed drivers for ndiswrapper<br />
$ ndiswrapper -l<br />
<br />
4. Let ndiswrapper write its configuration in {{ic|/etc/modprobe.d/ndiswrapper.conf}}:<br />
# ndiswrapper -m<br />
# depmod -a<br />
<br />
Now the ndiswrapper install is almost finished; follow the instructions on [[Kernel modules#Automatic module loading with systemd]] to automatically load the module at boot.<br />
<br />
The important part is making sure that ndiswrapper exists on this line, so just add it alongside the other modules. It would be best to test that ndiswrapper will load now, so:<br />
# modprobe ndiswrapper<br />
# iwconfig<br />
<br />
and ''wlan0'' should now exist. If you have problems, some help is available at:<br />
[http://sourceforge.net/p/ndiswrapper/ndiswrapper/HowTos/ ndiswrapper howto] and [http://sourceforge.net/p/ndiswrapper/ndiswrapper/FAQ/ ndiswrapper FAQ].<br />
<br />
=== backports-patched ===<br />
<br />
{{AUR|backports-patched}} provide drivers released on newer kernels backported for usage on older kernels. The project started since 2007 and was originally known as compat-wireless, evolved to compat-drivers and was recently renamed simply to backports. <br />
<br />
If you are using old kernel and have wireless issue, drivers in this package may help.<br />
<br />
== See also ==<br />
<br />
* [http://wireless.kernel.org/ The Linux Wireless project]<br />
* [http://aircrack-ng.org/doku.php?id=install_drivers Aircrack-ng guide on installing drivers]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=DeveloperWiki_talk:UID_/_GID_Database&diff=569049DeveloperWiki talk:UID / GID Database2019-03-18T12:40:43Z<p>Pgoetz: add signature</p>
<hr />
<div>{{Note|'''Moderation''': [[AUR]] packages are unsupported content. This page is about packages in the [[official repositories]]. If you wish to reserve groups, or otherwise request features, use the bugtracker: https://bugs.archlinux.org/. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:11, 17 March 2016 (UTC)}}<br />
<br />
== Create users at build time ==<br />
<br />
Why should user and group be created at build time? This sounds really weird to me.<br />
Arch packages aren't supposed to be shared? You can very well build a package and not install it immediately.<br />
<br />
In any cases, I think this task definitively needs to be made at install time.<br />
That is why it is always done in scriptlets.<br />
Now what you might want to do is somehow unifying this task inside the scriptlets.<br />
If that's the case, please add your proposal with the two functions there :<br />
[https://bugs.archlinux.org/task/10375 FS#10375]<br />
and maybe edit the wiki accordingly.<br />
--[[User:Shining|shining]] 04:42, 19 May 2008 (EDT)<br />
<br />
== Add svn user and group ==<br />
<br />
Just a suggestion:<br />
create/reserve UID 44 and GID 44 for snv user ([http://subversion.tigris.org subversion] server)<br />
<br />
== mailman ==<br />
<br />
Can we have UID and GID 97 set aside for mailman? http://www.list.org<br />
<br />
EDIT: 91 is used for video apparently, changed to 97<br />
<br />
== kodi ==<br />
<br />
Before the xbmc package just created a system user and in the install script it always did a chown to make sure the /var/lib/xbmc folder was owned by xbmc.<br />
<br />
Now the folder is owned by uid 420 and gid 420, the chown is only needed when updating from a previous state.<br />
<br />
Could someone add the xbmc uid and gid to the list?<br />
<br />
:Now {{Pkg|kodi}}. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:13, 23 October 2015 (UTC)<br />
<br />
== lightdm ==<br />
<br />
The lightdm package uses {{ic|620}} for it's UID/GUID:<br />
<br />
{{bc|1=<nowiki><br />
post_install() {<br />
getent group lightdm > /dev/null 2>&1 || groupadd -g 620 lightdm<br />
getent passwd lightdm > /dev/null 2>&1 || useradd -c 'Light Display Manager' -u 620 -g lightdm -d /var/lib/lightdm -s /usr/bin/nologin lightdm<br />
passwd -l lightdm > /dev/null<br />
systemd-tmpfiles --create /usr/lib/tmpfiles.d/lightdm.conf<br />
}<br />
</nowiki>}}<br />
<br />
== Reserve UID/GID for system administrators? ==<br />
<br />
Standardization of UID/GID is nice thing but currently I believe it is assigned randomly based on package maintainer request.<br />
<br />
I need to create 2-3 system users on many machines where assumption is UID/GID will be same in all machines.<br />
<br />
But I fear that in future Arch may allocate that UID/GID to some "new" popular package.<br />
<br />
Because in that case then I will have to change UID/GID of my system users on all machines as well as chown all files owned by those UID/GID.<br />
<br />
So if we can reserve some fifty to hundred UIDs (say from 800 to 850 OR 800 to 900) for system adminitrator's use only, then it would be nice for administrators like me.<br />
<br />
[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 16:36, 21 May 2017 (UTC)<br />
<br />
:Is this right place for discussing this?<br />
:<br />
:This is something like systemd where /usr is used for defaults and /etc is used for system administrators so as to avoid conflicts<br />
:<br />
:Sameway UID/GID from 800 to 850/900 can be reserved to be used by system administrators without worrying that it would be used by some other package in future and create conflict.<br />
:<br />
:[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 04:56, 16 August 2017 (UTC)<br />
<br />
::As you can see from the list, Arch has reserved less than 1000 UIDs out of [https://serverfault.com/questions/105260/how-big-in-bits-is-a-unix-uid some very large number]. ''useradd'' assigns UIDs from 1000 to 60000 and [[systemd-nspawn]] uses UIDs larger than 65536 for [[systemd-nspawn#Creating private users (unprivileged containers)|unprivileged containers]]. So if you use UIDs around 60000 for your own purposes, there is very good chance that it won't conflict with anything. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:22, 16 August 2017 (UTC)<br />
<br />
:::Thank you but system UID/GID are defined by SYS_UID_MIN (500) and SYS_UID_MAX (999) (defined in /etc/login.defs) and some tools use those numbers to differentiate between system user and normal user. (and warn if system user is being deleted) Reserving range of system UID/GID for administrator use, helps for coders who develop their own daemons and want to make sure that in future UID/GID do not conflict.<br />
:::[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 09:55, 16 August 2017 (UTC)<br />
<br />
== GIDs are now generated dynamically / the static GIDs here are not valid anymore ==<br />
<br />
After recent changes to the filesystem package GIDs are now created by sysusers.d(5). The means, that for example the "users" group does not have a static id of 100 anymore. So, the information here is outdated and needs to be updated to reflect the dynamic id allocation. Either that, or there is a possibilty to set static user ids with sysusers.d, but I haven't investigated this yet.<br />
<br />
[[User:Jrk|Jrk]] ([[User talk:Jrk|talk]]) 11:50, 14 December 2017 (UTC)<br />
<br />
: I'm not following this argument: just because GIDs are created by sysusers.d, why does this mean the users group doesn't have a static id any more? [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:21, 18 March 2019 (UTC)<br />
<br />
::Because systemd's [https://github.com/systemd/systemd/blob/master/sysusers.d/basic.conf.in basic.conf] does not specify the GIDs for most of the groups and Arch's PKGBUILD leaves the configurable values to the default, which leads to dynamic behaviour even for {{ic|users}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:25, 18 March 2019 (UTC)<br />
<br />
== <s>The sudo group is missing. Other distros have this gid set to 27</s> ==<br />
<br />
For some reason I'm not able to edit this page, but it would be a good idea to include sudo = 27 as per at least Ubuntu/Debian. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:24, 18 March 2019 (UTC)<br />
<br />
:Arch's {{pkg|sudo}} package does not create a {{ic|sudo}} group, other distributions are irrelevant. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:17, 18 March 2019 (UTC)<br />
<br />
:: Yes, I've wondered about this. Does this have something to do with upstream? The sudo group is pretty widely used AFAIK to identify sys admins on a system, and the {{ic|/etc/sudoers}} file seems to support this by default:<br />
<br />
## Uncomment to allow members of group sudo to execute any command<br />
# %sudo ALL=(ALL) ALL<br />
<br />
:: Anyway, for the people coming from other distros who are used to having a sudo group, is there any harm in providing guidelines for what the GID should be to be consistent? Seems like no harm done and useful if included. Nothing in the page description suggests that something which isn't created by default should be excluded. If this is the policy, you might want to mention that in order to avoid having to respond to comments like this. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 12:40, 18 March 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=DeveloperWiki_talk:UID_/_GID_Database&diff=569048DeveloperWiki talk:UID / GID Database2019-03-18T12:40:12Z<p>Pgoetz: further formatting</p>
<hr />
<div>{{Note|'''Moderation''': [[AUR]] packages are unsupported content. This page is about packages in the [[official repositories]]. If you wish to reserve groups, or otherwise request features, use the bugtracker: https://bugs.archlinux.org/. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:11, 17 March 2016 (UTC)}}<br />
<br />
== Create users at build time ==<br />
<br />
Why should user and group be created at build time? This sounds really weird to me.<br />
Arch packages aren't supposed to be shared? You can very well build a package and not install it immediately.<br />
<br />
In any cases, I think this task definitively needs to be made at install time.<br />
That is why it is always done in scriptlets.<br />
Now what you might want to do is somehow unifying this task inside the scriptlets.<br />
If that's the case, please add your proposal with the two functions there :<br />
[https://bugs.archlinux.org/task/10375 FS#10375]<br />
and maybe edit the wiki accordingly.<br />
--[[User:Shining|shining]] 04:42, 19 May 2008 (EDT)<br />
<br />
== Add svn user and group ==<br />
<br />
Just a suggestion:<br />
create/reserve UID 44 and GID 44 for snv user ([http://subversion.tigris.org subversion] server)<br />
<br />
== mailman ==<br />
<br />
Can we have UID and GID 97 set aside for mailman? http://www.list.org<br />
<br />
EDIT: 91 is used for video apparently, changed to 97<br />
<br />
== kodi ==<br />
<br />
Before the xbmc package just created a system user and in the install script it always did a chown to make sure the /var/lib/xbmc folder was owned by xbmc.<br />
<br />
Now the folder is owned by uid 420 and gid 420, the chown is only needed when updating from a previous state.<br />
<br />
Could someone add the xbmc uid and gid to the list?<br />
<br />
:Now {{Pkg|kodi}}. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:13, 23 October 2015 (UTC)<br />
<br />
== lightdm ==<br />
<br />
The lightdm package uses {{ic|620}} for it's UID/GUID:<br />
<br />
{{bc|1=<nowiki><br />
post_install() {<br />
getent group lightdm > /dev/null 2>&1 || groupadd -g 620 lightdm<br />
getent passwd lightdm > /dev/null 2>&1 || useradd -c 'Light Display Manager' -u 620 -g lightdm -d /var/lib/lightdm -s /usr/bin/nologin lightdm<br />
passwd -l lightdm > /dev/null<br />
systemd-tmpfiles --create /usr/lib/tmpfiles.d/lightdm.conf<br />
}<br />
</nowiki>}}<br />
<br />
== Reserve UID/GID for system administrators? ==<br />
<br />
Standardization of UID/GID is nice thing but currently I believe it is assigned randomly based on package maintainer request.<br />
<br />
I need to create 2-3 system users on many machines where assumption is UID/GID will be same in all machines.<br />
<br />
But I fear that in future Arch may allocate that UID/GID to some "new" popular package.<br />
<br />
Because in that case then I will have to change UID/GID of my system users on all machines as well as chown all files owned by those UID/GID.<br />
<br />
So if we can reserve some fifty to hundred UIDs (say from 800 to 850 OR 800 to 900) for system adminitrator's use only, then it would be nice for administrators like me.<br />
<br />
[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 16:36, 21 May 2017 (UTC)<br />
<br />
:Is this right place for discussing this?<br />
:<br />
:This is something like systemd where /usr is used for defaults and /etc is used for system administrators so as to avoid conflicts<br />
:<br />
:Sameway UID/GID from 800 to 850/900 can be reserved to be used by system administrators without worrying that it would be used by some other package in future and create conflict.<br />
:<br />
:[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 04:56, 16 August 2017 (UTC)<br />
<br />
::As you can see from the list, Arch has reserved less than 1000 UIDs out of [https://serverfault.com/questions/105260/how-big-in-bits-is-a-unix-uid some very large number]. ''useradd'' assigns UIDs from 1000 to 60000 and [[systemd-nspawn]] uses UIDs larger than 65536 for [[systemd-nspawn#Creating private users (unprivileged containers)|unprivileged containers]]. So if you use UIDs around 60000 for your own purposes, there is very good chance that it won't conflict with anything. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:22, 16 August 2017 (UTC)<br />
<br />
:::Thank you but system UID/GID are defined by SYS_UID_MIN (500) and SYS_UID_MAX (999) (defined in /etc/login.defs) and some tools use those numbers to differentiate between system user and normal user. (and warn if system user is being deleted) Reserving range of system UID/GID for administrator use, helps for coders who develop their own daemons and want to make sure that in future UID/GID do not conflict.<br />
:::[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 09:55, 16 August 2017 (UTC)<br />
<br />
== GIDs are now generated dynamically / the static GIDs here are not valid anymore ==<br />
<br />
After recent changes to the filesystem package GIDs are now created by sysusers.d(5). The means, that for example the "users" group does not have a static id of 100 anymore. So, the information here is outdated and needs to be updated to reflect the dynamic id allocation. Either that, or there is a possibilty to set static user ids with sysusers.d, but I haven't investigated this yet.<br />
<br />
[[User:Jrk|Jrk]] ([[User talk:Jrk|talk]]) 11:50, 14 December 2017 (UTC)<br />
<br />
: I'm not following this argument: just because GIDs are created by sysusers.d, why does this mean the users group doesn't have a static id any more? [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:21, 18 March 2019 (UTC)<br />
<br />
::Because systemd's [https://github.com/systemd/systemd/blob/master/sysusers.d/basic.conf.in basic.conf] does not specify the GIDs for most of the groups and Arch's PKGBUILD leaves the configurable values to the default, which leads to dynamic behaviour even for {{ic|users}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:25, 18 March 2019 (UTC)<br />
<br />
== <s>The sudo group is missing. Other distros have this gid set to 27</s> ==<br />
<br />
For some reason I'm not able to edit this page, but it would be a good idea to include sudo = 27 as per at least Ubuntu/Debian. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:24, 18 March 2019 (UTC)<br />
<br />
:Arch's {{pkg|sudo}} package does not create a {{ic|sudo}} group, other distributions are irrelevant. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:17, 18 March 2019 (UTC)<br />
<br />
:: Yes, I've wondered about this. Does this have something to do with upstream? The sudo group is pretty widely used AFAIK to identify sys admins on a system, and the {{ic|/etc/sudoers}} file seems to support this by default:<br />
<br />
## Uncomment to allow members of group sudo to execute any command<br />
# %sudo ALL=(ALL) ALL<br />
<br />
:: Anyway, for the people coming from other distros who are used to having a sudo group, is there any harm in providing guidelines for what the GID should be to be consistent? Seems like no harm done and useful if included. Nothing in the page description suggests that something which isn't created by default should be excluded. If this is the policy, you might want to mention that in order to avoid having to respond to comments like this.</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=DeveloperWiki_talk:UID_/_GID_Database&diff=569047DeveloperWiki talk:UID / GID Database2019-03-18T12:39:39Z<p>Pgoetz: formatting</p>
<hr />
<div>{{Note|'''Moderation''': [[AUR]] packages are unsupported content. This page is about packages in the [[official repositories]]. If you wish to reserve groups, or otherwise request features, use the bugtracker: https://bugs.archlinux.org/. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:11, 17 March 2016 (UTC)}}<br />
<br />
== Create users at build time ==<br />
<br />
Why should user and group be created at build time? This sounds really weird to me.<br />
Arch packages aren't supposed to be shared? You can very well build a package and not install it immediately.<br />
<br />
In any cases, I think this task definitively needs to be made at install time.<br />
That is why it is always done in scriptlets.<br />
Now what you might want to do is somehow unifying this task inside the scriptlets.<br />
If that's the case, please add your proposal with the two functions there :<br />
[https://bugs.archlinux.org/task/10375 FS#10375]<br />
and maybe edit the wiki accordingly.<br />
--[[User:Shining|shining]] 04:42, 19 May 2008 (EDT)<br />
<br />
== Add svn user and group ==<br />
<br />
Just a suggestion:<br />
create/reserve UID 44 and GID 44 for snv user ([http://subversion.tigris.org subversion] server)<br />
<br />
== mailman ==<br />
<br />
Can we have UID and GID 97 set aside for mailman? http://www.list.org<br />
<br />
EDIT: 91 is used for video apparently, changed to 97<br />
<br />
== kodi ==<br />
<br />
Before the xbmc package just created a system user and in the install script it always did a chown to make sure the /var/lib/xbmc folder was owned by xbmc.<br />
<br />
Now the folder is owned by uid 420 and gid 420, the chown is only needed when updating from a previous state.<br />
<br />
Could someone add the xbmc uid and gid to the list?<br />
<br />
:Now {{Pkg|kodi}}. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:13, 23 October 2015 (UTC)<br />
<br />
== lightdm ==<br />
<br />
The lightdm package uses {{ic|620}} for it's UID/GUID:<br />
<br />
{{bc|1=<nowiki><br />
post_install() {<br />
getent group lightdm > /dev/null 2>&1 || groupadd -g 620 lightdm<br />
getent passwd lightdm > /dev/null 2>&1 || useradd -c 'Light Display Manager' -u 620 -g lightdm -d /var/lib/lightdm -s /usr/bin/nologin lightdm<br />
passwd -l lightdm > /dev/null<br />
systemd-tmpfiles --create /usr/lib/tmpfiles.d/lightdm.conf<br />
}<br />
</nowiki>}}<br />
<br />
== Reserve UID/GID for system administrators? ==<br />
<br />
Standardization of UID/GID is nice thing but currently I believe it is assigned randomly based on package maintainer request.<br />
<br />
I need to create 2-3 system users on many machines where assumption is UID/GID will be same in all machines.<br />
<br />
But I fear that in future Arch may allocate that UID/GID to some "new" popular package.<br />
<br />
Because in that case then I will have to change UID/GID of my system users on all machines as well as chown all files owned by those UID/GID.<br />
<br />
So if we can reserve some fifty to hundred UIDs (say from 800 to 850 OR 800 to 900) for system adminitrator's use only, then it would be nice for administrators like me.<br />
<br />
[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 16:36, 21 May 2017 (UTC)<br />
<br />
:Is this right place for discussing this?<br />
:<br />
:This is something like systemd where /usr is used for defaults and /etc is used for system administrators so as to avoid conflicts<br />
:<br />
:Sameway UID/GID from 800 to 850/900 can be reserved to be used by system administrators without worrying that it would be used by some other package in future and create conflict.<br />
:<br />
:[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 04:56, 16 August 2017 (UTC)<br />
<br />
::As you can see from the list, Arch has reserved less than 1000 UIDs out of [https://serverfault.com/questions/105260/how-big-in-bits-is-a-unix-uid some very large number]. ''useradd'' assigns UIDs from 1000 to 60000 and [[systemd-nspawn]] uses UIDs larger than 65536 for [[systemd-nspawn#Creating private users (unprivileged containers)|unprivileged containers]]. So if you use UIDs around 60000 for your own purposes, there is very good chance that it won't conflict with anything. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:22, 16 August 2017 (UTC)<br />
<br />
:::Thank you but system UID/GID are defined by SYS_UID_MIN (500) and SYS_UID_MAX (999) (defined in /etc/login.defs) and some tools use those numbers to differentiate between system user and normal user. (and warn if system user is being deleted) Reserving range of system UID/GID for administrator use, helps for coders who develop their own daemons and want to make sure that in future UID/GID do not conflict.<br />
:::[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 09:55, 16 August 2017 (UTC)<br />
<br />
== GIDs are now generated dynamically / the static GIDs here are not valid anymore ==<br />
<br />
After recent changes to the filesystem package GIDs are now created by sysusers.d(5). The means, that for example the "users" group does not have a static id of 100 anymore. So, the information here is outdated and needs to be updated to reflect the dynamic id allocation. Either that, or there is a possibilty to set static user ids with sysusers.d, but I haven't investigated this yet.<br />
<br />
[[User:Jrk|Jrk]] ([[User talk:Jrk|talk]]) 11:50, 14 December 2017 (UTC)<br />
<br />
: I'm not following this argument: just because GIDs are created by sysusers.d, why does this mean the users group doesn't have a static id any more? [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:21, 18 March 2019 (UTC)<br />
<br />
::Because systemd's [https://github.com/systemd/systemd/blob/master/sysusers.d/basic.conf.in basic.conf] does not specify the GIDs for most of the groups and Arch's PKGBUILD leaves the configurable values to the default, which leads to dynamic behaviour even for {{ic|users}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:25, 18 March 2019 (UTC)<br />
<br />
== <s>The sudo group is missing. Other distros have this gid set to 27</s> ==<br />
<br />
For some reason I'm not able to edit this page, but it would be a good idea to include sudo = 27 as per at least Ubuntu/Debian. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:24, 18 March 2019 (UTC)<br />
<br />
:Arch's {{pkg|sudo}} package does not create a {{ic|sudo}} group, other distributions are irrelevant. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:17, 18 March 2019 (UTC)<br />
<br />
:: Yes, I've wondered about this. Does this have something to do with upstream? The sudo group is pretty widely used AFAIK to identify sys admins on a system, and the {{ic|/etc/sudoers}} file seems to support this by default:<br />
<br />
:: ## Uncomment to allow members of group sudo to execute any command<br />
# %sudo ALL=(ALL) ALL<br />
<br />
:: Anyway, for the people coming from other distros who are used to having a sudo group, is there any harm in providing guidelines for what the GID should be to be consistent? Seems like no harm done and useful if included. Nothing in the page description suggests that something which isn't created by default should be excluded. If this is the policy, you might want to mention that in order to avoid having to respond to comments like this.</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=DeveloperWiki_talk:UID_/_GID_Database&diff=569046DeveloperWiki talk:UID / GID Database2019-03-18T12:39:01Z<p>Pgoetz: follow up comment</p>
<hr />
<div>{{Note|'''Moderation''': [[AUR]] packages are unsupported content. This page is about packages in the [[official repositories]]. If you wish to reserve groups, or otherwise request features, use the bugtracker: https://bugs.archlinux.org/. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:11, 17 March 2016 (UTC)}}<br />
<br />
== Create users at build time ==<br />
<br />
Why should user and group be created at build time? This sounds really weird to me.<br />
Arch packages aren't supposed to be shared? You can very well build a package and not install it immediately.<br />
<br />
In any cases, I think this task definitively needs to be made at install time.<br />
That is why it is always done in scriptlets.<br />
Now what you might want to do is somehow unifying this task inside the scriptlets.<br />
If that's the case, please add your proposal with the two functions there :<br />
[https://bugs.archlinux.org/task/10375 FS#10375]<br />
and maybe edit the wiki accordingly.<br />
--[[User:Shining|shining]] 04:42, 19 May 2008 (EDT)<br />
<br />
== Add svn user and group ==<br />
<br />
Just a suggestion:<br />
create/reserve UID 44 and GID 44 for snv user ([http://subversion.tigris.org subversion] server)<br />
<br />
== mailman ==<br />
<br />
Can we have UID and GID 97 set aside for mailman? http://www.list.org<br />
<br />
EDIT: 91 is used for video apparently, changed to 97<br />
<br />
== kodi ==<br />
<br />
Before the xbmc package just created a system user and in the install script it always did a chown to make sure the /var/lib/xbmc folder was owned by xbmc.<br />
<br />
Now the folder is owned by uid 420 and gid 420, the chown is only needed when updating from a previous state.<br />
<br />
Could someone add the xbmc uid and gid to the list?<br />
<br />
:Now {{Pkg|kodi}}. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:13, 23 October 2015 (UTC)<br />
<br />
== lightdm ==<br />
<br />
The lightdm package uses {{ic|620}} for it's UID/GUID:<br />
<br />
{{bc|1=<nowiki><br />
post_install() {<br />
getent group lightdm > /dev/null 2>&1 || groupadd -g 620 lightdm<br />
getent passwd lightdm > /dev/null 2>&1 || useradd -c 'Light Display Manager' -u 620 -g lightdm -d /var/lib/lightdm -s /usr/bin/nologin lightdm<br />
passwd -l lightdm > /dev/null<br />
systemd-tmpfiles --create /usr/lib/tmpfiles.d/lightdm.conf<br />
}<br />
</nowiki>}}<br />
<br />
== Reserve UID/GID for system administrators? ==<br />
<br />
Standardization of UID/GID is nice thing but currently I believe it is assigned randomly based on package maintainer request.<br />
<br />
I need to create 2-3 system users on many machines where assumption is UID/GID will be same in all machines.<br />
<br />
But I fear that in future Arch may allocate that UID/GID to some "new" popular package.<br />
<br />
Because in that case then I will have to change UID/GID of my system users on all machines as well as chown all files owned by those UID/GID.<br />
<br />
So if we can reserve some fifty to hundred UIDs (say from 800 to 850 OR 800 to 900) for system adminitrator's use only, then it would be nice for administrators like me.<br />
<br />
[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 16:36, 21 May 2017 (UTC)<br />
<br />
:Is this right place for discussing this?<br />
:<br />
:This is something like systemd where /usr is used for defaults and /etc is used for system administrators so as to avoid conflicts<br />
:<br />
:Sameway UID/GID from 800 to 850/900 can be reserved to be used by system administrators without worrying that it would be used by some other package in future and create conflict.<br />
:<br />
:[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 04:56, 16 August 2017 (UTC)<br />
<br />
::As you can see from the list, Arch has reserved less than 1000 UIDs out of [https://serverfault.com/questions/105260/how-big-in-bits-is-a-unix-uid some very large number]. ''useradd'' assigns UIDs from 1000 to 60000 and [[systemd-nspawn]] uses UIDs larger than 65536 for [[systemd-nspawn#Creating private users (unprivileged containers)|unprivileged containers]]. So if you use UIDs around 60000 for your own purposes, there is very good chance that it won't conflict with anything. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:22, 16 August 2017 (UTC)<br />
<br />
:::Thank you but system UID/GID are defined by SYS_UID_MIN (500) and SYS_UID_MAX (999) (defined in /etc/login.defs) and some tools use those numbers to differentiate between system user and normal user. (and warn if system user is being deleted) Reserving range of system UID/GID for administrator use, helps for coders who develop their own daemons and want to make sure that in future UID/GID do not conflict.<br />
:::[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 09:55, 16 August 2017 (UTC)<br />
<br />
== GIDs are now generated dynamically / the static GIDs here are not valid anymore ==<br />
<br />
After recent changes to the filesystem package GIDs are now created by sysusers.d(5). The means, that for example the "users" group does not have a static id of 100 anymore. So, the information here is outdated and needs to be updated to reflect the dynamic id allocation. Either that, or there is a possibilty to set static user ids with sysusers.d, but I haven't investigated this yet.<br />
<br />
[[User:Jrk|Jrk]] ([[User talk:Jrk|talk]]) 11:50, 14 December 2017 (UTC)<br />
<br />
: I'm not following this argument: just because GIDs are created by sysusers.d, why does this mean the users group doesn't have a static id any more? [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:21, 18 March 2019 (UTC)<br />
<br />
::Because systemd's [https://github.com/systemd/systemd/blob/master/sysusers.d/basic.conf.in basic.conf] does not specify the GIDs for most of the groups and Arch's PKGBUILD leaves the configurable values to the default, which leads to dynamic behaviour even for {{ic|users}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:25, 18 March 2019 (UTC)<br />
<br />
== <s>The sudo group is missing. Other distros have this gid set to 27</s> ==<br />
<br />
For some reason I'm not able to edit this page, but it would be a good idea to include sudo = 27 as per at least Ubuntu/Debian. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:24, 18 March 2019 (UTC)<br />
<br />
:Arch's {{pkg|sudo}} package does not create a {{ic|sudo}} group, other distributions are irrelevant. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:17, 18 March 2019 (UTC)<br />
<br />
:: Yes, I've wondered about this. Does this have something to do with upstream? The sudo group is pretty widely used AFAIK to identify sys admins on a system, and the {{ic|/etc/sudoers}} file seems to support this by default:<br />
<br />
## Uncomment to allow members of group sudo to execute any command<br />
# %sudo ALL=(ALL) ALL<br />
<br />
Anyway, for the people coming from other distros who are used to having a sudo group, is there any harm in providing guidelines for what the GID should be to be consistent? Seems like no harm done and useful if included. Nothing in the page description suggests that something which isn't created by default should be excluded. If this is the policy, you might want to mention that in order to avoid having to respond to comments like this.</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=DeveloperWiki_talk:UID_/_GID_Database&diff=569042DeveloperWiki talk:UID / GID Database2019-03-18T11:24:06Z<p>Pgoetz: Add standard sudo group to this list</p>
<hr />
<div>{{Note|'''Moderation''': [[AUR]] packages are unsupported content. This page is about packages in the [[official repositories]]. If you wish to reserve groups, or otherwise request features, use the bugtracker: https://bugs.archlinux.org/. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:11, 17 March 2016 (UTC)}}<br />
<br />
== Create users at build time ==<br />
<br />
Why should user and group be created at build time? This sounds really weird to me.<br />
Arch packages aren't supposed to be shared? You can very well build a package and not install it immediately.<br />
<br />
In any cases, I think this task definitively needs to be made at install time.<br />
That is why it is always done in scriptlets.<br />
Now what you might want to do is somehow unifying this task inside the scriptlets.<br />
If that's the case, please add your proposal with the two functions there :<br />
[https://bugs.archlinux.org/task/10375 FS#10375]<br />
and maybe edit the wiki accordingly.<br />
--[[User:Shining|shining]] 04:42, 19 May 2008 (EDT)<br />
<br />
== Add svn user and group ==<br />
<br />
Just a suggestion:<br />
create/reserve UID 44 and GID 44 for snv user ([http://subversion.tigris.org subversion] server)<br />
<br />
== mailman ==<br />
<br />
Can we have UID and GID 97 set aside for mailman? http://www.list.org<br />
<br />
EDIT: 91 is used for video apparently, changed to 97<br />
<br />
== kodi ==<br />
<br />
Before the xbmc package just created a system user and in the install script it always did a chown to make sure the /var/lib/xbmc folder was owned by xbmc.<br />
<br />
Now the folder is owned by uid 420 and gid 420, the chown is only needed when updating from a previous state.<br />
<br />
Could someone add the xbmc uid and gid to the list?<br />
<br />
:Now {{Pkg|kodi}}. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:13, 23 October 2015 (UTC)<br />
<br />
== lightdm ==<br />
<br />
The lightdm package uses {{ic|620}} for it's UID/GUID:<br />
<br />
{{bc|1=<nowiki><br />
post_install() {<br />
getent group lightdm > /dev/null 2>&1 || groupadd -g 620 lightdm<br />
getent passwd lightdm > /dev/null 2>&1 || useradd -c 'Light Display Manager' -u 620 -g lightdm -d /var/lib/lightdm -s /usr/bin/nologin lightdm<br />
passwd -l lightdm > /dev/null<br />
systemd-tmpfiles --create /usr/lib/tmpfiles.d/lightdm.conf<br />
}<br />
</nowiki>}}<br />
<br />
== Reserve UID/GID for system administrators? ==<br />
<br />
Standardization of UID/GID is nice thing but currently I believe it is assigned randomly based on package maintainer request.<br />
<br />
I need to create 2-3 system users on many machines where assumption is UID/GID will be same in all machines.<br />
<br />
But I fear that in future Arch may allocate that UID/GID to some "new" popular package.<br />
<br />
Because in that case then I will have to change UID/GID of my system users on all machines as well as chown all files owned by those UID/GID.<br />
<br />
So if we can reserve some fifty to hundred UIDs (say from 800 to 850 OR 800 to 900) for system adminitrator's use only, then it would be nice for administrators like me.<br />
<br />
[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 16:36, 21 May 2017 (UTC)<br />
<br />
:Is this right place for discussing this?<br />
:<br />
:This is something like systemd where /usr is used for defaults and /etc is used for system administrators so as to avoid conflicts<br />
:<br />
:Sameway UID/GID from 800 to 850/900 can be reserved to be used by system administrators without worrying that it would be used by some other package in future and create conflict.<br />
:<br />
:[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 04:56, 16 August 2017 (UTC)<br />
<br />
::As you can see from the list, Arch has reserved less than 1000 UIDs out of [https://serverfault.com/questions/105260/how-big-in-bits-is-a-unix-uid some very large number]. ''useradd'' assigns UIDs from 1000 to 60000 and [[systemd-nspawn]] uses UIDs larger than 65536 for [[systemd-nspawn#Creating private users (unprivileged containers)|unprivileged containers]]. So if you use UIDs around 60000 for your own purposes, there is very good chance that it won't conflict with anything. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:22, 16 August 2017 (UTC)<br />
<br />
:::Thank you but system UID/GID are defined by SYS_UID_MIN (500) and SYS_UID_MAX (999) (defined in /etc/login.defs) and some tools use those numbers to differentiate between system user and normal user. (and warn if system user is being deleted) Reserving range of system UID/GID for administrator use, helps for coders who develop their own daemons and want to make sure that in future UID/GID do not conflict.<br />
:::[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 09:55, 16 August 2017 (UTC)<br />
<br />
== GIDs are now generated dynamically / the static GIDs here are not valid anymore ==<br />
<br />
After recent changes to the filesystem package GIDs are now created by sysusers.d(5). The means, that for example the "users" group does not have a static id of 100 anymore. So, the information here is outdated and needs to be updated to reflect the dynamic id allocation. Either that, or there is a possibilty to set static user ids with sysusers.d, but I haven't investigated this yet.<br />
<br />
[[User:Jrk|Jrk]] ([[User talk:Jrk|talk]]) 11:50, 14 December 2017 (UTC)<br />
<br />
: I'm not following this argument: just because GIDs are created by sysusers.d, why does this mean the users group doesn't have a static id any more? [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:21, 18 March 2019 (UTC)<br />
<br />
== The sudo group is missing. Other distros have this gid set to 27 ==<br />
<br />
For some reason I'm not able to edit this page, but it would be a good idea to include sudo = 27 as per at least Ubuntu/Debian. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:24, 18 March 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=DeveloperWiki_talk:UID_/_GID_Database&diff=569041DeveloperWiki talk:UID / GID Database2019-03-18T11:21:39Z<p>Pgoetz: Questioning the reasoning behind this statement</p>
<hr />
<div>{{Note|'''Moderation''': [[AUR]] packages are unsupported content. This page is about packages in the [[official repositories]]. If you wish to reserve groups, or otherwise request features, use the bugtracker: https://bugs.archlinux.org/. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:11, 17 March 2016 (UTC)}}<br />
<br />
== Create users at build time ==<br />
<br />
Why should user and group be created at build time? This sounds really weird to me.<br />
Arch packages aren't supposed to be shared? You can very well build a package and not install it immediately.<br />
<br />
In any cases, I think this task definitively needs to be made at install time.<br />
That is why it is always done in scriptlets.<br />
Now what you might want to do is somehow unifying this task inside the scriptlets.<br />
If that's the case, please add your proposal with the two functions there :<br />
[https://bugs.archlinux.org/task/10375 FS#10375]<br />
and maybe edit the wiki accordingly.<br />
--[[User:Shining|shining]] 04:42, 19 May 2008 (EDT)<br />
<br />
== Add svn user and group ==<br />
<br />
Just a suggestion:<br />
create/reserve UID 44 and GID 44 for snv user ([http://subversion.tigris.org subversion] server)<br />
<br />
== mailman ==<br />
<br />
Can we have UID and GID 97 set aside for mailman? http://www.list.org<br />
<br />
EDIT: 91 is used for video apparently, changed to 97<br />
<br />
== kodi ==<br />
<br />
Before the xbmc package just created a system user and in the install script it always did a chown to make sure the /var/lib/xbmc folder was owned by xbmc.<br />
<br />
Now the folder is owned by uid 420 and gid 420, the chown is only needed when updating from a previous state.<br />
<br />
Could someone add the xbmc uid and gid to the list?<br />
<br />
:Now {{Pkg|kodi}}. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:13, 23 October 2015 (UTC)<br />
<br />
== lightdm ==<br />
<br />
The lightdm package uses {{ic|620}} for it's UID/GUID:<br />
<br />
{{bc|1=<nowiki><br />
post_install() {<br />
getent group lightdm > /dev/null 2>&1 || groupadd -g 620 lightdm<br />
getent passwd lightdm > /dev/null 2>&1 || useradd -c 'Light Display Manager' -u 620 -g lightdm -d /var/lib/lightdm -s /usr/bin/nologin lightdm<br />
passwd -l lightdm > /dev/null<br />
systemd-tmpfiles --create /usr/lib/tmpfiles.d/lightdm.conf<br />
}<br />
</nowiki>}}<br />
<br />
== Reserve UID/GID for system administrators? ==<br />
<br />
Standardization of UID/GID is nice thing but currently I believe it is assigned randomly based on package maintainer request.<br />
<br />
I need to create 2-3 system users on many machines where assumption is UID/GID will be same in all machines.<br />
<br />
But I fear that in future Arch may allocate that UID/GID to some "new" popular package.<br />
<br />
Because in that case then I will have to change UID/GID of my system users on all machines as well as chown all files owned by those UID/GID.<br />
<br />
So if we can reserve some fifty to hundred UIDs (say from 800 to 850 OR 800 to 900) for system adminitrator's use only, then it would be nice for administrators like me.<br />
<br />
[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 16:36, 21 May 2017 (UTC)<br />
<br />
:Is this right place for discussing this?<br />
:<br />
:This is something like systemd where /usr is used for defaults and /etc is used for system administrators so as to avoid conflicts<br />
:<br />
:Sameway UID/GID from 800 to 850/900 can be reserved to be used by system administrators without worrying that it would be used by some other package in future and create conflict.<br />
:<br />
:[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 04:56, 16 August 2017 (UTC)<br />
<br />
::As you can see from the list, Arch has reserved less than 1000 UIDs out of [https://serverfault.com/questions/105260/how-big-in-bits-is-a-unix-uid some very large number]. ''useradd'' assigns UIDs from 1000 to 60000 and [[systemd-nspawn]] uses UIDs larger than 65536 for [[systemd-nspawn#Creating private users (unprivileged containers)|unprivileged containers]]. So if you use UIDs around 60000 for your own purposes, there is very good chance that it won't conflict with anything. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:22, 16 August 2017 (UTC)<br />
<br />
:::Thank you but system UID/GID are defined by SYS_UID_MIN (500) and SYS_UID_MAX (999) (defined in /etc/login.defs) and some tools use those numbers to differentiate between system user and normal user. (and warn if system user is being deleted) Reserving range of system UID/GID for administrator use, helps for coders who develop their own daemons and want to make sure that in future UID/GID do not conflict.<br />
:::[[User:Amish|Amish]] ([[User talk:Amish|talk]]) 09:55, 16 August 2017 (UTC)<br />
<br />
== GIDs are now generated dynamically / the static GIDs here are not valid anymore ==<br />
<br />
After recent changes to the filesystem package GIDs are now created by sysusers.d(5). The means, that for example the "users" group does not have a static id of 100 anymore. So, the information here is outdated and needs to be updated to reflect the dynamic id allocation. Either that, or there is a possibilty to set static user ids with sysusers.d, but I haven't investigated this yet.<br />
<br />
[[User:Jrk|Jrk]] ([[User talk:Jrk|talk]]) 11:50, 14 December 2017 (UTC)<br />
<br />
: I'm not following this argument: just because GIDs are created by sysusers.d, why does this mean the users group doesn't have a static id any more? [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 11:21, 18 March 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=568878Creating packages2019-03-16T12:20:23Z<p>Pgoetz: minor clarification on language that confused at least me previously</p>
<hr />
<div>[[Category:About Arch]]<br />
[[Category:Package development]]<br />
[[cs:Creating packages]]<br />
[[es:Creating packages]]<br />
[[fa:ایجاد بستهها]]<br />
[[fr:Standard paquetage]]<br />
[[it:Creating packages]]<br />
[[ja:パッケージの作成]]<br />
[[pt:Creating packages]]<br />
[[ru:Creating packages]]<br />
[[zh-hans:Creating packages]]<br />
{{Related articles start}}<br />
{{Related|Arch Build System}}<br />
{{Related|Arch packaging standards}}<br />
{{Related|Arch User Repository}}<br />
{{Related|Creating packages for other distributions}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related|Patching in ABS}}<br />
{{Related|PKGBUILD}}<br />
{{Related|.SRCINFO}}<br />
{{Related|DeveloperWiki:Building in a Clean Chroot}}<br />
{{Related articles end}}<br />
<br />
This article aims to assist users creating their own packages using the Arch Linux "ports-like" [[Arch Build System|build system]], also for submission in [[AUR]]. It covers creation of a [[PKGBUILD]] &ndash; a package build description file sourced by {{ic|makepkg}} to create a binary package from source. If already in possession of a {{ic|PKGBUILD}}, see [[makepkg]]. For instructions regarding existing rules and ways to improve package quality see [[Arch packaging standards]].<br />
<br />
== Overview == <br />
<br />
Packages in Arch Linux are built using the [[makepkg]] utility and the information stored in a [[PKGBUILD]] file. When {{ic|makepkg}} runs, it searches for a {{ic|PKGBUILD}} in the current directory and follows the instructions in it to acquire the required files and/or compile them to be packed within a package file ({{ic|pkgname.pkg.tar.xz}}). The resulting package contains binary files and installation instructions ready to be installed by [[pacman]].<br />
<br />
An Arch package is no more than a tar archive, or 'tarball', compressed using {{man|1|xz}}, which contains the following files generated by makepkg:<br />
<br />
* The binary files to install.<br />
* {{ic|.PKGINFO}}: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
* {{ic|.BUILDINFO}}: contains information needed for reproducible builds. This file is present only if a package is built with pacman 5.1 or newer.<br />
* {{ic|.MTREE}}: contains hashes and timestamps of the files, which are included in the local database so that pacman can verify the integrity of the package.<br />
* {{ic|.INSTALL}}: an optional file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the {{ic|PKGBUILD}}.)<br />
* {{ic|.Changelog}}: an optional file kept by the package maintainer documenting the changes of the package. (It is not present in all packages.)<br />
<br />
== Preparation ==<br />
<br />
=== Prerequisite software ===<br />
<br />
First, ensure that the necessary tools are [[install]]ed: the package group {{Grp|base-devel}} should be sufficient, it includes {{ic|make}} and additional tools needed for compiling from source.<br />
<br />
The key tool for building packages is [[makepkg]] (provided by {{Pkg|pacman}}), which does the following:<br />
<br />
# Checks if package dependencies are installed.<br />
# Downloads the source file(s) from the specified server(s).<br />
# Unpacks the source file(s).<br />
# Compiles the software and installs it under a fakeroot environment.<br />
# Strips symbols from binaries and libraries.<br />
# Generates the package meta file which is included with each package.<br />
# Compresses the fakeroot environment into a package file.<br />
# Stores the package file in the configured destination directory, which is the current working directory by default.<br />
<br />
=== Download and test the installation ===<br />
<br />
Download the source tarball of the software you want to package, extract it, and follow the author's steps to install the program. Make a note of all commands and/or steps needed to compile and install it. You will be repeating those same commands in the {{ic|PKGBUILD}} file.<br />
<br />
Most software authors stick to the 3-step build cycle:<br />
<br />
./configure<br />
make<br />
make install<br />
<br />
This is a good time to make sure the program is working correctly.<br />
<br />
== Creating a PKGBUILD ==<br />
<br />
When {{ic|makepkg}} is run, it looks for a {{ic|PKGBUILD}} file in the current working directory. If it finds one, it downloads the software's source code and compiles it according to the instructions specified in the {{ic|PKGBUILD}} file. The instructions must be fully interpretable by the [[Wikipedia:Bash_(Unix_shell)|Bash]] shell. After successful completion, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a {{ic|pkgname.pkg.tar.xz}} package file. The newly created package can be installed by simply using {{ic|makepkg --install}} which will call pacman in the background, or by directly using {{ic|pacman -U ''pkgname.pkg.tar.xz''}}.<br />
<br />
To start building a new package, first create a new directory for the package and change current directory into this one. Then, a {{ic|PKGBUILD}} file needs to be created: a prototype PKGBUILD found in {{ic|/usr/share/pacman/}} can be used or you can start from a {{ic|PKGBUILD}} from another package. The latter may be a good choice if a similar package already exists.<br />
<br />
=== Defining PKGBUILD variables ===<br />
<br />
Example PKGBUILDs are located in {{Ic|/usr/share/pacman/}}. An explanation of possible {{ic|PKGBUILD}} variables can be found in the [[PKGBUILD]] article.<br />
<br />
''makepkg'' defines two variables that you should use as part of the build and install process:<br />
<br />
; {{ic|srcdir}}: This points to the directory where ''makepkg'' extracts or symlinks all files in the source array.<br />
<br />
; {{ic|pkgdir}}: This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package.<br />
<br />
They contain ''absolute'' paths, which means you do not have to worry about your working directory if you use these variables properly.<br />
<br />
{{Note|''makepkg'', and thus the {{ic|build()}} and {{ic|package()}} functions, are intended to be non-interactive. Interactive utilities or scripts called in those functions may break ''makepkg'', particularly if it is invoked with build-logging enabled ({{ic|-L}}). (See {{Bug|13214}}.)}}<br />
<br />
=== PKGBUILD functions ===<br />
<br />
There are five functions, listed here in the order they are executed. Beside the fifth function, {{ic|package()}}, which is required in every PKGBUILD, if one function does not exist it is simply skipped.<br />
<br />
==== prepare() ====<br />
<br />
With this function, commands that are used to prepare sources for building are run, such as [[Patching in ABS|patching]]. This function runs right after package extraction, before [[#pkgver()|pkgver()]] and the build function. If extraction is skipped ({{ic|makepkg -e}}), then {{ic|prepare()}} is not run. <br />
<br />
{{Note|(From {{man|5|PKGBUILD}}) The function is run in {{ic|bash -e}} mode, meaning any command that exits with a non-zero status will cause the function to exit.}}<br />
<br />
==== pkgver() ====<br />
<br />
{{ic|pkgver()}} runs after the sources are fetched, extracted and [[#prepare()|prepare()]] executed. So you can update the pkgver variable during a makepkg stage.<br />
<br />
This is particularly useful if you are [[VCS PKGBUILD Guidelines|making git/svn/hg/etc. packages]], where the build process may remain the same, but the source could be updated every day, even every hour. The old way of doing this was to put the date into the pkgver field which, if the software was not updated, makepkg would still rebuild it thinking the version had changed. Some useful commands for this are {{ic|git describe}}, {{ic|hg identify -ni}}, etc. Please test these before submitting a PKGBUILD, as a failure in the {{ic|pkgver()}} function can stop a build in its tracks. <br />
<br />
{{Note|pkgver cannot contain spaces or hyphens ({{ic|-}}). Using sed to correct this is common.}}<br />
<br />
==== build() ====<br />
<br />
Now you need to implement the {{ic|build()}} function in the {{ic|PKGBUILD}} file. This function uses common shell commands in [[Wikipedia:Bash_(Unix_shell)|Bash]] syntax to automatically compile software and create a directory called {{ic|pkg}} to install the software to. This allows ''makepkg'' to package files without having to sift through your file system.<br />
<br />
The first step in the {{ic|build()}} function is to change into the directory created by uncompressing the source tarball. ''makepkg'' will change the current directory to {{ic|$srcdir}} before executing the {{ic|build()}} function. Therefore, in most cases, like suggested in {{ic|/usr/share/pacman/PKGBUILD.proto}}, the first command will look like this:<br />
<br />
cd "$pkgname-$pkgver"<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The {{ic|build()}} function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use {{ic|1=--prefix=/usr}} when building packages for pacman. A lot of software installs files relative to the {{ic|/usr/local}} directory, which should only be done if you are manually building from source. All Arch Linux packages should use the {{ic|/usr}} directory. As seen in the {{ic|/usr/share/pacman/PKGBUILD.proto}} file, the next two lines often look like this:<br />
<br />
./configure --prefix=/usr<br />
make<br />
<br />
{{Note|If your software does not need to build anything, do not use the {{ic|build()}} function. The {{ic|build()}} function is not required, but the {{ic|package()}} function is.}}<br />
<br />
==== check() ====<br />
<br />
Place for calls to {{Ic|make check}} and similar testing routines. It is highly recommended to have {{Ic|check()}} as it helps to make sure software has been built correctly and works fine with its dependencies.<br />
<br />
Users who do not need it (and occasionally maintainers who can not fix a package for this to pass) can disable it using {{ic|1=BUILDENV+=('!check')}} in PKGBUILD/makepkg.conf or call {{ic|makepkg}} with {{ic|--nocheck}} flag.<br />
<br />
==== package() ====<br />
<br />
The final step is to put the compiled files in a directory where ''makepkg'' can retrieve them to create a package. This by default is the {{ic|pkg}} directory—a simple fakeroot environment. The {{ic|pkg}} directory replicates the hierarchy of the root file system of the software's installation paths. If you have to manually place files under the root of your filesystem, you should install them in the {{ic|pkg}} directory under the same directory structure. For example, if you want to install a file to {{ic|/usr/bin}}, it should instead be placed under {{ic|$pkgdir/usr/bin}}. Very few install procedures require the user to copy dozens of files manually. Instead, for most software, calling {{ic|make install}} will do so. The final line should look like the following in order to correctly install the software in the {{ic|pkg}} directory:<br />
<br />
make DESTDIR="$pkgdir/" install<br />
<br />
{{Note|It is sometimes the case where {{ic|DESTDIR}} is not used in the {{ic|Makefile}}; you may need to use {{ic|prefix}} instead. If the package is built with ''autoconf'' / ''automake'', use {{ic|DESTDIR}}; this is what is [https://www.gnu.org/software/automake/manual/automake.html#Install documented] in the manuals. If {{ic|DESTDIR}} does not work, try building with {{ic|1=make prefix="$pkgdir/usr/" install}}. If that does not work, you will have to look further into the install commands that are executed by "{{ic|make <...> install}}".}}<br />
<br />
{{ic|makepkg --repackage}} runs only the {{ic|package()}} function, so it creates a package without building. This may save time e.g. if you have changed just the {{ic|depends}} variable of the package.<br />
<br />
== Testing the PKGBUILD and package ==<br />
<br />
As you are writing the {{ic|build()}} function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the {{ic|makepkg}} command in the directory containing the {{ic|PKGBUILD}} file. With a properly formatted {{ic|PKGBUILD}}, makepkg will create a package; with a broken or unfinished {{ic|PKGBUILD}}, it will raise an error.<br />
<br />
If makepkg finishes successfully, it will place a file named {{ic|pkgname-pkgver.pkg.tar.xz}} in your working directory. This package can be installed with the {{ic|pacman -U}} command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use pacman's query functions to display a list of files contained in the package and the dependencies it requires with {{ic|pacman -Qlp [package file]}} and {{ic|pacman -Qip [package file]}} respectively.<br />
<br />
If the package looks sane, then you are done! However, if you plan on releasing the {{ic|PKGBUILD}} file, it is imperative that you check and double-check the contents of the {{ic|depends}} array. <br />
<br />
Also ensure that the package binaries actually ''run'' flawlessly! It is annoying to release a package that contains all necessary files, but crashes because of some obscure configuration option that does not quite work well with the rest of the system. If you are only going to compile packages for your own system, though, you do not need to worry too much about this quality assurance step, as you are the only person suffering from mistakes, after all.<br />
<br />
=== Checking package sanity ===<br />
<br />
After testing package functionality check it for errors using [[namcap]]:<br />
$ namcap PKGBUILD<br />
$ namcap ''<package file name>''.pkg.tar.xz<br />
<br />
Namcap will:<br />
<br />
# Check PKGBUILD contents for common errors and package file hierarchy for unnecessary/misplaced files<br />
# Scan all ELF files in package using {{ic|ldd}}, automatically reporting which packages with required shared libraries are missing from {{Ic|depends}} and which can be omitted as transitive dependencies<br />
# Heuristically search for missing and redundant dependencies<br />
<br />
and much more.<br />
<br />
Get into the habit of checking your packages with namcap to avoid having to fix the simplest mistakes after package submission.<br />
<br />
== Submitting packages to the AUR ==<br />
<br />
Please read [[AUR User Guidelines#Submitting packages]] for a detailed description of the submission process.<br />
<br />
== Summary ==<br />
<br />
# Download the source tarball of the software to package.<br />
# Try compiling the package and installing it into an arbitrary directory.<br />
# Copy over the prototype {{ic|/usr/share/pacman/PKGBUILD.proto}} and rename it to {{ic|PKGBUILD}} in a temporary working directory.<br />
# Edit the {{ic|PKGBUILD}} according to the needs of your package.<br />
# Run {{ic|makepkg}} and check whether the package builds correctly.<br />
# If not, repeat the previous two steps.<br />
<br />
=== Warnings ===<br />
<br />
* Before you can automate the package building process, you should have done it manually at least once unless you know ''exactly'' what you are doing ''in advance'', in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "{{ic|./configure}}; {{ic|make}}; {{ic|make install}}", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you cannot get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you do not even need to try packaging it. There is not any magic pixie dust in {{ic|makepkg}} that makes source problems go away.<br />
* In a few cases, the packages are not even available as source and you have to use something like {{ic|sh installer.run}} to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from Gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However, {{ic|makepkg}} needs to be completely autonomous, with no user input. Therefore if you need to edit the makefiles, you may have to bundle a custom patch with the {{ic|PKGBUILD}} and install it from inside the {{ic|prepare()}} function, or you might have to issue some {{ic|sed}} commands from inside the {{ic|prepare()}} function.<br />
<br />
== More detailed guidelines ==<br />
<br />
{{Package guidelines}}<br />
<br />
== PKGBUILD generators ==<br />
<br />
PKGBUILDs for some packages can be generated automatically.<br />
<br />
{{Note|Users are still responsible for ensuring that the package meets the high quality standards before submitting the generated files to the [[AUR]].}}<br />
<br />
* [[Go]]: [https://github.com/seletskiy/go-makepkg go-makepkg]<br />
* [[Haskell]]: [https://github.com/magthe/cblrepo cblrepo]<br />
* [[Node.js]]: {{AUR|nodejs-npm2arch}} [https://github.com/simon04/npm2arch|igorvisi npm2arch]<br />
* [[Python]]: {{AUR|pipman-git}}, {{AUR|pip2arch-git}}, {{AUR|python-pypi2pkgbuild}}<br />
* [[Ruby]]: {{AUR|gem2arch}}, {{AUR|pacgem}}<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=91408 How to correctly create a patch file].<br />
* [https://archwomen.org/media/project_classroom/classlogs/ Arch Linux Classroom IRC Logs of classes about creating PKGBUILDs].<br />
* [http://www.linuxfromscratch.org/hints/downloads/files/fakeroot.txt Fakeroot approach for package installation]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Arch_package_guidelines&diff=568646Talk:Arch package guidelines2019-03-13T22:20:13Z<p>Pgoetz: added signature</p>
<hr />
<div>== Fields order ==<br />
<br />
[[Arch_Packaging_Standards#Package_etiquette]] states: "It is common practice to preserve the order of the PKGBUILD fields as shown above." But this is not true. Common practice is to use {{ic|/usr/share/pacman/PKGBUILD.proto}} as a template, and the order of fields in that prototype has a far greater influence on packages in the wild than this page. This page should edited to reflect the current state of {{ic|PKGBUILD.proto}}. Perhaps this page should state: "It is common practice to order PKGBUILD fields so they match the order of fields in {{ic|PKGBUILD.proto}}. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 14:32, 19 October 2013 (UTC)<br />
<br />
== Punctuation in PKGBUILD ==<br />
What is the official guidance regarding ending a pkgdesc in a period or using commas and English prose punctuation in general?<br />
<br />
[[https://bbs.archlinux.org/viewtopic.php?pid=1288063 Link]] to discussion thread.<br />
<br />
[[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 15:17, 14 June 2013 (UTC)<br />
<br />
==Package naming==<br />
* Package names should consist of '''alphanumeric characters only'''; all letters should be '''lowercase'''.<br />
:--unsigned<br />
<br />
::This is a guideline, but I see some packages with hypens and underscores (tesseract-data-chi_sim), dots (gstreamer0.10), plus (libxml++) and even at-signs (kde-l10n-ca@valencia). A package with uppercase name is libreoffice-bn-IN. According to the makepkg source, the allowed chars are: {{ic|[:alnum:]+_.@-}}. [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
:::"alphanumeric characters only" rule is ridiculous, 85% of official packages break this rule. I think it should be changed to allow hypens. It makes package names more readable. In regards to other characters, the + sign breaks [https://aur.archlinux.org/rpc.php AUR search] ([https://aur.archlinux.org/rpc.php?type=search&arg=a++ example], [https://aur.archlinux.org/rpc.php?type=search&arg=a%2B%2B should be escaped]). [[User:Axper|axper]] ([[User talk:Axper|talk]]) 11:19, 11 May 2014 (UTC)<br />
<br />
* Package names should NOT be suffixed with the upstream major release version number (e.g. we don't want libfoo2 if upstream calls it libfoo v2.3.4) in case the library and its dependencies are expected to be able to keep using the most recent library version with each respective upstream release. However, for some software or dependencies, this can not be assumed. In the past this has been especially true for widget toolkits such as GTK and Qt. Software that depends on such toolkits can usually not be trivially ported to a new major version. As such, in cases where software can not trivially keep rolling alongside its dependencies, package names should carry the major version suffix (e.g. gtk2, gtk3, qt4, qt5). For cases where most dependencies can keep rolling along the newest release but some can't (for instance closed source that needs libpng12 or similar), a deprecated version of that package might be called libfoo1 while the current version is just libfoo.<br />
:--unsigned<br />
<br />
* Package versions '''should be the same as the version released by the author'''. Versions can include letters if need be (eg, nmap's version is 2.54BETA32). '''Version tags may not include hyphens!''' Letters, numbers, and periods only.<br />
:--unsigned<br />
<br />
::This rule needs to get more stricter. Having a slash in the version breaks filenames. For craziness, I tried setting up a pkgver containing all characters from 0x01 to 0xff which makes makepkg throw a Bash syntax error. The current packages have versions matching {{ic}[[alnum:]._+~]+} (and a colon for epoch, a hypen for pkgrel). What about limiting to those characters? Debian has a similar set, see [https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version their policy docs] [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
* Package releases are '''specific to Arch Linux packages'''. These allow users to differentiate between newer and older package builds. When a new package version is first released, the '''release count starts at 1'''. Then as fixes and optimizations are made, the package will be '''re-released''' to the Arch Linux public and the '''release number will increment'''. When a new version comes out, the release count resets to 1. Package release tags follow the '''same naming restrictions as version tags'''.<br />
:--unsigned<br />
<br />
* Why is there no mentioning of suffixes for different build sources, such as vcs sources (-git, -hg, …) or binary distributions (-bin)? IMO this is an important part of the package naming conventions in AUR. [[User:Fordprefect|Fordprefect]] ([[User talk:Fordprefect|talk]]) 13:43, 10 May 2016 (UTC)<br />
<br />
::Some of the information is sequestered into the AUR page's FAQ and other places, but I have [[Talk:Creating packages#Proposal: Creating a PKGBUILD: Package naming conventions|a proposal]] to bring it together (and add some additional conventions). Since this page already has a section on package naming conventions, it would integrate well here. Unfortunately, as this is a protected page, I wouldn't be able to make the edits myself. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 15:29, 23 February 2019 (UTC)<br />
<br />
::[[User:Quequotion/Arch package guidelines#Package naming|Here]]'s a whole-page draft of what that might look like. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 16:04, 23 February 2019 (UTC)<br />
<br />
=== Proposal: Additional Conventions ===<br />
<br />
* Packages having extra features enabled and/or patches in comparison to the official ones should be named differently to express that. For example, a package for GNU {{Pkg|screen}} containing the sidebar patch could be named {{ic|screen-sidebar}}. Additionally the {{ic|1=provides=('screen')}} array should be used to avoid conflicts with the official package and satisfy its dependents.<br />
<br />
See also individual package guidelines pages for their particular naming conventions.<br />
<br />
== Is it acceptable for build() to start by removing directories? ==<br />
<br />
I just downloaded a PKGBUILD whose build() function begins with the following:<br />
<br />
find ./ -maxdepth 1 -mindepth 1 -type d -exec rm -r {} \;<br />
<br />
It seems to me that a PKGBUILD has no business doing this and that it is potentially dangerous. I admit that its danger will typically require people to do non-standard things and, arguably, things they would be better advised not to do anyway. But it still seems to me to invite trouble.<br />
<br />
I don't remember seeing this in a PKGBUILD before but I can't find anything definitely ruling it out.<br />
<br />
Is it acceptable for a build function to start by removing directories in this way? Is it safe?<br />
<br />
--[[User:Margali|cfr]] ([[User talk:Margali|talk]]) 03:03, 27 February 2014 (UTC)<br />
<br />
: I'd argue that this is an acceptable thing to do, at least in some cases. As an example, consider [http://www.talend.com/products/data-integration Talend Open Studio DI]: a single source file provides files for Windows, Linux, Mac OS, PowerPC (?) and Solaris. In response, the {{AUR|talend-open-studio-di}} PKGBUILD simply removes them. Does removing those files invite trouble? Yes. But removing files seems like an integral tool in the package maintainer's toolkit, and plenty of other weird stuff happens in PKGBUILDs too. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 02:20, 3 March 2014 (UTC)<br />
<br />
== Unique sources ==<br />
<br />
The source array should only contain unique sources names if a shares source directory is used. This applies to most github download. You can use "${pkgname}-${pkgver}.tar.gz::" prependet to each source to make the filename unique. <br />
I am not allowed to edit the page, could someone please do so?--[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 15:33, 16 December 2016 (UTC)<br />
<br />
== Add security standards ==<br />
<br />
As we decided to use https and GPG wherever possible for PKGBUILDs this should be added here as well. A Link to the mailing list would be also nice. The usage of strong hashes could also be mentioned, but I assume some people will not like the idea. A Link to the discussion about the hashes could also help for everyone to get his own opinion. It should be also mentioned that maintainers still need to validate the content of the downloads and test the update. Another important point is to contact upstream for GPG signatures if they are not available yet. One can link to some templates/tutorials I made on nicohood.de --[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 19:40, 16 December 2016 (UTC)<br />
<br />
:Forget about the checksums part, as it was already declined multiple times by the developers. For the rest, patches welcome. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:19, 16 December 2016 (UTC)<br />
:edit: see also [[User:Apg#makepkg:_replace_default_checksums]] -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:21, 14 March 2017 (UTC)<br />
<br />
== Architecture Section not clear enough ==<br />
<br />
The arch array depends "on which architectures it can be built on". This is okay but I believe it should be clarified that the program also needs to run and work on that architecture. I know it's a bit "obvious" but people who write interpreted programs may understand that they should put "any" in the arch array even if their program is not usable at all for some architectures. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 07:14, 28 April 2017 (UTC)<br />
<br />
:How does fixing "built on" to "built for" prevent people from abusing {{ic|any}}? That's a separate problem. Also, interpreted programs like scripts ''should'' use {{ic|any}}, where do you think they shouldn't? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:39, 28 April 2017 (UTC)<br />
<br />
::There is that program (debtap in AUR) wrote in bash that converts deb packages to Arch Linux packages. Unfortunately the program works only for i386 and amd64 because it fetches Ubuntu repositories at some specific locations. So when you run it on an arm architecture it fails with a curl output saying 404 which is not user friendly at all. IMHO a package should be restricted to the architectures where it works but in the specifications here, the only requirement is that it compiles. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 09:08, 28 April 2017 (UTC)<br />
<br />
:::Actually it is better specified here: [[PKGBUILD#arch]] "If instead a package can be compiled for any architecture, but is architecture-specific once compiled, specify all architectures officially supported by Arch, i.e. arch=('i686' 'x86_64'). " [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 10:10, 29 April 2017 (UTC)<br />
<br />
Since we no longer support i686 and the section had to be edited anyway, I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=507402&oldid=485119 tried to clarify] the situation described above. I don't think it should include something like ".. and any other architectures the package builds/compiles/runs on", as we only support x86_64. None of the packages in the official repositories specify architectures besides 'x86_64' and 'any' (I think). [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 15:41, 13 January 2018 (UTC)<br />
:Maybe we should just do like we do for Licenses, and say "See [[PKGBUILD#arch]]". I think we explain in sufficient detail there. :) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 03:26, 14 January 2018 (UTC)<br />
<br />
::Not saying it's a bad thing, but following this approach there wouldn't be much left of the ''official'' packaging guidelines... The purpose of the entire page should be rethought. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:41, 14 January 2018 (UTC)<br />
<br />
== /opt vs /usr/share ==<br />
<br />
Should there be a clause here or somewhere about preferring {{ic|/opt}} for big/self-contained AUR packages instead of {{ic|/usr/share}}? Isn't there such a policy? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 17:17, 21 May 2017 (UTC)<br />
<br />
:That's somewhat covered by the [http://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html FHS]. There's no reason to make it specific only to AUR, even official packages like {{Pkg|cuda}} or {{Pkg|vtk6}} are installed into {{ic|/opt}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:34, 21 May 2017 (UTC)<br />
<br />
::Do you mean that actual page? So sections like [[Arch packaging standards#Directories]] should really be replaced with a link there? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 19:02, 21 May 2017 (UTC)<br />
<br />
:::There you go, you even ''have'' the policy, so what's the point of this discussion really?? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:07, 21 May 2017 (UTC)<br />
<br />
::::Alad, I'd appreciate it, if you didn't just come in and close an ongoing discussion. Anyway, so shouldn't that text be amended if that small piece is our official guideline? 1) Java is not installed in {{ic|/opt}} (neither {{Pkg|jre7-openjdk}} nor {{Pkg|jre8-openjdk}}), 2) what is a "self-contained" package? Can it have e.g. icons and desktop files in {{ic|/usr}}? I would hope so. —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 21:19, 21 May 2017 (UTC)<br />
<br />
:::::Det, you really need to improve the way you ask questions. We don't have telepathic powers like you might have, so there is no way we could have guessed from the first post that you want an explanation for a section that you linked in your second post. Please read the standard reference on this topic, [http://www.catb.org/~esr/faqs/smart-questions.html How To Ask Questions The Smart Way].<br />
:::::Now back to the topic. You're right about Java, so I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=477997&oldid=462352 removed] that example. There are multiple reasons to use {{ic|/opt}}, most often it is because it may be too hard or even impossible to merge the software with the system's {{ic|/usr}} hierarchy. For example the software might come with bundled libraries which may conflict with the system libraries, this is where the "self-contained" comes from. If you take a look at the content of the {{pkg|cuda}} package, you will see that manual pages, licenses and desktop files are installed into {{ic|/usr/share}}.<br />
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:17, 22 May 2017 (UTC)<br />
<br />
::::::Hmm. I don't think I was looking for an explanation to another article from the talk page of a different article. What "telepathic powers" that I "may have" have got to do with that, I've no clue. Also, I don't ''think'' I need patronisations about how to ask good questions. :-)<br />
::::::Anyway, as you can see from the flow of the conversation, first I thought there should be an AUR-specific instruction on {{ic|/opt}}. Then you say no, and there's also a different site. Then I ask about that other general one I found, different article, which is very cryptic, a bit out-of-date, and maybe that's the reason that it is. Then you respond, well exactly, that's what we already got, so why ask in the first place, and Alad closes the conversation?<br />
::::::Right? On the issue, I can see {{Pkg|cuda}} has its stuff elsewhere besides {{ic|/opt}}. ''However'', the ''point is'', why isn't it explained ''in that'' article? Why isn't ''your'' explanation in the article? Also, it currently says "large self-contained". What is the definition of ''large''? Smaller ones belong in {{ic|/usr}}?<br />
::::::''I'' don't need that explanation, the ''article'' needs it. People reading for the ''first time'' need it. Right? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 08:24, 22 May 2017 (UTC)<br />
<br />
== Directories -- Why shouldn't /srv be used? ==<br />
<br />
I'm updating the AUR package for the cyrus-imapd package, and noticed that this guideline states that the /srv directory should not be included in the package. Persistent application data should be placed in /var/lib/{pkg}. I'm wondering if there is a good reason for this? From long experience, /var tends to include a lot of rapidly changing ephemeral data and often ends up on a (typically smaller and faster) OS disk partition. And in the past, mounting another partition to /var lead to timing issues. systemd has fixed the latter, but the former persists, and IMAP mail stores tend to grow quite large over time. As a result, I've adopted the convention of using /srv for data which is served out and which can grow in size indefinitely. Furthermore, this is precisely how the directory is intended to be used according to the FHS. So I'd like to put the IMAP user mail store in /srv/imap by default, and was planning to do so until I ran across this document. Sort of feeling like this specific instruction is out of date (but agree that the other directories listed shouldn't be used) [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 22:15, 13 March 2019 (UTC)<br />
: Adding to my own comment, for purposes of clarification. Again, from long experience, people find setting up an imap server to be complicated and intimidating, so it would be better to offer an a priori rational directory structure which needn't be modified after the fact. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 22:20, 13 March 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Arch_package_guidelines&diff=568645Talk:Arch package guidelines2019-03-13T22:19:49Z<p>Pgoetz: additional clarification</p>
<hr />
<div>== Fields order ==<br />
<br />
[[Arch_Packaging_Standards#Package_etiquette]] states: "It is common practice to preserve the order of the PKGBUILD fields as shown above." But this is not true. Common practice is to use {{ic|/usr/share/pacman/PKGBUILD.proto}} as a template, and the order of fields in that prototype has a far greater influence on packages in the wild than this page. This page should edited to reflect the current state of {{ic|PKGBUILD.proto}}. Perhaps this page should state: "It is common practice to order PKGBUILD fields so they match the order of fields in {{ic|PKGBUILD.proto}}. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 14:32, 19 October 2013 (UTC)<br />
<br />
== Punctuation in PKGBUILD ==<br />
What is the official guidance regarding ending a pkgdesc in a period or using commas and English prose punctuation in general?<br />
<br />
[[https://bbs.archlinux.org/viewtopic.php?pid=1288063 Link]] to discussion thread.<br />
<br />
[[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 15:17, 14 June 2013 (UTC)<br />
<br />
==Package naming==<br />
* Package names should consist of '''alphanumeric characters only'''; all letters should be '''lowercase'''.<br />
:--unsigned<br />
<br />
::This is a guideline, but I see some packages with hypens and underscores (tesseract-data-chi_sim), dots (gstreamer0.10), plus (libxml++) and even at-signs (kde-l10n-ca@valencia). A package with uppercase name is libreoffice-bn-IN. According to the makepkg source, the allowed chars are: {{ic|[:alnum:]+_.@-}}. [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
:::"alphanumeric characters only" rule is ridiculous, 85% of official packages break this rule. I think it should be changed to allow hypens. It makes package names more readable. In regards to other characters, the + sign breaks [https://aur.archlinux.org/rpc.php AUR search] ([https://aur.archlinux.org/rpc.php?type=search&arg=a++ example], [https://aur.archlinux.org/rpc.php?type=search&arg=a%2B%2B should be escaped]). [[User:Axper|axper]] ([[User talk:Axper|talk]]) 11:19, 11 May 2014 (UTC)<br />
<br />
* Package names should NOT be suffixed with the upstream major release version number (e.g. we don't want libfoo2 if upstream calls it libfoo v2.3.4) in case the library and its dependencies are expected to be able to keep using the most recent library version with each respective upstream release. However, for some software or dependencies, this can not be assumed. In the past this has been especially true for widget toolkits such as GTK and Qt. Software that depends on such toolkits can usually not be trivially ported to a new major version. As such, in cases where software can not trivially keep rolling alongside its dependencies, package names should carry the major version suffix (e.g. gtk2, gtk3, qt4, qt5). For cases where most dependencies can keep rolling along the newest release but some can't (for instance closed source that needs libpng12 or similar), a deprecated version of that package might be called libfoo1 while the current version is just libfoo.<br />
:--unsigned<br />
<br />
* Package versions '''should be the same as the version released by the author'''. Versions can include letters if need be (eg, nmap's version is 2.54BETA32). '''Version tags may not include hyphens!''' Letters, numbers, and periods only.<br />
:--unsigned<br />
<br />
::This rule needs to get more stricter. Having a slash in the version breaks filenames. For craziness, I tried setting up a pkgver containing all characters from 0x01 to 0xff which makes makepkg throw a Bash syntax error. The current packages have versions matching {{ic}[[alnum:]._+~]+} (and a colon for epoch, a hypen for pkgrel). What about limiting to those characters? Debian has a similar set, see [https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version their policy docs] [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
* Package releases are '''specific to Arch Linux packages'''. These allow users to differentiate between newer and older package builds. When a new package version is first released, the '''release count starts at 1'''. Then as fixes and optimizations are made, the package will be '''re-released''' to the Arch Linux public and the '''release number will increment'''. When a new version comes out, the release count resets to 1. Package release tags follow the '''same naming restrictions as version tags'''.<br />
:--unsigned<br />
<br />
* Why is there no mentioning of suffixes for different build sources, such as vcs sources (-git, -hg, …) or binary distributions (-bin)? IMO this is an important part of the package naming conventions in AUR. [[User:Fordprefect|Fordprefect]] ([[User talk:Fordprefect|talk]]) 13:43, 10 May 2016 (UTC)<br />
<br />
::Some of the information is sequestered into the AUR page's FAQ and other places, but I have [[Talk:Creating packages#Proposal: Creating a PKGBUILD: Package naming conventions|a proposal]] to bring it together (and add some additional conventions). Since this page already has a section on package naming conventions, it would integrate well here. Unfortunately, as this is a protected page, I wouldn't be able to make the edits myself. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 15:29, 23 February 2019 (UTC)<br />
<br />
::[[User:Quequotion/Arch package guidelines#Package naming|Here]]'s a whole-page draft of what that might look like. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 16:04, 23 February 2019 (UTC)<br />
<br />
=== Proposal: Additional Conventions ===<br />
<br />
* Packages having extra features enabled and/or patches in comparison to the official ones should be named differently to express that. For example, a package for GNU {{Pkg|screen}} containing the sidebar patch could be named {{ic|screen-sidebar}}. Additionally the {{ic|1=provides=('screen')}} array should be used to avoid conflicts with the official package and satisfy its dependents.<br />
<br />
See also individual package guidelines pages for their particular naming conventions.<br />
<br />
== Is it acceptable for build() to start by removing directories? ==<br />
<br />
I just downloaded a PKGBUILD whose build() function begins with the following:<br />
<br />
find ./ -maxdepth 1 -mindepth 1 -type d -exec rm -r {} \;<br />
<br />
It seems to me that a PKGBUILD has no business doing this and that it is potentially dangerous. I admit that its danger will typically require people to do non-standard things and, arguably, things they would be better advised not to do anyway. But it still seems to me to invite trouble.<br />
<br />
I don't remember seeing this in a PKGBUILD before but I can't find anything definitely ruling it out.<br />
<br />
Is it acceptable for a build function to start by removing directories in this way? Is it safe?<br />
<br />
--[[User:Margali|cfr]] ([[User talk:Margali|talk]]) 03:03, 27 February 2014 (UTC)<br />
<br />
: I'd argue that this is an acceptable thing to do, at least in some cases. As an example, consider [http://www.talend.com/products/data-integration Talend Open Studio DI]: a single source file provides files for Windows, Linux, Mac OS, PowerPC (?) and Solaris. In response, the {{AUR|talend-open-studio-di}} PKGBUILD simply removes them. Does removing those files invite trouble? Yes. But removing files seems like an integral tool in the package maintainer's toolkit, and plenty of other weird stuff happens in PKGBUILDs too. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 02:20, 3 March 2014 (UTC)<br />
<br />
== Unique sources ==<br />
<br />
The source array should only contain unique sources names if a shares source directory is used. This applies to most github download. You can use "${pkgname}-${pkgver}.tar.gz::" prependet to each source to make the filename unique. <br />
I am not allowed to edit the page, could someone please do so?--[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 15:33, 16 December 2016 (UTC)<br />
<br />
== Add security standards ==<br />
<br />
As we decided to use https and GPG wherever possible for PKGBUILDs this should be added here as well. A Link to the mailing list would be also nice. The usage of strong hashes could also be mentioned, but I assume some people will not like the idea. A Link to the discussion about the hashes could also help for everyone to get his own opinion. It should be also mentioned that maintainers still need to validate the content of the downloads and test the update. Another important point is to contact upstream for GPG signatures if they are not available yet. One can link to some templates/tutorials I made on nicohood.de --[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 19:40, 16 December 2016 (UTC)<br />
<br />
:Forget about the checksums part, as it was already declined multiple times by the developers. For the rest, patches welcome. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:19, 16 December 2016 (UTC)<br />
:edit: see also [[User:Apg#makepkg:_replace_default_checksums]] -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:21, 14 March 2017 (UTC)<br />
<br />
== Architecture Section not clear enough ==<br />
<br />
The arch array depends "on which architectures it can be built on". This is okay but I believe it should be clarified that the program also needs to run and work on that architecture. I know it's a bit "obvious" but people who write interpreted programs may understand that they should put "any" in the arch array even if their program is not usable at all for some architectures. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 07:14, 28 April 2017 (UTC)<br />
<br />
:How does fixing "built on" to "built for" prevent people from abusing {{ic|any}}? That's a separate problem. Also, interpreted programs like scripts ''should'' use {{ic|any}}, where do you think they shouldn't? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:39, 28 April 2017 (UTC)<br />
<br />
::There is that program (debtap in AUR) wrote in bash that converts deb packages to Arch Linux packages. Unfortunately the program works only for i386 and amd64 because it fetches Ubuntu repositories at some specific locations. So when you run it on an arm architecture it fails with a curl output saying 404 which is not user friendly at all. IMHO a package should be restricted to the architectures where it works but in the specifications here, the only requirement is that it compiles. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 09:08, 28 April 2017 (UTC)<br />
<br />
:::Actually it is better specified here: [[PKGBUILD#arch]] "If instead a package can be compiled for any architecture, but is architecture-specific once compiled, specify all architectures officially supported by Arch, i.e. arch=('i686' 'x86_64'). " [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 10:10, 29 April 2017 (UTC)<br />
<br />
Since we no longer support i686 and the section had to be edited anyway, I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=507402&oldid=485119 tried to clarify] the situation described above. I don't think it should include something like ".. and any other architectures the package builds/compiles/runs on", as we only support x86_64. None of the packages in the official repositories specify architectures besides 'x86_64' and 'any' (I think). [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 15:41, 13 January 2018 (UTC)<br />
:Maybe we should just do like we do for Licenses, and say "See [[PKGBUILD#arch]]". I think we explain in sufficient detail there. :) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 03:26, 14 January 2018 (UTC)<br />
<br />
::Not saying it's a bad thing, but following this approach there wouldn't be much left of the ''official'' packaging guidelines... The purpose of the entire page should be rethought. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:41, 14 January 2018 (UTC)<br />
<br />
== /opt vs /usr/share ==<br />
<br />
Should there be a clause here or somewhere about preferring {{ic|/opt}} for big/self-contained AUR packages instead of {{ic|/usr/share}}? Isn't there such a policy? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 17:17, 21 May 2017 (UTC)<br />
<br />
:That's somewhat covered by the [http://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html FHS]. There's no reason to make it specific only to AUR, even official packages like {{Pkg|cuda}} or {{Pkg|vtk6}} are installed into {{ic|/opt}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:34, 21 May 2017 (UTC)<br />
<br />
::Do you mean that actual page? So sections like [[Arch packaging standards#Directories]] should really be replaced with a link there? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 19:02, 21 May 2017 (UTC)<br />
<br />
:::There you go, you even ''have'' the policy, so what's the point of this discussion really?? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:07, 21 May 2017 (UTC)<br />
<br />
::::Alad, I'd appreciate it, if you didn't just come in and close an ongoing discussion. Anyway, so shouldn't that text be amended if that small piece is our official guideline? 1) Java is not installed in {{ic|/opt}} (neither {{Pkg|jre7-openjdk}} nor {{Pkg|jre8-openjdk}}), 2) what is a "self-contained" package? Can it have e.g. icons and desktop files in {{ic|/usr}}? I would hope so. —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 21:19, 21 May 2017 (UTC)<br />
<br />
:::::Det, you really need to improve the way you ask questions. We don't have telepathic powers like you might have, so there is no way we could have guessed from the first post that you want an explanation for a section that you linked in your second post. Please read the standard reference on this topic, [http://www.catb.org/~esr/faqs/smart-questions.html How To Ask Questions The Smart Way].<br />
:::::Now back to the topic. You're right about Java, so I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=477997&oldid=462352 removed] that example. There are multiple reasons to use {{ic|/opt}}, most often it is because it may be too hard or even impossible to merge the software with the system's {{ic|/usr}} hierarchy. For example the software might come with bundled libraries which may conflict with the system libraries, this is where the "self-contained" comes from. If you take a look at the content of the {{pkg|cuda}} package, you will see that manual pages, licenses and desktop files are installed into {{ic|/usr/share}}.<br />
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:17, 22 May 2017 (UTC)<br />
<br />
::::::Hmm. I don't think I was looking for an explanation to another article from the talk page of a different article. What "telepathic powers" that I "may have" have got to do with that, I've no clue. Also, I don't ''think'' I need patronisations about how to ask good questions. :-)<br />
::::::Anyway, as you can see from the flow of the conversation, first I thought there should be an AUR-specific instruction on {{ic|/opt}}. Then you say no, and there's also a different site. Then I ask about that other general one I found, different article, which is very cryptic, a bit out-of-date, and maybe that's the reason that it is. Then you respond, well exactly, that's what we already got, so why ask in the first place, and Alad closes the conversation?<br />
::::::Right? On the issue, I can see {{Pkg|cuda}} has its stuff elsewhere besides {{ic|/opt}}. ''However'', the ''point is'', why isn't it explained ''in that'' article? Why isn't ''your'' explanation in the article? Also, it currently says "large self-contained". What is the definition of ''large''? Smaller ones belong in {{ic|/usr}}?<br />
::::::''I'' don't need that explanation, the ''article'' needs it. People reading for the ''first time'' need it. Right? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 08:24, 22 May 2017 (UTC)<br />
<br />
== Directories -- Why shouldn't /srv be used? ==<br />
<br />
I'm updating the AUR package for the cyrus-imapd package, and noticed that this guideline states that the /srv directory should not be included in the package. Persistent application data should be placed in /var/lib/{pkg}. I'm wondering if there is a good reason for this? From long experience, /var tends to include a lot of rapidly changing ephemeral data and often ends up on a (typically smaller and faster) OS disk partition. And in the past, mounting another partition to /var lead to timing issues. systemd has fixed the latter, but the former persists, and IMAP mail stores tend to grow quite large over time. As a result, I've adopted the convention of using /srv for data which is served out and which can grow in size indefinitely. Furthermore, this is precisely how the directory is intended to be used according to the FHS. So I'd like to put the IMAP user mail store in /srv/imap by default, and was planning to do so until I ran across this document. Sort of feeling like this specific instruction is out of date (but agree that the other directories listed shouldn't be used) [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 22:15, 13 March 2019 (UTC)<br />
: Adding to my own comment, for purposes of clarification. Again, from long experience, people find setting up an imap server to be complicated and intimidating, so it would be better to offer an a priori rational directory structure which needn't be modified after the fact.</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Arch_package_guidelines&diff=568644Talk:Arch package guidelines2019-03-13T22:17:15Z<p>Pgoetz: /* Directories -- Why shouldn't /srv be used? */</p>
<hr />
<div>== Fields order ==<br />
<br />
[[Arch_Packaging_Standards#Package_etiquette]] states: "It is common practice to preserve the order of the PKGBUILD fields as shown above." But this is not true. Common practice is to use {{ic|/usr/share/pacman/PKGBUILD.proto}} as a template, and the order of fields in that prototype has a far greater influence on packages in the wild than this page. This page should edited to reflect the current state of {{ic|PKGBUILD.proto}}. Perhaps this page should state: "It is common practice to order PKGBUILD fields so they match the order of fields in {{ic|PKGBUILD.proto}}. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 14:32, 19 October 2013 (UTC)<br />
<br />
== Punctuation in PKGBUILD ==<br />
What is the official guidance regarding ending a pkgdesc in a period or using commas and English prose punctuation in general?<br />
<br />
[[https://bbs.archlinux.org/viewtopic.php?pid=1288063 Link]] to discussion thread.<br />
<br />
[[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 15:17, 14 June 2013 (UTC)<br />
<br />
==Package naming==<br />
* Package names should consist of '''alphanumeric characters only'''; all letters should be '''lowercase'''.<br />
:--unsigned<br />
<br />
::This is a guideline, but I see some packages with hypens and underscores (tesseract-data-chi_sim), dots (gstreamer0.10), plus (libxml++) and even at-signs (kde-l10n-ca@valencia). A package with uppercase name is libreoffice-bn-IN. According to the makepkg source, the allowed chars are: {{ic|[:alnum:]+_.@-}}. [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
:::"alphanumeric characters only" rule is ridiculous, 85% of official packages break this rule. I think it should be changed to allow hypens. It makes package names more readable. In regards to other characters, the + sign breaks [https://aur.archlinux.org/rpc.php AUR search] ([https://aur.archlinux.org/rpc.php?type=search&arg=a++ example], [https://aur.archlinux.org/rpc.php?type=search&arg=a%2B%2B should be escaped]). [[User:Axper|axper]] ([[User talk:Axper|talk]]) 11:19, 11 May 2014 (UTC)<br />
<br />
* Package names should NOT be suffixed with the upstream major release version number (e.g. we don't want libfoo2 if upstream calls it libfoo v2.3.4) in case the library and its dependencies are expected to be able to keep using the most recent library version with each respective upstream release. However, for some software or dependencies, this can not be assumed. In the past this has been especially true for widget toolkits such as GTK and Qt. Software that depends on such toolkits can usually not be trivially ported to a new major version. As such, in cases where software can not trivially keep rolling alongside its dependencies, package names should carry the major version suffix (e.g. gtk2, gtk3, qt4, qt5). For cases where most dependencies can keep rolling along the newest release but some can't (for instance closed source that needs libpng12 or similar), a deprecated version of that package might be called libfoo1 while the current version is just libfoo.<br />
:--unsigned<br />
<br />
* Package versions '''should be the same as the version released by the author'''. Versions can include letters if need be (eg, nmap's version is 2.54BETA32). '''Version tags may not include hyphens!''' Letters, numbers, and periods only.<br />
:--unsigned<br />
<br />
::This rule needs to get more stricter. Having a slash in the version breaks filenames. For craziness, I tried setting up a pkgver containing all characters from 0x01 to 0xff which makes makepkg throw a Bash syntax error. The current packages have versions matching {{ic}[[alnum:]._+~]+} (and a colon for epoch, a hypen for pkgrel). What about limiting to those characters? Debian has a similar set, see [https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version their policy docs] [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
* Package releases are '''specific to Arch Linux packages'''. These allow users to differentiate between newer and older package builds. When a new package version is first released, the '''release count starts at 1'''. Then as fixes and optimizations are made, the package will be '''re-released''' to the Arch Linux public and the '''release number will increment'''. When a new version comes out, the release count resets to 1. Package release tags follow the '''same naming restrictions as version tags'''.<br />
:--unsigned<br />
<br />
* Why is there no mentioning of suffixes for different build sources, such as vcs sources (-git, -hg, …) or binary distributions (-bin)? IMO this is an important part of the package naming conventions in AUR. [[User:Fordprefect|Fordprefect]] ([[User talk:Fordprefect|talk]]) 13:43, 10 May 2016 (UTC)<br />
<br />
::Some of the information is sequestered into the AUR page's FAQ and other places, but I have [[Talk:Creating packages#Proposal: Creating a PKGBUILD: Package naming conventions|a proposal]] to bring it together (and add some additional conventions). Since this page already has a section on package naming conventions, it would integrate well here. Unfortunately, as this is a protected page, I wouldn't be able to make the edits myself. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 15:29, 23 February 2019 (UTC)<br />
<br />
::[[User:Quequotion/Arch package guidelines#Package naming|Here]]'s a whole-page draft of what that might look like. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 16:04, 23 February 2019 (UTC)<br />
<br />
=== Proposal: Additional Conventions ===<br />
<br />
* Packages having extra features enabled and/or patches in comparison to the official ones should be named differently to express that. For example, a package for GNU {{Pkg|screen}} containing the sidebar patch could be named {{ic|screen-sidebar}}. Additionally the {{ic|1=provides=('screen')}} array should be used to avoid conflicts with the official package and satisfy its dependents.<br />
<br />
See also individual package guidelines pages for their particular naming conventions.<br />
<br />
== Is it acceptable for build() to start by removing directories? ==<br />
<br />
I just downloaded a PKGBUILD whose build() function begins with the following:<br />
<br />
find ./ -maxdepth 1 -mindepth 1 -type d -exec rm -r {} \;<br />
<br />
It seems to me that a PKGBUILD has no business doing this and that it is potentially dangerous. I admit that its danger will typically require people to do non-standard things and, arguably, things they would be better advised not to do anyway. But it still seems to me to invite trouble.<br />
<br />
I don't remember seeing this in a PKGBUILD before but I can't find anything definitely ruling it out.<br />
<br />
Is it acceptable for a build function to start by removing directories in this way? Is it safe?<br />
<br />
--[[User:Margali|cfr]] ([[User talk:Margali|talk]]) 03:03, 27 February 2014 (UTC)<br />
<br />
: I'd argue that this is an acceptable thing to do, at least in some cases. As an example, consider [http://www.talend.com/products/data-integration Talend Open Studio DI]: a single source file provides files for Windows, Linux, Mac OS, PowerPC (?) and Solaris. In response, the {{AUR|talend-open-studio-di}} PKGBUILD simply removes them. Does removing those files invite trouble? Yes. But removing files seems like an integral tool in the package maintainer's toolkit, and plenty of other weird stuff happens in PKGBUILDs too. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 02:20, 3 March 2014 (UTC)<br />
<br />
== Unique sources ==<br />
<br />
The source array should only contain unique sources names if a shares source directory is used. This applies to most github download. You can use "${pkgname}-${pkgver}.tar.gz::" prependet to each source to make the filename unique. <br />
I am not allowed to edit the page, could someone please do so?--[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 15:33, 16 December 2016 (UTC)<br />
<br />
== Add security standards ==<br />
<br />
As we decided to use https and GPG wherever possible for PKGBUILDs this should be added here as well. A Link to the mailing list would be also nice. The usage of strong hashes could also be mentioned, but I assume some people will not like the idea. A Link to the discussion about the hashes could also help for everyone to get his own opinion. It should be also mentioned that maintainers still need to validate the content of the downloads and test the update. Another important point is to contact upstream for GPG signatures if they are not available yet. One can link to some templates/tutorials I made on nicohood.de --[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 19:40, 16 December 2016 (UTC)<br />
<br />
:Forget about the checksums part, as it was already declined multiple times by the developers. For the rest, patches welcome. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:19, 16 December 2016 (UTC)<br />
:edit: see also [[User:Apg#makepkg:_replace_default_checksums]] -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:21, 14 March 2017 (UTC)<br />
<br />
== Architecture Section not clear enough ==<br />
<br />
The arch array depends "on which architectures it can be built on". This is okay but I believe it should be clarified that the program also needs to run and work on that architecture. I know it's a bit "obvious" but people who write interpreted programs may understand that they should put "any" in the arch array even if their program is not usable at all for some architectures. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 07:14, 28 April 2017 (UTC)<br />
<br />
:How does fixing "built on" to "built for" prevent people from abusing {{ic|any}}? That's a separate problem. Also, interpreted programs like scripts ''should'' use {{ic|any}}, where do you think they shouldn't? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:39, 28 April 2017 (UTC)<br />
<br />
::There is that program (debtap in AUR) wrote in bash that converts deb packages to Arch Linux packages. Unfortunately the program works only for i386 and amd64 because it fetches Ubuntu repositories at some specific locations. So when you run it on an arm architecture it fails with a curl output saying 404 which is not user friendly at all. IMHO a package should be restricted to the architectures where it works but in the specifications here, the only requirement is that it compiles. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 09:08, 28 April 2017 (UTC)<br />
<br />
:::Actually it is better specified here: [[PKGBUILD#arch]] "If instead a package can be compiled for any architecture, but is architecture-specific once compiled, specify all architectures officially supported by Arch, i.e. arch=('i686' 'x86_64'). " [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 10:10, 29 April 2017 (UTC)<br />
<br />
Since we no longer support i686 and the section had to be edited anyway, I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=507402&oldid=485119 tried to clarify] the situation described above. I don't think it should include something like ".. and any other architectures the package builds/compiles/runs on", as we only support x86_64. None of the packages in the official repositories specify architectures besides 'x86_64' and 'any' (I think). [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 15:41, 13 January 2018 (UTC)<br />
:Maybe we should just do like we do for Licenses, and say "See [[PKGBUILD#arch]]". I think we explain in sufficient detail there. :) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 03:26, 14 January 2018 (UTC)<br />
<br />
::Not saying it's a bad thing, but following this approach there wouldn't be much left of the ''official'' packaging guidelines... The purpose of the entire page should be rethought. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:41, 14 January 2018 (UTC)<br />
<br />
== /opt vs /usr/share ==<br />
<br />
Should there be a clause here or somewhere about preferring {{ic|/opt}} for big/self-contained AUR packages instead of {{ic|/usr/share}}? Isn't there such a policy? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 17:17, 21 May 2017 (UTC)<br />
<br />
:That's somewhat covered by the [http://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html FHS]. There's no reason to make it specific only to AUR, even official packages like {{Pkg|cuda}} or {{Pkg|vtk6}} are installed into {{ic|/opt}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:34, 21 May 2017 (UTC)<br />
<br />
::Do you mean that actual page? So sections like [[Arch packaging standards#Directories]] should really be replaced with a link there? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 19:02, 21 May 2017 (UTC)<br />
<br />
:::There you go, you even ''have'' the policy, so what's the point of this discussion really?? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:07, 21 May 2017 (UTC)<br />
<br />
::::Alad, I'd appreciate it, if you didn't just come in and close an ongoing discussion. Anyway, so shouldn't that text be amended if that small piece is our official guideline? 1) Java is not installed in {{ic|/opt}} (neither {{Pkg|jre7-openjdk}} nor {{Pkg|jre8-openjdk}}), 2) what is a "self-contained" package? Can it have e.g. icons and desktop files in {{ic|/usr}}? I would hope so. —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 21:19, 21 May 2017 (UTC)<br />
<br />
:::::Det, you really need to improve the way you ask questions. We don't have telepathic powers like you might have, so there is no way we could have guessed from the first post that you want an explanation for a section that you linked in your second post. Please read the standard reference on this topic, [http://www.catb.org/~esr/faqs/smart-questions.html How To Ask Questions The Smart Way].<br />
:::::Now back to the topic. You're right about Java, so I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=477997&oldid=462352 removed] that example. There are multiple reasons to use {{ic|/opt}}, most often it is because it may be too hard or even impossible to merge the software with the system's {{ic|/usr}} hierarchy. For example the software might come with bundled libraries which may conflict with the system libraries, this is where the "self-contained" comes from. If you take a look at the content of the {{pkg|cuda}} package, you will see that manual pages, licenses and desktop files are installed into {{ic|/usr/share}}.<br />
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:17, 22 May 2017 (UTC)<br />
<br />
::::::Hmm. I don't think I was looking for an explanation to another article from the talk page of a different article. What "telepathic powers" that I "may have" have got to do with that, I've no clue. Also, I don't ''think'' I need patronisations about how to ask good questions. :-)<br />
::::::Anyway, as you can see from the flow of the conversation, first I thought there should be an AUR-specific instruction on {{ic|/opt}}. Then you say no, and there's also a different site. Then I ask about that other general one I found, different article, which is very cryptic, a bit out-of-date, and maybe that's the reason that it is. Then you respond, well exactly, that's what we already got, so why ask in the first place, and Alad closes the conversation?<br />
::::::Right? On the issue, I can see {{Pkg|cuda}} has its stuff elsewhere besides {{ic|/opt}}. ''However'', the ''point is'', why isn't it explained ''in that'' article? Why isn't ''your'' explanation in the article? Also, it currently says "large self-contained". What is the definition of ''large''? Smaller ones belong in {{ic|/usr}}?<br />
::::::''I'' don't need that explanation, the ''article'' needs it. People reading for the ''first time'' need it. Right? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 08:24, 22 May 2017 (UTC)<br />
<br />
== Directories -- Why shouldn't /srv be used? ==<br />
<br />
I'm updating the AUR package for the cyrus-imapd package, and noticed that this guideline states that the /srv directory should not be included in the package. Persistent application data should be placed in /var/lib/{pkg}. I'm wondering if there is a good reason for this? From long experience, /var tends to include a lot of rapidly changing ephemeral data and often ends up on a (typically smaller and faster) OS disk partition. And in the past, mounting another partition to /var lead to timing issues. systemd has fixed the latter, but the former persists, and IMAP mail stores tend to grow quite large over time. As a result, I've adopted the convention of using /srv for data which is served out and which can grow in size indefinitely. Furthermore, this is precisely how the directory is intended to be used according to the FHS. So I'd like to put the IMAP user mail store in /srv/imap by default, and was planning to do so until I ran across this document. Sort of feeling like this specific instruction is out of date (but agree that the other directories listed shouldn't be used) [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 22:15, 13 March 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Talk:Arch_package_guidelines&diff=568642Talk:Arch package guidelines2019-03-13T22:15:01Z<p>Pgoetz: Added section on the use of directories</p>
<hr />
<div>== Fields order ==<br />
<br />
[[Arch_Packaging_Standards#Package_etiquette]] states: "It is common practice to preserve the order of the PKGBUILD fields as shown above." But this is not true. Common practice is to use {{ic|/usr/share/pacman/PKGBUILD.proto}} as a template, and the order of fields in that prototype has a far greater influence on packages in the wild than this page. This page should edited to reflect the current state of {{ic|PKGBUILD.proto}}. Perhaps this page should state: "It is common practice to order PKGBUILD fields so they match the order of fields in {{ic|PKGBUILD.proto}}. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 14:32, 19 October 2013 (UTC)<br />
<br />
== Punctuation in PKGBUILD ==<br />
What is the official guidance regarding ending a pkgdesc in a period or using commas and English prose punctuation in general?<br />
<br />
[[https://bbs.archlinux.org/viewtopic.php?pid=1288063 Link]] to discussion thread.<br />
<br />
[[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 15:17, 14 June 2013 (UTC)<br />
<br />
==Package naming==<br />
* Package names should consist of '''alphanumeric characters only'''; all letters should be '''lowercase'''.<br />
:--unsigned<br />
<br />
::This is a guideline, but I see some packages with hypens and underscores (tesseract-data-chi_sim), dots (gstreamer0.10), plus (libxml++) and even at-signs (kde-l10n-ca@valencia). A package with uppercase name is libreoffice-bn-IN. According to the makepkg source, the allowed chars are: {{ic|[:alnum:]+_.@-}}. [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
:::"alphanumeric characters only" rule is ridiculous, 85% of official packages break this rule. I think it should be changed to allow hypens. It makes package names more readable. In regards to other characters, the + sign breaks [https://aur.archlinux.org/rpc.php AUR search] ([https://aur.archlinux.org/rpc.php?type=search&arg=a++ example], [https://aur.archlinux.org/rpc.php?type=search&arg=a%2B%2B should be escaped]). [[User:Axper|axper]] ([[User talk:Axper|talk]]) 11:19, 11 May 2014 (UTC)<br />
<br />
* Package names should NOT be suffixed with the upstream major release version number (e.g. we don't want libfoo2 if upstream calls it libfoo v2.3.4) in case the library and its dependencies are expected to be able to keep using the most recent library version with each respective upstream release. However, for some software or dependencies, this can not be assumed. In the past this has been especially true for widget toolkits such as GTK and Qt. Software that depends on such toolkits can usually not be trivially ported to a new major version. As such, in cases where software can not trivially keep rolling alongside its dependencies, package names should carry the major version suffix (e.g. gtk2, gtk3, qt4, qt5). For cases where most dependencies can keep rolling along the newest release but some can't (for instance closed source that needs libpng12 or similar), a deprecated version of that package might be called libfoo1 while the current version is just libfoo.<br />
:--unsigned<br />
<br />
* Package versions '''should be the same as the version released by the author'''. Versions can include letters if need be (eg, nmap's version is 2.54BETA32). '''Version tags may not include hyphens!''' Letters, numbers, and periods only.<br />
:--unsigned<br />
<br />
::This rule needs to get more stricter. Having a slash in the version breaks filenames. For craziness, I tried setting up a pkgver containing all characters from 0x01 to 0xff which makes makepkg throw a Bash syntax error. The current packages have versions matching {{ic}[[alnum:]._+~]+} (and a colon for epoch, a hypen for pkgrel). What about limiting to those characters? Debian has a similar set, see [https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version their policy docs] [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
* Package releases are '''specific to Arch Linux packages'''. These allow users to differentiate between newer and older package builds. When a new package version is first released, the '''release count starts at 1'''. Then as fixes and optimizations are made, the package will be '''re-released''' to the Arch Linux public and the '''release number will increment'''. When a new version comes out, the release count resets to 1. Package release tags follow the '''same naming restrictions as version tags'''.<br />
:--unsigned<br />
<br />
* Why is there no mentioning of suffixes for different build sources, such as vcs sources (-git, -hg, …) or binary distributions (-bin)? IMO this is an important part of the package naming conventions in AUR. [[User:Fordprefect|Fordprefect]] ([[User talk:Fordprefect|talk]]) 13:43, 10 May 2016 (UTC)<br />
<br />
::Some of the information is sequestered into the AUR page's FAQ and other places, but I have [[Talk:Creating packages#Proposal: Creating a PKGBUILD: Package naming conventions|a proposal]] to bring it together (and add some additional conventions). Since this page already has a section on package naming conventions, it would integrate well here. Unfortunately, as this is a protected page, I wouldn't be able to make the edits myself. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 15:29, 23 February 2019 (UTC)<br />
<br />
::[[User:Quequotion/Arch package guidelines#Package naming|Here]]'s a whole-page draft of what that might look like. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 16:04, 23 February 2019 (UTC)<br />
<br />
=== Proposal: Additional Conventions ===<br />
<br />
* Packages having extra features enabled and/or patches in comparison to the official ones should be named differently to express that. For example, a package for GNU {{Pkg|screen}} containing the sidebar patch could be named {{ic|screen-sidebar}}. Additionally the {{ic|1=provides=('screen')}} array should be used to avoid conflicts with the official package and satisfy its dependents.<br />
<br />
See also individual package guidelines pages for their particular naming conventions.<br />
<br />
== Is it acceptable for build() to start by removing directories? ==<br />
<br />
I just downloaded a PKGBUILD whose build() function begins with the following:<br />
<br />
find ./ -maxdepth 1 -mindepth 1 -type d -exec rm -r {} \;<br />
<br />
It seems to me that a PKGBUILD has no business doing this and that it is potentially dangerous. I admit that its danger will typically require people to do non-standard things and, arguably, things they would be better advised not to do anyway. But it still seems to me to invite trouble.<br />
<br />
I don't remember seeing this in a PKGBUILD before but I can't find anything definitely ruling it out.<br />
<br />
Is it acceptable for a build function to start by removing directories in this way? Is it safe?<br />
<br />
--[[User:Margali|cfr]] ([[User talk:Margali|talk]]) 03:03, 27 February 2014 (UTC)<br />
<br />
: I'd argue that this is an acceptable thing to do, at least in some cases. As an example, consider [http://www.talend.com/products/data-integration Talend Open Studio DI]: a single source file provides files for Windows, Linux, Mac OS, PowerPC (?) and Solaris. In response, the {{AUR|talend-open-studio-di}} PKGBUILD simply removes them. Does removing those files invite trouble? Yes. But removing files seems like an integral tool in the package maintainer's toolkit, and plenty of other weird stuff happens in PKGBUILDs too. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 02:20, 3 March 2014 (UTC)<br />
<br />
== Unique sources ==<br />
<br />
The source array should only contain unique sources names if a shares source directory is used. This applies to most github download. You can use "${pkgname}-${pkgver}.tar.gz::" prependet to each source to make the filename unique. <br />
I am not allowed to edit the page, could someone please do so?--[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 15:33, 16 December 2016 (UTC)<br />
<br />
== Add security standards ==<br />
<br />
As we decided to use https and GPG wherever possible for PKGBUILDs this should be added here as well. A Link to the mailing list would be also nice. The usage of strong hashes could also be mentioned, but I assume some people will not like the idea. A Link to the discussion about the hashes could also help for everyone to get his own opinion. It should be also mentioned that maintainers still need to validate the content of the downloads and test the update. Another important point is to contact upstream for GPG signatures if they are not available yet. One can link to some templates/tutorials I made on nicohood.de --[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 19:40, 16 December 2016 (UTC)<br />
<br />
:Forget about the checksums part, as it was already declined multiple times by the developers. For the rest, patches welcome. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:19, 16 December 2016 (UTC)<br />
:edit: see also [[User:Apg#makepkg:_replace_default_checksums]] -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:21, 14 March 2017 (UTC)<br />
<br />
== Architecture Section not clear enough ==<br />
<br />
The arch array depends "on which architectures it can be built on". This is okay but I believe it should be clarified that the program also needs to run and work on that architecture. I know it's a bit "obvious" but people who write interpreted programs may understand that they should put "any" in the arch array even if their program is not usable at all for some architectures. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 07:14, 28 April 2017 (UTC)<br />
<br />
:How does fixing "built on" to "built for" prevent people from abusing {{ic|any}}? That's a separate problem. Also, interpreted programs like scripts ''should'' use {{ic|any}}, where do you think they shouldn't? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:39, 28 April 2017 (UTC)<br />
<br />
::There is that program (debtap in AUR) wrote in bash that converts deb packages to Arch Linux packages. Unfortunately the program works only for i386 and amd64 because it fetches Ubuntu repositories at some specific locations. So when you run it on an arm architecture it fails with a curl output saying 404 which is not user friendly at all. IMHO a package should be restricted to the architectures where it works but in the specifications here, the only requirement is that it compiles. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 09:08, 28 April 2017 (UTC)<br />
<br />
:::Actually it is better specified here: [[PKGBUILD#arch]] "If instead a package can be compiled for any architecture, but is architecture-specific once compiled, specify all architectures officially supported by Arch, i.e. arch=('i686' 'x86_64'). " [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 10:10, 29 April 2017 (UTC)<br />
<br />
Since we no longer support i686 and the section had to be edited anyway, I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=507402&oldid=485119 tried to clarify] the situation described above. I don't think it should include something like ".. and any other architectures the package builds/compiles/runs on", as we only support x86_64. None of the packages in the official repositories specify architectures besides 'x86_64' and 'any' (I think). [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 15:41, 13 January 2018 (UTC)<br />
:Maybe we should just do like we do for Licenses, and say "See [[PKGBUILD#arch]]". I think we explain in sufficient detail there. :) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 03:26, 14 January 2018 (UTC)<br />
<br />
::Not saying it's a bad thing, but following this approach there wouldn't be much left of the ''official'' packaging guidelines... The purpose of the entire page should be rethought. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:41, 14 January 2018 (UTC)<br />
<br />
== /opt vs /usr/share ==<br />
<br />
Should there be a clause here or somewhere about preferring {{ic|/opt}} for big/self-contained AUR packages instead of {{ic|/usr/share}}? Isn't there such a policy? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 17:17, 21 May 2017 (UTC)<br />
<br />
:That's somewhat covered by the [http://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html FHS]. There's no reason to make it specific only to AUR, even official packages like {{Pkg|cuda}} or {{Pkg|vtk6}} are installed into {{ic|/opt}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:34, 21 May 2017 (UTC)<br />
<br />
::Do you mean that actual page? So sections like [[Arch packaging standards#Directories]] should really be replaced with a link there? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 19:02, 21 May 2017 (UTC)<br />
<br />
:::There you go, you even ''have'' the policy, so what's the point of this discussion really?? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:07, 21 May 2017 (UTC)<br />
<br />
::::Alad, I'd appreciate it, if you didn't just come in and close an ongoing discussion. Anyway, so shouldn't that text be amended if that small piece is our official guideline? 1) Java is not installed in {{ic|/opt}} (neither {{Pkg|jre7-openjdk}} nor {{Pkg|jre8-openjdk}}), 2) what is a "self-contained" package? Can it have e.g. icons and desktop files in {{ic|/usr}}? I would hope so. —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 21:19, 21 May 2017 (UTC)<br />
<br />
:::::Det, you really need to improve the way you ask questions. We don't have telepathic powers like you might have, so there is no way we could have guessed from the first post that you want an explanation for a section that you linked in your second post. Please read the standard reference on this topic, [http://www.catb.org/~esr/faqs/smart-questions.html How To Ask Questions The Smart Way].<br />
:::::Now back to the topic. You're right about Java, so I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=477997&oldid=462352 removed] that example. There are multiple reasons to use {{ic|/opt}}, most often it is because it may be too hard or even impossible to merge the software with the system's {{ic|/usr}} hierarchy. For example the software might come with bundled libraries which may conflict with the system libraries, this is where the "self-contained" comes from. If you take a look at the content of the {{pkg|cuda}} package, you will see that manual pages, licenses and desktop files are installed into {{ic|/usr/share}}.<br />
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:17, 22 May 2017 (UTC)<br />
<br />
::::::Hmm. I don't think I was looking for an explanation to another article from the talk page of a different article. What "telepathic powers" that I "may have" have got to do with that, I've no clue. Also, I don't ''think'' I need patronisations about how to ask good questions. :-)<br />
::::::Anyway, as you can see from the flow of the conversation, first I thought there should be an AUR-specific instruction on {{ic|/opt}}. Then you say no, and there's also a different site. Then I ask about that other general one I found, different article, which is very cryptic, a bit out-of-date, and maybe that's the reason that it is. Then you respond, well exactly, that's what we already got, so why ask in the first place, and Alad closes the conversation?<br />
::::::Right? On the issue, I can see {{Pkg|cuda}} has its stuff elsewhere besides {{ic|/opt}}. ''However'', the ''point is'', why isn't it explained ''in that'' article? Why isn't ''your'' explanation in the article? Also, it currently says "large self-contained". What is the definition of ''large''? Smaller ones belong in {{ic|/usr}}?<br />
::::::''I'' don't need that explanation, the ''article'' needs it. People reading for the ''first time'' need it. Right? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 08:24, 22 May 2017 (UTC)<br />
<br />
== Directories -- Why shouldn't /srv be used? ==<br />
<br />
I'm updating the AUR package for the cyrus-imapd package, and noticed that this guideline states that the /srv directory should not be included in the package. Persistent application data should be placed in /var/lib/{pkg}. I'm wondering if there is a good reason for this? From long experience, /var tends to include a lot of rapidly changing ephemeral data and often ends up on a (typically smaller and faster) OS disk partition. And in the past, mounting another partition to /var lead to timing issues. systemd has fixed the latter, but the former persists, and IMAP mail stores tend to grow quite large over time. As a result, I've adopted the convention of using /srv for data which is served out and which can grow in size indefinitely. Furthermore, this is precisely how the directory is intended to be used according to the FHS. So I'd like to put the IMAP user mail store in /srv/imap by default, and was planning to do so until I ran across this document. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 22:15, 13 March 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=568611Creating packages2019-03-13T18:41:15Z<p>Pgoetz: /* package() */ "pkg" really means "pkgdir" and otherwise is confusing</p>
<hr />
<div>[[Category:About Arch]]<br />
[[Category:Package development]]<br />
[[cs:Creating packages]]<br />
[[es:Creating packages]]<br />
[[fa:ایجاد بستهها]]<br />
[[fr:Standard paquetage]]<br />
[[it:Creating packages]]<br />
[[ja:パッケージの作成]]<br />
[[pt:Creating packages]]<br />
[[ru:Creating packages]]<br />
[[zh-hans:Creating packages]]<br />
{{Related articles start}}<br />
{{Related|Arch Build System}}<br />
{{Related|Arch packaging standards}}<br />
{{Related|Arch User Repository}}<br />
{{Related|Creating packages for other distributions}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related|Patching in ABS}}<br />
{{Related|PKGBUILD}}<br />
{{Related|.SRCINFO}}<br />
{{Related|DeveloperWiki:Building in a Clean Chroot}}<br />
{{Related articles end}}<br />
<br />
This article aims to assist users creating their own packages using the Arch Linux "ports-like" [[Arch Build System|build system]], also for submission in [[AUR]]. It covers creation of a [[PKGBUILD]] &ndash; a package build description file sourced by {{ic|makepkg}} to create a binary package from source. If already in possession of a {{ic|PKGBUILD}}, see [[makepkg]]. For instructions regarding existing rules and ways to improve package quality see [[Arch packaging standards]].<br />
<br />
== Overview == <br />
<br />
Packages in Arch Linux are built using the [[makepkg]] utility and the information stored in a [[PKGBUILD]] file. When {{ic|makepkg}} runs, it searches for a {{ic|PKGBUILD}} in the current directory and follows the instructions in it to acquire the required files and/or compile them to be packed within a package file ({{ic|pkgname.pkg.tar.xz}}). The resulting package contains binary files and installation instructions ready to be installed by [[pacman]].<br />
<br />
An Arch package is no more than a tar archive, or 'tarball', compressed using {{man|1|xz}}, which contains the following files generated by makepkg:<br />
<br />
* The binary files to install.<br />
* {{ic|.PKGINFO}}: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
* {{ic|.BUILDINFO}}: contains information needed for reproducible builds. This file is present only if a package is built with pacman 5.1 or newer.<br />
* {{ic|.MTREE}}: contains hashes and timestamps of the files, which are included in the local database so that pacman can verify the integrity of the package.<br />
* {{ic|.INSTALL}}: an optional file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the {{ic|PKGBUILD}}.)<br />
* {{ic|.Changelog}}: an optional file kept by the package maintainer documenting the changes of the package. (It is not present in all packages.)<br />
<br />
== Preparation ==<br />
<br />
=== Prerequisite software ===<br />
<br />
First, ensure that the necessary tools are [[install]]ed: the package group {{Grp|base-devel}} should be sufficient, it includes {{ic|make}} and additional tools needed for compiling from source.<br />
<br />
The key tool for building packages is [[makepkg]] (provided by {{Pkg|pacman}}), which does the following:<br />
<br />
# Checks if package dependencies are installed.<br />
# Downloads the source file(s) from the specified server(s).<br />
# Unpacks the source file(s).<br />
# Compiles the software and installs it under a fakeroot environment.<br />
# Strips symbols from binaries and libraries.<br />
# Generates the package meta file which is included with each package.<br />
# Compresses the fakeroot environment into a package file.<br />
# Stores the package file in the configured destination directory, which is the current working directory by default.<br />
<br />
=== Download and test the installation ===<br />
<br />
Download the source tarball of the software you want to package, extract it, and follow the author's steps to install the program. Make a note of all commands and/or steps needed to compile and install it. You will be repeating those same commands in the {{ic|PKGBUILD}} file.<br />
<br />
Most software authors stick to the 3-step build cycle:<br />
<br />
./configure<br />
make<br />
make install<br />
<br />
This is a good time to make sure the program is working correctly.<br />
<br />
== Creating a PKGBUILD ==<br />
<br />
When {{ic|makepkg}} is run, it looks for a {{ic|PKGBUILD}} file in the current working directory. If it finds one, it downloads the software's source code and compiles it according to the instructions specified in the {{ic|PKGBUILD}} file. The instructions must be fully interpretable by the [[Wikipedia:Bash_(Unix_shell)|Bash]] shell. After successful completion, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a {{ic|pkgname.pkg.tar.xz}} package file. The newly created package can be installed by simply using {{ic|makepkg --install}} which will call pacman in the background, or by directly using {{ic|pacman -U ''pkgname.pkg.tar.xz''}}.<br />
<br />
To start building a new package, first create a new directory for the package and change current directory into this one. Then, a {{ic|PKGBUILD}} file needs to be created: a prototype PKGBUILD found in {{ic|/usr/share/pacman/}} can be used or you can start from a {{ic|PKGBUILD}} from another package. The latter may be a good choice if a similar package already exists.<br />
<br />
=== Defining PKGBUILD variables ===<br />
<br />
Example PKGBUILDs are located in {{Ic|/usr/share/pacman/}}. An explanation of possible {{ic|PKGBUILD}} variables can be found in the [[PKGBUILD]] article.<br />
<br />
''makepkg'' defines two variables that you should use as part of the build and install process:<br />
<br />
; {{ic|srcdir}}: This points to the directory where ''makepkg'' extracts or symlinks all files in the source array.<br />
<br />
; {{ic|pkgdir}}: This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package.<br />
<br />
They contain ''absolute'' paths, which means you do not have to worry about your working directory if you use these variables properly.<br />
<br />
{{Note|''makepkg'', and thus the {{ic|build()}} and {{ic|package()}} functions, are intended to be non-interactive. Interactive utilities or scripts called in those functions may break ''makepkg'', particularly if it is invoked with build-logging enabled ({{ic|-L}}). (See {{Bug|13214}}.)}}<br />
<br />
=== PKGBUILD functions ===<br />
<br />
There are five functions, listed here in the order they are executed. Beside the fifth function, {{ic|package()}}, which is required in every PKGBUILD, if one function does not exist it is simply skipped.<br />
<br />
==== prepare() ====<br />
<br />
With this function, commands that are used to prepare sources for building are run, such as [[Patching in ABS|patching]]. This function runs right after package extraction, before [[#pkgver()|pkgver()]] and the build function. If extraction is skipped ({{ic|makepkg -e}}), then {{ic|prepare()}} is not run. <br />
<br />
{{Note|(From {{man|5|PKGBUILD}}) The function is run in {{ic|bash -e}} mode, meaning any command that exits with a non-zero status will cause the function to exit.}}<br />
<br />
==== pkgver() ====<br />
<br />
{{ic|pkgver()}} runs after the sources are fetched, extracted and [[#prepare()|prepare()]] executed. So you can update the pkgver variable during a makepkg stage.<br />
<br />
This is particularly useful if you are [[VCS PKGBUILD Guidelines|making git/svn/hg/etc. packages]], where the build process may remain the same, but the source could be updated every day, even every hour. The old way of doing this was to put the date into the pkgver field which, if the software was not updated, makepkg would still rebuild it thinking the version had changed. Some useful commands for this are {{ic|git describe}}, {{ic|hg identify -ni}}, etc. Please test these before submitting a PKGBUILD, as a failure in the {{ic|pkgver()}} function can stop a build in its tracks. <br />
<br />
{{Note|pkgver cannot contain spaces or hyphens ({{ic|-}}). Using sed to correct this is common.}}<br />
<br />
==== build() ====<br />
<br />
Now you need to implement the {{ic|build()}} function in the {{ic|PKGBUILD}} file. This function uses common shell commands in [[Wikipedia:Bash_(Unix_shell)|Bash]] syntax to automatically compile software and create a {{ic|pkgdir}} directory to install the software to. This allows ''makepkg'' to package files without having to sift through your file system.<br />
<br />
The first step in the {{ic|build()}} function is to change into the directory created by uncompressing the source tarball. ''makepkg'' will change the current directory to {{ic|$srcdir}} before executing the {{ic|build()}} function. Therefore, in most cases, like suggested in {{ic|/usr/share/pacman/PKGBUILD.proto}}, the first command will look like this:<br />
<br />
cd "$pkgname-$pkgver"<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The {{ic|build()}} function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use {{ic|1=--prefix=/usr}} when building packages for pacman. A lot of software installs files relative to the {{ic|/usr/local}} directory, which should only be done if you are manually building from source. All Arch Linux packages should use the {{ic|/usr}} directory. As seen in the {{ic|/usr/share/pacman/PKGBUILD.proto}} file, the next two lines often look like this:<br />
<br />
./configure --prefix=/usr<br />
make<br />
<br />
{{Note|If your software does not need to build anything, do not use the {{ic|build()}} function. The {{ic|build()}} function is not required, but the {{ic|package()}} function is.}}<br />
<br />
==== check() ====<br />
<br />
Place for calls to {{Ic|make check}} and similar testing routines. It is highly recommended to have {{Ic|check()}} as it helps to make sure software has been built correctly and works fine with its dependencies.<br />
<br />
Users who do not need it (and occasionally maintainers who can not fix a package for this to pass) can disable it using {{ic|1=BUILDENV+=('!check')}} in PKGBUILD/makepkg.conf or call {{ic|makepkg}} with {{ic|--nocheck}} flag.<br />
<br />
==== package() ====<br />
<br />
The final step is to put the compiled files in a directory where ''makepkg'' can retrieve them to create a package. This by default is the {{ic|pkgdir}} directory—a simple fakeroot environment. The {{ic|pkgdir}} directory replicates the hierarchy of the root file system of the software's installation paths. If you have to manually place files under the root of your filesystem, you should install them in the {{ic|pkgdir}} directory under the same directory structure. For example, if you want to install a file to {{ic|/usr/bin}}, it should instead be placed under {{ic|$pkgdir/usr/bin}}. Very few install procedures require the user to copy dozens of files manually. Instead, for most software, calling {{ic|make install}} will do so. The final line should look like the following in order to correctly install the software in the {{ic|pkgdir}} directory:<br />
<br />
make DESTDIR="$pkgdir/" install<br />
<br />
{{Note|It is sometimes the case where {{ic|DESTDIR}} is not used in the {{ic|Makefile}}; you may need to use {{ic|prefix}} instead. If the package is built with ''autoconf'' / ''automake'', use {{ic|DESTDIR}}; this is what is [https://www.gnu.org/software/automake/manual/automake.html#Install documented] in the manuals. If {{ic|DESTDIR}} does not work, try building with {{ic|1=make prefix="$pkgdir/usr/" install}}. If that does not work, you will have to look further into the install commands that are executed by "{{ic|make <...> install}}".}}<br />
<br />
{{ic|makepkg --repackage}} runs only the {{ic|package()}} function, so it creates a package without building. This may save time e.g. if you have changed just the {{ic|depends}} variable of the package.<br />
<br />
== Testing the PKGBUILD and package ==<br />
<br />
As you are writing the {{ic|build()}} function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the {{ic|makepkg}} command in the directory containing the {{ic|PKGBUILD}} file. With a properly formatted {{ic|PKGBUILD}}, makepkg will create a package; with a broken or unfinished {{ic|PKGBUILD}}, it will raise an error.<br />
<br />
If makepkg finishes successfully, it will place a file named {{ic|pkgname-pkgver.pkg.tar.xz}} in your working directory. This package can be installed with the {{ic|pacman -U}} command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use pacman's query functions to display a list of files contained in the package and the dependencies it requires with {{ic|pacman -Qlp [package file]}} and {{ic|pacman -Qip [package file]}} respectively.<br />
<br />
If the package looks sane, then you are done! However, if you plan on releasing the {{ic|PKGBUILD}} file, it is imperative that you check and double-check the contents of the {{ic|depends}} array. <br />
<br />
Also ensure that the package binaries actually ''run'' flawlessly! It is annoying to release a package that contains all necessary files, but crashes because of some obscure configuration option that does not quite work well with the rest of the system. If you are only going to compile packages for your own system, though, you do not need to worry too much about this quality assurance step, as you are the only person suffering from mistakes, after all.<br />
<br />
=== Checking package sanity ===<br />
<br />
After testing package functionality check it for errors using [[namcap]]:<br />
$ namcap PKGBUILD<br />
$ namcap ''<package file name>''.pkg.tar.xz<br />
<br />
Namcap will:<br />
<br />
# Check PKGBUILD contents for common errors and package file hierarchy for unnecessary/misplaced files<br />
# Scan all ELF files in package using {{ic|ldd}}, automatically reporting which packages with required shared libraries are missing from {{Ic|depends}} and which can be omitted as transitive dependencies<br />
# Heuristically search for missing and redundant dependencies<br />
<br />
and much more.<br />
<br />
Get into the habit of checking your packages with namcap to avoid having to fix the simplest mistakes after package submission.<br />
<br />
== Submitting packages to the AUR ==<br />
<br />
Please read [[AUR User Guidelines#Submitting packages]] for a detailed description of the submission process.<br />
<br />
== Summary ==<br />
<br />
# Download the source tarball of the software to package.<br />
# Try compiling the package and installing it into an arbitrary directory.<br />
# Copy over the prototype {{ic|/usr/share/pacman/PKGBUILD.proto}} and rename it to {{ic|PKGBUILD}} in a temporary working directory.<br />
# Edit the {{ic|PKGBUILD}} according to the needs of your package.<br />
# Run {{ic|makepkg}} and check whether the package builds correctly.<br />
# If not, repeat the previous two steps.<br />
<br />
=== Warnings ===<br />
<br />
* Before you can automate the package building process, you should have done it manually at least once unless you know ''exactly'' what you are doing ''in advance'', in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "{{ic|./configure}}; {{ic|make}}; {{ic|make install}}", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you cannot get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you do not even need to try packaging it. There is not any magic pixie dust in {{ic|makepkg}} that makes source problems go away.<br />
* In a few cases, the packages are not even available as source and you have to use something like {{ic|sh installer.run}} to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from Gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However, {{ic|makepkg}} needs to be completely autonomous, with no user input. Therefore if you need to edit the makefiles, you may have to bundle a custom patch with the {{ic|PKGBUILD}} and install it from inside the {{ic|prepare()}} function, or you might have to issue some {{ic|sed}} commands from inside the {{ic|prepare()}} function.<br />
<br />
== More detailed guidelines ==<br />
<br />
{{Package guidelines}}<br />
<br />
== PKGBUILD generators ==<br />
<br />
PKGBUILDs for some packages can be generated automatically.<br />
<br />
{{Note|Users are still responsible for ensuring that the package meets the high quality standards before submitting the generated files to the [[AUR]].}}<br />
<br />
* [[Go]]: [https://github.com/seletskiy/go-makepkg go-makepkg]<br />
* [[Haskell]]: [https://github.com/magthe/cblrepo cblrepo]<br />
* [[Node.js]]: {{AUR|nodejs-npm2arch}} [https://github.com/simon04/npm2arch|igorvisi npm2arch]<br />
* [[Python]]: {{AUR|pipman-git}}, {{AUR|pip2arch-git}}, {{AUR|python-pypi2pkgbuild}}<br />
* [[Ruby]]: {{AUR|gem2arch}}, {{AUR|pacgem}}<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=91408 How to correctly create a patch file].<br />
* [https://archwomen.org/media/project_classroom/classlogs/ Arch Linux Classroom IRC Logs of classes about creating PKGBUILDs].<br />
* [http://www.linuxfromscratch.org/hints/downloads/files/fakeroot.txt Fakeroot approach for package installation]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=568609Creating packages2019-03-13T18:40:09Z<p>Pgoetz: AFAIK "pkg" should be "pkgdir"</p>
<hr />
<div>[[Category:About Arch]]<br />
[[Category:Package development]]<br />
[[cs:Creating packages]]<br />
[[es:Creating packages]]<br />
[[fa:ایجاد بستهها]]<br />
[[fr:Standard paquetage]]<br />
[[it:Creating packages]]<br />
[[ja:パッケージの作成]]<br />
[[pt:Creating packages]]<br />
[[ru:Creating packages]]<br />
[[zh-hans:Creating packages]]<br />
{{Related articles start}}<br />
{{Related|Arch Build System}}<br />
{{Related|Arch packaging standards}}<br />
{{Related|Arch User Repository}}<br />
{{Related|Creating packages for other distributions}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related|Patching in ABS}}<br />
{{Related|PKGBUILD}}<br />
{{Related|.SRCINFO}}<br />
{{Related|DeveloperWiki:Building in a Clean Chroot}}<br />
{{Related articles end}}<br />
<br />
This article aims to assist users creating their own packages using the Arch Linux "ports-like" [[Arch Build System|build system]], also for submission in [[AUR]]. It covers creation of a [[PKGBUILD]] &ndash; a package build description file sourced by {{ic|makepkg}} to create a binary package from source. If already in possession of a {{ic|PKGBUILD}}, see [[makepkg]]. For instructions regarding existing rules and ways to improve package quality see [[Arch packaging standards]].<br />
<br />
== Overview == <br />
<br />
Packages in Arch Linux are built using the [[makepkg]] utility and the information stored in a [[PKGBUILD]] file. When {{ic|makepkg}} runs, it searches for a {{ic|PKGBUILD}} in the current directory and follows the instructions in it to acquire the required files and/or compile them to be packed within a package file ({{ic|pkgname.pkg.tar.xz}}). The resulting package contains binary files and installation instructions ready to be installed by [[pacman]].<br />
<br />
An Arch package is no more than a tar archive, or 'tarball', compressed using {{man|1|xz}}, which contains the following files generated by makepkg:<br />
<br />
* The binary files to install.<br />
* {{ic|.PKGINFO}}: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
* {{ic|.BUILDINFO}}: contains information needed for reproducible builds. This file is present only if a package is built with pacman 5.1 or newer.<br />
* {{ic|.MTREE}}: contains hashes and timestamps of the files, which are included in the local database so that pacman can verify the integrity of the package.<br />
* {{ic|.INSTALL}}: an optional file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the {{ic|PKGBUILD}}.)<br />
* {{ic|.Changelog}}: an optional file kept by the package maintainer documenting the changes of the package. (It is not present in all packages.)<br />
<br />
== Preparation ==<br />
<br />
=== Prerequisite software ===<br />
<br />
First, ensure that the necessary tools are [[install]]ed: the package group {{Grp|base-devel}} should be sufficient, it includes {{ic|make}} and additional tools needed for compiling from source.<br />
<br />
The key tool for building packages is [[makepkg]] (provided by {{Pkg|pacman}}), which does the following:<br />
<br />
# Checks if package dependencies are installed.<br />
# Downloads the source file(s) from the specified server(s).<br />
# Unpacks the source file(s).<br />
# Compiles the software and installs it under a fakeroot environment.<br />
# Strips symbols from binaries and libraries.<br />
# Generates the package meta file which is included with each package.<br />
# Compresses the fakeroot environment into a package file.<br />
# Stores the package file in the configured destination directory, which is the current working directory by default.<br />
<br />
=== Download and test the installation ===<br />
<br />
Download the source tarball of the software you want to package, extract it, and follow the author's steps to install the program. Make a note of all commands and/or steps needed to compile and install it. You will be repeating those same commands in the {{ic|PKGBUILD}} file.<br />
<br />
Most software authors stick to the 3-step build cycle:<br />
<br />
./configure<br />
make<br />
make install<br />
<br />
This is a good time to make sure the program is working correctly.<br />
<br />
== Creating a PKGBUILD ==<br />
<br />
When {{ic|makepkg}} is run, it looks for a {{ic|PKGBUILD}} file in the current working directory. If it finds one, it downloads the software's source code and compiles it according to the instructions specified in the {{ic|PKGBUILD}} file. The instructions must be fully interpretable by the [[Wikipedia:Bash_(Unix_shell)|Bash]] shell. After successful completion, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a {{ic|pkgname.pkg.tar.xz}} package file. The newly created package can be installed by simply using {{ic|makepkg --install}} which will call pacman in the background, or by directly using {{ic|pacman -U ''pkgname.pkg.tar.xz''}}.<br />
<br />
To start building a new package, first create a new directory for the package and change current directory into this one. Then, a {{ic|PKGBUILD}} file needs to be created: a prototype PKGBUILD found in {{ic|/usr/share/pacman/}} can be used or you can start from a {{ic|PKGBUILD}} from another package. The latter may be a good choice if a similar package already exists.<br />
<br />
=== Defining PKGBUILD variables ===<br />
<br />
Example PKGBUILDs are located in {{Ic|/usr/share/pacman/}}. An explanation of possible {{ic|PKGBUILD}} variables can be found in the [[PKGBUILD]] article.<br />
<br />
''makepkg'' defines two variables that you should use as part of the build and install process:<br />
<br />
; {{ic|srcdir}}: This points to the directory where ''makepkg'' extracts or symlinks all files in the source array.<br />
<br />
; {{ic|pkgdir}}: This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package.<br />
<br />
They contain ''absolute'' paths, which means you do not have to worry about your working directory if you use these variables properly.<br />
<br />
{{Note|''makepkg'', and thus the {{ic|build()}} and {{ic|package()}} functions, are intended to be non-interactive. Interactive utilities or scripts called in those functions may break ''makepkg'', particularly if it is invoked with build-logging enabled ({{ic|-L}}). (See {{Bug|13214}}.)}}<br />
<br />
=== PKGBUILD functions ===<br />
<br />
There are five functions, listed here in the order they are executed. Beside the fifth function, {{ic|package()}}, which is required in every PKGBUILD, if one function does not exist it is simply skipped.<br />
<br />
==== prepare() ====<br />
<br />
With this function, commands that are used to prepare sources for building are run, such as [[Patching in ABS|patching]]. This function runs right after package extraction, before [[#pkgver()|pkgver()]] and the build function. If extraction is skipped ({{ic|makepkg -e}}), then {{ic|prepare()}} is not run. <br />
<br />
{{Note|(From {{man|5|PKGBUILD}}) The function is run in {{ic|bash -e}} mode, meaning any command that exits with a non-zero status will cause the function to exit.}}<br />
<br />
==== pkgver() ====<br />
<br />
{{ic|pkgver()}} runs after the sources are fetched, extracted and [[#prepare()|prepare()]] executed. So you can update the pkgver variable during a makepkg stage.<br />
<br />
This is particularly useful if you are [[VCS PKGBUILD Guidelines|making git/svn/hg/etc. packages]], where the build process may remain the same, but the source could be updated every day, even every hour. The old way of doing this was to put the date into the pkgver field which, if the software was not updated, makepkg would still rebuild it thinking the version had changed. Some useful commands for this are {{ic|git describe}}, {{ic|hg identify -ni}}, etc. Please test these before submitting a PKGBUILD, as a failure in the {{ic|pkgver()}} function can stop a build in its tracks. <br />
<br />
{{Note|pkgver cannot contain spaces or hyphens ({{ic|-}}). Using sed to correct this is common.}}<br />
<br />
==== build() ====<br />
<br />
Now you need to implement the {{ic|build()}} function in the {{ic|PKGBUILD}} file. This function uses common shell commands in [[Wikipedia:Bash_(Unix_shell)|Bash]] syntax to automatically compile software and create a {{ic|pkgdir}} directory to install the software to. This allows ''makepkg'' to package files without having to sift through your file system.<br />
<br />
The first step in the {{ic|build()}} function is to change into the directory created by uncompressing the source tarball. ''makepkg'' will change the current directory to {{ic|$srcdir}} before executing the {{ic|build()}} function. Therefore, in most cases, like suggested in {{ic|/usr/share/pacman/PKGBUILD.proto}}, the first command will look like this:<br />
<br />
cd "$pkgname-$pkgver"<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The {{ic|build()}} function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use {{ic|1=--prefix=/usr}} when building packages for pacman. A lot of software installs files relative to the {{ic|/usr/local}} directory, which should only be done if you are manually building from source. All Arch Linux packages should use the {{ic|/usr}} directory. As seen in the {{ic|/usr/share/pacman/PKGBUILD.proto}} file, the next two lines often look like this:<br />
<br />
./configure --prefix=/usr<br />
make<br />
<br />
{{Note|If your software does not need to build anything, do not use the {{ic|build()}} function. The {{ic|build()}} function is not required, but the {{ic|package()}} function is.}}<br />
<br />
==== check() ====<br />
<br />
Place for calls to {{Ic|make check}} and similar testing routines. It is highly recommended to have {{Ic|check()}} as it helps to make sure software has been built correctly and works fine with its dependencies.<br />
<br />
Users who do not need it (and occasionally maintainers who can not fix a package for this to pass) can disable it using {{ic|1=BUILDENV+=('!check')}} in PKGBUILD/makepkg.conf or call {{ic|makepkg}} with {{ic|--nocheck}} flag.<br />
<br />
==== package() ====<br />
<br />
The final step is to put the compiled files in a directory where ''makepkg'' can retrieve them to create a package. This by default is the {{ic|pkg}} directory—a simple fakeroot environment. The {{ic|pkg}} directory replicates the hierarchy of the root file system of the software's installation paths. If you have to manually place files under the root of your filesystem, you should install them in the {{ic|pkg}} directory under the same directory structure. For example, if you want to install a file to {{ic|/usr/bin}}, it should instead be placed under {{ic|$pkgdir/usr/bin}}. Very few install procedures require the user to copy dozens of files manually. Instead, for most software, calling {{ic|make install}} will do so. The final line should look like the following in order to correctly install the software in the {{ic|pkg}} directory:<br />
<br />
make DESTDIR="$pkgdir/" install<br />
<br />
{{Note|It is sometimes the case where {{ic|DESTDIR}} is not used in the {{ic|Makefile}}; you may need to use {{ic|prefix}} instead. If the package is built with ''autoconf'' / ''automake'', use {{ic|DESTDIR}}; this is what is [https://www.gnu.org/software/automake/manual/automake.html#Install documented] in the manuals. If {{ic|DESTDIR}} does not work, try building with {{ic|1=make prefix="$pkgdir/usr/" install}}. If that does not work, you will have to look further into the install commands that are executed by "{{ic|make <...> install}}".}}<br />
<br />
{{ic|makepkg --repackage}} runs only the {{ic|package()}} function, so it creates a package without building. This may save time e.g. if you have changed just the {{ic|depends}} variable of the package.<br />
<br />
== Testing the PKGBUILD and package ==<br />
<br />
As you are writing the {{ic|build()}} function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the {{ic|makepkg}} command in the directory containing the {{ic|PKGBUILD}} file. With a properly formatted {{ic|PKGBUILD}}, makepkg will create a package; with a broken or unfinished {{ic|PKGBUILD}}, it will raise an error.<br />
<br />
If makepkg finishes successfully, it will place a file named {{ic|pkgname-pkgver.pkg.tar.xz}} in your working directory. This package can be installed with the {{ic|pacman -U}} command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use pacman's query functions to display a list of files contained in the package and the dependencies it requires with {{ic|pacman -Qlp [package file]}} and {{ic|pacman -Qip [package file]}} respectively.<br />
<br />
If the package looks sane, then you are done! However, if you plan on releasing the {{ic|PKGBUILD}} file, it is imperative that you check and double-check the contents of the {{ic|depends}} array. <br />
<br />
Also ensure that the package binaries actually ''run'' flawlessly! It is annoying to release a package that contains all necessary files, but crashes because of some obscure configuration option that does not quite work well with the rest of the system. If you are only going to compile packages for your own system, though, you do not need to worry too much about this quality assurance step, as you are the only person suffering from mistakes, after all.<br />
<br />
=== Checking package sanity ===<br />
<br />
After testing package functionality check it for errors using [[namcap]]:<br />
$ namcap PKGBUILD<br />
$ namcap ''<package file name>''.pkg.tar.xz<br />
<br />
Namcap will:<br />
<br />
# Check PKGBUILD contents for common errors and package file hierarchy for unnecessary/misplaced files<br />
# Scan all ELF files in package using {{ic|ldd}}, automatically reporting which packages with required shared libraries are missing from {{Ic|depends}} and which can be omitted as transitive dependencies<br />
# Heuristically search for missing and redundant dependencies<br />
<br />
and much more.<br />
<br />
Get into the habit of checking your packages with namcap to avoid having to fix the simplest mistakes after package submission.<br />
<br />
== Submitting packages to the AUR ==<br />
<br />
Please read [[AUR User Guidelines#Submitting packages]] for a detailed description of the submission process.<br />
<br />
== Summary ==<br />
<br />
# Download the source tarball of the software to package.<br />
# Try compiling the package and installing it into an arbitrary directory.<br />
# Copy over the prototype {{ic|/usr/share/pacman/PKGBUILD.proto}} and rename it to {{ic|PKGBUILD}} in a temporary working directory.<br />
# Edit the {{ic|PKGBUILD}} according to the needs of your package.<br />
# Run {{ic|makepkg}} and check whether the package builds correctly.<br />
# If not, repeat the previous two steps.<br />
<br />
=== Warnings ===<br />
<br />
* Before you can automate the package building process, you should have done it manually at least once unless you know ''exactly'' what you are doing ''in advance'', in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "{{ic|./configure}}; {{ic|make}}; {{ic|make install}}", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you cannot get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you do not even need to try packaging it. There is not any magic pixie dust in {{ic|makepkg}} that makes source problems go away.<br />
* In a few cases, the packages are not even available as source and you have to use something like {{ic|sh installer.run}} to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from Gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However, {{ic|makepkg}} needs to be completely autonomous, with no user input. Therefore if you need to edit the makefiles, you may have to bundle a custom patch with the {{ic|PKGBUILD}} and install it from inside the {{ic|prepare()}} function, or you might have to issue some {{ic|sed}} commands from inside the {{ic|prepare()}} function.<br />
<br />
== More detailed guidelines ==<br />
<br />
{{Package guidelines}}<br />
<br />
== PKGBUILD generators ==<br />
<br />
PKGBUILDs for some packages can be generated automatically.<br />
<br />
{{Note|Users are still responsible for ensuring that the package meets the high quality standards before submitting the generated files to the [[AUR]].}}<br />
<br />
* [[Go]]: [https://github.com/seletskiy/go-makepkg go-makepkg]<br />
* [[Haskell]]: [https://github.com/magthe/cblrepo cblrepo]<br />
* [[Node.js]]: {{AUR|nodejs-npm2arch}} [https://github.com/simon04/npm2arch|igorvisi npm2arch]<br />
* [[Python]]: {{AUR|pipman-git}}, {{AUR|pip2arch-git}}, {{AUR|python-pypi2pkgbuild}}<br />
* [[Ruby]]: {{AUR|gem2arch}}, {{AUR|pacgem}}<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=91408 How to correctly create a patch file].<br />
* [https://archwomen.org/media/project_classroom/classlogs/ Arch Linux Classroom IRC Logs of classes about creating PKGBUILDs].<br />
* [http://www.linuxfromscratch.org/hints/downloads/files/fakeroot.txt Fakeroot approach for package installation]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=User_talk:Lahwaacz&diff=565554User talk:Lahwaacz2019-02-02T16:00:43Z<p>Pgoetz: Response</p>
<hr />
<div>== bot checking links after move ==<br />
<br />
Hi, re [[Talk:Touchpad Synaptics#adding libinput alternative]]. [[Touchpad Synaptics]] has 100+ backlinks and the more important ones - a bit tedious task. I was just glancing over your clever github bot scripts. It would be handy to have a script after such moves: walk over the backlinks of [[Touchpad Synaptics]] and just replace "[[Touchpad Synaptics" with "[[Synaptics" from the links. That would leave all links to subsections intact. Leaving out the translations to handle manually, there would not be much to go wrong, or? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 07:36, 26 September 2015 (UTC)<br />
<br />
:Hi, thanks for the suggestion. It would be indeed handy in this case, but most likely not generally. Imagine that there was a [[UUID]] page, which was later generalized and renamed to [[Persistent block device naming]] and content about UUID is now only a section on the page. In this case using the naive replacement would likely change the meaning of many sentences, and using shorter redirects for convenience is actually encouraged. There would have to be a list of whitelisted "harmless" replacements, which could even help to replace <nowiki>[[pacman|Install]]</nowiki> with <nowiki>[[Install]]</nowiki> etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:01, 26 September 2015 (UTC)<br />
<br />
::Yes, good examples, but you are thinking universal already :) I did not mean it could be that. For example, if you take the time when the bulk of the title case moves were done. With such a script one could avoid a lot of internal redirects as well. E.g. [https://wiki.archlinux.org/index.php/Special:WhatLinksHere/Beginners'_Guide]. But it's ok, just an idea. Please close this, if you think it's too singular cases with a simple enough replacement where it could be applied. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:02, 26 September 2015 (UTC)<br />
<br />
== aur-mirror ==<br />
<br />
Hi Lahwaacz,<br />
<br />
It seems that [http://pkgbuild.com/git/aur-mirror.git aur-mirror] has been down for a while.<br />
I'm not sure if this is intentional or not, but if it is, could you have Lahwaacz.bot remove [[Template:Aur-mirror]] from pages? At least where they are in a [[Template:Broken package link]] like {{ic|<nowiki>{{Broken package link|{{aur-mirror|foobar}}}}</nowiki>}}.<br />
<br />
If there is anything I can do to help, let me know.<br />
<br />
Thanks! [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 14:56, 19 October 2016 (UTC)<br />
<br />
:Maybe drifting a bit offtopic... but I'm in favor to finally remove any and all packages that are not on AUR4 from the wiki. Users have had over a year time to migrate, which is a century in Arch standards. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 16:21, 19 October 2016 (UTC)<br />
<br />
::I agree, especially on pages like [[List of games]] (already [https://wiki.archlinux.org/index.php?title=List_of_games&curid=4401&diff=454419&oldid=454356 took care of that]), and [[List of Applications]] (see [[Talk:List of applications#AUR3 packages]]). On other pages, where the non-existing packages are mentioned inline, it requires some more knowledge and effort to remove them. -- [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 16:34, 19 October 2016 (UTC)<br />
<br />
:::Hmm... For the moment I just updated the template to point to Github instead. What would be the alternative "hint" without the link? It should still be different from just "package not found". -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:08, 19 October 2016 (UTC)<br />
<br />
::::The GitHub repository is fine as well. I think we can keep that one while we (carefully) remove/update all broken links. Thanks! [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 06:52, 20 October 2016 (UTC)<br />
<br />
== mkosi ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=Systemd-nspawn&diff=0&oldid=491975 revert]: You can use mkosi also to create a container/directory tree (-t directory). So it can do the same and more. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 11:33, 1 October 2017 (UTC)<br />
<br />
:Alright, how is the "more" relevant to systemd-nspawn though? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:30, 3 October 2017 (UTC)<br />
<br />
::Hi, mkosi let's you create images (or directory trees) of various different distributions and allows you to do things like setting the root-password or installing additional packages. systemd-nspawn alows you to boot such images/directory trees. So I thought mentioning mkosi as alternative to manually creating a container with pacstrap or debootstrap would be worth it. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 22:23, 5 October 2017 (UTC)<br />
<br />
== GRUB/Tips and Tricks ==<br />
<br />
You reverted an edit I made to the /etc/grub.d/40_custom example at [[GRUB/Tips and tricks#Password_protection_of_GRUB_menu]], and your comment for doing so has me thinking you believe I put the heredoc syntax in to show someone how to cat mulitple lines from the command line. If that was my intent, I would agree with you that my change should be reverted. That's not what I was doing.<br />
<br />
The file contents as they are now produce an error upon running grub-mkconfig. I know because I tried this. The file ''contents'' need to include the heredoc syntax.<br />
<br />
In other words, if the file contents are the following, grub-mkconfig produces an error:<br />
set superusers="username"<br />
password_pbkdf2 username <password><br />
<br />
I was able to resolve this by adding the heredoc syntax, upon which everything worked. Again, the ''file contents'' need the heredoc syntax, as follows:<br />
cat << EOF<br />
set superusers="username"<br />
password_pbkdf2 username <password><br />
EOF<br />
<br />
With that in mind, I hope you'll agree that my edit was worthwhile.<br />
<br />
By the way, this isn't uncommon syntax for grub.d conf files. There are other examples of it, for instance section 3 of [https://askubuntu.com/questions/264247/proprietary-nvidia-drivers-with-efi-on-mac-to-prevent-overheating/613573#613573 this AskUbuntu answer] for Mac users to activate their discrete video cards.<br />
<br />
[[User:Djmoch|Djmoch]] ([[User talk:Djmoch|talk]]) 12:13, 1 December 2017 (UTC)<br />
<br />
== Waking from suspend with USB device ==<br />
<br />
Hi Lahwaacz, thanks for your input on this topic.<br />
Can you help me a bit further, I know the USB host controller and the USB device are different things but I thought that enabling the host controller was not necessary anymore, see [https://www.spinics.net/lists/linux-usb/msg53661.html].<br />
In my case all the {{ic|driver/*/power/wakeup}} are all enabled by default and the {{ic|/proc/acpi/wakeup}} as well.<br />
Anyway I have added a step in my explanations to identify the path awaiting for more clarity.<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 21:57, 16 January 2018 (UTC)<br />
<br />
:Hi, thanks for the link, it's entirely possible that something changed since the section was written. However, in my case only the keyboard device has wakeup enabled by default: {{bc|<nowiki><br />
$ for f in /sys/bus/usb/drivers/usb/*/power/wakeup; do echo "$f: $(cat $f)"; done<br />
/sys/bus/usb/drivers/usb/1-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/2-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-11/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-12/power/wakeup: enabled<br />
/sys/bus/usb/drivers/usb/3-13/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-4/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb2/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb4/power/wakeup: disabled<br />
</nowiki>}}<br />
:But in practice it seems to wake up the system even without the host controllers enabled for wakeup... It might also depend on some BIOS/firmware settings but if it works by default on most systems then I think the host controller settings could be removed again.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:14, 19 January 2018 (UTC)<br />
<br />
== Page titles ==<br />
<br />
Hi, i need help. I didn't find answer on my question in archwiki. Is "Title (Language)/Sub-page (Language)" correct? It is logically. But in archwiki says only: <br />
"Also note that in case of sub-pages, the language tag still goes at the end, so "Title (Language)/Sub-page" is wrong, while "Title/Sub-page (Language)" is correct." -- [[User:ArchLinuxUser|ArchLinuxUser]] ([[User talk:ArchLinuxUser|talk]]) 16:08, 21 January 2018 (UTC)<br />
<br />
:[[Help:I18n#Page titles]] is pretty clear on that "Title/Sub-page (Language)" is correct. It seems to me that "Title (Language)/Sub-page (Language)" would be superfluous.<br />
:The "(Language)" suffix applies to the entire "Title/Sub-page" bit as a whole. It can't be that the first (Language) is different from the second (Language), so why would you put it there twice?<br />
:-- [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 16:48, 21 January 2018 (UTC)<br />
<br />
:Also see [[Help talk:Style#Slashes in titles]]. Seems like there was some discussion on this. -- [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 16:58, 21 January 2018 (UTC)<br />
<br />
::If you use "Title/Sub-page (Language)", then you return to "Title", not to "Title (Language)". For examle, if you go to [[List of applications/Internet (Русский)]], and you want to go back through the "< List of applications", you will be taken to the English version of the page. -- [[User:ArchLinuxUser|ArchLinuxUser]] ([[User talk:ArchLinuxUser|talk]]) 17:11, 21 January 2018 (UTC)<br />
<br />
::How about my variant? It is logically (for example, the ''Russian'' sub-page is part of ''Russian'' page. Schematically it look like this: {{ic|Title (Language)/Subpage (Language)}}). -- [[User:ArchLinuxUser|ArchLinuxUser]] ([[User talk:ArchLinuxUser|talk]]) 18:00, 21 January 2018 (UTC)<br />
<br />
:::Hi, the {{ic|Title (Language)/Sub-page}} and {{ic|Title (Language)/Sub-page (Language)}} formats don't work, because the English page is {{ic|Title/Sub-page}} and the interlanguage links (shown in the left navigation column of each page) lead to {{ic|Title/Sub-page (Language)}}. Unfortunately, as I mentioned in [[Help_talk:Style#Localized_subpages]], there is no way to configure the interlanguage links to have the language in the middle of the page title. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:11, 21 January 2018 (UTC)<br />
<br />
::::We can do another format of Interlanguage links for sub-page. For examle,<br />
<nowiki>[[en:Title/Sub-page]]</nowiki><br />
<nowiki>[[es:Title (Español)/Sub-page]]</nowiki><br />
<nowiki>[[ru:Title (Русский)/Sub-page]]</nowiki><br />
::::See also [[CUPS (Русский)/Troubleshooting (Русский)]] and [[CUPS/Troubleshooting]]. Do i understand everything true? Must i fix this page? -- [[User:ArchLinuxUser|ArchLinuxUser]] ([[User talk:ArchLinuxUser|talk]]) 05:00, 22 January 2018 (UTC)<br />
<br />
:::::Well, technically the {{ic|Title (Language)/Subpage (Language)}} format + {{ic|lang:Title (Language)/Subpage}} link would work, but repeating the language does not look nice (and I think there are even some pages like {{ic|Title/Subpage/Subsubpage}}). I think the ultimate goal is to use language namespaces as discussed in [[Help_talk:I18n#Language_namespace.28s.29_in_place_of_suffixes.3F]], but it's still a long way ahead so until then let's use what we have for consistency. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:08, 23 January 2018 (UTC)<br />
<br />
== Are supported local/remote destinations important for choosing a backup program? ==<br />
<br />
You [[Special:Diff/525550|reverted]] my edit adding supported backup destinations to [[Synchronization_and_backup_programs]]. This is puzzling to me. Here are some thoughts:<br />
* if choosing any backup program, the ability to send the backup off-site vs only on a local disk is a key feature consideration. Perhaps *the* key feature: one helps me recover in case my house gets burglarized or burns down, and the other does not. This is a much more important feature consideration than, say, whether the program is written in Go or Mono (something that has a full column). I think it's hard to disagree on that.<br />
* Given this, I am very puzzled you would use the term "useless" in the revert message.<br />
* I assume you didn't like that the table got even bigger (it didn't fit into the layout even before). I don't like it either, but perhaps the revert should have said "can you put this somewhere else, not in this already-too-big table?"<br />
* On a personal note, when I provide feedback or give opinion on somebody else's work, I'd like to be constructive and kind, instead of aggressive and putting people down. Just a thought. Thanks for listening.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 17:38, 11 June 2018 (UTC)<br />
<br />
:No because you can use any remote back-end with any backup application by just running one command / writing the backups to a [[FUSE]] (if available).--[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 04:39, 12 June 2018 (UTC)<br />
<br />
::Hmm, by that reasoning we don't need the Arch package repository, as long as we have source code and makepkg. Or Perl, if we have bash and awk. But even then, and if all the fuse backends existed (I doubt they do), and if it were easy to set all of them up (another thing I doubt), do you indeed believe that running something written to read/write local files will be just as efficient backing up gigabytes of data to a remote repository as something that is specifically optimized for that use case? Note that backing up, say, daily, a typical hard drive via tpyical consumer broadband is still quite a bandwidth challenge in many places today. What about we add this info, and remove (or merge) some other columns to make the table smaller? {{Unsigned|18:08, 12 June 2018|Jernst}}<br />
<br />
:::Your comparisons don't make sense. Mind the slash in my response, you do not need a FUSE implementation, a simple CLI suffices. You do not need to "set all of them up", you only need one. --[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 18:47, 12 June 2018 (UTC)<br />
<br />
::::If you ever attempt to help a normal user set up a reliably-working off-site backup strategy, think of this discussion. In the meantime, this is all the time I'm going to spend on a discussion that has such repeated gems in it as "makes no sense" without explaining why you think so. Have a nice day. [[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 18:54, 12 June 2018 (UTC)<br />
<br />
== Archive (Español) ==<br />
<br />
Sorry for giving you some work today. I didn't know there should be only one "Archive" for all languages. You could have warned me and I would have corrected it for you. Best regards and sorry again. --[[User:AlonsoLP|AlonsoLP]] ([[User talk:AlonsoLP|talk]]) 11:38, 15 September 2018 (UTC)<br />
<br />
== Being in the vboxsf group does not automatically give you access to mount points ==<br />
<br />
Hi -<br />
<br />
Regarding revision #565457 of the VirtualBox Wiki page. I'm aware of what upstream says and hesitated before making this change, but I tested it myself (current non-dkms VirtualBox, fairly generic Arch client with the virtualbox-host-modules-arch package installed), and it just ''does not work''. Perhaps this is because automatic mounting is currently broken? (See https://bbs.archlinux.org/viewtopic.php?id=243871 which references a couple of bug reports.)<br />
<br />
In any case, on the Arch client, user pgoetz is in the vboxsf group. I set up a shared folder using the hypervisor GUI like this:<br />
<br />
:Folder Path: /home/pgoetz<br />
:Folder Name: pgoetz<br />
:Mount Point: /home/share/pgoetz<br />
<br />
:Read-only: no<br />
:Auto-mount: yes<br />
:Make Permanent: yes<br />
<br />
VBoxManage showvminfo {VM Name}<br />
<br />
shows the mount:<br />
<br />
:Shared folders:<br />
<br />
:Name: 'pgoetz', Host path: '/home/pgoetz' (machine mapping), writable, auto-mount, mount-point: '/home/share/pgoetz'<br />
<br />
but nothing is actually mounted there. Maybe this is the issue; if the folder were actually mounted there it would be write-accessible by any member of the vboxsf group<br />
<br />
However, the only way to get the mount to happen is to either mount it manually or create an entry in /etc/fstab.<br />
<br />
If I use this entry in /etc/fstab:<br />
<br />
pgoetz /home/share/pgoetz vboxsf rw,noauto,x-systemd.automount 0 0<br />
<br />
the folder is definitely '''not''' accessible by user pgoetz. In order to facilitate that, I have to use this /etc/fstab entry:<br />
<br />
pgoetz /home/share/pgoetz vboxsf uid=1000,gid=1000,rw,noauto,x-systemd.automount 0 0<br />
<br />
<br />
In any case, as stated currently on the VB Wiki page, it does not work, which is why I changed it, thinking that what is there will confuse people. We can leave it as is for now, and I'll test again if and when the hypervisor initiated automount starts working again.<br />
<br />
[[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 14:18, 2 February 2019 (UTC)<br />
<br />
:There are other places which mention the {{ic|vboxsf}} group (e.g. the previous section), so I found your edit more confusing than the original state. [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:27, 2 February 2019 (UTC)<br />
<br />
::Understood. I'll revisit this if and when the hypervisor automount works again. If it still doesn't work, I'll make sure I update it everywhere. Thanks. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 16:00, 2 February 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=User_talk:Lahwaacz&diff=565545User talk:Lahwaacz2019-02-02T14:18:23Z<p>Pgoetz: /* Being in the vboxsf group does not automatically give you access to mount points */ new section</p>
<hr />
<div>== bot checking links after move ==<br />
<br />
Hi, re [[Talk:Touchpad Synaptics#adding libinput alternative]]. [[Touchpad Synaptics]] has 100+ backlinks and the more important ones - a bit tedious task. I was just glancing over your clever github bot scripts. It would be handy to have a script after such moves: walk over the backlinks of [[Touchpad Synaptics]] and just replace "[[Touchpad Synaptics" with "[[Synaptics" from the links. That would leave all links to subsections intact. Leaving out the translations to handle manually, there would not be much to go wrong, or? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 07:36, 26 September 2015 (UTC)<br />
<br />
:Hi, thanks for the suggestion. It would be indeed handy in this case, but most likely not generally. Imagine that there was a [[UUID]] page, which was later generalized and renamed to [[Persistent block device naming]] and content about UUID is now only a section on the page. In this case using the naive replacement would likely change the meaning of many sentences, and using shorter redirects for convenience is actually encouraged. There would have to be a list of whitelisted "harmless" replacements, which could even help to replace <nowiki>[[pacman|Install]]</nowiki> with <nowiki>[[Install]]</nowiki> etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:01, 26 September 2015 (UTC)<br />
<br />
::Yes, good examples, but you are thinking universal already :) I did not mean it could be that. For example, if you take the time when the bulk of the title case moves were done. With such a script one could avoid a lot of internal redirects as well. E.g. [https://wiki.archlinux.org/index.php/Special:WhatLinksHere/Beginners'_Guide]. But it's ok, just an idea. Please close this, if you think it's too singular cases with a simple enough replacement where it could be applied. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:02, 26 September 2015 (UTC)<br />
<br />
== aur-mirror ==<br />
<br />
Hi Lahwaacz,<br />
<br />
It seems that [http://pkgbuild.com/git/aur-mirror.git aur-mirror] has been down for a while.<br />
I'm not sure if this is intentional or not, but if it is, could you have Lahwaacz.bot remove [[Template:Aur-mirror]] from pages? At least where they are in a [[Template:Broken package link]] like {{ic|<nowiki>{{Broken package link|{{aur-mirror|foobar}}}}</nowiki>}}.<br />
<br />
If there is anything I can do to help, let me know.<br />
<br />
Thanks! [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 14:56, 19 October 2016 (UTC)<br />
<br />
:Maybe drifting a bit offtopic... but I'm in favor to finally remove any and all packages that are not on AUR4 from the wiki. Users have had over a year time to migrate, which is a century in Arch standards. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 16:21, 19 October 2016 (UTC)<br />
<br />
::I agree, especially on pages like [[List of games]] (already [https://wiki.archlinux.org/index.php?title=List_of_games&curid=4401&diff=454419&oldid=454356 took care of that]), and [[List of Applications]] (see [[Talk:List of applications#AUR3 packages]]). On other pages, where the non-existing packages are mentioned inline, it requires some more knowledge and effort to remove them. -- [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 16:34, 19 October 2016 (UTC)<br />
<br />
:::Hmm... For the moment I just updated the template to point to Github instead. What would be the alternative "hint" without the link? It should still be different from just "package not found". -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:08, 19 October 2016 (UTC)<br />
<br />
::::The GitHub repository is fine as well. I think we can keep that one while we (carefully) remove/update all broken links. Thanks! [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 06:52, 20 October 2016 (UTC)<br />
<br />
== mkosi ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=Systemd-nspawn&diff=0&oldid=491975 revert]: You can use mkosi also to create a container/directory tree (-t directory). So it can do the same and more. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 11:33, 1 October 2017 (UTC)<br />
<br />
:Alright, how is the "more" relevant to systemd-nspawn though? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:30, 3 October 2017 (UTC)<br />
<br />
::Hi, mkosi let's you create images (or directory trees) of various different distributions and allows you to do things like setting the root-password or installing additional packages. systemd-nspawn alows you to boot such images/directory trees. So I thought mentioning mkosi as alternative to manually creating a container with pacstrap or debootstrap would be worth it. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 22:23, 5 October 2017 (UTC)<br />
<br />
== GRUB/Tips and Tricks ==<br />
<br />
You reverted an edit I made to the /etc/grub.d/40_custom example at [[GRUB/Tips and tricks#Password_protection_of_GRUB_menu]], and your comment for doing so has me thinking you believe I put the heredoc syntax in to show someone how to cat mulitple lines from the command line. If that was my intent, I would agree with you that my change should be reverted. That's not what I was doing.<br />
<br />
The file contents as they are now produce an error upon running grub-mkconfig. I know because I tried this. The file ''contents'' need to include the heredoc syntax.<br />
<br />
In other words, if the file contents are the following, grub-mkconfig produces an error:<br />
set superusers="username"<br />
password_pbkdf2 username <password><br />
<br />
I was able to resolve this by adding the heredoc syntax, upon which everything worked. Again, the ''file contents'' need the heredoc syntax, as follows:<br />
cat << EOF<br />
set superusers="username"<br />
password_pbkdf2 username <password><br />
EOF<br />
<br />
With that in mind, I hope you'll agree that my edit was worthwhile.<br />
<br />
By the way, this isn't uncommon syntax for grub.d conf files. There are other examples of it, for instance section 3 of [https://askubuntu.com/questions/264247/proprietary-nvidia-drivers-with-efi-on-mac-to-prevent-overheating/613573#613573 this AskUbuntu answer] for Mac users to activate their discrete video cards.<br />
<br />
[[User:Djmoch|Djmoch]] ([[User talk:Djmoch|talk]]) 12:13, 1 December 2017 (UTC)<br />
<br />
== Waking from suspend with USB device ==<br />
<br />
Hi Lahwaacz, thanks for your input on this topic.<br />
Can you help me a bit further, I know the USB host controller and the USB device are different things but I thought that enabling the host controller was not necessary anymore, see [https://www.spinics.net/lists/linux-usb/msg53661.html].<br />
In my case all the {{ic|driver/*/power/wakeup}} are all enabled by default and the {{ic|/proc/acpi/wakeup}} as well.<br />
Anyway I have added a step in my explanations to identify the path awaiting for more clarity.<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 21:57, 16 January 2018 (UTC)<br />
<br />
:Hi, thanks for the link, it's entirely possible that something changed since the section was written. However, in my case only the keyboard device has wakeup enabled by default: {{bc|<nowiki><br />
$ for f in /sys/bus/usb/drivers/usb/*/power/wakeup; do echo "$f: $(cat $f)"; done<br />
/sys/bus/usb/drivers/usb/1-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/2-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-11/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-12/power/wakeup: enabled<br />
/sys/bus/usb/drivers/usb/3-13/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-4/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb2/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb4/power/wakeup: disabled<br />
</nowiki>}}<br />
:But in practice it seems to wake up the system even without the host controllers enabled for wakeup... It might also depend on some BIOS/firmware settings but if it works by default on most systems then I think the host controller settings could be removed again.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:14, 19 January 2018 (UTC)<br />
<br />
== Page titles ==<br />
<br />
Hi, i need help. I didn't find answer on my question in archwiki. Is "Title (Language)/Sub-page (Language)" correct? It is logically. But in archwiki says only: <br />
"Also note that in case of sub-pages, the language tag still goes at the end, so "Title (Language)/Sub-page" is wrong, while "Title/Sub-page (Language)" is correct." -- [[User:ArchLinuxUser|ArchLinuxUser]] ([[User talk:ArchLinuxUser|talk]]) 16:08, 21 January 2018 (UTC)<br />
<br />
:[[Help:I18n#Page titles]] is pretty clear on that "Title/Sub-page (Language)" is correct. It seems to me that "Title (Language)/Sub-page (Language)" would be superfluous.<br />
:The "(Language)" suffix applies to the entire "Title/Sub-page" bit as a whole. It can't be that the first (Language) is different from the second (Language), so why would you put it there twice?<br />
:-- [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 16:48, 21 January 2018 (UTC)<br />
<br />
:Also see [[Help talk:Style#Slashes in titles]]. Seems like there was some discussion on this. -- [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 16:58, 21 January 2018 (UTC)<br />
<br />
::If you use "Title/Sub-page (Language)", then you return to "Title", not to "Title (Language)". For examle, if you go to [[List of applications/Internet (Русский)]], and you want to go back through the "< List of applications", you will be taken to the English version of the page. -- [[User:ArchLinuxUser|ArchLinuxUser]] ([[User talk:ArchLinuxUser|talk]]) 17:11, 21 January 2018 (UTC)<br />
<br />
::How about my variant? It is logically (for example, the ''Russian'' sub-page is part of ''Russian'' page. Schematically it look like this: {{ic|Title (Language)/Subpage (Language)}}). -- [[User:ArchLinuxUser|ArchLinuxUser]] ([[User talk:ArchLinuxUser|talk]]) 18:00, 21 January 2018 (UTC)<br />
<br />
:::Hi, the {{ic|Title (Language)/Sub-page}} and {{ic|Title (Language)/Sub-page (Language)}} formats don't work, because the English page is {{ic|Title/Sub-page}} and the interlanguage links (shown in the left navigation column of each page) lead to {{ic|Title/Sub-page (Language)}}. Unfortunately, as I mentioned in [[Help_talk:Style#Localized_subpages]], there is no way to configure the interlanguage links to have the language in the middle of the page title. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:11, 21 January 2018 (UTC)<br />
<br />
::::We can do another format of Interlanguage links for sub-page. For examle,<br />
<nowiki>[[en:Title/Sub-page]]</nowiki><br />
<nowiki>[[es:Title (Español)/Sub-page]]</nowiki><br />
<nowiki>[[ru:Title (Русский)/Sub-page]]</nowiki><br />
::::See also [[CUPS (Русский)/Troubleshooting (Русский)]] and [[CUPS/Troubleshooting]]. Do i understand everything true? Must i fix this page? -- [[User:ArchLinuxUser|ArchLinuxUser]] ([[User talk:ArchLinuxUser|talk]]) 05:00, 22 January 2018 (UTC)<br />
<br />
:::::Well, technically the {{ic|Title (Language)/Subpage (Language)}} format + {{ic|lang:Title (Language)/Subpage}} link would work, but repeating the language does not look nice (and I think there are even some pages like {{ic|Title/Subpage/Subsubpage}}). I think the ultimate goal is to use language namespaces as discussed in [[Help_talk:I18n#Language_namespace.28s.29_in_place_of_suffixes.3F]], but it's still a long way ahead so until then let's use what we have for consistency. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:08, 23 January 2018 (UTC)<br />
<br />
== Are supported local/remote destinations important for choosing a backup program? ==<br />
<br />
You [[Special:Diff/525550|reverted]] my edit adding supported backup destinations to [[Synchronization_and_backup_programs]]. This is puzzling to me. Here are some thoughts:<br />
* if choosing any backup program, the ability to send the backup off-site vs only on a local disk is a key feature consideration. Perhaps *the* key feature: one helps me recover in case my house gets burglarized or burns down, and the other does not. This is a much more important feature consideration than, say, whether the program is written in Go or Mono (something that has a full column). I think it's hard to disagree on that.<br />
* Given this, I am very puzzled you would use the term "useless" in the revert message.<br />
* I assume you didn't like that the table got even bigger (it didn't fit into the layout even before). I don't like it either, but perhaps the revert should have said "can you put this somewhere else, not in this already-too-big table?"<br />
* On a personal note, when I provide feedback or give opinion on somebody else's work, I'd like to be constructive and kind, instead of aggressive and putting people down. Just a thought. Thanks for listening.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 17:38, 11 June 2018 (UTC)<br />
<br />
:No because you can use any remote back-end with any backup application by just running one command / writing the backups to a [[FUSE]] (if available).--[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 04:39, 12 June 2018 (UTC)<br />
<br />
::Hmm, by that reasoning we don't need the Arch package repository, as long as we have source code and makepkg. Or Perl, if we have bash and awk. But even then, and if all the fuse backends existed (I doubt they do), and if it were easy to set all of them up (another thing I doubt), do you indeed believe that running something written to read/write local files will be just as efficient backing up gigabytes of data to a remote repository as something that is specifically optimized for that use case? Note that backing up, say, daily, a typical hard drive via tpyical consumer broadband is still quite a bandwidth challenge in many places today. What about we add this info, and remove (or merge) some other columns to make the table smaller? {{Unsigned|18:08, 12 June 2018|Jernst}}<br />
<br />
:::Your comparisons don't make sense. Mind the slash in my response, you do not need a FUSE implementation, a simple CLI suffices. You do not need to "set all of them up", you only need one. --[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 18:47, 12 June 2018 (UTC)<br />
<br />
::::If you ever attempt to help a normal user set up a reliably-working off-site backup strategy, think of this discussion. In the meantime, this is all the time I'm going to spend on a discussion that has such repeated gems in it as "makes no sense" without explaining why you think so. Have a nice day. [[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 18:54, 12 June 2018 (UTC)<br />
<br />
== Archive (Español) ==<br />
<br />
Sorry for giving you some work today. I didn't know there should be only one "Archive" for all languages. You could have warned me and I would have corrected it for you. Best regards and sorry again. --[[User:AlonsoLP|AlonsoLP]] ([[User talk:AlonsoLP|talk]]) 11:38, 15 September 2018 (UTC)<br />
<br />
== Being in the vboxsf group does not automatically give you access to mount points ==<br />
<br />
Hi -<br />
<br />
Regarding revision #565457 of the VirtualBox Wiki page. I'm aware of what upstream says and hesitated before making this change, but I tested it myself (current non-dkms VirtualBox, fairly generic Arch client with the virtualbox-host-modules-arch package installed), and it just ''does not work''. Perhaps this is because automatic mounting is currently broken? (See https://bbs.archlinux.org/viewtopic.php?id=243871 which references a couple of bug reports.)<br />
<br />
In any case, on the Arch client, user pgoetz is in the vboxsf group. I set up a shared folder using the hypervisor GUI like this:<br />
<br />
:Folder Path: /home/pgoetz<br />
:Folder Name: pgoetz<br />
:Mount Point: /home/share/pgoetz<br />
<br />
:Read-only: no<br />
:Auto-mount: yes<br />
:Make Permanent: yes<br />
<br />
VBoxManage showvminfo {VM Name}<br />
<br />
shows the mount:<br />
<br />
:Shared folders:<br />
<br />
:Name: 'pgoetz', Host path: '/home/pgoetz' (machine mapping), writable, auto-mount, mount-point: '/home/share/pgoetz'<br />
<br />
but nothing is actually mounted there. Maybe this is the issue; if the folder were actually mounted there it would be write-accessible by any member of the vboxsf group<br />
<br />
However, the only way to get the mount to happen is to either mount it manually or create an entry in /etc/fstab.<br />
<br />
If I use this entry in /etc/fstab:<br />
<br />
pgoetz /home/share/pgoetz vboxsf rw,noauto,x-systemd.automount 0 0<br />
<br />
the folder is definitely '''not''' accessible by user pgoetz. In order to facilitate that, I have to use this /etc/fstab entry:<br />
<br />
pgoetz /home/share/pgoetz vboxsf uid=1000,gid=1000,rw,noauto,x-systemd.automount 0 0<br />
<br />
<br />
In any case, as stated currently on the VB Wiki page, it does not work, which is why I changed it, thinking that what is there will confuse people. We can leave it as is for now, and I'll test again if and when the hypervisor initiated automount starts working again.<br />
<br />
[[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 14:18, 2 February 2019 (UTC)</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=VirtualBox&diff=565457VirtualBox2019-02-01T15:52:00Z<p>Pgoetz: Being in the vboxsf group does not automatically give you access to mount points</p>
<hr />
<div>[[Category:Hypervisors]]<br />
[[Category:Oracle]]<br />
[[cs:VirtualBox]]<br />
[[de:VirtualBox]]<br />
[[el:VirtualBox]]<br />
[[es:VirtualBox]]<br />
[[fr:VirtualBox]]<br />
[[hu:VirtualBox]]<br />
[[it:VirtualBox]]<br />
[[ja:VirtualBox]]<br />
[[pt:VirtualBox]]<br />
[[ru:VirtualBox]]<br />
[[zh-hans:VirtualBox]]<br />
{{Related articles start}}<br />
{{Related|VirtualBox/Tips and tricks}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|PhpVirtualBox}}<br />
{{Related|RemoteBox}}<br />
{{Related|Moving an existing install into (or out of) a virtual machine}}<br />
{{Related articles end}}<br />
<br />
[https://www.virtualbox.org VirtualBox] is a [[Wikipedia:Hypervisor|hypervisor]] used to run operating systems in a special environment, called a virtual machine, on top of the existing operating system. VirtualBox is in constant development and new features are implemented continuously. It comes with a [[Qt]] GUI interface, as well as headless and [[Wikipedia:Simple DirectMedia Layer|SDL]] command-line tools for managing and running virtual machines.<br />
<br />
In order to integrate functions of the host system to the guests, including shared folders and clipboard, video acceleration and a seamless window integration mode, ''guest additions'' are provided for some guest operating systems.<br />
<br />
== Installation steps for Arch Linux hosts ==<br />
<br />
In order to launch VirtualBox virtual machines on your Arch Linux box, follow these installation steps.<br />
<br />
=== Install the core packages ===<br />
<br />
[[Install]] the {{Pkg|virtualbox}} package. You will need to choose a package to provide host modules:<br />
* for {{Pkg|linux}} kernel choose {{Pkg|virtualbox-host-modules-arch}}<br />
* for other [[kernels]] choose {{Pkg|virtualbox-host-dkms}}<br />
** It is also necessary to install the appropriate headers package(s) for your installed kernel(s): {{Pkg|linux-headers}} or {{Pkg|linux-lts-headers}}. [https://lists.archlinux.org/pipermail/arch-dev-public/2016-March/027808.html] When either VirtualBox or the kernel is updated, the kernel modules will be automatically recompiled thanks to the [[DKMS]] Pacman hook.<br />
<br />
=== Sign modules ===<br />
<br />
When using a custom kernel with {{ic|CONFIG_MODULE_SIG_FORCE}} option enabled, you must sign your modules with a key generated during kernel compilation.<br />
<br />
Navigate to your kernel tree folder and execute the following command:<br />
# for module in `ls /lib/modules/$(uname -r)/kernel/misc/{vboxdrv.ko,vboxnetadp.ko,vboxnetflt.ko,vboxpci.ko}` ; do ./scripts/sign-file sha1 certs/signing_key.pem certs/signing_key.x509 $module ; done<br />
<br />
{{Note|Hashing algorithm does not have to match the one configured, but it must be built into the kernel.}}<br />
<br />
=== Load the VirtualBox kernel modules ===<br />
<br />
{{Pkg|virtualbox-host-modules-arch}} and {{Pkg|virtualbox-host-dkms}} use {{ic|systemd-modules-load.service}} to load all four VirtualBox modules automatically at boot time. For the modules to be loaded after installation, either reboot or load the modules once manually.<br />
<br />
{{Note|If you do not want the VirtualBox modules to be automatically loaded at boot time, you have to [[mask]] the default {{ic|/usr/lib/modules-load.d/virtualbox-host-modules-arch.conf}} (or {{ic|/usr/lib/modules-load.d/virtualbox-host-dkms.conf}}) by creating an empty file (or symlink to {{ic|/dev/null}}) with the same name in {{ic|/etc/modules-load.d/}}.}}<br />
<br />
Among the [[kernel modules]] VirtualBox uses, there is a mandatory module named {{ic|vboxdrv}}, which must be loaded before any virtual machines can run.<br />
<br />
To load the module manually, run:<br />
<br />
# modprobe vboxdrv<br />
<br />
The following modules are only required in advanced configurations:<br />
<br />
* {{ic|vboxnetadp}} and {{ic|vboxnetflt}} are both needed when you intend to use the [https://www.virtualbox.org/manual/ch06.html#network_bridged bridged] or [https://www.virtualbox.org/manual/ch06.html#network_hostonly host-only networking] feature. More precisely, {{ic|vboxnetadp}} is needed to create the host interface in the VirtualBox global preferences, and {{ic|vboxnetflt}} is needed to launch a virtual machine using that network interface.<br />
<br />
* {{ic|vboxpci}} is needed when your virtual machine needs to pass through a PCI device on your host.<br />
<br />
{{Note|If the VirtualBox kernel modules were loaded in the kernel while you updated the modules, you need to reload them manually to use the new updated version. To do it, run {{ic|vboxreload}} as root.}}<br />
<br />
=== Accessing host USB devices in guest ===<br />
<br />
To use the USB ports of your host machine in your virtual machines, add users that will be authorized to use this feature to the {{ic|vboxusers}} [[user group]].<br />
<br />
=== Guest additions disc ===<br />
<br />
It is also recommended to install the {{Pkg|virtualbox-guest-iso}} package on the host running VirtualBox. This package will act as a disc image that can be used to install the guest additions onto guest systems other than Arch Linux. The ''.iso'' file will be located at {{ic|/usr/lib/virtualbox/additions/VBoxGuestAdditions.iso}}, and may have to be mounted manually inside the virtual machine. Once mounted, you can run the guest additions installer inside the guest.<br />
<br />
=== Extension pack ===<br />
<br />
The Oracle Extension Pack provides [https://www.virtualbox.org/manual/ch01.html#intro-installing additional features] and is released under a non-free license '''only available for personal use'''. To install it, the {{aur|virtualbox-ext-oracle}} package is available, and a prebuilt version can be found in the [[Unofficial user repositories#seblu|seblu]] repository.<br />
<br />
If you prefer to use the traditional and manual way: download the extension manually and install it via the GUI (''File > Preferences > Extensions'') or via {{ic|VBoxManage extpack install <.vbox-extpack>}}, make sure you have a toolkit like [[Polkit]] to grant privileged access to VirtualBox. The installation of this extension [https://www.virtualbox.org/ticket/8473 requires root access].<br />
<br />
=== Front-ends ===<br />
<br />
VirtualBox comes with three front-ends:<br />
<br />
* If you want to use VirtualBox with the regular GUI, use {{ic|VirtualBox}}.<br />
* If you want to launch and manage your virtual machines from the command-line, use the {{ic|VBoxSDL}} command, which only provides a plain window for the virtual machine without any overlays.<br />
* If you want to use VirtualBox without running any GUI (e.g. on a server), use the {{ic|VBoxHeadless}} command. With the VRDP extension you can still remotely access the displays of your virtual machines.<br />
<br />
Finally, you can also use [[phpVirtualBox]] to administrate your virtual machines via a web interface.<br />
<br />
Refer to the [https://www.virtualbox.org/manual VirtualBox manual] to learn how to create virtual machines.<br />
<br />
{{Warning|If you intend to store virtual disk images on a [[Btrfs]] file system, before creating any images, you should consider disabling [[Btrfs#Copy-on-Write (CoW)|copy-on-write]] for the destination directory of these images.}}<br />
<br />
== Installation steps for Arch Linux guests ==<br />
<br />
Boot the Arch installation media through one of the virtual machine's virtual drives. Then, complete the installation of a basic Arch system as explained in the [[Installation guide]].<br />
<br />
=== Installation in EFI mode ===<br />
<br />
If you want to install Arch Linux in EFI mode inside VirtualBox, in the settings of the virtual machine, choose ''System'' item from the panel on the left and ''Motherboard'' tab from the right panel, and check the checkbox ''Enable EFI (special OSes only)''. After selecting the kernel from the Arch Linux installation media's menu, the media will hang for a minute or two and will continue to boot the kernel normally afterwards. Be patient.<br />
<br />
Once the system and the boot loader are installed, VirtualBox will first attempt to run {{ic|/EFI/BOOT/BOOTX64.EFI}} from the [[ESP]]. If that first option fails, VirtualBox will then try the EFI shell script {{ic|startup.nsh}} from the root of the ESP. This means that in order to boot the system you have the following options:<br />
<br />
* [[Unified Extensible Firmware Interface#UEFI Shell|Launch the bootloader manually]] from the EFI shell every time;<br />
* Move the bootloader to the default {{ic|/EFI/BOOT/BOOTX64.EFI}} path;<br />
* Create a script named {{ic|startup.nsh}} at the ESP root containing the path to the boot loader application, e.g. {{ic|\EFI\grub\grubx64.efi}}.<br />
* Boot directly from the ESP partition using a [[EFISTUB#Using a startup.nsh script|startup.nsh script]]. <br />
<br />
Do not bother with the VirtualBox Boot Manager (accessible with {{ic|F2}} at boot), as it is buggy and incomplete. It does not store efivars set interactively. Therefore, EFI entries added to it manually in the firmware (accessed with {{ic|F12}} at boot time) or with {{Pkg|efibootmgr}} will persist after a reboot [https://www.virtualbox.org/ticket/11177 but are lost when the VM is shut down].<br />
<br />
See also [https://bbs.archlinux.org/viewtopic.php?id=158003 UEFI VirtualBox installation boot problems].<br />
<br />
{{Note|In UEFI mode you may experience a black screen, see [[#Black screen for guest in EFI mode]] for a workaround.}}<br />
<br />
=== Install the Guest Additions ===<br />
<br />
VirtualBox [https://www.virtualbox.org/manual/ch04.html Guest Additions] provides drivers and applications that optimize the guest operating system including improved image resolution and better control of the mouse. Within the installed guest system, install:<br />
<br />
* {{Pkg|virtualbox-guest-utils}} for VirtualBox Guest utilities with X support<br />
* {{Pkg|virtualbox-guest-utils-nox}} for VirtualBox Guest utilities without X support<br />
<br />
Both packages will make you choose a package to provide guest modules:<br />
<br />
* for the default {{Pkg|linux}} kernel choose {{Pkg|virtualbox-guest-modules-arch}}<br />
* for non-default [[kernels]] choose {{Pkg|virtualbox-guest-dkms}}<br />
<br />
To compile the virtualbox modules provided by {{Pkg|virtualbox-guest-dkms}}, it will also be necessary to install the appropriate headers package(s) for your installed kernel(s) (e.g. {{Pkg|linux-lts-headers}} for {{Pkg|linux-lts}}). [https://lists.archlinux.org/pipermail/arch-dev-public/2016-March/027808.html] When either VirtualBox or the kernel is updated, the kernel modules will be automatically recompiled thanks to the [[DKMS]] Pacman hook.<br />
<br />
{{Note|<nowiki></nowiki><br />
* You can alternatively install the Guest Additions with the ISO from the {{Pkg|virtualbox-guest-iso}} package, provided you installed this on the host system. To do this, go to the device menu click Insert Guest Additions CD Image.<br />
* To recompile the vbox kernel modules, run {{ic|rcvboxdrv}} as root.<br />
}}<br />
<br />
The guest additions running on your guest, and the VirtualBox application running on your host must have matching versions, otherwise the guest additions (like shared clipboard) may stop working. If you upgrade your guest (e.g. {{ic|pacman -Syu}}), make sure your VirtualBox application on this host is also the latest version. "Check for updates" in the VirtualBox GUI is sometimes not sufficient; check the [https://www.virtualbox.org/ VirtualBox.org] website.<br />
<br />
=== Set optimal framebuffer resolution ===<br />
<br />
{{Move|VirtualBox/Tips and tricks}}<br />
Typically after installing Guest Additions, a fullscreen Arch guest running X will be set to the optimal resolution for your display; however, the virtual console's framebuffer will be set to a standard, often smaller, resolution detected from VirtualBox's custom VESA driver.<br />
<br />
To use the virtual consoles at optimal resolution, Arch needs to recognize that resolution as valid, which in turn requires VirtualBox to pass this information along to the guest OS.<br />
<br />
First, check if your desired resolution is not already recognized by running the command:<br />
<br />
hwinfo --framebuffer<br />
<br />
If the optimal resolution does not show up, then you will need to run the {{ic|VBoxManage}} tool on the host machine and add "extra resolutions" to your virtual machine (on a Windows host, go to the VirtualBox installation directory to find {{ic|VBoxManage.exe}}). For example:<br />
<br />
$ VBoxManage setextradata "Arch Linux" "CustomVideoMode1" "1360x768x24"<br />
<br />
The parameters "Arch Linux" and "1360x768x24" in the example above should be replaced with your VM name and the desired framebuffer resolution. Incidentally, this command allows for defining up to 16 extra resolutions ("CustomVideoMode1" through "CustomVideoMode16").<br />
<br />
Afterwards, restart the virtual machine and run {{ic|hwinfo --framebuffer}} once more to verify that the new resolutions have been recognized by your guest system (which does not guarantee they will all work, depending on your hardware limitations).<br />
<br />
{{Note|As of VirtualBox 5.2, {{ic|hwinfo --framebuffer}} might not show any output, but you should still be able to set a custom resolution following this procedure.}}<br />
<br />
Finally, add a {{ic|1=video=''resolution''}} [[kernel parameter]] to set the framebuffer to the new resolution, for example:<br />
<br />
video=1360x768<br />
<br />
Additionally you may want to configure your [[bootloader]] to use the same resolution. If you use GRUB, see [[GRUB/Tips and tricks#Setting the framebuffer resolution]].<br />
<br />
{{Note|Neither the kernel parameter {{ic|vga}} nor the bootloader's resolution settings (e.g. GRUB's {{ic|GRUB_GFXPAYLOAD_LINUX}}) will fix the framebuffer, since they are overriden by virtue of Kernel Mode Setting. The framebuffer resolution must be set by the kernel parameter {{ic|video}} as described above.}}<br />
<br />
=== Load the VirtualBox kernel modules ===<br />
<br />
To load the modules automatically, [[enable]] {{ic|vboxservice.service}} which loads the modules and synchronizes the guest's system time with the host.<br />
<br />
To load the modules manually, type:<br />
<br />
# modprobe -a vboxguest vboxsf vboxvideo<br />
<br />
{{Pkg|virtualbox-guest-dkms}} uses {{ic|systemd-modules-load.service}} to load its modules at boot time.<br />
<br />
{{Note|If you do not want the VirtualBox modules to be loaded at boot time, you have to [[mask]] the default {{ic|/usr/lib/modules-load.d/virtualbox-guest-dkms.conf}} by creating an empty file (or symlink to {{ic|/dev/null}}) with the same name in {{ic|/etc/modules-load.d/}}.}}<br />
<br />
=== Launch the VirtualBox guest services ===<br />
<br />
After the rather big installation step dealing with VirtualBox kernel modules, now you need to start the guest services. The guest services are actually just a binary executable called {{ic|VBoxClient}} which will interact with your X Window System. {{ic|VBoxClient}} manages the following features:<br />
<br />
* shared clipboard and drag and drop between the host and the guest;<br />
* seamless window mode;<br />
* the guest display is automatically resized according to the size of the guest window;<br />
* checking the VirtualBox host version<br />
<br />
All of these features can be enabled independently with their dedicated flags:<br />
<br />
$ VBoxClient --clipboard --draganddrop --seamless --display --checkhostversion<br />
<br />
As a shortcut, the {{ic|VBoxClient-all}} bash script enables all of these features.<br />
<br />
{{Pkg|virtualbox-guest-utils}} installs {{ic|/etc/xdg/autostart/vboxclient.desktop}} that launches {{ic|VBoxClient-all}} on logon. If your [[desktop environment]] or [[window manager]] does not support [[XDG Autostart]], you will need to set up autostarting yourself, see [[Autostarting#On desktop environment startup]] and [[Autostarting#On window manager startup]] for more details.<br />
<br />
VirtualBox can also synchronize the time between the host and the guest, to do this, [[start/enable]] the {{ic|vboxservice.service}}.<br />
<br />
Now, you should have a working Arch Linux guest. Note that features like clipboard sharing are disabled by default in VirtualBox, and you will need to turn them on in the per-VM settings if you actually want to use them (e.g. ''Settings > General > Advanced > Shared Clipboard'').<br />
<br />
=== Hardware acceleration ===<br />
<br />
Hardware acceleration can be activated in the VirtualBox options. The [[GDM]] display manager 3.16+ is known to break hardware acceleration support. [https://bugzilla.gnome.org/show_bug.cgi?id=749390] So if you get issues with hardware acceleration, try out another display manager (lightdm seems to work fine). [https://bbs.archlinux.org/viewtopic.php?id=200025] [https://bbs.archlinux.org/viewtopic.php?pid=1607593#p1607593]<br />
<br />
=== Enable shared folders ===<br />
<br />
Shared folders are managed on the host, in the settings of the Virtual Machine accessible via the GUI of VirtualBox, in the ''Shared Folders'' tab. There, ''Folder Path'', the name of the mount point identified by ''Folder name'', and options like ''Read-only'', ''Auto-mount'' and ''Make permanent'' can be specified. These parameters can be defined with the {{ic|VBoxManage}} command line utility. See [https://www.virtualbox.org/manual/ch04.html#sharedfolders there for more details].<br />
<br />
No matter which method you will use to mount your folder, all methods require some steps first.<br />
<br />
To avoid this issue {{ic|/sbin/mount.vboxsf: mounting failed with the error: No such device}}, make sure the {{ic|vboxsf}} kernel module is properly loaded. It should be, since we enabled all guest kernel modules previously.<br />
<br />
Two additional steps are needed in order for the mount point to be accessible from users other than root:<br />
<br />
* the {{Pkg|virtualbox-guest-utils}} package created a group {{ic|vboxsf}} (done in a previous step);<br />
* your user must be in {{ic|vboxsf}} [[user group]].<br />
<br />
==== Manual mounting ====<br />
<br />
Use the following command to mount your folder in your Arch Linux guest:<br />
<br />
# mount -t vboxsf ''shared_folder_name'' ''mount_point_on_guest_system''<br />
<br />
where ''shared_folder_name'' is the ''Folder name'' assigned by the hypervisor when the share was created.<br />
<br />
The vboxsf filesystem offers other options which can be displayed with this command:<br />
<br />
# mount.vboxsf<br />
<br />
For example we can use this command to give access to our mountpoint to the user with uid/gid 1000:<br />
<br />
# mount -t vboxsf -o uid=1000,gid=1000 home /mnt<br />
<br />
Where ''uid'' and ''gid'' are values corresponding to the users we want to give access to. These values are obtained from the {{ic|id}} command run against this user.<br />
<br />
==== Automounting ====<br />
<br />
{{Note|Automounting requires the {{ic|vboxservice.service}} to be [[enabled]]/[[started]].}}<br />
<br />
In order for the automounting feature to work you must have checked the auto-mount checkbox in the GUI or used the optional {{ic|--automount}} argument with the command {{ic|VBoxManage sharedfolder}}.<br />
<br />
The shared folder should now appear in {{ic|/media/sf_''shared_folder_name''}}. If users in {{ic|media}} cannot access the shared folders, check that {{ic|media}} has permissions {{ic|755}} or has group ownership {{ic|vboxsf}} if using permission {{ic|750}}. This is currently not the default if media is created by installing {{Pkg|virtualbox-guest-utils}}.<br />
<br />
You can use symlinks if you want to have a more convenient access and avoid to browse in that directory, e.g.:<br />
$ ln -s /media/sf_''shared_folder_name'' ~/''my_documents''<br />
<br />
==== Mount at boot ====<br />
<br />
You can mount your directory with [[fstab]]. However, to prevent startup problems with systemd, {{ic|1=noauto,x-systemd.automount}} should be added to {{ic|/etc/fstab}}. This way, the shared folders are mounted only when those mount points are accessed and not during startup. This can avoid some problems, especially if the guest additions are not loaded yet when systemd reads fstab and mounts the partitions.<br />
''sharedFolderName'' ''/path/to/mntPtOnGuestMachine'' vboxsf uid=''user'',gid=''group'',rw,dmode=700,fmode=600,noauto,x-systemd.automount <br />
<br />
* {{ic|''sharedFolderName''}}: the value from the VirtualMachine's ''Settings > SharedFolders > Edit > FolderName'' menu. This value can be different from the name of the real folder name on the host machine. To see the VirtualMachine's ''Settings'' go to the host OS VirtualBox application, select the corresponding virtual machine and click on ''Settings''.<br />
* {{ic|''/path/to/mntPtOnGuestMachine''}}: if not existing, this directory should be created manually (for example by using [[Core utilities#Essentials|mkdir]]).<br />
* {{ic|dmode}}/{{ic|fmode}} are directory/file permissions for directories/files inside {{ic|''/path/to/mntPtOnGuestMachine''}}.<br />
<br />
As of 2012-08-02, mount.vboxsf does not support the ''nofail'' option:<br />
''desktop'' ''/media/desktop'' vboxsf uid=''user'',gid=''group'',rw,dmode=700,fmode=600,nofail 0 0<br />
<br />
=== SSH from host to guest ===<br />
<br />
The network tab of the virtual machine settings contains, in "Advanced", a tool to create port forwarding. <br />
It is possible to use it to forward the Guest ssh port {{ic|22}} to a Host port, e.g. {{ic|3022}} :<br />
<br />
user@host$ ssh -p 3022 $USER@localhost<br />
<br />
will establish a connection from Host to Guest.<br />
<br />
==== SSHFS as alternative to the shared folder ====<br />
<br />
Using this port forwarding and sshfs, it is straightforward to mount the Guest filesystem onto the Host one:<br />
<br />
user@host$ sshfs -p 3022 $USER@localhost:$HOME ~/shared_folder<br />
<br />
and then transfer files between both.<br />
<br />
== Virtual disks management ==<br />
<br />
See also [[VirtualBox/Tips and tricks#Import/export VirtualBox virtual machines from/to other hypervisors]].<br />
<br />
=== Formats supported by VirtualBox ===<br />
<br />
VirtualBox supports the following virtual disk formats:<br />
<br />
* '''VDI''': The Virtual Disk Image is the VirtualBox own open container used by default when you create a virtual machine with VirtualBox.<br />
<br />
* '''VMDK''': The Virtual Machine Disk has been initially developed by VMware for their products. The specification was initially closed source, but it became now an open format which is fully supported by VirtualBox. This format offers the ability to be split into several 2GB files. This feature is especially useful if you want to store the virtual machine on machines which do not support very large files. Other formats, excluding the HDD format from Parallels, do not provide such an equivalent feature.<br />
<br />
* '''VHD''': The Virtual Hard Disk is the format used by Microsoft in Windows Virtual PC and Hyper-V. If you intend to use any of these Microsoft products, you will have to choose this format.<br />
:{{Tip|Since Windows 7, this format can be mounted directly without any additional application.}} <br />
<br />
* '''VHDX''' (read only): This is the eXtended version of the Virtual Hard Disk format developed by Microsoft, which has been released on 2012-09-04 with Hyper-V 3.0 coming with Windows Server 2012. This new version of the disk format does offer enhanced performance (better block alignment), larger blocks size, and journal support which brings power failure resiliency. VirtualBox [https://www.virtualbox.org/manual/ch15.html#idp63002176 should support this format in read only].<br />
<br />
* '''HDD''' (version 2): The HDD format is developed by Parallels Inc and used in their hypervisor solutions like Parallels Desktop for Mac. Newer versions of this format (i.e. 3 and 4) are not supported due to the lack of documentation for this proprietary format. {{Note|There is currently a controversy regarding the support of the version 2 of the format. While the official VirtualBox manual [https://www.virtualbox.org/manual/ch05.html#vdidetails only reports the second version of the HDD file format as supported], Wikipedia's contributors are [[Wikipedia:Comparison of platform virtual machines#Image type compatibility|reporting the first version may work too]]. Help is welcome if you can perform some tests with the first version of the HDD format.}}<br />
<br />
* '''QED''': The QEMU Enhanced Disk format is an old file format for QEMU, another free and open source hypervisor. This format was designed from 2010 in a way to provide a superior alternative to QCOW2 and others. This format features a fully asynchronous I/O path, strong data integrity, backing files, and sparse files. QED format is supported only for compatibility with virtual machines created with old versions of QEMU.<br />
<br />
* '''QCOW''': The QEMU Copy On Write format is the current format for QEMU. The QCOW format does support zlib-based transparent compression and encryption (the latter is flawed and is not recommended). QCOW is available in two versions: QCOW and QCOW2. QCOW2 tends to supersede the first one. QCOW is [https://www.virtualbox.org/manual/ch15.html#idp63002176 currently fully supported by VirtualBox]. QCOW2 comes in two revisions: QCOW2 0.10 and QCOW2 1.1 (which is the default when you create a virtual disk with QEMU). VirtualBox does not support QCOW2.<br />
<br />
* '''OVF''': The Open Virtualization Format is an open format which has been designed for interoperability and distributions of virtual machines between different hypervisors. VirtualBox supports all revisions of this format via the [https://www.virtualbox.org/manual/ch08.html#idp55423424 VBoxManage import/export feature] but with [https://www.virtualbox.org/manual/ch14.html#KnownProblems known limitations].<br />
<br />
* '''RAW''': This is the mode when the virtual disk is exposed directly to the disk without being contained in a specific file format container. VirtualBox supports this feature in several ways: converting RAW disk [https://www.virtualbox.org/manual/ch08.html#idp59139136 to a specific format], or by [https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi cloning a disk to RAW], or by using directly a VMDK file [https://www.virtualbox.org/manual/ch09.html#idp57804112 which points to a physical disk or a simple file].<br />
<br />
=== Disk image format conversion ===<br />
<br />
[https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi VBoxManage clonehd] can be used to convert between VDI, VMDK, VHD and RAW.<br />
<br />
$ VBoxManage clonehd ''inputfile'' ''outputfile'' --format ''outputformat''<br />
<br />
For example to convert VDI to VMDK:<br />
<br />
$ VBoxManage clonehd ''source.vdi'' ''destination.vmdk'' --format VMDK<br />
<br />
==== QCOW ====<br />
<br />
VirtualBox does not support [[QEMU]]'s QCOW2 disk image format. To use a QCOW2 disk image with VirtualBox you therefore need to convert it, which you can do with {{Pkg|qemu}}'s {{ic|qemu-img}} command. {{ic|qemu-img}} can convert QCOW to / from VDI, VMDK, VHDX, RAW and various other formats (which you can see by running {{ic|qemu-img --help}}).<br />
<br />
$ qemu-img convert -O ''output_fmt'' ''inputfile'' ''outputfile''<br />
<br />
For example to convert QCOW2 to VDI:<br />
<br />
$ qemu-img convert -O vdi ''source.qcow2'' ''destination.vdi''<br />
<br />
{{Tip|The {{ic|-p}} parameter is used to get the progression of the conversion task.}}<br />
<br />
There are two revisions of QCOW2: 0.10 and 1.1. You can specify the revision to use with {{ic|1=-o compat=''revision''}}.<br />
<br />
=== Mount virtual disks ===<br />
<br />
==== VDI ====<br />
<br />
Mounting VDI images only works with fixed size images (a.k.a. static images); dynamic (dynamically size allocating) images are not easily mountable.<br />
<br />
The offset of the partition (within the VDI) is needed, then add the value of {{ic|offData}} to {{ic|32256}} (e.g. 69632 + 32256 = 101888):<br />
<br />
$ VBoxManage internalcommands dumphdinfo <storage.vdi> | grep "offData"<br />
<br />
The can now be mounted with:<br />
<br />
# mount -t ext4 -o rw,noatime,noexec,loop,offset=101888 <storage.vdi> /mntpoint/<br />
<br />
You can also use [https://github.com/pld-linux/VirtualBox/blob/master/mount.vdi mount.vdi] script that, which you can use as (install script itself to {{ic|/usr/bin/}}):<br />
<br />
# mount -t vdi -o fstype=ext4,rw,noatime,noexec ''vdi_file_location'' ''/mnt/''<br />
<br />
Alternately you can use {{Pkg|qemu}}'s kernel module that can do this [http://bethesignal.org/blog/2011/01/05/how-to-mount-virtualbox-vdi-image/ attrib]:<br />
<br />
# modprobe nbd max_part=16<br />
# qemu-nbd -c /dev/nbd0 <storage.vdi><br />
# mount /dev/nbd0p1 /mnt/dir/<br />
# # to unmount:<br />
# umount /mnt/dir/<br />
# qemu-nbd -d /dev/nbd0<br />
<br />
If the partition nodes are not propagated try using {{ic|partprobe /dev/nbd0}}; otherwise, a VDI partition can be mapped directly to a node by: {{ic|qemu-nbd -P 1 -c /dev/nbd0 <storage.vdi>}}.<br />
<br />
=== Compact virtual disks ===<br />
<br />
Compacting virtual disks only works with ''.vdi'' files and basically consists of the following steps.<br />
<br />
Boot your virtual machine and remove all bloat manually or by using cleaning tools like {{Pkg|bleachbit}} which is [http://bleachbit.sourceforge.net/download/windows available for Windows systems too].<br />
<br />
Wiping free space with zeroes can be achieved with several tools:<br />
* If you were previously using Bleachbit, check the checkbox ''System > Free disk space'' in the GUI, or use {{ic|bleachbit -c system.free_disk_space}} in CLI;<br />
* On UNIX-based systems, by using {{ic|dd}} or preferably {{Pkg|dcfldd}} (see [http://superuser.com/a/355322 here] to learn the differences):<br />
:{{bc|1=# dcfldd if=/dev/zero of=''/fillfile'' bs=4M}}<br />
:When {{ic|fillfile}} reaches the limit of the partition, you will get a message like {{ic|1280 blocks (5120Mb) written.dcfldd:: No space left on device}}. This means that all of the user-space and non-reserved blocks of the partition will be filled with zeros. Using this command as root is important to make sure all free blocks have been overwritten. Indeed, by default, when using partitions with ext filesystem, a specified percentage of filesystem blocks is reserved for the super-user (see the {{ic|-m}} argument in the {{ic|mkfs.ext4}} man pages or use {{ic|tune2fs -l}} to see how much space is reserved for root applications).<br />
:When the aforementioned process has completed, you can remove the file {{ic|''fillfile''}} you created.<br />
<br />
* On Windows, there are two tools available:<br />
:*{{ic|sdelete}} from the [http://technet.microsoft.com/en-us/sysinternals/bb842062.aspx Sysinternals Suite], type {{ic|sdelete -s -z ''c:''}}, where you need to reexecute the command for each drive you have in your virtual machine;<br />
:* or, if you love scripts, there is a [http://blog.whatsupduck.net/2012/03/powershell-alternative-to-sdelete.html PowerShell solution], but which still needs to be repeated for all drives.<br />
::{{bc|PS> ./Write-ZeroesToFreeSpace.ps1 -Root ''c:\'' -PercentFree 0}}<br />
::{{Note|This script must be run in a PowerShell environment with administrator privileges. By default, scripts cannot be run, ensure the execution policy is at least on {{ic|RemoteSigned}} and not on {{ic|Restricted}}. This can be checked with {{ic|Get-ExecutionPolicy}} and the required policy can be set with {{ic|Set-ExecutionPolicy RemoteSigned}}.}}<br />
<br />
Once the free disk space have been wiped, shut down your virtual machine.<br />
<br />
The next time you boot your virtual machine, it is recommended to do a filesystem check.<br />
* On UNIX-based systems, you can use {{ic|fsck}} manually;<br />
:* On GNU/Linux systems, and thus on Arch Linux, you can force a disk check at boot [[Fsck#Forcing the check|thanks to a kernel boot parameter]];<br />
* On Windows systems, you can use:<br />
:* either {{ic|chkdsk ''c:'' /F}} where {{ic|''c:''}} needs to be replaced by each disk you need to scan and fix errors;<br />
:* or {{ic|FsckDskAll}} [http://therightstuff.de/2009/02/14/ChkDskAll-ChkDsk-For-All-Drives.aspx from here] which is basically the same software as {{ic|chkdsk}}, but without the need to repeat the command for all drives;<br />
<br />
Now, remove the zeros from the ''.vdi'' file with [https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvdi VBoxManage modifyhd]:<br />
$ VBoxManage modifyhd ''your_disk.vdi'' --compact<br />
<br />
{{Note|If your virtual machine has snapshots, you need to apply the above command on each {{ic|.vdi}} files you have.}}<br />
<br />
=== Increase virtual disks ===<br />
<br />
==== General procedure ====<br />
<br />
If you are running out of space due to the small hard drive size you selected when you created your virtual machine, the solution adviced by the VirtualBox manual is to use [https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvdi VBoxManage modifyhd]. However this command only works for VDI and VHD disks and only for the dynamically allocated variants. If you want to resize a fixed size virtual disk disk too, read on this trick which works either for a Windows or UNIX-like virtual machine.<br />
<br />
First, create a new virtual disk next to the one you want to increase:<br />
<br />
$ VBoxManage createhd -filename ''new.vdi'' --size ''10000''<br />
<br />
where size is in MiB, in this example 10000MiB ~= 10GiB, and ''new.vdi'' is name of new hard drive to be created.<br />
<br />
{{Note|By default, this command uses the ''Standard'' (corresponding to dynamic allocated) file format variant and thus will not use the same file format variant as your source virtual disk. If your ''old.vdi'' has a fixed size and you want to keep this variant, add the parameter {{ic|--variant Fixed}}.}}<br />
<br />
Next, the old virtual disk needs to be cloned to the new one which this may take some time:<br />
<br />
$ VBoxManage clonehd ''old.vdi'' ''new.vdi'' --existing<br />
<br />
Detach the old hard drive and attach new one, replace all mandatory italic arguments by your own:<br />
<br />
$ VBoxManage storageattach ''VM_name'' --storagectl ''SATA'' --port ''0'' --medium none<br />
$ VBoxManage storageattach ''VM_name'' --storagectl ''SATA'' --port ''0'' --medium ''new.vdi'' --type hdd<br />
<br />
To get the storage controller name and the port number, you can use the command {{ic|VBoxManage showvminfo ''VM_name''}}. Among the output you will get such a result (what you are looking for is in italic):<br />
<br />
{{bc|<br />
[...]<br />
Storage Controller Name (0): IDE<br />
Storage Controller Type (0): PIIX4<br />
Storage Controller Instance Number (0): 0<br />
Storage Controller Max Port Count (0): 2<br />
Storage Controller Port Count (0): 2<br />
Storage Controller Bootable (0): on<br />
Storage Controller Name (1): SATA<br />
Storage Controller Type (1): IntelAhci<br />
Storage Controller Instance Number (1): 0<br />
Storage Controller Max Port Count (1): 30<br />
Storage Controller Port Count (1): 1<br />
Storage Controller Bootable (1): on<br />
IDE (1, 0): Empty<br />
''SATA'' (''0'', 0): /home/wget/IT/Virtual_machines/GNU_Linux_distributions/ArchLinux_x64_EFI/Snapshots/{6bb17af7-e8a2-4bbf-baac-fbba05ebd704}.vdi (UUID: 6bb17af7-e8a2-4bbf-baac-fbba05ebd704)<br />
[...]<br />
}}<br />
<br />
Download [http://gparted.org/download.php GParted live image] and mount it as a virtual CD/DVD disk file, boot your virtual machine, increase/move your partitions, umount GParted live and reboot.<br />
<br />
{{Note|On GPT disks, increasing the size of the disk will result in the backup GPT header not being at the end of the device. GParted will ask to fix this, click on ''Fix'' both times. On MBR disks, you do not have such a problem as this partition table as no trailer at the end of the disk.}}<br />
<br />
Finally, unregister the virtual disk from VirtualBox and remove the file:<br />
<br />
$ VBoxManage closemedium disk ''old.vdi''<br />
$ rm ''old.vdi''<br />
<br />
==== Increasing the size of VDI disks ====<br />
<br />
If your disk is a VDI one, run:<br />
<br />
$ VBoxManage modifyhd ''your_virtual_disk.vdi'' --resize ''the_new_size''<br />
<br />
Then jump back to the Gparted step, to increase the size of the partition on the virtual disk.<br />
<br />
=== Replace a virtual disk manually from the .vbox file ===<br />
<br />
If you think that editing a simple ''XML'' file is more convenient than playing with the GUI or with {{ic|VBoxManage}} and you want to replace (or add) a virtual disk to your virtual machine, in the ''.vbox'' configuration file corresponding to your virtual machine, simply replace the GUID, the file location and the format to your needs:<br />
<br />
{{hc|ArchLinux_vm.vbox|2=<br />
<HardDisk uuid="''{670157e5-8bd4-4f7b-8b96-9ee412a712b5}''" location="''ArchLinux_vm.vdi''" format="''VDI''" type="Normal"/><br />
}}<br />
<br />
then in the {{ic|<AttachedDevice>}} sub-tag of {{ic|<StorageController>}}, replace the GUID by the new one.<br />
<br />
{{hc|ArchLinux_vm.vbox|2=<br />
<AttachedDevice type="HardDisk" port="0" device="0"><br />
<Image uuid="''{670157e5-8bd4-4f7b-8b96-9ee412a712b5}''"/><br />
</AttachedDevice><br />
}}<br />
<br />
{{Note|If you do not know the GUID of the drive you want to add, you can use the {{ic|VBoxManage showhdinfo ''file''}}. If you previously used {{ic|VBoxManage clonehd}} to copy/convert your virtual disk, this command should have outputted the GUID just after the copy/conversion completed. Using a random GUID does not work, as each [http://www.virtualbox.org/manual/ch05.html#cloningvdis UUID is stored inside each disk image].}}<br />
<br />
==== Transfer between Linux host and other OS ====<br />
<br />
The information about path to harddisks and the snapshots is stored between {{ic|<HardDisks> .... </HardDisks>}} tags in the file with the ''.vbox'' extension. You can edit them manually or use this script where you will need change only the path or use defaults, assumed that ''.vbox'' is in the same directory with a virtual harddisk and the snapshots folder. It will print out new configuration to stdout.<br />
<br />
{{bc|1=<br />
#!/bin/bash<br />
NewPath="${PWD}/"<br />
Snapshots="Snapshots/"<br />
Filename="$1"<br />
<br />
awk -v SetPath="$NewPath" -v SnapPath="$Snapshots" '{if(index($0,"<HardDisk uuid=") != 0){A=$3;split(A,B,"=");<br />
L=B[2];<br />
gsub(/\"/,"",L);<br />
sub(/^.*\//,"",L);<br />
sub(/^.*\\/,"",L);<br />
if(index($3,"{") != 0){SnapS=SnapPath}else{SnapS=""};<br />
print $1" "$2" location="\"SetPath SnapS L"\" "$4" "$5}<br />
else print $0}' "$Filename"<br />
}}<br />
<br />
{{Note|<br />
* If you will prepare virtual machine for use in Windows host then in the path name end you should use backslash \ instead of / .<br />
* The script detects snapshots by looking for {{ic|{}} in the file name.<br />
* To make it run on a new host you will need to add it first to the register by clicking on '''Machine -> Add...''' or use hotkeys Ctrl+A and then browse to ''.vbox'' file that contains configuration or use command line {{ic|VBoxManage registervm ''filename''.vbox}}<br />
}}<br />
<br />
=== Clone a virtual disk and assigning a new UUID to it ===<br />
<br />
UUIDs are widely used by VirtualBox. Each virtual machines and each virtual disk of a virtual machine must have a different UUID. When you launch a virtual machine in VirtualBox, VirtualBox will keep track of all UUIDs of your virtual machine instance. See the [http://www.virtualbox.org/manual/ch08.html#vboxmanage-list VBoxManage list] to list the items registered with VirtualBox.<br />
<br />
If you cloned a virtual disk manually by copying the virtual disk file, you will need to assign a new UUID to the cloned virtual drive if you want to use the disk in the same virtual machine or even in another (if that one has already been opened, and thus registered, with VirtualBox).<br />
<br />
You can use this command to assign a new UUID to a virtual disk: <br />
$ VBoxManage internalcommands sethduuid ''/path/to/disk.vdi''<br />
<br />
{{Tip|To avoid copying the virtual disk and assigning a new UUID to your file manually you can use [http://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi VBoxManage clonehd].}}<br />
<br />
{{Note|The commands above support all [[#Formats supported by VirtualBox|virtual disk formats supported by VirtualBox]].}}<br />
<br />
== Tips and tricks ==<br />
<br />
For advanced configuration, see [[VirtualBox/Tips and tricks]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Keyboard and mouse are locked into virtual machine ===<br />
<br />
This means your virtual machine has captured the input of your keyboard and your mouse. Simply press the right {{ic|Ctrl}} key and your input should control your host again.<br />
<br />
To control transparently your virtual machine with your mouse going back and forth your host, without having to press any key, and thus have a seamless integration, install the guest additions inside the guest. Read from the [[#Install the Guest Additions]] step if you guest is Arch Linux, otherwise read the official VirtualBox help.<br />
<br />
=== No 64-bit OS client options ===<br />
<br />
When launching a VM client, and no 64-bit options are available, make sure your CPU virtualization capabilities (usually named {{ic|VT-x}}) are enabled in the BIOS.<br />
<br />
If you are using a Windows host, you may need to disable Hyper-V, as it prevents VirtualBox from using VT-x. [https://www.virtualbox.org/ticket/12350]<br />
<br />
=== VirtualBox GUI does not match host GTK theme ===<br />
<br />
See [[Uniform look for Qt and GTK applications]] for information about theming Qt-based applications like VirtualBox.<br />
<br />
=== Cannot send Ctrl+Alt+Fn to guest ===<br />
<br />
Your guest operating system is a GNU/Linux distribution and you want to open a new TTY shell by hitting {{ic|Ctrl+Alt+F2}} or exit your current X session with {{ic|Ctrl+Alt+Backspace}}. If you type these keyboard shortcuts without any adaptation, the guest will not receive any input and the host (if it is a GNU/Linux distribution too) will intercept these shortcut keys. To send {{ic|Ctrl+Alt+F2}} to the guest for example, simply hit your ''Host Key'' (usually the right {{ic|Ctrl}} key) and press {{ic|F2}} simultaneously.<br />
<br />
=== USB subsystem not working ===<br />
<br />
Your user must be in the {{ic|vboxusers}} group and you need to install the [[#Extension pack|extension pack]] if you want USB 2 support. Then you will be able to enable USB 2 in the VM settings and add one or several filters for the devices you want to access from the guest OS.<br />
<br />
If {{ic|VBoxManage list usbhost}} does not show any USB devices even if run as root, make sure that there is no old udev rules (from VirtualBox 4.x) in {{ic|/etc/udev/rules.d/}}. VirtualBox 5.0 installs udev rules to {{ic|/usr/lib/udev/rules.d/}}. You can use command like {{ic|pacman -Qo /usr/lib/udev/rules.d/60-vboxdrv.rules}} to determine if the udev rule file is outdated.<br />
<br />
Sometimes, on old Linux hosts, the USB subsystem is not auto-detected resulting in an error {{ic|Could not load the Host USB Proxy service: VERR_NOT_FOUND}} or in a not visible USB drive on the host, [https://bbs.archlinux.org/viewtopic.php?id=121377 even when the user is in the '''vboxusers''' group]. This problem is due to the fact that VirtualBox switched from ''usbfs'' to ''sysfs'' in version 3.0.8. If the host does not understand this change, you can revert to the old behaviour by defining the following environment variable in any file that is sourced by your shell (e.g. your {{ic|~/.bashrc}} if you are using ''bash''):<br />
<br />
{{hc|~/.bashrc|2=<br />
VBOX_USB=usbfs<br />
}}<br />
<br />
Then make sure, the environment has been made aware of this change (reconnect, source the file manually, launch a new shell instance or reboot).<br />
<br />
Also make sure that your user is a member of the {{ic|storage}} group.<br />
<br />
=== USB modem not working on host ===<br />
<br />
If you have a USB modem which is being used by the guest OS, killing the guest OS can cause the modem to become unusable by the host system. Killing and restarting {{ic|VBoxSVC}} should fix this problem.<br />
<br />
=== Access serial port from guest ===<br />
<br />
Check you permission for the serial port:<br />
{{hc|$ ls -l /dev/ttyS*|<br />
crw-rw---- 1 root uucp 4, 64 Feb 3 09:12 /dev/ttyS0<br />
crw-rw---- 1 root uucp 4, 65 Feb 3 09:12 /dev/ttyS1<br />
crw-rw---- 1 root uucp 4, 66 Feb 3 09:12 /dev/ttyS2<br />
crw-rw---- 1 root uucp 4, 67 Feb 3 09:12 /dev/ttyS3<br />
}}<br />
<br />
Add your user to the {{ic|uucp}} [[user group]].<br />
<br />
=== Guest freezes after starting Xorg ===<br />
<br />
Faulty or missing drivers may cause the guest to freeze after starting Xorg, see for example [https://bbs.archlinux.org/viewtopic.php?pid=1167838] and [https://bbs.archlinux.org/viewtopic.php?id=156079]. Try disabling 3D acceleration in ''Settings > Display'', and check if all [[Xorg]] drivers are installed.<br />
<br />
=== Fullscreen mode shows blank screen ===<br />
<br />
On some window managers ([[i3]], [[awesome]]), VirtualBox has issues with fullscreen mode properly due to the overlay bar. To work around this issue, disable "Show in Full-screen/Seamless" option in "Guest Settings > User Interface > Mini ToolBar". See the [https://www.virtualbox.org/ticket/14323 upstream bug report] for more information.<br />
<br />
=== Host freezes on virtual machine start ===<br />
<br />
{{Expansion|Needs a link to a bug report.}}<br />
<br />
Possible causes/solutions:<br />
<br />
* SMAP<br />
This is a known incompatiblity with SMAP enabled kernels affecting (mostly) Intel Broadwell chipsets. A solution to this problem is disabling SMAP support in your kernel by appending the {{ic|nosmap}} option to your [[kernel parameters]].<br />
* Hardware Virtualisation<br />
Disabling hardware virtualisation (VT-x/AMD-V) may solve the problem.<br />
* Various Kernel bugs<br />
** Fuse mounted partitions (like ntfs) [https://bbs.archlinux.org/viewtopic.php?id=185841], [https://bugzilla.kernel.org/show_bug.cgi?id=82951#c12]<br />
<br />
Generally, such issues are observed after upgrading VirtualBox or linux kernel. Downgrading them to the previous versions of theirs might solve the problem.<br />
<br />
=== Linux guests have slow/distorted audio ===<br />
<br />
The AC97 audio driver within the Linux kernel occasionally guesses the wrong clock settings when running inside Virtual Box, leading to audio that is either too slow or too fast. To fix this, create a file in {{ic|/etc/modprobe.d/}} with the following line:<br />
<br />
options snd-intel8x0 ac97_clock=48000<br />
<br />
=== Analog microphone not working ===<br />
<br />
If the audio input from an analog microphone is working correctly on the host, but no sound seems to get through to the guest, despite the microphone device apparently being detected normally, installing a [[Sound system#Sound servers|sound server]] such as [[PulseAudio]] on the host might fix the problem.<br />
<br />
If after installing [[PulseAudio]] the microphone still refuses to work, setting ''Host Audio Driver'' (under ''VirtualBox > Machine > Settings > Audio'') to ''ALSA Audio Driver'' might help.<br />
<br />
=== Microphone not working after upgrade ===<br />
<br />
There have been issues reported around sound input in 5.1.x versions. [https://forums.virtualbox.org/viewtopic.php?f=7&t=78797]<br />
<br />
[[Downgrading]] may solve the problem. You can use {{aur|virtualbox-bin-5.0}} to ease downgrading.<br />
<br />
=== Problems with images converted to ISO ===<br />
<br />
Some image formats cannot be reliably converted to ISO. For instance, {{Pkg|ccd2iso}} ignores .ccd and .sub files, which can result in disk images with broken files. <br />
<br />
In this case, you will either have to use [[CDemu]] for Linux inside VirtualBox or any other utility used to mount disk images.<br />
<br />
=== Failed to create the host-only network interface ===<br />
<br />
Make sure all required kernel modules are loaded. See [[#Load the VirtualBox kernel modules]].<br />
<br />
If all required kernel modules are loaded and you are still unable to create the host-only adapter, navigate to ''File > Host Network Manager'' and click the ''Create'' button to add the network interface.<br />
<br />
=== Failed to insert module ===<br />
<br />
When you get the following error when trying to load modules:<br />
<br />
Failed to insert 'vboxdrv': Required key not available<br />
<br />
[[#Sign modules|Sign]] your modules or disable {{ic|CONFIG_MODULE_SIG_FORCE}} in your kernel config.<br />
<br />
=== VBOX_E_INVALID_OBJECT_STATE (0x80BB0007) ===<br />
<br />
This can occur if a VM is exited ungracefully. Run the following command:<br />
<br />
$ VBoxManage controlvm ''virtual_machine_name'' poweroff<br />
<br />
=== NS_ERROR_FAILURE and missing menu items ===<br />
<br />
This happens sometimes when selecting ''QCOW''/''QCOW2''/''QED'' disk format when creating a new virtual disk.<br />
<br />
If you encounter this message the first time you start the virtual machine:<br />
<br />
{{bc|Failed to open a session for the virtual machine debian.<br />
Could not open the medium '/home/.../VirtualBox VMs/debian/debian.qcow'.<br />
QCow: Reading the L1 table for image '/home/.../VirtualBox VMs/debian/debian.qcow' failed (VERR_EOF).<br />
VD: error VERR_EOF opening image file '/home/.../VirtualBox VMs/debian/debian.qcow' (VERR_EOF).<br />
<br />
Result Code: <br />
NS_ERROR_FAILURE (0x80004005)<br />
Component: <br />
Medium<br />
}}<br />
<br />
Exit VirtualBox, delete all files of the new machine and from virtualbox config file remove the last line in {{ic|MachineRegistry}} menu (or the offending machine you are creating):<br />
<br />
{{hc|~/.config/VirtualBox/VirtualBox.xml|2=<br />
...<br />
<MachineRegistry><br />
<MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/debian/debian.vbox"/><br />
<MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/ubuntu/ubuntu.vbox"/><br />
<strike><MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/lastvmcausingproblems/lastvmcausingproblems.qcow"/></strike><br />
</MachineRegistry><br />
...<br />
}}<br />
<br />
=== Arch: pacstrap script fails ===<br />
<br />
If you used ''pacstrap'' in the [[#Installation steps for Arch Linux guests]] to also [[#Install the Guest Additions]] '''before''' performing a first boot into the new guest, you will need to {{ic|umount -l /mnt/dev}} as root before using ''pacstrap'' again; a failure to do this will render it unusable.<br />
<br />
=== OpenBSD unusable when virtualisation instructions unavailable ===<br />
<br />
While OpenBSD is reported to work fine on other hypervisors without virtualisation instructions (VT-x AMD-V) enabled, an OpenBSD virtual machine running on VirtualBox without these instructions will be unusable, manifesting with a bunch of segmentation faults. Starting VirtualBox with the ''-norawr0'' argument [https://www.virtualbox.org/ticket/3947 may solve the problem]. You can do it like this:<br />
$ VBoxSDL -norawr0 -vm ''name_of_OpenBSD_VM''<br />
<br />
=== Windows host: VERR_ACCESS_DENIED ===<br />
<br />
To access the raw VMDK image on a Windows host, run the VirtualBox GUI as administrator.<br />
<br />
=== Windows: "The specified path does not exist. Check the path and then try again." ===<br />
<br />
This error message may appear when running an {{ic|.exe}} file which requires administrator privileges from a shared folder in windows guests. [https://www.virtualbox.org/ticket/5732#comment:39]<br />
<br />
As a workaround, copy the file to the virtual drive or use [[w:Uniform Naming Convention|UNC paths]] ({{ic|\\vboxsvr}}). See [https://support.microsoft.com/de-de/help/2019185/copying-files-from-a-mapped-drive-to-a-local-directory-fails-with-erro] for more information.<br />
<br />
=== Windows 8.x error code 0x000000C4===<br />
<br />
If you get this error code while booting, even if you choose OS Type Win 8, try to enable the {{ic|CMPXCHG16B}} CPU instruction:<br />
<br />
$ vboxmanage setextradata ''virtual_machine_name'' VBoxInternal/CPUM/CMPXCHG16B 1<br />
<br />
=== Windows 8, 8.1 or 10 fails to install, boot or has error "ERR_DISK_FULL" ===<br />
<br />
Update the VM's settings by going to ''Settings > Storage > Controller:SATA'' and check "Use Host I/O Cache".<br />
<br />
=== WinXP: Bit-depth cannot be greater than 16 ===<br />
<br />
If you are running at 16-bit color depth, then the icons may appear fuzzy/choppy. However, upon attempting to change the color depth to a higher level, the system may restrict you to a lower resolution or simply not enable you to change the depth at all. To fix this, run {{ic|regedit}} in Windows and add the following key to the Windows XP VM's registry:<br />
<br />
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services]<br />
"ColorDepth"=dword:00000004<br />
<br />
Then update the color depth in the "desktop properties" window. If nothing happens, force the screen to redraw through some method (i.e. {{ic|Host+f}} to redraw/enter full screen).<br />
<br />
=== Windows: Screen flicker if 3D acceleration enabled ===<br />
<br />
VirtualBox > 4.3.14 has a regression in which Windows guests with 3D acceleration flicker. Since r120678 a patch has been implemented to recognize an [[environment variable]] setting, launch VirtualBox like this:<br />
<br />
$ CR_RENDER_FORCE_PRESENT_MAIN_THREAD=0 VirtualBox<br />
<br />
Make sure no VirtualBox services are still running. See [https://www.virtualbox.org/ticket/13653 VirtualBox bug 13653].<br />
<br />
=== No hardware 3D acceleration in Arch Linux guest ===<br />
<br />
{{Pkg|virtualbox-guest-utils}} package as of version 5.2.16-2 does not contain the file {{ic|VBoxEGL.so}}. This causes the Arch Linux guest does not have proper 3D acceleration. See {{Bug|49752}}.<br />
<br />
To deal with this problem, apply the patch set at {{Bug|49752#comment152254}}. Some fix to the patch set is required to make it work for version 5.2.16-2.<br />
<br />
=== Black screen for guest in EFI mode ===<br />
<br />
When the guest is using UEFI in Virtualbox by following [[#Installation in EFI mode]], you will get a black screen during boot and after if the VM's Graphics Controller is set to VBoxSVGA.<br />
<br />
This is because you are experiencing {{Bug|61184}}.<br />
<br />
The workaround is to use VMSVGA (the default) or VBoxVGA as the graphics controller. Go to VM ''Settings > Display''' and change the ''Graphics Controller'' to either ''VMSVGA'' or ''VBoxVGA''.<br />
<br />
== Known issues ==<br />
<br />
=== Automounting does not work ===<br />
<br />
Automounting does not work with the packaged guest additions {{Pkg|virtualbox-guest-utils}} and {{Pkg|virtualbox-guest-utils-nox}} starting with version 6.0.0-1. See {{Bug|61307}}.<br />
<br />
== See also ==<br />
<br />
* [https://www.virtualbox.org/manual/UserManual.html VirtualBox User Manual]<br />
* [[Wikipedia:VirtualBox]]</div>Pgoetzhttps://wiki.archlinux.org/index.php?title=VirtualBox&diff=565456VirtualBox2019-02-01T15:39:56Z<p>Pgoetz: formatting for readability</p>
<hr />
<div>[[Category:Hypervisors]]<br />
[[Category:Oracle]]<br />
[[cs:VirtualBox]]<br />
[[de:VirtualBox]]<br />
[[el:VirtualBox]]<br />
[[es:VirtualBox]]<br />
[[fr:VirtualBox]]<br />
[[hu:VirtualBox]]<br />
[[it:VirtualBox]]<br />
[[ja:VirtualBox]]<br />
[[pt:VirtualBox]]<br />
[[ru:VirtualBox]]<br />
[[zh-hans:VirtualBox]]<br />
{{Related articles start}}<br />
{{Related|VirtualBox/Tips and tricks}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|PhpVirtualBox}}<br />
{{Related|RemoteBox}}<br />
{{Related|Moving an existing install into (or out of) a virtual machine}}<br />
{{Related articles end}}<br />
<br />
[https://www.virtualbox.org VirtualBox] is a [[Wikipedia:Hypervisor|hypervisor]] used to run operating systems in a special environment, called a virtual machine, on top of the existing operating system. VirtualBox is in constant development and new features are implemented continuously. It comes with a [[Qt]] GUI interface, as well as headless and [[Wikipedia:Simple DirectMedia Layer|SDL]] command-line tools for managing and running virtual machines.<br />
<br />
In order to integrate functions of the host system to the guests, including shared folders and clipboard, video acceleration and a seamless window integration mode, ''guest additions'' are provided for some guest operating systems.<br />
<br />
== Installation steps for Arch Linux hosts ==<br />
<br />
In order to launch VirtualBox virtual machines on your Arch Linux box, follow these installation steps.<br />
<br />
=== Install the core packages ===<br />
<br />
[[Install]] the {{Pkg|virtualbox}} package. You will need to choose a package to provide host modules:<br />
* for {{Pkg|linux}} kernel choose {{Pkg|virtualbox-host-modules-arch}}<br />
* for other [[kernels]] choose {{Pkg|virtualbox-host-dkms}}<br />
** It is also necessary to install the appropriate headers package(s) for your installed kernel(s): {{Pkg|linux-headers}} or {{Pkg|linux-lts-headers}}. [https://lists.archlinux.org/pipermail/arch-dev-public/2016-March/027808.html] When either VirtualBox or the kernel is updated, the kernel modules will be automatically recompiled thanks to the [[DKMS]] Pacman hook.<br />
<br />
=== Sign modules ===<br />
<br />
When using a custom kernel with {{ic|CONFIG_MODULE_SIG_FORCE}} option enabled, you must sign your modules with a key generated during kernel compilation.<br />
<br />
Navigate to your kernel tree folder and execute the following command:<br />
# for module in `ls /lib/modules/$(uname -r)/kernel/misc/{vboxdrv.ko,vboxnetadp.ko,vboxnetflt.ko,vboxpci.ko}` ; do ./scripts/sign-file sha1 certs/signing_key.pem certs/signing_key.x509 $module ; done<br />
<br />
{{Note|Hashing algorithm does not have to match the one configured, but it must be built into the kernel.}}<br />
<br />
=== Load the VirtualBox kernel modules ===<br />
<br />
{{Pkg|virtualbox-host-modules-arch}} and {{Pkg|virtualbox-host-dkms}} use {{ic|systemd-modules-load.service}} to load all four VirtualBox modules automatically at boot time. For the modules to be loaded after installation, either reboot or load the modules once manually.<br />
<br />
{{Note|If you do not want the VirtualBox modules to be automatically loaded at boot time, you have to [[mask]] the default {{ic|/usr/lib/modules-load.d/virtualbox-host-modules-arch.conf}} (or {{ic|/usr/lib/modules-load.d/virtualbox-host-dkms.conf}}) by creating an empty file (or symlink to {{ic|/dev/null}}) with the same name in {{ic|/etc/modules-load.d/}}.}}<br />
<br />
Among the [[kernel modules]] VirtualBox uses, there is a mandatory module named {{ic|vboxdrv}}, which must be loaded before any virtual machines can run.<br />
<br />
To load the module manually, run:<br />
<br />
# modprobe vboxdrv<br />
<br />
The following modules are only required in advanced configurations:<br />
<br />
* {{ic|vboxnetadp}} and {{ic|vboxnetflt}} are both needed when you intend to use the [https://www.virtualbox.org/manual/ch06.html#network_bridged bridged] or [https://www.virtualbox.org/manual/ch06.html#network_hostonly host-only networking] feature. More precisely, {{ic|vboxnetadp}} is needed to create the host interface in the VirtualBox global preferences, and {{ic|vboxnetflt}} is needed to launch a virtual machine using that network interface.<br />
<br />
* {{ic|vboxpci}} is needed when your virtual machine needs to pass through a PCI device on your host.<br />
<br />
{{Note|If the VirtualBox kernel modules were loaded in the kernel while you updated the modules, you need to reload them manually to use the new updated version. To do it, run {{ic|vboxreload}} as root.}}<br />
<br />
=== Accessing host USB devices in guest ===<br />
<br />
To use the USB ports of your host machine in your virtual machines, add users that will be authorized to use this feature to the {{ic|vboxusers}} [[user group]].<br />
<br />
=== Guest additions disc ===<br />
<br />
It is also recommended to install the {{Pkg|virtualbox-guest-iso}} package on the host running VirtualBox. This package will act as a disc image that can be used to install the guest additions onto guest systems other than Arch Linux. The ''.iso'' file will be located at {{ic|/usr/lib/virtualbox/additions/VBoxGuestAdditions.iso}}, and may have to be mounted manually inside the virtual machine. Once mounted, you can run the guest additions installer inside the guest.<br />
<br />
=== Extension pack ===<br />
<br />
The Oracle Extension Pack provides [https://www.virtualbox.org/manual/ch01.html#intro-installing additional features] and is released under a non-free license '''only available for personal use'''. To install it, the {{aur|virtualbox-ext-oracle}} package is available, and a prebuilt version can be found in the [[Unofficial user repositories#seblu|seblu]] repository.<br />
<br />
If you prefer to use the traditional and manual way: download the extension manually and install it via the GUI (''File > Preferences > Extensions'') or via {{ic|VBoxManage extpack install <.vbox-extpack>}}, make sure you have a toolkit like [[Polkit]] to grant privileged access to VirtualBox. The installation of this extension [https://www.virtualbox.org/ticket/8473 requires root access].<br />
<br />
=== Front-ends ===<br />
<br />
VirtualBox comes with three front-ends:<br />
<br />
* If you want to use VirtualBox with the regular GUI, use {{ic|VirtualBox}}.<br />
* If you want to launch and manage your virtual machines from the command-line, use the {{ic|VBoxSDL}} command, which only provides a plain window for the virtual machine without any overlays.<br />
* If you want to use VirtualBox without running any GUI (e.g. on a server), use the {{ic|VBoxHeadless}} command. With the VRDP extension you can still remotely access the displays of your virtual machines.<br />
<br />
Finally, you can also use [[phpVirtualBox]] to administrate your virtual machines via a web interface.<br />
<br />
Refer to the [https://www.virtualbox.org/manual VirtualBox manual] to learn how to create virtual machines.<br />
<br />
{{Warning|If you intend to store virtual disk images on a [[Btrfs]] file system, before creating any images, you should consider disabling [[Btrfs#Copy-on-Write (CoW)|copy-on-write]] for the destination directory of these images.}}<br />
<br />
== Installation steps for Arch Linux guests ==<br />
<br />
Boot the Arch installation media through one of the virtual machine's virtual drives. Then, complete the installation of a basic Arch system as explained in the [[Installation guide]].<br />
<br />
=== Installation in EFI mode ===<br />
<br />
If you want to install Arch Linux in EFI mode inside VirtualBox, in the settings of the virtual machine, choose ''System'' item from the panel on the left and ''Motherboard'' tab from the right panel, and check the checkbox ''Enable EFI (special OSes only)''. After selecting the kernel from the Arch Linux installation media's menu, the media will hang for a minute or two and will continue to boot the kernel normally afterwards. Be patient.<br />
<br />
Once the system and the boot loader are installed, VirtualBox will first attempt to run {{ic|/EFI/BOOT/BOOTX64.EFI}} from the [[ESP]]. If that first option fails, VirtualBox will then try the EFI shell script {{ic|startup.nsh}} from the root of the ESP. This means that in order to boot the system you have the following options:<br />
<br />
* [[Unified Extensible Firmware Interface#UEFI Shell|Launch the bootloader manually]] from the EFI shell every time;<br />
* Move the bootloader to the default {{ic|/EFI/BOOT/BOOTX64.EFI}} path;<br />
* Create a script named {{ic|startup.nsh}} at the ESP root containing the path to the boot loader application, e.g. {{ic|\EFI\grub\grubx64.efi}}.<br />
* Boot directly from the ESP partition using a [[EFISTUB#Using a startup.nsh script|startup.nsh script]]. <br />
<br />
Do not bother with the VirtualBox Boot Manager (accessible with {{ic|F2}} at boot), as it is buggy and incomplete. It does not store efivars set interactively. Therefore, EFI entries added to it manually in the firmware (accessed with {{ic|F12}} at boot time) or with {{Pkg|efibootmgr}} will persist after a reboot [https://www.virtualbox.org/ticket/11177 but are lost when the VM is shut down].<br />
<br />
See also [https://bbs.archlinux.org/viewtopic.php?id=158003 UEFI VirtualBox installation boot problems].<br />
<br />
{{Note|In UEFI mode you may experience a black screen, see [[#Black screen for guest in EFI mode]] for a workaround.}}<br />
<br />
=== Install the Guest Additions ===<br />
<br />
VirtualBox [https://www.virtualbox.org/manual/ch04.html Guest Additions] provides drivers and applications that optimize the guest operating system including improved image resolution and better control of the mouse. Within the installed guest system, install:<br />
<br />
* {{Pkg|virtualbox-guest-utils}} for VirtualBox Guest utilities with X support<br />
* {{Pkg|virtualbox-guest-utils-nox}} for VirtualBox Guest utilities without X support<br />
<br />
Both packages will make you choose a package to provide guest modules:<br />
<br />
* for the default {{Pkg|linux}} kernel choose {{Pkg|virtualbox-guest-modules-arch}}<br />
* for non-default [[kernels]] choose {{Pkg|virtualbox-guest-dkms}}<br />
<br />
To compile the virtualbox modules provided by {{Pkg|virtualbox-guest-dkms}}, it will also be necessary to install the appropriate headers package(s) for your installed kernel(s) (e.g. {{Pkg|linux-lts-headers}} for {{Pkg|linux-lts}}). [https://lists.archlinux.org/pipermail/arch-dev-public/2016-March/027808.html] When either VirtualBox or the kernel is updated, the kernel modules will be automatically recompiled thanks to the [[DKMS]] Pacman hook.<br />
<br />
{{Note|<nowiki></nowiki><br />
* You can alternatively install the Guest Additions with the ISO from the {{Pkg|virtualbox-guest-iso}} package, provided you installed this on the host system. To do this, go to the device menu click Insert Guest Additions CD Image.<br />
* To recompile the vbox kernel modules, run {{ic|rcvboxdrv}} as root.<br />
}}<br />
<br />
The guest additions running on your guest, and the VirtualBox application running on your host must have matching versions, otherwise the guest additions (like shared clipboard) may stop working. If you upgrade your guest (e.g. {{ic|pacman -Syu}}), make sure your VirtualBox application on this host is also the latest version. "Check for updates" in the VirtualBox GUI is sometimes not sufficient; check the [https://www.virtualbox.org/ VirtualBox.org] website.<br />
<br />
=== Set optimal framebuffer resolution ===<br />
<br />
{{Move|VirtualBox/Tips and tricks}}<br />
Typically after installing Guest Additions, a fullscreen Arch guest running X will be set to the optimal resolution for your display; however, the virtual console's framebuffer will be set to a standard, often smaller, resolution detected from VirtualBox's custom VESA driver.<br />
<br />
To use the virtual consoles at optimal resolution, Arch needs to recognize that resolution as valid, which in turn requires VirtualBox to pass this information along to the guest OS.<br />
<br />
First, check if your desired resolution is not already recognized by running the command:<br />
<br />
hwinfo --framebuffer<br />
<br />
If the optimal resolution does not show up, then you will need to run the {{ic|VBoxManage}} tool on the host machine and add "extra resolutions" to your virtual machine (on a Windows host, go to the VirtualBox installation directory to find {{ic|VBoxManage.exe}}). For example:<br />
<br />
$ VBoxManage setextradata "Arch Linux" "CustomVideoMode1" "1360x768x24"<br />
<br />
The parameters "Arch Linux" and "1360x768x24" in the example above should be replaced with your VM name and the desired framebuffer resolution. Incidentally, this command allows for defining up to 16 extra resolutions ("CustomVideoMode1" through "CustomVideoMode16").<br />
<br />
Afterwards, restart the virtual machine and run {{ic|hwinfo --framebuffer}} once more to verify that the new resolutions have been recognized by your guest system (which does not guarantee they will all work, depending on your hardware limitations).<br />
<br />
{{Note|As of VirtualBox 5.2, {{ic|hwinfo --framebuffer}} might not show any output, but you should still be able to set a custom resolution following this procedure.}}<br />
<br />
Finally, add a {{ic|1=video=''resolution''}} [[kernel parameter]] to set the framebuffer to the new resolution, for example:<br />
<br />
video=1360x768<br />
<br />
Additionally you may want to configure your [[bootloader]] to use the same resolution. If you use GRUB, see [[GRUB/Tips and tricks#Setting the framebuffer resolution]].<br />
<br />
{{Note|Neither the kernel parameter {{ic|vga}} nor the bootloader's resolution settings (e.g. GRUB's {{ic|GRUB_GFXPAYLOAD_LINUX}}) will fix the framebuffer, since they are overriden by virtue of Kernel Mode Setting. The framebuffer resolution must be set by the kernel parameter {{ic|video}} as described above.}}<br />
<br />
=== Load the VirtualBox kernel modules ===<br />
<br />
To load the modules automatically, [[enable]] {{ic|vboxservice.service}} which loads the modules and synchronizes the guest's system time with the host.<br />
<br />
To load the modules manually, type:<br />
<br />
# modprobe -a vboxguest vboxsf vboxvideo<br />
<br />
{{Pkg|virtualbox-guest-dkms}} uses {{ic|systemd-modules-load.service}} to load its modules at boot time.<br />
<br />
{{Note|If you do not want the VirtualBox modules to be loaded at boot time, you have to [[mask]] the default {{ic|/usr/lib/modules-load.d/virtualbox-guest-dkms.conf}} by creating an empty file (or symlink to {{ic|/dev/null}}) with the same name in {{ic|/etc/modules-load.d/}}.}}<br />
<br />
=== Launch the VirtualBox guest services ===<br />
<br />
After the rather big installation step dealing with VirtualBox kernel modules, now you need to start the guest services. The guest services are actually just a binary executable called {{ic|VBoxClient}} which will interact with your X Window System. {{ic|VBoxClient}} manages the following features:<br />
<br />
* shared clipboard and drag and drop between the host and the guest;<br />
* seamless window mode;<br />
* the guest display is automatically resized according to the size of the guest window;<br />
* checking the VirtualBox host version<br />
<br />
All of these features can be enabled independently with their dedicated flags:<br />
<br />
$ VBoxClient --clipboard --draganddrop --seamless --display --checkhostversion<br />
<br />
As a shortcut, the {{ic|VBoxClient-all}} bash script enables all of these features.<br />
<br />
{{Pkg|virtualbox-guest-utils}} installs {{ic|/etc/xdg/autostart/vboxclient.desktop}} that launches {{ic|VBoxClient-all}} on logon. If your [[desktop environment]] or [[window manager]] does not support [[XDG Autostart]], you will need to set up autostarting yourself, see [[Autostarting#On desktop environment startup]] and [[Autostarting#On window manager startup]] for more details.<br />
<br />
VirtualBox can also synchronize the time between the host and the guest, to do this, [[start/enable]] the {{ic|vboxservice.service}}.<br />
<br />
Now, you should have a working Arch Linux guest. Note that features like clipboard sharing are disabled by default in VirtualBox, and you will need to turn them on in the per-VM settings if you actually want to use them (e.g. ''Settings > General > Advanced > Shared Clipboard'').<br />
<br />
=== Hardware acceleration ===<br />
<br />
Hardware acceleration can be activated in the VirtualBox options. The [[GDM]] display manager 3.16+ is known to break hardware acceleration support. [https://bugzilla.gnome.org/show_bug.cgi?id=749390] So if you get issues with hardware acceleration, try out another display manager (lightdm seems to work fine). [https://bbs.archlinux.org/viewtopic.php?id=200025] [https://bbs.archlinux.org/viewtopic.php?pid=1607593#p1607593]<br />
<br />
=== Enable shared folders ===<br />
<br />
Shared folders are managed on the host, in the settings of the Virtual Machine accessible via the GUI of VirtualBox, in the ''Shared Folders'' tab. There, ''Folder Path'', the name of the mount point identified by ''Folder name'', and options like ''Read-only'', ''Auto-mount'' and ''Make permanent'' can be specified. These parameters can be defined with the {{ic|VBoxManage}} command line utility. See [https://www.virtualbox.org/manual/ch04.html#sharedfolders there for more details].<br />
<br />
No matter which method you will use to mount your folder, all methods require some steps first.<br />
<br />
To avoid this issue {{ic|/sbin/mount.vboxsf: mounting failed with the error: No such device}}, make sure the {{ic|vboxsf}} kernel module is properly loaded. It should be, since we enabled all guest kernel modules previously.<br />
<br />
Two additional steps are needed in order for the mount point to be accessible from users other than root:<br />
<br />
* the {{Pkg|virtualbox-guest-utils}} package created a group {{ic|vboxsf}} (done in a previous step);<br />
* your user must be in {{ic|vboxsf}} [[user group]].<br />
<br />
==== Manual mounting ====<br />
<br />
Use the following command to mount your folder in your Arch Linux guest:<br />
<br />
# mount -t vboxsf ''shared_folder_name'' ''mount_point_on_guest_system''<br />
<br />
where ''shared_folder_name'' is the ''Folder name'' assigned by the hypervisor when the share was created.<br />
<br />
The vboxsf filesystem offers other options which can be displayed with this command:<br />
<br />
# mount.vboxsf<br />
<br />
For example if the user was not in the ''vboxsf'' group, we could have used this command to give access our mountpoint to him:<br />
<br />
# mount -t vboxsf -o uid=1000,gid=1000 home /mnt<br />
<br />
Where ''uid'' and ''gid'' are values corresponding to the users we want to give access to. These values are obtained from the {{ic|id}} command run against this user.<br />
<br />
==== Automounting ====<br />
<br />
{{Note|Automounting requires the {{ic|vboxservice.service}} to be [[enabled]]/[[started]].}}<br />
<br />
In order for the automounting feature to work you must have checked the auto-mount checkbox in the GUI or used the optional {{ic|--automount}} argument with the command {{ic|VBoxManage sharedfolder}}.<br />
<br />
The shared folder should now appear in {{ic|/media/sf_''shared_folder_name''}}. If users in {{ic|media}} cannot access the shared folders, check that {{ic|media}} has permissions {{ic|755}} or has group ownership {{ic|vboxsf}} if using permission {{ic|750}}. This is currently not the default if media is created by installing {{Pkg|virtualbox-guest-utils}}.<br />
<br />
You can use symlinks if you want to have a more convenient access and avoid to browse in that directory, e.g.:<br />
$ ln -s /media/sf_''shared_folder_name'' ~/''my_documents''<br />
<br />
==== Mount at boot ====<br />
<br />
You can mount your directory with [[fstab]]. However, to prevent startup problems with systemd, {{ic|1=noauto,x-systemd.automount}} should be added to {{ic|/etc/fstab}}. This way, the shared folders are mounted only when those mount points are accessed and not during startup. This can avoid some problems, especially if the guest additions are not loaded yet when systemd reads fstab and mounts the partitions.<br />
''sharedFolderName'' ''/path/to/mntPtOnGuestMachine'' vboxsf uid=''user'',gid=''group'',rw,dmode=700,fmode=600,noauto,x-systemd.automount <br />
<br />
* {{ic|''sharedFolderName''}}: the value from the VirtualMachine's ''Settings > SharedFolders > Edit > FolderName'' menu. This value can be different from the name of the real folder name on the host machine. To see the VirtualMachine's ''Settings'' go to the host OS VirtualBox application, select the corresponding virtual machine and click on ''Settings''.<br />
* {{ic|''/path/to/mntPtOnGuestMachine''}}: if not existing, this directory should be created manually (for example by using [[Core utilities#Essentials|mkdir]]).<br />
* {{ic|dmode}}/{{ic|fmode}} are directory/file permissions for directories/files inside {{ic|''/path/to/mntPtOnGuestMachine''}}.<br />
<br />
As of 2012-08-02, mount.vboxsf does not support the ''nofail'' option:<br />
''desktop'' ''/media/desktop'' vboxsf uid=''user'',gid=''group'',rw,dmode=700,fmode=600,nofail 0 0<br />
<br />
=== SSH from host to guest ===<br />
<br />
The network tab of the virtual machine settings contains, in "Advanced", a tool to create port forwarding. <br />
It is possible to use it to forward the Guest ssh port {{ic|22}} to a Host port, e.g. {{ic|3022}} :<br />
<br />
user@host$ ssh -p 3022 $USER@localhost<br />
<br />
will establish a connection from Host to Guest.<br />
<br />
==== SSHFS as alternative to the shared folder ====<br />
<br />
Using this port forwarding and sshfs, it is straightforward to mount the Guest filesystem onto the Host one:<br />
<br />
user@host$ sshfs -p 3022 $USER@localhost:$HOME ~/shared_folder<br />
<br />
and then transfer files between both.<br />
<br />
== Virtual disks management ==<br />
<br />
See also [[VirtualBox/Tips and tricks#Import/export VirtualBox virtual machines from/to other hypervisors]].<br />
<br />
=== Formats supported by VirtualBox ===<br />
<br />
VirtualBox supports the following virtual disk formats:<br />
<br />
* '''VDI''': The Virtual Disk Image is the VirtualBox own open container used by default when you create a virtual machine with VirtualBox.<br />
<br />
* '''VMDK''': The Virtual Machine Disk has been initially developed by VMware for their products. The specification was initially closed source, but it became now an open format which is fully supported by VirtualBox. This format offers the ability to be split into several 2GB files. This feature is especially useful if you want to store the virtual machine on machines which do not support very large files. Other formats, excluding the HDD format from Parallels, do not provide such an equivalent feature.<br />
<br />
* '''VHD''': The Virtual Hard Disk is the format used by Microsoft in Windows Virtual PC and Hyper-V. If you intend to use any of these Microsoft products, you will have to choose this format.<br />
:{{Tip|Since Windows 7, this format can be mounted directly without any additional application.}} <br />
<br />
* '''VHDX''' (read only): This is the eXtended version of the Virtual Hard Disk format developed by Microsoft, which has been released on 2012-09-04 with Hyper-V 3.0 coming with Windows Server 2012. This new version of the disk format does offer enhanced performance (better block alignment), larger blocks size, and journal support which brings power failure resiliency. VirtualBox [https://www.virtualbox.org/manual/ch15.html#idp63002176 should support this format in read only].<br />
<br />
* '''HDD''' (version 2): The HDD format is developed by Parallels Inc and used in their hypervisor solutions like Parallels Desktop for Mac. Newer versions of this format (i.e. 3 and 4) are not supported due to the lack of documentation for this proprietary format. {{Note|There is currently a controversy regarding the support of the version 2 of the format. While the official VirtualBox manual [https://www.virtualbox.org/manual/ch05.html#vdidetails only reports the second version of the HDD file format as supported], Wikipedia's contributors are [[Wikipedia:Comparison of platform virtual machines#Image type compatibility|reporting the first version may work too]]. Help is welcome if you can perform some tests with the first version of the HDD format.}}<br />
<br />
* '''QED''': The QEMU Enhanced Disk format is an old file format for QEMU, another free and open source hypervisor. This format was designed from 2010 in a way to provide a superior alternative to QCOW2 and others. This format features a fully asynchronous I/O path, strong data integrity, backing files, and sparse files. QED format is supported only for compatibility with virtual machines created with old versions of QEMU.<br />
<br />
* '''QCOW''': The QEMU Copy On Write format is the current format for QEMU. The QCOW format does support zlib-based transparent compression and encryption (the latter is flawed and is not recommended). QCOW is available in two versions: QCOW and QCOW2. QCOW2 tends to supersede the first one. QCOW is [https://www.virtualbox.org/manual/ch15.html#idp63002176 currently fully supported by VirtualBox]. QCOW2 comes in two revisions: QCOW2 0.10 and QCOW2 1.1 (which is the default when you create a virtual disk with QEMU). VirtualBox does not support QCOW2.<br />
<br />
* '''OVF''': The Open Virtualization Format is an open format which has been designed for interoperability and distributions of virtual machines between different hypervisors. VirtualBox supports all revisions of this format via the [https://www.virtualbox.org/manual/ch08.html#idp55423424 VBoxManage import/export feature] but with [https://www.virtualbox.org/manual/ch14.html#KnownProblems known limitations].<br />
<br />
* '''RAW''': This is the mode when the virtual disk is exposed directly to the disk without being contained in a specific file format container. VirtualBox supports this feature in several ways: converting RAW disk [https://www.virtualbox.org/manual/ch08.html#idp59139136 to a specific format], or by [https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi cloning a disk to RAW], or by using directly a VMDK file [https://www.virtualbox.org/manual/ch09.html#idp57804112 which points to a physical disk or a simple file].<br />
<br />
=== Disk image format conversion ===<br />
<br />
[https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi VBoxManage clonehd] can be used to convert between VDI, VMDK, VHD and RAW.<br />
<br />
$ VBoxManage clonehd ''inputfile'' ''outputfile'' --format ''outputformat''<br />
<br />
For example to convert VDI to VMDK:<br />
<br />
$ VBoxManage clonehd ''source.vdi'' ''destination.vmdk'' --format VMDK<br />
<br />
==== QCOW ====<br />
<br />
VirtualBox does not support [[QEMU]]'s QCOW2 disk image format. To use a QCOW2 disk image with VirtualBox you therefore need to convert it, which you can do with {{Pkg|qemu}}'s {{ic|qemu-img}} command. {{ic|qemu-img}} can convert QCOW to / from VDI, VMDK, VHDX, RAW and various other formats (which you can see by running {{ic|qemu-img --help}}).<br />
<br />
$ qemu-img convert -O ''output_fmt'' ''inputfile'' ''outputfile''<br />
<br />
For example to convert QCOW2 to VDI:<br />
<br />
$ qemu-img convert -O vdi ''source.qcow2'' ''destination.vdi''<br />
<br />
{{Tip|The {{ic|-p}} parameter is used to get the progression of the conversion task.}}<br />
<br />
There are two revisions of QCOW2: 0.10 and 1.1. You can specify the revision to use with {{ic|1=-o compat=''revision''}}.<br />
<br />
=== Mount virtual disks ===<br />
<br />
==== VDI ====<br />
<br />
Mounting VDI images only works with fixed size images (a.k.a. static images); dynamic (dynamically size allocating) images are not easily mountable.<br />
<br />
The offset of the partition (within the VDI) is needed, then add the value of {{ic|offData}} to {{ic|32256}} (e.g. 69632 + 32256 = 101888):<br />
<br />
$ VBoxManage internalcommands dumphdinfo <storage.vdi> | grep "offData"<br />
<br />
The can now be mounted with:<br />
<br />
# mount -t ext4 -o rw,noatime,noexec,loop,offset=101888 <storage.vdi> /mntpoint/<br />
<br />
You can also use [https://github.com/pld-linux/VirtualBox/blob/master/mount.vdi mount.vdi] script that, which you can use as (install script itself to {{ic|/usr/bin/}}):<br />
<br />
# mount -t vdi -o fstype=ext4,rw,noatime,noexec ''vdi_file_location'' ''/mnt/''<br />
<br />
Alternately you can use {{Pkg|qemu}}'s kernel module that can do this [http://bethesignal.org/blog/2011/01/05/how-to-mount-virtualbox-vdi-image/ attrib]:<br />
<br />
# modprobe nbd max_part=16<br />
# qemu-nbd -c /dev/nbd0 <storage.vdi><br />
# mount /dev/nbd0p1 /mnt/dir/<br />
# # to unmount:<br />
# umount /mnt/dir/<br />
# qemu-nbd -d /dev/nbd0<br />
<br />
If the partition nodes are not propagated try using {{ic|partprobe /dev/nbd0}}; otherwise, a VDI partition can be mapped directly to a node by: {{ic|qemu-nbd -P 1 -c /dev/nbd0 <storage.vdi>}}.<br />
<br />
=== Compact virtual disks ===<br />
<br />
Compacting virtual disks only works with ''.vdi'' files and basically consists of the following steps.<br />
<br />
Boot your virtual machine and remove all bloat manually or by using cleaning tools like {{Pkg|bleachbit}} which is [http://bleachbit.sourceforge.net/download/windows available for Windows systems too].<br />
<br />
Wiping free space with zeroes can be achieved with several tools:<br />
* If you were previously using Bleachbit, check the checkbox ''System > Free disk space'' in the GUI, or use {{ic|bleachbit -c system.free_disk_space}} in CLI;<br />
* On UNIX-based systems, by using {{ic|dd}} or preferably {{Pkg|dcfldd}} (see [http://superuser.com/a/355322 here] to learn the differences):<br />
:{{bc|1=# dcfldd if=/dev/zero of=''/fillfile'' bs=4M}}<br />
:When {{ic|fillfile}} reaches the limit of the partition, you will get a message like {{ic|1280 blocks (5120Mb) written.dcfldd:: No space left on device}}. This means that all of the user-space and non-reserved blocks of the partition will be filled with zeros. Using this command as root is important to make sure all free blocks have been overwritten. Indeed, by default, when using partitions with ext filesystem, a specified percentage of filesystem blocks is reserved for the super-user (see the {{ic|-m}} argument in the {{ic|mkfs.ext4}} man pages or use {{ic|tune2fs -l}} to see how much space is reserved for root applications).<br />
:When the aforementioned process has completed, you can remove the file {{ic|''fillfile''}} you created.<br />
<br />
* On Windows, there are two tools available:<br />
:*{{ic|sdelete}} from the [http://technet.microsoft.com/en-us/sysinternals/bb842062.aspx Sysinternals Suite], type {{ic|sdelete -s -z ''c:''}}, where you need to reexecute the command for each drive you have in your virtual machine;<br />
:* or, if you love scripts, there is a [http://blog.whatsupduck.net/2012/03/powershell-alternative-to-sdelete.html PowerShell solution], but which still needs to be repeated for all drives.<br />
::{{bc|PS> ./Write-ZeroesToFreeSpace.ps1 -Root ''c:\'' -PercentFree 0}}<br />
::{{Note|This script must be run in a PowerShell environment with administrator privileges. By default, scripts cannot be run, ensure the execution policy is at least on {{ic|RemoteSigned}} and not on {{ic|Restricted}}. This can be checked with {{ic|Get-ExecutionPolicy}} and the required policy can be set with {{ic|Set-ExecutionPolicy RemoteSigned}}.}}<br />
<br />
Once the free disk space have been wiped, shut down your virtual machine.<br />
<br />
The next time you boot your virtual machine, it is recommended to do a filesystem check.<br />
* On UNIX-based systems, you can use {{ic|fsck}} manually;<br />
:* On GNU/Linux systems, and thus on Arch Linux, you can force a disk check at boot [[Fsck#Forcing the check|thanks to a kernel boot parameter]];<br />
* On Windows systems, you can use:<br />
:* either {{ic|chkdsk ''c:'' /F}} where {{ic|''c:''}} needs to be replaced by each disk you need to scan and fix errors;<br />
:* or {{ic|FsckDskAll}} [http://therightstuff.de/2009/02/14/ChkDskAll-ChkDsk-For-All-Drives.aspx from here] which is basically the same software as {{ic|chkdsk}}, but without the need to repeat the command for all drives;<br />
<br />
Now, remove the zeros from the ''.vdi'' file with [https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvdi VBoxManage modifyhd]:<br />
$ VBoxManage modifyhd ''your_disk.vdi'' --compact<br />
<br />
{{Note|If your virtual machine has snapshots, you need to apply the above command on each {{ic|.vdi}} files you have.}}<br />
<br />
=== Increase virtual disks ===<br />
<br />
==== General procedure ====<br />
<br />
If you are running out of space due to the small hard drive size you selected when you created your virtual machine, the solution adviced by the VirtualBox manual is to use [https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvdi VBoxManage modifyhd]. However this command only works for VDI and VHD disks and only for the dynamically allocated variants. If you want to resize a fixed size virtual disk disk too, read on this trick which works either for a Windows or UNIX-like virtual machine.<br />
<br />
First, create a new virtual disk next to the one you want to increase:<br />
<br />
$ VBoxManage createhd -filename ''new.vdi'' --size ''10000''<br />
<br />
where size is in MiB, in this example 10000MiB ~= 10GiB, and ''new.vdi'' is name of new hard drive to be created.<br />
<br />
{{Note|By default, this command uses the ''Standard'' (corresponding to dynamic allocated) file format variant and thus will not use the same file format variant as your source virtual disk. If your ''old.vdi'' has a fixed size and you want to keep this variant, add the parameter {{ic|--variant Fixed}}.}}<br />
<br />
Next, the old virtual disk needs to be cloned to the new one which this may take some time:<br />
<br />
$ VBoxManage clonehd ''old.vdi'' ''new.vdi'' --existing<br />
<br />
Detach the old hard drive and attach new one, replace all mandatory italic arguments by your own:<br />
<br />
$ VBoxManage storageattach ''VM_name'' --storagectl ''SATA'' --port ''0'' --medium none<br />
$ VBoxManage storageattach ''VM_name'' --storagectl ''SATA'' --port ''0'' --medium ''new.vdi'' --type hdd<br />
<br />
To get the storage controller name and the port number, you can use the command {{ic|VBoxManage showvminfo ''VM_name''}}. Among the output you will get such a result (what you are looking for is in italic):<br />
<br />
{{bc|<br />
[...]<br />
Storage Controller Name (0): IDE<br />
Storage Controller Type (0): PIIX4<br />
Storage Controller Instance Number (0): 0<br />
Storage Controller Max Port Count (0): 2<br />
Storage Controller Port Count (0): 2<br />
Storage Controller Bootable (0): on<br />
Storage Controller Name (1): SATA<br />
Storage Controller Type (1): IntelAhci<br />
Storage Controller Instance Number (1): 0<br />
Storage Controller Max Port Count (1): 30<br />
Storage Controller Port Count (1): 1<br />
Storage Controller Bootable (1): on<br />
IDE (1, 0): Empty<br />
''SATA'' (''0'', 0): /home/wget/IT/Virtual_machines/GNU_Linux_distributions/ArchLinux_x64_EFI/Snapshots/{6bb17af7-e8a2-4bbf-baac-fbba05ebd704}.vdi (UUID: 6bb17af7-e8a2-4bbf-baac-fbba05ebd704)<br />
[...]<br />
}}<br />
<br />
Download [http://gparted.org/download.php GParted live image] and mount it as a virtual CD/DVD disk file, boot your virtual machine, increase/move your partitions, umount GParted live and reboot.<br />
<br />
{{Note|On GPT disks, increasing the size of the disk will result in the backup GPT header not being at the end of the device. GParted will ask to fix this, click on ''Fix'' both times. On MBR disks, you do not have such a problem as this partition table as no trailer at the end of the disk.}}<br />
<br />
Finally, unregister the virtual disk from VirtualBox and remove the file:<br />
<br />
$ VBoxManage closemedium disk ''old.vdi''<br />
$ rm ''old.vdi''<br />
<br />
==== Increasing the size of VDI disks ====<br />
<br />
If your disk is a VDI one, run:<br />
<br />
$ VBoxManage modifyhd ''your_virtual_disk.vdi'' --resize ''the_new_size''<br />
<br />
Then jump back to the Gparted step, to increase the size of the partition on the virtual disk.<br />
<br />
=== Replace a virtual disk manually from the .vbox file ===<br />
<br />
If you think that editing a simple ''XML'' file is more convenient than playing with the GUI or with {{ic|VBoxManage}} and you want to replace (or add) a virtual disk to your virtual machine, in the ''.vbox'' configuration file corresponding to your virtual machine, simply replace the GUID, the file location and the format to your needs:<br />
<br />
{{hc|ArchLinux_vm.vbox|2=<br />
<HardDisk uuid="''{670157e5-8bd4-4f7b-8b96-9ee412a712b5}''" location="''ArchLinux_vm.vdi''" format="''VDI''" type="Normal"/><br />
}}<br />
<br />
then in the {{ic|<AttachedDevice>}} sub-tag of {{ic|<StorageController>}}, replace the GUID by the new one.<br />
<br />
{{hc|ArchLinux_vm.vbox|2=<br />
<AttachedDevice type="HardDisk" port="0" device="0"><br />
<Image uuid="''{670157e5-8bd4-4f7b-8b96-9ee412a712b5}''"/><br />
</AttachedDevice><br />
}}<br />
<br />
{{Note|If you do not know the GUID of the drive you want to add, you can use the {{ic|VBoxManage showhdinfo ''file''}}. If you previously used {{ic|VBoxManage clonehd}} to copy/convert your virtual disk, this command should have outputted the GUID just after the copy/conversion completed. Using a random GUID does not work, as each [http://www.virtualbox.org/manual/ch05.html#cloningvdis UUID is stored inside each disk image].}}<br />
<br />
==== Transfer between Linux host and other OS ====<br />
<br />
The information about path to harddisks and the snapshots is stored between {{ic|<HardDisks> .... </HardDisks>}} tags in the file with the ''.vbox'' extension. You can edit them manually or use this script where you will need change only the path or use defaults, assumed that ''.vbox'' is in the same directory with a virtual harddisk and the snapshots folder. It will print out new configuration to stdout.<br />
<br />
{{bc|1=<br />
#!/bin/bash<br />
NewPath="${PWD}/"<br />
Snapshots="Snapshots/"<br />
Filename="$1"<br />
<br />
awk -v SetPath="$NewPath" -v SnapPath="$Snapshots" '{if(index($0,"<HardDisk uuid=") != 0){A=$3;split(A,B,"=");<br />
L=B[2];<br />
gsub(/\"/,"",L);<br />
sub(/^.*\//,"",L);<br />
sub(/^.*\\/,"",L);<br />
if(index($3,"{") != 0){SnapS=SnapPath}else{SnapS=""};<br />
print $1" "$2" location="\"SetPath SnapS L"\" "$4" "$5}<br />
else print $0}' "$Filename"<br />
}}<br />
<br />
{{Note|<br />
* If you will prepare virtual machine for use in Windows host then in the path name end you should use backslash \ instead of / .<br />
* The script detects snapshots by looking for {{ic|{}} in the file name.<br />
* To make it run on a new host you will need to add it first to the register by clicking on '''Machine -> Add...''' or use hotkeys Ctrl+A and then browse to ''.vbox'' file that contains configuration or use command line {{ic|VBoxManage registervm ''filename''.vbox}}<br />
}}<br />
<br />
=== Clone a virtual disk and assigning a new UUID to it ===<br />
<br />
UUIDs are widely used by VirtualBox. Each virtual machines and each virtual disk of a virtual machine must have a different UUID. When you launch a virtual machine in VirtualBox, VirtualBox will keep track of all UUIDs of your virtual machine instance. See the [http://www.virtualbox.org/manual/ch08.html#vboxmanage-list VBoxManage list] to list the items registered with VirtualBox.<br />
<br />
If you cloned a virtual disk manually by copying the virtual disk file, you will need to assign a new UUID to the cloned virtual drive if you want to use the disk in the same virtual machine or even in another (if that one has already been opened, and thus registered, with VirtualBox).<br />
<br />
You can use this command to assign a new UUID to a virtual disk: <br />
$ VBoxManage internalcommands sethduuid ''/path/to/disk.vdi''<br />
<br />
{{Tip|To avoid copying the virtual disk and assigning a new UUID to your file manually you can use [http://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi VBoxManage clonehd].}}<br />
<br />
{{Note|The commands above support all [[#Formats supported by VirtualBox|virtual disk formats supported by VirtualBox]].}}<br />
<br />
== Tips and tricks ==<br />
<br />
For advanced configuration, see [[VirtualBox/Tips and tricks]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Keyboard and mouse are locked into virtual machine ===<br />
<br />
This means your virtual machine has captured the input of your keyboard and your mouse. Simply press the right {{ic|Ctrl}} key and your input should control your host again.<br />
<br />
To control transparently your virtual machine with your mouse going back and forth your host, without having to press any key, and thus have a seamless integration, install the guest additions inside the guest. Read from the [[#Install the Guest Additions]] step if you guest is Arch Linux, otherwise read the official VirtualBox help.<br />
<br />
=== No 64-bit OS client options ===<br />
<br />
When launching a VM client, and no 64-bit options are available, make sure your CPU virtualization capabilities (usually named {{ic|VT-x}}) are enabled in the BIOS.<br />
<br />
If you are using a Windows host, you may need to disable Hyper-V, as it prevents VirtualBox from using VT-x. [https://www.virtualbox.org/ticket/12350]<br />
<br />
=== VirtualBox GUI does not match host GTK theme ===<br />
<br />
See [[Uniform look for Qt and GTK applications]] for information about theming Qt-based applications like VirtualBox.<br />
<br />
=== Cannot send Ctrl+Alt+Fn to guest ===<br />
<br />
Your guest operating system is a GNU/Linux distribution and you want to open a new TTY shell by hitting {{ic|Ctrl+Alt+F2}} or exit your current X session with {{ic|Ctrl+Alt+Backspace}}. If you type these keyboard shortcuts without any adaptation, the guest will not receive any input and the host (if it is a GNU/Linux distribution too) will intercept these shortcut keys. To send {{ic|Ctrl+Alt+F2}} to the guest for example, simply hit your ''Host Key'' (usually the right {{ic|Ctrl}} key) and press {{ic|F2}} simultaneously.<br />
<br />
=== USB subsystem not working ===<br />
<br />
Your user must be in the {{ic|vboxusers}} group and you need to install the [[#Extension pack|extension pack]] if you want USB 2 support. Then you will be able to enable USB 2 in the VM settings and add one or several filters for the devices you want to access from the guest OS.<br />
<br />
If {{ic|VBoxManage list usbhost}} does not show any USB devices even if run as root, make sure that there is no old udev rules (from VirtualBox 4.x) in {{ic|/etc/udev/rules.d/}}. VirtualBox 5.0 installs udev rules to {{ic|/usr/lib/udev/rules.d/}}. You can use command like {{ic|pacman -Qo /usr/lib/udev/rules.d/60-vboxdrv.rules}} to determine if the udev rule file is outdated.<br />
<br />
Sometimes, on old Linux hosts, the USB subsystem is not auto-detected resulting in an error {{ic|Could not load the Host USB Proxy service: VERR_NOT_FOUND}} or in a not visible USB drive on the host, [https://bbs.archlinux.org/viewtopic.php?id=121377 even when the user is in the '''vboxusers''' group]. This problem is due to the fact that VirtualBox switched from ''usbfs'' to ''sysfs'' in version 3.0.8. If the host does not understand this change, you can revert to the old behaviour by defining the following environment variable in any file that is sourced by your shell (e.g. your {{ic|~/.bashrc}} if you are using ''bash''):<br />
<br />
{{hc|~/.bashrc|2=<br />
VBOX_USB=usbfs<br />
}}<br />
<br />
Then make sure, the environment has been made aware of this change (reconnect, source the file manually, launch a new shell instance or reboot).<br />
<br />
Also make sure that your user is a member of the {{ic|storage}} group.<br />
<br />
=== USB modem not working on host ===<br />
<br />
If you have a USB modem which is being used by the guest OS, killing the guest OS can cause the modem to become unusable by the host system. Killing and restarting {{ic|VBoxSVC}} should fix this problem.<br />
<br />
=== Access serial port from guest ===<br />
<br />
Check you permission for the serial port:<br />
{{hc|$ ls -l /dev/ttyS*|<br />
crw-rw---- 1 root uucp 4, 64 Feb 3 09:12 /dev/ttyS0<br />
crw-rw---- 1 root uucp 4, 65 Feb 3 09:12 /dev/ttyS1<br />
crw-rw---- 1 root uucp 4, 66 Feb 3 09:12 /dev/ttyS2<br />
crw-rw---- 1 root uucp 4, 67 Feb 3 09:12 /dev/ttyS3<br />
}}<br />
<br />
Add your user to the {{ic|uucp}} [[user group]].<br />
<br />
=== Guest freezes after starting Xorg ===<br />
<br />
Faulty or missing drivers may cause the guest to freeze after starting Xorg, see for example [https://bbs.archlinux.org/viewtopic.php?pid=1167838] and [https://bbs.archlinux.org/viewtopic.php?id=156079]. Try disabling 3D acceleration in ''Settings > Display'', and check if all [[Xorg]] drivers are installed.<br />
<br />
=== Fullscreen mode shows blank screen ===<br />
<br />
On some window managers ([[i3]], [[awesome]]), VirtualBox has issues with fullscreen mode properly due to the overlay bar. To work around this issue, disable "Show in Full-screen/Seamless" option in "Guest Settings > User Interface > Mini ToolBar". See the [https://www.virtualbox.org/ticket/14323 upstream bug report] for more information.<br />
<br />
=== Host freezes on virtual machine start ===<br />
<br />
{{Expansion|Needs a link to a bug report.}}<br />
<br />
Possible causes/solutions:<br />
<br />
* SMAP<br />
This is a known incompatiblity with SMAP enabled kernels affecting (mostly) Intel Broadwell chipsets. A solution to this problem is disabling SMAP support in your kernel by appending the {{ic|nosmap}} option to your [[kernel parameters]].<br />
* Hardware Virtualisation<br />
Disabling hardware virtualisation (VT-x/AMD-V) may solve the problem.<br />
* Various Kernel bugs<br />
** Fuse mounted partitions (like ntfs) [https://bbs.archlinux.org/viewtopic.php?id=185841], [https://bugzilla.kernel.org/show_bug.cgi?id=82951#c12]<br />
<br />
Generally, such issues are observed after upgrading VirtualBox or linux kernel. Downgrading them to the previous versions of theirs might solve the problem.<br />
<br />
=== Linux guests have slow/distorted audio ===<br />
<br />
The AC97 audio driver within the Linux kernel occasionally guesses the wrong clock settings when running inside Virtual Box, leading to audio that is either too slow or too fast. To fix this, create a file in {{ic|/etc/modprobe.d/}} with the following line:<br />
<br />
options snd-intel8x0 ac97_clock=48000<br />
<br />
=== Analog microphone not working ===<br />
<br />
If the audio input from an analog microphone is working correctly on the host, but no sound seems to get through to the guest, despite the microphone device apparently being detected normally, installing a [[Sound system#Sound servers|sound server]] such as [[PulseAudio]] on the host might fix the problem.<br />
<br />
If after installing [[PulseAudio]] the microphone still refuses to work, setting ''Host Audio Driver'' (under ''VirtualBox > Machine > Settings > Audio'') to ''ALSA Audio Driver'' might help.<br />
<br />
=== Microphone not working after upgrade ===<br />
<br />
There have been issues reported around sound input in 5.1.x versions. [https://forums.virtualbox.org/viewtopic.php?f=7&t=78797]<br />
<br />
[[Downgrading]] may solve the problem. You can use {{aur|virtualbox-bin-5.0}} to ease downgrading.<br />
<br />
=== Problems with images converted to ISO ===<br />
<br />
Some image formats cannot be reliably converted to ISO. For instance, {{Pkg|ccd2iso}} ignores .ccd and .sub files, which can result in disk images with broken files. <br />
<br />
In this case, you will either have to use [[CDemu]] for Linux inside VirtualBox or any other utility used to mount disk images.<br />
<br />
=== Failed to create the host-only network interface ===<br />
<br />
Make sure all required kernel modules are loaded. See [[#Load the VirtualBox kernel modules]].<br />
<br />
If all required kernel modules are loaded and you are still unable to create the host-only adapter, navigate to ''File > Host Network Manager'' and click the ''Create'' button to add the network interface.<br />
<br />
=== Failed to insert module ===<br />
<br />
When you get the following error when trying to load modules:<br />
<br />
Failed to insert 'vboxdrv': Required key not available<br />
<br />
[[#Sign modules|Sign]] your modules or disable {{ic|CONFIG_MODULE_SIG_FORCE}} in your kernel config.<br />
<br />
=== VBOX_E_INVALID_OBJECT_STATE (0x80BB0007) ===<br />
<br />
This can occur if a VM is exited ungracefully. Run the following command:<br />
<br />
$ VBoxManage controlvm ''virtual_machine_name'' poweroff<br />
<br />
=== NS_ERROR_FAILURE and missing menu items ===<br />
<br />
This happens sometimes when selecting ''QCOW''/''QCOW2''/''QED'' disk format when creating a new virtual disk.<br />
<br />
If you encounter this message the first time you start the virtual machine:<br />
<br />
{{bc|Failed to open a session for the virtual machine debian.<br />
Could not open the medium '/home/.../VirtualBox VMs/debian/debian.qcow'.<br />
QCow: Reading the L1 table for image '/home/.../VirtualBox VMs/debian/debian.qcow' failed (VERR_EOF).<br />
VD: error VERR_EOF opening image file '/home/.../VirtualBox VMs/debian/debian.qcow' (VERR_EOF).<br />
<br />
Result Code: <br />
NS_ERROR_FAILURE (0x80004005)<br />
Component: <br />
Medium<br />
}}<br />
<br />
Exit VirtualBox, delete all files of the new machine and from virtualbox config file remove the last line in {{ic|MachineRegistry}} menu (or the offending machine you are creating):<br />
<br />
{{hc|~/.config/VirtualBox/VirtualBox.xml|2=<br />
...<br />
<MachineRegistry><br />
<MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/debian/debian.vbox"/><br />
<MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/ubuntu/ubuntu.vbox"/><br />
<strike><MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/lastvmcausingproblems/lastvmcausingproblems.qcow"/></strike><br />
</MachineRegistry><br />
...<br />
}}<br />
<br />
=== Arch: pacstrap script fails ===<br />
<br />
If you used ''pacstrap'' in the [[#Installation steps for Arch Linux guests]] to also [[#Install the Guest Additions]] '''before''' performing a first boot into the new guest, you will need to {{ic|umount -l /mnt/dev}} as root before using ''pacstrap'' again; a failure to do this will render it unusable.<br />
<br />
=== OpenBSD unusable when virtualisation instructions unavailable ===<br />
<br />
While OpenBSD is reported to work fine on other hypervisors without virtualisation instructions (VT-x AMD-V) enabled, an OpenBSD virtual machine running on VirtualBox without these instructions will be unusable, manifesting with a bunch of segmentation faults. Starting VirtualBox with the ''-norawr0'' argument [https://www.virtualbox.org/ticket/3947 may solve the problem]. You can do it like this:<br />
$ VBoxSDL -norawr0 -vm ''name_of_OpenBSD_VM''<br />
<br />
=== Windows host: VERR_ACCESS_DENIED ===<br />
<br />
To access the raw VMDK image on a Windows host, run the VirtualBox GUI as administrator.<br />
<br />
=== Windows: "The specified path does not exist. Check the path and then try again." ===<br />
<br />
This error message may appear when running an {{ic|.exe}} file which requires administrator privileges from a shared folder in windows guests. [https://www.virtualbox.org/ticket/5732#comment:39]<br />
<br />
As a workaround, copy the file to the virtual drive or use [[w:Uniform Naming Convention|UNC paths]] ({{ic|\\vboxsvr}}). See [https://support.microsoft.com/de-de/help/2019185/copying-files-from-a-mapped-drive-to-a-local-directory-fails-with-erro] for more information.<br />
<br />
=== Windows 8.x error code 0x000000C4===<br />
<br />
If you get this error code while booting, even if you choose OS Type Win 8, try to enable the {{ic|CMPXCHG16B}} CPU instruction:<br />
<br />
$ vboxmanage setextradata ''virtual_machine_name'' VBoxInternal/CPUM/CMPXCHG16B 1<br />
<br />
=== Windows 8, 8.1 or 10 fails to install, boot or has error "ERR_DISK_FULL" ===<br />
<br />
Update the VM's settings by going to ''Settings > Storage > Controller:SATA'' and check "Use Host I/O Cache".<br />
<br />
=== WinXP: Bit-depth cannot be greater than 16 ===<br />
<br />
If you are running at 16-bit color depth, then the icons may appear fuzzy/choppy. However, upon attempting to change the color depth to a higher level, the system may restrict you to a lower resolution or simply not enable you to change the depth at all. To fix this, run {{ic|regedit}} in Windows and add the following key to the Windows XP VM's registry:<br />
<br />
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services]<br />
"ColorDepth"=dword:00000004<br />
<br />
Then update the color depth in the "desktop properties" window. If nothing happens, force the screen to redraw through some method (i.e. {{ic|Host+f}} to redraw/enter full screen).<br />
<br />
=== Windows: Screen flicker if 3D acceleration enabled ===<br />
<br />
VirtualBox > 4.3.14 has a regression in which Windows guests with 3D acceleration flicker. Since r120678 a patch has been implemented to recognize an [[environment variable]] setting, launch VirtualBox like this:<br />
<br />
$ CR_RENDER_FORCE_PRESENT_MAIN_THREAD=0 VirtualBox<br />
<br />
Make sure no VirtualBox services are still running. See [https://www.virtualbox.org/ticket/13653 VirtualBox bug 13653].<br />
<br />
=== No hardware 3D acceleration in Arch Linux guest ===<br />
<br />
{{Pkg|virtualbox-guest-utils}} package as of version 5.2.16-2 does not contain the file {{ic|VBoxEGL.so}}. This causes the Arch Linux guest does not have proper 3D acceleration. See {{Bug|49752}}.<br />
<br />
To deal with this problem, apply the patch set at {{Bug|49752#comment152254}}. Some fix to the patch set is required to make it work for version 5.2.16-2.<br />
<br />
=== Black screen for guest in EFI mode ===<br />
<br />
When the guest is using UEFI in Virtualbox by following [[#Installation in EFI mode]], you will get a black screen during boot and after if the VM's Graphics Controller is set to VBoxSVGA.<br />
<br />
This is because you are experiencing {{Bug|61184}}.<br />
<br />
The workaround is to use VMSVGA (the default) or VBoxVGA as the graphics controller. Go to VM ''Settings > Display''' and change the ''Graphics Controller'' to either ''VMSVGA'' or ''VBoxVGA''.<br />
<br />
== Known issues ==<br />
<br />
=== Automounting does not work ===<br />
<br />
Automounting does not work with the packaged guest additions {{Pkg|virtualbox-guest-utils}} and {{Pkg|virtualbox-guest-utils-nox}} starting with version 6.0.0-1. See {{Bug|61307}}.<br />
<br />
== See also ==<br />
<br />
* [https://www.virtualbox.org/manual/UserManual.html VirtualBox User Manual]<br />
* [[Wikipedia:VirtualBox]]</div>Pgoetz