https://wiki.archlinux.org/api.php?action=feedcontributions&user=Rozha&feedformat=atomArchWiki - User contributions [en]2024-03-29T05:45:59ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Btrfs&diff=684986Btrfs2021-07-03T05:26:47Z<p>Rozha: /* Multi-device file system */ Fix RAID1 mkfs example</p>
<hr />
<div>[[Category:File systems]]<br />
[[de:Arch auf BtrFS]]<br />
[[es:Btrfs]]<br />
[[fr:Btrfs]]<br />
[[it:Btrfs]]<br />
[[ja:Btrfs]]<br />
[[pt:Btrfs]]<br />
[[zh-hans:Btrfs]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|Snapper}}<br />
{{Related|dm-crypt/Encrypting an entire system#Btrfs subvolumes with swap}}<br />
{{Related articles end}}<br />
<br />
From [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs Wiki]:<br />
<br />
:Btrfs is a modern copy on write (CoW) filesystem for Linux aimed at implementing advanced features while also focusing on fault tolerance, repair and easy administration. Jointly developed at multiple companies, Btrfs is licensed under the GPL and open for contribution from anyone.<br />
<br />
{{Warning|Btrfs has some features that are unstable. See the Btrfs Wiki's [https://btrfs.wiki.kernel.org/index.php/Status Status], [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_Btrfs_stable.3F Is Btrfs stable?] and [https://btrfs.wiki.kernel.org/index.php/Getting_started Getting started] for more detailed information. See the [[#Known issues]] section.}}<br />
<br />
== Preparation ==<br />
<br />
For user space utilities [[install]] the {{Pkg|btrfs-progs}} package, which is required for basic operations.<br />
<br />
If you need to boot from a Btrfs file system (i.e., your kernel and initramfs reside on a Btrfs partition), check if your [[boot loader]] supports Btrfs.<br />
<br />
== File system creation ==<br />
<br />
The following shows how to create a new Btrfs [[file system]]. To convert an ext3/4 partition to Btrfs, see [[#Ext3/4 to Btrfs conversion]]. To use a partitionless setup, see [[#Partitionless Btrfs disk]].<br />
<br />
See {{man|8|mkfs.btrfs}} for more information.<br />
<br />
=== File system on a single device ===<br />
<br />
To create a Btrfs filesystem on partition {{ic|/dev/''partition''}}:<br />
<br />
# mkfs.btrfs -L ''mylabel'' /dev/''partition''<br />
<br />
The Btrfs default nodesize for metadata is 16KB, while the default sectorsize for data is equal to page size and autodetected. To use a larger nodesize for metadata (must be a multiple of sectorsize, up to 64KB is allowed), specify a value for the {{ic|nodesize}} via the {{ic|-n}} switch as shown in this example using 32KB blocks:<br />
<br />
# mkfs.btrfs -L ''mylabel'' -n 32k /dev/''partition''<br />
<br />
{{Note|According to {{man|8|mkfs.btrfs|OPTIONS}}, "[a] smaller node size increases fragmentation but leads to taller b-trees which in turn leads to lower locking contention. Higher node sizes give better packing and less fragmentation at the cost of more expensive memory operations while updating the metadata blocks".}}<br />
<br />
=== Multi-device file system ===<br />
<br />
{{Warning|The RAID 5 and RAID 6 modes of Btrfs are fatally flawed, and should not be used for "anything but testing with throw-away data." [https://lore.kernel.org/linux-btrfs/20200627032414.GX10769@hungrycats.org/ List of known problems and partial workarounds.] See [https://btrfs.wiki.kernel.org/index.php/RAID56 the Btrfs page on RAID5 and RAID6] for status updates (seems to not be updated).}}<br />
<br />
Multiple devices can be used to create a RAID. Supported RAID levels include RAID 0, RAID 1, RAID 10, RAID 5 and RAID 6. Starting from kernel 5.5 RAID1c3 and RAID1c4 for 3- and 4- copies of RAID 1 level. The RAID levels can be configured separately for data and metadata using the {{ic|-d}} and {{ic|-m}} options respectively. By default the data has one copy ({{ic|single}}) and the metadata is mirrored ({{ic|raid1}}). This is similar to <br />
creating a [[W:JBOD|JBOD configuration]], where disks are seen as one filesystem, but files are not duplicated. See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Using Btrfs with Multiple Devices] for more information about how to create a Btrfs RAID volume.<br />
<br />
# mkfs.btrfs -d raid1 -m raid1 /dev/''part1'' /dev/''part2'' ...<br />
<br />
You must include either the {{ic|udev}} hook or the {{ic|btrfs}} hook in {{ic|/etc/mkinitcpio.conf}} in order to use multiple Btrfs devices in a pool. See the [[Mkinitcpio#Common hooks]] article for more information.<br />
<br />
{{Note|<br />
* It is possible to add devices to a multiple-device filesystem later on. See the [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Btrfs wiki article] for more information.<br />
* Devices can be of different sizes. However, if one drive in a RAID configuration is bigger than the others, this extra space will not be used. <br />
* Some [[boot loader]]s such as [[Syslinux]] do not support multi-device file systems.<br />
* Btrfs does not automatically read from the fastest device, so mixing different kinds of disks results in inconsistent performance. See [https://stackoverflow.com/a/55408367 this Stack Overflow answer] for details.<br />
}}<br />
<br />
See [[#RAID]] for advice on maintenance specific to multi-device Btrfs file systems.<br />
<br />
== Configuring the file system ==<br />
<br />
=== Copy-on-Write (CoW) ===<br />
<br />
By default, Btrfs uses [[Wikipedia:copy-on-write|copy-on-write]] for all files all the time. See the [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Copy_on_Write_.28CoW.29 Btrfs Sysadmin Guide section] for implementation details, as well as advantages and disadvantages.<br />
<br />
==== Disabling CoW ====<br />
<br />
To disable copy-on-write for newly created files in a mounted subvolume, use the {{ic|nodatacow}} mount option. This will only affect newly created files. Copy-on-write will still happen for existing files. The {{ic|nodatacow}} option also disables compression. See {{man|5|btrfs}} for details.<br />
<br />
{{Note|From {{man|5|btrfs|MOUNT OPTIONS}}: "within a single file system, it is not possible to mount some subvolumes with {{ic|nodatacow}} and others with {{ic|datacow}}. The mount option of the first mounted subvolume applies to any other subvolumes."}}<br />
<br />
To disable copy-on-write for single files/directories do:<br />
<br />
$ chattr +C ''/dir/file''<br />
<br />
This will disable copy-on-write for those operation in which there is only one reference to the file. If there is more than one reference (e.g. through {{ic|1=cp --reflink=always}} or because of a filesystem snapshot), copy-on-write still occurs.<br />
<br />
{{Note|From chattr man page: "For btrfs, the 'C' flag should be set on new or empty files. If it is set on a file which already has data blocks, it is undefined when the blocks assigned to the file will be fully stable. If the 'C' flag is set on a directory, it will have no effect on the directory, but new files created in that directory will have the No_COW attribute."}}<br />
<br />
{{Tip|In accordance with the note above, you can use the following trick to disable copy-on-write on existing files in a directory:<br />
<br />
$ mv ''/path/to/dir'' ''/path/to/dir''_old<br />
$ mkdir ''/path/to/dir''<br />
$ chattr +C ''/path/to/dir''<br />
$ cp -a ''/path/to/dir''_old/* ''/path/to/dir''<br />
$ rm -rf ''/path/to/dir''_old<br />
<br />
Make sure that the data are not used during this process. Also note that {{ic|mv}} or {{ic|cp --reflink}} as described below will not work.<br />
}}<br />
<br />
==== Creating lightweight copies ====<br />
<br />
By default, when copying files on a Btrfs filesystem with {{ic|cp}}, actual copies are created. To create a lightweight copy referencing to the original data, use the ''reflink'' option:<br />
<br />
$ cp --reflink ''source'' ''dest'' <br />
<br />
See the man page on {{man|1|cp}} for more details on the {{ic|--reflink}} flag.<br />
<br />
=== Compression ===<br />
<br />
Btrfs supports [https://btrfs.wiki.kernel.org/index.php/Compression transparent and automatic compression]. This reduces the size of files as well as significantly increases the lifespan of flash-based media by reducing write amplification. See [[Fedora:Changes/BtrfsByDefault#Compression]], [https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/NTV77NFF6NDZM3QTPUM2TQZ5PCM6GOO2/], and [https://pagure.io/fedora-btrfs/project/issue/36#comment-701551]. It can also [https://www.phoronix.com/scan.php?page=article&item=btrfs_compress_2635&num=1 improve performance], in some cases (e.g. single thread with heavy file I/O), while obviously harming performance in other cases (e.g. multi-threaded and/or CPU intensive tasks with large file I/O). Better performance is generally achieved with the fastest compress algorithms, ''zstd'' and ''lzo'', and some [https://www.phoronix.com/scan.php?page=article&item=btrfs-zstd-compress benchmarks] provide detailed comparisons.<br />
<br />
The {{ic|1=compress=''alg''}} mount option enables automatically considering every file for compression, where {{ic|''alg''}} is either {{ic|zlib}}, {{ic|lzo}}, {{ic|zstd}}, or {{ic|no}} (for no compression). Using this option, btrfs will check if compressing the first portion of the data shrinks it. If it does, the entire write to that file will be compressed. If it does not, none of it is compressed. With this option, if the first portion of the write does not shrink, no compression will be applied to the write even if the rest of the data would shrink tremendously. [https://btrfs.wiki.kernel.org/index.php/Compression#What_happens_to_incompressible_files.3F] This is done to prevent making the disk wait to start writing until all of the data to be written is fully given to btrfs and compressed.<br />
<br />
The {{ic|1=compress-force=''alg''}} mount option can be used instead, which makes btrfs skip checking if compression shrinks the first portion, and enables automatic compression try for every file. In a worst-case scenario, this can cause (slightly) more CPU usage for no purpose. However, empirical testing on multiple mixed-use systems showed a significant improvement of about 10% disk compression from using {{ic|1=compress-force=''zstd''}} over just {{ic|1=compress=''zstd''}}, which also had 10% disk compression.<br />
<br />
Only files created or modified after the mount option is added will be compressed.<br />
<br />
To apply compression to existing files, use the {{ic|btrfs filesystem defragment -c''alg''}} command, where {{ic|''alg''}} is either {{ic|zlib}}, {{ic|lzo}} or {{ic|zstd}}. For example, in order to re-compress the whole file system with {{pkg|zstd}}, run the following command:<br />
<br />
# btrfs filesystem defragment -r -v -czstd /<br />
<br />
To enable compression when installing Arch to an empty Btrfs partition, use the {{ic|compress}} option when [[mounting]] the file system: {{ic|1=mount -o compress=zstd /dev/sd''xY'' /mnt/}}. During configuration, add {{ic|1=compress=zstd}} to the mount options of the root file system in [[fstab]].<br />
<br />
{{Tip|Compression can also be enabled per-file without using the {{ic|compress}} mount option; to do so apply {{ic|chattr +c}} to the file. When applied to directories, it will cause new files to be automatically compressed as they come.}}<br />
<br />
{{Warning|<br />
* Systems using older kernels or {{pkg|btrfs-progs}} without {{ic|zstd}} support may be unable to read or repair your filesystem if you use this option.<br />
* [[GRUB]] introduced ''zstd'' support in 2.04. Make sure you have actually upgraded the bootloader installed in your MBR/ESP since then, by running {{ic|grub-install}} with the appropriate options for your BIOS/UEFI setup, since that is not done automatically. See {{Bug|63235}}.<br />
}}<br />
<br />
==== View compression types and ratios ====<br />
<br />
{{pkg|compsize}} takes a list of files (or an entire btrfs filesystem) and measures compression types used and effective compression ratios. Uncompressed size may not match the number given by other programs such as {{ic|du}}, because every extent is counted once, even if it is reflinked several times, and even if part of it is no longer used anywhere but has not been garbage collected. The {{ic|-x}} option keeps it on a single filesystem, which is useful in situations like {{ic|compsize -x /}} to avoid it from attempting to look in non-btrfs subdirectories and fail the entire run.<br />
<br />
=== Subvolumes ===<br />
<br />
{{Merge|User:I2Oc9/Btrfs_subvolumes|A more straightforward introduction}}<br />
"A btrfs subvolume is not a block device (and cannot be treated as one) instead, a btrfs subvolume can be thought of as a POSIX file namespace. This namespace can be accessed via the top-level subvolume of the filesystem, or it can be mounted in its own right." [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes]<br />
<br />
Each Btrfs file system has a top-level subvolume with ID 5. It can be mounted as {{ic|/}} (by default), or another subvolume can be [[#Mounting subvolumes|mounted]] instead. Subvolumes can be moved around in the filesystem and are rather identified by their id than their path.<br />
<br />
See the following links for more details:<br />
<br />
* [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes Btrfs Wiki SysadminGuide#Subvolumes]<br />
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Basic_Filesystem_Commands Btrfs Wiki Getting started#Basic Filesystem Commands]<br />
* [https://btrfs.wiki.kernel.org/index.php/Trees Btrfs Wiki Trees]<br />
<br />
==== Creating a subvolume ====<br />
<br />
To create a subvolume:<br />
<br />
# btrfs subvolume create ''/path/to/subvolume''<br />
<br />
==== Listing subvolumes ====<br />
<br />
To see a list of current subvolumes and their ids under {{ic|''path''}}:<br />
<br />
# btrfs subvolume list -p ''path''<br />
<br />
==== Deleting a subvolume ====<br />
<br />
To delete a subvolume:<br />
<br />
# btrfs subvolume delete ''/path/to/subvolume''<br />
<br />
Since Linux 4.18, one can also delete a subvolume like a regular directory ({{ic|<nowiki>rm -r</nowiki>}}, {{ic|<nowiki>rmdir</nowiki>}}).<br />
<br />
==== Mounting subvolumes ====<br />
<br />
Subvolumes can be mounted like file system partitions using the {{ic|1=subvol=''/path/to/subvolume''}} or {{ic|1=subvolid=''objectid''}} mount flags. For example, you could have a subvolume named {{ic|subvol_root}} and mount it as {{ic|/}}. One can mimic traditional file system partitions by creating various subvolumes under the top level of the file system and then mounting them at the appropriate mount points. Thus one can easily restore a file system (or part of it) to a previous state using [[#Snapshots]].<br />
<br />
{{Tip|1= Changing subvolume layouts is made simpler by not using the toplevel subvolume (ID=5) as {{ic|/}} (which is done by default). Instead, consider creating a subvolume to house your actual data and mounting it as {{ic|/}}.}}<br />
<br />
{{Note|From {{man|5|btrfs|MOUNT OPTIONS}}: "Most mount options apply to the '''whole filesystem''', and only the options for the first subvolume to be mounted will take effect. This is due to lack of implementation and may change in the future.". See the [https://btrfs.wiki.kernel.org/index.php/FAQ#Can_I_mount_subvolumes_with_different_mount_options.3F Btrfs Wiki FAQ] for which mount options can be used per subvolume.}}<br />
<br />
See [[Snapper#Suggested filesystem layout]], [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Managing_Snapshots Btrfs SysadminGuide#Managing Snapshots], and [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Layout Btrfs SysadminGuide#Layout] for example file system layouts using subvolumes.<br />
<br />
See {{man|5|btrfs}} for a full list of btrfs-specific mount options.<br />
<br />
==== Mounting subvolume as root ====<br />
<br />
To use a subvolume as the root mountpoint specify the subvolume via a [[Kernel parameters#Configuration|kernel parameter]] using {{ic|1=rootflags=subvol=''/path/to/subvolume''}}. Edit the root mountpoint in {{ic|/etc/fstab}} and specify the mount option {{ic|1=subvol=}}. Alternatively the subvolume can be specified with its id, {{ic|1=rootflags=subvolid=''objectid''}} as kernel parameter and {{ic|1=subvolid=''objectid''}} as mount option in {{ic|/etc/fstab}}.<br />
<br />
==== Changing the default sub-volume ====<br />
<br />
The default sub-volume is mounted if no {{ic|1=subvol=}} mount option is provided. To change the default subvolume, do:<br />
<br />
# btrfs subvolume set-default ''subvolume-id'' /<br />
<br />
where ''subvolume-id'' can be found by [[#Listing subvolumes|listing]].<br />
<br />
{{Note|1=After changing the default subvolume on a system with [[GRUB]], you should run {{ic|grub-install}} again to notify the bootloader of the changes. See [https://bbs.archlinux.org/viewtopic.php?pid=1615373 this forum thread].}}<br />
<br />
Changing the default subvolume with {{ic|btrfs subvolume set-default}} will make the top level of the filesystem inaccessible, except by use of the {{ic|1=subvol=/}} or {{ic|1=subvolid=5}} mount options [https://btrfs.wiki.kernel.org/index.php/SysadminGuide].<br />
<br />
=== Quota ===<br />
<br />
{{warning|Qgroup is not stable yet and combining quota with (too many) snapshots of subvolumes can cause performance problems, for example when deleting snapshots. Plus there are several more [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues known issues].}}<br />
<br />
Quota support in Btrfs is implemented at a subvolume level by the use of quota groups or qgroup: Each subvolume is assigned a quota groups in the form of ''0/subvolume_id'' by default. However it is possible to create a quota group using any number if desired.<br />
<br />
To use qgroups you need to enable quota first using<br />
<br />
# btrfs quota enable ''path''<br />
<br />
From this point onwards newly created subvolumes will be controlled by those groups.<br />
In order to retrospectively enable them for already existing subvolumes, enable quota normally, then create a qgroup (quota group) for each of those subvolume using their ''subvolume_id'' and rescan them:<br />
<br />
# btrfs subvolume list ''path'' | cut -d' ' -f2 | xargs -I{} -n1 btrfs qgroup create 0/{} ''path''<br />
# btrfs quota rescan ''path''<br />
<br />
Quota groups in Btrfs form a tree hierarchy, whereby qgroups are attached to subvolumes. The size limits are set per qgroup and apply when any limit is reached in tree that contains a given subvolume.<br />
<br />
Limits on quota groups can be applied either to the total data usage, un-shared data usage, compressed data usage or both. File copy and file deletion may both affect limits since the unshared limit of another qgroup can change if the original volume's files are deleted and only one copy is remaining. For example a fresh snapshot shares almost all the blocks with the original subvolume, new writes to either subvolume will raise towards the exclusive limit, deletions of common data in one volume raises towards the exclusive limit in the other one.<br />
<br />
To apply a limit to a qgroup, use the command {{ic|btrfs qgroup limit}}. Depending on your usage either use a total limit, unshared limit ({{ic|-e}}) or compressed limit ({{ic|-c}}).<br />
To show usage and limits for a given path within a filesystem use<br />
<br />
# btrfs qgroup show -reF ''path''<br />
<br />
=== Commit interval ===<br />
<br />
The resolution at which data are written to the filesystem is dictated by Btrfs itself and by system-wide settings. Btrfs defaults to a 30 seconds checkpoint interval in which new data are committed to the filesystem. This can be changed by appending the {{ic|commit}} mount option in {{ic|/etc/fstab}} for the btrfs partition.<br />
<br />
LABEL=arch64 / btrfs defaults,compress=zstd,commit=120 0 0<br />
<br />
System-wide settings also affect commit intervals. They include the files under {{ic|/proc/sys/vm/*}} and are out-of-scope of this wiki article. The kernel documentation for them resides in {{ic|Documentation/sysctl/vm.txt}}.<br />
<br />
=== SSD TRIM ===<br />
<br />
A Btrfs filesystem is able to free unused blocks from an SSD drive supporting the TRIM command. Starting with kernel version 5.6 there is asynchronous discard support, enabled with mount option {{ic|1=discard=async}}. Freed extents are not discarded immediately, but grouped together and trimmed later by a separate worker thread, improving commit latency.<br />
<br />
More information about enabling and using TRIM can be found in [[Solid State Drives#TRIM]].<br />
<br />
== Usage ==<br />
<br />
=== Swap file ===<br />
<br />
[[Swap file]]s in Btrfs are supported since Linux kernel 5.0.[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ed46ff3d423780fa5173b38a844bf0fdb210a2a7] The proper way to initialize a swap file is to first create a non-compressed, non-snapshotted subvolume to host the file, ''cd'' into its directory, then create a zero length file, set the {{ic|No_COW}} attribute on it with [[chattr]], and make sure compression is disabled:<br />
<br />
# cd ''/path/to/swapfile''<br />
# truncate -s 0 ./swapfile<br />
# chattr +C ./swapfile<br />
# btrfs property set ./swapfile compression none<br />
<br />
Continue with the steps in [[Swap file#Swap file creation]]. Configuring hibernation to a swap file is described in [[Power management/Suspend and hibernate#Hibernation into swap file on Btrfs]].<br />
<br />
{{Note|1=Since Linux kernel 5.0, Btrfs has native swap file support with some limitations:<br />
* The swap file cannot be on a snapshotted subvolume. The proper procedure is to create a new subvolume to place the swap file in.<br />
* It does not support swap files on file systems that span multiple devices. See [https://btrfs.wiki.kernel.org/index.php/FAQ#Does_Btrfs_support_swap_files.3F Btrfs wiki: Does btrfs support swap files?] and [https://bbs.archlinux.org/viewtopic.php?pid=1849371#p1849371 Arch forums discussion].<br />
}}<br />
<br />
=== Displaying used/free space ===<br />
<br />
General linux userspace tools such as {{ic|df}} will inaccurately report free space on a Btrfs partition. It is recommended to use {{ic|btrfs filesystem usage}} to query Btrfs partitions. For example, for a full breakdown of device allocation and usage stats:<br />
<br />
# btrfs filesystem usage /<br />
<br />
{{Note|The {{ic|btrfs filesystem usage}} command does not currently work correctly with {{ic|RAID5/RAID6}} RAID levels.}}<br />
<br />
Alternatively, {{ic|btrfs filesystem df}} allows a quick check on usage of allocated space without the requirement to run as root:<br />
<br />
$ btrfs filesystem df /<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/FAQ#How_much_free_space_do_I_have.3F] for more information.<br />
<br />
=== Defragmentation ===<br />
<br />
Btrfs supports online defragmentation through the mount option {{ic|autodefrag}}, see {{man|5|btrfs|MOUNT OPTIONS}}. To manually defragment your root, use:<br />
<br />
# btrfs filesystem defragment -r /<br />
<br />
Using the above command without the {{ic|-r}} switch will result in only the metadata held by the subvolume containing the directory being defragmented. This allows for single file defragmentation by simply specifying the path.<br />
<br />
Defragmenting a file which has a COW copy (either a snapshot copy or one made with {{ic|cp --reflink}} or bcp) plus using the {{ic|-c}} switch with a compression algorithm may result in two unrelated files effectively increasing the disk usage.<br />
<br />
=== RAID ===<br />
<br />
Btrfs offers native "RAID" for [[#Multi-device file system]]s. Notable features which set btrfs RAID apart from [[mdadm]] are self-healing redundant arrays and online balancing. See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices the Btrfs wiki page] for more information. The Btrfs sysadmin page also [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#RAID_and_data_replication has a section] with some more technical background.<br />
<br />
{{Warning| Parity RAID (RAID 5/6) code has multiple serious data-loss bugs in it. See the Btrfs Wiki's [https://btrfs.wiki.kernel.org/index.php/RAID56 RAID5/6 page] and a bug report on [https://www.mail-archive.com/linux-btrfs@vger.kernel.org/msg55161.html linux-btrfs mailing list] for more detailed information. In June 2020, somebody posted a [https://lore.kernel.org/linux-btrfs/20200627030614.GW10769@hungrycats.org/ comprehensive list of current issues] and a [https://lore.kernel.org/linux-btrfs/20200627032414.GX10769@hungrycats.org/ helpful recovery guide]. }}<br />
<br />
=== Scrub ===<br />
<br />
{{Expansion|[https://unix.stackexchange.com/questions/556816/does-btrfs-scrub-examine-subvolume-or-the-device-that-subvolume-resides-on Does Btrfs scrub examine subvolume or the device that subvolume resides on?]}}<br />
<br />
The [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary] says that Btrfs scrub is "[a]n online filesystem checking tool. Reads all the data and metadata on the filesystem, and uses checksums and the duplicate copies from RAID storage to identify and repair any corrupt data."<br />
<br />
{{Note|A running scrub process will prevent the system from suspending, see [https://web.archive.org/web/20160723034801/http://comments.gmane.org/gmane.comp.file-systems.btrfs/33106 this thread] for details.}}<br />
<br />
==== Start manually ====<br />
<br />
To start a (background) scrub on the filesystem which contains {{ic|/}}:<br />
<br />
# btrfs scrub start /<br />
<br />
To check the status of a running scrub:<br />
<br />
# btrfs scrub status /<br />
<br />
==== Start with a service or timer ====<br />
<br />
The {{Pkg|btrfs-progs}} package brings the {{ic|btrfs-scrub@.timer}} unit for monthly scrubbing the specified mountpoint. [[Enable]] the timer with an escaped path, e.g. {{ic|btrfs-scrub@-.timer}} for {{ic|/}} and {{ic|btrfs-scrub@home.timer}} for {{ic|/home}}. You can use {{ic|systemd-escape -p ''/path/to/mountpoint''}} to escape the path, see {{man|1|systemd-escape}} for details.<br />
<br />
You can also run the scrub by [[starting]] {{ic|btrfs-scrub@.service}} (with the same encoded path). The advantage of this over {{ic|btrfs scrub}} (as the root user) is that the results of the scrub will be logged in the [[systemd journal]].<br />
<br />
On large NVMe drives with insufficient cooling (e.g. in a laptop), scrubbing can read the drive fast enough and long enough to get it very hot. If you are running scrubs with systemd, you can easily limit the rate of scrubbing with the {{ic|IOReadBandwidthMax}} option described in {{man|5|systemd.resource-control}} by using a [[drop-in file]].<br />
<br />
=== Balance ===<br />
<br />
"A balance passes all data in the filesystem through the allocator again. It is primarily intended to rebalance the data in the filesystem across the devices when a device is added or removed. A balance will regenerate missing copies for the redundant RAID levels, if a device has failed." [https://btrfs.wiki.kernel.org/index.php/Glossary] See [https://btrfs.wiki.kernel.org/index.php/FAQ#What_does_.22balance.22_do.3F Upstream FAQ page].<br />
<br />
On a single-device filesystem a balance may be also useful for (temporarily) reducing the amount of allocated but unused (meta)data chunks. Sometimes this is needed for fixing [https://btrfs.wiki.kernel.org/index.php/FAQ#Help.21_Btrfs_claims_I.27m_out_of_space.2C_but_it_looks_like_I_should_have_lots_left.21 "filesystem full" issues].<br />
<br />
# btrfs balance start --bg /<br />
# btrfs balance status /<br />
<br />
=== Snapshots ===<br />
<br />
"A snapshot is simply a subvolume that shares its data (and metadata) with some other subvolume, using btrfs's COW capabilities." See [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Snapshots Btrfs Wiki SysadminGuide#Snapshots] for details.<br />
<br />
To create a snapshot:<br />
<br />
# btrfs subvolume snapshot ''source'' [''dest''/]''name''<br />
<br />
To create a readonly snapshot add the {{ic|-r}} flag. To create writable version of a readonly snapshot, simply create a snapshot of it.<br />
<br />
{{Note|Snapshots are not recursive. Every nested subvolume will be an empty directory inside the snapshot.}}<br />
<br />
=== Send/receive ===<br />
<br />
A subvolume can be sent to stdout or a file using the {{ic|send}} command. This is usually most useful when piped to a Btrfs {{ic|receive}} command. For example, to send a snapshot named {{ic|/root_backup}} (perhaps of a snapshot you made of {{ic|/}} earlier) to {{ic|/backup}} you would do the following:<br />
<br />
# btrfs send /root_backup | btrfs receive /backup<br />
<br />
The snapshot that is sent ''must'' be readonly. The above command is useful for copying a subvolume to an external device (e.g. a USB disk mounted at {{ic|/backup}} above).<br />
<br />
You can also send only the difference between two snapshots. For example, if you have already sent a copy of {{ic|root_backup}} above and have made a new readonly snapshot on your system named {{ic|root_backup_new}}, then to send only the incremental difference to {{ic|/backup}} do:<br />
<br />
# btrfs send -p /root_backup /root_backup_new | btrfs receive /backup<br />
<br />
Now a new subvolume named {{ic|root_backup_new}} will be present in {{ic|/backup}}.<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Incremental_Backup Btrfs Wiki's Incremental Backup page] on how to use this for incremental backups and for tools that automate the process.<br />
<br />
=== Deduplication ===<br />
<br />
Using copy-on-write, Btrfs is able to copy files or whole subvolumes without actually copying the data. However whenever a file is altered a new ''proper'' copy is created. Deduplication takes this a step further, by actively identifying blocks of data which share common sequences and combining them into an extent with the same copy-on-write semantics.<br />
<br />
Tools dedicated to deduplicate a Btrfs formatted partition include {{Pkg|duperemove}}, {{aur|bedup}} and ''btrfs-dedup''. One may also want to merely deduplicate data on a file based level instead using e.g. {{pkg|rmlint}}, {{aur|jdupes}} or {{aur|dduper-git}}. For an overview of available features of those programs and additional information have a look at the [https://btrfs.wiki.kernel.org/index.php/Deduplication#Batch upstream Wiki entry].<br />
<br />
Furthermore Btrfs developers are working on inband (also known as synchronous or inline) deduplication, meaning deduplication done when writing new data to the filesystem. Currently it is still an experiment which is developed out-of-tree. Users willing to test the new feature should read the [https://btrfs.wiki.kernel.org/index.php/User_notes_on_dedupe appropriate kernel wiki page].<br />
<br />
== Known issues ==<br />
<br />
A few limitations should be known before trying.<br />
<br />
=== Encryption ===<br />
<br />
Btrfs has no built-in encryption support, but this [https://lwn.net/Articles/700487/ may] come in the future. Users can encrypt the partition before running {{ic|mkfs.btrfs}}. See [[dm-crypt/Encrypting an entire system#Btrfs subvolumes with swap]]. <br />
<br />
Existing Btrfs file systems can use something like [[EncFS]] or [[TrueCrypt]], though perhaps without some of Btrfs' features.<br />
<br />
=== btrfs check issues ===<br />
<br />
The tool {{ic|btrfs check}} has known issues and should not be run without further reading, see section [[#btrfs check]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Partitionless Btrfs disk ===<br />
<br />
{{Warning|<br />
* Most users do not want this type of setup and instead should install Btrfs on a regular partition. Furthermore, GRUB strongly discourages installation to a partitionless disk. <br />
* Since {{Pkg|grub}} 2.04, GRUB's {{ic|core.img}} is too big to fit in Btrfs VBR. See {{Bug|63656}}.<br />
}}<br />
<br />
Btrfs can occupy an entire data storage device, replacing the [[MBR]] or [[GPT]] partitioning schemes, using [[#Subvolumes|subvolumes]] to simulate partitions. However, using a partitionless setup is not required to simply [[#File system creation|create a Btrfs filesystem]] on an existing [[partition]] that was created using another method. There are some limitations to partitionless single disk setups:<br />
<br />
* Cannot place other [[file systems]] on another partition on the same disk.<br />
* If using a Linux kernel version before 5.0, you cannot use [[Swap|swap area]] as Btrfs did not support [[Swap#Swap_file|swap files]] pre-5.0 and there is no place to create [[Swap#Swap_partition|swap partition]]<br />
* Cannot use [[UEFI]] to boot.<br />
<br />
To overwrite the existing partition table with Btrfs, run the following command:<br />
<br />
# mkfs.btrfs /dev/sd''X''<br />
<br />
For example, use {{ic|/dev/sda}} rather than {{ic|/dev/sda1}}. The latter would format an existing partition instead of replacing the entire partitioning scheme. Because the root partition is Btrfs, make sure {{ic|btrfs}} is compiled into the kernel, or put {{ic|btrfs}} into [[mkinitcpio.conf#MODULES]] and [[regenerate the initramfs]].<br />
<br />
Install the [[boot loader]] like you would for a data storage device with a [[Master Boot Record]]. See [[Syslinux#Manual install]] or [[GRUB/Tips and tricks#Install to partition or partitionless disk]]. If your kernel does not boot due to {{ic|Failed to mount /sysroot.}}, please add {{ic|1=GRUB_PRELOAD_MODULES="btrfs"}} in {{ic|/etc/default/grub}} and generate the grub configuration ([[GRUB#Generate the main configuration file]]).<br />
<br />
=== Ext3/4 to Btrfs conversion ===<br />
<br />
{{Warning|There are many reports on the btrfs mailing list about incomplete/corrupt/broken conversions. Make sure you have ''working'' backups of any data you cannot afford to lose. See [https://btrfs.wiki.kernel.org/index.php/Conversion_from_Ext3 Conversion from Ext3] on the btrfs wiki for more information.}}<br />
{{Warning|There is a bug in btrfs-progs 5.6.1 and before, that will yield a btrfs filesystem with wrong size for the last block group, thus preventing to mount the newly converted btrfs. This bug is fixed in btrfs-progs 5.7 in [https://github.com/kdave/btrfs-progs/commit/0ff7a9b5210723bd4ad0d9d78dbbb18ee8fdd2b1#diff-31168275dcaac634489082b54c4c66d0 this commit]. Please use btrfs-convert from btrfs-progs 5.7-1 and above.}}<br />
<br />
Boot from an install CD, then convert by doing:<br />
<br />
# btrfs-convert /dev/''partition''<br />
<br />
Mount the partion and test the conversion by checking the files. Be sure to change the {{ic|/etc/fstab}} to reflect the change ('''type''' to {{ic|btrfs}} and '''fs_passno''' [the last field] to {{ic|0}} as Btrfs does not do a file system check on boot). Also note that the UUID of the partition will have changed, so update fstab accordingly when using UUIDs. {{ic|chroot}} into the system and rebuild your bootloaders menu list (see [[Install from existing Linux]]). If converting a root filesystem, while still chrooted run {{ic|mkinitcpio -p linux}} to regenerate the initramfs or the system will not successfully boot.<br />
<br />
{{Note| If there is anything wrong, either unable to mount or write files to the newly converted btrfs, there is always the option to rollback as long as the backup subvolume {{ic|/ext2_saved}} is still there. Use {{ic|btrfs-convert -r /dev/''partition''}} command to rollback, this will discard any modifications to the newly converted btrfs filesystem.}}<br />
<br />
After confirming that there are no problems, complete the conversion by deleting the backup {{ic|ext2_saved}} sub-volume. Note that you cannot revert back to ext3/4 without it.<br />
<br />
# btrfs subvolume delete /ext2_saved<br />
<br />
Finally [[#Balance|balance]] the file system to reclaim the space.<br />
<br />
Remember that some applications which were installed prior have to be adapted to Btrfs.<br />
<br />
=== Checksum hardware acceleration ===<br />
<br />
{{Accuracy|1=According to [https://bugzilla.redhat.com/show_bug.cgi?id=1874808#c4], the CRC algorithm printed by the following command simply matches "''whatever crypto library is currently loaded at the time''", and "''can change arbitrarily while the file system is loaded''". So this method should not be relied upon in order to determine which CRC algorithm Btrfs is currently using.}}<br />
<br />
CRC32 is a new instruction in Intel SSE4.2. To verify if Btrfs checksum is hardware accelerated:<br />
<br />
{{hc|# dmesg {{!}} grep crc32c|2=<br />
Btrfs loaded, crc32c=crc32c-intel<br />
}}<br />
<br />
If you see {{ic|1=crc32c=crc32c-generic}}, it is probably because your root partition is Btrfs, and you will have to compile {{ic|crc32c-intel}} into the kernel to make it work. Putting {{ic|crc32c-intel}} into [[mkinitcpio.conf]] does ''not'' work.<br />
<br />
=== Corruption recovery ===<br />
<br />
{{Warning|The tool {{ic|btrfs check}} has known issues, see section [[#btrfs check]]}}<br />
<br />
''btrfs-check'' cannot be used on a mounted file system. To be able to use ''btrfs-check'' without booting from a live USB, add it to the initial ramdisk:<br />
<br />
{{hc|/etc/mkinitcpio.conf|output=<br />
BINARIES=("/usr/bin/btrfs")<br />
}}<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
Then if there is a problem booting, the utility is available for repair.<br />
<br />
{{Note|If the fsck process has to invalidate the space cache (and/or other caches?) then it is normal for a subsequent boot to hang up for a while (it may give console messages about btrfs-transaction being hung). The system should recover from this after a while.}}<br />
<br />
See the [https://btrfs.wiki.kernel.org/index.php/Btrfsck Btrfs Wiki page] for more information.<br />
<br />
=== Booting into snapshots ===<br />
<br />
In order to boot into a snapshot, the same procedure applies as for mounting a subvolume as your root parition, as given in section [[#Mounting subvolume as root|mounting a subvolume as your root partition]], because snapshots can be mounted like subvolumes.<br />
<br />
* If using [[GRUB]] you can automatically populate your boot menu with btrfs snapshots when regenerating the configuration file with the help of {{Pkg|grub-btrfs}} or {{AUR|grub-btrfs-git}}.<br />
* If using [[rEFInd]] you can automatically populate your boot menu with btrfs snapshots with the help of {{AUR|refind-btrfs}}, after [[enabling]] {{ic|refind-btrfs.service}}.<br />
<br />
=== Use Btrfs subvolumes with systemd-nspawn ===<br />
<br />
See the [[Systemd-nspawn#Use Btrfs subvolume as container root]] and [[Systemd-nspawn#Use temporary Btrfs snapshot of container]] articles.<br />
<br />
=== Reducing access time metadata updates ===<br />
<br />
Because of the copy-on-write nature of Btrfs simply accessing files can trigger the metadata copy and writing. Reducing the frequency of access time updates may eliminate this unexpected disk usage and increase performance. See [[fstab#atime options]] for the available options.<br />
<br />
== Troubleshooting ==<br />
<br />
See the [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ Btrfs Problem FAQ] for general troubleshooting.<br />
<br />
=== GRUB ===<br />
<br />
==== Partition offset ====<br />
<br />
The offset problem may happen when you try to embed {{ic|core.img}} into a partitioned disk. It means that [[Special:Diff/319474|it is OK]] to embed GRUB's {{ic|core.img}} into a Btrfs pool on a partitionless disk (e.g. {{ic|/dev/sd''X''}}) directly.<br />
<br />
[[GRUB]] can boot Btrfs partitions, however the module may be larger than other [[file systems]]. And the {{ic|core.img}} file made by {{ic|grub-install}} may not fit in the first 63 sectors (31.5KiB) of the drive between the MBR and the first partition. Up-to-date partitioning tools such as {{ic|fdisk}} and {{ic|gdisk}} avoid this issue by offsetting the first partition by roughly 1MiB or 2MiB.<br />
<br />
==== Missing root ====<br />
<br />
{{Accuracy|Suggests editing a non-configuration file manually.|Talk:Btrfs#Should not suggest to edit files in /usr/share}}<br />
<br />
Users experiencing the following: {{ic|1=error no such device: root}} when booting from a RAID style setup then edit /usr/share/grub/grub-mkconfig_lib and remove both quotes from the line {{ic|1=echo " search --no-floppy --fs-uuid --set=root ${hints} ${fs_uuid}"}}. Regenerate the config for grub and the system should boot without an error.<br />
<br />
=== Mounting timed out ===<br />
<br />
Sometimes, especially with large RAID1 arrays, mounting might time out during boot with a journal message such as:<br />
<br />
{{bc|1=<br />
Jan 25 18:05:12 host systemd[1]: storage.mount: Mounting timed out. Terminating.<br />
Jan 25 18:05:46 host systemd[1]: storage.mount: Mount process exited, code=killed, status=15/TERM<br />
Jan 25 18:05:46 host systemd[1]: storage.mount: Failed with result 'timeout'.<br />
Jan 25 18:05:46 host systemd[1]: Failed to mount /storage.<br />
Jan 25 18:05:46 host systemd[1]: Startup finished in 32.943s (firmware) + 3.097s (loader) + 7.247s (kernel)><br />
Jan 25 18:05:46 host kernel: BTRFS error (device sda): open_ctree failed<br />
}}<br />
<br />
This can easily be worked around by providing a longer timeout via the systemd-specific mount option {{ic|x-systemd.mount-timeout}} in [[fstab]]. For example:<br />
<br />
/dev/sda /storage btrfs rw,relatime,x-systemd.mount-timeout=5min 0 0<br />
<br />
=== BTRFS: open_ctree failed ===<br />
<br />
As of November 2014 there seems to be a bug in [[systemd]] or [[mkinitcpio]] causing the following error on systems with multi-device Btrfs filesystem using the {{ic|btrfs}} hook in {{ic|mkinitcpio.conf}}:<br />
<br />
{{bc|<nowiki><br />
BTRFS: open_ctree failed<br />
mount: wrong fs type, bad option, bad superblock on /dev/sdb2, missing codepage or helper program, or other error<br />
<br />
In some cases useful info is found in syslog - try dmesg|tail or so.<br />
<br />
You are now being dropped into an emergency shell.<br />
</nowiki>}}<br />
<br />
A workaround is to remove {{ic|btrfs}} from the {{ic|HOOKS}} array in {{ic|/etc/mkinitcpio.conf}} and instead add {{ic|btrfs}} to the {{ic|MODULES}} array. Then [[regenerate the initramfs]] and reboot.<br />
<br />
You will get the same error if you try to mount a raid array without one of the devices. In that case you must add the {{ic|degraded}} mount option to {{ic|/etc/fstab}}. If your root resides on the array, you must also add {{ic|1=rootflags=degraded}} to your [[kernel parameters]].<br />
<br />
As of August 2016, a potential workaround for this bug is to mount the array by a single drive only in {{ic|/etc/fstab}}, and allow btrfs to discover and append the other drives automatically. Group-based identifiers such as UUID and LABEL appear to contribute to the failure. For example, a two-device RAID1 array consisting of 'disk1' and disk2' will have a UUID allocated to it, but instead of using the UUID, use only {{ic|/dev/mapper/disk1}} in {{ic|/etc/fstab}}. For a more detailed explanation, see the following [https://web.archive.org/web/20161108175034/http://blog.samcater.com/fix-for-btrfs-open_ctree-failed-when-running-root-fs-on-raid-1-or-raid10-arch-linux/ blog post].<br />
<br />
Another possible workaround is to remove the {{ic|udev}} hook in [[mkinitcpio.conf]] and replace it with the {{ic|systemd}} hook. In this case, {{ic|btrfs}} should ''not'' be in the {{ic|HOOKS}} or {{ic|MODULES}} arrays.<br />
<br />
See the [https://bbs.archlinux.org/viewtopic.php?id=189845 original forums thread] and {{Bug|42884}} for further information and discussion.<br />
<br />
=== btrfs check ===<br />
<br />
{{Warning|Since Btrfs is under heavy development, especially the {{ic|btrfs check}} command, it is highly recommended to create a '''backup''' and consult the [https://btrfs.wiki.kernel.org/index.php/Btrfsck Btrfsck documentation] before executing {{ic|btrfs check}} with the {{ic|--repair}} switch.}}<br />
<br />
The ''[https://btrfs.wiki.kernel.org/index.php/Manpage/btrfs-check btrfs check]'' command can be used to check or repair an unmounted Btrfs filesystem. However, this repair tool is still immature and not able to repair certain filesystem errors even those that do not render the filesystem unmountable.<br />
<br />
== See also ==<br />
<br />
* '''Official site'''<br />
** [https://btrfs.wiki.kernel.org/ Btrfs Wiki]<br />
* '''Performance related'''<br />
** [https://superuser.com/questions/432188/should-i-put-my-multi-device-btrfs-filesystem-on-disk-partitions-or-raw-devices Btrfs on raw disks?]<br />
** [https://www.spinics.net/lists/linux-btrfs/msg18652.html Varying leafsize and nodesize in Btrfs]<br />
** [https://web.archive.org/web/20150717135111/http://comments.gmane.org/gmane.comp.file-systems.btrfs/15646 Btrfs support for efficient SSD operation (data blocks alignment)]<br />
** [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_Btrfs_optimized_for_SSD.3F Is Btrfs optimized for SSDs?]<br />
** '''Phoronix mount option benchmarking'''<br />
*** [https://www.phoronix.com/scan.php?page=article&item=btrfs-mount-linux49 Linux 4.9]<br />
*** [https://www.phoronix.com/scan.php?page=article&item=linux_314_btrfs Linux 3.14]<br />
*** [https://www.phoronix.com/scan.php?page=article&item=linux_btrfs_311&num=1 Linux 3.11]<br />
*** [https://www.phoronix.com/scan.php?page=news_item&px=MTM0OTU Linux 3.9]<br />
*** [https://www.phoronix.com/scan.php?page=article&item=btrfs_linux37_mounts&num=1 Linux 3.7]<br />
*** [https://www.phoronix.com/scan.php?page=article&item=linux_btrfs_options&num=1 Linux 3.2]<br />
** [https://blog.erdemagaoglu.com/post/4605524309/lzo-vs-snappy-vs-lzf-vs-zlib-a-comparison-of Lzo vs. zLib]<br />
* '''Miscellaneous'''<br />
** [[Funtoo:BTRFS Fun]]<br />
** [https://www.phoronix.com/scan.php?page=news_item&px=MTA0ODU Avi Miller presenting Btrfs] at SCALE 10x, January 2012.<br />
** [https://www.phoronix.com/scan.php?page=news_item&px=MTA4Mzc Summary of Chris Mason's talk] from LFCS 2012<br />
** [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=35054394c4b3cecd52577c2662c84da1f3e73525 Btrfs: stop providing a bmap operation to avoid swapfile corruptions] 2009-01-21<br />
** [https://marc.merlins.org/perso/btrfs/post_2014-03-22_Btrfs-Tips_-Doing-Fast-Incremental-Backups-With-Btrfs-Send-and-Receive.html Doing Fast Incremental Backups With Btrfs Send and Receive]</div>Rozhahttps://wiki.archlinux.org/index.php?title=PostgreSQL&diff=262950PostgreSQL2013-06-16T04:49:00Z<p>Rozha: /* Installing PostgreSQL */</p>
<hr />
<div>[[Category:Database management systems]]<br />
[[Category:Web Server]]<br />
[[it:PostgreSQL]]<br />
[[ru:PostgreSQL]]<br />
[[zh-CN:PostgreSQL]]<br />
{{Poor writing|excessive use of lists, please use them only when there are items to list.}}<br />
<br />
PostgreSQL is an open source, community driven, standard compliant object-relational database system.<br />
<br />
This document describes how to set up PostgreSQL. It also describes how to configure PostgreSQL to be accessible from a remote client. If you need help setting up the rest of a web stack, see the [[LAMP]] page and follow all of the sections except the one related to [[MySQL]].<br />
<br />
== Before you start ==<br />
<br />
Several sections have instructions stating "become the postgres user". Execute the following to get a shell as the postgres user:<br />
su root<br />
su - postgres<br />
<br />
Otherwise sudo can be used:<br />
<br />
sudo -i -u postgres<br />
<br />
== Installing PostgreSQL ==<br />
<br />
[[pacman|Install]] {{Pkg|postgresql}} from the [[official repositories]].<br />
<br />
Create the file tmpfiles.d for {{ic|/run/postgresql}}:<br />
# systemd-tmpfiles --create postgresql.conf<br />
<br />
Create the data directory (accordingly with the PGROOT variable set before in the config file)<br />
# mkdir /var/lib/postgres/data<br />
Set {{ic|/var/lib/postgres}} ownership to user {{ic|postgres}}:<br />
# chown -c -R postgres:postgres /var/lib/postgres<br />
As {{ic|postgres}} user start the database:<br />
# su - postgres<br />
$ initdb -D '/var/lib/postgres/data'<br />
Start PostgreSQL<br />
# systemctl start postgresql<br />
(Optional) Add PostgreSQL to the list of daemons that start on system startup<br />
# systemctl enable postgresql<br />
<br />
== Create your first database/user ==<br />
<br />
Become the postgres user. Add a new database-user using the [http://www.postgresql.org/docs/9.0/static/app-createuser.html createuser] command.<br />
<br />
If you create a user as per your login user ($USER) it allows you to access the postgresql database shell without having to specify a user to login (which makes it quite convenient).<br />
<br />
e.g. to create a superuser<br />
<br />
{{hc|$ createuser -s -U postgres --interactive|<br />
Enter name of role to add: myUsualArchLoginName}}<br />
<br />
Create a new database over which the above user has read/write privileges using the [http://www.postgresql.org/docs/9.0/static/app-createdb.html createdb] command.<br />
<br />
From your login shell ('''not''' the postrgres user's):<br />
<br />
$ createdb myDatabaseName<br />
<br />
== Familiarize with PostgreSQL ==<br />
<br />
=== Access the database shell ===<br />
<br />
Become the postgres user. Start the primary db shell, [http://www.postgresql.org/docs/8.3/static/app-psql.html psql], where you can do all your creation of databases/tables, deletion, set permissions, and run raw SQL commands. Use the "-d" option to connect to the database you created (without specifying a database, psql will try to access a database that matches your username)<br />
$ psql -d myDatabaseName<br />
<br />
Some helpful commands:<br />
<br />
Connect to a particular database<br />
=> \c <database><br />
List all users and their permission levels<br />
=> \du<br />
Shows summary information about all tables in the current database<br />
=> \dt<br />
exit/quit the psql shell<br />
=> \q or CTRL+d<br />
<br />
There are of course many more meta-commands, but these should help you get started.<br />
<br />
== Configure PostgreSQL to be accessible from remote hosts ==<br />
<br />
The PostgreSQL database server configuration file is {{ic|postgresql.conf}}. This file is located in the data directory of the server, typically {{ic|/var/lib/postgres/data}}. This folder also houses the other main config files, including the {{ic|pg_hba.conf}}.<br />
<br />
{{Note|By default this folder will not even be browseable (or searchable) by a regular user, if you are wondering why {{ic|find}} or {{ic|locate}} is not finding the conf files, this is the reason.}}<br />
<br />
As root user edit the file {{ic|/var/lib/postgres/data/postgresql.conf}}.<br />
In the connections and authentications section uncomment or edit the {{ic|listen_addresses}} line to your needs:<br />
listen_addresses = '*'<br />
Take a careful look at the other lines.<br />
Hereafter insert the following line in the host-based authentication file {{ic|/var/lib/postgres/data/pg_hba.conf}}. This file controls which hosts are allowed to connect, so '''be careful'''.<br />
# IPv4 local connections:<br />
host all all your_desired_ip_address/32 trust<br />
where {{ic|your_desired_ip_address}} is the IP address of the client.<br />
After this you should restart the daemon process for the changes to take effect with:<br />
# systemctl restart postgresql<br />
<br />
{{Note|Postgresql uses port 5432 by default for remote connections. So make sure this port is open and able to receive incoming connections.}}<br />
<br />
For troubleshooting take a look in the server log file<br />
tail /var/log/postgresql.log<br />
<br />
== Configure PostgreSQL to work with PHP==<br />
<br />
Install the PHP-PostgreSQL modules {{Pkg|php-pgsql}}.<br />
Edit the file {{ic|/etc/php/php.ini}}. Find the line that starts with:<br />
;extension=pgsql.so<br />
Change it to:<br />
extension=pgsql.so<br />
If you need PDO, do the same thing with {{ic|;extension&#61;pdo.so}} and {{ic|;extension&#61;pdo_pgsql.so}}. If these lines are not present, add them. These lines may be in the "Dynamic Extensions" section of the file, or toward the very end of the file.<br />
Restart the Apache web server:<br />
# systemctl restart httpd<br />
<br />
== Change default data dir (optional) ==<br />
<br />
The default directory where all your newly created databases will be stored is {{ic|/var/lib/postgres/data}}. To change this, follow these steps:<br />
<br />
Create the new directory and assign it to user {{ic|postgres}} (you eventually have to become root):<br />
mkdir -p /pathto/pgroot/data<br />
chown -R postgres:postgres /pathto/pgroot<br />
Become the postgres user(change to root, then postgres user), and initialize the new cluster:<br />
initdb -D /pathto/pgroot/data<br />
If not using systemd, edit {{ic|/etc/conf.d/postgresql}} and change the PGROOT variable(optionally PGLOG) to point to your new pgroot directory:<br />
#PGROOT="/var/lib/postgres/"<br />
PGROOT="''/pathto/pgroot/''"<br />
If using systemd, edit {{ic|/etc/systemd/system/multi-user.target.wants/postgresql.service}}, which links to {{ic|/usr/lib/systemd/system/postgresql.service}}, and change the default PGROOT path.<br />
#Environment=PGROOT=/var/lib/postgres/<br />
Environment=PGROOT=''/pathto/pgroot/''<br />
You will also need to change the default PIDFile path.<br />
PIDFile=/pathto/pgroot/data/postmaster.pid<br />
<br />
== Change default encoding of new databases to UTF-8 (optional) ==<br />
<br />
When creating a new database (e.g. with {{ic|createdb blog}}) PostgreSQL actually copies a template database. There are two predefined templates: template0 is vanilla, while template1 is meant as an on-site template changeable by the administrator and is used by default. In order to change the encoding of new database, one of the options is to change on-site template1. To do this, log into PostgresSQL shell (psql) and execute the following:<br />
<br />
First, we need to drop template1. Templates cannot be dropped, so we first modify it so it is an ordinary database:<br />
UPDATE pg_database SET datistemplate = FALSE WHERE datname = 'template1';<br />
Now we can drop it:<br />
DROP DATABASE template1;<br />
The next step is to create a new database from template0, with a new default encoding:<br />
CREATE DATABASE template1 WITH TEMPLATE = template0 ENCODING = 'UNICODE';<br />
Now modify template1 so it is actually a template:<br />
UPDATE pg_database SET datistemplate = TRUE WHERE datname = 'template1';<br />
(OPTIONAL) If you do not want anyone connecting to this template, set datallowconn to FALSE:<br />
UPDATE pg_database SET datallowconn = FALSE WHERE datname = 'template1';<br />
<br />
{{Note|this last step can create problems when upgrading via {{ic|pg_upgrade}}.}}<br />
<br />
Now you can create a new database by running from regular shell:<br />
su -<br />
su - postgres<br />
createdb blog;<br />
<br />
If you log in back to psql and check the databases, you should see the proper encoding of your new database:<br />
\l<br />
returns<br />
List of databases<br />
Name | Owner | Encoding | Collation | Ctype | Access privileges<br />
-----------+----------+-----------+-----------+-------+----------------------<br />
blog | postgres | UTF8 | C | C |<br />
postgres | postgres | SQL_ASCII | C | C |<br />
template0 | postgres | SQL_ASCII | C | C | =c/postgres<br />
: postgres=CTc/postgres<br />
template1 | postgres | UTF8 | C | C |<br />
<br />
== Administration tools ==<br />
<br />
* {{App|[[phpPgAdmin]]|Web-based administration tool for PostgreSQL.|http://phppgadmin.sourceforge.net|{{Pkg|phppgadmin}}}}<br />
* {{App|pgAdmin|GUI-based administration tool for PostgreSQL.|http://www.pgadmin.org/|{{Pkg|pgadmin3}}}}<br />
<br />
== Upgrading PostgreSQL ==<br />
<br />
=== Quick guide ===<br />
<br />
This is for upgrading from 9.1 to 9.2.<br />
<br />
pacman -S --needed postgresql-old-upgrade<br />
su - postgres -c 'mv /var/lib/postgres/data /var/lib/postgres/data-9.1'<br />
su - postgres -c 'mkdir /var/lib/postgres/data'<br />
su - postgres -c 'initdb -D /var/lib/postgres/data'<br />
<br />
If you had custom settings in configuration files like pg_hba.conf and postgresql.conf, merge them into the new ones. Then:<br />
<br />
su - postgres -c 'pg_upgrade -b /opt/pgsql-9.1/bin/ -B /usr/bin/ -d /var/lib/postgres/data-9.1 -D /var/lib/postgres/data'<br />
<br />
If the "pg_upgrade" step fails with:<br />
* ''cannot write to log file pg_upgrade_internal.log<br /> Failure, exiting'' <br />Make sure you're in a directory that the "postgres" user has enough rights to write the log file to ({{ic|/tmp}} for example). Or use "su - postgres" instead of "sudo -u postgres".<br />
* ''LC_COLLATE error that says that old and new values are different''<br />Figure out what the old locale was, C or en_US.UTF-8 for example, and force it when calling initdb.<br />
sudo -u postgres LC_ALL=C initdb -D /var/lib/postgres/data<br />
<br />
* ''There seems to be a postmaster servicing the old cluster.<br/>Please shutdown that postmaster and try again.''<br/>Make sure postgres isn't running. If you still get the error then chances are these an old PID file you need to clear out.<br />
> sudo -u postgres ls -l /var/lib/postgres/data-9.1<br />
total 88<br />
-rw------- 1 postgres postgres 4 Mar 25 2012 PG_VERSION<br />
drwx------ 8 postgres postgres 4096 Jul 17 00:36 base<br />
drwx------ 2 postgres postgres 4096 Jul 17 00:38 global<br />
drwx------ 2 postgres postgres 4096 Mar 25 2012 pg_clog<br />
-rw------- 1 postgres postgres 4476 Mar 25 2012 pg_hba.conf<br />
-rw------- 1 postgres postgres 1636 Mar 25 2012 pg_ident.conf<br />
drwx------ 4 postgres postgres 4096 Mar 25 2012 pg_multixact<br />
drwx------ 2 postgres postgres 4096 Jul 17 00:05 pg_notify<br />
drwx------ 2 postgres postgres 4096 Mar 25 2012 pg_serial<br />
drwx------ 2 postgres postgres 4096 Jul 17 00:53 pg_stat_tmp<br />
drwx------ 2 postgres postgres 4096 Mar 25 2012 pg_subtrans<br />
drwx------ 2 postgres postgres 4096 Mar 25 2012 pg_tblspc<br />
drwx------ 2 postgres postgres 4096 Mar 25 2012 pg_twophase<br />
drwx------ 3 postgres postgres 4096 Mar 25 2012 pg_xlog<br />
-rw------- 1 postgres postgres 19169 Mar 25 2012 postgresql.conf<br />
-rw------- 1 postgres postgres 48 Jul 17 00:05 postmaster.opts<br />
-rw------- 1 postgres postgres 80 Jul 17 00:05 postmaster.pid # <-- This is the problem<br />
<br />
> sudo -u postgres mv /var/lib/postgres/data-9.1/postmaster.pid /tmp<br />
* ''ERROR: could not access file "$libdir/postgis-2.0": No such file or directory'' <br> Retrieve postgis-2.0.so from postgis package for version postgresql 9.1 () and copy it to /opt/pgsql-9.1/lib (make sure the privileges are right)<br />
<br />
=== Detailed instructions ===<br />
<br />
{{Note|Official PostgreSQL [http://www.postgresql.org/docs/current/static/upgrading.html upgrade documentation] should be followed.}}<br />
<br />
Note that these instructions could cause data loss. '''Use at your own risk'''.<br />
<br />
It is recommended to add the following to your {{ic|/etc/pacman.conf}} file:<br />
IgnorePkg = postgresql postgresql-libs<br />
This will ensure you do not accidentally upgrade the database to an incompatible version. When an upgrade is available, pacman will notify you that it is skipping the upgrade because of the entry in pacman.conf. Minor version upgrades (e.g., 9.0.3 to 9.0.4) are safe to perform. However, if you do an accidental upgrade to a different major version (e.g., 9.0.X to 9.1.X), you might not be able to access any of your data. Always check the PostgreSQL home page (http://www.postgresql.org/) to be sure of what steps are required for each upgrade. For a bit about why this is the case see the [http://www.postgresql.org/support/versioning versioning policy].<br />
<br />
There are two main ways to upgrade your PostgreSQL database. Read the official documentation for details.<br />
<br />
For those wishing to use {{ic|pg_upgrade}}, a {{Pkg|postgresql-old-upgrade}} package is available in the repositories that will always run one major version behind the real PostgreSQL package. This can be installed side by side with the new version of PostgreSQL. When you are ready to perform the upgrade, you can do<br />
pacman -Syu postgresql postgresql-libs postgresql-old-upgrade<br />
Note also that the data directory does not change from version to version, so before running pg_upgrade it is necessary to rename your existing data directory and migrate into a new directory. The new database must be initialized by starting the server, as described near the top of this page. The server then needs to be stopped before running pg_upgrade.<br />
<br />
# systemctl stop postgresql<br />
# su - postgres -c 'mv /var/lib/postgres/data /var/lib/postgres/olddata'<br />
# systemctl start postgresql<br />
# systemctl stop postgresql<br />
<br />
Reference the [http://www.postgresql.org/docs/current/static/pgupgrade.html upstream pg_upgrade documentation] for details.<br />
<br />
The upgrade invocation will likely look something like the following (run as the postgres user). '''Do not run this command blindly without understanding what it does!'''<br />
<br />
# su - postgres -c 'pg_upgrade -d /var/lib/postgres/olddata/ -D /var/lib/postgres/data/ -b /opt/pgsql-8.4/bin/ -B /usr/bin/'<br />
<br />
You could also do something like this (after the upgrade and install of postgresql-old-upgrade)<br />
<br />
# systemctl stop postgresql<br />
# /opt/pgsql-8.4/bin/pg_ctl -D /var/lib/postgres/olddata/ start<br />
# pg_dumpall >> old_backup.sql<br />
# /opt/pgsql-8.4/bin/pg_ctl -D /var/lib/postgres/olddata/ stop<br />
# systemctl start postgresql<br />
# psql -f old_backup.sql postgres<br />
<br />
== Troubleshooting ==<br />
<br />
=== Improve performance of small transactions ===<br />
<br />
If you are using PostgresSQL on a local machine for development and it seems slow, you could try turning [http://www.postgresql.org/docs/current/static/runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT synchronous_commit off] in the configuration ({{ic|/var/lib/postgres/data/postgresql.conf}}). Beware of the [http://www.postgresql.org/docs/current/static/runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT caveats], however.<br />
<br />
synchronous_commit = off<br />
<br />
=== Prevent disk writes when idle ===<br />
<br />
PostgreSQL periodically updates its internal "statistics" file. By default, this file is stored on disk, which prevents disks spinning down on laptops and causes hard drive seek noise. It's simple and safe to relocate this file to a memory-only file system with the following configuration option:<br />
<br />
stats_temp_directory = '/run/postgresql'<br />
<br />
== See also ==<br />
<br />
* [http://www.postgresql.org/ Official PostgreSQL Homepage]</div>Rozhahttps://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=252127Network configuration/Wireless2013-03-28T00:22:19Z<p>Rozha: The AUR project 'compat-wireless-patched' has been renamed to 'compat-drivers-patched'</p>
<hr />
<div>[[Category:Wireless Networking]]<br />
[[cs:Wireless Setup]]<br />
[[de:(W)LAN_und_Arch_Linux]]<br />
[[es:Wireless Setup]]<br />
[[fr:Wifi]]<br />
[[it:Wireless Setup]]<br />
[[ja:Wireless Setup]]<br />
[[nl:Wireless Setup]]<br />
[[ro:Wireless]]<br />
[[ru:Wireless Setup]]<br />
[[th:Wireless Setup]]<br />
[[tr:Kablosuz_bağlantı]]<br />
[[zh-CN:Wireless Setup]]<br />
{{Article summary start}}<br />
{{Article summary text|A complete guide to enabling and configuring wireless networking.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Networking overview}}}}<br />
{{Article summary end}}<br />
<br />
{{Poor writing|Article too large, drivers specific guidelines should be moved to a dedicated page.}}<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, so make sure you install them), 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 />
'''About new Arch Linux systems:''' Most wireless drivers and tools are available during Arch set-up under the {{grp|base}} group. Be sure to install the proper driver for your card. [[Udev]] will usually load the appropriate module, thereby creating the wireless interface, in the initial live system of the installer, as well as the newly installed system on your hard drive. If you are configuring your wireless functionality after, and not during, Arch Linux installation, simply ensure the required packages are installed with [[pacman]], (driver, firmware if needed, {{Pkg|wireless_tools}}, {{Pkg|iw}}, {{Pkg|wpa_supplicant}}, etc.) and follow the guidelines below. Note that {{Pkg|wireless_tools}} may be optional depending on how recent your wireless hardware is.<br />
<br />
== Part I: Identify Card/Install Driver ==<br />
<br />
=== Identify and Discover if Supported ===<br />
<br />
First you will need to check and see if the Linux kernel has support for your card or if a user-space driver is available for it.<br />
<br />
==== Identify your card ====<br />
<br />
You can find your card type by command:<br />
# lspci | grep -i net<br />
<br />
Or, if you have a USB device, run:<br />
# lsusb<br />
<br />
{{Note|The internal Wi-Fi card in some laptops may actually be a USB device, so make sure you check both commands.}}<br />
<br />
==== Discover if the card is supported ====<br />
<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 />
* The [http://wireless.kernel.org/en/users/Devices kernel page] additionally has a matrix of supported hardware.<br />
<br />
==== If your card is not listed ====<br />
<br />
If your wireless hardware is not listed above, likely it is supported only under Windows (some Broadcom, 3com, etc). For these, you will need to use [http://ndiswrapper.sourceforge.net/wiki/index.php/List ndiswrapper]. <br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. See the compatibility list [http://ndiswrapper.sourceforge.net/mediawiki/index.php/List here]. You will need the {{ic|.inf}} and {{ic|.sys}} files from your Windows install. If you have a newer card, or a more exotic card, you might want to look up your exact model name and 'linux' and search the Internet before doing this step.<br />
<br />
===Install user space tools ===<br />
<br />
====If you have wired Internet access available====<br />
If you have wired Ethernet available and are simply adding wireless functionality to an existing system, and you did not include {{Pkg|wireless_tools}} during initial installation, then [[pacman|install]] the package {{Pkg|wireless_tools}}.<br />
<br />
{{Note|{{Pkg|wireless_tools}} may not be required depending on the age of your hardware and whether your hardware/drivers support {{Pkg|wpa_supplicant}}. If your configuration is supported well enough to work using only {{Pkg|wpa_supplicant}}, then it is recommended to stick with wpa_supplicant only.}}<br />
<br />
The drivers' corresponding package names are either highlighted in '''bold''' or via {{ic|monospaced font}} on this page. The packages can be installed during initial package selection on the Arch Linux installation media and can also be [[pacman|installed]] later.<br />
<br />
====If you have only wireless internet available====<br />
The {{Pkg|wireless_tools}} package is now available as part of the base system and is also on the live installation media (CD/USB stick image) under the [[Beginners%27_Guide#Install_the_base_system|base-devel]] group. <br />
<br />
You cannot initialize wireless hardware without these user-space tools, so ensure they are installed from the [[Beginners%27_Guide#Install_the_base_system|installer media]], especially if you have no means of networking other than wirelessly. Otherwise, you will be stuck in a "catch 22" when you reboot your newly installed Arch Linux system: you will need {{Pkg|wireless_tools}} and drivers, but in order to get them, you will need {{Pkg|wireless_tools}} and drivers.<br />
<br />
===Drivers and firmware===<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. Udev will load appropriate modules (drivers) for your corresponding hardware, and the driver, in turn, will allow creation of a kernel ''interface''. <br />
<br />
The interface name for different drivers and chipsets will vary. Some examples are ''wlan0'', ''eth1'', and ''ath0''.<br />
<br />
{{Note|Udev is not perfect. If the proper module is not loaded by udev on boot, simply {{ic|modprobe}} it and add the module name in a {{ic|.conf}} file in {{ic|/etc/modules-load.d/}}. Note also that udev may occasionally load more than one driver for a device, and the resulting conflict will prevent successful configuration. Be sure to [[Kernel_modules#Blacklisting|blacklist]] the unwanted module.}}<br />
<br />
Methods and procedures for installing kernel modules for various chipsets are covered below. In addition, certain chipsets require the installation of corresponding ''firmware'' (also covered below). Read [[Kernel modules]] for general informations on operations with modules.<br />
<br />
====rt2860 and rt2870====<br />
<br />
From Linux kernel 3.0, the staging driver {{ic|rt2860sta}} is replaced by the mainline driver {{ic|rt2800pci}}, and {{ic|rt2870sta}} is replaced by {{ic|rt2800usb}}. As a result, the staging drivers are deleted. Source: [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3 Kernel commit]. The rt2800 driver automatically works with devices using the rt2870 chipset.<br />
<br />
It has 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] available from Ralink.<br />
<br />
====rt3090====<br />
For devices which are using the rt3090 chipset it should be possible to use {{ic|rt2860sta}} driver. The mainline driver {{ic|rt2800pci}} is not working with this chipset very well (e.g. sometimes it's not possible to use higher rate than 2Mb/s).<br />
<br />
The best way is to use the {{AUR|rt3090}} driver from [[AUR]]. Compile the {{AUR|rt3090}} driver from [[AUR]], delete/move the /etc/Wireless/RT2860STA/RT2860STA.dat firmware file to allow installation of the compiled RT3090 package, [[Kernel modules#Blacklisting|blacklist]] the rt2860sta module and setup the rt3090sta module to [[Kernel modules#Loading|load]] at boot.<br />
<br />
Note: This driver also works for rt3062 chipsets.<br />
<br />
====rt2x00====<br />
Unified driver for Ralink chipsets (replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, but some devices may require extra firmware. It can be configured using the standard {{Pkg|wpa_supplicant}} and {{ic|iwconfig}} tools.<br />
<br />
Some chips require a firmware file, which is installed by default in Arch Linux via the package {{Pkg|linux-firmware}}.<br />
<br />
See: [[Using the new rt2x00 beta driver]]<br />
<br />
====rt3573====<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it, see [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 example]<br />
====rt5572====<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 />
====w322u====<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See: [[rt2870]]<br />
<br />
====rtl8180====<br />
Realtek rtl8180 PCI/Cardbus 802.11b is now fully supported in the kernel. It can be configured using the standard {{Pkg|wpa_supplicant}} and {{ic|iwconfig}} tools.<br />
<br />
====rtl8187====<br />
See: [[Rtl8187_wireless|rtl8187]]<br />
<br />
====rtl8192e====<br />
<br />
The driver is part of the current kernel package. It can be configured using the standard {{Pkg|wpa_supplicant}} and {{ic|iwconfig}} tools.<br />
<br />
{{Note|[[wicd]] may cause excessive dropped connections with this driver, while [[NetworkManager]] appears to work better.}}<br />
<br />
=====Module initialization fails=====<br />
<br />
The module initialization may fail at boot giving this error message : <br />
<br />
rtl819xE:ERR in CPUcheck_firmware_ready()<br />
rtl819xE:ERR in init_firmware() step 2<br />
rtl819xE:ERR!!! _rtl8192_up(): initialization is failed!<br />
r8169 0000:03:00.0: eth0: link down<br />
<br />
A workaround is to simply unload the module: <br />
# modprobe -r r8192e_pci<br />
and reload the module (after a pause): <br />
# modprobe r8192e_pci<br />
<br />
====rtl8192s====<br />
<br />
The driver is part of the current kernel package. Firmware may need to be added manually if {{ic|/usr/lib/firmware/RTL8192SU/rtl8192sfw.bin}} does not exist. ({{ic|dmesg}} will report ''"rtl819xU:FirmwareRequest92S(): failed"'' if the firmware is missing)<br />
<br />
To download and install firmware:<br />
$ wget http://launchpadlibrarian.net/33927923/rtl8192se_linux_2.6.0010.1012.2009.tar.gz<br />
# mkdir /lib/firmware/RTL8192SU<br />
# tar -xzOf rtl8192se_linux_2.6.0010.1012.2009.tar.gz \<br />
rtl8192se_linux_2.6.0010.1012.2009/firmware/RTL8192SE/rtl8192sfw.bin > \<br />
/lib/firmware/RTL8192SU/rtl8192sfw.bin<br />
<br />
{{Note|An alternate version of the firmware may be found [http://launchpadlibrarian.net/37387612/rtl8192sfw.bin.gz here], but this version may cause dropped connections.}}<br />
<br />
{{Note|[[wicd]] may cause excessive dropped connections with this driver, while [[NetworkManager]] appears to work better.}}<br />
<br />
====madwifi-ng====<br />
There are three modules maintained by the MadWifi team:<br />
* {{ic|ath_pci}} is the older driver.<br />
* [[#ath5k|{{ic|ath5k}}]] will eventually phase out {{ic|ath_pci}}. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* [[#ath9k|{{ic|ath9k}}]] is the new, official, superior driver for newer Atheros hardware (see below)<br />
<br />
For old {{ic|ath_pci}} driver, install package {{AUR|madwifi}} and optionally {{AUR|madwifi-utils-svn}}. Then:<br />
# modprobe ath_pci<br />
<br />
If using {{ic|ath_pci}}, you may need to blacklist {{ic|ath5k}}. See [[Kernel_modules#Blacklisting]] for instructions.<br />
<br />
Some users '''may need''' to use the {{ic|countrycode}} option when loading the MadWifi driver in order to use channels and transmit power settings that are legal in their country/region. In the Netherlands, for example, you would load the module like this:<br />
# modprobe ath_pci countrycode=528<br />
<br />
You can verify the settings with the {{ic|iwlist}} command. See {{ic|man iwlist}} and the [http://madwifi-project.org/wiki/UserDocs/CountryCode CountryCode page on the MadWifi wiki]. To have this setting automatically applied during boot, refer to [[Kernel_modules#Configuration]], and note the following module option setting:<br />
options ath_pci countrycode=528<br />
<br />
====ath5k====<br />
{{ic|ath5k}} is the preferred driver for AR5xxx chipsets including those which are already working with {{ic|madwifi-ng}} and for some chipsets older than AR5xxx. <br />
<br />
If {{ic|ath5k}} is conflicting with {{ic|ath_pci}} on your system, [[Kernel_modules#Blacklisting|blacklist]] (and unload using {{ic|rmmod}} or reboot) the following drivers:<br />
ath_hal<br />
ath_pci<br />
ath_rate_amrr<br />
ath_rate_onoe<br />
ath_rate_sample<br />
wlan<br />
wlan_acl<br />
wlan_ccmp<br />
wlan_scan_ap<br />
wlan_scan_sta<br />
wlan_tkip<br />
wlan_wep<br />
wlan_xauth<br />
<br />
then {{ic|modprobe ath5k}} manually or reboot. ''wlan0'' (or ''wlanX'') in sta mode should spawn and become ready to use.<br />
<br />
Info:<br />
* http://wireless.kernel.org/en/users/Drivers/ath5k<br />
* http://wiki.debian.org/ath5k<br />
<br />
{{Note|1=Some laptop have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
echo none > "/sys/class/leds/ath5k-phy0::tx/trigger"<br />
echo none > "/sys/class/leds/ath5k-phy0::rx/trigger"<br />
<br />
For alternatives, look [https://bugzilla.redhat.com/show_bug.cgi?id=618232 here].}}<br />
<br />
{{Note|1=If you find web pages randomly loading very slow in Firefox/Opera/Chromium try to switch from hardware to software encryption:<br />
rmmod ath5k<br />
modprobe ath5k nohwcrypt<br />
<br />
And restart your connection. If it helps, make the change permanent by adding into {{ic|/etc/modprobe.d/010-ath5k.conf}}:<br />
options ath5k nohwcrypt<br />
<br />
More about modprobe options: [[Modprobe#Options]]<br />
}}<br />
<br />
====ath9k====<br />
{{ic|ath9k}} is Atheros' officially supported driver for the newer 802.11n chipsets. All of the chips with 802.11n capabilities are supported, with a maximum throughput around 180 Mbps. To see a complete list of supported hardware, check this [http://wireless.kernel.org/en/users/Drivers/ath9k page].<br />
<br />
Working modes: Station, AP and Adhoc.<br />
<br />
{{ic|ath9k}} has been part of the Linux kernel as of v2.6.27. (In the unlikely event that you have stability issues that trouble you, you could try using the [http://wireless.kernel.org/en/users/Download compat-wireless] package.<br />
An [https://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list] exists for support and development related discussions.)<br />
<br />
Info:<br />
* http://wireless.kernel.org/en/users/Drivers/ath9k<br />
* http://wiki.debian.org/ath9k<br />
<br />
====ath9k_htc====<br />
{{ic|ath9k_htc}} is Atheros' officially supported driver for 802.11n USB devices. Station and Ad-Hoc modes are supported. The driver is included in the kernel. For more information, see http://wireless.kernel.org/en/users/Drivers/ath9k_htc .<br />
<br />
====ipw2100 and ipw2200====<br />
These modules are fully supported in the kernel, but they require additional firmware. It can be configured using the standard {{Pkg|wpa_supplicant}} and {{ic|iwconfig}} tools.<br />
<br />
Depending on which of the chipsets you have, [[pacman|install]] either {{Pkg|ipw2100-fw}} or {{Pkg|ipw2200-fw}}.<br />
<br />
If installing after initial Arch Linux installation, the module may need to be reloaded for the firmware to be loaded; run the following as root:<br />
rmmod ipw2200<br />
modprobe ipw2200<br />
<br />
=====Enabling the radiotap interface=====<br />
Launch the following as root:<br />
rmmod ipw2200<br />
modprobe ipw2200 rtap_iface=1<br />
<br />
=====Enabling the LED=====<br />
Most laptops will have a front LED to indicate when the wireless is connected (or not). Add the following to {{ic|/etc/modprobe.d/ipw2200.conf}}:<br />
options ipw2200 led=1<br />
<br />
====iwl3945, iwl4965 and iwl5000-series====<br />
'''I'''ntel's open source '''W'''i-Fi drivers for '''L'''inux (See [http://intellinuxwireless.org iwlwifi]) will work for both the 3945 and 4965 chipsets since kernel 2.6.24. And iwl5000-series chipsets (including 5100BG, 5100ABG, 5100AGN, 5300AGN and 5350AGN) have been supported since '''kernel 2.6.27''', by the in-tree driver '''iwlagn'''.<br />
<br />
Since the 2.6.34 kernel update, the firmware files were moved to the {{ic|linux-firmware}} package. Manually installing firmware packages is not required.<br />
<br />
=====Loading the Driver=====<br />
[[udev]] should load the driver automatically. To manually load the driver at start-up, read [[Kernel modules#Loading]], and add {{ic|iwl3945}} or {{ic|iwl4965}} respectively to the new file. For example:<br />
# Load Intel Wi-Fi modules<br />
iwl3945<br />
<br />
The drivers should now load after a reboot, and running {{ic|ip addr}} from a terminal should report ''wlan0'' as a new network interface.<br />
<br />
=====Disabling LED blink=====<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:<br />
<br />
# echo 'w /sys/class/leds/phy0-led/trigger - - - - phy0radio' > /etc/tmpfiles.d/phy0-led.conf<br />
# systemd-tmpfiles --create phy0-led.conf<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
Here is an example for the old way, if you do not have {{ic|/sys/class/leds/phy0-led}}:<br />
<br />
# echo "options iwlcore led_mode=1" >> /etc/modprobe.d/modprobe.conf<br />
# rmmod iwlagn<br />
# rmmod iwlcore<br />
# modprobe iwlcore<br />
# modprobe iwlagn<br />
<br />
On Linux kernels 2.6.39.1-1 and up, the {{ic|iwlcore}} module was deprecated. Use {{ic|1=options iwlagn led_mode=1}} or {{ic|1=options iwl_legacy led_mode=1}} instead (find out what module is loaded with {{ic|lsmod}}).<br />
<br />
{{Note| iwl_legacy was renamed iwlegacy in Linux kernel 3.3.1. For this version, use {{ic|1=options iwlegacy led_mode=1}}.}}<br />
<br />
=====Other Notes=====<br />
* The MS Windows NETw4x32 driver can be used with ndiswrapper as an alternative to the {{ic|iwl3945}} and {{ic|ipw3945}} drivers.<br />
* In some cases (specifically a [[Dell Latitude D620]] with Arch 2008.06, though it could happen elsewhere), after installation you may have both {{ic|iwl3945}} and {{ic|ipw3945}} modules loaded. The card will not work with both modules loaded, so you will have to [[Kernel modules#Blacklisting|blacklist]] the {{ic|ipw3945}} module.<br />
* By default, {{ic|iwl3945}} is configured to only work with networks on channels 1-11. Higher frequency bands are not allowed in some parts of the world (e.g. the US). In the EU however, channels 12 and 13 are used quite commonly (and Japan allows for channel 14). To make {{ic|iwl3945}} scan for all channels, add {{ic|1=options cfg80211 ieee80211_regdom=EU}} to {{ic|/etc/modprobe.d/modprobe.conf}}. With {{ic|iwlist f}} you can check which channels are allowed.<br />
* If you want to enable more channels on Intel Wifi 5100 (and quite possible other cards too), you can do that with the {{pkg|crda}} package. After installing the package, edit {{ic|/etc/conf.d/wireless-regdom}} and uncomment the line where your country code is found. When executing {{ic|sudo iwlist wlan0 channel}}, you should now have access to more channels (depending on your location).<br />
<br />
====orinoco====<br />
This should be a part of the kernel package and be installed already.<br />
<br />
{{Note|1=Some Orinoco chipsets are Hermes I/II. You can use the AUR package {{AUR|wl_lkm}} to replace the {{ic|orinoco}} driver and gain WPA support. See [http://ubuntuforums.org/showthread.php?p=2154534#post2154534 this post] for more information.}}<br />
<br />
To use the driver, [[Kernel modules#Blacklisting|blacklist]] {{ic|orinoco_cs}}, and then add {{ic|wlags49_h1_cs}}.<br />
<br />
====ndiswrapper====<br />
Ndiswrapper is not a real driver, but you can use it when there are no native Linux kernel drivers for your wireless chipset, so it is very useful in some situations. To use it, you need the {{ic|*.inf}} file from your Windows driver (the {{ic|*.sys}} file must also be present in the same directory). Be sure to use drivers appropriate to your architecture (e.g. 32/64bit). 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 the driver to {{ic|/etc/ndiswrapper/*}}<br />
ndiswrapper -i filename.inf<br />
2. List all installed drivers for ndiswrapper<br />
ndiswrapper -l<br />
3. Write configuration file 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#Loading]] 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. Check this page if you are having problems:<br />
[http://ndiswrapper.sourceforge.net/joomla/index.php?/component/option,com_openwiki/Itemid,33/id,installation/ Ndiswrapper installation wiki].<br />
<br />
====prism54====<br />
Download the firmware driver for your appropriate card from [http://linuxwireless.org/en/users/Drivers/p54 this site]. Rename the firmware file to {{ic|isl3890}}.<br />
If non-existent, create the directory {{ic|/usr/lib/firmware}} and move the file {{ic|isl3890}} inside it. This should do the trick. [https://bbs.archlinux.org/viewtopic.php?t=16569&start=0&postdays=0&postorder=asc&highlight=siocsifflags+such+file++directory]<br />
<br />
If that did not work, try this:<br />
<br />
*Reload the prism module ({{ic|modprobe p54usb}} or {{ic|modprobe p54pci}}, depending on your hardware)<br />
Alternatively, remove your Wi-Fi card and then reconnect it.<br />
*Use the {{ic|dmesg}} command, and look at the end of the output it prints out.<br />
Look for a section similar to this: <br />
firmware: requesting '''isl3887usb_bare'''<br />
p54: LM86 firmware<br />
p54: FW rev 2.5.8.0 - Softmac protocol 3.0<br />
and try renaming the firmware file to the name corresponding to the part bolded here.<br />
<br />
If you get the message <br />
SIOCSIFFLAGS: Operation not permitted<br />
when performing {{ic|ip link set wlan0 up}} OR <br />
prism54: Your card/socket may be faulty, or IRQ line too busy :(<br />
appears in {{ic|dmesg}}'s output this may be because you have both the deprecated kernel module {{ic|prism54}} and one of the newer kernel modules ({{ic|p54pci}} or {{ic|p54usb}}) loaded at the same time and they are fighting over ownership of the IRQ. Use the command {{ic|<nowiki>lsmod | grep prism54</nowiki>}} to see if the deprecated module is being loaded. If so, you need to stop {{ic|prism54}} from loading by [[blacklisting]] it (there are several ways to do this which are described elsewhere). Once blacklisted, you may find you have to rename the firmware as {{ic|prism54}} and {{ic|p54pci}}/{{ic|p54usb}} look for different firmware filenames (i.e. recheck the {{ic|dmesg}} output after performing {{ic|ip link set eth0 up}}).<br />
<br />
====ACX100/111====<br />
Packages: {{ic|tiacx}} {{ic|tiacx-firmware}}<br />
<br />
The driver should tell you which firmware it needs; check {{ic|/var/log/messages.log}} or use the {{ic|dmesg}} command.<br />
<br />
Link the appropriate firmware to {{ic|/usr/lib/firmware}}:<br />
ln -s /usr/share/tiacx/acx111_2.3.1.31/tiacx111c16 /usr/lib/firmware<br />
<br />
For another way to determine which firmware revision number to use, see the [http://acx100.sourceforge.net/wiki/Firmware "Which firmware" section] of the acx100.sourceforge wiki. For ACX100, you can follow the links provided there to a table of card model numbers vs. "firmware files known to work"; you can figure out the rev. number you need, by looking at the suffix there. For example, a dlink_dwl650+ uses "1.9.8.b", in which case you would do this:<br />
ln -s /usr/share/tiacx/acx100_1.9.8.b/* /usr/lib/firmware<br />
<br />
If you find that the driver is spamming your kernel log, for example because you are running Kismet with channel-hopping, you could put this in {{ic|/etc/modprobe.d/modprobe.conf}}:<br />
options acx debug=0<br />
<br />
{{Note|The open-source {{ic|acx}} driver does not support WPA/RSN encryption. Ndiswrapper will have to be used with the Windows driver to enable the enhanced encryption. See ndiswrapper, this page, for more details.}}<br />
<br />
==== b43, broadcom-wl and brcmsmac (previously brcm80211)====<br />
See the [[Broadcom_wireless|Broadcom wireless]] page.<br />
<br />
====zd1211rw====<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 [[pacman|install]] the firmware for the device, provided by the {{Pkg|zd1211-firmware}} package.<br />
<br />
====carl9170====<br />
[http://wireless.kernel.org/en/users/Drivers/carl9170/ {{ic|carl9170}}] is the 802.11n USB driver with GPLv2 firmware for Atheros USB AR9170 devices. It supports these [http://wireless.kernel.org/en/users/Drivers/carl9170#available_devices devices]. The '''firmware''' is not yet part of the {{Pkg|linux-firmware}} package; it is available in the [[AUR]] ({{AUR|carl9170-fw}}). The '''driver''' is a part of the Linux kernel v2.6.37 and higher.<br />
<br />
In order to use this driver, the following older driver modules must be [[Kernel_modules#Blacklisting|blacklisted]]:<br />
*{{ic|arusb_lnx}}<br />
*{{ic|ar9170usb}}<br />
<br />
====hostap_cs====<br />
Host AP is the Linux driver for Prism2/2.5/3 like WCP11. {{ic|hostap_cs}} should be a part of the {{ic|linux}} package and should be installed already.<br />
<br />
{{ic|orinico_cs}} can cause problems, so it must be [[Kernel_modules#Blacklisting|blacklisted]]. After blacklisting, the driver should work.<br />
<br />
More information:[http://hostap.epitest.fi/ Home page]<br />
<br />
====compat-drivers-patched====<br />
Patched compat wireless drivers correct the "fixed-channel -1" issue, whilst providing better injection. Please install the {{AUR|compat-drivers-patched}} package from the [[Arch User Repository|AUR]].<br />
<br />
{{AUR|compat-drivers-patched}} does not conflict with any other package and the modules built reside in {{ic|/usr/lib/modules/''your_kernel_version''/updates}}.<br />
<br />
These patched drivers come from the [http://wireless.kernel.org/ Linux Wireless project] and support many of the above mentioned chips such as:<br />
<br />
ath5k ath9k_htc carl9170 b43 zd1211rw rt2x00 wl1251 wl12xx ath6kl brcm80211<br />
<br />
Supported groups:<br />
<br />
atheros ath iwlagn rtl818x rtlwifi wl12xx atlxx bt<br />
<br />
It is also possible to build a specific module/driver or a group of drivers by editing the [[PKGBUILD]], particularly uncommenting the '''line #46'''. Here is an example of building the atheros group:<br />
<br />
scripts/driver-select atheros<br />
<br />
Please read the package's [[PKGBUILD]] for any other possible modifications prior to compilation and installation.<br />
<br />
===Test installation===<br />
After loading your driver, run {{ic|ip link}} to ensure a wireless interface (e.g. ''wlanX'', ''ethX'', ''athX'') is created.<br />
<br />
If no such interface is visible, modprobing it might work. To start your driver, use the {{ic|rmmod}} and {{ic|modprobe}} commands. If {{ic|rmmod}} fails, continue with {{ic|modprobe}}. See [[Kernel modules]] for more info.<br />
<br />
Example: If your driver is called "driverXXX", you would run the following commands:<br />
# rmmod driverXXX<br />
# modprobe driverXXX<br />
<br />
Bring the interface up with {{ic|ip link set <interface> up}}. For example, assuming the interface is ''wlan0'':<br />
# ip link set wlan0 up<br />
<br />
If you get this error message: {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means your wireless chipset requires a firmware to function, which you need to install as explained above.<br />
<br />
==Part II: Wireless management==<br />
Assuming that your drivers are installed and working properly, you will need to choose a method for managing your wireless connections. The following subsections will help you decide the best way to do just that.<br />
<br />
Procedure and tools required will depend on several factors:<br />
* The desired nature of configuration management; from a completely manual command line setup procedure to a software-managed, automated solution.<br />
* The encryption type (or lack thereof) which protects the wireless network.<br />
* The need for network profiles, if the computer will frequently change networks (such as a laptop).<br />
<br />
The manual method requires more work from you, but gives you much more control over your configuration.<br />
Usually you will have to enter a set of commands which have no persistant effect, i.e. they won't apply after a reboot.<br />
Either you enter those commands on every boot which may be quite cumbersome, or you put all these commands in a shell script to automate the process. This script can even be executed automatically at boot time. See [[Arch Boot Process]].<br />
<br />
===Management methods===<br />
The following table shows the different methods that can be used to activate and manage a wireless network connection, depending on the encryption and management types, and the various tools that are required. Although there may be other possibilities, these are the most frequently used:<br />
{| border="1"<br />
! Management || No encryption/WEP || WPA/WPA2 PSK<br />
|-<br />
| Manual || {{pkg|iproute2}} + {{ic|iwconfig}} + {{ic|dhcpcd}}/{{ic|iproute2}} || {{ic|iproute2}} + {{ic|iwconfig}} + [[WPA supplicant|wpa_supplicant]] + {{ic|dhcpcd}}/{{ic|iproute2}}<br />
|-<br />
| Automatically managed, with network profiles support || colspan="2" align="center" | [[netcfg]], [[Wicd]], [[NetworkManager]], etc.<br />
|}<br />
<br />
More choice guide: <br />
<br />
{| border="1"<br />
! - || netcfg || Wicd || [[NetworkManager]] + {{pkg|network-manager-applet}}<br />
|-<br />
| auto connect at boot || with [[Netcfg#Net-Profiles|net-profiles]] service || yes || yes<br />
|-<br />
| auto connect if dropped <br>or changed location || with [[Netcfg#Net-Auto-Wireless|net-auto-wireless]] service || yes || yes<br />
|-<br />
| support 3G Modem || || || yes<br />
|-<br />
| GUI (proposes to manage and connect/disconnect<br> profiles from a systray icon. <br>Automatic wireless detection is also available) || with ArchAssistant || yes || yes<br />
|-<br />
| console tools || with {{ic|wifi-select}} || {{ic|wicd-curses}} (part of {{pkg|wicd}} package) || {{ic|nmcli}}<br />
|}<br />
<br />
Please note that the Linux wireless extensions and corresponding commands like {{ic|iwconfig}} or {{ic|iwlist}} become deprecated and replaced by {{ic|iw}}, which has to be installed seperately from the core-repository. This is not fully reflected in this wiki yet and both work still. A comparison of common commands is found on [http://linuxwireless.org/en/users/Documentation/iw/replace-iwconfig Linuxwireless].<br />
<br />
Whatever your choice, '''you should really try to connect using the manual method first'''. This will help you understand the different steps that are required and debug them in case a problem arose. Another tip: if possible (e.g. if you manage your Wi-Fi access point), try connecting with no encryption, to check everything works. Then try using encryption, either WEP (simpler to configure -- but crackable in a matter of seconds, so it is hardly more secure than an unencrypted connection), WPA, or WPA2.<br />
<br />
When it comes to ease of use, NetworkManager (with GNOME's {{pkg|network-manager-applet}}) and {{ic|wicd}} have good GUI's and can provide a list of available networks to connect, and they prompt for passwords, which is straightforward and highly recommended. WPA Supplicant has also a GUI configuration tool, {{pkg|wpa_supplicant_gui}}.<br />
<br />
{{Note|GNOME's {{pkg|network-manager-applet}} also works under [[Xfce]] if you install {{AUR|xfce4-xfapplet-plugin}} first. {{AUR|xfce4-xfapplet-plugin}} is in the [[Arch User Repository|AUR]], but it is orphaned and may not work. Additionally, there are applets available for [[KDE]].}}<br />
<br />
===Manual setup===<br />
The programs provided by the package {{pkg|wireless_tools}} are the basic set of tools to set up a wireless network. Additionally the {{pkg|iw}} package provides the new tool. Moreover, if you use WPA/WPA2 encryption, you will need the package {{pkg|wpa_supplicant}}. These powerful user-space console tools work extremely well and allow complete, manual control from the shell.<br />
<br />
These examples assume your wireless device is ''wlan0''. Replace ''wlan0'' with the appropriate device name.<br />
{{Note|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 directly try to activate their wireless network from step 3.}}<br />
<br />
====Operating mode====<br />
''(Optional, may be required)'' At this step you may need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an ad-hoc network, you might need to set the operating mode to ''ad-hoc:''<br />
<br />
# iw wlan0 set type ibss<br />
<br />
{{Note|Ideally, you should already know which type of network you are going to connect to. If you do not, scan the network as described in step 2 below, then, if necessary, return back to this step and change the mode. Also, please keep in mind that changing the operating mode might require the wireless interface to be ''down'' ({{ic|ip link set wlan0 down}}).}}<br />
<br />
====Interface activation====<br />
''(Also optional, may be required)'' Some cards require that the kernel interface be activated before you can use the {{ic|wireless_tools}}:<br />
# ip link set wlan0 up<br />
<br />
====Access point discovery====<br />
See what access points are available:<br />
# iw dev wlan0 scan | less<br />
or<br />
$ iwlist wlan0 scanning | less<br />
{{Note|If it displays "''Interface doesn't support scanning''" then you probably forgot to install the firmware. You can also try bringing up the interface first as shown in point 1. In some cases this message is also displayed when not running iw as root. <br />
Also, your wireless network card may be soft-blocked. Try getting {{pkg|rfkill}} and running {{ic|rfkill list all}} to check.}}<br />
<br />
The important points to check:<br />
* ESSID: the "name" of the access point.<br />
* Quality: in general try something above 40/70.<br />
* Encryption key: if it is "on", check if you can see any line regarding<br />
** WEP, WPA, or RSN. Note that RSN and WPA2 are different names for the protocol.<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'll 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). Find more details at [[Wikipedia:List_of_authentication_protocols]] and the sub-articles.<br />
<br />
====Association====<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 />
Assuming you want to use the ESSID {{ic|MyEssid}}:<br />
{{Note|The essid is usually just the name of the network you want to connect to.}}<br />
* '''No encryption'''<br />
# iwconfig wlan0 essid "MyEssid"<br />
Or, alternatively, for the new netlink interface<br />
# iw wlan0 connect MyEssid<br />
* '''WEP'''<br />
using a hexadecimal key:<br />
# iwconfig wlan0 essid "MyEssid" key 1234567890<br />
using an ASCII key:<br />
# iwconfig wlan0 essid "MyEssid" key s:asciikey<br />
* '''WPA/WPA2'''<br />
<br />
You need to edit the {{ic|/etc/wpa_supplicant.conf}} file as described in [[WPA_Supplicant]] and according to what you got from [[#Access point discovery]]. Then, issue this command:<br />
# wpa_supplicant -i wlan0 -c /etc/wpa_supplicant.conf<br />
<br />
This is assuming your device uses the {{ic|wext}} driver. If this does not work, you may need to adjust these options. <br />
If connected successfully, continue in a new terminal (or quit {{ic|wpa_supplicant}} with {{Keypress|Ctrl+c}} and add the {{ic|-B}} switch to the above command to run it in the background). [[WPA_Supplicant]] contains more information and troubleshooting.<br />
<br />
Regardless of the method used, you can check if you have associated successfully as follows:<br />
# iwconfig wlan0<br />
Or, alternatively, for the new netlink interface<br />
# iw dev wlan0 link<br />
<br />
{{Note|In some setups it may still display "Access Point: Not-Associated", continue on to the next step.}}<br />
<br />
====Getting an IP address====<br />
Finally, provide an IP address to the network interface. Simple examples are:<br />
# dhcpcd wlan0<br />
for DHCP, or<br />
# ip addr add 192.168.0.2/24 dev wlan0<br />
# ip route add default via 192.168.0.1<br />
for static IP addressing.<br />
<br />
{{Note|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 />
# iwconfig wlan0 channel auto <br />
Before changing the channel to auto, make sure your wireless interface (in this case, 'wlan0') is '''down'''. After it has successfully changed it, you can again bring the interface up and continue from there.<br />
<br />
{{Note|Although the manual configuration method will help troubleshoot wireless problems, you will have to re-type every command each time you reboot. You can also quickly write a shell script to automate the whole process, which is still a quite convenient way of managing networks while keeping full control over your configuration.}}<br />
<br />
====Manual wireless connection at boot using systemd and dhcpcd====<br />
To have [[systemd]] connect to a manually configured wireless network at boot:<br />
<br />
Create {{ic|/etc/conf.d/network}} to store your interface or static IP settings in:<br />
{{hc|/etc/conf.d/network|<nowiki><br />
interface=wlan0<br />
address=192.168.0.10<br />
netmask=24<br />
broadcast=192.168.0.255<br />
gateway=192.168.0.1<br />
</nowiki>}}<br />
<br />
Create a systemctl unit e.g: {{ic|/etc/systemd/system/network.service}}. This example uses dhcpcd and [[WPA supplicant]].<br />
{{hc|/etc/systemd/system/network.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity<br />
Wants=network.target<br />
Before=network.target<br />
BindsTo=sys-subsystem-net-devices-${interface}.device<br />
After=sys-subsystem-net-devices-${interface}.device<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
EnvironmentFile=/etc/conf.d/network<br />
ExecStart=/sbin/ip link set dev ${interface} up<br />
ExecStart=/usr/sbin/wpa_supplicant -B -i ${interface} -c /etc/wpa_supplicant.conf<br />
ExecStart=/sbin/dhcpcd ${interface}<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Or without {{ic|/etc/conf.d/network}}:<br />
{{hc|/etc/systemd/system/network.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity<br />
Wants=network.target<br />
Before=network.target<br />
BindsTo=sys-subsystem-net-devices-wlan0.device<br />
After=sys-subsystem-net-devices-wlan0.device<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/sbin/ip link set dev wlan0 up<br />
ExecStart=/usr/sbin/wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf<br />
ExecStart=/sbin/dhcpcd wlan0<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Do not forget to enable it!<br />
# systemctl enable network<br />
<br />
To test, reboot or make sure all other network daemons are stopped and then issue as superuser<br />
# systemctl start network<br />
<br />
====Systemd with wpa_supplicant and static IP====<br />
This example configuration uses the new systemd-197 interface naming scheme.<br />
<br />
See http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames<br />
<br />
https://mailman.archlinux.org/pipermail/arch-dev-public/2013-January/024231.html<br />
<br />
Run this script as non-root to find your interface names:<br />
<br />
for i in /sys/class/net/*; do<br />
echo "==$i"<br />
udevadm test-builtin net_id "$i";<br />
echo<br />
done 2>/dev/null<br />
<br />
Create {{ic|/etc/conf.d/network}}<br />
{{hc|/etc/conf.d/network|<nowiki><br />
interface=wlp0s26f7u3<br />
address=192.168.0.10<br />
netmask=24<br />
broadcast=192.168.0.255<br />
gateway=192.168.0.1<br />
</nowiki>}}<br />
<br />
Install {{ic|wpa_supplicant}} and create {{ic|/etc/wpa_supplicant.conf}}. See [[WPA supplicant]]<br />
{{hc|/etc/wpa_supplicant.conf|<nowiki><br />
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=network<br />
update_config=1<br />
network={<br />
ssid="My-Wireless"<br />
psk=b705a6bfcd5639d5c40cd972cd4048cfb94572987f30d324c82036317b91a138<br />
}<br />
</nowiki>}}<br />
<br />
Create a systemd unit file containing the name of the interface: {{ic|/etc/systemd/system/network@wlp0s26f7u3.service}}<br />
{{hc|/etc/systemd/system/network@wlp0s26f7u3.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity (%i)<br />
Wants=network.target<br />
Before=network.target<br />
BindsTo=sys-subsystem-net-devices-%i.device<br />
After=sys-subsystem-net-devices-%i.device<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
EnvironmentFile=/etc/conf.d/network<br />
ExecStart=/usr/sbin/ip link set dev ${interface} up<br />
ExecStart=/usr/sbin/wpa_supplicant -B -i ${interface} -c /etc/wpa_supplicant.conf<br />
ExecStart=/usr/sbin/ip addr add ${address}/${netmask} broadcast ${broadcast} dev ${interface}<br />
ExecStart=/usr/sbin/ip route add default via ${gateway}<br />
ExecStop=/usr/sbin/ip addr flush dev ${interface}<br />
ExecStop=/usr/sbin/ip link set dev ${interface} down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Enable the unit and start it.<br />
# systemctl enable network@wlp0s26f7u3.service<br />
# systemctl start network@wlp0s26f7u3.service<br />
<br />
===Automatic setup===<br />
There are many solutions to choose from, but remember that all of them are mutually exclusive; you should not run two daemons simultaneously.<br />
<br />
====Netcfg====<br />
{{ic|netcfg}} provides a ''versatile, robust and fast'' solution to networking on Arch Linux.<br />
<br />
netcfg uses a profile based setup and is capable of detection and connection to a wide range of network types. This is no harder than using graphical tools.<br />
<br />
See: [[Netcfg]]<br />
<br />
====Wicd====<br />
Wicd is a network manager that can handle both wireless and wired connections. It is written in Python and Gtk with fewer dependencies than NetworkManager, making it an ideal solution for lightweight desktop users. Wicd is available in the [[Official Repositories|official repositories]].<br />
<br />
See: [[Wicd]]<br />
<br />
====NetworkManager====<br />
NetworkManager is an advanced network management tool that is enabled by default in most popular GNU/Linux distributions. In addition to managing wired connections, NetworkManager provides worry-free wireless roaming with an easy-to-use GUI program for selecting your desired network. <br />
<br />
If you do not use [[GNOME]] but use a window manager like [[Openbox]] or [[xmonad]], do not forget to [[pacman|install]] {{Pkg|polkit-gnome}}, {{Pkg|gnome-keyring}}, {{Pkg|libgnome-keyring}}, and {{Pkg|pyxdg}} to manage WEP, WPA, and WPA2 connections.<br />
<br />
See: [[NetworkManager]]<br />
<br />
====WiFi Radar====<br />
WiFi Radar is a Python/PyGTK2 utility for managing wireless profiles (and ''only'' wireless). It enables you to scan for available networks and create profiles for your preferred networks.<br />
<br />
See: [[Wifi Radar]]<br />
<br />
====wlassistant====<br />
wlassistant is a very intuitive and straight-forward GUI application for managing your wireless connections. <br />
<br />
Install the {{AUR|wlassistant}} package from the [[Arch User Repository|AUR]].<br />
<br />
wlassistant must be run with root privileges:<br />
# wlassistant<br />
<br />
{{out of date|References {{ic|/etc/rc.conf}} which is deprecated and does not give clear instructions for configuration outside of {{ic|/etc/rc.conf}}.}}<br />
One method of using wlassistant is to configure your wireless card within {{ic|/etc/rc.conf}}, specifying the access point you use most often. On start-up, your card will automatically be configured for this ESSID, but if other wireless networks are needed/available, {{ic|wlassistant}} can then be invoked to access them. Background the {{ic|network}} daemon in {{ic|/etc/rc.conf}}, by prefixing it with a {{ic|@}} to avoid boot-up delays.<br />
<br />
==Power saving==<br />
<br />
See [[Power_saving#Wireless_power_saving]].<br />
<br />
==See also==<br />
*[[Sharing PPP Connection]]<br />
*[[Ad-hoc networking]]<br />
<br />
==External links==<br />
*[http://www.gnome.org/projects/NetworkManager/ NetworkManager] -- The official website for NetworkManager<br />
*[http://wicd.sourceforge.net/ WICD] -- The official website for WICD<br />
*[http://wifi-radar.berlios.de/ WiFi Radar] -- WiFi Radar information page<br />
*[http://madwifi-project.org/wiki/UserDocs/FirstTimeHowTo The MadWifi project's method of installing] -- Recommended if you are having trouble after reading this article</div>Rozhahttps://wiki.archlinux.org/index.php?title=Ccache&diff=245445Ccache2013-01-29T06:23:37Z<p>Rozha: /* Change the cache directory */</p>
<hr />
<div>[[Category:Package development]]<br />
[[zh-CN:Ccache]]<br />
There's a wonderful tool for {{Ic|gcc}} called {{Ic|ccache}}. You can read about it at their [http://ccache.samba.org home page].<br />
<br />
If you're always compiling the same programs over and over again — such as trying out several kernel patches, or testing your own development — then {{Ic|ccache}} is perfect. While it may take a few seconds longer to compile a program the first time with {{Ic|ccache}}, subsequent compiles will be much, much faster.<br />
<br />
== Installation ==<br />
<br />
[[pacman|Install]] {{pkg|ccache}}, available from the [[official repositories]]<br />
<br />
=== Enable ccache for makepkg ===<br />
To enable ccache when using makepkg edit {{ic|/etc/makepkg.conf}}. In {{Ic|BUILDENV}} remove exclamation mark before ccache and it will enabled. For example:<br />
BUILDENV=(fakeroot !distcc color ccache !xdelta)<br />
<br />
{{Note|If you are compiling for KDE example you have to disable export CPP and export CXX — it prevents from some errors.''}}<br />
<br />
=== Enable for command line ===<br />
If you're compiling your code from the command line, and not building packages, then you'll still want to use {{Ic|ccache}} to help speed things up.<br />
<br />
For that, you need to change your {{Ic|$PATH}} to include {{Ic|ccache}}'s binaries before the path to your compiler.<br />
<br />
export PATH="/usr/lib/ccache/bin/:$PATH"<br />
<br />
You may want to add this line to your {{ic|~/.bashrc}} file for regular usage.<br />
<br />
=== Enable with colorgcc ===<br />
Since colorgcc is also a compiler wrapper, some care needs to be taken to ensure each wrapper is called in the correct sequence.<br />
<br />
export PATH="/usr/lib/colorgcc/bin/:$PATH" # As per usual colorgcc installation, leave unchanged (don't add ccache)<br />
export CCACHE_PATH="/usr/bin" # Tell ccache to only use compilers here<br />
<br />
Then colorgcc needs to be told to call ccache instead of the real compiler. Edit {{ic|/etc/colorgcc/colorgccrc}} and change the {{ic|/usr/bin}} paths to {{ic|/usr/lib/ccache/bin}} for all the compilers in {{ic|/usr/lib/ccache/bin}}:<br />
{{hc|/etc/colorgcc/colorgccrc|g++: /usr/lib/ccache/bin/g++<br />
gcc: /usr/lib/ccache/bin/gcc<br />
c++: /usr/lib/ccache/bin/g++<br />
cc: /usr/lib/ccache/bin/gcc<br />
g77:/usr/bin/g77<br />
f77:/usr/bin/g77<br />
gcj:/usr/bin/gcj}}<br />
<br />
== Misc ==<br />
=== Change the cache directory ===<br />
You may want to move the cache directory to a faster location than the default "~/.ccache" directory, like an SSD or a ramdisk.<br />
<br />
To do change the cache location:<br />
export CCACHE_DIR=/ramdisk/ccache # Tell ccache to use this path to store its cache<br />
<br />
=== CLI ===<br />
You can use the command line utility ccache to...<br />
<br />
Show statistics summary:<br />
$ ccache -s<br />
<br />
Clear the cache completely:<br />
$ ccache -C<br />
<br />
== See also ==<br />
<br />
*[http://ccache.samba.org/ ccache homepage]<br />
*[http://ccache.samba.org/manual.html ccache manual]</div>Rozha