https://wiki.archlinux.org/api.php?action=feedcontributions&user=Kevr&feedformat=atomArchWiki - User contributions [en]2024-03-29T11:52:43ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=PKGBUILD&diff=766149PKGBUILD2023-02-01T23:38:37Z<p>Kevr: Add inlined code example of groups</p>
<hr />
<div>[[Category:Package development]]<br />
[[es:PKGBUILD]]<br />
[[fa:PKGBUILD]]<br />
[[fr:PKGBUILD]]<br />
[[ja:PKGBUILD]]<br />
[[pt:PKGBUILD]]<br />
[[ru:PKGBUILD]]<br />
[[zh-hans:PKGBUILD]]<br />
{{Related articles start}}<br />
{{Related|Arch package guidelines}}<br />
{{Related|Creating packages}}<br />
{{Related|.SRCINFO}}<br />
{{Related|Arch User Repository}}<br />
{{Related|:Category:Package development}}<br />
{{Related|Arch Build System}}<br />
{{Related|makepkg}}<br />
{{Related articles end}}<br />
<br />
This article discusses variables definable by the maintainer in a {{ic|PKGBUILD}}. For information on the {{ic|PKGBUILD}} functions and creating packages in general, refer to [[Creating packages]]. Also read {{man|5|PKGBUILD}}.<br />
<br />
A {{ic|PKGBUILD}} is a shell script containing the build information required by [[Arch Linux]] packages.<br />
<br />
Packages in Arch Linux are built using the [[makepkg]] utility. When ''makepkg'' is run, it searches for a {{ic|PKGBUILD}} file in the current directory and follows the instructions therein to either compile or otherwise acquire the files to build a package archive ({{ic|''pkgname''.pkg.tar.zst}}). The resulting package contains binary files and installation instructions, readily installable with [[pacman]].<br />
<br />
Mandatory variables are {{ic|pkgname}}, {{ic|pkgver}}, {{ic|pkgrel}}, and {{ic|arch}}. {{ic|license}} is not strictly necessary to build a package, but is recommended for any {{ic|PKGBUILD}} shared with others, as ''makepkg'' will produce a warning if not present.<br />
<br />
It is a common practice to define the variables in the {{ic|PKGBUILD}} in the same order as given here. However, this is not mandatory, as long as correct [[Bash]] syntax is used.<br />
<br />
{{Tip|Use [[namcap]] to check {{ic|PKGBUILD}}s for common packaging mistakes.}}<br />
<br />
== Package name ==<br />
<br />
=== pkgbase ===<br />
<br />
When building regular packages, this variable should not be explicitly declared in the {{ic|PKGBUILD}}: its value defaults to that of [[#pkgname]].<br />
<br />
When building a [https://man.archlinux.org/man/PKGBUILD.5#PACKAGE_SPLITTING split package], this variable can be used to explicitly specify the name to be used to refer to the group of packages in the output of ''makepkg'' and in the naming of source-only tarballs. The value is not allowed to begin with a hyphen. If not specified, the value will default to the first element in the {{ic|pkgname}} array.<br />
<br />
All options and directives for split packages default to the global values given in the {{ic|PKGBUILD}}. Nevertheless, the following ones can be overridden within each split package’s packaging function: [[#pkgdesc]], [[#arch]], [[#url]], [[#license]], [[#groups]], [[#depends]], [[#optdepends]], [[#provides]], [[#conflicts]], [[#replaces]], [[#backup]], [[#options]], [[#install]], and [[#changelog]].<br />
<br />
=== pkgname ===<br />
<br />
Either the name of the package, e.g. {{ic|1=pkgname='foo'}}, or, for split packages, an array of names, e.g. {{ic|1=pkgname=('foo' 'bar')}}. Package names should only consist of lowercase alphanumerics and the following characters: {{ic|@._+-}} (at symbol, dot, underscore, plus, hyphen). Names are not allowed to start with hyphens or dots. For the sake of consistency, {{ic|pkgname}} should match the name of the source tarball of the software: for instance, if the software is in {{ic|foobar-2.5.tar.gz}}, use {{ic|1=pkgname=foobar}}.<br />
<br />
== Version ==<br />
<br />
=== pkgver ===<br />
<br />
The version of the package. This should be the same as the version published by the author of the upstream software. It can contain letters, numbers, periods and underscores, but '''not''' a hyphen ({{ic|-}}). If the author of the software uses one, replace it with an underscore ({{ic|_}}). If the {{ic|pkgver}} variable is used later in the {{ic|PKGBUILD}}, then the underscore can easily be substituted for a hyphen, e.g. {{ic|1=source=("$pkgname-${pkgver//_/-}.tar.gz")}}.<br />
<br />
{{Note|If upstream uses a timestamp versioning such as {{ic|30102014}}, ensure to use the reversed date, i.e. {{ic|20141030}} ([[Wikipedia:ISO 8601|ISO 8601]] format). Otherwise it will not appear as a newer version.}}<br />
<br />
{{Tip|<br />
* The ordering of uncommon values can be tested with {{man|8|vercmp}}, which is provided by the [[pacman]] package.<br />
* [[makepkg]] can automatically [http://allanmcrae.com/2013/04/pacman-4-1-released/ update] this variable by defining a {{ic|pkgver()}} function in the {{ic|PKGBUILD}}. See [[VCS package guidelines#The pkgver() function]] for details.<br />
}}<br />
<br />
=== pkgrel ===<br />
<br />
The release number. This is usually a positive integer number that allows to differentiate between consecutive builds of the same version of a package. As fixes and additional features are added to the {{ic|PKGBUILD}} that influence the resulting package, the {{ic|pkgrel}} should be incremented by 1. When a new version of the software is released, this value must be reset to 1. In exceptional cases other formats can be found in use, such as ''major.minor''.<br />
<br />
=== epoch ===<br />
<br />
{{Warning|{{ic|epoch}} should only be used when absolutely required to do so.}}<br />
<br />
Used to force the package to be seen as newer than any previous version with a lower epoch. This value is required to be a non-negative integer; the default is 0. It is used when the version numbering scheme of a package changes (or is alphanumeric), breaking normal version comparison logic. For example:<br />
<br />
{{hc|1=<br />
pkgver=5.13<br />
pkgrel=2<br />
epoch=1<br />
|2=<br />
1:5.13-2<br />
}}<br />
<br />
See {{man|8|pacman}} for more information on version comparisons.<br />
<br />
== Generic ==<br />
<br />
=== pkgdesc ===<br />
<br />
The description of the package. This is recommended to be 80 characters or less and should not include the package name in a self-referencing way, unless the application name differs from the package name. For example, use {{ic|1=pkgdesc="Text editor for X11"}} instead of {{ic|1=pkgdesc="Nedit is a text editor for X11"}}.<br />
<br />
Also it is important to use keywords wisely to increase the chances of appearing in relevant search queries.<br />
<br />
=== arch ===<br />
<br />
An array of architectures that the {{ic|PKGBUILD}} is intended to build and work on. Arch officially supports only {{ic|x86_64}}, but other projects may support other architectures. For example, [https://archlinux32.org/ Arch Linux 32] provides support for {{ic|i686}} and {{ic|pentium4}} and [https://archlinuxarm.org/ Arch Linux ARM] provides support for {{ic|armv7h}} (armv7 hardfloat) and {{ic|aarch64}} (armv8 64-bit).<br />
<br />
There are two types of values the array can use:<br />
<br />
* {{ic|1=arch=('any')}} indicates the package can be built once on any architecture, and once built, is architecture-independent in its compiled state (shell scripts, fonts, themes, many types of extensions, etc.).<br />
* {{ic|1=arch=('x86_64')}} with one or more architectures indicates the package can be compiled for any of the specified architectures, but is architecture-specific once compiled. For these packages, specify all architectures that the {{ic|PKGBUILD}} officially supports. For official repository and AUR packages, this means ''x86_64''. Optionally, AUR packages may choose to additionally support other known working architectures.<br />
<br />
The target architecture can be accessed with the variable {{ic|$CARCH}} during a build.<br />
<br />
=== url ===<br />
<br />
The URL of the official site of the software being packaged.<br />
<br />
=== license ===<br />
<br />
The license under which the software is distributed. The {{Pkg|licenses}} package (a dependency of the {{Pkg|base}} [[meta package]]) contains many commonly used licenses, which are installed under {{ic|/usr/share/licenses/common/}}. If a package is licensed under one of these licenses, the value should be set to the directory name, e.g. {{ic|1=license=('GPL')}}. If the appropriate license is not included, several things must be done:<br />
<br />
# Add {{ic|custom}} to the {{ic|license}} array. Optionally, you can replace {{ic|custom}} with {{ic|custom:''name of license''}}. Once a license is used in two or more packages in an official repository (including [[community repository|community]]), it becomes a part of the {{Pkg|licenses}} package.<br />
# Install the license in: {{ic|/usr/share/licenses/''pkgname''/}}, e.g. {{ic|/usr/share/licenses/foobar/LICENSE}}. One good way to do this is by using: {{bc|install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"}}<br />
# If the license is only found in a website, then you need to separately include it in the package.<br />
<br />
* The [[Wikipedia:BSD License|BSD]], [[Wikipedia:ISC license|ISC]], [[Wikipedia:MIT License|MIT]], [[Wikipedia:ZLIB license|zlib/png]], [[Wikipedia:Python License|Python]] and [[Wikipedia:SIL Open Font License|OFL]] licenses are special cases and could not be included in the {{Pkg|licenses}} package, due to them including copyright notices [https://lists.archlinux.org/archives/list/arch-general@lists.archlinux.org/message/OWAOXTOS4IVO5VHFFNRJ7AQP4VKKOBTK/]. For the sake of the {{ic|license}} array, it is treated as a common license ({{ic|1=license=('BSD')}}, {{ic|1=license=('ISC')}}, {{ic|1=license=('MIT')}}, {{ic|1=license=('ZLIB')}}, {{ic|1=license=('Python')}}, and {{ic|1=license=('OFL')}}), but technically each one is a custom license, because each one has its own copyright line. Any package licensed under these five should have its own unique license file stored in {{ic|/usr/share/licenses/''pkgname''/}}.<br />
* Some packages may not be covered by a single license. In these cases, multiple entries may be made in the {{ic|license}} array, e.g. {{ic|1=license=('GPL' 'custom:''name of license''')}}.<br />
* (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:<br />
** (L)GPL — (L)GPLv2 or any later version<br />
** (L)GPL2 — (L)GPL2 only<br />
** (L)GPL3 — (L)GPL3 or any later version<br />
* If after researching the issue no license can be determined, [https://gitlab.archlinux.org/pacman/pacman/blob/master/proto/PKGBUILD.proto PKGBUILD.proto] suggests using {{ic|unknown}}. However, upstream should be contacted about the conditions under which the software is (and is not) available.<br />
<br />
{{Tip|Some software authors do not provide separate license file and describe distribution rules in section of common {{ic|ReadMe.txt}}. This information can be extracted to a separate file during {{ic|build()}} with something like {{ic|sed -n '/'''This software'''/,/''' thereof.'''/p' ReadMe.txt > LICENSE}}}}<br />
<br />
See also [[Nonfree applications package guidelines]].<br />
<br />
Additional information and perspectives on free and open source software licenses may be found on the following pages:<br />
<br />
* [[Wikipedia:Free software licence]]<br />
* [[Wikipedia:Comparison of free and open-source software licenses]]<br />
* [https://www.softwarefreedom.org/resources/2008/foss-primer.html A Legal Issues Primer for Open Source and Free Software Projects]<br />
* [https://www.gnu.org/licenses/license-list.html GNU Project - Various Licenses and Comments about Them]<br />
* [https://www.debian.org/legal/licenses/ Debian - License information]<br />
* [https://www.opensource.org/licenses/alphabetical Open Source Initiative - Licenses by Name]<br />
<br />
=== groups ===<br />
<br />
The [[Package group|group]] the package belongs in. For instance, when installing {{Grp|plasma}}, it installs all packages belonging in that group.<br />
<br />
[[PKGBUILD]] groups can be set using the {{ic|groups}} variable: {{ic|groups{{=}}('group-name')}}<br />
<br />
== Dependencies ==<br />
<br />
{{Note|Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=optdepends_x86_64=()}}.}}<br />
<br />
=== depends ===<br />
<br />
An array of packages that must be installed for the software to build '''and''' run. Dependencies defined inside the {{ic|package()}} function are only required to run the software.<br />
<br />
Version restrictions can be specified with comparison operators, e.g. {{ic|1=depends=('foobar>=1.8.0')}}; if multiple restrictions are needed, the dependency can be repeated for each, e.g. {{ic|1=depends=('foobar>=1.8.0' 'foobar<2.0.0')}}.<br />
<br />
{{Merge|Arch package guidelines|The PKGBUILD format does not enforce a packaging policy.}}<br />
<br />
The {{ic|depends}} array should list all direct first level dependencies even when some are already declared transitively. For instance, if a package ''foo'' depends on both ''bar'' and ''baz'', and the ''bar'' package depends in turn on ''baz'' too, it will ultimately lead to undesired behavior if ''bar'' stops pulling in ''baz''. Pacman will not enforce the installation of ''baz'' on systems which newly install the ''foo'' package, or have cleaned up orphans, and ''foo'' will crash at runtime or otherwise misbehave.<br />
<br />
In some cases this is not necessary and may or may not be listed, for example {{Pkg|glibc}} cannot be uninstalled as every system needs some C library, or {{Pkg|python}} for a package that already depends on another ''python-'' module, as the second module must per definition depend on ''python'' and cannot ever stop pulling it in as a dependency.<br />
<br />
Dependencies should normally include the requirements for building all optional features of a package. Alternatively, any feature whose dependencies are not included should be explicitly disabled via a configure option. Failure to do this can lead to packages with "[[Gentoo:Project:Quality Assurance/Automagic dependencies|automagic dependencies]]" build-time optional features that are unpredictably enabled due to transitive dependencies or unrelated software installed on the build machine, but which are not reflected in the package dependencies.<br />
<br />
If the dependency name appears to be a library, e.g. {{ic|1=depends=('libfoobar.so')}}, ''makepkg'' will try to find a binary that depends on the library in the built package and append the [[Wikipedia:soname|soname]] version needed by the binary. Appending the version yourself disables automatic detection, e.g. {{ic|1=depends=('libfoobar.so=2')}}.<br />
<br />
=== makedepends ===<br />
<br />
An array of packages that are '''only''' required to build the package. The minimum dependency version can be specified in the same format as in the {{ic|depends}} array. The packages in the {{ic|depends}} array are implicitly required to build the package, they should not be duplicated here.<br />
<br />
{{Tip|The following can be used to check whether a particular package is either in the {{Grp|base-devel}} group or is pulled in by a member of the group:<br />
<br />
{{bc|1=$ LC_ALL=C pacman -Si $(pactree -rl ''package'') 2>/dev/null {{!}} grep -q "^Groups *:.*base-devel"}}<br />
}}<br />
<br />
{{Note|The group {{Grp|base-devel}} is assumed to be already installed when building with ''makepkg''. Members of this group '''should not''' be included in {{ic|makedepends}} array.}}<br />
<br />
=== checkdepends ===<br />
<br />
An array of packages that the software depends on to run its test suite, but are not needed at runtime. Packages in this list follow the same format as {{ic|depends}}. These dependencies are only considered when the [[Creating packages#check()|check()]] function is present and is to be run by ''makepkg''.<br />
<br />
{{Note|The group {{Grp|base-devel}} is assumed to be already installed when building with ''makepkg''. Members of this group '''should not''' be included in {{ic|checkdepends}} array.}}<br />
<br />
=== optdepends ===<br />
<br />
An array of packages that are not needed for the software to function, but provide additional features. This may imply that not all executables provided by a package will function without the respective optdepends.[https://lists.archlinux.org/archives/list/arch-general@lists.archlinux.org/message/ZFBCD2NFFBSOZBI22AYZYHH2PDRCLJWF/] If the software works on multiple alternative dependencies, all of them can be listed here, instead of the {{ic|depends}} array.<br />
<br />
A short description of the extra functionality each optdepend provides should also be noted:<br />
<br />
optdepends=('cups: printing support'<br />
'sane: scanners support'<br />
'libgphoto2: digital cameras support'<br />
'alsa-lib: sound support'<br />
'giflib: GIF images support'<br />
'libjpeg: JPEG images support'<br />
'libpng: PNG images support')<br />
<br />
== Package relations ==<br />
<br />
{{Note|Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=conflicts_x86_64=()}}.}}<br />
<br />
=== provides ===<br />
<br />
An array of additional packages that the software provides the features of (or a virtual package such as {{ic|cron}} or {{ic|sh}}). Packages providing the same item can be installed side-by-side, unless at least one of them uses a {{ic|conflicts}} array.<br />
<br />
{{Note|The version that the package provides should be mentioned ({{ic|pkgver}} and potentially the {{ic|pkgrel}}), in case packages referencing the software require one. For instance, a modified ''qt'' package version 3.3.8, named ''qt-foobar'', should use {{ic|1=provides=('qt=3.3.8')}}; omitting the version number would cause the dependencies that require a specific version of ''qt'' to fail. Do not add {{ic|pkgname}} to the {{ic|provides}} array, as it is done automatically.}}<br />
<br />
=== conflicts ===<br />
<br />
An array of packages that conflict with, or cause problems with the package, if installed. All these packages and packages providing this item will need to be removed. The version properties of the conflicting packages can also be specified in the same format as the {{ic|depends}} array.<br />
<br />
Note that conflicts are checked against {{ic|pkgname}} as well as names specified in the {{ic|provides}} array. Hence, if your package {{ic|provides}} a {{ic|''foo''}} feature, specifying {{ic|''foo''}} in the {{ic|conflicts}} array will cause a conflict between your package and all other packages that contain {{ic|''foo''}} in their {{ic|provides}} array (i.e., you do not need to specify all those conflicting package names in your {{ic|conflicts}} array). Let us take a concrete example:<br />
<br />
* {{Pkg|netbeans}} implicitly provides {{ic|netbeans}} as the {{ic|pkgname}} itself<br />
* {{AUR|netbeans-cpp}} provides {{ic|netbeans}} and conflicts with {{ic|netbeans}}<br />
* {{AUR|netbeans-php}} provides {{ic|netbeans}} and conflicts with {{ic|netbeans}}, but does not need to explicitly conflict with {{AUR|netbeans-cpp}} since packages providing the same feature are implicitly in conflict.<br />
<br />
When packages provide the same feature via the {{ic|provides}} array, there is a difference between explicitly adding the alternative package to the {{ic|conflicts}} array and not adding it. If the {{ic|conflicts}} array is explicitly declared the two packages providing the same feature will be considered as ''alternative''; if the {{ic|conflicts}} array is missing the two packages providing the same feature will be considered as ''possibly cohabiting''. Packagers should always ignore the content of the {{ic|provides}} variable in deciding whether to declare a {{ic|conflicts}} variable or not.<br />
<br />
=== replaces ===<br />
<br />
An array of obsolete packages that are replaced by the package, e.g. {{Pkg|wireshark-qt}} uses {{ic|1=replaces=('wireshark')}}. When syncing, ''pacman'' will immediately replace an installed package upon encountering another package with the matching {{ic|replaces}} in the repositories. If providing an alternate version of an already existing package or uploading to the AUR, use the {{ic|conflicts}} and {{ic|provides}} arrays, which are only evaluated when actually installing the conflicting package.<br />
<br />
== Others ==<br />
<br />
=== backup ===<br />
<br />
An array of files that can contain user-made changes and should be preserved during upgrade or removal of a package, primarily intended for configuration files in {{ic|/etc}}.<br />
<br />
Files in this array should use '''relative''' paths without the leading slash ({{ic|/}}) (e.g. {{ic|etc/pacman.conf}}, instead of {{ic|/etc/pacman.conf}}).<br />
<br />
When updating, new versions may be saved as {{ic|''file''.pacnew}} to avoid overwriting a file which already exists and was previously modified by the user. Similarly, when the package is removed, user-modified files will be preserved as {{ic|''file''.pacsave}} unless the package was removed with the {{ic|pacman -Rn}} command.<br />
<br />
See also [[Pacnew and Pacsave files]].<br />
<br />
=== options ===<br />
<br />
This array allows overriding some of the default behavior of ''makepkg'', defined in {{ic|/etc/makepkg.conf}}. To set an option, include the name in the array. To disable an option, place an '''{{ic|!}}''' before it.<br />
<br />
The full list of the available options can be found in {{man|5|PKGBUILD}}.<br />
<br />
=== install ===<br />
<br />
The name of the ''.install'' script to be included in the package.<br />
<br />
''pacman'' has the ability to store and execute a package-specific script when it installs, removes or upgrades a package. The script contains the following functions which run at different times:<br />
<br />
* {{ic|pre_install}} — The script is run right before files are extracted. One argument is passed: new package version.<br />
* {{ic|post_install}} — The script is run right after files are extracted. One argument is passed: new package version.<br />
* {{ic|pre_upgrade}} — The script is run right before files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
* {{ic|post_upgrade}} — The script is run right after files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
* {{ic|pre_remove}} — The script is run right before files are removed. One argument is passed: old package version.<br />
* {{ic|post_remove}} — The script is run right after files are removed. One argument is passed: old package version.<br />
<br />
Each function is run [[chroot]]ed inside the ''pacman'' install directory. See [https://bbs.archlinux.org/viewtopic.php?pid=913891 this thread].<br />
<br />
{{Tip|<br />
* A prototype ''.install'' is provided at [https://gitlab.archlinux.org/pacman/pacman/raw/master/proto/proto.install /usr/share/pacman/proto.install].<br />
* [[pacman#Hooks]] provide similar functionality.<br />
}}<br />
<br />
{{Note|Do not end the script with {{ic|exit}}. This would prevent the contained functions from executing.}}<br />
<br />
=== changelog ===<br />
<br />
The name of the package changelog. To view changelogs for installed packages (that have this file):<br />
<br />
$ pacman -Qc ''pkgname''<br />
<br />
== Sources ==<br />
<br />
=== source ===<br />
<br />
An array of files needed to build the package. It must contain the location of the software source, which in most cases is a full HTTP or FTP URL. The previously set variables {{ic|pkgname}} and {{ic|pkgver}} can be used effectively here; e.g. {{ic|<nowiki>source=("https://example.com/$pkgname-$pkgver.tar.gz")</nowiki>}}.<br />
<br />
Files can also be supplied in the same directory where the {{ic|PKGBUILD}} is located, and their names added to this array. Before the actual build process starts, all the files referenced in this array will be downloaded or checked for existence, and ''makepkg'' will not proceed if any is missing.<br />
<br />
''.install'' files are recognized automatically by ''makepkg'' and should not be included in the {{ic|source}} array. Files in the {{ic|source}} array with extensions ''.sig'', ''.sign'', or ''.asc'' are recognized by ''makepkg'' as PGP signatures and will be automatically used to verify the integrity of the corresponding source file.<br />
<br />
{{Warning|The downloaded source filename must be unique because the [[makepkg#Package output|SRCDEST]] directory can be the same for all packages. For instance, using the version number of the project as a filename potentially conflicts with other projects with the same version number. In this case, the alternative unique filename to be used is provided with the syntax {{ic|1=source=('<nowiki/>''unique_package_name'''''::'''''file_uri''<nowiki/>')}}; e.g. {{ic|<nowiki>source=("$pkgname-$pkgver.tar.gz::https://github.com/coder/program/archive/v$pkgver.tar.gz")</nowiki>}}.<br />
}}<br />
<br />
{{Tip|<br />
* Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=source_x86_64=()}}. There must be a corresponding integrity array with checksums, e.g. {{ic|1=sha256sums_x86_64=()}}.<br />
* Some servers restrict download by filtering the ''User-Agent'' string of the client or other types of restrictions, which can be circumvented with [[Nonfree applications package guidelines#Custom DLAGENTS|DLAGENTS]].<br />
* You can use {{ic|file://}} URL to point to a directory or a file in your computer filesystem. For example, a local Git repository can be specified as {{ic|"$pkgname"::"git+file://''/path/to/repository''"}}.<br />
* Magnet link support can be added using {{AUR|transmission-dlagent}} as {{ic|DLAGENT}} and using the {{ic|<nowiki>magnet://</nowiki>}} uri prefix instead of the canonical {{ic|magnet:?}}.<br />
* See {{man|5|PKGBUILD|USING VCS SOURCES}} and [[VCS package guidelines#VCS sources]] for details on VCS specific options, such as targeting a specific Git branch or commit.<br />
}}<br />
<br />
=== noextract ===<br />
<br />
An array of files listed under {{ic|source}}, which should not be extracted from their archive format by [[makepkg]]. This can be used with archives that cannot be handled by {{ic|/usr/bin/bsdtar}} or those that need to be installed as-is. If an alternative unarchiving tool is used (e.g. {{Pkg|lrzip}}), it should be added in the {{ic|makedepends}} array and the first line of the [[Creating packages#prepare()|prepare()]] function should extract the source archive manually; for example:<br />
<br />
prepare() {<br />
lrzip -d ''source''.tar.lrz<br />
}<br />
<br />
Note that while the {{ic|source}} array accepts URLs, {{ic|noextract}} is '''just''' the file name portion:<br />
<br />
<nowiki>source=("http://foo.org/bar/foobar.tar.xz")</nowiki><br />
noextract=('foobar.tar.xz')<br />
<br />
To extract ''nothing'', you can do something like this:<br />
<br />
* If {{ic|source}} contains only plain URLs without custom file names, strip the {{ic|source}} array before the last slash:<br />
: {{bc|1=noextract=("${source[@]##*/}")}}<br />
* If {{ic|source}} contains only entries with custom file names, strip the {{ic|source}} array after the {{ic|::}} separator (taken from [https://github.com/archlinux/svntogit-packages/blob/packages/firefox-i18n/trunk/PKGBUILD#L123 firefox-i18n's PKGBUILD]):<br />
: {{bc|1=noextract=("${source[@]%%::*}")}}<br />
<br />
=== validpgpkeys ===<br />
<br />
An array of PGP fingerprints. If used, ''makepkg'' will only accept signatures from the keys listed here and will ignore the trust values from the keyring. If the source file was signed with a subkey, ''makepkg'' will still use the primary key for comparison.<br />
<br />
Only full fingerprints are accepted. They must be uppercase and must not contain whitespace characters.<br />
<br />
{{Note|You can use {{ic|gpg --list-keys --fingerprint ''KEYID''}} to find out the fingerprint of the appropriate key.}}<br />
<br />
Please read [[makepkg#Signature checking]] for more information.<br />
<br />
== Integrity ==<br />
<br />
These variables are arrays whose items are checksum strings that will be used to verify the integrity of the respective files in the [[#source|source]] array. You can also insert {{ic|SKIP}} for a particular file, and its checksum will not be tested.<br />
<br />
The checksum type and values should always be those provided by upstream, such as in release announcements. When multiple types are available, the strongest checksum is to be preferred: {{ic|b2}} over {{ic|sha512}}, {{ic|sha512}} over {{ic|sha384}}, {{ic|sha384}} over {{ic|sha256}}, {{ic|sha256}} over {{ic|sha224}}, {{ic|sha224}} over {{ic|sha1}}, {{ic|sha1}} over {{ic|md5}}, and {{ic|md5}} over {{ic|ck}}. This best ensures the integrity of the downloaded files, from upstream's announcement to package building.<br />
<br />
{{Note|Additionally, when upstream makes [[Wikipedia:Digital signature|digital signatures]] available, the signature files should be added to the [[#source|source]] array and the PGP key fingerprint to the [[#validpgpkeys|validpgpkeys]] array. This allows authentication of the files at build time.}}<br />
<br />
The values for these variables can be auto-generated by [[makepkg]]'s {{ic|-g}}/{{ic|--geninteg}} option, then commonly appended with {{ic|makepkg -g >> PKGBUILD}}. The {{man|8|updpkgsums}} command from {{Pkg|pacman-contrib}} is able to update the variables wherever they are in the {{ic|PKGBUILD}}. Both tools will use the variable that is already set in the {{ic|PKGBUILD}}, or fall back to {{ic|md5sums}} if none is set.<br />
<br />
The file integrity checks to use can be set up with the {{ic|INTEGRITY_CHECK}} option in {{ic|/etc/makepkg.conf}}. See {{man|5|makepkg.conf}}.<br />
<br />
{{Note|Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=sha256sums_x86_64=()}}.}}<br />
<br />
=== cksums ===<br />
<br />
An array [[Wikipedia:Cyclic redundancy check|CRC32]] checksums (from UNIX-standard [[Wikipedia:cksum|cksum]]) of the files listed in the {{ic|source}} array.<br />
<br />
=== md5sums ===<br />
<br />
An array of 128-bit [[Wikipedia:MD5|MD5]] checksums of the files listed in the {{ic|source}} array.<br />
<br />
=== sha1sums ===<br />
<br />
An array of 160-bit [[Wikipedia:SHA-1|SHA-1]] checksums of the files listed in the {{ic|source}} array.<br />
<br />
=== sha256sums ===<br />
<br />
An array of [[Wikipedia:SHA-2|SHA-2]] checksums with digest size of 256 bits.<br />
<br />
=== sha224sums, sha384sums, sha512sums ===<br />
<br />
An array of SHA-2 checksums with digest sizes 224, 384, and 512 bits, respectively. These are less common alternatives to {{ic|sha256sums}}.<br />
<br />
=== b2sums ===<br />
<br />
An array of [[Wikipedia:BLAKE (hash function)#BLAKE2|BLAKE2]] checksums with digest size of 512 bits.<br />
<br />
== See also ==<br />
<br />
* {{man|5|PKGBUILD}} manual page<br />
* [https://gitlab.archlinux.org/pacman/pacman/raw/master/proto/PKGBUILD.proto Example PKGBUILD file]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Arch_User_Repository&diff=719266Arch User Repository2022-02-19T01:46:30Z<p>Kevr: Added some details about account suspension and inactivity</p>
<hr />
<div>[[Category:About Arch]]<br />
[[Category:Package development]]<br />
[[Category:Package management]]<br />
[[de:Arch User Repository]]<br />
[[es:Arch User Repository]]<br />
[[fr:Arch User Repository]]<br />
[[ja:Arch User Repository]]<br />
[[pl:Arch User Repository]]<br />
[[pt:Arch User Repository]]<br />
[[ru:Arch User Repository]]<br />
[[zh-hans:Arch User Repository]]<br />
{{Related articles start}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related|PKGBUILD}}<br />
{{Related|.SRCINFO}}<br />
{{Related|Aurweb RPC interface}}<br />
{{Related|AUR submission guidelines}}<br />
{{Related|AUR Trusted User Guidelines}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related|Creating packages}}<br />
{{Related|AUR helpers}}<br />
{{Related|AUR Cleanup Day}}<br />
{{Related articles end}}<br />
<br />
The Arch User Repository (AUR) is a community-driven repository for Arch users. It contains package descriptions ([[PKGBUILD]]s) that allow you to compile a package from source with [[makepkg]] and then install it via [[pacman#Additional commands|pacman]]. The AUR was created to organize and share new packages from the community and to help expedite popular packages' inclusion into the [[community repository]]. This document explains how users can access and utilize the AUR.<br />
<br />
A good number of new packages that enter the official repositories start in the AUR. In the AUR, users are able to contribute their own package builds ({{ic|PKGBUILD}} and related files). The AUR community has the ability to vote for packages in the AUR. If a package becomes popular enough &mdash; provided it has a compatible license and good packaging technique &mdash; it may be entered into the ''community'' repository (directly accessible by ''pacman'' or [[abs]]).<br />
<br />
{{Warning|AUR packages are user-produced content. These {{ic|PKGBUILD}}s are completely unofficial and have not been thoroughly vetted. Any use of the provided files is at your own risk.}}<br />
<br />
== Getting started ==<br />
<br />
Users can search and download [[PKGBUILD]]s from the [https://aur.archlinux.org AUR Web Interface]. These {{ic|PKGBUILD}}s can be built into installable packages using ''makepkg'', then installed using ''pacman''.<br />
<br />
* Ensure the {{Grp|base-devel}} package group is installed in full ({{ic|pacman -S --needed base-devel}}).<br />
* Glance over the [[#FAQ]] for answers to the most common questions.<br />
* You may wish to adjust {{ic|/etc/makepkg.conf}} to optimize the build process to your system prior to building packages from the AUR. A significant improvement in package build times can be realized on systems with multi-core processors by adjusting the {{ic|MAKEFLAGS}} variable, by using multiple cores for compression, or by using different compression algorithm. Users can also enable hardware-specific compiler optimizations via the {{ic|CFLAGS}} variable. See [[makepkg#Tips and tricks]] for more information.<br />
<br />
It is also possible to interact with the AUR through SSH: type {{ic|ssh aur@aur.archlinux.org help}} for a list of available commands.<br />
<br />
== History ==<br />
<br />
In the beginning, there was {{ic|<nowiki>ftp://ftp.archlinux.org/incoming</nowiki>}}, and people contributed by simply uploading the [[PKGBUILD]], the needed supplementary files, and the built package itself to the server. The package and associated files remained there until a [[Package Maintainer]] saw the program and adopted it.<br />
<br />
Then the Trusted User Repositories were born. Certain individuals in the community were allowed to host their own repositories for anyone to use. The AUR expanded on this basis, with the aim of making it both more flexible and more usable. In fact, the AUR maintainers are still referred to as TUs (Trusted Users).<br />
<br />
Between 2015-06-08 and 2015-08-08 the AUR transitioned from version 3.5.1 to 4.0.0, introducing the use of Git repositories for publishing the {{ic|PKGBUILD}}s.<br />
Existing packages were dropped unless manually migrated to the new infrastructure by their maintainers.<br />
<br />
=== Git repositories for AUR3 packages ===<br />
<br />
The [https://github.com/aur-archive AUR Archive] on GitHub has a repository for every package that was in AUR 3 at the time of the migration.<br />
Alternatively, there is the [https://github.com/felixonmars/aur3-mirror/ aur3-mirror] repository which provides the same.<br />
<br />
== Installing and upgrading packages ==<br />
<br />
Installing packages from the AUR is a relatively simple process. Essentially:<br />
<br />
# Acquire the build files, including the [[PKGBUILD]] and possibly other required files, like [[systemd]] units and patches (often not the actual code).<br />
# Verify that the {{ic|PKGBUILD}} and accompanying files are not malicious or untrustworthy.<br />
# Run {{ic|makepkg}} in the directory where the files are saved. This will download the code, compile it, and package it.<br />
# Run {{ic|pacman -U ''package_file''}} to install the package onto your system.<br />
<br />
{{Note|The AUR is unsupported, so any packages you install are ''your responsibility'' to update, not pacman's. If packages in the official repositories are updated, you will need to rebuild any AUR packages that depend on those libraries.}}<br />
<br />
=== Prerequisites ===<br />
<br />
First ensure that the necessary tools are installed by [[install]]ing the {{grp|base-devel}} group in full which includes {{pkg|make}} and other tools needed for compiling from source.<br />
<br />
{{Tip|Use the {{ic|--needed}} flag when installing the {{grp|base-devel}} group to skip packages you already have instead of reinstalling them.}}<br />
<br />
{{Note|Packages in the AUR assume that the {{grp|base-devel}} group is installed, i.e. they do not list the group's members as build dependencies explicitly.}}<br />
<br />
Next choose an appropriate build directory. A build directory is simply a directory where the package will be made or "built" and can be any directory. The examples in the following sections will use {{ic|~/builds}} as the build directory.<br />
<br />
=== Acquire build files ===<br />
<br />
Locate the package in the AUR. This is done using the search field at the top of the [https://aur.archlinux.org/ AUR home page]. Clicking the application's name in the search list brings up an information page on the package. Read through the description to confirm that this is the desired package, note when the package was last updated, and read any comments.<br />
<br />
There are several methods for acquiring the build files for a package:<br />
<br />
* Clone its [[git]] repository, labeled "Git Clone URL" in the "Package Details" on its AUR page. This is the preferred method, an advantage of which is that you can easily get updates to the package via {{ic|git pull}}.<br />
:{{bc|$ git clone <nowiki>https://aur.archlinux.org/</nowiki>''package_name''.git}}<br />
* Download a snapshot, either by clicking the "Download snapshot" link under "Package Actions" on the right hand side of its AUR page, or in a terminal: <br />
:{{bc|$ curl -L -O <nowiki>https://aur.archlinux.org/cgit/aur.git/snapshot/</nowiki>''package_name''.tar.gz}}<br />
:{{Note|The snapshot file is compressed, and must be extracted (preferably in a directory set aside for AUR builds): {{ic|tar -xvf ''package_name''.tar.gz}}}}<br />
<br />
=== Acquire a PGP public key if needed ===<br />
<br />
Check if a signature file in the form of ''.sig'' or ''.asc'' is part of the [[PKGBUILD]] source array, if that is the case, then acquire one of the public keys listed in the PKGBUILD [[PKGBUILD#validpgpkeys|validpgpkeys]] array. Refer to [[makepkg#Signature checking]] for more information.<br />
<br />
=== Build the package ===<br />
<br />
Change directories to the directory containing the package's [[PKGBUILD]].<br />
<br />
$ cd ''package_name''<br />
<br />
{{Warning|Carefully check the {{ic|PKGBUILD}}, any ''.install'' files, and any other files in the package's git repository for malicious or dangerous commands. If in doubt, do not build the package, and [[General_troubleshooting#Additional_support|seek advice]] on the forums or mailing list. Malicious code has been found in packages before. [https://lists.archlinux.org/pipermail/aur-general/2018-July/034151.html]}}<br />
<br />
View the contents of all provided files. For example, to use the pager ''less'' to view {{ic|PKGBUILD}} do:<br />
<br />
$ less PKGBUILD<br />
<br />
{{Tip|If you are updating a package, you may want to look at the changes since the last commit.<br />
* To view changes since the last git commit you can use {{ic|git show}}.<br />
* To view changes since the last commit using ''vimdiff'', do {{ic|git difftool @~..@ vimdiff}}. The advantage of ''vimdiff'' is that you view the entire contents of each file along with indicators on what has changed.}}<br />
<br />
Make the package. After manually confirming the contents of the files, run [[makepkg]] as a normal user. Some helpful flags:<br />
<br />
* {{ic|-s}}/{{ic|--syncdeps}} automatically resolves and installs any dependencies with [[pacman]] before building. If the package depends on other AUR packages, you will need to manually install them first.<br />
* {{ic|-i}}/{{ic|--install}} installs the package if it is built successfully. This lets you skip the next step that is usually done manually.<br />
* {{ic|-r}}/{{ic|--rmdeps}} removes build-time dependencies after the build, as they are no longer needed. However these dependencies may need to be reinstalled the next time the package is updated.<br />
* {{ic|-c}}/{{ic|--clean}} cleans up temporary build files after the build, as they are no longer needed. These files are usually needed only when debugging the build process.<br />
<br />
{{Tip|Use {{ic| git clean -dfX}} to delete all files that are ignored by git, thus deleting all previously built package files.}}<br />
<br />
=== Install the package ===<br />
<br />
The package can now be installed with pacman:<br />
<br />
# pacman -U ''package_name''-''version''-''architecture''.pkg.tar.zst<br />
<br />
{{Note|<br />
* If you have changed your {{ic|PKGEXT}} in {{ic|makepkg.conf}}, the name of the package file may be slightly different.<br />
* The above example is only a brief summary of the build process. It is '''highly''' recommended to read the [[makepkg]] and [[ABS]] articles for more details.<br />
}}<br />
<br />
=== Upgrading packages ===<br />
<br />
In the directory containing the package's [[PKGBUILD]] you must first update the files and changes by using the command <br />
<br />
$ git pull<br />
<br />
then follow the previous build and install instructions.<br />
<br />
== Account Status ==<br />
<br />
=== Suspension ===<br />
<br />
When editing a user as a Trusted User, users can set the Suspended field, which suspends the target user. '''When a user is suspended, they cannot:'''<br />
<br />
* Login to https://aur.archlinux.org<br />
* Receive notifications<br />
* Interact with the git interface<br />
<br />
=== Inactivity ===<br />
<br />
When editing your own account or another as a Trusted User, users can set the Inactive field. Inactive accounts are used for two reasons:<br />
<br />
* Display the date someone was marked inactive on their account page<br />
* Generate a current count of active Trusted Users based on their inactivity for new proposals<br />
<br />
== Feedback ==<br />
<br />
=== Commenting on packages ===<br />
<br />
The [https://aur.archlinux.org AUR Web Interface] has a comments facility that allows users to provide suggestions and feedback on improvements to the [[PKGBUILD]] contributor.<br />
<br />
{{Tip|Avoid pasting patches or {{ic|PKGBUILD}}s into the comments section: they quickly become obsolete and just end up needlessly taking up lots of space. Instead email those files to the maintainer, or even use a [[pastebin]].}}<br />
<br />
[https://python-markdown.github.io/ Python-Markdown] provides basic [[Wikipedia:Markdown|Markdown]] syntax to format comments.<br />
<br />
{{Note|<br />
* This implementation has some occasional [https://python-markdown.github.io/#differences differences] with the official [https://daringfireball.net/projects/markdown/syntax syntax rules].<br />
* Commit hashes to the [[Git]] repository of the package and references to [[Flyspray]] tickets are converted to links automatically.<br />
* Long comments are collapsed and can be expanded on demand.<br />
}}<br />
<br />
=== Voting for packages ===<br />
<br />
One of the easiest activities for '''all''' Arch users is to browse the AUR and '''vote''' for their favourite packages using the online interface. All packages are eligible for adoption by a TU for inclusion in the [[community repository]], and the vote count is one of the considerations in that process; it is in everyone's interest to vote!<br />
<br />
Sign up on the [https://aur.archlinux.org/ AUR website] to get a "Vote for this package" option while browsing packages. After signing up it is also possible to vote from the commandline with {{AUR|aurvote}}, {{AUR|aurvote-git}} or {{AUR|aur-auto-vote-git}}.<br />
<br />
Alternatively, if you have set up [[AUR submission guidelines#Authentication|ssh authentication]], you can directly vote from the command line using your ssh key. This means that you will not need to save or type in your AUR password.<br />
<br />
$ ssh aur@aur.archlinux.org vote ''package_name''<br />
<br />
=== Flagging packages out-of-date ===<br />
<br />
First, you should flag the package ''out-of-date'' indicating details on why the package is outdated, preferably including links to the release announcement or the new release [[Archiving and compression#Archiving only|tarball]].<br />
<br />
You should also try to reach out to the maintainer directly by email. If there is no response from the maintainer after ''two weeks'', you can file an ''orphan'' request. See [[AUR submission guidelines#Requests]] for details.<br />
<br />
{{Note|[[VCS package guidelines|VCS packages]] are not considered out of date when the {{ic|pkgver}} changes, do not flag them as the maintainer will merely unflag the package and ignore you. AUR maintainers should not commit mere {{ic|pkgver}} bumps.}}<br />
<br />
== Debugging the package build process ==<br />
<br />
# Ensure your build environment is up-to-date by [[Pacman#Upgrading_packages|upgrading]] before building anything.<br />
# Ensure you have the {{Grp|base-devel}} group installed.<br />
# Use the {{ic|-s}} option with {{ic|makepkg}} to check and install all dependencies needed before starting the build process.<br />
# Try the default [https://github.com/archlinux/svntogit-packages/blob/packages/pacman/trunk/makepkg.conf makepkg configuration].<br />
# See [[Makepkg#Troubleshooting]] for common issues.<br />
<br />
If you are having trouble building a package, first read its [[PKGBUILD]] and the comments on its AUR page.<br />
<br />
It is possible that a {{ic|PKGBUILD}} is broken for everyone. If you cannot figure it out on your own, report it to the maintainer (e.g. by [[#Commenting on packages|posting the errors you are getting in the comments on the AUR page]]). You may also seek help in the [https://bbs.archlinux.org/viewforum.php?id=38 AUR Issues, Discussion & PKGBUILD Requests forum].<br />
<br />
The reason might not be trivial after all. Custom {{ic|CFLAGS}}, {{ic|LDFLAGS}} and {{ic|MAKEFLAGS}} can cause failures. To avoid problems caused by your particular system configuration, build packages in a [[DeveloperWiki:Building in a clean chroot|clean chroot]]. If the build process still fails in a clean chroot, the issue is probably with the {{ic|PKGBUILD}}.<br />
<br />
See [[Creating packages#Checking package sanity]] about using {{ic|namcap}}. If you would like to have a {{ic|PKGBUILD}} reviewed, post it on the [https://mailman.archlinux.org/mailman/listinfo/aur-general aur-general mailing list] to get feedback from the TUs and fellow AUR members, or the [https://bbs.archlinux.org/viewforum.php?id=4 Creating & Modifying Packages forum]. You could also seek help in the [[IRC channel]] [ircs://irc.libera.chat/archlinux-aur #archlinux-aur] on the [https://libera.chat Libera Chat] network.<br />
<br />
== Submitting packages ==<br />
<br />
Users can share [[PKGBUILD]]s using the Arch User Repository. See [[AUR submission guidelines]] for details.<br />
<br />
== Web interface translation ==<br />
<br />
See [https://gitlab.archlinux.org/archlinux/aurweb/-/blob/master/doc/i18n.txt i18n.txt] in the AUR source tree for information about creating and maintaining translation of the [https://aur.archlinux.org AUR Web Interface].<br />
<br />
== FAQ ==<br />
<br />
=== What kind of packages are permitted on the AUR? ===<br />
<br />
The packages on the AUR are merely "build scripts", i.e. recipes to build binaries for [[pacman]]. For most cases, everything is permitted, subject to [[AUR submission guidelines#Rules of submission|usefulness and scope guidelines]], as long as you are in compliance with the licensing terms of the content. For other cases, where it is mentioned that "you may not link" to downloads, i.e. contents that are not redistributable, you may only use the file name itself as the source. This means and requires that users already have the restricted source in the build directory prior to building the package. When in doubt, ask.<br />
<br />
=== How can I vote for packages in the AUR? ===<br />
<br />
See [[#Voting for packages]].<br />
<br />
=== What is a Trusted User / TU? ===<br />
<br />
A [[AUR Trusted User Guidelines|Trusted User]], in short TU, is a person who is chosen to oversee AUR and the [[community repository]]. They are the ones who maintain popular [[PKGBUILD]]s in ''community'', and overall keep the AUR running.<br />
<br />
=== What is the difference between the Arch User Repository and the community repository? ===<br />
<br />
The Arch User Repository is where all [[PKGBUILD]]s that users submit are stored, and must be built manually with [[makepkg]]. When {{ic|PKGBUILD}}s receive enough community interest and the support of a TU, they are moved into the [[community repository]] (maintained by the TUs), where the binary packages can be installed with [[pacman]].<br />
<br />
=== Foo in the AUR is outdated; what should I do? ===<br />
<br />
See [[#Flagging packages out-of-date]].<br />
<br />
In the meantime, you can try updating the package yourself by editing the [[PKGBUILD]] locally. Sometimes, updates do not require changes to the build or package process, in which case simply updating the {{ic|pkgver}} or {{ic|source}} array is sufficient.<br />
<br />
=== Foo in the AUR does not compile when I run makepkg; what should I do? ===<br />
<br />
You are probably missing something trivial, see [[#Debugging the package build process]].<br />
<br />
=== ERROR: One or more PGP signatures could not be verified!; what should I do? ===<br />
<br />
Most likely you do not have the required public key(s) in your personal keyring to verify downloaded files. See [[Makepkg#Signature checking]] for details.<br />
<br />
=== How do I create a PKGBUILD? ===<br />
<br />
Consult the [[AUR submission guidelines#Rules of submission]], then see [[creating packages]].<br />
<br />
=== I have a PKGBUILD I would like to submit; can someone check it to see if there are any errors? ===<br />
<br />
There are several channels available to submit your package for review; see [[#Debugging the package build process]].<br />
<br />
=== How to get a PKGBUILD into the community repository? ===<br />
<br />
Usually, at least 10 votes are required for something to move into [[community repository|community]]. However, if a [[TU]] wants to support a package, it will often be found in the repository.<br />
<br />
Reaching the required minimum of votes is not the only requirement, there has to be a TU willing to maintain the package. TUs are not required to move a package into the ''community'' repository even if it has thousands of votes.<br />
<br />
Usually when a very popular package stays in the AUR it is because:<br />
<br />
* Arch Linux already has another version of a package in the repositories<br />
* Its license prohibits redistribution<br />
* It helps retrieve user-submitted [[PKGBUILD]]s. [[AUR helpers]] are [https://bbs.archlinux.org/viewtopic.php?pid=828310#p828310 unsupported] by definition.<br />
<br />
See also [[AUR Trusted User Guidelines#Rules for packages entering the %5Bcommunity%5D repository|Rules for Packages Entering the community Repo]].<br />
<br />
=== How can I speed up repeated build processes? ===<br />
<br />
See [[Makepkg#Improving compile times]].<br />
<br />
=== What is the difference between foo and foo-git packages? ===<br />
<br />
Many AUR packages come in "stable" release and "unstable" development versions. Development packages usually have a [[VCS package guidelines#Guidelines|suffix]] denoting their [[Version Control System]] and are not intended for regular use, but may offer new features or bugfixes. Because these packages only download the latest available source when you execute {{ic|makepkg}}, their {{ic|pkgver()}} in the AUR does not reflect upstream changes. Likewise, these packages cannot perform an authenticity checksum on any [[VCS_package_guidelines#VCS_sources|VCS source]].<br />
<br />
See also [[System maintenance#Use proven software packages]].<br />
<br />
=== Why has foo disappeared from the AUR? ===<br />
<br />
It is possible the package has been adopted by a [[TU]] and is now in the [[community repository]].<br />
<br />
Packages may be deleted if they did not fulfill the [[AUR submission guidelines#Rules of submission|rules of submission]]. See the [https://lists.archlinux.org/pipermail/aur-requests/ aur-requests archives] for the reason for deletion.<br />
<br />
{{Note|The git repository for a deleted package typically remains available. See [[AUR submission guidelines#Requests]] for details.}}<br />
<br />
If the package used to exist in AUR3, it might not have been [https://lists.archlinux.org/pipermail/aur-general/2015-August/031322.html migrated to AUR4]. See the [[#Git repositories for AUR3 packages]] where these are preserved.<br />
<br />
=== How do I find out if any of my installed packages disappeared from AUR? ===<br />
<br />
The simplest way is to check the HTTP status of the package's AUR page:<br />
<br />
$ comm -23 <(pacman -Qqm | sort) <(curl https://aur.archlinux.org/packages.gz | gzip -cd | sort)<br />
<br />
=== How can I obtain a list of all AUR packages? ===<br />
<br />
* https://aur.archlinux.org/packages.gz<br />
* Use {{ic|aurpkglist}} from {{aur|python3-aur}}<br />
<br />
== See also ==<br />
<br />
* [https://aur.archlinux.org AUR Web Interface]<br />
* [https://lists.archlinux.org/listinfo/aur-general AUR Mailing List]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mailnag&diff=701484Mailnag2021-11-10T20:21:46Z<p>Kevr: Include general Autostart section which includes the two methods within; renamed some titles.</p>
<hr />
<div>[[Category:Applications]]<br />
mailnag is a Wayland e-mail notification daemon. It integrates well with {{Pkg|mako}} and {{Pkg|libnotify}} and comes with interactive configuration tooling, making setup very straight-forward.<br />
<br />
== Installation ==<br />
<br />
''mailnag'' can be [[install]]ed with the {{Pkg|mailnag}} package.<br />
<br />
{{Note|You may also want to install {{Pkg|gnome-keyring}} to satisfy the needed {{ic|org.freedesktop.secrets}} service file.}}<br />
<br />
== Configuration ==<br />
<br />
Run {{ic|mailnag-config}} to create an initial configuration at {{ic|~/.config/mailnag/mailnag.cfg}}.<br />
<br />
== Usage ==<br />
<br />
Users can run ''mailnag'' from within a shell while running a [[Wayland]] or [[Xorg]] session, given that a notification daemon is running.<br />
<br />
{{Note|''mailnag'' needs to be able to access a valid [[dbus]] session to communicate with a notification back-end.}}<br />
<br />
== Autostart ==<br />
<br />
''mailnag'' supports XDG autostart out of the box; a [https://wiki.archlinux.org/title/Systemd/User systemd user service] example has been included below as another option.<br />
<br />
=== Systemd User Unit ===<br />
<br />
Users will probably want to run ''mailnag'' in a systemd unit. Provided below is an example user unit where ''user id'' is the numeric ID of the user where this service is installed.<br />
<br />
{{hc|1=~/.config/system/user/mailnag.service|2=[Unit]<br />
Description=Mailnag notification service<br />
<br />
[Service]<br />
ExecStart=/usr/bin/mailnag<br />
<br />
[Install]<br />
WantedBy=default.target}}<br />
<br />
Then [[start]] {{ic|mailnag.service}}.<br />
<br />
=== XDG ===<br />
<br />
The {{Pkg|mailnag}} package provides a {{ic|/usr/share/applications/mailnag.desktop}} file for use with XDG autostart supported by Gnome and various other desktop environments.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/pulb/mailnag GitHub project]<br />
* [https://github.com/pulb/mailnag/wiki/Mailnag-Changelog Changelog]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mailnag&diff=701483Mailnag2021-11-10T20:16:27Z<p>Kevr: Include XDG Autostart information</p>
<hr />
<div>[[Category:Applications]]<br />
mailnag is a Wayland e-mail notification daemon. It integrates well with {{Pkg|mako}} and {{Pkg|libnotify}} and comes with interactive configuration tooling, making setup very straight-forward.<br />
<br />
== Installation ==<br />
<br />
''mailnag'' can be [[install]]ed with the {{Pkg|mailnag}} package.<br />
<br />
{{Note|You may also want to install {{Pkg|gnome-keyring}} to satisfy the needed {{ic|org.freedesktop.secrets}} service file.}}<br />
<br />
== Configuration ==<br />
<br />
Run {{ic|mailnag-config}} to create an initial configuration at {{ic|~/.config/mailnag/mailnag.cfg}}.<br />
<br />
== Usage ==<br />
<br />
Users can run ''mailnag'' from within a shell while running a [[Wayland]] or [[Xorg]] session, given that a notification daemon is running.<br />
<br />
{{Note|''mailnag'' needs to be able to access a valid [[dbus]] session to communicate with a notification back-end.}}<br />
<br />
=== systemd user unit ===<br />
<br />
Users will probably want to run ''mailnag'' in a systemd unit. Provided below is an example user unit where ''user id'' is the numeric ID of the user where this service is installed.<br />
<br />
{{hc|1=~/.config/system/user/mailnag.service|2=[Unit]<br />
Description=Mailnag notification service<br />
<br />
[Service]<br />
ExecStart=/usr/bin/mailnag<br />
<br />
[Install]<br />
WantedBy=default.target}}<br />
<br />
Then [[start]] {{ic|mailnag.service}}.<br />
<br />
=== XDG Autostart ===<br />
<br />
The {{Pkg|mailnag}} package provides a {{ic|/usr/share/applications/mailnag.desktop}} file for use with XDG autostart supported by Gnome and various other desktop environments.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/pulb/mailnag GitHub project]<br />
* [https://github.com/pulb/mailnag/wiki/Mailnag-Changelog Changelog]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mailnag&diff=701479Mailnag2021-11-10T20:12:13Z<p>Kevr: mailnag also supports libnotify</p>
<hr />
<div>[[Category:Applications]]<br />
mailnag is a Wayland e-mail notification daemon. It integrates well with {{Pkg|mako}} and {{Pkg|libnotify}} and comes with interactive configuration tooling, making setup very straight-forward.<br />
<br />
== Installation ==<br />
<br />
''mailnag'' can be [[install]]ed with the {{Pkg|mailnag}} package.<br />
<br />
{{Note|You may also want to install {{Pkg|gnome-keyring}} to satisfy the needed {{ic|org.freedesktop.secrets}} service file.}}<br />
<br />
== Configuration ==<br />
<br />
Run {{ic|mailnag-config}} to create an initial configuration at {{ic|~/.config/mailnag/mailnag.cfg}}.<br />
<br />
== Usage ==<br />
<br />
Users can run ''mailnag'' from within a shell while running a [[Wayland]] or [[Xorg]] session, given that a notification daemon is running.<br />
<br />
{{Note|''mailnag'' needs to be able to access a valid [[dbus]] session to communicate with a notification back-end.}}<br />
<br />
=== systemd user unit ===<br />
<br />
Users will probably want to run ''mailnag'' in a systemd unit. Provided below is an example user unit where ''user id'' is the numeric ID of the user where this service is installed.<br />
<br />
{{hc|1=~/.config/system/user/mailnag.service|2=[Unit]<br />
Description=Mailnag notification service<br />
<br />
[Service]<br />
ExecStart=/usr/bin/mailnag<br />
<br />
[Install]<br />
WantedBy=default.target}}<br />
<br />
Then [[start]] {{ic|mailnag.service}}.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/pulb/mailnag GitHub project]<br />
* [https://github.com/pulb/mailnag/wiki/Mailnag-Changelog Changelog]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mailnag&diff=701475Mailnag2021-11-10T19:47:55Z<p>Kevr: Remove unnecessary dbus env var from the systemd unit</p>
<hr />
<div>[[Category:Applications]]<br />
mailnag is a Wayland e-mail notification daemon. It integrates well with {{Pkg|mako}} and comes with interactive configuration tooling, making setup very straight-forward.<br />
<br />
== Installation ==<br />
<br />
''mailnag'' can be [[install]]ed with the {{Pkg|mailnag}} package.<br />
<br />
{{Note|You may also want to install {{Pkg|gnome-keyring}} to satisfy the needed {{ic|org.freedesktop.secrets}} service file.}}<br />
<br />
== Configuration ==<br />
<br />
Run {{ic|mailnag-config}} to create an initial configuration at {{ic|~/.config/mailnag/mailnag.cfg}}.<br />
<br />
== Usage ==<br />
<br />
Users can run ''mailnag'' from within a shell while running a [[Wayland]] session.<br />
<br />
{{Note|''mailnag'' needs to be able to access a valid [[dbus]] session to communicate with a notification back-end like {{Pkg|mako}}.}}<br />
<br />
=== systemd user unit ===<br />
<br />
Users will probably want to run ''mailnag'' in a systemd unit. Provided below is an example user unit where ''user id'' is the numeric ID of the user where this service is installed.<br />
<br />
{{hc|1=~/.config/system/user/mailnag.service|2=[Unit]<br />
Description=Mailnag notification service<br />
<br />
[Service]<br />
ExecStart=/usr/bin/mailnag<br />
<br />
[Install]<br />
WantedBy=default.target}}<br />
<br />
Then [[start]] {{ic|mailnag.service}}.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/pulb/mailnag GitHub project]<br />
* [https://github.com/pulb/mailnag/wiki/Mailnag-Changelog Changelog]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mailnag&diff=701474Mailnag2021-11-10T19:46:26Z<p>Kevr: Added upstream references to == See also ==</p>
<hr />
<div>[[Category:Applications]]<br />
mailnag is a Wayland e-mail notification daemon. It integrates well with {{Pkg|mako}} and comes with interactive configuration tooling, making setup very straight-forward.<br />
<br />
== Installation ==<br />
<br />
''mailnag'' can be [[install]]ed with the {{Pkg|mailnag}} package.<br />
<br />
{{Note|You may also want to install {{Pkg|gnome-keyring}} to satisfy the needed {{ic|org.freedesktop.secrets}} service file.}}<br />
<br />
== Configuration ==<br />
<br />
Run {{ic|mailnag-config}} to create an initial configuration at {{ic|~/.config/mailnag/mailnag.cfg}}.<br />
<br />
== Usage ==<br />
<br />
Users can run ''mailnag'' from within a shell while running a [[Wayland]] session.<br />
<br />
{{Note|''mailnag'' needs to be able to access a valid [[dbus]] session to communicate with a notification back-end like {{Pkg|mako}}.}}<br />
<br />
=== systemd user unit ===<br />
<br />
Users will probably want to run ''mailnag'' in a systemd unit. Provided below is an example user unit where ''user id'' is the numeric ID of the user where this service is installed.<br />
<br />
{{hc|1=~/.config/system/user/mailnag.service|2=[Unit]<br />
Description=Mailnag notification service<br />
<br />
[Service]<br />
Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/''user id''/bus<br />
ExecStart=/usr/bin/mailnag<br />
<br />
[Install]<br />
WantedBy=default.target}}<br />
<br />
Then [[start]] {{ic|mailnag.service}}.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/pulb/mailnag GitHub project]<br />
* [https://github.com/pulb/mailnag/wiki/Mailnag-Changelog Changelog]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mailnag&diff=701467Mailnag2021-11-10T19:34:40Z<p>Kevr: Created the Mailnag page.</p>
<hr />
<div>[[Category:Applications]]<br />
<br />
{{Pkg|mailnag}} is a Wayland e-mail notification daemon. It integrates well with {{Pkg|mako}} and comes with interactive configuration tooling, making setup very straight-forward.<br />
<br />
== Installation ==<br />
<br />
''mailnag'' can be [[install]]ed with the {{Pkg|mailnag}} package.<br />
<br />
{{Note|You may also want to install {{Pkg|gnome-keyring}} to satisfy the needed {{ic|org.freedesktop.secrets}} service file.}}<br />
<br />
== Configuration ==<br />
<br />
Run {{ic|mailnag-config}} to create an initial configuration at {{ic|~/.config/mailnag/mailnag.cfg}}.<br />
<br />
== Usage ==<br />
<br />
Users can run ''mailnag'' from within a shell while running a Wayland session.<br />
<br />
{{Note|''mailnag'' needs to be able to access a valid {{Pkg|dbus}} session to communicate with a notification back-end like {{Pkg|mako}}.}}<br />
<br />
=== systemd User Service ===<br />
<br />
Users will probably want to run ''mailnag'' in a systemd unit. Provided below is an example {{ic|systemd --user}} service file where {{ic|<user_id>}} is the numeric ID of the user where this service is installed.<br />
<br />
{{hc|head=~/.config/system/user/mailnag.service|output=[Unit]<br />
Description=Mailnag notification service<br />
<br />
[Service]<br />
Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/<user_id>/bus<br />
ExecStart=/usr/bin/mailnag<br />
<br />
[Install]<br />
WantedBy=default.target}}<br />
<br />
Start it by executing {{ic|systemd --user start mailnag}} while you have a valid DBUS session running.</div>Kevrhttps://wiki.archlinux.org/index.php?title=User:Kevr&diff=701463User:Kevr2021-11-10T19:05:12Z<p>Kevr: </p>
<hr />
<div>A person named "Kevin Morris," who frequents #archlinux and #archlinux-offtopic on Libera as "kevr."</div>Kevrhttps://wiki.archlinux.org/index.php?title=User_talk:Kevr&diff=699319User talk:Kevr2021-10-17T05:42:28Z<p>Kevr: Blanked the page</p>
<hr />
<div></div>Kevrhttps://wiki.archlinux.org/index.php?title=User_talk:Kevr&diff=699301User talk:Kevr2021-10-17T02:56:59Z<p>Kevr: Added a warning to "The pkgver() function" section about not flagging VCS packaging based on an "outdated" pkgver seen in the AUR.</p>
<hr />
<div>[[Category:Arch package guidelines]]<br />
[[it:VCS package guidelines]]<br />
[[ja:VCS PKGBUILD ガイドライン]]<br />
[[pt:VCS package guidelines]]<br />
[[zh-hant:VCS package guidelines]]<br />
{{Package guidelines}}<br />
<br />
[[Wikipedia:Revision_control|Version control systems]] can be used for retrieval of source code for both usual statically versioned packages and latest (trunk) version of a development branch. This article covers both cases.<br />
<br />
== Prototypes ==<br />
<br />
Use only the PKGBUILD prototypes provided in the {{Pkg|pacman}} package ({{ic|PKGBUILD-split.proto}}, {{ic|PKGBUILD-vcs.proto}} and {{ic|PKGBUILD.proto}} in {{ic|/usr/share/pacman}}).<br />
<br />
== Guidelines ==<br />
<br />
* Suffix {{ic|pkgname}} with {{ic|-cvs}}, {{ic|-svn}}, {{ic|-hg}}, {{ic|-darcs}}, {{ic|-bzr}}, {{ic|-git}} etc. unless the package fetches a specific release.<br />
* If the resulting package is different after changing the dependencies, URL, sources, etc. increasing the {{ic|pkgrel}} is mandatory. Touching the {{ic|pkgver}} is not.<br />
* {{ic|--holdver}} can be used to prevent [[makepkg]] from updating the {{ic|pkgver}} (see: {{man|8|makepkg}})<br />
* Include what the package conflicts with and provides (e.g. for {{AUR|fluxbox-git}}: {{ic|1=conflicts=('fluxbox')}} and {{ic|1=provides=('fluxbox')}}).<br />
* {{ic|1=replaces=()}} generally causes unnecessary problems and should be avoided.<br />
* When using the cvsroot, use {{ic|anonymous:@}} rather than {{ic|anonymous@}} to avoid having to enter a blank password or {{ic|anonymous:password@}}, if one is required.<br />
* Include the appropriate VCS tool in {{ic|1=makedepends=()}} ({{pkg|cvs}}, {{pkg|subversion}}, {{pkg|git}}, ...).<br />
* Because the sources are not static, skip the checksum in {{ic|1=md5sums=()}} by adding {{ic|'SKIP'}}.<br />
<br />
=== VCS sources ===<br />
<br />
{{Note|Pacman 4.1 supports the following VCS sources: {{ic|bzr}}, {{ic|git}}, {{ic|hg}} and {{ic|svn}}. See the {{ic|fragment}} section of {{man|5|PKGBUILD|USING VCS SOURCES}} for a list of supported VCS.}}<br />
<br />
Starting with {{Pkg|pacman}} 4.1, the VCS sources should be specified in the {{ic|1=source=()}} array and will be treated like any other source. {{ic|makepkg}} will clone/checkout/branch the repository into {{ic|$SRCDEST}} (same as {{ic|$startdir}} if not set in {{man|5|makepkg.conf}}) and copy it to {{ic|$srcdir}} (in a specific way to each VCS). The local repository is left untouched, thus invalidating the need for a {{ic|-build}} directory.<br />
<br />
The general format of a VCS {{ic|1=source=()}} array is:<br />
<br />
source=('[folder::][vcs+]url[#fragment]')<br />
<br />
* {{ic|folder}} (optional) is used to change the default repository name to something more relevant (e.g. than {{ic|trunk}}) or to preserve the previous sources.<br />
* {{ic|vcs+}} is needed for URLs that do not reflect the VCS type, e.g. {{ic|<nowiki>git+http://some_repo</nowiki>}}.<br />
* {{ic|url}} is the URL to the distant or local repository.<br />
* {{ic|#fragment}} (optional) is needed to pull a specific branch or commit. See {{man|5|PKGBUILD|USING VCS SOURCES}} for more information on the fragments available for each VCS.<br />
<br />
An example Git source array:<br />
<br />
<nowiki>source=('project_name::git+https://project_url#branch=project_branch')</nowiki><br />
<br />
=== The pkgver() function ===<br />
<br />
{{Warning|VCS packages should '''not''' be flagged out-of-date because of versions which can be seen on the AUR. With VCS packages, the version is not updated to the intended VCS HEAD commit's version until a user builds it, and the version will be reflected in the locally installed package. Out-of-date flagging should only occur due to a source build problem. In short: if a VCS package can be successfully built with ''makepkg'', it should not be flagged out-of-date.}}<br />
<br />
The {{ic|pkgver}} autobump is now achieved via a dedicated {{ic|pkgver()}} function. This allows for better control over the {{ic|pkgver}}, and maintainers should favor a {{ic|pkgver}} that makes sense. To use {{ic|pkgver()}}, you still need to declare the {{ic|pkgver}} variable with the most recent value. makepkg will invoke function {{ic|pkgver()}}, and update variable {{ic|pkgver}} accordingly.<br />
<br />
It is recommended to have following version format: ''RELEASE.rREVISION'' where ''REVISION'' is a monotonically increasing number that uniquely identifies the source tree (VCS revisions do this). If there are no public releases and no repository tags then zero could be used as a release number or you can drop ''RELEASE'' completely and use version number that looks like ''rREVISION''. If there are public releases but repo has no tags then the developer should get the release version somehow e.g. by parsing the project files.<br />
<br />
The revision number delimiter ("r" right before REVISION) is important. This delimiter allows to avoid problems in case if upstream decides to make its first release or uses versions with different number of components. E.g. if at revision "455" upstream decides to release version 0.1 then the revision delimiter preserves version monotonicity - {{ic|0.1.r456 > r454}}. Without the delimiter monotonicity fails - {{ic|0.1.456 < 454}}.<br />
<br />
See [https://gitlab.archlinux.org/pacman/pacman/blob/master/proto/PKGBUILD-vcs.proto#L33 PKGBUILD-vcs.proto] for generic examples showing the intended output.<br />
<br />
==== Git ====<br />
<br />
Using the most recent annotated tag reachable from the last commit:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
git describe --long | sed 's/\([^-]*-g\)/r\1/;s/-/./g'<br />
}</nowiki>|<br />
2.0.r6.ga17a017<br />
}}<br />
<br />
Using the most recent un-annotated tag reachable from the last commit:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
git describe --long --tags | sed 's/\([^-]*-g\)/r\1/;s/-/./g'<br />
}</nowiki>|<br />
0.71.r115.gd95ee07<br />
}}<br />
<br />
In case if the git tag does not contain dashes then one can use simpler sed expression {{ic|sed 's/-/.r/;s/-/./'}}.<br />
<br />
If tag contains a prefix, like {{ic|v}} or project name then it should be cut off:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
# cutting off 'foo-' prefix that presents in the git tag<br />
git describe --long | sed 's/^foo-//;s/\([^-]*-g\)/r\1/;s/-/./g'<br />
}</nowiki>|<br />
6.1.r3.gd77e105<br />
}}<br />
<br />
If there are no tags then use number of revisions since beginning of the history:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"<br />
}</nowiki>|<br />
r1142.a17a017<br />
}}<br />
<br />
Version and only commit/revision number (SHA1 omitted; however, without a SHA1 quick referencing of an exact revision is lost if not mindful of versioning):<br />
<br />
git describe --long | sed -r 's/-([0-9,a-g,A-G]{7}.*)//' | sed 's/-/./g'<br />
<br />
Both methods can also be combined, to support repositories that start without a tag but get tagged later on (uses a bashism):<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
( set -o pipefail<br />
git describe --long 2>/dev/null | sed 's/\([^-]*-g\)/r\1/;s/-/./g' ||<br />
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"<br />
)<br />
}</nowiki>|<br />
0.9.9.r27.g2b039da # if tags exist<br />
r1581.2b039da # else fallback<br />
}}<br />
<br />
==== Subversion ====<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
local ver="$(svnversion)"<br />
printf "r%s" "${ver//[[:alpha:]]}"<br />
}</nowiki>|<br />
r8546<br />
}}<br />
<br />
{{Note|If the project has releases you should use them instead of the {{ic|0.}}.}}<br />
<br />
==== Mercurial ====<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
printf "r%s.%s" "$(hg identify -n)" "$(hg identify -i)"<br />
}</nowiki>|<br />
r2813.75881cc5391e<br />
}}<br />
<br />
==== Bazaar ====<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
printf "r%s" "$(bzr revno)"<br />
}</nowiki>|<br />
r830<br />
}}<br />
<br />
==== Fallback ====<br />
<br />
In case no satisfactory {{ic|pkgver}} can be extracted from the repository, the current date can be used:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
date +%Y%m%d<br />
}</nowiki>|<br />
20130408<br />
}}<br />
<br />
Although it does not identify source tree state uniquely, so avoid it if possible.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Git submodules ===<br />
<br />
Git submodules are a little tricky to do. The idea is to add the URLs of the submodules themselves directly to the sources array and then reference them during prepare(). This could look like this:<br />
<br />
{{bc|<nowiki><br />
source=("git://somewhere.org/something/something.git"<br />
"git://somewhere.org/mysubmodule/mysubmodule.git")<br />
<br />
prepare() {<br />
cd something<br />
git submodule init<br />
git config submodule.mysubmodule.url "$srcdir/mysubmodule"<br />
git submodule update<br />
}<br />
</nowiki>}}</div>Kevrhttps://wiki.archlinux.org/index.php?title=Screen_capture&diff=695264Screen capture2021-09-11T03:54:03Z<p>Kevr: grimshot (the more production swayshot) is available in the sway package, there is no need for an AUR package.</p>
<hr />
<div>[[Category:System administration]]<br />
[[Category:Multimedia]]<br />
[[es:Screen capture]]<br />
[[ja:スクリーンショットの取得]]<br />
[[zh-hans:Taking a screenshot]]<br />
{{Related articles start}}<br />
{{Related|Key binding}}<br />
{{Related articles end}}<br />
This article lists and describes [[Wikipedia:Screenshot|screenshot]] and [[Wikipedia:Screencast|screencast]] software.<br />
<br />
== Screenshot software ==<br />
<br />
=== Dedicated software ===<br />
<br />
* {{App|CoreShot|Simple lightweight screen capture utility for X11. Part of C-Suite.|https://cubocore.org/|{{AUR|coreshot}}}}<br />
* {{App|Deepin Screenshot|Quite easy-to-use screenshot tool. Features: global hotkey to trigger screenshot tool, take screenshot of a selected area, easy to add text and line drawings onto the screenshot. Python/Qt5 based. However, it is now deprecated and has been merged into Deepin Screen Recorder. There is also a known issue with the clipboard functionality. There is a patched version in the aur {{AUR|deepin-screenshot-copy-patch}}|https://www.deepin.org/en/original/deepin-screenshot/|{{Pkg|deepin-screenshot}}}}<br />
* {{App|Escrotum|Screen capture using python and gtk3, inspired by scrot.|https://github.com/Roger/escrotum|{{AUR|escrotum-git}}}}<br />
* {{App|[[Flameshot]]|Qt5 based software for interactive screenshot taking. Select the desired area, draw with different tools and enjoy the customization capabilities.|https://github.com/lupoDharkael/flameshot|{{Pkg|flameshot}}}}<br />
* {{App|[[Wikipedia:GNOME Screenshot|GNOME Screenshot]]|Screenshot tool for the GNOME desktop.|https://gitlab.gnome.org/GNOME/gnome-screenshot/|{{Pkg|gnome-screenshot}}}}<br />
* {{App|grim|Grab images from a Wayland compositor.|https://github.com/emersion/grim|{{Pkg|grim}}}}<br />
* {{App|gscreenshot|Simple GTK screenshot utility with delays, selection, and copy-to-clipboard functionality.|https://github.com/thenaterhood/gscreenshot|{{AUR|gscreenshot}}}}<br />
* {{App|HotShots|Application for capturing screens and saving them in a variety of image formats as well as adding annotations and graphical data (arrows, lines, texts, ...).|https://github.com/obiwankennedy/HotShots|{{AUR|hotshots-git}}}}<br />
* {{App|imgur-screenshot|Take screenshot selection, upload to [https://imgur.com imgur]. + more cool things|https://github.com/jomo/imgur-screenshot|{{AUR|imgur-screenshot-git}}}}<br />
* {{App|ksnip|Ksnip is a Qt based cross-platform screenshot tool that provides many annotation features for your screenshots.|https://github.com/ksnip/ksnip|{{Pkg|ksnip}}}}<br />
* {{App|Lightscreen|Simple tool to automate the tedious process of saving and cataloging screenshots, it operates as a hidden background process that is invoked with one (or multiple) hotkeys and then saves a screenshot file to disk according to the user's preferences.|https://lightscreen.com.ar|{{AUR|lightscreen}}}}<br />
* {{App|LXQt Screenshot|Screenshot tool for LXQt. Run with {{ic|lximage-qt --screenshot}}.|https://github.com/lxde/lximage-qt|{{Pkg|lximage-qt}}}}<br />
* {{App|maim|Simple command line utility that takes screenshots. It is meant to replace scrot and performs better than scrot in many ways.|https://github.com/naelstrof/maim|{{Pkg|maim}}}}<br />
* {{App|MATE Screenshot|Screenshot tool for the MATE desktop.|https://mate-desktop.org|{{Pkg|mate-utils}}}}<br />
* {{App|menyoki|Screen{shot,cast} and perform ImageOps on the command line.|https://github.com/orhun/menyoki|{{Pkg|menyoki}}}}<br />
* {{App|mss|An [[xrandr]]-aware screenshots Python module with a minimal CLI.|https://pypi.org/project/mss/|{{Pkg|python-mss}}}}<br />
* {{App|Pantheon Screenshot|Screenshot tool designed for elementary OS.|https://github.com/elementary/screenshot|{{Pkg|pantheon-screenshot}}}}<br />
* {{App|ScreenCloud|Take a screenshot of the entire screen or to select an area and then uploading the screenshot to [https://imgur.com imgur]+auth. has plugins and system tray.|https://screencloud.net/|{{AUR|screencloud}}}}<br />
* {{App|ScreenGrab|Cross-platform application designed to quickly take screenshots (Qt).|https://github.com/DOOMer/screengrab|{{Pkg|screengrab}}}}<br />
* {{App|[[Wikipedia:Scrot|Scrot]]|Simple command-line screenshot utility for X.|https://github.com/resurrecting-open-source-projects/scrot|{{Pkg|scrot}}}}<br />
* {{App|Shotgun|Minimal X screenshot utility written in Rust. According to the author it is twice as fast as maim.|https://github.com/neXromancers/shotgun|{{Pkg|shotgun}}}}<br />
* {{App|Shutter|Rich screenshot and editing program. Supports [https://hyp.is/AVQUNTRUH9ZO4OKSlue9/askubuntu.com/questions/252281/how-do-i-take-screenshots-with-a-delay/260178 delay]. |https://shutter-project.org/|{{Pkg|shutter}}}}<br />
* {{App|Spectacle|[[KDE]] application for taking screenshots. It is capable of capturing images of the whole desktop, a single window, a section of a window, a selected rectangular region or a freehand region. Part of {{Grp|kde-graphics}}.|https://github.com/KDE/spectacle/|{{Pkg|spectacle}}}}<br />
* {{App|Xfce4 Screenshooter|Application and Xfce4 panel plugin to take screenshots about the entire screen, the active window or a selected region. Part of {{Grp|xfce4-goodies}}.|https://goodies.xfce.org/projects/applications/xfce4-screenshooter|{{Pkg|xfce4-screenshooter}}}}<br />
* {{App|xwd|X Window System image dumping utility|https://www.x.org/|{{Pkg|xorg-xwd}}}}<br />
<br />
==== xwd ====<br />
<br />
{{man|1|xwd}} is provided by {{Pkg|xorg-xwd}}.<br />
<br />
To take a screenshot of the root window:<br />
<br />
$ xwd -root -out screenshot.xwd<br />
<br />
{{Tip|To obtain a delay before taking a screenshot, use the {{ic|sleep}} command. For example: {{ic|sleep 5; xwd ...}}.}}<br />
<br />
==== scrot ====<br />
<br />
{{Pkg|scrot}} enables taking screenshots from the CLI and offers features such as a user-definable time delay. Unless instructed otherwise, it saves the file in the current working directory.<br />
<br />
$ scrot -t 20 -d 5<br />
<br />
The above command saves a dated ''.png'' file, along with a thumbnail (20% of original), for Web posting. It provides a 5 second delay before capturing in this instance.<br />
<br />
You can also use standard date and time formatting when saving to a file. e.g.,<br />
<br />
$ scrot ~/screenshots/%Y-%m-%d-%T-screenshot.png<br />
<br />
saves the screenshot in a filename with the current year, month, date, hours, minutes, and seconds to a folder in your home directory called "screenshots" <br />
<br />
See {{man|1|scrot}} for more information. You can simply automate the file to uploaded like so [https://github.com/kaihendry/Kai-s--HOME/tree/master/bin].<br />
<br />
{{Note|In some window managers ({{AUR|dwm}}, {{Pkg|xmonad}} and possibly others) {{ic|scrot -s}} does not work properly when running via window manager's keyboard shortcut, this can be worked around by prepending scrot invocation with a short pause {{ic|sleep 0.2; scrot -s}}.}}<br />
<br />
==== escrotum ====<br />
<br />
{{AUR|escrotum-git}} screen capture using PyGTK, inspired by scrot<br />
<br />
Created because scrot has glitches when selection mode is used with refreshing windows.<br />
<br />
Because the command line interface its almost the same as scrot, can be used as a replacement of it.<br />
<br />
==== maim ====<br />
<br />
{{Pkg|maim}} is aimed to be an improved scrot.<br />
<br />
Takes screenshots of your desktop using [https://github.com/naelstrof/slop slop] for regions. It is meant to overcome shortcomings of scrot.<br />
<br />
To select a portion of the screen and store it on the clipboard, {{Pkg|xclip}} can be used:<br />
<br />
$ maim -s -u | xclip -selection clipboard -t image/png -i<br />
<br />
=== Desktop environment specific ===<br />
<br />
==== Spectacle ====<br />
<br />
If you use [[KDE]], you might want to use {{ic|Spectacle}}.<br />
<br />
Spectacle is provided by the {{Pkg|spectacle}} package.<br />
<br />
==== Xfce Screenshooter ====<br />
<br />
If you use [[Xfce]] you can install {{Pkg|xfce4-screenshooter}} and then add a keyboard binding:<br />
<br />
''Xfce Menu > Settings > Keyboard > Application Shortcuts''<br />
<br />
If you want to skip the Screenshot prompt, type {{ic|$ xfce4-screenshooter -h}} in terminal for the options.<br />
<br />
==== GNOME ====<br />
<br />
[[GNOME]] users can press {{ic|PrintScreen}} or ''Apps > Accessories > Take Screenshot''. You may need to install {{Pkg|gnome-screenshot}}.<br />
<br />
GNOME features built-in screen recording with the {{ic|Ctrl+Shift+Alt+r}} key combination. A red circle is displayed in the bottom right corner of the screen when the recording is in progress. After the recording is finished, a file named {{ic|Screencast from %d%u-%c.webm}} is saved in the {{ic|Videos}} directory. In order to use the screencast feature the gst plugins need to be installed.<br />
<br />
==== Cinnamon ====<br />
<br />
The default installation of [[Cinnamon]] does not provide a screenshot utility. Installing {{Pkg|gnome-screenshot}} will enable screenshots through the ''Menu > Accessories > Screenshot'' or by pressing {{ic|PrintScreen}}.<br />
<br />
==== Other desktop environments or window managers ====<br />
<br />
For other desktop environments such as [[LXDE]] or window managers such as [[Openbox]] and [[Compiz]], one can add the above commands to the hotkey to take the screenshot. For example,<br />
<br />
$ import -window root ~/Pictures/$(date '+%Y%m%d-%H%M%S').png<br />
<br />
Note that {{ic|import}} is part of the {{Pkg|imagemagick}} package. Adding the above command to the {{ic|PrintScreen}} key to Compiz allows to take the screenshot to the Pictures folder according to date and time.<br />
Notice that the {{ic|rc.xml}} file in Openbox does not understand commas; so, in order to bind that command to the {{ic|PrintScreen}} key in Openbox, you need to add the following to the keyboard section of your {{ic|rc.xml}} file:<br />
<br />
{{hc|rc.xml|<nowiki><br />
<!-- Screenshot --><br />
<keybind key="Print"><br />
<action name="Execute"><br />
<command>sh -c "import -window root ~/Pictures/$(date '+%Y%m%d-%H%M%S').png"</command><br />
</action><br />
</keybind><br />
</nowiki>}}<br />
<br />
If the {{ic|Print}} above does not work, see [[Extra keyboard keys]] and use different ''keysym'' or ''keycode''.<br />
<br />
=== Packages including a screenshot utility ===<br />
<br />
==== ImageMagick/GraphicsMagick ====<br />
<br />
See [[ImageMagick#Screenshot taking]].<br />
<br />
==== GIMP ====<br />
<br />
You also can take screenshots with [[GIMP]] (''File > Create > Screenshot''...).<br />
<br />
==== imlib2 ====<br />
<br />
{{Pkg|imlib2}} provides a binary {{ic|imlib2_grab}} to take screenshots. To take a screenshot of the full screen, type:<br />
<br />
$ imlib2_grab screenshot.png<br />
<br />
==== FFmpeg ====<br />
<br />
See [[FFmpeg#Screen capture]].<br />
<br />
== Screencast software ==<br />
<br />
See also [[FFmpeg#Screen capture]] and [[Wikipedia:Comparison of screencasting software]].<br />
<br />
Screencast utilities allow you to create a video of your desktop or individual windows.<br />
<br />
* {{App|Byzanz|Simple screencast tool that produces GIF animations.|https://gitlab.gnome.org/Archive/byzanz|{{Pkg|byzanz}}}}<br />
* {{App|Deepin Screen Recorder|Screen recorder application for Deepin desktop.|https://www.deepin.org/en/original/deepin-screen-recorder/|{{Pkg|deepin-screen-recorder}}}}<br />
* {{App|FFcast|FFmpeg-based screencast tool written in Bash.|https://github.com/lolilolicon/FFcast|{{AUR|ffcast}}}}<br />
* {{App|Green Recorder|Simple yet functional desktop recorder for Linux systems.|https://github.com/dvershinin/green-recorder|{{AUR|green-recorder}}}}<br />
* {{App|Kazam|Screencasting program with design in mind. Handles multiscreen setups.|https://launchpad.net/kazam|{{AUR|kazam}}}}<br />
* {{App|Kooha|Simple screen recorder with a minimal GTK interface.|https://github.com/SeaDve/Kooha|{{AUR|kooha}}}}<br />
* {{App|menyoki|Screen{shot,cast} and perform ImageOps on the command line.|https://github.com/orhun/menyoki|{{Pkg|menyoki}}}}<br />
* {{App|[[Wikipedia:Open Broadcaster Software|OBS]]|Video recording and live streaming application.|https://obsproject.com/|{{Pkg|obs-studio}}}}<br />
:* {{AUR|obs-gnome-screencast}} – plugin for GNOME screencast feature, supports Wayland<br />
:* {{AUR|obs-xdg-portal-git}} – plugin that uses Desktop portal for Wayland & X11 screencasting<br />
:* {{AUR|obs-studio-browser}} – OBS built with the browser plugin<br />
* {{App|[[Wikipedia:Peek_(software)|Peek]]|Simple screencast tool that produces GIF, APNG, WebM or MP4 animations.|https://github.com/phw/peek|{{Pkg|peek}}}}<br />
* {{App|RecApp|User friendly screencaster written in GTK. Using free GStreamer modules and not depend on FFmpeg.|https://github.com/amikha1lov/RecApp|{{AUR|recapp-git}}}}<br />
* {{App|RecordItNow|Plugin based desktop recorder for KDE.|http://recorditnow.sourceforge.net/|{{AUR|recorditnow}}}}<br />
* {{App|[[RecordMyDesktop]]|Easy to use utility that records your desktop into the ogg format with a CLI, GTK or Qt interface. (inactive development)|http://recordmydesktop.sourceforge.net/|CLI: {{Pkg|recordmydesktop}}, GTK: {{AUR|gtk-recordmydesktop}}, Qt: {{AUR|qt-recordmydesktop}}}}<br />
* {{App|screencast|Command line interface to record an X11 desktop using FFmpeg, having support for offline recording and live streaming.|https://github.com/dbermond/screencast/|{{AUR|screencast}}}}<br />
* {{App|Screencast|Simple screencast recorder designed for elementary OS.|https://github.com/artemanufrij/screencast|{{AUR|pantheon-screencast}}}}<br />
* {{App|[[Wikipedia:SimpleScreenRecorder|SimpleScreenRecorder]]|Feature-rich screen recorder written in C++/Qt5 that supports X11 and OpenGL.|https://www.maartenbaert.be/simplescreenrecorder/|{{Pkg|simplescreenrecorder}}}}<br />
* {{App|VokoScreen|Simple screencast GUI tool using GStreamer.|https://linuxecke.volkoh.de/vokoscreen/vokoscreen.html|{{Pkg|vokoscreen}}}}<br />
* {{App|[[Wikipedia:XVidCap|XVidCap]]|Application used for recording a screencast or digital recording of an X Window System screen output with an audio narration.|http://xvidcap.sourceforge.net/|{{AUR|xvidcap}}}}<br />
<br />
== Wayland ==<br />
<br />
Capturing the screen on Wlroots-based compositor can be done using {{Pkg|grim}} or grimshot (provided by {{Pkg|sway}}) for screenshots and {{Pkg|wf-recorder}} (or {{AUR|wf-recorder-git}}) for video; {{AUR|wlrobs-hg}} is an {{Pkg|obs-studio}} plugin that allows you to screen capture on wlroots-based compositors. Optionally, {{Pkg|slurp}} can be used to select the part of the screen to capture.<br />
<br />
Take a screenshot of the whole screen:<br />
<br />
$ grim screenshot.png<br />
<br />
Take a screenshot of current window:<br />
<br />
$ grim -g "$(swaymsg -t get_tree | jq -r '.. | select(.focused?) | .rect | "\(.x),\(.y) \(.width)x\(.height)"')" screenshot.png<br />
<br />
Take a screenshot of a part of the screen:<br />
<br />
$ grim -g "$(slurp)" screenshot.png<br />
<br />
Take a screenshot of a part of the screen and put the output into the clipboard using {{Pkg|wl-clipboard}}:<br />
<br />
$ grim -g "$(slurp)" - | wl-copy<br />
<br />
Capture a video of the whole screen:<br />
<br />
$ wf-recorder -f recording.mp4<br />
<br />
Capture a video of a part of the screen:<br />
<br />
$ wf-recorder -g "$(slurp)"<br />
<br />
{{Tip|<br />
* [https://github.com/de-arl/slurpshot slurpshot] is an interactive screenshot taking script using {{Pkg|bemenu}}.<br />
* To use a post-capture screenshot editing and drawing tool such as {{Pkg|swappy}}: {{ic|grim -g "$(slurp)" - {{!}} swappy -f -}}<br />
}}<br />
<br />
Additionally, some programs mentioned above work under Wayland (e.g. {{Pkg|ksnip}}, {{AUR|green-recorder}}).<br />
<br />
=== Screencasting ===<br />
<br />
==== Via GNOME screencast ====<br />
<br />
{{AUR|green-recorder}}, {{AUR|obs-gnome-screencast}} and {{AUR|obs-xdg-portal-git}} support screen recording on Wayland using GNOME screencast feature.<br />
<br />
==== Via a virtual webcam video feed ====<br />
<br />
{{Tip|<br />
*This method has been tested with {{AUR|zoom}} (desktop client running under {{Pkg|xorg-xwayland}}) and [https://bigbluebutton.org/ BigBlueButton] under {{Pkg|chromium}} (under {{Pkg|firefox}} the resolution is really low); {{AUR|skypeforlinux-stable-bin}} detects the virtual video device {{ic|VirtualVideoDevice}}, but outputs a blank screen.<br />
*The example uses {{ic|wf-recorder}} but you can use whatever software, just feed the output to the virtual device.}}<br />
<br />
Install {{Pkg|wf-recorder}} (or {{AUR|wf-recorder-git}}) and {{Pkg|v4l2loopback-dkms}}. Load the {{ic|v4l2loopback}} kernel module with the following parameters:<br />
<br />
# modprobe v4l2loopback exclusive_caps=1 card_label=VirtualVideoDevice<br />
<br />
Verify that a new virtual video device {{ic|VirtualVideoDevice}} has been created:<br />
<br />
{{hc|$ v4l2-ctl --list-devices|<br />
...<br />
VirtualVideoDevice (platform:v4l2loopback-000):<br />
/dev/video2<br />
... <br />
}}<br />
<br />
Start recording the screen with {{ic|wf-recorder}} and feed the output to the new virtual video device {{ic|VirtualVideoDevice}} created by {{ic|v4l2loopback}}:<br />
<br />
$ wf-recorder --muxer=v4l2 --codec=rawvideo --file=/dev/video2 -x yuv420p<br />
<br />
The {{ic|yuv420p}} colour space is required for the video output to be compatible with Zoom [https://github.com/ammen99/wf-recorder/pull/43].<br />
<br />
You can now select the above virtual video device as your "webcam" in video calling/video conferencing applications (the device is called {{ic|VirtualVideoDevice}}). You can use {{ic|ffplay}} (part of {{Pkg|ffmpeg}}), {{Pkg|mpv}}, or {{ic|gst-launch}} (part of {{Pkg|gstreamer}}) to verify that the virtual video device indeed outputs your screenshare:<br />
<br />
$ ffplay /dev/video2<br />
<br />
$ mpv av://v4l2:/dev/video2<br />
<br />
$ gst-launch-1.0 -v v4l2src device=/dev/video2 ! glimagesink<br />
<br />
If Firefox is unable to read the video stream and prints a message like "AbortError: Starting video failed", try preloading {{ic|v4l2compat.so}}:<br />
$ LD_PRELOAD=/usr/lib/v4l1compat.so firefox<br />
<br />
===== Sharing individual applications =====<br />
<br />
{{Warning|This method does not involve a proper implementation of individual application sharing as the region being shared will not change after resizing any windows.}}<br />
<br />
As explained above, {{ic|wf-recorder}} is able to record only a portion of the screen by first selecting a region with {{Pkg|slurp}}. To use this functionality for sharing a specific region/application window through a virtual video device, start recording the screen with the following modified command:<br />
<br />
$ wf-recorder '''-g "$(slurp)"''' --muxer=v4l2 --codec=rawvideo --file=/dev/video2 -x yuv420p<br />
<br />
After selecting a region of the screen, you will be able to access the video feed through the vitual video device {{ic|/dev/video2}} as above.<br />
<br />
==== Via the WebRTC protocol ====<br />
<br />
{{Note|This method only allows sharing an entire output and not individual applications [https://github.com/emersion/xdg-desktop-portal-wlr/wiki/FAQ#will-this-let-me-share-individual-windows].}}<br />
<br />
See [[PipeWire#WebRTC screen sharing]].<br />
<br />
Chromium and Firefox should now be able to access the screenshare. You can verify this through [https://mozilla.github.io/webrtc-landing/gum_test.html Mozilla's getUserMedia / getDisplayMedia Test Page].<br />
<br />
== Terminal ==<br />
<br />
{{Expansion|Add subsection about [https://intoli.com/blog/terminal-recorders/ terminal recorders].}}<br />
<br />
=== Capture with ANSI codes ===<br />
<br />
You can use the {{man|1|script}} command, part of the {{Pkg|util-linux}} package.<br />
Just run {{ic|script}} and from that moment, all the output is going to be saved to the {{ic|typescript}} file, including the ANSI codes.<br />
<br />
Once you are done, just run {{ic|exit}} and the {{ic|typescript}} would ready. The resulting file can be converted to HTML using the {{AUR|ansi2html}} package, from the [[AUR]]. (Not to be confused with ansi2html from {{Pkg|python-ansi2html}}).<br />
<br />
To convert the {{ic|typescript}} file to {{ic|typescript.html}}, do the following:<br />
<br />
$ ansi2html --bg=dark < typescript > typescript.html<br />
<br />
Actually, '''some''' commands can be piped directly to ansi2html:<br />
<br />
$ ls --color|ansi2html --bg=dark >output.html<br />
<br />
That does not work on every single case, so in those cases, using {{ic|script}} is mandatory.<br />
<br />
=== Framebuffer ===<br />
<br />
Install a [[framebuffer]] and use {{Pkg|fbgrab}} or {{Pkg|fbdump}} to take a screenshot.<br />
<br />
=== Virtual console ===<br />
<br />
If you merely want to capture the text in the console and not an actual image, you can use {{ic|setterm}}, which is part of the {{Pkg|util-linux}} package. The following command will dump the textual contents of virtual console 1 to a file {{ic|screen.dump}} in the current directory:<br />
<br />
# setterm -dump 1 -file screen.dump<br />
<br />
Root permission is needed because the contents of {{ic|/dev/vcs1}} need to be read.</div>Kevrhttps://wiki.archlinux.org/index.php?title=Talk:Arch_IRC_channels&diff=673623Talk:Arch IRC channels2021-05-26T06:36:30Z<p>Kevr: Signed the edit I made.</p>
<hr />
<div>== Matrix ==<br />
<br />
Perhaps we should investigate a migration to matrix. We can bridge with irc so the move would be 100% transparent to existing users.<br />
<br />
[[User:Aleccoder|Aleccoder]] ([[User talk:Aleccoder|talk]]) 18:23, 10 November 2019 (UTC)<br />
<br />
:This has been discussed multiple times and no consensus could be reached but Matrix already runs a freenode bridge: https://matrix.org/blog/2015/06/22/the-matrix-org-irc-bridge-now-bridges-all-of-freenode<br />
: But there would be no "migration" in either case, irc will stay.<br />
:[[User:Namarrgon|Namarrgon]] ([[User talk:Namarrgon|talk]]) 18:55, 10 November 2019 (UTC)<br />
<br />
::Even if irc will stay for some users, I think there should be a noticeable mention of a Matrix channel. I added the [[Matrix]] article to related, but for some reason it was [https://wiki.archlinux.org/index.php?title=Arch_IRC_channels&diff=prev&oldid=668031 removed] as unrelated by [[User:Alad|Alad]]. Then maybe just create a link to this article from main page? Because IRC channels are discoverable, while Matrix are not. I did not even know about existence of that channel, before I knew that Matrix exists and then intentionally searched if the Arch Linux channel exists.<br />
::[[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 13:37, 6 May 2021 (UTC)<br />
<br />
:::There is no official Arch Linux matrix channel, so this is why it was edited out as irrelevant. This is also why [[User:Alad]] removed the mentions of the telegram bridges.<br />
:::--- [[User:NetSysFire|NetSysFire]] ([[User talk:NetSysFire|talk]]) 14:05, 6 May 2021 (UTC)<br />
<br />
::::Arch runs its own [https://gitlab.archlinux.org/archlinux/infrastructure/-/blob/master/docs/matrix.md Matrix homeserver] with IRC bridges for team members, but I don't think you're talking about this. I think the best way to make the options more discoverable would be to improve [[Matrix]], [[List of applications/Internet#IRC clients]] and [[List of applications/Internet#Matrix clients]] somehow. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:42, 9 May 2021 (UTC)<br />
<br />
== Channels list ordered alphabetically ==<br />
<br />
I just edited a bit the channels lists to apply alphabetic order of the channels name. While translating to Portuguese, I felt that the international channels list being order by language name would '''not''' help much the translationg, as the translated language names 1) would make no sense in alphabetic order as they can have another leading letter (e.g. Czech -> Tcheco, in Portuguese), or 2) would require reordering the translated language names which would make harder to keep the translated synchronized with the original page.<br />
<br />
I also reordered the #archlinux-proaudio channel in the "Other channels" section, for the same channel alphabetic order.<br><br />
-- [[User:Josephgbr|Josephgbr]] ([[User talk:Josephgbr|talk]]) 10:04, 24 November 2020 (UTC)<br />
<br />
== Libera IRC ==<br />
<br />
{{Warning|IRC users are required to identify with services before they can take part in official Arch Linux IRC channels, like '''#archlinux'''. The entirety of this '''Libera IRC''' article section should be read.}}<br />
<br />
As of 2021-05-24, Arch Linux has moved its channels to https://libera.chat. See https://archlinux.org/news/move-of-official-irc-channels-to-liberachat/ for details about why.<br />
<br />
Because https://libera.chat is a new network, some guidance can help users migrate and/or get onto Libera securely.<br />
<br />
=== Connect to Libera ===<br />
<br />
See https://libera.chat/guides/connect for upstream documentation on connecting to Libera's IRC network.<br />
<br />
=== Register with NickServ ===<br />
<br />
Primary Arch Linux channels, like '''#archlinux''', require a user of the IRC network to be registered and identified in order to participate in conversation. In order to register and identify your nickname with the Libera network, one can follow their upstream guide: https://libera.chat/guides/registration.<br />
<br />
=== Cloak Yourself ===<br />
<br />
When using IRC, a ''cloak'' can be used to obfuscate network addresses used to connect to a network from other users on the network. This can help a lot to reduce the possibility of DDOS and attacks in general.<br />
<br />
This is done by giving a user a "fake" host, in the form of '''user/<nickname>'''. When a cloaked user is {{ic|/whois}}'d, the following information is gained: {{ic|nickname!~username@user/nickname}}.<br />
<br />
Gaining a cloak is highly recommended for all users of Libera.<br />
<br />
To gain a cloak, make sure you are first logged into services by identifying yourself with NickServ and perform the following actions on {{ic|irc.libera.chat}}.<br />
<br />
/join #libera-cloak<br />
/msg #libera-cloak !cloakme<br />
<br />
After sending the {{ic|!cloakme}} command, you will be kicked from the channel and receive a user cloak which persists with your NickServ account. This can be verified by performing a {{ic|/whois <irc_nickname>}} on yourself.<br />
<br />
=== SASL Authentication ===<br />
<br />
For further protection, users can configure ''SASL Authentication'' for their IRC clients, which performs the identification step at connection. This removes any time where your host may be exposed in the case a user has gained a cloak.<br />
<br />
Please see https://libera.chat/guides/sasl for upstream documentation on configuring SASL on Libera for various common IRC clients.<br />
<br />
[[User:Kevr|Kevr]] ([[User talk:Kevr|talk]]) 06:36, 26 May 2021 (UTC)<br />
<br />
== Channel names that changed with the migration from freenode to Libera Chat ==<br />
<br />
Some of the revisions preceding [[Special:Diff/673308|Diff/673308]] changed the channel links to point to Libera Chat instead of freenode. However, '''#archlinux.de''' on freenode is now known as '''#archlinux-de''' on Libera Chat (with a hyphen instead of a period). I'm not sure if any of the other international IRC channels are going to make (or have made) this change as well. -- [[User:Flyingpig|Flyingpig]] ([[User talk:Flyingpig|talk]]) 01:33, 25 May 2021 (UTC)<br />
<br />
: #archlinux.dk will be changed to #archlinux-dk. I'm not aware of any other changes. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 04:42, 25 May 2021 (UTC)</div>Kevrhttps://wiki.archlinux.org/index.php?title=Talk:Arch_IRC_channels&diff=673613Talk:Arch IRC channels2021-05-26T02:56:06Z<p>Kevr: Include details for users about irc.libera.chat and point them to documentation and/or cloak information.</p>
<hr />
<div>== Matrix ==<br />
<br />
Perhaps we should investigate a migration to matrix. We can bridge with irc so the move would be 100% transparent to existing users.<br />
<br />
[[User:Aleccoder|Aleccoder]] ([[User talk:Aleccoder|talk]]) 18:23, 10 November 2019 (UTC)<br />
<br />
:This has been discussed multiple times and no consensus could be reached but Matrix already runs a freenode bridge: https://matrix.org/blog/2015/06/22/the-matrix-org-irc-bridge-now-bridges-all-of-freenode<br />
: But there would be no "migration" in either case, irc will stay.<br />
:[[User:Namarrgon|Namarrgon]] ([[User talk:Namarrgon|talk]]) 18:55, 10 November 2019 (UTC)<br />
<br />
::Even if irc will stay for some users, I think there should be a noticeable mention of a Matrix channel. I added the [[Matrix]] article to related, but for some reason it was [https://wiki.archlinux.org/index.php?title=Arch_IRC_channels&diff=prev&oldid=668031 removed] as unrelated by [[User:Alad|Alad]]. Then maybe just create a link to this article from main page? Because IRC channels are discoverable, while Matrix are not. I did not even know about existence of that channel, before I knew that Matrix exists and then intentionally searched if the Arch Linux channel exists.<br />
::[[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 13:37, 6 May 2021 (UTC)<br />
<br />
:::There is no official Arch Linux matrix channel, so this is why it was edited out as irrelevant. This is also why [[User:Alad]] removed the mentions of the telegram bridges.<br />
:::--- [[User:NetSysFire|NetSysFire]] ([[User talk:NetSysFire|talk]]) 14:05, 6 May 2021 (UTC)<br />
<br />
::::Arch runs its own [https://gitlab.archlinux.org/archlinux/infrastructure/-/blob/master/docs/matrix.md Matrix homeserver] with IRC bridges for team members, but I don't think you're talking about this. I think the best way to make the options more discoverable would be to improve [[Matrix]], [[List of applications/Internet#IRC clients]] and [[List of applications/Internet#Matrix clients]] somehow. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:42, 9 May 2021 (UTC)<br />
<br />
== Channels list ordered alphabetically ==<br />
<br />
I just edited a bit the channels lists to apply alphabetic order of the channels name. While translating to Portuguese, I felt that the international channels list being order by language name would '''not''' help much the translationg, as the translated language names 1) would make no sense in alphabetic order as they can have another leading letter (e.g. Czech -> Tcheco, in Portuguese), or 2) would require reordering the translated language names which would make harder to keep the translated synchronized with the original page.<br />
<br />
I also reordered the #archlinux-proaudio channel in the "Other channels" section, for the same channel alphabetic order.<br><br />
-- [[User:Josephgbr|Josephgbr]] ([[User talk:Josephgbr|talk]]) 10:04, 24 November 2020 (UTC)<br />
<br />
== Libera IRC ==<br />
<br />
{{Warning|IRC users are required to identify with services before they can take part in official Arch Linux IRC channels, like '''#archlinux'''. The entirety of this '''Libera IRC''' article section should be read.}}<br />
<br />
As of 2021-05-24, Arch Linux has moved its channels to https://libera.chat. See https://archlinux.org/news/move-of-official-irc-channels-to-liberachat/ for details about why.<br />
<br />
Because https://libera.chat is a new network, some guidance can help users migrate and/or get onto Libera securely.<br />
<br />
=== Connect to Libera ===<br />
<br />
See https://libera.chat/guides/connect for upstream documentation on connecting to Libera's IRC network.<br />
<br />
=== Register with NickServ ===<br />
<br />
Primary Arch Linux channels, like '''#archlinux''', require a user of the IRC network to be registered and identified in order to participate in conversation. In order to register and identify your nickname with the Libera network, one can follow their upstream guide: https://libera.chat/guides/registration.<br />
<br />
=== Cloak Yourself ===<br />
<br />
When using IRC, a ''cloak'' can be used to obfuscate network addresses used to connect to a network from other users on the network. This can help a lot to reduce the possibility of DDOS and attacks in general.<br />
<br />
This is done by giving a user a "fake" host, in the form of '''user/<nickname>'''. When a cloaked user is {{ic|/whois}}'d, the following information is gained: {{ic|nickname!~username@user/nickname}}.<br />
<br />
Gaining a cloak is highly recommended for all users of Libera.<br />
<br />
To gain a cloak, make sure you are first logged into services by identifying yourself with NickServ and perform the following actions on {{ic|irc.libera.chat}}.<br />
<br />
/join #libera-cloak<br />
/msg #libera-cloak !cloakme<br />
<br />
After sending the {{ic|!cloakme}} command, you will be kicked from the channel and receive a user cloak which persists with your NickServ account. This can be verified by performing a {{ic|/whois <irc_nickname>}} on yourself.<br />
<br />
=== SASL Authentication ===<br />
<br />
For further protection, users can configure ''SASL Authentication'' for their IRC clients, which performs the identification step at connection. This removes any time where your host may be exposed in the case a user has gained a cloak.<br />
<br />
Please see https://libera.chat/guides/sasl for upstream documentation on configuring SASL on Libera for various common IRC clients.<br />
<br />
== Channel names that changed with the migration from freenode to Libera Chat ==<br />
<br />
Some of the revisions preceding [[Special:Diff/673308|Diff/673308]] changed the channel links to point to Libera Chat instead of freenode. However, '''#archlinux.de''' on freenode is now known as '''#archlinux-de''' on Libera Chat (with a hyphen instead of a period). I'm not sure if any of the other international IRC channels are going to make (or have made) this change as well. -- [[User:Flyingpig|Flyingpig]] ([[User talk:Flyingpig|talk]]) 01:33, 25 May 2021 (UTC)<br />
<br />
: #archlinux.dk will be changed to #archlinux-dk. I'm not aware of any other changes. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 04:42, 25 May 2021 (UTC)</div>Kevrhttps://wiki.archlinux.org/index.php?title=System76_Oryx_Pro&diff=580876System76 Oryx Pro2019-08-25T07:22:09Z<p>Kevr: /* Suspend/Hibernate */ Rename section.</p>
<hr />
<div>== Installation ==<br />
<br />
The System76 Oryx Pro comes with two NVMe M.2 slots, as well as space for a 2.5" SSD/HDD. Booting from NVMe requires the use of EFI, while booting over SATA/AHCI does not. Typically EFI would be a safe-to-use method for this laptop overall.<br />
<br />
== Drivers ==<br />
<br />
The System76 Oryx Pro has customized utilities and daemons that assist with running the Oryx Pro nicely under Linux. This includes driver (graphical, io, fan) configuration, firmware updates, and LED control.<br />
<br />
System76 produces a distribution called Pop OS! which they install on their machines. This guide is meant to align drivers and graphical configurations with the style that Pop OS! chooses, which seems to be best for these configurations.<br />
<br />
The collection of drivers can be found in the AUR.<br />
<br />
{{AUR|system76-driver}}<br />
<br />
{{AUR|system76-dkms}}<br />
<br />
{{AUR|system76-io-dkms}}<br />
<br />
{{AUR|system76-firmware-daemon}}<br />
<br />
{{AUR|system76-power}}<br />
<br />
There are also -git versions of many of these packages, if you wish to stay bleeding edge.<br />
<br />
== Graphical ==<br />
<br />
This system comes complete with an integrated (intel) and discrete (nvidia) graphics card. The external ports (DP over Mini-DP, DP over USB-C, HDMI) are tied to the discrete nvidia card. Some users have reported getting this to work right with Bumblebee.<br />
<br />
When in doubt, remove bumblebee and install nvidia proprietary drivers.<br />
<br />
Your mileage may vary if you're using a more complete DE like Gnome; this has only been tested with i3-wm.<br />
<br />
== Audio ==<br />
<br />
Audio seems to work out of the box with a USB headset, however, it does not relay audio to the onboard speaker. This section needs to be feature complete with workarounds for any issues.<br />
<br />
== Suspend/Hibernate ==<br />
<br />
Out of the box, Arch Linux does not resume a previously suspended or hibernated session. This section needs to be feature complete with workarounds for any issues.</div>Kevrhttps://wiki.archlinux.org/index.php?title=System76_Oryx_Pro&diff=580871System76 Oryx Pro2019-08-25T05:53:45Z<p>Kevr: Include some audio information, sleep/hibernate awareness of issues</p>
<hr />
<div>== Installation ==<br />
<br />
The System76 Oryx Pro comes with two NVMe M.2 slots, as well as space for a 2.5" SSD/HDD. Booting from NVMe requires the use of EFI, while booting over SATA/AHCI does not. Typically EFI would be a safe-to-use method for this laptop overall.<br />
<br />
== Drivers ==<br />
<br />
The System76 Oryx Pro has customized utilities and daemons that assist with running the Oryx Pro nicely under Linux. This includes driver (graphical, io, fan) configuration, firmware updates, and LED control.<br />
<br />
System76 produces a distribution called Pop OS! which they install on their machines. This guide is meant to align drivers and graphical configurations with the style that Pop OS! chooses, which seems to be best for these configurations.<br />
<br />
The collection of drivers can be found in the AUR.<br />
<br />
{{AUR|system76-driver}}<br />
<br />
{{AUR|system76-dkms}}<br />
<br />
{{AUR|system76-io-dkms}}<br />
<br />
{{AUR|system76-firmware-daemon}}<br />
<br />
{{AUR|system76-power}}<br />
<br />
There are also -git versions of many of these packages, if you wish to stay bleeding edge.<br />
<br />
== Graphical ==<br />
<br />
This system comes complete with an integrated (intel) and discrete (nvidia) graphics card. The external ports (DP over Mini-DP, DP over USB-C, HDMI) are tied to the discrete nvidia card. Some users have reported getting this to work right with Bumblebee.<br />
<br />
When in doubt, remove bumblebee and install nvidia proprietary drivers.<br />
<br />
Your mileage may vary if you're using a more complete DE like Gnome; this has only been tested with i3-wm.<br />
<br />
== Audio ==<br />
<br />
Audio seems to work out of the box with a USB headset, however, it does not relay audio to the onboard speaker. This section needs to be feature complete with workarounds for any issues.<br />
<br />
== Sleep/Hibernate ==<br />
<br />
Out of the box, Arch Linux does not resume a previously slept or hibernated session. This section needs to be feature complete with workarounds for any issues.</div>Kevrhttps://wiki.archlinux.org/index.php?title=System76_Oryx_Pro&diff=580731System76 Oryx Pro2019-08-23T02:16:51Z<p>Kevr: /* Graphical */ Make this segment impersonal</p>
<hr />
<div>== Installation ==<br />
<br />
The System76 Oryx Pro comes with two NVMe M.2 slots, as well as space for a 2.5" SSD/HDD. Booting from NVMe requires the use of EFI, while booting over SATA/AHCI does not. Typically EFI would be a safe-to-use method for this laptop overall.<br />
<br />
== Drivers ==<br />
<br />
The System76 Oryx Pro has customized utilities and daemons that assist with running the Oryx Pro nicely under Linux. This includes driver (graphical, io, fan) configuration, firmware updates, and LED control.<br />
<br />
System76 produces a distribution called Pop OS! which they install on their machines. This guide is meant to align drivers and graphical configurations with the style that Pop OS! chooses, which seems to be best for these configurations.<br />
<br />
The collection of drivers can be found in the AUR.<br />
<br />
{{AUR|system76-driver}}<br />
<br />
{{AUR|system76-dkms}}<br />
<br />
{{AUR|system76-io-dkms}}<br />
<br />
{{AUR|system76-firmware-daemon}}<br />
<br />
{{AUR|system76-power}}<br />
<br />
There are also -git versions of many of these packages, if you wish to stay bleeding edge.<br />
<br />
== Graphical ==<br />
<br />
This system comes complete with an integrated (intel) and discrete (nvidia) graphics card. The external ports (DP over Mini-DP, DP over USB-C, HDMI) are tied to the discrete nvidia card. Some users have reported getting this to work right with Bumblebee.<br />
<br />
When in doubt, remove bumblebee and install nvidia proprietary drivers.<br />
<br />
Your mileage may vary if you're using a more complete DE like Gnome; this has only been tested with i3-wm.</div>Kevrhttps://wiki.archlinux.org/index.php?title=System76_Oryx_Pro&diff=580730System76 Oryx Pro2019-08-23T02:14:50Z<p>Kevr: Introduction to some help regarding Oryx Pro. This needs to be more complete with included software matrix tables for EFI/Disks etc</p>
<hr />
<div>== Installation ==<br />
<br />
The System76 Oryx Pro comes with two NVMe M.2 slots, as well as space for a 2.5" SSD/HDD. Booting from NVMe requires the use of EFI, while booting over SATA/AHCI does not. Typically EFI would be a safe-to-use method for this laptop overall.<br />
<br />
== Drivers ==<br />
<br />
The System76 Oryx Pro has customized utilities and daemons that assist with running the Oryx Pro nicely under Linux. This includes driver (graphical, io, fan) configuration, firmware updates, and LED control.<br />
<br />
System76 produces a distribution called Pop OS! which they install on their machines. This guide is meant to align drivers and graphical configurations with the style that Pop OS! chooses, which seems to be best for these configurations.<br />
<br />
The collection of drivers can be found in the AUR.<br />
<br />
{{AUR|system76-driver}}<br />
<br />
{{AUR|system76-dkms}}<br />
<br />
{{AUR|system76-io-dkms}}<br />
<br />
{{AUR|system76-firmware-daemon}}<br />
<br />
{{AUR|system76-power}}<br />
<br />
There are also -git versions of many of these packages, if you wish to stay bleeding edge.<br />
<br />
== Graphical ==<br />
<br />
This system comes complete with an integrated (intel) and discrete (nvidia) graphics card. The external ports (DP over Mini-DP, DP over USB-C, HDMI) are tied to the discrete nvidia card. Some users have reported getting this to work right with Bumblebee, however, during my attempts, I felt it was unnecessary to run Bumblebee as I prefer always running on the discrete nvidia chip.<br />
<br />
When in doubt, remove bumblebee and install nvidia proprietary drivers.</div>Kevrhttps://wiki.archlinux.org/index.php?title=User:Kevr&diff=580729User:Kevr2019-08-23T01:49:10Z<p>Kevr: Created page with "A person named "Kevin Morris," who frequents #archlinux and #archlinux-offtopic on Freenode as "kevr.""</p>
<hr />
<div>A person named "Kevin Morris," who frequents #archlinux and #archlinux-offtopic on Freenode as "kevr."</div>Kevrhttps://wiki.archlinux.org/index.php?title=Virtual_user_mail_system_with_Postfix,_Dovecot_and_Roundcube&diff=457592Virtual user mail system with Postfix, Dovecot and Roundcube2016-11-24T01:51:39Z<p>Kevr: Updated PostfixAdmin section to give some vital information about the directory tree.</p>
<hr />
<div>[[Category:Mail server]]<br />
[[ja:仮想ユーザーメールシステム]]<br />
{{Related articles start}}<br />
{{Related|Courier MTA}}<br />
{{Related|OpenDKIM}}<br />
{{Related|Postfix}}<br />
{{Related|SOGo}}<br />
{{Related articles end}}<br />
This article describes how to set up a complete virtual user mail system on an Arch Linux system in the simplest manner possible. However, since a mail system consists of many complex components, quite a bit of configuration will still be necessary. <br />
<br />
Roughly, the components used in this article are Postfix as the mail server, Dovecot as the IMAP server, Roundcube as the webmail interface and PostfixAdmin as the administration interface to manage it all.<br />
<br />
In the end, the provided solution will allow you to use the best currently available security mechanisms, you will be able to send mails using SMTP and SMTPS and receive mails using POP3, POP3S, IMAP and IMAPS. Additionally, configuration will be easy thanks to PostfixAdmin and users will be able to login using Roundcube. What a deal!<br />
<br />
== Installation ==<br />
Before you start, you must have both a working MySQL server as described in [[MySQL]] and a working Postfix server as described in [[Postfix]].<br />
<br />
[[Install]] the {{Pkg|dovecot}} and {{Pkg|roundcubemail}} packages.<br />
<br />
== Configuration ==<br />
=== User ===<br />
For security reasons, a new user should be created to store the mails:<br />
# groupadd -g 5000 vmail<br />
# useradd -u 5000 -g vmail -s /usr/bin/nologin -d /home/vmail -m vmail<br />
A gid and uid of 5000 is used in both cases so that we do not run into conflicts with regular users. All your mail will then be stored in {{ic|/home/vmail}}. You could change the home directory to something like {{ic|/var/mail/vmail}} but be careful to change this in any configuration below as well.<br />
<br />
=== Database ===<br />
You will need to create an empty database and corresponding user. In this article, the user ''postfix_user'' will have read/write access to the database ''postfix_db'' using ''hunter2'' as password. You are expected to create the database and user yourself, and give the user permission to use the database, as shown in the following code.<br />
<br />
{{hc|$ mysql -u root -p|<br />
CREATE DATABASE postfix_db;<br />
GRANT ALL ON postfix_db.* TO 'postfix_user'@'localhost' IDENTIFIED BY 'hunter2';<br />
FLUSH PRIVILEGES;<br />
}}<br />
<br />
{{Expansion|Further manual database installation is missing. So far, the only way to follow this article is by installing PostfixAdmin with Apache, MySQL and PHP.}}<br />
<br />
Now you can go to the PostfixAdmin's setup page, let PostfixAdmin create the needed tables and create the users in there.<br />
<br />
==== PostfixAdmin ====<br />
See [[Postfix#PostfixAdmin]].<br />
<br />
=== SSL certificate ===<br />
You will need a SSL certificate for all encrypted mail communications (SMTPS/IMAPS/POP3S). If you do not have one, create one:<br />
# cd /etc/ssl/private/<br />
# openssl req -new -x509 -nodes -newkey rsa:4096 -keyout vmail.key -out vmail.crt -days 1460 #days are optional<br />
# chmod 400 vmail.key<br />
# chmod 444 vmail.crt<br />
<br />
=== Postfix ===<br />
<br />
==== SMTPS ====<br />
<br />
Enable secure SMTP as described in [[Postfix#Secure SMTP]]. <br />
<br />
==== Prerequisites ====<br />
<br />
Before you copy&paste the configuration below, check if {{ic|relay_domains}} has already been already set. If you leave more than one active, you will receive warnings during runtime.<br />
<br />
{{Warning|{{ic|<nowiki>relay_domains</nowiki>}} can be dangerous. You usually do not want Postfix to forward mail of strangers. {{ic|<nowiki>$mydestination</nowiki>}} is a sane default value. Double check it's value before running postfix! See http://www.postfix.org/BASIC_CONFIGURATION_README.html#relay_to}} <br />
<br />
Also check if your SSL certificate paths are set right in all upcoming config examples.<br />
<br />
==== Setting up Postfix ====<br />
<br />
To {{ic|/etc/postfix/main.cf}} append:<br />
relay_domains = $mydestination<br />
virtual_alias_maps = proxy:mysql:/etc/postfix/virtual_alias_maps.cf<br />
virtual_mailbox_domains = proxy:mysql:/etc/postfix/virtual_mailbox_domains.cf<br />
virtual_mailbox_maps = proxy:mysql:/etc/postfix/virtual_mailbox_maps.cf<br />
virtual_mailbox_base = /home/vmail<br />
virtual_mailbox_limit = 512000000<br />
virtual_minimum_uid = 5000<br />
virtual_transport = virtual<br />
virtual_uid_maps = static:5000<br />
virtual_gid_maps = static:5000<br />
local_transport = virtual<br />
local_recipient_maps = $virtual_mailbox_maps<br />
transport_maps = hash:/etc/postfix/transport<br />
<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = /var/run/dovecot/auth-client<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
smtpd_relay_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
smtpd_sasl_security_options = noanonymous<br />
smtpd_sasl_tls_security_options = $smtpd_sasl_security_options<br />
smtpd_tls_security_level = may<br />
smtpd_tls_auth_only = yes<br />
smtpd_tls_received_header = yes<br />
smtpd_tls_cert_file = /etc/ssl/private/vmail.crt<br />
smtpd_tls_key_file = /etc/ssl/private/vmail.key<br />
smtpd_sasl_local_domain = $mydomain<br />
broken_sasl_auth_clients = yes<br />
smtpd_tls_loglevel = 1<br />
<br />
* In the configuration above {{ic|virtual_mailbox_domains}} is a list of the domains that you want to receive mail for. This CANNOT contain the domain that is set in {{ic|mydestination}}. That is why we left {{ic|mydestination}} to be localhost only.<br />
<br />
* {{ic|virtual_mailbox_maps}} will contain the information of virtual users and their mailbox locations. We are using a hash file to store the more permanent maps, and these will then override the forwards in the MySQL database.<br />
<br />
* {{ic|virtual_mailbox_base}} is the base directory where the virtual mailboxes will be stored.<br />
<br />
The {{ic|virtual_uid_maps}} and {{ic|virtual_gid_maps}} are the real system user IDs that the virtual mails will be owned by. This is for storage purposes. <br />
<br />
{{note|Since we will be using a web interface (Roundcube), and do not want people accessing this by any other means, we will be creating this account later without providing any login access.}}<br />
<br />
==== Create the file structure ====<br />
<br />
Those new additional settings reference a lot of files that do not even exist yet. We will create them with the following steps.<br />
<br />
If you were setting up your database with PostfixAdmin and created the database schema through PostfixAdmin, you can create the following files. Do not forget to change the password:<br />
<br />
{{hc|/etc/postfix/virtual_alias_maps.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = alias<br />
select_field = goto<br />
where_field = address<br />
</nowiki>}}<br />
<br />
{{hc|/etc/postfix/virtual_mailbox_domains.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = domain<br />
select_field = domain<br />
where_field = domain<br />
</nowiki>}}<br />
<br />
{{hc|/etc/postfix/virtual_mailbox_maps.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = mailbox<br />
select_field = maildir<br />
where_field = username<br />
</nowiki>}}<br />
<br />
{{Note | For setups without using PostfixAdmin, create the following files.}}<br />
<br />
{{hc|/etc/postfix/virtual_alias_maps.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = domains<br />
select_field = virtual<br />
where_field = domain<br />
</nowiki>}}<br />
<br />
{{hc|/etc/postfix/virtual_mailbox_domains.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = forwardings<br />
select_field = destination<br />
where_field = source<br />
</nowiki>}}<br />
<br />
{{hc|/etc/postfix/virtual_mailbox_maps.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = users<br />
select_field = concat(domain,'/',email,'/')<br />
where_field = email<br />
</nowiki>}}<br />
<br />
Run ''postmap'' on ''transport'' to generate its db:<br />
# postmap /etc/postfix/transport<br />
<br />
=== Dovecot ===<br />
<br />
Instead of using the provided Dovecot example config file, we'll create our own {{ic|/etc/dovecot/dovecot.conf}}. Please note that the user and group here might be vmail '''instead of postfix'''!<br />
<br />
{{hc|/etc/dovecot/dovecot.conf|<nowiki><br />
protocols = imap pop3<br />
auth_mechanisms = plain<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf<br />
}<br />
userdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf<br />
}<br />
<br />
service auth {<br />
unix_listener auth-client {<br />
group = postfix<br />
mode = 0660<br />
user = postfix<br />
}<br />
user = root<br />
}<br />
<br />
mail_home = /home/vmail/%d/%n<br />
mail_location = maildir:~<br />
<br />
ssl_cert = </etc/ssl/private/vmail.crt<br />
ssl_key = </etc/ssl/private/vmail.key<br />
</nowiki>}}<br />
<br />
{{note|If you instead want to modify {{ic|dovecot.conf.sample}}, beware that the default configuration file imports the content of {{ic|conf.d/*.conf}}. Those files call other files that aren't present in our configuration.}}<br />
<br />
Now we create {{ic|/etc/dovecot/dovecot-sql.conf}}, which we just referenced in the config above. Use the following contents and check if everything is set accordingly to your system's configuration.<br />
<br />
If you used PostfixAdmin, then you add the following:<br />
<br />
{{hc|/etc/dovecot/dovecot-sql.conf|<nowiki><br />
driver = mysql<br />
connect = host=localhost dbname=postfix_db user=postfix_user password=hunter2<br />
# It is highly recommended to not use deprecated MD5-CRYPT. Read more at http://wiki2.dovecot.org/Authentication/PasswordSchemes<br />
default_pass_scheme = SHA512-CRYPT<br />
# Get the mailbox<br />
user_query = SELECT '/home/vmail/%d/%n' as home, 'maildir:/home/vmail/%d/%n' as mail, 5000 AS uid, 5000 AS gid, concat('dirsize:storage=', quota) AS quota FROM mailbox WHERE username = '%u' AND active = '1'<br />
# Get the password<br />
password_query = SELECT username as user, password, '/home/vmail/%d/%n' as userdb_home, 'maildir:/home/vmail/%d/%n' as userdb_mail, 5000 as userdb_uid, 5000 as userdb_gid FROM mailbox WHERE username = '%u' AND active = '1'<br />
# If using client certificates for authentication, comment the above and uncomment the following<br />
#password_query = SELECT null AS password, ‘%u’ AS user<br />
</nowiki>}}<br />
<br />
Without having used PostfixAdmin you can use:<br />
<br />
{{hc|/etc/dovecot/dovecot-sql.conf|<nowiki><br />
driver = mysql<br />
connect = host=localhost dbname=postfix_db user=postfix_user password=hunter2<br />
# It is highly recommended to not use deprecated MD5-CRYPT. Read more at http://wiki2.dovecot.org/Authentication/PasswordSchemes<br />
default_pass_scheme = SHA512-CRYPT<br />
# Get the mailbox<br />
user_query = SELECT '/home/vmail/%d/%n' as home, 'maildir:/home/vmail/%d/%n' as mail, 5000 AS uid, 5000 AS gid, concat('dirsize:storage=', quota) AS quota FROM users WHERE email = '%u'<br />
# Get the password<br />
password_query = SELECT email as user, password, '/home/vmail/%d/%n' as userdb_home, 'maildir:/home/vmail/%d/%n' as userdb_mail, 5000 as userdb_uid, 5000 as userdb_gid FROM users WHERE email = '%u'<br />
# If using client certificates for authentication, comment the above and uncomment the following<br />
#password_query = SELECT null AS password, ‘%u’ AS user<br />
</nowiki>}}<br />
<br />
{{tip | Visit http://wiki2.dovecot.org/Variables to learn more about Dovecot variables.}}<br />
<br />
=== PostfixAdmin ===<br />
See [[Postfix#PostfixAdmin]].<br />
<br />
Note: To match the configuration in this file, config.inc.php should contain the following.<br />
<br />
# /etc/postfixadmin/config.inc.php<br />
...<br />
$CONF['domain_path'] = 'YES';<br />
$CONF['domain_in_mailbox'] = 'NO';<br />
...<br />
<br />
=== Roundcube ===<br />
<br />
Make sure that both the {{ic|pdo_mysql.so}} extension and {{ic|iconv.so}} extension are uncommented in your {{ic|php.ini}} file. Also check the {{ic|.htaccess}} for access restrictions. Assuming that localhost is your current host, navigate a browser to {{ic|http://localhost/roundcube/installer/}} and follow the instructions. <br />
<br />
Roundcube needs a separate database to work. You should not use the same database for Roundcube and PostfixAdmin. Create a second database {{ic|roundcube_db}} and a new user named {{ic|roundcube_user}}.<br />
<br />
While running the installer ...<br />
<br />
* Make sure to address of the IMAP host is {{ic|ssl://localhost/}} or {{ic|tls://localhost/}} and not just {{ic|localhost}}. <br />
* Use port {{ic|993}}. Likewise with SMTP. <br />
* Make sure to provide {{ic|ssl://localhost/}} with port {{ic|465}} if you used the wrapper mode<br />
* and use {{ic|tls://localhost/}} port {{ic|587}} if you used the proper TLS mode. <br />
* See [[#Postfix|here]] for an explanation on that.<br />
<br />
The post install process is similar to any other webapp like [[PhpMyAdmin]] or PostFixAdmin. The configuration file is in {{ic|/etc/webapps/roundcubemail/config/config.inc.php}} which works as an override over {{ic|default.inc.php}}.<br />
<br />
==== Apache configuration ====<br />
<br />
If you are using Apache, copy the example configuration file to your webserver configuration directory.<br />
<br />
# cp /etc/webapps/roundcubemail/apache.conf /etc/httpd/conf/extra/httpd-roundcubemail.conf<br />
<br />
Add the following line in<br />
<br />
{{hc|/etc/httpd/conf/httpd.conf|<nowiki><br />
Include conf/extra/httpd-roundcubemail.conf<br />
</nowiki>}}<br />
<br />
==== Roundcube: Change Password Plugin ====<br />
<br />
To let users change their passwords from within Roundcube, do the following:<br />
<br />
Enable the password plugin by adding this line to<br />
<br />
{{hc|/etc/webapps/roundcubemail/config/config.inc.php|<nowiki><br />
$rcmail_config['plugins'] = array('password');<br />
</nowiki>}}<br />
<br />
Configure the password plugin and make sure you alter the settings accordingly:<br />
<br />
{{hc|/usr/share/webapps/roundcubemail/plugins/password/config.inc.php|<nowiki><br />
$config['password_driver'] = 'sql';<br />
$config['password_db_dsn'] = 'mysql://<postfix_database_user>:<password>@localhost/<postfix_database_name>';<br />
## for dovecot salted passwords only<br />
# $config['password_dovecotpw'] = 'doveadm pw';<br />
# $config['password_dovecotpw_method'] = 'SHA512-CRYPT';<br />
# $config['password_dovecotpw_with_method'] = true;<br />
$config['password_query'] = 'UPDATE mailbox SET password=%c WHERE username=%u';<br />
</nowiki>}}<br />
<br />
== Fire it up ==<br />
All necessary daemons should be started in order to test the configuration. [[Start]] both {{ic|postfix}} and {{ic|dovecot}}.<br />
<br />
Now for testing purposes, create a domain and mail account in PostfixAdmin. Try to login to this account using Roundcube. Now send yourself a mail.<br />
<br />
== Optional Items ==<br />
Although these items are not required, they definitely add more completeness to your setup<br />
<br />
=== Quota ===<br />
To enable mailbox quota support by dovecot, do the following: <br />
*First add the following lines to /etc/dovecot/dovecot.conf<br />
dict {<br />
quotadict = mysql:/etc/dovecot/dovecot-dict-sql.conf.ext<br />
}<br />
service dict {<br />
unix_listener dict {<br />
group = vmail<br />
mode = 0660<br />
user = vmail<br />
}<br />
user = root<br />
}<br />
service quota-warning {<br />
executable = script /usr/local/bin/quota-warning.sh<br />
user = vmail<br />
unix_listener quota-warning {<br />
group = vmail<br />
mode = 0660<br />
user = vmail<br />
}<br />
} <br />
mail_plugins=quota<br />
protocol pop3 {<br />
mail_plugins = quota<br />
pop3_client_workarounds = outlook-no-nuls oe-ns-eoh<br />
pop3_uidl_format = %08Xu%08Xv<br />
}<br />
protocol lda {<br />
mail_plugins = quota<br />
postmaster_address = postmaster@yourdomain.com<br />
}<br />
protocol imap {<br />
mail_plugins = $mail_plugins imap_quota<br />
mail_plugin_dir = /usr/lib/dovecot/modules<br />
}<br />
plugin {<br />
quota = dict:User quota::proxy::quotadict<br />
quota_rule2 = Trash:storage=+10%%<br />
quota_warning = storage=100%% quota-warning +100 %u<br />
quota_warning2 = storage=95%% quota-warning +95 %u<br />
quota_warning3 = storage=80%% quota-warning +80 %u<br />
quota_warning4 = -storage=100%% quota-warning -100 %u # user is no longer over quota<br />
}<br />
<br />
*Create a new file /etc/dovecot/dovecot-dict-sql.conf.ext with the following code:<br />
connect = host=localhost dbname=yourdb user=youruser password=yourpassword<br />
map {<br />
pattern = priv/quota/storage<br />
table = quota2<br />
username_field = username<br />
value_field = bytes<br />
}<br />
map {<br />
pattern = priv/quota/messages<br />
table = quota2<br />
username_field = username<br />
value_field = messages<br />
}<br />
*Create a warning script /usr/local/bin/quota-warning.sh and make sure it is executable. This warning script works with postfix lmtp configuration as well.<br />
<pre> #!/bin/sh<br />
BOUNDARY="$1"<br />
USER="$2"<br />
MSG=""<br />
if [[ "$BOUNDARY" = "+100" ]]; then<br />
MSG="Your mailbox is now overfull (>100%). In order for your account to continue functioning properly, you need to remove some emails NOW."<br />
elif [[ "$BOUNDARY" = "+95" ]]; then<br />
MSG="Your mailbox is now over 95% full. Please remove some emails ASAP."<br />
elif [[ "$BOUNDARY" = "+80" ]]; then<br />
MSG="Your mailbox is now over 80% full. Please consider removing some emails to save space."<br />
elif [[ "$BOUNDARY" = "-100" ]]; then<br />
MSG="Your mailbox is now back to normal (<100%)."<br />
fi<br />
<br />
cat << EOF | /usr/lib/dovecot/dovecot-lda -d $USER -o "plugin/quota=maildir:User quota:noenforcing"<br />
From: postmaster@yourdomain.com<br />
Subject: Email Account Quota Warning<br />
<br />
Dear User,<br />
<br />
$MSG<br />
<br />
Best regards,<br />
Your Mail System<br />
EOF<br />
</pre><br />
<br />
*Edit the user_query line and add iterat_query in dovecot-sql.conf as following:<br />
user_query = SELECT '/home/vmail/%d/%n' as home, 'maildir:/home/vmail/%d/%n' as mail, 5000 AS uid, 5000 AS gid, concat('*:bytes=', quota) AS quota_rule FROM mailbox WHERE username = '%u' AND active = '1'<br />
iterate_query = SELECT username AS user FROM mailbox<br />
*Set up LDA as described above under SpamAssassin. If you're not using SpamAssassin, the pipe should look like this in /etc/postfix/master.cf :<br />
dovecot unix - n n - - pipe<br />
flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -f ${sender} -d ${recipient}<br />
As above activate it in Postfix main.cf<br />
virtual_transport = dovecot<br />
*You can set up quota per each mailbox in postfixadmin. Make sure the relevant lines in config.inc.php look like this:<br />
$CONF['quota'] = 'YES';<br />
$CONF['quota_multiplier'] = '1024000';<br />
<br />
Restart postfix and dovecot services. If things go well, you should be able to list all users' quota and usage by the this command:<br />
doveadm quota get -A<br />
You should be able to see the quota in roundcube too.<br />
<br />
== Sidenotes ==<br />
<br />
=== Alternative vmail folder structure ===<br />
<br />
Instead of having a directory structure like {{ic|/home/vmail/example.com/user@example.com}} you can have cleaner subdirectories (without the additional domain name) by replacing {{ic|select_field}} and {{ic|where_field}} with:<br />
{{bc|1=query = SELECT CONCAT(SUBSTRING_INDEX(email,'@',-1),'/',SUBSTRING_INDEX(email,'@',1),'/') FROM users WHERE email='%s'}}<br />
<br />
<br />
== Troubleshooting ==<br />
<br />
=== IMAP/POP3 client failing to receive mails ===<br />
<br />
If you get similar errors, take a look into {{ic|/var/log/mail.log}} or use {{ic|journalctl -xn --unit postfix.service}} to find out more.<br />
<br />
It may turn out that the Maildir {{ic|/home/vmail/mail@domain.tld}} is just being created if there is at least one email waiting. Otherwise there wouldn't be any need for the directory creation before.<br />
<br />
<br />
=== Roundcube not able to delete emails or view any 'standard' folders ===<br />
<br />
Ensure that the Roundcube config.inc.php file contains the following:<br />
<br />
{{bc|1=<br />
$rcmail_config['default_imap_folders'] = array('INBOX', 'Drafts', 'Sent', 'Junk', 'Trash');<br />
$rcmail_config['create_default_folders'] = true;<br />
$rcmail_config['protect_default_folders'] = true;<br />
}}</div>Kevrhttps://wiki.archlinux.org/index.php?title=Xorg&diff=327701Xorg2014-07-30T23:44:13Z<p>Kevr: Felt like this was necessary information running into the same issue.</p>
<hr />
<div>[[Category:X Server]]<br />
[[Category:Graphics]]<br />
[[cs:Xorg]]<br />
[[da:Xorg]]<br />
[[de:X]]<br />
[[el:Xorg]]<br />
[[es:Xorg]]<br />
[[fr:Xorg]]<br />
[[it:Xorg]]<br />
[[ja:Xorg]]<br />
[[nl:Xorg]]<br />
[[pl:Xorg]]<br />
[[pt:Xorg]]<br />
[[ro:Xorg]]<br />
[[ru:Xorg]]<br />
[[tr:X_Sunucusu]]<br />
[[zh-CN:Xorg]]<br />
[[zh-TW:Xorg]]<br />
{{Related articles start}}<br />
{{Related|Start X at Login}}<br />
{{Related|Autostarting}}<br />
{{Related|Display manager}}<br />
{{Related|Window manager}}<br />
{{Related|Font configuration}}<br />
{{Related|Cursor Themes}}<br />
{{Related|Desktop environment}}<br />
{{Related|Wayland}}<br />
{{Related|Mir}}<br />
{{Related articles end}}<br />
From http://www.x.org/wiki/:<br />
:''The X.Org project provides an open source implementation of the X Window System. The development work is being done in conjunction with the freedesktop.org community. The X.Org Foundation is the educational non-profit corporation whose Board serves this effort, and whose Members lead this work.''<br />
<br />
'''Xorg''' is the public, open-source implementation of the X window system version 11. Since Xorg is the most popular choice among Linux users, its ubiquity has led to making it an ever-present requisite for GUI applications, resulting in massive adoption from most distributions. See the [[Wikipedia:X.Org Server|Xorg]] Wikipedia article or visit the [http://www.x.org/wiki/ Xorg website] for more details.<br />
<br />
== Installation ==<br />
<br />
You will need to [[pacman|install]] the essential package {{Pkg|xorg-server}}, available in the [[official repositories]].<br />
<br />
Additionally, the {{Pkg|xorg-server-utils}} meta-package pulls in the most useful packages for certain configuration tasks, they are pointed out in the relevant sections. Some other useful packages are part of the {{Grp|xorg-apps}} group.<br />
<br />
{{Tip|The default X environment is rather bare, and you will typically seek to install a [[Window manager|window manager]] or a [[Desktop environment|desktop environment]] to supplement X.}}<br />
<br />
=== Driver installation ===<br />
<br />
The Linux kernel includes open-source video drivers and support for hardware accelerated framebuffers. However, userland support is required for OpenGL and 2D acceleration in X11.<br />
<br />
First, identify your card:<br />
<br />
$ lspci | grep VGA<br />
<br />
{{Note| if you don't get any output, try looking for a 3D controller instead <br />
$ lspci <nowiki>|</nowiki> grep 3D<br />
}}<br />
<br />
Then install an appropriate driver. You can search the package database for a complete list of open-source video drivers:<br />
<br />
$ pacman -Ss xf86-video<br />
<br />
The default graphics driver is ''vesa'' (package {{Pkg|xf86-video-vesa}}), which handles a large number of chipsets but does not include any 2D or 3D acceleration. If a better driver cannot be found or fails to load, Xorg will fall back to ''vesa''.<br />
<br />
In order for video acceleration to work, and often to expose all the modes that the GPU can set, a proper video driver is required:<br />
<br />
{{Note| If you have a NVIDIA Optimus enabled laptop; one that uses an integrated video card combined with a dedicated GPU, then you might want to look at [[Bumblebee]].}}<br />
<br />
{| class="wikitable" style="text-align:center"<br />
|-<br />
! Brand !! Type !! Driver !! [[Multilib]] Package<br><span style="font-weight: normal; font-size: 0.8em;">(for 32-bit applications on Arch x86_64)</span> !! &nbsp;Documentation&nbsp;<br />
|-<br />
| rowspan="2" bgcolor=#f7e3e3| '''<span style="color: #e62c2c;">&nbsp;AMD/ATI&nbsp;</span>'''<br />
| &nbsp;Open source&nbsp; || {{Pkg|xf86-video-ati}} || {{Pkg|lib32-ati-dri}} || [[ATI]]<br />
|-<br />
| Proprietary || {{AUR|catalyst}} || {{AUR|lib32-catalyst-utils}} || [[AMD Catalyst]]<br />
|-<br />
| bgcolor=#e3ecf7| '''<span style="color: #2a6dc8;">Intel</span>'''<br />
| Open source<br />
| {{Pkg|xf86-video-intel}} || {{Pkg|lib32-intel-dri}} || [[Intel Graphics]]<br />
|-<br />
| rowspan="5" bgcolor=#e3f7e6| '''<span style="color: #409044;">Nvidia</span>'''<br />
| Open source<br />
| {{Pkg|xf86-video-nouveau}} || {{Pkg|lib32-nouveau-dri}} || [[Nouveau]]<br />
|-<br />
| rowspan="2"| Proprietary || {{Pkg|nvidia}} || {{Pkg|lib32-nvidia-libgl}} || rowspan="2"| [[NVIDIA]]<br />
|-<br />
| {{Pkg|nvidia-304xx}} || {{Pkg|lib32-nvidia-304xx-libgl}}<br />
|}<br />
<br />
Other video drivers can be found in the {{Grp|xorg-drivers}} group.<br />
<br />
Xorg should run smoothly without closed source drivers, which are typically needed only for advanced features such as fast 3D-accelerated rendering for games, dual-screen setups, and TV-out.<br />
<br />
== Running ==<br />
<br />
=== Display manager ===<br />
<br />
A convenient way to start X, but one that requires an additional application and dependencies, is by using a [[display manager]] such as [[GDM]], [[KDM]] or [[SLiM]].<br />
<br />
=== Manually ===<br />
<br />
If you want to start X without a display manager, install the package {{Pkg|xorg-xinit}} which provides the ''startx'' and ''xinit'' commands (the ''startx'' script is merely a front end to the ''xinit'' command).<br />
<br />
To determine the client to run, ''startx''/''xinit'' will first try to parse a {{ic|~/.xinitrc}} file in the user's home directory. In the absence of {{ic|~/.xinitrc}}, ''startx''/''xinit'' defaults to parsing the global file {{ic|/etc/X11/xinit/xinitrc}}, which starts a basic environment with the [[Twm]] window manager, [[Wikipedia:Xclock|Xclock]] and [[Xterm]]: this requires the packages {{Pkg|xorg-twm}}, {{Pkg|xorg-xclock}} and {{Pkg|xterm}} to be installed. See [[xinitrc]] for information on how to initialize and configure it.<br />
<br />
To launch the X server and clients, simply run:<br />
<br />
$ startx<br />
<br />
{{Tip|You can exploit the global file {{ic|/etc/X11/xinit/xinitrc}} to quickly test X in a minimal environment, especially immediately after installing it or for other debugging purposes: simply rename your {{ic|~/.xinitrc}} file to temporarily disable it. After running {{ic|startx}}, a few movable windows should show up, and your mouse should work. To quit this environment, issue the {{ic|exit}} command into the terminals until you return to the virtual console.}}<br />
<br />
See also [[Start X at Login]].<br />
<br />
{{Note|<br />
* By default, due to permissions on console devices, the X display needs to be on the same tty where the login occurred. This is handled by the default {{ic|/etc/X11/xinit/xserverrc}}. See [[General troubleshooting#Session permissions]] for details.<br />
* If you wish to have the X display on a separate console from the one where the server is invoked, you can do so by using the X server wrapper provided by {{ic|/usr/lib/systemd/systemd-multi-seat-x}}. For convenience, ''startx'' can be set up to use this wrapper by modifying your {{ic|~/.xserverrc}}.<br />
* If you choose to use ''xinit'' instead of ''startx'', you are responsible for passing {{ic|-nolisten tcp}} and ensuring the session does not break by starting X on a different tty.<br />
}}<br />
<br />
{{Moveto|#Troubleshooting|The following notes are for troubleshooting, maybe they belong better there. We could provide a link to such section here instead. Note there's also [[#Common problems]] there.}}<br />
<br />
{{Note|<br />
* If a problem occurs, then view the log at {{ic|/var/log/Xorg.0.log}}. Be on the lookout for any lines beginning with {{ic|(EE)}}, which represent errors, and also {{ic|(WW)}}, which are warnings that could indicate other issues.<br />
* If there is an ''empty'' {{ic|.xinitrc}} file in your {{ic|$HOME}}, either delete or edit it in order for X to start properly. If you do not do this X will show a blank screen with what appears to be no errors in your {{ic|Xorg.0.log}}. Simply deleting it will get it running with a default X environment.<br />
* If the screen goes black, you may still attempt to switch to a different virtual console (e.g. {{ic|Ctrl+Alt+F2}}), and blindly log in as root. You can do this by typing "root" (press {{ic|Enter}} after typing it) and entering the root password (again, press {{ic|Enter}} after typing it).<br />
<br />
: You may also attempt to kill the X server with:<br />
: {{bc|# pkill X}}<br />
: If this does not work, reboot blindly with:<br />
: {{bc|# reboot}}<br />
}}<br />
<br />
== Configuration ==<br />
<br />
{{Note|Arch supplies default configuration files in {{ic|/etc/X11/xorg.conf.d}}, and no extra configuration is necessary for most setups.}}<br />
<br />
Xorg uses a configuration file called {{ic|xorg.conf}} and files ending in the suffix {{ic|.conf}} for its initial setup: the complete list of the folders where these files are searched can be found at [http://www.x.org/releases/current/doc/man/man5/xorg.conf.5.xhtml] or by running {{ic|man xorg.conf}}, together with a detailed explanation of all the available options.<br />
<br />
=== Using .conf files ===<br />
<br />
The {{ic|/etc/X11/xorg.conf.d/}} directory stores host specific configuration. You are free to add configuration files there, but they must have a {{ic|.conf}} suffix: the files are read in ASCII order, and by convention their names start with {{ic|''XX''-}} (two digits and a hyphen, so that for example 10 is read before 20). These files are parsed by the X server upon startup and are treated like part of the traditional {{ic|xorg.conf}} configuration file. The X server essentially treats the collection of configuration files as one big file with entries from {{ic|xorg.conf}} at the end.<br />
<br />
=== Using xorg.conf ===<br />
<br />
Xorg can also be configured via {{ic|/etc/X11/xorg.conf}} or {{ic|/etc/xorg.conf}}. You can also generate a skeleton for {{ic|xorg.conf}} with:<br />
<br />
# Xorg :0 -configure<br />
<br />
This should create a {{ic|xorg.conf.new}} file in {{ic|/root/}} that you can copy over to {{ic|/etc/X11/xorg.conf}}.<br />
<br />
Alternatively, your proprietary video card drivers may come with a tool to automatically configure Xorg: see the article of your video driver, [[NVIDIA]] or [[AMD Catalyst]], for more details.<br />
<br />
{{Note|Configuration file keywords are case insensitive, and "_" characters are ignored. Most strings (including Option names) are also case insensitive, and insensitive to white space and "_" characters.}}<br />
<br />
=== Sample configurations ===<br />
<br />
* {{ic|xorg.conf}}<br />
: [http://pastebin.com/raw.php?i=EuSKahkn Sample 1]<br />
: {{Note|Sample configuration file using {{ic|/etc/X11/xorg.conf.d/10-evdev.conf}} for the keyboard layouts. Note the commented out {{ic|InputDevice}} sections.}}<br />
* {{ic|/etc/X11/xorg.conf.d/10-evdev.conf}}<br />
: [http://pastebin.com/raw.php?i=4mPY35Mw Sample 1]<br />
: {{Note|This is the {{ic|10-evdev.conf}} file that goes with the xorg.conf sample 1.}}<br />
* {{ic|/etc/X11/xorg.conf.d/10-monitor.conf}}<br />
:# [http://pastebin.com/raw.php?i=fJv8EXGb VMware]<br />
:# [http://pastebin.com/raw.php?i=NRz7v0Kn KVM]<br />
:# [https://gist.github.com/daemox/6325050 NVIDIA]<br />
: {{Note|nvidia-ck binary drivers (v325); Dual GPU, Dual Monitor, Dual Screen; No Twinview, No Xinerama; Rotated and vertically placed screen1 above screen0.}}<br />
<br />
== Input devices ==<br />
<br />
[[Udev]] will detect your hardware and [[Wikipedia:evdev|evdev]] will act as the hotplugging input driver for almost all devices. Udev is provided by {{Pkg|systemd}} and {{Pkg|xf86-input-evdev}} is required by {{Pkg|xorg-server}}, so there is no need to explicitly install those packages. If evdev does not support your device, install the needed driver from the {{Grp|xorg-drivers}} group.<br />
<br />
You should have {{ic|10-evdev.conf}} in the {{ic|/etc/X11/xorg.conf.d/}} directory, which manages keyboards, mice, touchpads and touchscreens.<br />
<br />
See the following pages for specific instructions, or the [https://fedoraproject.org/wiki/Input_device_configuration Fedora wiki] entry for more examples.<br />
<br />
=== Mouse acceleration ===<br />
<br />
See the main page: [[Mouse acceleration]]<br />
<br />
=== Extra mouse buttons ===<br />
<br />
See the main page: [[All Mouse Buttons Working]]<br />
<br />
=== Touchpad Synaptics ===<br />
<br />
See the main page: [[Touchpad Synaptics]]<br />
<br />
=== Keyboard settings ===<br />
<br />
See the main page: [[Keyboard configuration in Xorg]]<br />
<br />
== Monitor settings ==<br />
<br />
=== Getting started ===<br />
<br />
{{Note|Newer versions of Xorg are auto-configuring, you should not need to use this.}}<br />
<br />
First, create a new config file, such as {{ic|/etc/X11/xorg.conf.d/10-monitor.conf}}.<br />
<br />
{{hc|/etc/X11/xorg.conf.d/10-monitor.conf|<nowiki><br />
Section "Monitor"<br />
Identifier "Monitor0"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Device0"<br />
Driver "vesa" #Choose the driver used for this monitor<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "Screen0" #Collapse Monitor and Device section to Screen section<br />
Device "Device0"<br />
Monitor "Monitor0"<br />
DefaultDepth 16 #Choose the depth (16||24)<br />
SubSection "Display"<br />
Depth 16<br />
Modes "1024x768_75.00" #Choose the resolution<br />
EndSubSection<br />
EndSection<br />
</nowiki>}}<br />
<br />
=== Multiple monitors ===<br />
<br />
See main article [[Multihead]] for general information.<br />
<br />
See also GPU-specific instructions:<br />
* [[NVIDIA#Multiple monitors]]<br />
* [[Nouveau#Dual Head]]<br />
* [[AMD Catalyst#Double Screen (Dual Head / Dual Screen / Xinerama)]]<br />
* [[ATI#Dual Head setup]]<br />
<br />
==== More than one graphics card ====<br />
<br />
You must define the correct driver to use and put the bus ID of your graphic cards.<br />
<br />
{{bc|<br />
Section "Device"<br />
Identifier "Screen0"<br />
Driver "nouveau"<br />
BusID "PCI:0:12:0"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Screen1"<br />
Driver "radeon"<br />
BusID "PCI:1:0:0"<br />
EndSection<br />
}}<br />
<br />
To get your bus ID:<br />
<br />
{{hc|<nowiki>$ lspci | grep VGA</nowiki>|<nowiki><br />
01:00.0 VGA compatible controller: nVidia Corporation G96 [GeForce 9600M GT] (rev a1)<br />
</nowiki>}}<br />
<br />
The bus ID here is 1:0:0.<br />
<br />
=== Display size and DPI ===<br />
<br />
{{Accuracy|1=Xorg always sets dpi to 96. See [https://bugs.freedesktop.org/show_bug.cgi?id=23705 this], [https://bugs.freedesktop.org/show_bug.cgi?id=41115 this] and finally [http://pastebin.com/vtzyBK6e this].}}<br />
<br />
The DPI of the X server is determined in the following manner:<br />
# The -dpi command line option has highest priority.<br />
# If this is not used, the DisplaySize setting in the X config file is used to derive the DPI, given the screen resolution.<br />
# If no DisplaySize is given, the monitor size values from DDC are used to derive the DPI, given the screen resolution.<br />
# If DDC does not specify a size, 75 DPI is used by default.<br />
<br />
In order to get correct dots per inch (DPI) set, the display size must be recognized or set. Having the correct DPI is especially necessary where fine detail is required (like font rendering). Previously, manufacturers tried to create a standard for 96 DPI (a 10.3" diagonal monitor would be 800x600, a 13.2" monitor 1024x768). These days, screen DPIs vary and may not be equal horizontally and vertically. For example, a 19" widescreen LCD at 1440x900 may have a DPI of 89x87. To be able to set the DPI, the Xorg server attempts to auto-detect your monitor's physical screen size through the graphic card with [[wikipedia:Display_Data_Channel|DDC]]. <s>When the Xorg server knows the physical screen size, it will be able to set the correct DPI depending on resolution size.</s><br />
<br />
To see if your display size and DPI are detected/calculated correctly:<br />
<br />
$ xdpyinfo | grep -B2 resolution<br />
<br />
Check that the dimensions match your display size. If the Xorg server is not able to correctly calculate the screen size, it will default to 75x75 DPI and you will have to calculate it yourself.<br />
<br />
If you have specifications on the physical size of the screen, they can be entered in the Xorg configuration file so that the proper DPI is calculated:<br />
<br />
{{bc|<br />
Section "Monitor"<br />
Identifier "Monitor0"<br />
DisplaySize 286 179 # In millimeters<br />
EndSection<br />
}}<br />
<br />
If you only want to enter the specification of your monitor '''without''' creating a full xorg.conf create a new config file. For example ({{ic|/etc/X11/xorg.conf.d/90-monitor.conf}}):<br />
<br />
{{bc|<br />
Section "Monitor"<br />
Identifier "<default monitor>"<br />
DisplaySize 286 179 # In millimeters<br />
EndSection<br />
}}<br />
<br />
If you do not have specifications for physical screen width and height (most specifications these days only list by diagonal size), you can use the monitor's native resolution (or aspect ratio) and diagonal length to calculate the horizontal and vertical physical dimensions. Using the Pythagorean theorem on a 13.3" diagonal length screen with a 1280x800 native resolution (or 16:10 aspect ratio):<br />
<br />
$ echo 'scale=5;sqrt(1280^2+800^2)' | bc # 1509.43698<br />
<br />
This will give the pixel diagonal length and with this value you can discover the physical horizontal and vertical lengths (and convert them to millimeters):<br />
<br />
$ echo 'scale=5;(13.3/1509)*1280*25.4' | bc # 286.43072<br />
$ echo 'scale=5;(13.3/1509)*800*25.4' | bc # 179.01920<br />
<br />
{{Note|This calculation works for monitors with square pixels; however, there is the seldom monitor that may compress aspect ratio (e.g 16:10 aspect resolution to a 16:9 monitor). If this is the case, you should measure your screen size manually.}}<br />
<br />
==== Setting DPI manually ====<br />
<br />
{{Accuracy|The following option is reported to work only with [[NVIDIA]] proprietary drivers.|Talk:Xorg#Setting_DPI_manually}}<br />
<br />
DPI can be set manually if you only plan to use one resolution ([http://pxcalc.com/ DPI calculator]):<br />
<br />
{{bc|<br />
Section "Monitor"<br />
Identifier "Monitor0"<br />
Option "DPI" "96 x 96"<br />
EndSection<br />
}}<br />
<br />
If you use an NVIDIA card, you can manually set the DPI adding the options bellow on {{ic|/etc/X11/xorg.conf.d/20-nvidia.conf}} (inside '''Device''' section):<br />
<br />
Option "UseEdidDpi" "False"<br />
Option "DPI" "96 x 96"<br />
<br />
For RandR compliant drivers, you can set it by:<br />
<br />
$ xrandr --dpi 96<br />
<br />
See [[Execute commands after X start]] to make it permanent.<br />
<br />
{{Note|While you can set any dpi you like and applications using Qt and GTK will scale accordingly, it's recommended to set it to 96, 120 (25% higher), 144 (50% higher), 168 (75% higher), 192 (100% higher) etc., to reduce scaling artifacts to GUI that use bitmaps. Reducing it below 96 dpi may not reduce size of graphical elements of GUI as typically the lowest dpi the icons are made for is 96.}}<br />
<br />
=== DPMS ===<br />
<br />
DPMS (Display Power Management Signaling) is a technology that allows power saving behaviour of monitors when the computer is not in use. This will allow you to have your monitors automatically go into standby after a predefined period of time. See: [[DPMS]]<br />
<br />
== Composite ==<br />
<br />
The Composite extension for X causes an entire sub-tree of the window hierarchy to be rendered to an off-screen buffer. Applications can then take the contents of that buffer and do whatever they like. The off-screen buffer can be automatically merged into the parent window or merged by external programs, called compositing managers. See the following article for more information: [[Wikipedia:Compositing window manager|compositing window manager]]<br />
<br />
=== List of composite managers ===<br />
<br />
* {{App|[[Cairo Compmgr|Cairo Composite Manager]]|Cairo based composite manager|http://cairo-compmgr.tuxfamily.org/|{{AUR|cairo-compmgr-git}}}}<br />
* {{App|[[Compiz]]|Composite manager for Aiglx and Xgl, with plugins and CCSM|http://www.compiz.org/|{{AUR|compiz-core-devel}}}}<br />
* {{App|[[Compton]]|X Compositor (a fork of xcompmgr-dana)|https://github.com/chjj/compton|{{AUR|compton}}}}<br />
* {{App|[[Xcompmgr]]|Composite Window-effects manager for X.org.|http://cgit.freedesktop.org/xorg/app/xcompmgr/|{{Pkg|xcompmgr}}}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== X startup tweaking (startx) ===<br />
<br />
{{Accuracy|{{ic|/usr/bin/startx}} should not be modified, ''startx'' recognises the options as command line arguments}}<br />
<br />
For X's option reference see:<br />
$ man Xserver<br />
<br />
The following options have to be appended to the variable {{ic|"defaultserverargs"}} in the {{ic|/usr/bin/startx}} file:<br />
<br />
* Enable deferred glyph loading for 16 bit fonts:<br />
-deferglyphs 16<br />
<br />
{{Note|If you start X with kdm, the startx script does not seem to be executed. X options must be appended to the variable {{ic|ServerArgsLocal}} in the {{ic|/usr/share/config/kdm/kdmrc}} file.}}<br />
<br />
=== Nested X session ===<br />
<br />
{{Expansion|mention [[Awesome#Using_Xephyr|xephyr]]}}<br />
<br />
To run a nested session of another desktop environment:<br />
$ /usr/bin/Xnest :1 -geometry 1024x768+0+0 -ac -name Windowmaker & wmaker -display :1<br />
<br />
This will launch a Window Maker session in a 1024 by 768 window within your current X session.<br />
<br />
This needs the package {{Pkg|xorg-server-xnest}} to be installed.<br />
<br />
=== Starting GUI programs remotely ===<br />
<br />
See main article: [[SSH#X11 forwarding]].<br />
<br />
=== On-demand disabling and enabling of input sources ===<br />
<br />
With the help of ''xinput'' you can temporarily disable or enable input sources. This might be useful, for example, on systems that have more than one mouse, such as the ThinkPads and you would rather use just one to avoid unwanted mouse clicks.<br />
<br />
[[pacman|Install]] the {{Pkg|xorg-xinput}} package from the [[official repositories]].<br />
<br />
Find the ID of the device you want to disable:<br />
<br />
$ xinput<br />
<br />
For example in a Lenovo ThinkPad T500, the output looks like this:<br />
<br />
{{hc|$ xinput|<nowiki><br />
⎡ Virtual core pointer id=2 [master pointer (3)]<br />
⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)]<br />
⎜ ↳ TPPS/2 IBM TrackPoint id=11 [slave pointer (2)]<br />
⎜ ↳ SynPS/2 Synaptics TouchPad id=10 [slave pointer (2)]<br />
⎣ Virtual core keyboard id=3 [master keyboard (2)]<br />
↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)]<br />
↳ Power Button id=6 [slave keyboard (3)]<br />
↳ Video Bus id=7 [slave keyboard (3)]<br />
↳ Sleep Button id=8 [slave keyboard (3)]<br />
↳ AT Translated Set 2 keyboard id=9 [slave keyboard (3)]<br />
↳ ThinkPad Extra Buttons id=12 [slave keyboard (3)]<br />
</nowiki>}}<br />
<br />
Disable the device with {{ic|xinput --disable ''device_id''}}, where ''device_id'' is the device ID you want to disable. In this example we will disable the Synaptics Touchpad, with the ID 10:<br />
<br />
$ xinput --disable 10<br />
<br />
To re-enable the device, just issue the opposite command:<br />
<br />
$ xinput --enable 10<br />
<br />
== Troubleshooting ==<br />
<br />
=== Common problems ===<br />
<br />
If Xorg will not start, the screen is completely black, the keyboard and mouse are not working, etc., first take these simple steps:<br />
*Check the log file: {{ic|cat /var/log/Xorg.0.log}}<br />
*Check specific pages in [[:Category:Input devices]] if you have issues with keyboard, mouse, touchpad etc.<br />
*Finally, search for common problems in [[ATI]], [[Intel]] and [[NVIDIA]] articles.<br />
<br />
=== CTRL right key does not work with oss keymap ===<br />
<br />
{{Accuracy|The file will be overwritten on {{Pkg|xkeyboard-config}} update; for such simple task should be used [[Xmodmap]].}}<br />
<br />
Edit as root {{ic|/usr/share/X11/xkb/symbols/fr}}, and change the line:<br />
<br />
include "level5(rctrl_switch)"<br />
<br />
to<br />
<br />
// include "level5(rctrl_switch)"<br />
<br />
Then restart X, reboot or run<br />
<br />
setxkbmap fr oss<br />
<br />
=== X clients started with "su" fail ===<br />
<br />
If you are getting "Client is not authorized to connect to server", try adding the line:<br />
<br />
session optional pam_xauth.so<br />
<br />
to {{ic|/etc/pam.d/su}}. {{ic|pam_xauth}} will then properly set environment variables and handle {{ic|xauth}} keys.<br />
<br />
=== Program requests "font '(null)'" ===<br />
<br />
* Error message: "''unable to load font `(null)'.''"<br />
Some programs only work with bitmap fonts. Two major packages with bitmap fonts are available, {{Pkg|xorg-fonts-75dpi}} and {{Pkg|xorg-fonts-100dpi}}. You do not need both; one should be enough. To find out which one would be better in your case, try this:<br />
<br />
$ xdpyinfo | grep resolution<br />
<br />
and use what is closer to you (75 or 100 instead of XX)<br />
<br />
# pacman -S xorg-fonts-XXdpi<br />
<br />
=== Frame-buffer mode problems ===<br />
<br />
If X fails to start with the following log messages,<br />
<br />
{{bc|<nowiki><br />
(WW) Falling back to old probe method for fbdev<br />
(II) Loading sub module "fbdevhw"<br />
(II) LoadModule: "fbdevhw"<br />
(II) Loading /usr/lib/xorg/modules/linux//libfbdevhw.so<br />
(II) Module fbdevhw: vendor="X.Org Foundation"<br />
compiled for 1.6.1, module version=0.0.2<br />
ABI class: X.Org Video Driver, version 5.0<br />
(II) FBDEV(1): using default device<br />
<br />
Fatal server error:<br />
Cannot run in framebuffer mode. Please specify busIDs for all framebuffer devices<br />
</nowiki>}}<br />
<br />
uninstall fbdev:<br />
<br />
# pacman -R xf86-video-fbdev<br />
<br />
=== DRI with Matrox cards stops working ===<br />
<br />
If you use a Matrox card and DRI stops working after upgrading to Xorg, try adding the line:<br />
<br />
Option "OldDmaInit" "On"<br />
<br />
to the Device section that references the video card in {{ic|xorg.conf}}.<br />
<br />
=== Recovery: disabling Xorg before GUI login ===<br />
<br />
If Xorg is set to boot up automatically and for some reason you need to prevent it from starting up before the login/display manager appears (if the system is wrongly configured and Xorg does not recognize your mouse or keyboard input, for instance), you can accomplish this task with two methods.<br />
<br />
* Change default target to rescue.target. See [[systemd#Change default target to boot into]].<br />
* If you have not only a faulty system that makes Xorg unusable, but you have also set the GRUB menu wait time to zero, or cannot otherwise use GRUB to prevent Xorg from booting, you can use the Arch Linux live CD. Boot up the live CD and log in as root. You need a mount point, such as {{ic|/mnt}}, and you need to know the name of the partition you want to mount.<br />
<br />
You can use the command,<br />
<br />
# fdisk -l<br />
<br />
to see your partitions. Usually, the one you want will be resembling {{ic|/dev/sda1}}. Then, to mount this to {{ic|/mnt}}, use<br />
<br />
# mount /dev/sda1 /mnt<br />
<br />
Then your filesystem will show up under {{ic|/mnt}}. From here you can delete the {{ic|gdm}} daemon to prevent Xorg from booting up normally or make any other necessary changes to the configuration.<br />
<br />
=== X failed to start: Keyboard initialization failed ===<br />
<br />
If your hard disk is full, startx will fail. {{ic|/var/log/Xorg.0.log}} will end with:<br />
<br />
{{bc|<br />
(EE) Error compiling keymap (server-0)<br />
(EE) XKB: Could not compile keymap<br />
(EE) XKB: Failed to load keymap. Loading default keymap instead.<br />
(EE) Error compiling keymap (server-0)<br />
(EE) XKB: Could not compile keymap<br />
XKB: Failed to compile keymap<br />
Keyboard initialization failed. This could be a missing or incorrect setup of xkeyboard-config.<br />
Fatal server error:<br />
Failed to activate core devices.<br />
Please consult the The X.Org Foundation support at http://wiki.x.org<br />
for help.<br />
Please also check the log file at "/var/log/Xorg.0.log" for additional information.<br />
(II) AIGLX: Suspending AIGLX clients for VT switch<br />
}}<br />
<br />
Make some free space on your root partition and X will start.<br />
<br />
=== Black screen, No protocol specified.., Resource temporarily unavailable for all or some users ===<br />
<br />
X creates configuration and temporary files in current user's home directory. Make sure there is free disk space available on the partition your home directory resides in. Unfortunately, X server does not provide any more obvious information about lack of disk space in this case.<br />
<br />
=== Launching multiple X sessions with proprietary NVIDIA on Xorg 1.16 ===<br />
<br />
When attempting to launch X sessions in multiple ttys on Xorg 1.16, you may be rejected with a log indicating that no drivers were found. I found that a workaround for this was to specifically tell X that we'd like to use the 'nvidia' driver.<br />
<br />
{{ic|/etc/X11/xorg.conf.d/20-nvidia.conf}}<br />
Section "Device"<br />
Identifier "Device0"<br />
Driver "nvidia"<br />
VendorName "NVIDIA Corporation"<br />
Option "NoLogo" "True"<br />
EndSection</div>Kevrhttps://wiki.archlinux.org/index.php?title=USB_flash_installation_medium&diff=323530USB flash installation medium2014-07-06T02:13:23Z<p>Kevr: Removed a note that said the user was required to reformat his drive if it previously had other partitions on it. dd overwrites the blocks with it's own partition data.</p>
<hr />
<div>[[Category:Getting and installing Arch]]<br />
[[ar:USB Installation Media]]<br />
[[bg:USB Installation Media]]<br />
[[de:Installation von einem USB-Stick]]<br />
[[es:USB Installation Media]]<br />
[[fr: Créer une clef USB avec l'ISO Arch Linux]]<br />
[[it:USB Installation Media]]<br />
[[ja:USB Installation Media]]<br />
[[ro:Instalare prin USB]]<br />
[[ru:USB Installation Media]]<br />
[[tr:USB_ile_kurulum]]<br />
[[zh-CN:USB Installation Media]]<br />
[[zh-TW:USB Installation Media]]<br />
{{Related articles start}}<br />
{{Related|CD Burning}}<br />
{{Related|Archiso}}<br />
{{Related articles end}}<br />
This page discusses various mutiplatform methods on how to create a Arch Linux Installer USB drive (also referred to as ''"flash drive", "USB stick", "USB key"'', etc) for booting in BIOS and UEFI systems. The result will be a LiveUSB (LiveCD-like) system that can be used for installing Arch Linux, system maintenance or for recovery purposes, and that, because of the nature of [[Wikipedia:SquashFS|SquashFS]], will discard all changes once the computer shuts down.<br />
<br />
If you would like to run a full install of Arch Linux from a USB drive (i.e. with persistent settings), see [[Installing Arch Linux on a USB key]]. If you would like to use your bootable Arch Linux USB stick as a rescue USB, see [[Change Root]].<br />
<br />
== BIOS and UEFI Bootable USB ==<br />
<br />
=== Using dd ===<br />
{{Note|This method is recommended due to its simplicity. If it does not work, switch to the alternative method [[#Using manual formatting ]] below.}}<br />
<br />
{{Warning|This will irrevocably destroy all data on {{ic|/dev/sd'''x'''}}.}}<br />
<br />
==== In GNU/Linux ====<br />
<br />
{{Tip|Find out the name of your USB drive with {{ic|lsblk}}. Make sure that it is '''not''' mounted.}}<br />
<br />
Run the following command, replacing {{ic|/dev/'''sdx'''}} with your drive, e.g. {{ic|/dev/sdb}}. (do '''not''' append a partition number, so do '''not''' use something like {{ic|/dev/sdb'''1'''}})<br />
<br />
# dd bs=4M if=/path/to/archlinux.iso of=/dev/'''sdx''' && sync<br />
<br />
==== In Windows ====<br />
<br />
===== Using USBwriter =====<br />
<br />
This method does not require any workaround and is as straightforward as {{ic|dd}} under Linux. Just download the Arch Linux ISO, and use the [http://sourceforge.net/p/usbwriter/wiki/Documentation/ USBwriter] utility to write to your USB flash memory.<br />
<br />
===== Using Universal USB Installer =====<br />
<br />
This is probably the most straightforward way to create a bootable Arch Linux USB stick from Windows. Download [http://www.pendrivelinux.com/universal-usb-installer-easy-as-1-2-3/ Universal USB Installer], which runs on Windows XP/Vista/7/8. There's no installation involved; you directly download a single executable. Download the Arch ISO file and run Universal-USB-Installer-1.9.5.2.exe (the version numbers will vary). The use of the program is fairly self-explanatory. You select the distribution you'd like to create a bootable USB for (Arch Linux), the ISO file you downloaded, and the USB flash drive you want to install to.<br />
<br />
{{Note|1= As of UUI 1.9.5.2, this does not work out-of-the-box because of a [https://bbs.archlinux.org/viewtopic.php?pid=1344629 discrepancy in syslinux versions].}}<br />
<br />
{{Tip|The Arch syslinux installer uses the USB disk label to facilitate mounting the correct drive. The current version of UUI (1.9.5.2) sets the disk label to UUI, when Arch is expecting something else. You can easily fix this by right-clicking the USB drive icon, and clicking on ''Properties'' to change the label. For archlinux-2014.07.03-dual.iso, the label should be {{ic|ARCH_201407}}. It should be clear what the label should be for other versions of the ISO, but in any case, Arch will tell you what the label needs to be if you attempt to boot from the USB with an incorrect label.}}<br />
<br />
{{Warning|Make sure you don't accidentally click on one of the ads on the pendrivelinux.com page which feature prominent ''Download'' buttons—these are likely to carry virus/spyware/trojan payloads. The Pendrive download button is small and near the middle of the page.}}<br />
<br />
===== Using Cygwin =====<br />
<br />
Make sure your [http://www.cygwin.com/ Cygwin] installation contains the {{ic|dd}} package.<br />
<br />
{{Tip|If you do not want to install Cygwin, you can download {{ic|dd}} for Windows from [http://www.chrysocome.net/dd here]. See the next section for more information.}}<br />
<br />
Place your image file in your home directory:<br />
<br />
C:\cygwin\home\John\<br />
<br />
Run cygwin as administrator (required for cygwin to access hardware). To write to your USB drive use the following command:<br />
<br />
dd if=image.iso of=\\.\'''x''': bs=4M<br />
<br />
where image.iso is the path to the iso image file within the {{ic|cygwin}} directory and {{ic|\\.\'''x''':}} is your USB flash drive where {{ic|'''x'''}} is the windows designated letter, e.g. {{ic|\\.\d:}}.<br />
<br />
On Cygwin 6.0, find out the correct partition with:<br />
<br />
cat /proc/partitions<br />
<br />
and write the ISO image with the information from the output. Example:<br />
<br />
{{Warning|This will irrevocably delete all files on your USB flash drive, so make sure you do not have any important files on the flash drive before doing this.}}<br />
<br />
dd if=image.iso of=/dev/sdb bs=4M<br />
<br />
===== dd for Windows =====<br />
<br />
{{Note|Some users have an "isolinux.bin missing or corrupt" problem when booting the media with this method.}}<br />
<br />
A GPL licensed dd version for Windows is available at http://www.chrysocome.net/dd. The advantage of this over Cygwin is a smaller download. Use it as shown in instructions for Cygwin above.<br />
<br />
To begin, download the latest version of dd for Windows. Once downloaded, extract the archive's contents into Downloads or elsewhere.<br />
<br />
Now, launch your {{ic|command prompt}} as an administrator. Next, change directory ({{ic|cd}}) into the Downloads directory.<br />
<br />
If your Arch Linux ISO is elsewhere you may need to state the full path, for convenience you may wish to put the Arch Linux ISO into the same folder as the dd executable. The basic format of the command will look like this.<br />
<br />
{{bc|<nowiki>dd if=archlinux-2014-XX-xx-dual.iso of=\\.\x: bs=4m</nowiki>}}<br />
{{Warning|This command will replace the drive's contents and its formatting with the ISO's. You will likely be unable to recover its contents in the event of an accidental copy. Be absolutely sure that you are directing dd to the correct drive before executing!}}<br />
Simply replace the various null spots (indicated by an "x") with the correct date and correct drive letter.<br />
<br />
Here is a complete example.<br />
{{bc|<nowiki>dd if=ISOs\archlinux-2014.07.03-dual.iso of=\\.\d: bs=4M</nowiki>}}<br />
<br />
==== In Mac OS X ====<br />
<br />
To be able to use {{ic|dd}} on your USB device on a Mac you have to do some special maneuvers. First of all insert your usb device, OS X will automount it, and in {{ic|Terminal.app}} run:<br />
<br />
$ diskutil list<br />
<br />
Figure out what your USB device is called with {{ic|mount}} or {{ic|<nowiki>sudo dmesg | tail</nowiki>}} (e.g. {{ic|/dev/disk1}}) and unmount the partitions on the device (i.e., /dev/disk1s1) while keeping the device proper (i.e., /dev/disk1):<br />
<br />
$ diskutil unmountDisk /dev/disk1<br />
<br />
Now we can continue in accordance with the instructions above (but, if you are using the OS X {{ic|dd}}, use {{ic|/dev/rdisk}} instead of {{ic|/dev/disk}}, and use {{ic|1=bs=1m}}. {{ic|rdisk}} means "raw disk" and is much faster on OS X, and {{ic|1=bs=1m}} indicates a 1 MB block size).<br />
<br />
{{hc|<nowiki># dd if=image.iso of=/dev/rdisk1 bs=1m</nowiki>|<br />
20480+0 records in<br />
20480+0 records out<br />
167772160 bytes transferred in 220.016918 secs (762542 bytes/sec)<br />
}}<br />
<br />
It is probably a good idea to eject your drive before physical removal at this point:<br />
<br />
$ diskutil eject /dev/disk1<br />
<br />
==== How to restore the USB drive ====<br />
<br />
Because the ISO image is a hybrid which can either be burned to a disc or directly written to a USB drive, it does not include a standard partition table.<br />
<br />
After you install Arch Linux and you are done with the USB drive, you should zero out its first 512 bytes ''(meaning the boot code from the MBR and the non-standard partition table)'' if you want to restore it to full capacity:<br />
<br />
# dd count=1 bs=512 if=/dev/zero of=/dev/sd'''x''' && sync<br />
<br />
Then create a new partition table (e.g. "msdos") and filesystem (e.g. EXT4, FAT32) using {{Pkg|gparted}}, or from a terminal:<br />
<br />
* For EXT2/3/4 (adjust accordingly), it would be:<br />
<br />
# cfdisk /dev/sd'''x'''<br />
# mkfs.ext4 /dev/sd'''x1'''<br />
# e2label /dev/sd'''x1''' USB_STICK<br />
<br />
* For FAT32, install the {{Pkg|dosfstools}} package and run:<br />
<br />
# cfdisk /dev/sd'''x'''<br />
# mkfs.vfat -F32 /dev/sd'''x1'''<br />
# dosfslabel /dev/sd'''x1''' USB_STICK<br />
<br />
=== Using manual formatting===<br />
<br />
==== In GNU/Linux ====<br />
<br />
This method is more complicated than writing the image directly with {{ic|dd}}, but it does keep the flash drive usable for data storage.<br />
<br />
* Make sure that the latest ''syslinux'' package (version 6.02 or newer) is installed on the system. <br />
<br />
* A MBR (msdos) partition table with at least one partition, containing a FAT32 filesystem must be present on the device. If not, create the partition and/or filesystem before continuing.<br />
<br />
* Mount the ISO image.<br />
# mkdir -p /mnt/iso<br />
# mount -o loop archlinux-2014.07.03-dual.iso /mnt/iso<br />
<br />
{{Note|In any of the following commands, adjust {{ic|/dev/sd'''X'''1}} according to your system.}}<br />
* Mount the FAT32 filesystem on the USB flash device, and copy the contents of the isofile to it.<br />
# mkdir -p /mnt/usb<br />
# mount /dev/sd'''X'''1 /mnt/usb<br />
# cp -a /mnt/iso/* /mnt/usb<br />
# sync<br />
# umount /mnt/{usb,iso}<br />
<br />
* Adjust the configuration files archiso_sys32 and archiso_sys64. This step is not required when using [[Archboot]] instead of [[Archiso]]. This command replaces the {{ic|1=archisolabel=ARCH_2014XX}} part with your equivalent of {{ic|1=archiso'''device'''=/dev/disk/by-uuid/47FA-4071}} in both files.<br />
{{Warning|Failure to label the drive "{{ic|ARCH_2014XX}}" (with the appropriate release month) or to use an [[UUID]] (to re-label it to whatever you like) prevents booting from the created medium.}}<br />
<br />
$ sed -i "s|label=ARCH_.*|device=/dev/disk/by-uuid/$(blkid -o value -s UUID /dev/sd'''X'''1)|" archiso_sys{32,64}.cfg<br />
<br />
* If want to use UUID to boot, such as by running the above command, and want to boot the stick using from a system using EFI, you need to update /mnt/usb/loader/entries/archiso-x86_64.conf (or similar for 32-bit ISO) similarly, by removing {{ic|1=archisolabel=ARCH_2014XX}} and adding {{ic|1=archisodevice=/dev/disk/by-uuid/your-uuid-here}}.<br />
<br />
{{Note|Again, adjust {{ic|/dev/sd'''X'''1}}.}}<br />
{{Accuracy|This makes no sense as you are changing files on a device you just unmounted, and also doesn't match the 2014 isos. Really, the Archiso/Archboot USB media creation process needs separate pages}}<br />
<br />
* Install Syslinux to the flash drive by following [[Syslinux#Manual_install]]. Overwrite the existing syslinux modules ({{ic|*.c32}} files) present in the USB (from the ISO) with the ones from the syslinux package. This is necessary to avoid boot failure because of a possible version mismatch.<br />
<br />
* Mark the partition as active by following [[Syslinux#MBR_partition_table]]<br />
<br />
==== In Windows ====<br />
<br />
{{Note|<br />
* Do not use any '''Bootable USB Creator utility''' for creating the UEFI bootable USB. Do not use ''dd for Windows'' to dd the ISO to the USB drive.<br />
<br />
* In the below commands '''X:''' is assumed to be the USB flash drive in Windows.<br />
<br />
* Windows used backward slash {{ic|\}} as path-separator, so the same is used in the below commands.<br />
<br />
* All commands should be run in Windows command prompt '''as administrator'''.<br />
<br />
* {{ic|>}} denotes the Windows command prompt.<br />
}}<br />
<br />
* Partition and format the USB drive using [http://rufus.akeo.ie/ Rufus USB partitioner]. Select partition scheme option as '''MBR for BIOS and UEFI''' and File system as '''FAT32'''. Uncheck "Create a bootable disk using ISO image" and "Create extended label and icon files" options. Use <br />
<br />
* Change the '''Volume Label''' of the USB flash drive {{ic|X:}} to match the LABEL mentioned in {{ic|1=archisolabel=}} part in {{ic|<ISO>\loader\entries\archiso-x86_64.conf}}. This step is required for Official ISO ([[Archiso]]) but not required for [[Archboot]].<br />
<br />
* Extract the ISO (similar to extracting ZIP archive) to the USB flash drive (using [http://7-zip.org/ 7-Zip]. <br />
<br />
* Download latest official syslinux 6.xx binaries (zip file) from https://www.kernel.org/pub/linux/utils/boot/syslinux/ and extract it.<br />
<br />
* Run the following command (in Windows cmd prompt, as admin):<br />
<br />
{{Note|Use {{ic|X:\boot\syslinux\}} for Archboot iso.}}<br />
<br />
> cd bios\<br />
> for /r %Y in (*.c32) do copy "%Y" "X:\arch\boot\syslinux\" /y<br />
> copy mbr\*.bin X:\arch\boot\syslinux\ /y<br />
<br />
* Install Syslinux to the USB by running (use {{ic|win64\syslinux64.exe}} for x64 Windows):<br />
<br />
{{Note|Use {{ic|/boot/syslinux}} for Archboot iso.}}<br />
<br />
> cd bios\<br />
> win32\syslinux.exe -d /arch/boot/syslinux -i -a -m X:<br />
<br />
{{Note|<br />
* The above step install Syslinux {{ic|ldlinux.sys}} to the USB partition VBR, sets the partition as active/boot in the MBR partition table and write the MBR boot code to the 1st 400-byte boot code region of the USB.<br />
<br />
* The {{ic|-d}} switch expects path with forward slash path-separator like in *unix systems.<br />
}}<br />
<br />
== Other Methods for BIOS systems ==<br />
{{Out of date|Can someone verify these work/are even needed to be mentioned?|section=Other Methods for BIOS systems}}<br />
=== In GNU/Linux ===<br />
<br />
==== Using UNetbootin ====<br />
<br />
UNetbootin can be used on any Linux distribution or Windows to copy your iso to a USB device. However, Unetbootin overwrites syslinux.cfg, so it creates a USB device that does not boot properly. For this reason, '''Unetbootin is not recommended''' -- please use {{ic|dd}} or one of the other methods discussed in this topic.<br />
{{Warning|UNetbootin writes over the default {{ic|syslinux.cfg}}; this must be restored before the USB device will boot properly.}}<br />
<br />
Edit {{ic|syslinux.cfg}}:<br />
<br />
{{hc|sysconfig.cfg|2=<br />
default menu.c32<br />
prompt 0<br />
menu title Archlinux Installer<br />
timeout 100<br />
<br />
label unetbootindefault<br />
menu label Archlinux_x86_64<br />
kernel /arch/boot/x86_64/vmlinuz<br />
append initrd=/arch/boot/x86_64/archiso.img archisodevice=/dev/sd'''x1''' ../../<br />
<br />
label ubnentry0<br />
menu label Archlinux_i686<br />
kernel /arch/boot/i686/vmlinuz<br />
append initrd=/arch/boot/i686/archiso.img archisodevice=/dev/sd'''x1''' ../../<br />
}}<br />
<br />
In {{ic|/dev/sd'''x1'''}} you must replace '''x''' with the first free letter after the last letter in use on the system where you are installing Arch Linux (e.g. if you have two hard drives, use {{ic|c}}.). You can make this change during the first phase of boot by pressing {{ic|Tab}} when the menu is shown.<br />
<br />
=== In Windows ===<br />
<br />
==== Win32 Disk Imager ====<br />
<br />
{{Warning|This will destroy all information on your USB flash drive!}}<br />
First, download the program from [http://sourceforge.net/projects/win32diskimager/ here]. Next, extract the archive and run the executable. Now, select the Arch Linux ISO under the {{ic|Image File}} section and the USB flash device letter (for example, [D:\]) under the {{ic|Device}} section. Finally, click {{ic|Write}} when ready.<br />
{{Note|After installation, you may need to restore the USB flash drive following a process as outlined [[USB_Installation_Media#How_to_restore_the_USB_drive|here]].}}<br />
<br />
==== USBWriter for Windows ====<br />
<br />
Download the program from http://sourceforge.net/projects/usbwriter/ and run it. Select the arch image file, the target USB stick, and click on the {{ic|write}} button. Now you should be able to boot from the usb stick and install Arch Linux from it.<br />
<br />
==== The Flashnul way ====<br />
<br />
[http://shounen.ru/soft/flashnul/ flashnul] is an utility to verify the functionality and maintenance of Flash-Memory (USB-Flash, IDE-Flash, SecureDigital, MMC, MemoryStick, SmartMedia, XD, CompactFlash etc).<br />
<br />
From a command prompt, invoke flashnul with {{ic|-p}}, and determine which device index is your USB drive, e.g.:<br />
<br />
{{hc|C:\>flashnul -p|<br />
Avaible physical drives:<br />
Avaible logical disks:<br />
C:\<br />
D:\<br />
E:\<br />
}}<br />
<br />
When you have determined which device is the correct one, you can write the image to your drive, by invoking flashnul with the device index, {{ic|-L}}, and the path to your image, e.g:<br />
<br />
C:\>flashnul '''E:''' -L ''path\to\arch.iso''<br />
<br />
As long as you are really sure you want to write the data, type yes, then wait a bit for it to write. If you get an access denied error, close any Explorer windows you have open.<br />
<br />
If under Vista or Win7, you should open the console as administrator, or else flashnul will fail to open the stick as a block device and will only be able to write via the drive handle windows provides<br />
<br />
{{Note|Confirmed that you need to use drive letter as opposed to number. flashnul 1rc1, Windows 7 x64.}}<br />
<br />
==== Loading the installation media from RAM ====<br />
<br />
This method uses [[Syslinux]] and a [[Ramdisk]] ([http://www.syslinux.org/wiki/index.php/MEMDISK MEMDISK]) to load the entire Arch Linux ISO image into RAM. Since this will be running entirely from system memory, you will need to make sure the system you will be installing this on has an adequate amount. A minimum amount of RAM between 500 MB and 1 GB should suffice for a MEMDISK based, Arch Linux install.<br />
<br />
For more information on Arch Linux system requirements as well as those for MEMDISK see the [[Beginners' guide]] and [http://www.etherboot.org/wiki/bootingmemdisk#preliminaries here].<br />
{{Tip|Once the installer has completed loading you can simply remove the USB stick and even use it on a different machine to start the process all over again. Utilizing MEMDISK also allows booting and installing Arch Linux to and from the same USB flash drive.}}<br />
<br />
===== Preparing the USB flash drive =====<br />
<br />
Begin by formatting the USB flash drive as '''FAT32'''. Then create the following folders on the newly formatted drive.<br />
* {{ic|Boot}}<br />
** {{ic|Boot/ISOs}}<br />
** {{ic|Boot/Settings}}<br />
<br />
===== Copy the needed files to the USB flash drive =====<br />
<br />
Next copy the ISO that you would like to boot to the {{ic|Boot/ISOs}} folder. After that, extract from the following files from the latest release of {{pkg|syslinux}} from [http://www.kernel.org/pub/linux/utils/boot/syslinux/ here] and copy them into the following folders.<br />
* {{ic|./win32/syslinux.exe}} to the Desktop or Downloads folder on your system.<br />
* {{ic|./memdisk/memdisk}} to the {{ic|Settings}} folder on your USB flash drive.<br />
<br />
===== Create the configuration file =====<br />
<br />
After copying the needed files, navigate to the USB flash drive, /boot/Settings and create a {{ic|syslinux.cfg}} file.<br />
{{Warning|On the {{ic|INITRD}} line, be sure to use the name of the ISO file that you copied to your {{ic|ISOs}} folder!}}<br />
{{hc|/Boot/Settings/syslinux.cfg|2=<br />
DEFAULT arch_iso<br />
<br />
LABEL arch_iso<br />
MENU LABEL Arch Setup<br />
LINUX memdisk<br />
INITRD /Boot/ISOs/archlinux-2014.07.03-dual.iso<br />
APPEND iso}}<br />
For more information on Syslinux see the [[Syslinux|Arch Wiki article]].<br />
<br />
===== Final steps =====<br />
<br />
Finally, create a {{ic|*.bat}} file where {{ic|syslinux.exe}} is located and run it ("Run as administrator" if you are on Vista or Windows 7):<br />
{{hc|C:\Documents and Settings\username\Desktop\install.bat|<br />
@echo off<br />
syslinux.exe -m -a -d /Boot/Settings X:}}<br />
<br />
== Troubleshooting ==<br />
<br />
* For the [[#Loading the installation media from RAM|MEMDISK Method]], if you get the famous "30 seconds" error trying to boot the i686 version, press the {{ic|Tab}} key over the {{ic|Boot Arch Linux (i686)}} entry and add {{ic|vmalloc&#61;448M}} at the end. For reference: ''If your image is bigger than 128MiB and you have a 32-bit OS, then you have to increase the maximum memory usage of vmalloc''. [http://www.syslinux.org/wiki/index.php/MEMDISK#-_memdiskfind_in_combination_with_phram_and_mtdblock]<br />
<br />
* If you get the "30 seconds" error due to the {{ic|/dev/disk/by-label/ARCH_XXXXYY}} not mounting, try renaming your USB media to {{ic|ARCH_XXXXYY}} (e.g. {{ic|ARCH_201405}}).<br />
<br />
== See Also ==<br />
<br />
* [https://wiki.gentoo.org/wiki/LiveUSB/HOWTO Gentoo wiki - LiveUSB/HOWTO]<br />
* [https://fedoraproject.org/wiki/How_to_create_and_use_Live_USB Fedora wiki - How to create and use Live USB]<br />
* [http://en.opensuse.org/SDB:Live_USB_stick openSUSE wiki - SDB:Live USB stick]</div>Kevrhttps://wiki.archlinux.org/index.php?title=List_of_applications/Internet&diff=316980List of applications/Internet2014-05-28T07:07:03Z<p>Kevr: /* Pastebin clients */</p>
<hr />
<div><noinclude><br />
[[Category:Internet applications]]<br />
[[cs:List of Applications/Internet]]<br />
[[es:List of Applications/Internet]]<br />
[[it:List of Applications/Internet]]<br />
[[ja:List of Applications/Internet]]<br />
[[ru:List of applications/Internet]]<br />
[[zh-CN:List of Applications/Internet]]<br />
{{List of applications navigation}}<br />
</noinclude><br />
== Internet ==<br />
<br />
{{Note|1=For possibly more up to date selection of applications, try checking the [https://aur.archlinux.org/packages.php?O=0&K=&do_Search=Go&detail=1&C=13&SeB=nd&SB=n&SO=a&PP=50 AUR 'network' category]}}<br />
<br />
=== Network managers ===<br />
<br />
* {{App|[[Connman]]|Daemon for managing internet connections within embedded devices running the Linux operating system. Comes with a command-line client, plus Enlightenment, GTK and Dmenu clients are available.|https://connman.net/|{{Pkg|connman}}}}<br />
* {{App|[[netctl]]|Simple and robust tool to manage network connections via profiles. Intended for use with systemd.|https://projects.archlinux.org/netctl.git/|{{Pkg|netctl}}}}<br />
* {{App|[[NetworkManager]]|Manager that provides wired, wireless, mobile broadband and OpenVPN detection with configuration and automatic connection.|http://projects.gnome.org/NetworkManager/|{{Pkg|networkmanager}}}}<br />
* {{App|[[systemd-networkd]]|Native Systemd daemon that manages network configuration. It includes support for basic network configuration through udev and networkd. The service is available with systemd > 210.|http://www.freedesktop.org/software/systemd/man/systemd-networkd.service.html|{{Pkg|systemd}}}}<br />
* {{App|[[Wicd]]|Wireless and wired connection manager with few dependencies. Comes with an ncurses interface, and a GTK interface {{Pkg|wicd-gtk}} is available.|http://wicd.sourceforge.net/|{{Pkg|wicd}}}}<br />
<br />
=== Web browsers ===<br />
<br />
See also [[Wikipedia:Comparison of web browsers]].<br />
<br />
==== Console ====<br />
<br />
* {{App|[[Wikipedia:ELinks|ELinks]]|Advanced and well-established feature-rich text mode web browser (Links fork, barely supported since 2009).|http://elinks.or.cz/|{{Pkg|elinks}}}}<br />
* {{App|[[Wikipedia:Links (web browser)|Links]]|Text WWW browser. Includes a console version [links] similar to Lynx, and a graphical X-window/framebuffer version [links -g] (must be compiled in, Arch has both) with CSS, image rendering, pull-down menus.|http://links.twibright.com/|{{Pkg|links}}}}<br />
* {{App|[[Wikipedia:Lynx (web browser)|Lynx]]|Text browser for the World Wide Web.|http://lynx.isc.org|{{Pkg|lynx}}}}<br />
* {{App|retawq|Interactive, multi-threaded network client (web browser) for text terminals.|http://retawq.sourceforge.net/|{{AUR|retawq}}}}<br />
* {{App|[[Wikipedia:W3m|w3m]]|Pager/text-based web browser. It has vim-like keybindings, and is able to display images. It has javascript support too.|http://w3m.sourceforge.net/|{{Pkg|w3m}}}}<br />
<br />
==== Graphical ====<br />
<br />
====="Mainstream"=====<br />
* {{App|[[Chromium]]|Web browser developed by Google, the open source project behind Google Chrome.|http://www.chromium.org/|{{Pkg|chromium}}}}<br />
* {{App|[[Firefox]]|Extensible browser from Mozilla based on Gecko with fast rendering.|https://mozilla.com/firefox|{{Pkg|firefox}}}}<br />
* {{App|[[Opera]]|Highly customizable browser with focuses on an adherence to web rendering standards.|http://opera.com|{{Pkg|opera}}}}<br />
<br />
=====Webkit-based=====<br />
* {{App|[[Wikipedia:Arora (browser)|Arora]]|Cross-platform web browser built using QtWebKit. Development stopped in January 2012.|https://code.google.com/p/arora/|{{Pkg|arora}}}}<br />
* {{App|[[dwb]]|Lightweight, highly customizable web browser based on the WebKit engine with vi-like shortcuts and tiling layouts.|http://portix.bitbucket.org/dwb/|{{Pkg|dwb}}}}<br />
* {{App|[[Epiphany]]|Browser which uses the WebKit rendering engine, part of {{Grp|gnome}}.|http://projects.gnome.org/epiphany/|{{Pkg|epiphany}}}}<br />
* {{App|[[Jumanji]]|Highly customizable and functional web browser.|http://pwmt.org/projects/jumanji|{{AUR|jumanji}}}}<br />
* {{App|[[Wikipedia:Konqueror|Konqueror]]|Web browser based on Qt and KHTML, part of {{Grp|kdebase}}.|http://konqueror.org/|{{Pkg|kdebase-konqueror}}}}<br />
* {{App|[[Luakit]]|Highly configurable, micro-browser framework based on the WebKit engine and the GTK+ toolkit. It is very fast, extensible by Lua and licensed under the GNU GPLv3 license.|http://mason-larobina.github.com/luakit/|{{Pkg|luakit}}}}<br />
* {{App|[[Wikipedia:Midori (web browser)|Midori]]|Lightweight web browser based on GTK+ and WebKit.|http://twotoasts.de/index.php/midori/|{{Pkg|midori}}}}<br />
* {{App|[[Wikipedia:QupZilla|QupZilla]]|New and very fast open source browser based on WebKit core, written in Qt framework.| http://www.qupzilla.com |{{pkg|qupzilla}}}} <br />
* {{App|[[wikipedia:Rekonq|Rekonq]]|WebKit-based web browser for KDE.|http://rekonq.kde.org/|{{Pkg|rekonq}}}}<br />
* {{App|Sb|Very lightweight WebKit-based browser that uses keybindings to perform most things the URL bar would usually do.|https://github.com/mutantturkey/sb/|{{AUR|sb-git}}}} <br />
* {{App|Surf|Lightweight WebKit-based browser, which follows the [http://suckless.org/philosophy suckless ideology] (basically, the browser itself is a single C source file).|http://surf.suckless.org|{{Pkg|surf}}}}<br />
* {{App|[[Wikipedia:Uzbl|Uzbl]]|Group of web interface tools which adhere to the Unix philosophy.|http://uzbl.org/|{{Pkg|uzbl-browser}}}}<br />
* {{App|[[Vimprobable]]|Browser that behaves like the Vimperator plugin available for Mozilla Firefox. It is based on the WebKit engine and uses the GTK+ bindings.|http://sourceforge.net/apps/trac/vimprobable/|{{AUR|vimprobable-git}}}}<br />
* {{App|[[Wikipedia:Xombrero|Xombrero]]|Webkit minimalist web browser with sophisticated security features designed-in, BSD style.|https://opensource.conformal.com/wiki/xombrero|{{AUR|xombrero-git}}}}<br />
<br />
=====Alternatives=====<br />
* {{App|[[Wikipedia:Abaco (web browser)|Abaco]]|Multi-page graphical web browser for the Plan 9 OS.|http://lab-fgb.com/abaco/|{{AUR|abaco}}}}<br />
* {{App|[[Wikipedia:Conkeror|Conkeror]]|Highly programmable web browser, with Emacs-like keybindings, based on Mozilla's XULRunner.|http://conkeror.org/|{{AUR|conkeror-git}}}}<br />
* {{App|[[Wikipedia:Dillo|Dillo]]|Small, fast graphical web browser built on [[Wikipedia:Fltk|FLTK]].|http://dillo.org/|{{Pkg|dillo}}}}<br />
* {{App|[[Wikipedia:NetSurf|NetSurf]]|Featherweight browser written in C, notable for its lack of JavaScript support and fast rendering through its own custom rendering engine.|http://netsurf-browser.org|{{Pkg|netsurf}}}}<br />
<br />
=== Downloaders ===<br />
<br />
==== FTP ====<br />
<br />
===== FTP clients =====<br />
<br />
See also [[Wikipedia:Comparison of FTP client software]].<br />
<br />
* {{App|CurlFtpFS|Filesystem for acessing FTP hosts based on FUSE and libcurl.|http://curlftpfs.sourceforge.net/|{{Pkg|curlftpfs}}}}<br />
* {{App|FatRat|Download manager with support for HTTP, FTP, SFTP, BitTorrent, RapidShare and more.|http://fatrat.dolezel.info/|{{Pkg|fatrat}}}}<br />
* {{App|[[Wikipedia:FileZilla|FileZilla]]|Fast and reliable FTP, FTPS and SFTP client.|http://filezilla-project.org/|{{Pkg|filezilla}}}}<br />
* {{App|fuseftp|FTP filesystem written in Perl, using [[Wikipedia:Filesystem in Userspace|FUSE]].|http://freshmeat.net/projects/fuseftp/|{{AUR|fuseftp}}}}<br />
* {{App|[[Wikipedia:gFTP|gFTP]]|Multithreaded FTP client for Linux.|http://gftp.seul.org/|{{Pkg|gftp}}}}<br />
* {{App|[[Wikipedia:Lftp|LFTP]]|Sophisticated command-line FTP client.|http://lftp.yar.ru/|{{Pkg|lftp}}}}<br />
* {{App|[[Wikipedia:tnftp|tnftp]]|FTP client with several advanced features for [[Wikipedia:NetBSD|NetBSD]].|http://freecode.com/projects/tnftp|{{Pkg|tnftp}}}}<br />
Some file managers like Dolphin, [[Nautilus]] and [[Thunar]] also provide FTP functionality.<br />
<br />
===== FTP servers =====<br />
<br />
* {{App|[[Pure-FTPd]]|Free (BSD-licensed), secure, production-quality and standard-compliant FTP server.|http://www.pureftpd.org/project/pure-ftpd|{{AUR|pure-ftpd}}}}<br />
* {{App|[[Very Secure FTP Daemon|vsftpd]]|Lightweight, stable and secure FTP server for UNIX-like systems.|https://security.appspot.com/vsftpd.html|{{Pkg|vsftpd}}}}<br />
* {{App|bftpd|Small, easy-to-configure FTP server.<br />
|http://bftpd.sourceforge.net/|{{Pkg|bftpd}}}}<br />
<br />
==== BitTorrent clients ====<br />
<br />
See also [[Wikipedia:Comparison of BitTorrent clients]].<br />
<br />
===== Console =====<br />
<br />
====== Command line / backend ======<br />
Can be used as-is via command line, but all have a choice of front-end options as well.<br />
* {{App|[[aria2]]|Lightweight download utility that supports simultaneous adaptive downloading via HTTP(S), FTP, BitTorrent (DHT, PEX, MSE/PE) protocols and Metalink. It can run as a daemon controlled via a built-in JSON-RPC or XML-RPC interface.|http://aria2.sourceforge.net/|{{Pkg|aria2}}}}<br />
* {{App|[[Wikipedia:MLDonkey|MLDonkey]]|Multi-protocol P2P client that supports BitTorrent, HTTP, FTP, eDonkey and Direct Connect.|http://mldonkey.sourceforge.net/|{{Pkg|mldonkey}}}}<br />
* {{App|[[Transmission]]|Simple and easy-to-use BitTorrent client with a daemon version, GTK+, Qt GUI, web and CLI front-ends.|http://transmissionbt.com/|{{Pkg|transmission-cli}} (includes backend, daemon, command-line interface, and a Web UI interface)}}<br />
<br />
====== Console Interface ======<br />
* {{App|[[rTorrent]]|Simple and lightweight ncurses BitTorrent client. Requires {{Pkg|libtorrent}} backend.|http://libtorrent.rakshasa.no/|{{Pkg|rtorrent}}}}<br />
* {{App|[[Transmission]]|Simple and easy-to-use BitTorrent client with a daemon version, ncurses CLI. Requires {{Pkg|transmission-cli}} backend.|http://transmissionbt.com/|{{Pkg|transmission-remote-cli}}}}<br />
<br />
===== Graphical Interface =====<br />
<br />
====== libtorrent-rasterbar backend ======<br />
* {{App|[[Deluge]]|User-friendly BitTorrent client written in PyGTK that can run as a daemon.|http://deluge-torrent.org/|{{Pkg|deluge}}}}<br />
* {{App|FatRat|Qt4 based download manager with support for HTTP, FTP, SFTP, BitTorrent, rapidshare and more. Written in C++.|http://fatrat.dolezel.info/|{{Pkg|fatrat}}}}<br />
* {{App|[[Wikipedia:qBittorrent|qBittorrent]]|Open source (GPLv2) BitTorrent client that strongly resembles µtorrent.|http://qbittorrent.sourceforge.net/|{{AUR|qbittorrent}}}}<br />
* {{App|[[Wikipedia:Tribler|Tribler]]|4th generation file sharing system bittorrent client.|http://www.tribler.org|{{AUR|tribler}}}}<br />
<br />
====== libktorrent backend ======<br />
* {{App|[[Wikipedia:KGet|KGet]]|Download manager for KDE that supports HTTP(S), FTP and BitTorrent. Part of {{Grp|kdenetwork}}.|http://www.kde.org/applications/internet/kget/|{{Pkg|kdenetwork-kget}}}}<br />
* {{App|[[Ktorrent]]|Feature-rich BitTorrent client for KDE.|http://ktorrent.org/|{{Pkg|ktorrent}}}}<br />
<br />
====== others ======<br />
* {{App|QTorrent|BitTorrent client written in PyQt3.|http://thegraveyard.org/qtorrent.php{{Dead link|2012|09|20}}|{{AUR|qtorrent}}}}<br />
* {{App|Tixati|P2P client that uses the BitTorrent protocol.|http://www.tixati.com|{{AUR|tixati}}}}<br />
* {{App|[[Transmission]]|Simple and easy-to-use BitTorrent client with daemon version, GTK+, Qt GUI, web and CLI front-ends.|http://transmissionbt.com/|{{Pkg|transmission-gtk}} {{Pkg|transmission-qt}} {{AUR|transmission-remote-gtk}} (remote clients work with the daemon in the -cli package)}}<br />
* {{App|[[Wikipedia:Vuze|Vuze]]|Feature-rich BitTorrent client written in Java (formerly Azureus).|https://www.vuze.com/|{{AUR|vuze}}}}<br />
<br />
==== eDonkey clients ====<br />
<br />
eDonkey is still the second-largest p2p network (see [http://ipoque.com/en/resources/internet-studies Internet Study 2008/2009]).<br />
<br />
See also [[Wikipedia:Comparison of eDonkey software]].<br />
<br />
* {{App|[[aMule]]|Well-known eDonkey/Kad client with a daemon version and GTK+, web, and CLI front-ends.|http://www.amule.org/|{{Pkg|amule}}}}<br />
* {{App|KaMule|KDE graphical front-end for aMule.|http://kde-apps.org/content/show.php?content&#61;150270|{{AUR|kamule}}}}<br />
<br />
==== Gnutella ====<br />
<br />
* {{App|[[Wikipedia:Sharelin|Sharelin]]|Gnutella2 only client with a web UI.|http://sourceforge.net/apps/mediawiki/sharelin|{{AUR|Sharelin}}}}<br />
<br />
=== Communication ===<br />
<br />
==== Email clients ====<br />
<br />
See also [[Wikipedia:Comparison of e-mail clients]].<br />
<br />
===== Console =====<br />
<br />
* {{App|[[Alpine]]|Fast, easy-to-use and Apache-licensed email client based on [[Wikipedia:Pine (email client)|Pine]].|https://washington.edu/alpine|{{AUR|alpine}}}}<br />
* {{App|[[Wikipedia:Gnus|Gnus]]|Email, NNTP and RSS client for Emacs.|http://gnus.org/|{{AUR|emacs-gnus-git}}}}<br />
* {{App|S-nail|a mail processing system with a command syntax reminiscent of ''ed'' with lines replaced by messages. Provides the functionality of [[Wikipedia:mailx|mailx]] and much more.|http://sourceforge.net/projects/s-nail/|{{Pkg|s-nail}}}}<br />
* {{App|mu/mu4e|Email indexer (mu) and client for emacs (mu4e). Xapian based for fast searches.|http://www.djcbsoftware.nl/code/mu/mu4e.html|{{AUR|mu}}}}<br />
* {{App|[[Mutt]]|Small but very powerful text-based mail client.|http://www.mutt.org/|{{Pkg|mutt}}}}<br />
* {{App|[[Sup]]|CLI mail client with very fast searching, tagging, threading and GMail like operation.|http://supmua.org/|{{AUR|sup}}}}<br />
* {{App|Wanderlust|Email client and news reader for Emacs.|http://www.gohome.org/wl/|{{Pkg|wanderlust}}}}<br />
<br />
===== Graphical =====<br />
<br />
* {{App|[[Balsa]]|Simple and light email client that is part of the Gnome project.|http://pawsa.fedorapeople.org/balsa/|{{Pkg|balsa}}}}<br />
* {{App|[[Wikipedia:Claws Mail|Claws Mail]]|Lightweight GTK-based email client and news reader.|http://claws-mail.org/|{{Pkg|claws-mail}}}}<br />
* {{App|[[Evolution]]|Mature and feature-rich e-mail client used in GNOME by default. Part of {{Grp|gnome-extra}}.|http://projects.gnome.org/evolution/|{{Pkg|evolution}}}}<br />
* {{App|Geary|Simple desktop mail client built in [[Wikipedia:Vala (programming language)|Vala]].|https://wiki.gnome.org/Apps/Geary|{{Pkg|geary}}}}<br />
* {{App|[[Wikipedia:Kmail|Kmail]]|Mature and feature-rich email client. Part of {{Grp|kdepim}}.|http://kde.org/applications/internet/kmail/|{{Pkg|kdepim-kmail}}}}<br />
* {{App|Manitou Mail|Database-driven email system.|http://www.manitou-mail.org/|{{AUR|manitou-mdx}} {{AUR|manitou-ui}}}}<br />
* {{App|[[Wikipedia:Sylpheed|Sylpheed]]|Lightweight and user-friendly GTK+ email client.|http://sylpheed.sraoss.jp/en/|{{Pkg|sylpheed}}}}<br />
* {{App|[[Thunderbird]]|Feature-rich email client from Mozilla written in GTK+.|http://www.mozilla.org/thunderbird/|{{Pkg|thunderbird}}}}<br />
* {{App|Trojitá|Qt IMAP email client.|http://trojita.flaska.net/|{{Pkg|trojita}}}}<br />
<br />
==== Instant messaging ====<br />
<br />
See also [[Wikipedia:Comparison of instant messaging protocols]].<br />
<br />
This section lists all software with [[Wikipedia:Instant messaging|instant messaging]] support. Particularly, that are client and server applications.<br />
<br />
===== Multi-protocol clients =====<br />
<br />
See also [[Wikipedia:Comparison of instant messaging clients]].<br />
<br />
{{Note|All messengers, that support several networks by means of direct connections to them, belong to this section.}}<br />
<br />
Many clients listed here (including Pidgin and all its forks) support multiple IM networks via [[Wikipedia:libpurple|libpurple]]. The number of networks supported by these clients is very large but they (like any multiprotocol clients) usually have very limited or no support for network-specific features.<br />
<br />
====== Console ======<br />
<br />
* {{App|BarnOwl|Ncurses-based chat client with support for the Zephyr, AIM, Jabber, IRC, and Twitter protocols.|http://barnowl.mit.edu/|{{AUR|barnowl}}}}<br />
* {{App|[[Bitlbee]]|IRC client that provides a gateway to popular chat networks (XMPP, MSN, Yahoo, AIM, ICQ and Twitter).|http://bitlbee.org/|{{Pkg|bitlbee}}}}<br />
* {{App|[[Wikipedia:Centericq|CenterIM]]|Fork of CenterICQ, a text mode menu- and window-driven IM interface.|http://centerim.org/|{{Pkg|centerim}}}}<br />
* {{App|[[Pidgin|Finch]]|Ncurses-based chat client that uses libpurple and supports all its protocols.|http://developer.pidgin.im/wiki/Using%20Finch|{{Pkg|finch}}}}<br />
* {{App|[[Wikipedia:naim (software)|naim]]|Ncurses chat client with support for AOL, ICQ, IRC and the Lily CMC.|http://naim.n.ml.org/|{{Pkg|naim}}}}<br />
* {{App|pork|Programmable, ncurses-based AIM and IRC client that mostly looks and feels like ircII.|http://dev.ojnk.net/|{{Pkg|pork}}}}<br />
<br />
====== Graphical ======<br />
<br />
* {{App|Carrier|Pidgin fork providing minor GUI enhancements (formerly FunPidgin).|http://funpidgin.sourceforge.net/|{{AUR|carrier}}}}<br />
* {{App|[[Wikipedia:Emesene|Emesene]]|PyGTK instant messenger for the Windows Live Messenger network, also compatible with Jabber, Facebook and Google Talk.|http://emesene.org/|{{AUR|emesene}}}}<br />
* {{App|[[Wikipedia:Empathy (software)|Empathy]]|GNOME instant messaging client using the [[Wikipedia:Telepathy (software)|Telepathy]] framework.|http://live.gnome.org/Empathy|{{Pkg|empathy}}}}<br />
* {{App|Galaxium Messenger|Messenger application designed for the GNOME desktop.|https://code.google.com/p/galaxium/|{{AUR|galaxium}}}}<br />
* {{App|[[Wikipedia:Instantbird|Instantbird]]|Multi-protocol chat client using Mozilla's XUL and libpurple.|http://instantbird.com/|{{AUR|instantbird}}}}<br />
* {{App|[[Wikipedia:Kopete|Kopete]]|User-friendly IM supporting AIM, ICQ, Windows Live Messenger, Yahoo, Jabber, Gadu-Gadu, Novell GroupWise Messenger, and other IM networks. Part of {{Grp|kdenetwork}}.|http://kopete.kde.org/|{{Pkg|kdenetwork-kopete}}}}<br />
* {{App|[[Kde#KDE_Telepathy|KDE Telepathy]]|KDE instant messaging client using the [[Wikipedia:Telepathy (software)|Telepathy]] framework. Meant as a replacement for Kopete.|http://community.kde.org/Real-Time_Communication_and_Collaboration/|{{Pkg|kde-telepathy-meta}}}}<br />
* {{App|Licq|Instant messaging client for UNIX supporting multiple protocols (currently ICQ, MSN and Jabber).|http://www.licq.org|{{Pkg|licq}}}}<br />
* {{App|[[Pidgin]]|Multi-protocol instant messaging client.|http://pidgin.im/|{{Pkg|pidgin}} {{AUR|pidgin-light}}}}<br />
* {{App|qutIM|Simple and user-friendly IM supporting ICQ, Jabber, Mail.Ru, IRC and VKontakte messaging.|http://qutim.org/|{{AUR|qutim-stable}}}}<br />
<br />
===== XMPP (Jabber) =====<br />
<br />
See also [[Wikipedia:XMPP]] and [[Wikipedia:Comparison of instant messaging clients#XMPP-related features]].<br />
<br />
====== Console clients ======<br />
<br />
* {{App|Freetalk|Console-based Jabber client.|https://gnu.org/s/freetalk/|{{Pkg|freetalk}}}}<br />
* {{App|jabber.el|Minimal Jabber client for [[Emacs]].|http://emacs-jabber.sourceforge.net/|{{AUR|emacs-jabber}}}}<br />
* {{App|[[Wikipedia:MCabber|MCabber]]|Small Jabber console client, includes features: SSL, PGP, MUC, OTR, and UTF8.|http://mcabber.com/|{{Pkg|mcabber}}}}<br />
* {{App|Profanity|A console based Jabber client inspired by Irssi.|http://www.profanity.im/|{{Pkg|profanity}}}}<br />
<br />
====== Graphical clients ======<br />
<br />
* {{App|[[Wikipedia:Gajim|Gajim]]|Jabber client written in PyGTK.|https://gajim.org/|{{Pkg|gajim}}}}<br />
* {{App|Jabbim|Jabber client written in PyQt.|http://www.jabbim.com/|{{AUR|jabbim-svn}}}}<br />
* {{App|[[Wikipedia:Psi (instant messaging client)|Psi]]|Qt-based Jabber client.|http://psi-im.org/|{{Pkg|psi}}}}<br />
* {{App|Psi+|Enhanced version of the Psi Jabber client with many new [http://psi-plus.com/wiki/en:features#differences_between_psi_beta_version_and_the_official_psi_015-dev_version features].|https://code.google.com/p/psi-dev/|{{AUR|psi-plus-git}}}}<br />
* {{App|[[Wikipedia:Tkabber|Tkabber]]|Easy to hack feature-rich XMPP client by the author of the ejabberd XMPP server.|http://tkabber.jabber.ru/|{{Pkg|tkabber}}}}<br />
<br />
====== Servers ======<br />
<br />
See also [[Wikipedia:Comparison of XMPP server software]].<br />
<br />
* {{App|[[Prosody]]|An XMPP server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license].|http://prosody.im/|{{Pkg|prosody}}}}<br />
* {{App|Ejabberd|Jabber server written in Erlang|http://www.ejabberd.im/|{{Pkg|ejabberd}}}}<br />
* {{App|[[Jabberd2]]|An XMPP server written in the C language and licensed under the GNU General Public License. It was inspired by jabberd14.|http://jabberd2.org|{{AUR|jabberd2}}}}<br />
<br />
===== IRC clients =====<br />
<br />
See also [[Wikipedia:Comparison of Internet Relay Chat clients]].<br />
<br />
====== Console ======<br />
<br />
* {{App|[[Wikipedia:BitchX|BitchX]]|Console-based IRC client developed from the popular [[Wikipedia:ircII|ircII]].|http://www.bitchx.org/|{{AUR|bitchx-git}}}}<br />
* {{App|ERC|Powerful, modular, and extensible IRC client for [[Emacs]].|http://savannah.gnu.org/projects/erc/|{{AUR|erc-git}}}}<br />
* {{App|[[Wikipedia:Ii (IRC client)|ii]]|Featherweight IRC client, literally {{ic|tail -f}} the conversation and {{ic|echo}} back your replies to a file.|http://tools.suckless.org/ii|{{AUR|ii}}}}<br />
* {{App|Ircfs|File system interface to IRC written in [http://limbo.cat-v.org Limbo].|http://www.ueber.net/code/r/ircfs|{{AUR?|ircfs}}}}<br />
* {{App|[[Irssi]]|Highly-configurable ncurses-based IRC client.|http://irssi.org/|{{Pkg|irssi}}}}<br />
* {{App|ScrollZ|Advanced IRC client based on [[Wikipedia:ircII|ircII]].|http://www.scrollz.com/|{{AUR|scrollz}}}}<br />
* {{App|sic|Extremely simple IRC client, similar to [[Wikipedia:Ii (IRC client)|ii]].|http://tools.suckless.org/sic|{{AUR|sic}}}}<br />
* {{App|[[Wikipedia:WeeChat|WeeChat]]|Modular, lightweight ncurses-based IRC client.|http://weechat.org/|{{Pkg|weechat}}}}<br />
<br />
====== Graphical ======<br />
<br />
* {{App|HexChat|Fork of XChat for Linux and Windows.|http://hexchat.github.io/|{{Pkg|hexchat}}}}<br />
* {{App|[[Wikipedia:Konversation|Konversation]]|Qt-based IRC client for the KDE desktop.|http://konversation.kde.org/|{{Pkg|konversation}}}}<br />
* {{App|[[Wikipedia:KVIrc|KVIrc]]|Qt-based IRC client featuring extensive themes support.|http://kvirc.net/|{{Pkg|kvirc}}}}<br />
* {{App|Loqui|GTK+ IRC client with only one dependency: [https://live.gnome.org/GNetLibrary GNet].|https://launchpad.net/loqui|{{AUR|loqui}}}}<br />
* {{App|LostIRC|Simple GTK+ IRC client with tab-autocompletion, multiple server support, logging and others.|http://lostirc.sourceforge.net|{{AUR|lostirc}}}}<br />
* {{App|pcw|Frontend for [http://tools.suckless.org/ii ii] that opens a new terminal for each channel.|https://bitbucket.org/emg/pcw|{{AUR|pcw-hg}}}}<br />
* {{App|[[Wikipedia:Quassel IRC|Quassel]]|Modern, cross-platform, distributed IRC client.|http://quassel-irc.org/|{{Pkg|quassel-core}} {{Pkg|quassel-client}}}}<br />
* {{App|[[Wikipedia:Smuxi|Smuxi]]|Cross-platform IRC client for the GNOME desktop inspired by [[Irssi]].|http://smuxi.org/|{{Pkg|smuxi}}}}<br />
* {{App|[[Wikipedia:XChat|XChat]]|GTK-based IRC client that works on both Linux and Windows.|http://xchat.org/|{{Pkg|xchat}}}}<br />
<br />
==== Softphone ====<br />
<br />
See also [[Wikipedia:Comparison of VoIP software]] and [[Wikipedia:List of SIP software]].<br />
<br />
===== Clients =====<br />
<br />
* {{App|[[Wikipedia:Blink (software)|Blink]]|State of the art, easy to use SIP client.|http://www.icanblink.com/|{{AUR|blink-darcs}}}}<br />
* {{App|[[Wikipedia:Ekiga|Ekiga]]|VoIP and video conferencing application with full SIP and H.323 support (formerly known as GNOME Meeting).|http://www.ekiga.org/|{{Pkg|ekiga}}}}<br />
* {{App|[[Wikipedia:Empathy (software)|Empathy]]|GNOME instant messenger client using the Telepathy framework with SIP support (using the Sofia-SIP library).|https://live.gnome.org/Empathy|{{Pkg|empathy}}}}<br />
* {{App|iaxComm|Open source softphone for the Asterisk PBX (using the IAX protocol).|http://iaxclient.sourceforge.net/iaxcomm/|{{AUR?|iaxcomm}}}}<br />
* {{App|[[Wikipedia:Jitsi|Jitsi]]|Audio/video SIP VoIP phone and instant messenger written in Java (formerly SIP-Communicator).|https://jitsi.org/|{{AUR|jitsi}}}}<br />
* {{App|Kiax|Qt-based IAX/2 Softphone.|http://www.forschung-direkt.eu/projects/kiax2/|{{AUR|kiax}}}}<br />
* {{App|[[Wikipedia:KPhone|KPhone]]|Qt SIP User Agent with voice, video and text messaging support.|http://sourceforge.net/projects/kphone/|{{AUR?|kphone}}}}<br />
* {{App|[[Wikipedia:Linphone|Linphone]]|VoIP phone application that allows you to to communicate freely with people over the internet, with voice, video, and text instant messaging.|http://www.linphone.org/|{{Pkg|linphone}}}}<br />
* {{App|Minisip|SIP User Agent with focus on security (supports TLS, end-to-end security, SRTP, MIKEY (DH, PSK, PKE)).|http://www.minisip.org/|{{AUR?|minisip}}}}<br />
* {{App|[[Wikipedia:Mumble (software)|Mumble]]|Voice chat application similar to TeamSpeak.|http://mumble.sourceforge.net/|{{pkg|mumble}}}}<br />
* {{App|[[Wikipedia:Psi (instant messaging client)|Psi]]|Qt-based Jabber client which supports video conferencing (since version 0.13).|http://psi-im.org/|{{Pkg|psi}} {{AUR|psi-plus-git}}}}<br />
* {{App|[[Wikipedia:QuteCom|QuteCom]]|Softphone which allows you to make free PC to PC video and voice calls, and to integrate all your IM contacts in one place (formerly Wengo Phone).|http://trac.qutecom.org/|{{AUR|qutecom}}}}<br />
* {{App|[[Wikipedia:SFLphone|SFLPhone]]|Open-source SIP/IAX2 compatible softphone with PulseAudio support.|http://sflphone.org/|{{AUR|sflphone}}}}<br />
* {{App|[[Skype]]|Popular but proprietary application for high-quality voice communication.|http://www.skype.com/|{{Pkg|skype}}}}<br />
* {{App|[[TeamSpeak]]|Proprietary VoIP application with gamers as its target audience.|http://www.teamspeak.com/|{{Pkg|teamspeak3}}}}<br />
* {{App|[[Wikipedia:Twinkle (software)|Twinkle]]|Qt softphone for VoIP and IM communication using SIP.|http://www.twinklephone.com/|{{AUR|twinkle}}}}<br />
* {{App|[[Wikipedia:X-Lite|X-Lite]]|Proprietary freeware VoIP soft phone that uses SIP.|http://www.counterpath.net/x-lite|{{AUR|xlite_bin}}}}<br />
* {{App|[[Wikipedia:Zfone|Zfone]]|Softphone application for secure voice communication over the Internet (VoIP), using the ZRTP protocol.|http://zfoneproject.com/|{{AUR|zfone}}}}<br />
<br />
===== Utilities =====<br />
<br />
* {{App|Gladstone|Educational ITU-T G.729 compliant codec with a GStreamer plugin.|https://gitorious.org/gladstone|{{AUR|gladstone-drizztbsd-git}}}}<br />
* {{App|SIPp|Open source test tool and traffic generator for the SIP protocol.|http://sipp.sourceforge.net/|{{AUR|sipp}}}}<br />
* {{App|Sipsak|Small command-line tool for developers and administrators of SIP applications.|http://sipsak.org/|{{AUR|sipsak}}}}<br />
<br />
=== News, RSS, and blogs ===<br />
<br />
==== News aggregators ====<br />
<br />
See also [[Wikipedia:Comparison of feed aggregators]].<br />
<br />
===== Console =====<br />
<br />
* {{App|[[Wikipedia:Canto (news aggregator)|Canto]]|Ncurses RSS aggregator.|http://codezen.org/canto/|{{AUR|canto}}}}<br />
* {{App|[[Wikipedia:Gnus|Gnus]]|Email, NNTP and RSS client for Emacs.|http://gnus.org/|{{AUR|emacs-gnus-git}}}}<br />
* {{App|Newsbeuter|Ncurses RSS aggregator with layout and keybinding similar to the [[Mutt]] email client.|http://newsbeuter.org|{{Pkg|newsbeuter}}}}<br />
* {{App|Rawdog|"RSS Aggregator Without Delusions Of Grandeur" that parses RSS/CDF/Atom feeds into a static HTML page of articles in chronological order.|http://offog.org/code/rawdog.html|{{AUR|rawdog}}}}<br />
* {{App|Snownews|Text mode RSS news reader.|http://kiza.kcore.de/software/snownews/|{{Pkg|snownews}}}}<br />
<br />
===== Graphical =====<br />
<br />
* {{App|[[Wikipedia:Kontact#News Feed Aggregator|Akregator]]|News aggregator for KDE, part of {{Grp|kdepim}}.|http://kde.org/applications/internet/akregator/|{{Pkg|kdepim-akregator}}}}<br />
* {{App|Blam|Simple newsreader for GNOME written in C Sharp.| https://git.gnome.org/browse/blam|{{Pkg|blam}}}}<br />
* {{App|[[Wikipedia:BlogBridge|BlogBridge]]|Excellent Java-based aggregator, which gives users the option to synchronize their feeds across multiple computers.|http://blogbridge.com|{{AUR|blogbridge}}}}<br />
* {{App|[[Wikipedia:Liferea|Liferea]]|GTK+ news aggregator for online news feeds and weblogs.| http://liferea.sourceforge.net|{{Pkg|liferea}}}}<br />
* {{App|RSS Guard|Very tiny RSS and ATOM news reader developed using Qt framework.|https://bitbucket.org/skunkos/rssguard|{{AUR|rssguard}}}}<br />
* {{App|[[Wikipedia:RSSOwl|RSSOwl]]|Powerful aggregator for RSS and Atom feeds, written in Java using Eclipse Rich Client Platform and SWT as a widget toolkit.|http://boreal.rssowl.org|{{AUR|rssowl}}}}<br />
* {{App|[[Thunderbird]]|Email client from Mozilla which also functions as a pretty nice news aggregator.|http://www.mozilla.org/thunderbird/|{{Pkg|thunderbird}}}}<br />
* {{App|Tickr (formerly News)|GTK-based RSS Reader that displays feeds as a smooth scrolling line on your Desktop, as known from TV stations.|http://newsrssticker.com/|{{AUR|tickr}}}}<br />
* {{App|Urssus|Cross platform GUI news aggregator.|https://code.google.com/p/urssus/|{{AUR|urssus}}}}<br />
* {{App|QuiteRSS|RSS/Atom feed reader written on Qt/С++.|http://quiterss.org/|{{AUR|quiterss}}}}<br />
<br />
==== Podcast clients ====<br />
<br />
* {{App|gPodder|A podcast client and feed aggregator (GTK+ and CLI interface).|http://gpodder.org/|{{AUR|gpodder3}}}}<br />
* {{App|Marrie|A simple podcast client that runs on the Command Line Interface.|https://github.com/rafaelmartins/marrie/|{{AUR|marrie-git}}}}<br />
<br />
==== Usenet newsreaders & newsgrabbers ====<br />
<br />
Some [[#Email_clients|email clients]] also support NNTP. This section mainly lists NNTP-only client.<br />
<br />
See also: [[Wikipedia:List_of_Usenet_newsreaders]], [[Wikipedia:Comparison_of_Usenet_newsreaders]].<br />
<br />
* {{app|nn|Alternative more user-friendly(curses-based) Usenet newsreader for UNIX.|http://www.nndev.org/|{{aur|nn}}}}<br />
* {{app|nzbget|CLI Utility to grab Usenet binary file using .nzb files.|http://nzbget.sourceforge.net/|{{pkg|nzbget}}}}<br />
* {{app|[[Wikipedia:Pan_(newsreader)|pan]]|A GTK2 Usenet newsreader that's good at both text and binaries.|http://pan.rebelbase.com/|{{aur|pan}}}}<br />
* {{app|[[Wikipedia:slrn|slrn]]|An open source text-based news client.|http://www.slrn.org/|{{pkg|slrn}}}}<br />
* {{app|[[Wikipedia:Tin_(newsreader)|tin]]|A cross-platform threaded NNTP and spool based UseNet newsreader.|http://tin.org/|{{aur|tin}}}}<br />
* {{app|trn|A text-based Threaded Usenet newsreader.|http://trn.sourceforge.net/|{{aur|trn}}}}<br />
* {{app|[[Wikipedia:XPN_(newsreader)|XPN]]|A graphical newsreader use PyGTK.|http://xpn.altervista.org/index-en.html|{{aur|xpn}}}}<br />
* {{app|xrn|Usenet newsreader for X Window System.|http://www.mit.edu/people/jik/software/xrn.html|{{aur|xrn}}}}<br />
<br />
==== Blog software ====<br />
<br />
See also [[Wikipedia:Blog software]] and [[Wikipedia:List of content management systems]].<br />
<br />
* {{App|[[Wordpress]]|An easy to setup and administer FLOSS content management system featuring a strong and vibrant community with thousands of plugins and themes.|http://wordpress.org/|{{Pkg|wordpress}}}}<br />
* {{App|[[Drupal]]|An open source content management platform powering millions of websites and applications. It is built, used, and supported by an active and diverse community of people around the world.|http://drupal.org/|{{Pkg|drupal}}}}<br />
* {{App|Nanoblogger|A small weblog engine written in Bash for the command line. It uses common UNIX tools such as cat, grep, and sed to create static HTML content.|http://nanoblogger.sourceforge.net/|{{Pkg|nanoblogger}}}}<br />
* {{App|[[Jekyll]]|A static blog engine, written in Ruby, which supports Markdown, textile and other formats.|http://jekyllrb.com/|{{AUR|ruby-jekyll}}}}<br />
<br />
==== Microblogging clients ====<br />
<br />
See also [[Wikipedia:List of Twitter services and applications]].<br />
<br />
* {{App|Birdie|A beautiful Twitter client for GNU/Linux.|http://birdieapp.github.io/|{{AUR|birdie}}}}<br />
* {{App|Choqok|Microblogging client for KDE that supports Twitter.com, Identi.ca and opendesktop.org services.|http://choqok.gnufolks.org/|{{Pkg|choqok}}}}<br />
* {{App|Corebird|Native Gtk+ Twitter client for the Linux desktop.|http://corebird.baedert.org/|{{AUR|corebird-git}}}}<br />
* {{App|[[Wikipedia:Gwibber|Gwibber]]|GTK-based microblogging client with support for Facebook, Identi.ca, Twitter, Flickr, Foursquare, Sina and Sohu.|http://gwibber.com/|{{AUR|gwibber}}}}<br />
* {{App|[[Wikipedia:Hotot (program)|Hotot]]|Lightweight and open source microblogging client with support for Twitter and Identi.ca and integration with various image sharing services and URL shorteners.|http://hotot.org|{{AUR|hotot}}}}<br />
* {{App|Pino|Simple and fast client for Twitter and Identi.ca written in [[Wikipedia:Vala (programming language)|Vala]].|http://pino-app.appspot.com/|{{AUR|pino}}}}<br />
* {{App|Polly|Linux Twitter client designed for multiple columns of multiple accounts.|https://launchpad.net/polly/|{{AUR|polly}}}}<br />
* {{App|Qwit|Cross-platform client for Twitter using the Qt toolkit.|http://code.google.com/p/qwit/|{{AUR|qwit}}}}<br />
* {{App|ttytter|Easily scriptable twitter client written in Perl.|http://www.floodgap.com/software/ttytter/|{{Pkg|ttytter}}}}<br />
* {{App|Turpial|Multi-interface Twitter client written in Python.|http://turpial.org.ve/|{{AUR|turpial-git}}}}<br />
* {{App|tyrs|Simple client for Twitter and Identi.ca supporting virtually all its features with nice console UI (unmaintained).|http://tyrs.nicosphere.net/|{{AUR|tyrs}}}}<br />
* {{App|turses|Twitter client for the console based off {{AUR|tyrs}} with major improvements.|http://turses.rtfd.org/|{{AUR|turses}}}}<br />
<br />
=== Pastebin clients ===<br />
<br />
See also [[Wikipedia:Pastebin]].<br />
<br />
Pastebin services are often used to paste information into [[IRC_Channel|IRC channels]] to help with troubleshooting. There are services for both text (e.g. [http://bpaste.net/ bpaste.net], [http://pastie.org/ pastie.org], [http://codepad.org/ codepad.org]) and images (e.g. [http://imgur.com/ imgur.com], [http://picpaste.com/ picpaste.com]). Pastebin clients allow you to post directy from the cli without using a web browser.<br />
<br />
{{Tip|The sprunge and ix pastebins can be accessed directly via curl, which should return a link to the paste: {{bc|<nowiki><command> | curl -F 'sprunge=<-' http://sprunge.us</nowiki><br><br><nowiki><command> 2>&1 | curl -F 'f:1=<-' ix.io</nowiki>}}<br />
There is also a [https://github.com/robbyrussell/oh-my-zsh/wiki/Usage-of-the-%22sprunge%22-command sprunge plugin] for [https://github.com/robbyrussell/oh-my-zsh/wiki oh-my-zsh] (a configuration tool for the [[Zsh]] command shell).}}<br />
<br />
{{Warning|Do not use [http://pastebin.com/ pastebin.com]. It appears to be the most popular site but it is slow, full of adverts, formats the text badly (it will mess up your code) and many people can not even open the site due to aggressive spam filters.}}<br />
<br />
* {{App|Elmer|Pastebin client similar to wgetpaste and curlpaste, except written in Perl and usable with wget or curl. Servers: [http://codepad.org/ codepad.org], [http://rafb.me/ rafb.me], [http://sprunge.us/ sprunge.us].|https://github.com/sudokode/elmer|{{AUR|elmer}}}}<br />
* {{App|Fb-client|Client for the [http://paste.xinu.at/ paste.xinu.at] pastebin.|http://paste.xinu.at|{{Pkg|fb-client}}}}<br />
* {{App|Gist|Command-line interface for the [https://gist.github.com/ gist.github.com] pastebin service.|http://github.com/defunkt/gist|{{AUR|gist}}}}<br />
* {{App|Haste|Universal pastebin tool, written in Haskell. Servers: [http://hpaste.org/ hpaste.org], [http://paste2.org/ paste2.org], [http://pastebin.com/ pastebin.com] and others.|http://hackage.haskell.org/package/haste|{{AUR|ruby-haste}} {{AUR|ruby-haste-git}}}}<br />
* {{App|Hg-paste|Pastebin extension for Mercurial which can send diffs to various pastebin websites for easy sharing. Servers: [http://dpaste.com/ dpaste.com] and [http://dpaste.org/ dpaste.org].|http://bitbucket.org/sjl/hg-paste|{{AUR|hg-paste}}}}<br />
* {{App|imgur|A CLI client which can upload image to [http://imgur.com imgur.com] image sharing service.|http://imgur.com/apps|{{AUR|imgur}}}}<br />
* {{App|Ix|Client for the ix.io pastebin.|http://ix.io|{{Pkg|ix}}}}<br />
* {{App|Npaste-client|Client for the [http://npaste.de/ npaste.de] pastebin.|http://npaste.de|{{AUR|npaste-client}}}}<br />
* {{App|Pastebinit|Really small Python script that acts as a Pastebin client. Servers: [http://pastie.org/ pastie.org], [http://paste.kde.org/ paste.kde.org], [http://paste.debian.net/ paste.debian.net], [http://paste.ubuntu.com/ paste.ubuntu.com] and others (for a full list see {{ic|pastebinit -l}}).|http://launchpad.net/pastebinit|{{Pkg|pastebinit}}}}<br />
* {{App|Uppity|The pastebin client with an attitude.|https://github.com/Kiwi/Uppity|{{AUR|uppity-git}}}}<br />
* {{App|Vim-gist|Vim script for [https://gist.github.com/ gist.github.com].| http://www.vim.org/scripts/script.php?script_id&#61;2423 |{{AUR|vim-gist}}}}<br />
* {{App|Vim-paster|Vim plugin to paste to any pastebin service using curl.|http://eugeneciurana.com/site.php?page&#61;tools|{{AUR|vim-paster}}}}<br />
* {{App|Wgetpaste|Bash script that automates pasting to a number of pastebin services. Servers: [http://pastebin.ca/ pastebin.ca], [http://codepad.org/ codepad.org], [http://dpaste.com/ dpaste.com] and [http://pastebin.osuosl.org/ pastebin.osuosl.org].|http://wgetpaste.zlin.dk/|{{Pkg|wgetpaste}}}}<br />
* {{App|codepad-git|A codepad.org pastebin client written in python.|http://www.codepad.org|{{AUR|codepad-git}}}}<br />
<br />
=== Bitcoin ===<br />
<br />
See the main article: [[Bitcoin]].<br />
<br />
* {{App|Armory|Bitcoin client with features such as support for multiple wallets, importing keys and backups.|https://github.com/etotheipi/BitcoinArmory|{{AUR|armory-git}}}}<br />
* {{App|[[Bitcoin]]|Official tool to manage Bitcoins, a P2P currency.|http://bitcoin.org/|{{Pkg|bitcoin-daemon}} {{Pkg|bitcoin-qt}}}}<br />
* {{App|Electrum|An easy to use Bitcoin client.|http://electrum.org/|{{Pkg|electrum}}}}<br />
* {{App|MultiBit|A lightweight Bitcoin desktop client powered by the BitCoinJ library.|https://multibit.org/|{{Pkg|multibit}}}}</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mutt&diff=292677Mutt2014-01-13T08:37:08Z<p>Kevr: /* Passwords management */</p>
<hr />
<div>[[Category:Email Client]]<br />
[[es:Mutt]]<br />
[[it:Mutt]]<br />
[[zh-CN:Mutt]]<br />
[[zh-TW:Mutt]]<br />
{{Related articles start}}<br />
{{Related|fdm}}<br />
{{Related|msmtp}}<br />
{{Related|offlineimap}}<br />
{{Related articles end}}<br />
'''Mutt''' is a text-based mail client renowned for its powerful features. Though over a decade old, Mutt remains the mail client of choice for a great number of power-users. Unfortunately, a default Mutt install is plagued by complex keybindings along with a daunting amount of documentation. This guide will help the average user get Mutt up and running, and begin customizing it to their particular needs.<br />
<br />
==Overview==<br />
Mutt focuses primarily on being a Mail User Agent (MUA), and was originally written to view mail. Later implementations (added for retrieval, sending, and filtering mail) are simplistic compared to other mail applications and, as such, users may wish to use external applications to extend Mutt's capabilities. <br />
<br />
Nevertheless, the Arch Linux {{Pkg|mutt}} package is compiled with IMAP, POP3 and SMTP support, removing the necessity for external applications.<br />
<br />
This article covers using both native IMAP sending and retrieval, and a setup depending on [[OfflineIMAP]] or [[getmail]] (POP3) to retrieve mail, [[procmail]] to filter it in the case of POP3, and [[msmtp]] to send it.<br />
<br />
==Installing==<br />
[[pacman|Install]] {{Pkg|mutt}}, available in the [[Official Repositories]]. <br />
<br />
Optionally install external helper applications for an IMAP setup, such as {{Pkg|offlineimap}} and {{Pkg|msmtp}}.<br />
<br />
Or (if using POP3) {{Pkg|getmail}} or {{Pkg|fdm}} and {{Pkg|procmail}}.<br />
<br />
{{Note|<br />
*If you just need the authentication methods LOGIN and PLAIN, these are satisfied with the dependency {{Pkg|libsasl}}<br />
*If you want to (or have to) use CRAM-MD5, GSSAPI or DIGEST-MD5, install the package {{Pkg|cyrus-sasl-gssapi}}<br />
*If you are using Gmail as your SMTP server, you may need to install the package {{Pkg|cyrus-sasl}}<br />
}}<br />
<br />
==Configuring==<br />
This section covers IMAP, [[#POP3]], [[#Maildir]] and [[#SMTP]] configuration.<br />
<br />
Note that Mutt will recognize two locations for its configuration file; {{ic|~/.muttrc}} and {{ic|~/.mutt/muttrc}}. Either location will work.<br />
You should also know some prerequisite for Mutt configuration. Its syntax is very close to the Bourne Shell. For example, you can get the content of another config file:<br />
source /path/to/other/config/file<br />
You can use variables and assign the result of shell commands to them.<br />
set editor=`echo \$EDITOR`<br />
Here the {{ic|$}} gets escaped so that it does not get substituted by Mutt before being passed to the shell.<br />
Also note the use of the backquotes, as bash syntax {{ic|$(...)}} does not work.<br />
Mutt has a lot of predefined variables, but you can also set your own. User variable '''must begin with "my"!'''<br />
set my_name = "John Doe"<br />
<br />
===IMAP===<br />
''Native and external setups''<br />
<br />
====Using native IMAP support====<br />
The pacman version of Mutt is compiled with IMAP support. At the very least you need to have 4 lines in your muttrc file to be able to access your mail.<br />
<br />
=====imap_user=====<br />
set imap_user=USERNAME<br />
<br />
Continuing with the previous example, remember that Gmail requires your full email address (this is not standard):<br />
set imap_user=your.username@gmail.com<br />
<br />
=====imap_pass=====<br />
If unset, the password will be prompted for.<br />
set imap_pass=SECRET<br />
<br />
=====folder=====<br />
Instead of a local directory which contains all your mail (and directories), use your server (and the highest folder in the hierarchy, if needed).<br />
set folder=imap[s]://imap.server.domain[:port]/[folder/]<br />
<br />
You do not have to use a folder, but it might be convenient if you have all your other folders inside your INBOX, for example. Whatever you set here as your folder can be accessed later in Mutt with just an equal sign (=) or a plus sign (+). Example:<br />
set folder=imaps://imap.gmail.com/<br />
<br />
It should be noted that for several accounts, it is best practice to use different folders -- e.g. for ''account-hook''. If you have several Gmail account, use<br />
set folder=imaps://username@imap.gmail.com/<br />
instead, where your account is ''username@gmail.com''. This way it will be possible to distinguish the different folders. Otherwise it would lead to authentication errors.<br />
<br />
=====spoolfile=====<br />
The spoolfile is the folder where your (unfiltered) e-mail arrives. Most e-mail services conventionally names it ''INBOX''. You can now use '=' or '+' as a substitution for the full {{ic|folder}} path that was configured above. For example:<br />
set spoolfile=+INBOX<br />
<br />
=====mailboxes=====<br />
Any imap folders that should be checked regularly for new mail should be listed here:<br />
mailboxes =INBOX =family<br />
mailboxes imaps://imap.gmail.com/INBOX imaps://imap.gmail.com/family<br />
<br />
Alternatively, check for all subscribed IMAP folders (as if all were added with a {{Ic|mailboxes}} line):<br />
set imap_check_subscribed<br />
<br />
These two versions are equivalent if you want to subscribe to all folders. So the second method is much more convenient, but the first one gives you more flexibility. Also, newer Mutt versions are configured by default to include a macro bound to the 'y' key which will allow you to change to any of the folders listed under mailboxes.<br />
<br />
If you do not set this variable, the ''spoolfile'' will be used by default.<br />
This variable is also important for the [[#Mutt-Sidebar|sidebar]].<br />
<br />
=====Summary=====<br />
Using these options, you will be able to start Mutt, enter your IMAP password, and start reading your mail. Here is a muttrc snippet (for Gmail) with some other lines you might consider adding for better IMAP support.<br />
{{bc|1=<br />
set folder = imaps://imap.gmail.com/<br />
set imap_user = your.username@gmail.com<br />
set imap_pass = your-imap-password<br />
set spoolfile = +INBOX<br />
mailboxes = +INBOX<br />
<br />
# Store message headers locally to speed things up.<br />
# If hcache is a folder, Mutt will create sub cache folders for each account which may speeds things even more up.<br />
set header_cache = ~/.cache/mutt<br />
<br />
# Store messages locally to speed things up, like searching message bodies.<br />
# Can be the same folder as header_cache.<br />
# This will cost important disk usage according to your e-mail amount.<br />
set message_cachedir = "~/.cache/mutt"<br />
<br />
# Specify where to save and/or look for postponed messages.<br />
set postponed = +[Gmail]/Drafts<br />
<br />
# Allow Mutt to open new imap connection automatically.<br />
unset imap_passive<br />
<br />
# Keep IMAP connection alive by polling intermittently (time in seconds).<br />
set imap_keepalive = 300<br />
<br />
# How often to check for new mail (time in seconds).<br />
set mail_check = 120<br />
}}<br />
<br />
====External IMAP support====<br />
While IMAP-functionality is built into Mutt, it does not download mail for offline-use. The [[OfflineIMAP]] article describes how to download your emails to a local folder which can then be processed by Mutt.<br />
<br />
Consider using applications such as {{pkg|spamassassin}} or {{AUR|imapfilter}} to sort mail.<br />
<br />
===POP3===<br />
''Retrieving and sorting mail with external applications''<br />
<br />
====Retrieving mail====<br />
Create the directory {{ic|~/.getmail/}}. Open the file {{ic|~/.getmail/getmailrc}} in your favorite text editor.<br />
<br />
Here is an example {{ic|getmailrc}} used with a gmail account.<br />
{{bc|1=<br />
[retriever]<br />
type = SimplePOP3SSLRetriever<br />
server = pop.gmail.com<br />
username = username@gmail.com<br />
port = 995<br />
password = password<br />
<br />
[destination]<br />
type = Maildir<br />
path = ~/mail/<br />
}}<br />
<br />
You can tweak this to your POP3 service's specification.<br />
<br />
Most people will like to add the following section to their {{ic|getmailrc}} to prevent all the mail on the server being downloaded every time getmail is ran.<br />
{{bc|1=<br />
[options]<br />
read_all = False<br />
}}<br />
<br />
As you can see {{ic|~/.getmail/getmailrc}} contains sensitive information (namely, email account passwords in plain text). You will want to change access permissions to the directory so only the owner can see it:<br />
<br />
$ chmod 700 ~/.getmail<br />
<br />
For this guide we will be storing our mail in the {{ic|maildir}} format. The two main mailbox formats are {{ic|mbox}} and {{ic|maildir}}. The main difference between the two is that {{ic|mbox}} is one file, with all of your mails and their headers stored in it, whereas a {{ic|maildir}} is a directory tree. Each mail is its own file, which will often speed things up.<br />
<br />
A {{ic|maildir}} is just a folder with the folders {{ic|cur}}, {{ic|new}} and {{ic|tmp}} in it.<br />
mkdir -p ~/mail/{cur,new,tmp}<br />
<br />
Now, run getmail. If it works fine, you can create a cronjob for getmail to run every n hours/minutes. Type {{ic|crontab -e}} to edit cronjobs, and enter the following:<br />
*/10 * * * * /usr/bin/getmail<br />
That will run {{ic|getmail}} every 10 minutes.<br />
<br />
Also, to quiet getmail down, we can reduce its verbosity to zero by adding the following to {{ic|getmailrc}}.<br />
{{bc|1=<br />
[options]<br />
verbose = 0<br />
}}<br />
<br />
=====More than one Email account with getmail=====<br />
By default, when you run {{ic|getmail}} the program searches for the file getmailrc created as seen above. If you have more than one mail account you would like to get mail from, then you can create such a file for each email address, and then tell getmail to run using both of them. Obviously if you have two accounts and two files you cannot have both of them called getmailrc. What you do is give them two different names, using myself as an example: I call one personal, and one university. These two files contain content relevant to my personal mail, and my university work mail respectively. Then to get getmail to work on these two files, instead of searching for getmailrc(default), I use the --rcfile switch like so: {{ic|getmail --rcfile university --rcfile personal}} This can work with more files if you have more email accounts, just make sure each file is in the .getmail directory and make sure to alter the cronjob to run the command with the --rcfile switches. E.g.<br />
'''*/30 * * * * /usr/bin/getmail --rcfile university --rcfile personal'''<br />
<br />
Obviously you can call your files whatever you want, providing you include them in the cronjob or shell command, and they are in the .getmail/ directory, getmail will fetch mail from those two accounts.<br />
<br />
====Sorting mail====<br />
[http://www.procmail.org/ Procmail] is an extremely powerful sorting tool. For the purposes of this wiki, we will do some primitive sorting to get started.<br />
<br />
You must edit your getmailrc to pass retrieved mail to procmail:<br />
{{bc|1=<br />
[destination]<br />
type = MDA_external<br />
path = /usr/bin/procmail<br />
}}<br />
<br />
Now, open up {{ic|.procmailrc}} in your favorite editor. The following will sort all mail from the happy-kangaroos mailing list, and all mail from your lovey-dovey friend in their own maildirs.<br />
{{bc|1=<br />
MAILDIR=$HOME/mail<br />
DEFAULT=$MAILDIR/inbox/<br />
LOGFILE=$MAILDIR/log<br />
<br />
:0:<br />
* ^To: happy-kangaroos@nicehost.com<br />
happy-kangaroos/<br />
<br />
:0:<br />
* ^From: loveydovey@iheartyou.net<br />
lovey-dovey/<br />
}}<br />
After you have saved your {{ic|.procmailrc}}, run getmail and see if procmail succeeds in sorting your mail into the appropriate directories.<br />
<br />
{{Note|One easy to make mistake with .procmailrc is the permission. procmail require it to have permission 644 and will not give meaningless error message if you do not.}}<br />
<br />
===Maildir===<br />
Maildir is a generic and standardized format. Almost every MUA is able to handle Maildirs and Mutt's support is excellent. There are just a few simple things that you need to do to get Mutt to use them. Open your muttrc and add the following lines:<br />
{{bc|1=<br />
set mbox_type=Maildir<br />
set folder=$HOME/mail<br />
set spoolfile=+/<br />
set header_cache=~/.cache/mutt<br />
}}<br />
<br />
This is a minimal Configuration that enables you to access your Maildir and checks for new local Mails in INBOX. This configuration also caches the headers of the eMails to speed up directory-listings. It might not be enabled in your build (but it sure is in the Arch-Package). Note that this does not affect OfflineIMAP in any way. It always syncs the all directories on a Server. {{ic|spoolfile}} tells Mutt which local directories to poll for new Mail. You might want to add more Spoolfiles (for example the Directories of Mailing-Lists) and maybe other things. But this is subject to the Mutt manual and beyond the scope of this document.<br />
<br />
===SMTP===<br />
Whether you use POP or IMAP to receive mail you will probably still send mail using SMTP.<br />
<br />
==== Folders ====<br />
<br />
There is basically only one important folder here: the one where all your sent e-mails will be saved.<br />
record = +Sent<br />
<br />
Gmail saves automatically sent e-mail to {{ic|+[Gmail]/Sent}}, so we do not want<br />
duplicates.<br />
unset record<br />
<br />
====Using native SMTP support====<br />
The pacman version of Mutt is also compiled with SMTP support. Just check the online manual [http://manual.cream.org/index.cgi/muttrc.5 muttrc], or {{ic|man muttrc}} for more information.<br />
<br />
For example:<br />
{{bc|1=<br />
set my_pass='mysecretpass'<br />
set my_user=myname<br />
<br />
set realname = 'Your Real Name'<br />
set from = your-email-address<br />
set use_from = yes<br />
<br />
set smtp_url=smtps://$my_user:$my_pass@smtp.domain.tld<br />
set ssl_force_tls = yes<br />
}}<br />
<br />
Note that if your SMTP credentials are the same as your IMAP credentials, then you can use those variables:<br />
<br />
{{bc|1=<br />
set smtp_url=smtps://$imap_user:$imap_pass@smtp.domain.tld<br />
}}<br />
<br />
You may need to tweak the security parameters. If you get an error like<br />
{{ic|SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol}},<br />
then your server most probably uses the SMTP instead of SMTPS.<br />
<br />
{{bc|1=<br />
set smtp_url=smtp://$imap_user:$imap_pass@smtp.domain.tld<br />
}}<br />
<br />
There is other variable that you may need to set. For example for use of STARTTLS:<br />
{{bc|1=<br />
set ssl_starttls = yes<br />
}}<br />
<br />
====External SMTP support====<br />
An external SMTP agent such as [[msmtp]], [[SSMTP]] or {{Pkg|opensmtpd}} can also be used. This section exclusively covers configuring Mutt for msmtp.<br />
<br />
Edit Mutt's configuration file or create it if unpresent:<br />
{{hc|muttrc|2=<br />
set realname='Disgruntled Kangaroo'<br />
<br />
set sendmail="/usr/bin/msmtp"<br />
<br />
set edit_headers=yes<br />
set folder=~/mail<br />
set mbox=+mbox<br />
set spoolfile=+inbox<br />
set record=+sent<br />
set postponed=+drafts<br />
set mbox_type=Maildir<br />
<br />
mailboxes +inbox +lovey-dovey +happy-kangaroos<br />
}}<br />
<br />
====Sending mails from Mutt====<br />
Now, startup {{Ic|mutt}}:<br />
<br />
You should see all the mail in {{ic|~/mail/inbox}}. Press {{ic|m}} to compose mail; it will use the editor defined by your {{Ic|EDITOR}} environment variable. If this variable is not set, you can fix it before starting Mutt:<br />
$ export EDITOR=your-favorite-editor<br />
$ mutt<br />
<br />
You should store the EDITOR value into your shell resource configuration file (such as [[bashrc]]).<br />
You can also set the editor from Mutt's configuration file:<br />
{{hc|.muttrc|2=<br />
set editor=your-favorite-editor<br />
}}<br />
<br />
For testing purposes, address the letter to yourself. After you have written the letter, save and exit the editor. You will return to Mutt, which will now show information about your e-mail. Press {{ic|y}} to send it.<br />
<br />
===Multiple accounts===<br />
<br />
Now you should have a working configuration for one account at least. You might wonder how to use several accounts, since we put everything into a single file.<br />
<br />
Well all you need is to write account-specific parameters to their respective files and source them. All the IMAP/POP3/SMTP config for each account should go to its respective folder.<br />
{{Warning|When one account is setting a variable that is not specified for other accounts, you '''must unset''' it for them, otherwise configuration will overlap and you will most certainly experience unexpected behaviour.}}<br />
<br />
Mutt can handle this thanks to one of its most powerful feature: hooks.<br />
Basically a hook is a command that gets executed before a specific action.<br />
There are several hook availables. For multiple accounts, you must use account-hooks ''and'' folder-hooks.<br />
* Folder-hooks will run a command before switching folders. This is mostly useful to set the appropriate SMTP parameters when you are in a specific folder. For instance when you are in your work mailbox and you send a e-mail, it will automatically use your work account as sender.<br />
* Account-hooks will run a command everytime Mutt calls a function related to an account, like IMAP syncing. It does not require you to switch to any folder.<br />
<br />
Hooks take two parameters:<br />
account-hook [!]regex command<br />
folder-hook [!]regex command<br />
The regex is the folder to be matched (or not if preceded by the !).<br />
The command tells what to do.<br />
<br />
Let us give a full example:<br />
<br />
{{hc|.muttrc|<nowiki><br />
## General options<br />
set header_cache = "~/.cache/mutt"<br />
set imap_check_subscribed<br />
set imap_keepalive = 300<br />
unset imap_passive<br />
set mail_check = 60<br />
set mbox_type=Maildir<br />
<br />
## ACCOUNT1<br />
source "~/.mutt/work"<br />
# Here we use the $folder variable that has just been set in the sourced file.<br />
# We must set it right now otherwise the 'folder' variable will change in the next sourced file.<br />
folder-hook $folder 'source ~/.mutt/work'<br />
<br />
## ACCOUNT2<br />
source "~/.mutt/personal"<br />
folder-hook *user@gmail.com/ 'source ~/.mutt/personal'<br />
folder-hook *user@gmail.com/Family 'set realname="Bob"'<br />
</nowiki>}}<br />
<br />
{{hc|.mutt/work|<nowiki><br />
## Receive options.<br />
set imap_user=user@gmail.com<br />
set imap_pass=****<br />
set folder = imaps://user@imap.gmail.com/<br />
set spoolfile = +INBOX<br />
set postponed = +Drafts<br />
set record = +Sent<br />
<br />
## Send options.<br />
set smtp_url=smtps://user:****@smtp.gmail.com<br />
set realname='User X'<br />
set from=user@gmail.com<br />
set hostname="gmail.com"<br />
set signature="John Doe"<br />
# Connection options<br />
set ssl_force_tls = yes<br />
unset ssl_starttls<br />
<br />
## Hook -- IMPORTANT!<br />
account-hook $folder "set imap_user=user@gmail.com imap_pass=****"<br />
</nowiki>}}<br />
<br />
Finally {{ic|.mutt/personal}} should be similar to {{ic|.mutt/work}}.<br />
<br />
Now all your accounts are set, start Mutt. To switch from one account to another, just change the folder ({{ic|c}} key). Alternatively you can use the [[#Mutt-Sidebar|sidebar]].<br />
<br />
To change folder for different mailboxes you have to type the complete address -- for IMAP/POP3 folders, this may be quite inconvenient -- let us bind some key to it.<br />
<br />
{{bc|<br />
## Shortcuts<br />
macro index,pager <f2> '<sync-mailbox><enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
macro index,pager <f3> '<sync-mailbox><enter-command>source ~/.mutt/work<enter><change-folder>!<enter>'<br />
}}<br />
<br />
With the above shortcuts (or with the sidebar) you will find that changing folders (with {{ic|c}} by default) is not contextual, ''i.e.'' it will not list the folders of the current mailbox, but of the one used the last time you changed folders. To make the behaviour more contextual, the trick is to press ''='' or ''+'' for current mailbox. You can automate this with the following macro:<br />
macro index 'c' '<change-folder>?<change-dir><home>^K=<enter>'<br />
<br />
===Passwords management===<br />
Keep in mind that writing your password in {{ic|.muttrc}} is a security risk, and it might be of your concern.<br />
The trivial way to keep your passwords safe is not writing them in the config file. Mutt will then prompt for it when needed.<br />
However, this is quiet combersome in the long run, especiallly if you have several accounts.<br />
<br />
Here follows a smart and convenient solution: all your passwords are encrypted into one file and Mutt will prompt for a passphrase on startup only. You can opt for a keyring tool (e.g. GPG, {{pkg|pwsafe}}) or an encryption tool like {{pkg|ccrypt}}, which may be more simple and straightforward to use.<br />
Since GPG is a Mutt dependency, we will use it here.<br />
<br />
First create a pair of public/private keys:<br />
gpg --gen-key<br />
If you do not understand this process have a look at [[Wikipedia:Asymmetric cryptography]].<br />
<br />
Create a file '''in a secure environment''' since it will contain your passwords for a couple of seconds:<br />
{{hc|~/.my-pwds|<nowiki><br />
set my_pw_personal = ****<br />
set my_pw_work = ****</nowiki><br />
}}<br />
{{Note|Remember that user defined variables '''must''' start with {{ic|my_}}}}<br />
<br />
Now encrypt the file:<br />
gpg -e -r 'your-name' ~/.my-pwds<br />
Note that 'your-name' must match the one you provided at the {{ic|gpg --gen-key}} step.<br />
Now you can wipe your file containing your passwords in clear:<br />
shred -xu ~/.my-pwds<br />
Back to your account dedicated files, e.g. {{ic|.mutt/muttrc}}:<br />
{{bc|1=<br />
set imap_pass=$my_pw_personal<br />
# Every time the password is needed, use $my_pw_personal variable.<br />
}}<br />
<br />
And in your {{ic|.muttrc}}, '''before''' you source any account dedicated file:<br />
{{bc|<br />
source "gpg2 -dq $HOME/.my-pwds.gpg {{ic|<nowiki>|</nowiki>}}"<br />
}}<br />
{{Note|At the end of the line above, there is no space between the pipe and the double quote.}}<br />
* The {{ic|-q}} parameter makes gpg2 quiet which prevents gpg2 output messing with Mutt interface.<br />
* The pipe {{ic|<nowiki>|</nowiki>}} at the end of a string is the Mutt syntax to tell that you want the result of what is preceeding.<br />
<br />
Explanation: when Mutt starts, it will first source the result of the password decryption, that's why it will prompt for a passphrase. Then all passwords will be stored in memory in specific variables for the time Mutt runs. Then, when a folder-hook is called, it sets the imap_pass variable to the variable holding the appropriate password. When switching accounts, the imap_pass variable will be set to another variable holding another password, etc.<br />
<br />
If you use external tools like OfflineIMAP and msmtp, you need to set up an agent (e.g. gpg-agent, see [[GnuPG#gpg-agent]]) to keep the passphrase into cache and thus avoiding those tools always prompting for it.<br />
<br />
{{Note|Storing a gpg encrypted password in a variable in your muttrc.}}<br />
{{bc|<br />
echo "password" > ~/.my-pwd<br />
gpg -e -r 'your-name' ~/.my-pwd<br />
shred -xu ~/.my-pwd<br />
}}<br />
<br />
Once you have setup ~/.my-pwd.gpg, continue to editing {{ic|.muttrc}}<br />
{{bc|1=<br />
set my_pw = `gpg -dq ~/.my-pwd.gpg`<br />
set imap_pass = $my_pw<br />
}}<br />
<br />
==Advanced features==<br />
Guides to get you started with using & customizing Mutt : <br />
* [http://mutt.blackfish.org.uk/ My first Mutt] (maintained by Bruno Postle) <br />
* [http://www.therandymon.com/woodnotes/mutt/using-mutt.html The Woodnotes Guide to the Mutt Email Client] (maintained by Randall Wood)<br />
* [http://stevelosh.com/blog/2012/10/the-homely-mutt The Homely Mutt] (by Steve Losh)<br />
<br />
If you have any Mutt specific questions, feel free to ask in [[ArchChannel|the irc channel]].<br />
<br />
===E-mail character encoding===<br />
You may be concerned with sending e-mail in a decent character set (charset for short) like UTF-8. Nowadays UTF-8 is highly recommended to almost everyone.<br />
<br />
When using Mutt there is two levels where the charset must be specified:<br />
* The text editor used to write the e-mail must save it in the desired encoding.<br />
* Mutt will then check the e-mail and determine which encoding is the more apropriate according to the priority you specified in the {{ic|send_charset}} variable. Default: "us-ascii:iso-8859-1:utf-8".<br />
<br />
So if you write an e-mail with characters allowed in ISO-8859-1 (like 'résumé'), but without characters specific to Unicode, then Mutt will set the encoding to ISO-8859-1.<br />
<br />
To avoid this behaviour, set the variable in your {{ic|muttrc}}:<br />
set send_charset="us-ascii:utf-8"<br />
or even<br />
set send_charset="utf-8"<br />
<br />
The first compatible charset starting from the left will be used.<br />
Since UTF-8 is a superset of US-ASCII it does not harm to leave it in front of UTF-8, it may ensure old MUA will not get confused when seeing the charset in the e-mail header.<br />
<br />
===Printing===<br />
You can install {{AUR|muttprint}} from the [[AUR]] for a fancier printing quality.<br />
In your muttrc file, insert:<br />
set print_command="/usr/bin/muttprint %s -p {PrinterName}"<br />
<br />
===Custom mail headers===<br />
One of the greatest thing in Mutt is that you can have full control over your mail header.<br />
<br />
First, make your headers editable when you write e-mails:<br />
set edit_headers=yes<br />
<br />
Mutt also features a special function {{ic|my_hdr}} for customizing your header. Yes, it is named just like a variable, but in fact it is a function.<br />
<br />
You can clear it completely, which you ''should'' do when switching accounts with different headers, otherwise they will overlap:<br />
unmy_hdr *<br />
<br />
Other variables have also an impact on the headers, so it is wise to clear them before using {{ic|my_hdr}}:<br />
unset use_from<br />
unset use_domain<br />
unset user_agent<br />
<br />
Now, you can add any field you want -- even non-standard one -- to your header using the following syntax:<br />
my_hdr <FIELD>: <VALUE><br />
Note that <VALUE> can be the result of a command.<br />
<br />
Example:<br />
{{bc|<br />
## Extra info.<br />
my_hdr X-Info: Keep It Simple, Stupid.<br />
<br />
## OS Info.<br />
my_hdr X-Operating-System: `uname -s`, kernel `uname -r`<br />
<br />
## This header only appears to MS Outlook users<br />
my_hdr X-Message-Flag: WARNING!! Outlook sucks<br />
<br />
## Custom Mail-User-Agent ID.<br />
my_hdr User-Agent: Every email client sucks, this one just sucks less.<br />
}}<br />
<br />
===Signature block===<br />
Create a .signature in your home directory. Your signature will be appended at the end of your email.<br />
Alternatively you can specify a file in your Mutt configuration:<br />
set signature="path/to/sig/file"<br />
====Random signature====<br />
You can use fortune to add a random signature to Mutt.<br />
{{bc|$ pacman -S fortune-mod}}<br />
<br />
Create a fortune file and then add the following line to your .muttrc:<br />
{{bc|1=set signature="fortune pathtofortunefile&#124;"}}<br />
Note the pipe at the end. It tells Mutt that the specified string is not a file, but a command.<br />
<br />
===Viewing URLs & opening your favorite web browser===<br />
Your should start by creating a .mutt directory in $HOME if not done yet. There, create a file named macros. Insert the following:<br />
macro pager \cb <pipe-entry>'urlview'<enter> 'Follow links with urlview'<br />
<br />
Then install {{AUR|urlview}} from the [[AUR]].<br />
<br />
Create a .urlview in $HOME and insert the following:<br />
REGEXP (((http|https|ftp|gopher)|mailto)[.:][^ >"\t]*|www\.[-a-z0-9.]+)[^ .,;\t>">\):]<br />
COMMAND <your-browser> %s <br />
<br />
When you read an email on the pager, hitting ctrl+b will list all the urls from the email. Navigate up or down with arrow keys and hit enter on the desired url. Your browser will start and go to the selected site.<br />
<br />
Some browser will require additional arguments to work properly. For example, [[Luakit]] will close on Mutt exit. You need to fork it to background, using the {{ic|-n}} parameter:<br />
COMMAND luakit -n %s 2>/dev/null<br />
The {{ic|2>/dev/null}} is to make it quiet, i.e. to prevent useless message printing where you do not want them to.<br />
<br />
{{Note|urlview has a few deficiencies (e.g. the inability to handle certain email encodings) and is fairly feature-bare (e.g. it does not provide context for links it finds). There are a couple alternatives that do better. One, which can handle all email encodings and provides link context, is [http://www.memoryhole.net/~kyle/extract_url/ extract_url.pl]. Another, which can also provide link context but cannot handle all email encodings, is [https://aur.archlinux.org/packages.php?ID&#61;44853 urlscan]. Both are drop-in replacements for urlview, though extract_url has features which benefit from additional configuration changes.}}<br />
<br />
===Viewing HTML===<br />
It is possible to pass the html body to an external HTML program and then dump it, keeping email viewing uniform and unobtrusive. Three programs are described here: lynx, w3m and elinks.<br />
<br />
Install lynx, w3m or elinks:<br />
pacman -S lynx<br />
or<br />
pacman -S w3m<br />
or<br />
pacman -S elinks<br />
<br />
If {{ic|~/.mutt/mailcap}} does not exist you will need to create it and save the following to it.<br />
text/html; lynx -display_charset=utf-8 -dump %s; nametemplate=%s.html; copiousoutput<br />
or, in case of w3m,<br />
text/html; w3m -I %{charset} -T text/html; copiousoutput;<br />
or, in case of elinks,<br />
text/html; elinks -dump ; copiousoutput;<br />
<br />
Edit muttrc and add the following,<br />
set mailcap_path = ~/.mutt/mailcap<br />
<br />
To automatically open HTML messages in lynx, add this additional line to the muttrc:<br />
auto_view text/html<br />
<br />
The beauty of this is, instead of seeing an html body as source or being opened<br />
by a separate program, in this case lynx, you see the formatted content directly,<br />
and any url links within the email can be displayed with {{ic|Ctrl+b}}.<br />
<br />
If you receive many emails with multiple or alternate encodings Mutt may default to treating every email as html. To avoid this, add the following variable to your ~/.muttrc to have Mutt default to text when available and use w3m/lynx only when no text version is availble in the email:<br />
alternative_order text/plain text/html<br />
<br />
Some HTML mails may not display correctly in a text-based web browser. As a fallback solution, you can bind a key to open a graphical browser in such cases.<br />
The following macro will open the HTML mail selected from the attachment view in the web browser defined in the environment. (Feel free to adapt the {{ic|~/.cache/mutt/}} folder).<br />
macro attach 'V' "<pipe-entry>cat >~/.cache/mutt/mail.html && $BROWSER ~/.cache/mutt/mail.html && rm ~/.cache/mutt/mail.html<enter>"<br />
<br />
===Mutt and Vim===<br />
*To limit the width of text to 72 characters, edit your .[[vim]]rc file and add:<br />
au BufRead /tmp/mutt-* set tw=72<br />
<br />
*Another choice is to use Vim's mail filetype plugin to enable other mail-centric options besides 72 character width. Edit {{ic|~/.vim/filetype.vim}}, creating it if unpresent, and add:<br />
{{bc| <br />
augroup filetypedetect<br />
" Mail<br />
autocmd BufRead,BufNewFile *mutt-* setfiletype mail<br />
augroup END<br />
}}<br />
<br />
*To set a different tmp directory, e.g. ~/.tmp, add a line to your muttrc as follows:<br />
set tmpdir="~/.tmp"<br />
<br />
*To reformat a modified text see the Vim context help<br />
:h 10.7<br />
<br />
===Mutt and GNU nano===<br />
[[nano]] is another nice console editor to use with Mutt. <br />
<br />
To limit the width of text to 72 characters, edit your .nanorc file and add:<br />
set fill 72<br />
<br />
Also, in muttrc file, you can specify the line to start editing so that you will skip the mail header:<br />
set editor="nano +7"<br />
<br />
===Mutt and Emacs===<br />
Emacs has a ''mail'' and a ''message'' major mode.<br />
To switch to mail-mode automatically when Emacs is called from Mutt, you can add the following to your {{ic|.emacs}}:<br />
{{hc|.emacs|<nowiki><br />
;; Mutt support.<br />
(setq auto-mode-alist (append '(("/tmp/mutt.*" . mail-mode)) auto-mode-alist))<br />
</nowiki>}}<br />
<br />
If you usually run Emacs daemon, you may want Mutt to connect to it. Add this to your {{ic|.muttrc}}:<br />
{{hc|.muttrc|<nowiki><br />
set editor="emacsclient -a \"\" -t"</nowiki><br />
}}<br />
<br />
===Colors===<br />
Append sample color definitions to your .muttrc file:<br />
$ cat /usr/share/doc/mutt/samples/colors.linux >> ~/.muttrc<br />
Then adjust to your liking.<br />
The actual color each of these settings will produce depends on the colors set in your [[Xresources|~/.Xresources]] file.<br />
<br />
Alternatively, you can source any file you want containing colors (and thus act as a theme file):<br />
{{bc|<br />
source ~/.mutt/colors.zenburn<br />
}}<br />
<br />
A nice theme example:<br />
{{bc|<nowiki><br />
## Theme kindly inspired from <br />
## http://nongeekshandbook.blogspot.ie/2009/03/mutt-color-configuration.html <br />
<br />
## Colours for items in the index <br />
color index brightcyan black ~N<br />
color index brightred black ~O<br />
color index brightyellow black ~F<br />
color index black green ~T<br />
color index brightred black ~D<br />
mono index bold ~N<br />
mono index bold ~F<br />
mono index bold ~T<br />
mono index bold ~D<br />
<br />
## Highlights inside the body of a message. <br />
<br />
## URLs <br />
color body brightgreen black "(http|ftp|news|telnet|finger)://[^ \"\t\r\n]*"<br />
color body brightgreen black "mailto:[-a-z_0-9.]+@[-a-z_0-9.]+"<br />
mono body bold "(http|ftp|news|telnet|finger)://[^ \"\t\r\n]*"<br />
mono body bold "mailto:[-a-z_0-9.]+@[-a-z_0-9.]+"<br />
<br />
## Email addresses. <br />
color body brightgreen black "[-a-z_0-9.%$]+@[-a-z_0-9.]+\\.[-a-z][-a-z]+"<br />
<br />
## Header <br />
color header green black "^from:"<br />
color header green black "^to:"<br />
color header green black "^cc:"<br />
color header green black "^date:"<br />
color header yellow black "^newsgroups:"<br />
color header yellow black "^reply-to:"<br />
color header brightcyan black "^subject:"<br />
color header red black "^x-spam-rule:"<br />
color header green black "^x-mailer:"<br />
color header yellow black "^message-id:"<br />
color header yellow black "^Organization:"<br />
color header yellow black "^Organisation:"<br />
color header yellow black "^User-Agent:"<br />
color header yellow black "^message-id: .*pine"<br />
color header yellow black "^X-Fnord:"<br />
color header yellow black "^X-WebTV-Stationery:"<br />
<br />
color header red black "^x-spam-rule:"<br />
color header green black "^x-mailer:"<br />
color header yellow black "^message-id:"<br />
color header yellow black "^Organization:"<br />
color header yellow black "^Organisation:"<br />
color header yellow black "^User-Agent:"<br />
color header yellow black "^message-id: .*pine"<br />
color header yellow black "^X-Fnord:"<br />
color header yellow black "^X-WebTV-Stationery:"<br />
color header yellow black "^X-Message-Flag:"<br />
color header yellow black "^X-Spam-Status:"<br />
color header yellow black "^X-SpamProbe:"<br />
color header red black "^X-SpamProbe: SPAM"<br />
<br />
## Coloring quoted text - coloring the first 7 levels: <br />
color quoted cyan black<br />
color quoted1 yellow black<br />
color quoted2 red black<br />
color quoted3 green black<br />
color quoted4 cyan black<br />
color quoted5 yellow black<br />
color quoted6 red black<br />
color quoted7 green black<br />
<br />
## Default color definitions <br />
#color hdrdefault white green <br />
color signature brightmagenta black<br />
color indicator black cyan<br />
color attachment black green<br />
color error red black<br />
color message white black<br />
color search brightwhite magenta<br />
color status brightyellow blue<br />
color tree brightblue black<br />
color normal white black<br />
color tilde green black<br />
color bold brightyellow black<br />
#color underline magenta black <br />
color markers brightcyan black<br />
<br />
## Colour definitions when on a mono screen <br />
mono bold bold<br />
mono underline underline<br />
mono indicator reverse</nowiki><br />
}}<br />
<br />
===Index Format===<br />
<br />
Here follows a quick example to put in your {{ic|.muttrc}} to customize the Index Format, i.e. the columns displayed in the folder view.<br />
{{bc|<nowiki><br />
set date_format="%y-%m-%d %T"<br />
set index_format="%2C | %Z [%d] %-30.30F (%-4.4c) %s"</nowiki><br />
}}<br />
See the [http://www.mutt.org/doc/manual/manual-6.html Mutt Reference], {{ic|man 3 strftime}} and {{ic|man 3 printf}} for more details.<br />
<br />
====Display recipient instead of sender in "Sent" folder view====<br />
<br />
By default Mutt will display the sender in the index view. It is fine for most folders, but rather useless for the one were you store a copy of your sent e-mails since it will always display your name.<br />
<br />
The "columns" of the index can be configured through the {{ic|index_format}} variable. Its syntax is documented in the {{ic|muttrc}} man page. The values of our concern are {{ic|%t}} (recipient) and {{ic|%F}} (sender).<br />
<br />
To change the columns according to the current folder, we need to use a hook:<br />
{{hc|muttrc|<nowiki><br />
folder-hook *[sS]ent* 'set index_format="%2C | %Z [%d] %-30.30t (%-4.4c) %s"'<br />
folder-hook ! *[sS]ent* 'set index_format="%2C | %Z [%d] %-30.30F (%-4.4c) %s"'<br />
</nowiki>}}<br />
<br />
The exclamation mark means ''everything that does not match the following regex''. Of course you can change the index_format following you taste, and the regular expression if the folder does not have ''Sent'' not ''sent'' in its name.<br />
<br />
====Variable column width====<br />
<br />
If you rezise the window, the subject might get truncated while there is still unused space left for some fields, like for the sender.<br />
You can get the maximum column of your terminal (i.e. the width) using a shell call to {{ic|tput cols}}. With this value you can set a percentage of the width to fields like Sender and Subject.<br />
<br />
Example using the above folder-hook and a sidebar width of 24:<br />
{{hc|muttrc|<nowiki><br />
## From field gets 30% of remaining space, Subject gets 70%.<br />
## Remaining space is the total width minus the other fields (35), minus the sidebar (24)<br />
set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`<br />
set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`<br />
<br />
folder-hook .*[sS]ent.* 'set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}t (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
folder-hook ! .*[sS]ent.* 'set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}F (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
</nowiki><br />
}}<br />
<br />
Unfortunately, the above example suffers from one caveat: the {{ic|my_col_*}} variables get computed one time only, on first start. So if you want it to refresh automatically, we need to set the variable in a hook. Sadly there is no hook for window resizing, but you can still use the {{ic|folder-hook}} so that a simple folder switch suffice to recompute the view.<br />
{{hc|muttrc|<nowiki><br />
folder-hook .*[sS]ent.* 'set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`; set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`; set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}t (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
folder-hook ! .*[sS]ent.* 'set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`; set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`; set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}F (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
</nowiki><br />
}}<br />
<br />
===Contact management===<br />
<br />
====Address aliases====<br />
''Aliases'' is the way Mutt manages contacts.<br />
An alias is '''nickname [longname] <address>'''.<br />
* The '''nickname''' is what you will type in Mutt to get your contact address. One word only, and should be easy to remember.<br />
* The '''longname''' is optional. It may be several words.<br />
* An '''<address>''' must be in a valid form (i.e. with an {{ic|@}}).<br />
<br />
It is quite simple indeed. Add this to {{ic|.muttrc}}:<br />
{{bc|1=<br />
set alias_file = "~/.mutt/aliases"<br />
set sort_alias = alias<br />
set reverse_alias = yes<br />
source $alias_file<br />
}}<br />
<br />
Explanation:<br />
* {{ic|alias_file}} is the file where the information is getting stored when you add an alias from within Mutt.<br />
* {{ic|sort_alias}} specifies which field to use to sort the alias list when displayed in Mutt. Possible values: alias, address.<br />
* {{ic|reverse_alias}} sorts in reverse order if set to yes.<br />
* {{ic|source $alias_file}} tells Mutt to read aliases on startup. Needed for auto-completion.<br />
<br />
Now all you have to do when prompted {{ic|To:}} is writing the alias instead of the full address. The beauty of it is that you can auto-complete the alias using {{ic|Tab}}.<br />
Autocompleting a wrong or an empty string will display the full list. You can select the alias as usual, or by typing its index number.<br />
<br />
There is two ways to create aliases:<br />
* From Mutt, press {{ic|a}} when an e-mail of the targetted person if selected.<br />
* Edit the alias_file manually. The syntax is really simple:<br />
{{bc|<br />
alias nickname Long Name <my-friend@domain.tld><br />
}}<br />
<br />
====Abook====<br />
<br />
{{pkg|abook}} is a stand-alone program dedicated to contact management. It uses a very simple text-based interface and contacts are stored in a plain text, human-readable database. Besides the desired contact properties are extensible (birthday, address, fax, and so on).<br />
<br />
Abook is specifically designed to be interfaced with Mutt, so that it can serve as a full, more featured replacement of Mutt internal aliases. If you want to use Abook instead of aliases, remove the aliases configuration in {{ic|.muttrc}} and add this:<br />
<br />
{{hc|muttrc|<nowiki><br />
## Abook<br />
set query_command= "abook --mutt-query '%s'"<br />
macro index,pager a "<pipe-message>abook --add-email-quiet<return>" "Add this sender to Abook"<br />
bind editor <Tab> complete-query<br />
</nowiki><br />
}}<br />
<br />
See the man pages {{ic|abook}} and {{ic|abookrc}} for more details and a full configuration sample.<br />
<br />
===Request IMAP mail retrieval manually===<br />
If you do not want to wait for the next automatic IMAP fetching (or if you did not enable it), you might want to fetch mails manually.<br />
There is a mutt command {{ic|imap-fetch-mail}} for that.<br />
Alternatively, you could bind it to a key:<br />
bind index "^" imap-fetch-mail<br />
<br />
===Avoiding slow index on large (IMAP) folders due to coloring===<br />
<br />
Index highlighting by regex is nice, but can lead to slow folder viewing if your regex checks the body of the message.<br />
<br />
Use folder-hook for only highlighting in for example the inbox (if you manage to empty your mailbox effiently):<br />
<br />
folder-hook . 'uncolor index "~b \"Hi Joe\" ~R !~T !~F !~p !~P"'<br />
folder-hook ""!"" 'color index brightyellow black "~b \"Hi Joe\" ~N !~T !~F !~p !~P"'<br />
<br />
===Speed up folders switch===<br />
Add this to your {{ic|.muttrc}}:<br />
{{bc|1=<br />
set sleep_time = 0<br />
}}<br />
<br />
===Use Mutt to send mail from command line===<br />
Man pages will show all available commands and how to use them, but here are a couple of examples. You could use Mutt to send alerts, logs or some other system information, triggered by login through .bash_profile, or as a regular cron job.<br />
<br />
Send a message:<br />
mutt -s "Subject" somejoeorjane@someserver.com < /var/log/somelog<br />
<br />
Send a message with attachment:<br />
mutt -s "Subject" somejoeorjane@someserver.com -a somefile < /tmp/sometext.txt<br />
<br />
===Composing HTML e-mails===<br />
<br />
Since Mutt has nothing of a WYSIWIG client, HTML is quite straightforward, and you can do much more than with all WYSIWIG mail clients around since you edit the source code directly.<br />
Simply write your mail using HTML syntax. For example:<br />
{{bc|<nowiki><br />
This is normal text<br><br />
<b>This is bold text</b></nowiki><br />
}}<br />
Now before sending the mail, use the {{ic|edit-type}} command (default shortcut {{ic|Ctrl+t}}), and replace {{ic|text/plain}} by {{ic|text/html}}.<br />
<br />
{{Note|HTML e-mails are regarded by many people as useless, cumbersome, and subject to reading issues. Mutt can read HTML mails with a text browser like w3m or lynx, but it has clearly no advantage over a plain-text e-mail. You should avoid writing HTML e-mails when possible.}}<br />
<br />
===How to display another email while composing===<br />
A common complaint with Mutt is that when composing a new mail (or reply), you cannot open another mail (i.e. for checking with another correspondent) without closing the current mail (postponing). The following describes a solution:<br />
<br />
First, fire up Mutt as usual. Then, launch another terminal window. Now start a new Mutt with <br />
mutt -R<br />
This starts Mutt in read-only mode, and you can browse other emails at your convenience. It is strongly recommended to always launch a second Mutt in read-only mode, as conflicts will easily arise otherwise.<br />
<br />
Now, this solution calls for a bit of typing, so we would like to automate this. The following works with [[Awesome]], in other WM's or DE's similar solutions are probably available: just google how to add a key binding, and make the desired key execute <br />
$TERM -e mutt -R <br />
where $TERM is your terminal.<br />
<br />
As for Awesome: edit your rc.lua, and add the following on one of the first lines, after terminal = "yourTerminal" etc.<br />
mailview = terminal .. " -e mutt -R"<br />
This automatically uses your preferred terminal, ".." is concatenation in Lua. Note the space before -e.<br />
<br />
Then add the following inside --{{{ Key bindings<br />
awful.key({ modkey, }, "m", function() awful.util.spawn(mailview) end),<br />
<br />
Omit the final comma if this is the last line. You can, of course use another key than "m". Now, save&quit, and check your syntax with <br />
awesome -k<br />
If this is good, restart awesome and give it a try!<br />
<br />
Now, a usage example: Launch Mutt as usual. Start a new mail, and then press "Mod4"+"m". This opens your mailbox in a new terminal, and you can browse around and read other emails. Now, a neat bonus: exit this read-only-Mutt with "q", and the terminal window it created disappears!<br />
<br />
===Archive treated e-mails===<br />
When you read an e-mail, you have four choices: Answer it, Flag it, Archive it or Delete it. If you have this in mind, you can keep your inbox slim and fit with this macro (set up for Gmail):<br />
<br />
macro index \' "<tag-pattern>~R !~D !~F<enter>\<br />
<tag-prefix><save-message>+[Gmail]/All <enter>" \<br />
"Archive"<br />
<br />
===Mutt-Sidebar===<br />
<br />
The vanilla Mutt does not feature a sidebar unlike most MUAs. If you miss it, you can install {{Aur|mutt-sidebar}} from the AUR which features a patch for a list of folders on the left side of the Mutt window.<br />
<br />
For a while there has been several different patches for the sidebar. Since the late 2000's, it seems like the main patch is maintained at [http://www.lunar-linux.org/mutt-sidebar/ Lunar Linux]. See the documentation there. Note that the patch also updates the {{ic|muttrc}} man page, so have a look at the {{ic|sidebar_*}} sections.<br />
<br />
You can choose to display the sidebar on startup, or to prompt it manually with a key:<br />
{{bc|<nowiki><br />
set sidebar_visible = yes<br />
macro index b '<enter-command>toggle sidebar_visible<enter><refresh>'<br />
macro pager b '<enter-command>toggle sidebar_visible<enter><redraw-screen>'<br />
</nowiki>}}<br />
<br />
You also probabaly need some shortcuts to navigate in the bar:<br />
{{bc|<nowiki><br />
# Ctrl-n, Ctrl-p to select next, previous folder.<br />
# Ctrl-o to open selected folder.<br />
bind index,pager \CP sidebar-prev<br />
bind index,pager \CN sidebar-next<br />
bind index,pager \CO sidebar-open<br />
</nowiki>}}<br />
<br />
{{Note|You ''must'' set the {{ic|mailboxes}} variables or the {{ic|imap_check_subscribed}} to tell the sidebar which folder should be displayed. See the [[#mailboxes|mailboxes]] section.}}<br />
<br />
If you use the {{ic|imap_check_subscribed}} option to list all your folders, they will appear in an uncontrollable order in the sidebar. Fix it with<br />
set sidebar_sort = yes<br />
Note that with the {{ic|mailboxes}} option, folders appear in the order they were set to {{ic|mailboxes}} if you do not use the {{ic|sidebar_sort}} option.<br />
<br />
If you have trouble with truncated names, set the option<br />
set sidebar_shortpath = yes<br />
<br />
Finally, you may want to add a separator between different mailboxes. The sidebar patch does not currently provide any kind of separator option. A simple (and dirty) workaround is to add a fake folder to the list of folders:<br />
mailboxes "+-- My mailbox -----------"<br />
The dashes are not required, they are here just for fancy output.<br />
It will also work if you used the {{ic|imap_check_subscribed}} option.<br />
If you chose to sort the folders, the separator will not appear in the correct place, so an even more dirty workaround is to add an 'A' in front of the name. Note that punctuation is ignored during sorting.<br />
mailboxes "+A-- My mailbox -----------"<br />
<br />
===Migrating mails from one computer to another===<br />
In case you are transfering your mails to a new machine (copy&paste), you probably need to delete the header cache (a file or folder like {{ic|~/.cache/mutt}} if you followed the above configuration) to make Mutt able to read your migrated E-Mails. Otherwise Mutt may freeze.<br />
<br />
Note that if you had a folder created for you header cache, all mailboxes will have their own cache file, so you can delete caches individually without having to remove everything.<br />
<br />
=== Filtering the message view ===<br />
<br />
You can restrict the view to e-mails matching a pattern and specific properties with the {{ic|limit}} command (default shortcut: {{ic|l}}).<br />
<br />
To view all e-mails containing "foo" in the header, simply write "foo" and you are done. To remove the filter, use the "all" keyword.<br />
<br />
To view all flagged messages, use<br />
~F<br />
To view all unread messages, use<br />
~U<br />
<br />
All possible patterns are listed in the [http://www.mutt.org/doc/manual/manual-4.html#ss4.2 official manual].<br />
<br />
=== Display the index above the pager view ===<br />
<br />
Set the following variable in your {{ic|muttrc}}:<br />
set pager_index_lines=10<br />
<br />
==Troubleshooting==<br />
<br />
===Backspace does not work in Mutt===<br />
This is a common problem with some xterm-like terminals.<br />
Two solutions:<br />
* Either rebind the key in {{ic|.muttrc}}<br />
bind index,pager ^? previous-page<br />
Note that {{ic|^?}} is one single character representing backspace in [[wikipedia:Caret_notation|caret notation]]. To type in Emacs, use {{ic|Ctrl+q Backspace}}, in Vim {{ic|Ctrl+v Backspace}}.<br />
<br />
* Or fix your terminal:<br />
$ infocmp > termbs.src<br />
Edit {{ic|termbs.src}} and change {{ic|1= kbs=^H}} to {{ic|1= kbs=\177}}, then:<br />
$ tic -x termbs.src<br />
<br />
===Android's default MUA receives empty e-mail with attachment "Unknown.txt"===<br />
<br />
This is because Mutt adds 'Content-Disposition' line to every e-mail header. This line is actually correct, the issue comes from Android 2 MUA misinterpreting it. This bug seems to be fixed in the Android 4 MUA.<br />
There is a patched version for Android available in the AUR. Installing {{AUR|mutt-android-patch}} will fix the issue.<br />
<br />
===The ''change-folder'' function always prompt for the same mailbox ===<br />
<br />
This is not a bug, this is actually an intended behaviour. See the [[#Multiple accounts|multiple accounts section]] for a workaround.<br />
<br />
===I cannot change folder when using Mutt read-only (Mutt -R)===<br />
<br />
This is certainly because you are use are using macros like this one:<br />
macro index,pager <f2> '<sync-mailbox><enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
This macro tells Mutt to sync (which is a write operation) before switching.<br />
Either use the [[#Mutt-Sidebar|sidebar]] or set another macro:<br />
macro index,pager <f3> '<enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
<br />
== Documentation ==<br />
<br />
Newcomers may find it quite hard to find help for Mutt. Actually most of the topics are covered in the official documentation. We urge you to read it.<br />
<br />
* [http://www.mutt.org/doc/manual/ The official manual]. The stock {{pkg|mutt}} package for Arch Linux also installs the HTML and plain text manual at {{ic|/usr/share/doc/mutt/}}.<br />
* The {{ic|mutt}} and {{ic|muttrc}} man pages.<br />
<br />
== See also ==<br />
* [http://www.mutt.org/ The official Mutt website]<br />
* [http://wiki.mutt.org/ The Mutt wiki]<br />
* [http://pbrisbin.com/posts/two_accounts_in_mutt/ Brisbin's great guide on how to setup different IMAP accounts with Mutt, offlineimap, msmtp]<br />
* [http://home.roadrunner.com/~computertaijutsu/mutt.html A Quick Guide to Mutt]<br />
* [http://pyropus.ca/software/getmail/configuration.html#running Documentation on Configuring Getmail with rcfiles]<br />
* [http://stevelosh.com/blog/2012/10/the-homely-mutt/ Steve Losh on Mutt, offlineimap, msmtp, notmuch (gmail focussed)]<br />
* [http://www.muttrcbuilder.org/ muttrc builder]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mutt&diff=292676Mutt2014-01-13T08:34:55Z<p>Kevr: /* Passwords management */</p>
<hr />
<div>[[Category:Email Client]]<br />
[[es:Mutt]]<br />
[[it:Mutt]]<br />
[[zh-CN:Mutt]]<br />
[[zh-TW:Mutt]]<br />
{{Related articles start}}<br />
{{Related|fdm}}<br />
{{Related|msmtp}}<br />
{{Related|offlineimap}}<br />
{{Related articles end}}<br />
'''Mutt''' is a text-based mail client renowned for its powerful features. Though over a decade old, Mutt remains the mail client of choice for a great number of power-users. Unfortunately, a default Mutt install is plagued by complex keybindings along with a daunting amount of documentation. This guide will help the average user get Mutt up and running, and begin customizing it to their particular needs.<br />
<br />
==Overview==<br />
Mutt focuses primarily on being a Mail User Agent (MUA), and was originally written to view mail. Later implementations (added for retrieval, sending, and filtering mail) are simplistic compared to other mail applications and, as such, users may wish to use external applications to extend Mutt's capabilities. <br />
<br />
Nevertheless, the Arch Linux {{Pkg|mutt}} package is compiled with IMAP, POP3 and SMTP support, removing the necessity for external applications.<br />
<br />
This article covers using both native IMAP sending and retrieval, and a setup depending on [[OfflineIMAP]] or [[getmail]] (POP3) to retrieve mail, [[procmail]] to filter it in the case of POP3, and [[msmtp]] to send it.<br />
<br />
==Installing==<br />
[[pacman|Install]] {{Pkg|mutt}}, available in the [[Official Repositories]]. <br />
<br />
Optionally install external helper applications for an IMAP setup, such as {{Pkg|offlineimap}} and {{Pkg|msmtp}}.<br />
<br />
Or (if using POP3) {{Pkg|getmail}} or {{Pkg|fdm}} and {{Pkg|procmail}}.<br />
<br />
{{Note|<br />
*If you just need the authentication methods LOGIN and PLAIN, these are satisfied with the dependency {{Pkg|libsasl}}<br />
*If you want to (or have to) use CRAM-MD5, GSSAPI or DIGEST-MD5, install the package {{Pkg|cyrus-sasl-gssapi}}<br />
*If you are using Gmail as your SMTP server, you may need to install the package {{Pkg|cyrus-sasl}}<br />
}}<br />
<br />
==Configuring==<br />
This section covers IMAP, [[#POP3]], [[#Maildir]] and [[#SMTP]] configuration.<br />
<br />
Note that Mutt will recognize two locations for its configuration file; {{ic|~/.muttrc}} and {{ic|~/.mutt/muttrc}}. Either location will work.<br />
You should also know some prerequisite for Mutt configuration. Its syntax is very close to the Bourne Shell. For example, you can get the content of another config file:<br />
source /path/to/other/config/file<br />
You can use variables and assign the result of shell commands to them.<br />
set editor=`echo \$EDITOR`<br />
Here the {{ic|$}} gets escaped so that it does not get substituted by Mutt before being passed to the shell.<br />
Also note the use of the backquotes, as bash syntax {{ic|$(...)}} does not work.<br />
Mutt has a lot of predefined variables, but you can also set your own. User variable '''must begin with "my"!'''<br />
set my_name = "John Doe"<br />
<br />
===IMAP===<br />
''Native and external setups''<br />
<br />
====Using native IMAP support====<br />
The pacman version of Mutt is compiled with IMAP support. At the very least you need to have 4 lines in your muttrc file to be able to access your mail.<br />
<br />
=====imap_user=====<br />
set imap_user=USERNAME<br />
<br />
Continuing with the previous example, remember that Gmail requires your full email address (this is not standard):<br />
set imap_user=your.username@gmail.com<br />
<br />
=====imap_pass=====<br />
If unset, the password will be prompted for.<br />
set imap_pass=SECRET<br />
<br />
=====folder=====<br />
Instead of a local directory which contains all your mail (and directories), use your server (and the highest folder in the hierarchy, if needed).<br />
set folder=imap[s]://imap.server.domain[:port]/[folder/]<br />
<br />
You do not have to use a folder, but it might be convenient if you have all your other folders inside your INBOX, for example. Whatever you set here as your folder can be accessed later in Mutt with just an equal sign (=) or a plus sign (+). Example:<br />
set folder=imaps://imap.gmail.com/<br />
<br />
It should be noted that for several accounts, it is best practice to use different folders -- e.g. for ''account-hook''. If you have several Gmail account, use<br />
set folder=imaps://username@imap.gmail.com/<br />
instead, where your account is ''username@gmail.com''. This way it will be possible to distinguish the different folders. Otherwise it would lead to authentication errors.<br />
<br />
=====spoolfile=====<br />
The spoolfile is the folder where your (unfiltered) e-mail arrives. Most e-mail services conventionally names it ''INBOX''. You can now use '=' or '+' as a substitution for the full {{ic|folder}} path that was configured above. For example:<br />
set spoolfile=+INBOX<br />
<br />
=====mailboxes=====<br />
Any imap folders that should be checked regularly for new mail should be listed here:<br />
mailboxes =INBOX =family<br />
mailboxes imaps://imap.gmail.com/INBOX imaps://imap.gmail.com/family<br />
<br />
Alternatively, check for all subscribed IMAP folders (as if all were added with a {{Ic|mailboxes}} line):<br />
set imap_check_subscribed<br />
<br />
These two versions are equivalent if you want to subscribe to all folders. So the second method is much more convenient, but the first one gives you more flexibility. Also, newer Mutt versions are configured by default to include a macro bound to the 'y' key which will allow you to change to any of the folders listed under mailboxes.<br />
<br />
If you do not set this variable, the ''spoolfile'' will be used by default.<br />
This variable is also important for the [[#Mutt-Sidebar|sidebar]].<br />
<br />
=====Summary=====<br />
Using these options, you will be able to start Mutt, enter your IMAP password, and start reading your mail. Here is a muttrc snippet (for Gmail) with some other lines you might consider adding for better IMAP support.<br />
{{bc|1=<br />
set folder = imaps://imap.gmail.com/<br />
set imap_user = your.username@gmail.com<br />
set imap_pass = your-imap-password<br />
set spoolfile = +INBOX<br />
mailboxes = +INBOX<br />
<br />
# Store message headers locally to speed things up.<br />
# If hcache is a folder, Mutt will create sub cache folders for each account which may speeds things even more up.<br />
set header_cache = ~/.cache/mutt<br />
<br />
# Store messages locally to speed things up, like searching message bodies.<br />
# Can be the same folder as header_cache.<br />
# This will cost important disk usage according to your e-mail amount.<br />
set message_cachedir = "~/.cache/mutt"<br />
<br />
# Specify where to save and/or look for postponed messages.<br />
set postponed = +[Gmail]/Drafts<br />
<br />
# Allow Mutt to open new imap connection automatically.<br />
unset imap_passive<br />
<br />
# Keep IMAP connection alive by polling intermittently (time in seconds).<br />
set imap_keepalive = 300<br />
<br />
# How often to check for new mail (time in seconds).<br />
set mail_check = 120<br />
}}<br />
<br />
====External IMAP support====<br />
While IMAP-functionality is built into Mutt, it does not download mail for offline-use. The [[OfflineIMAP]] article describes how to download your emails to a local folder which can then be processed by Mutt.<br />
<br />
Consider using applications such as {{pkg|spamassassin}} or {{AUR|imapfilter}} to sort mail.<br />
<br />
===POP3===<br />
''Retrieving and sorting mail with external applications''<br />
<br />
====Retrieving mail====<br />
Create the directory {{ic|~/.getmail/}}. Open the file {{ic|~/.getmail/getmailrc}} in your favorite text editor.<br />
<br />
Here is an example {{ic|getmailrc}} used with a gmail account.<br />
{{bc|1=<br />
[retriever]<br />
type = SimplePOP3SSLRetriever<br />
server = pop.gmail.com<br />
username = username@gmail.com<br />
port = 995<br />
password = password<br />
<br />
[destination]<br />
type = Maildir<br />
path = ~/mail/<br />
}}<br />
<br />
You can tweak this to your POP3 service's specification.<br />
<br />
Most people will like to add the following section to their {{ic|getmailrc}} to prevent all the mail on the server being downloaded every time getmail is ran.<br />
{{bc|1=<br />
[options]<br />
read_all = False<br />
}}<br />
<br />
As you can see {{ic|~/.getmail/getmailrc}} contains sensitive information (namely, email account passwords in plain text). You will want to change access permissions to the directory so only the owner can see it:<br />
<br />
$ chmod 700 ~/.getmail<br />
<br />
For this guide we will be storing our mail in the {{ic|maildir}} format. The two main mailbox formats are {{ic|mbox}} and {{ic|maildir}}. The main difference between the two is that {{ic|mbox}} is one file, with all of your mails and their headers stored in it, whereas a {{ic|maildir}} is a directory tree. Each mail is its own file, which will often speed things up.<br />
<br />
A {{ic|maildir}} is just a folder with the folders {{ic|cur}}, {{ic|new}} and {{ic|tmp}} in it.<br />
mkdir -p ~/mail/{cur,new,tmp}<br />
<br />
Now, run getmail. If it works fine, you can create a cronjob for getmail to run every n hours/minutes. Type {{ic|crontab -e}} to edit cronjobs, and enter the following:<br />
*/10 * * * * /usr/bin/getmail<br />
That will run {{ic|getmail}} every 10 minutes.<br />
<br />
Also, to quiet getmail down, we can reduce its verbosity to zero by adding the following to {{ic|getmailrc}}.<br />
{{bc|1=<br />
[options]<br />
verbose = 0<br />
}}<br />
<br />
=====More than one Email account with getmail=====<br />
By default, when you run {{ic|getmail}} the program searches for the file getmailrc created as seen above. If you have more than one mail account you would like to get mail from, then you can create such a file for each email address, and then tell getmail to run using both of them. Obviously if you have two accounts and two files you cannot have both of them called getmailrc. What you do is give them two different names, using myself as an example: I call one personal, and one university. These two files contain content relevant to my personal mail, and my university work mail respectively. Then to get getmail to work on these two files, instead of searching for getmailrc(default), I use the --rcfile switch like so: {{ic|getmail --rcfile university --rcfile personal}} This can work with more files if you have more email accounts, just make sure each file is in the .getmail directory and make sure to alter the cronjob to run the command with the --rcfile switches. E.g.<br />
'''*/30 * * * * /usr/bin/getmail --rcfile university --rcfile personal'''<br />
<br />
Obviously you can call your files whatever you want, providing you include them in the cronjob or shell command, and they are in the .getmail/ directory, getmail will fetch mail from those two accounts.<br />
<br />
====Sorting mail====<br />
[http://www.procmail.org/ Procmail] is an extremely powerful sorting tool. For the purposes of this wiki, we will do some primitive sorting to get started.<br />
<br />
You must edit your getmailrc to pass retrieved mail to procmail:<br />
{{bc|1=<br />
[destination]<br />
type = MDA_external<br />
path = /usr/bin/procmail<br />
}}<br />
<br />
Now, open up {{ic|.procmailrc}} in your favorite editor. The following will sort all mail from the happy-kangaroos mailing list, and all mail from your lovey-dovey friend in their own maildirs.<br />
{{bc|1=<br />
MAILDIR=$HOME/mail<br />
DEFAULT=$MAILDIR/inbox/<br />
LOGFILE=$MAILDIR/log<br />
<br />
:0:<br />
* ^To: happy-kangaroos@nicehost.com<br />
happy-kangaroos/<br />
<br />
:0:<br />
* ^From: loveydovey@iheartyou.net<br />
lovey-dovey/<br />
}}<br />
After you have saved your {{ic|.procmailrc}}, run getmail and see if procmail succeeds in sorting your mail into the appropriate directories.<br />
<br />
{{Note|One easy to make mistake with .procmailrc is the permission. procmail require it to have permission 644 and will not give meaningless error message if you do not.}}<br />
<br />
===Maildir===<br />
Maildir is a generic and standardized format. Almost every MUA is able to handle Maildirs and Mutt's support is excellent. There are just a few simple things that you need to do to get Mutt to use them. Open your muttrc and add the following lines:<br />
{{bc|1=<br />
set mbox_type=Maildir<br />
set folder=$HOME/mail<br />
set spoolfile=+/<br />
set header_cache=~/.cache/mutt<br />
}}<br />
<br />
This is a minimal Configuration that enables you to access your Maildir and checks for new local Mails in INBOX. This configuration also caches the headers of the eMails to speed up directory-listings. It might not be enabled in your build (but it sure is in the Arch-Package). Note that this does not affect OfflineIMAP in any way. It always syncs the all directories on a Server. {{ic|spoolfile}} tells Mutt which local directories to poll for new Mail. You might want to add more Spoolfiles (for example the Directories of Mailing-Lists) and maybe other things. But this is subject to the Mutt manual and beyond the scope of this document.<br />
<br />
===SMTP===<br />
Whether you use POP or IMAP to receive mail you will probably still send mail using SMTP.<br />
<br />
==== Folders ====<br />
<br />
There is basically only one important folder here: the one where all your sent e-mails will be saved.<br />
record = +Sent<br />
<br />
Gmail saves automatically sent e-mail to {{ic|+[Gmail]/Sent}}, so we do not want<br />
duplicates.<br />
unset record<br />
<br />
====Using native SMTP support====<br />
The pacman version of Mutt is also compiled with SMTP support. Just check the online manual [http://manual.cream.org/index.cgi/muttrc.5 muttrc], or {{ic|man muttrc}} for more information.<br />
<br />
For example:<br />
{{bc|1=<br />
set my_pass='mysecretpass'<br />
set my_user=myname<br />
<br />
set realname = 'Your Real Name'<br />
set from = your-email-address<br />
set use_from = yes<br />
<br />
set smtp_url=smtps://$my_user:$my_pass@smtp.domain.tld<br />
set ssl_force_tls = yes<br />
}}<br />
<br />
Note that if your SMTP credentials are the same as your IMAP credentials, then you can use those variables:<br />
<br />
{{bc|1=<br />
set smtp_url=smtps://$imap_user:$imap_pass@smtp.domain.tld<br />
}}<br />
<br />
You may need to tweak the security parameters. If you get an error like<br />
{{ic|SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol}},<br />
then your server most probably uses the SMTP instead of SMTPS.<br />
<br />
{{bc|1=<br />
set smtp_url=smtp://$imap_user:$imap_pass@smtp.domain.tld<br />
}}<br />
<br />
There is other variable that you may need to set. For example for use of STARTTLS:<br />
{{bc|1=<br />
set ssl_starttls = yes<br />
}}<br />
<br />
====External SMTP support====<br />
An external SMTP agent such as [[msmtp]], [[SSMTP]] or {{Pkg|opensmtpd}} can also be used. This section exclusively covers configuring Mutt for msmtp.<br />
<br />
Edit Mutt's configuration file or create it if unpresent:<br />
{{hc|muttrc|2=<br />
set realname='Disgruntled Kangaroo'<br />
<br />
set sendmail="/usr/bin/msmtp"<br />
<br />
set edit_headers=yes<br />
set folder=~/mail<br />
set mbox=+mbox<br />
set spoolfile=+inbox<br />
set record=+sent<br />
set postponed=+drafts<br />
set mbox_type=Maildir<br />
<br />
mailboxes +inbox +lovey-dovey +happy-kangaroos<br />
}}<br />
<br />
====Sending mails from Mutt====<br />
Now, startup {{Ic|mutt}}:<br />
<br />
You should see all the mail in {{ic|~/mail/inbox}}. Press {{ic|m}} to compose mail; it will use the editor defined by your {{Ic|EDITOR}} environment variable. If this variable is not set, you can fix it before starting Mutt:<br />
$ export EDITOR=your-favorite-editor<br />
$ mutt<br />
<br />
You should store the EDITOR value into your shell resource configuration file (such as [[bashrc]]).<br />
You can also set the editor from Mutt's configuration file:<br />
{{hc|.muttrc|2=<br />
set editor=your-favorite-editor<br />
}}<br />
<br />
For testing purposes, address the letter to yourself. After you have written the letter, save and exit the editor. You will return to Mutt, which will now show information about your e-mail. Press {{ic|y}} to send it.<br />
<br />
===Multiple accounts===<br />
<br />
Now you should have a working configuration for one account at least. You might wonder how to use several accounts, since we put everything into a single file.<br />
<br />
Well all you need is to write account-specific parameters to their respective files and source them. All the IMAP/POP3/SMTP config for each account should go to its respective folder.<br />
{{Warning|When one account is setting a variable that is not specified for other accounts, you '''must unset''' it for them, otherwise configuration will overlap and you will most certainly experience unexpected behaviour.}}<br />
<br />
Mutt can handle this thanks to one of its most powerful feature: hooks.<br />
Basically a hook is a command that gets executed before a specific action.<br />
There are several hook availables. For multiple accounts, you must use account-hooks ''and'' folder-hooks.<br />
* Folder-hooks will run a command before switching folders. This is mostly useful to set the appropriate SMTP parameters when you are in a specific folder. For instance when you are in your work mailbox and you send a e-mail, it will automatically use your work account as sender.<br />
* Account-hooks will run a command everytime Mutt calls a function related to an account, like IMAP syncing. It does not require you to switch to any folder.<br />
<br />
Hooks take two parameters:<br />
account-hook [!]regex command<br />
folder-hook [!]regex command<br />
The regex is the folder to be matched (or not if preceded by the !).<br />
The command tells what to do.<br />
<br />
Let us give a full example:<br />
<br />
{{hc|.muttrc|<nowiki><br />
## General options<br />
set header_cache = "~/.cache/mutt"<br />
set imap_check_subscribed<br />
set imap_keepalive = 300<br />
unset imap_passive<br />
set mail_check = 60<br />
set mbox_type=Maildir<br />
<br />
## ACCOUNT1<br />
source "~/.mutt/work"<br />
# Here we use the $folder variable that has just been set in the sourced file.<br />
# We must set it right now otherwise the 'folder' variable will change in the next sourced file.<br />
folder-hook $folder 'source ~/.mutt/work'<br />
<br />
## ACCOUNT2<br />
source "~/.mutt/personal"<br />
folder-hook *user@gmail.com/ 'source ~/.mutt/personal'<br />
folder-hook *user@gmail.com/Family 'set realname="Bob"'<br />
</nowiki>}}<br />
<br />
{{hc|.mutt/work|<nowiki><br />
## Receive options.<br />
set imap_user=user@gmail.com<br />
set imap_pass=****<br />
set folder = imaps://user@imap.gmail.com/<br />
set spoolfile = +INBOX<br />
set postponed = +Drafts<br />
set record = +Sent<br />
<br />
## Send options.<br />
set smtp_url=smtps://user:****@smtp.gmail.com<br />
set realname='User X'<br />
set from=user@gmail.com<br />
set hostname="gmail.com"<br />
set signature="John Doe"<br />
# Connection options<br />
set ssl_force_tls = yes<br />
unset ssl_starttls<br />
<br />
## Hook -- IMPORTANT!<br />
account-hook $folder "set imap_user=user@gmail.com imap_pass=****"<br />
</nowiki>}}<br />
<br />
Finally {{ic|.mutt/personal}} should be similar to {{ic|.mutt/work}}.<br />
<br />
Now all your accounts are set, start Mutt. To switch from one account to another, just change the folder ({{ic|c}} key). Alternatively you can use the [[#Mutt-Sidebar|sidebar]].<br />
<br />
To change folder for different mailboxes you have to type the complete address -- for IMAP/POP3 folders, this may be quite inconvenient -- let us bind some key to it.<br />
<br />
{{bc|<br />
## Shortcuts<br />
macro index,pager <f2> '<sync-mailbox><enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
macro index,pager <f3> '<sync-mailbox><enter-command>source ~/.mutt/work<enter><change-folder>!<enter>'<br />
}}<br />
<br />
With the above shortcuts (or with the sidebar) you will find that changing folders (with {{ic|c}} by default) is not contextual, ''i.e.'' it will not list the folders of the current mailbox, but of the one used the last time you changed folders. To make the behaviour more contextual, the trick is to press ''='' or ''+'' for current mailbox. You can automate this with the following macro:<br />
macro index 'c' '<change-folder>?<change-dir><home>^K=<enter>'<br />
<br />
===Passwords management===<br />
Keep in mind that writing your password in {{ic|.muttrc}} is a security risk, and it might be of your concern.<br />
The trivial way to keep your passwords safe is not writing them in the config file. Mutt will then prompt for it when needed.<br />
However, this is quiet combersome in the long run, especiallly if you have several accounts.<br />
<br />
Here follows a smart and convenient solution: all your passwords are encrypted into one file and Mutt will prompt for a passphrase on startup only. You can opt for a keyring tool (e.g. GPG, {{pkg|pwsafe}}) or an encryption tool like {{pkg|ccrypt}}, which may be more simple and straightforward to use.<br />
Since GPG is a Mutt dependency, we will use it here.<br />
<br />
First create a pair of public/private keys:<br />
gpg --gen-key<br />
If you do not understand this process have a look at [[Wikipedia:Asymmetric cryptography]].<br />
<br />
Create a file '''in a secure environment''' since it will contain your passwords for a couple of seconds:<br />
{{hc|~/.my-pwds|<nowiki><br />
set my_pw_personal = ****<br />
set my_pw_work = ****</nowiki><br />
}}<br />
{{Note|Remember that user defined variables '''must''' start with {{ic|my_}}}}<br />
<br />
Now encrypt the file:<br />
gpg -e -r 'your-name' ~/.my-pwds<br />
Note that 'your-name' must match the one you provided at the {{ic|gpg --gen-key}} step.<br />
Now you can wipe your file containing your passwords in clear:<br />
shred -xu ~/.my-pwds<br />
Back to your account dedicated files, e.g. {{ic|.mutt/muttrc}}:<br />
{{bc|1=<br />
set imap_pass=$my_pw_personal<br />
# Every time the password is needed, use $my_pw_personal variable.<br />
}}<br />
<br />
And in your {{ic|.muttrc}}, '''before''' you source any account dedicated file:<br />
{{bc|<br />
source "gpg2 -dq $HOME/.my-pwds.gpg {{ic|<nowiki>|</nowiki>}}"<br />
}}<br />
{{Note|At the end of the line above, there is no space between the pipe and the double quote.}}<br />
* The {{ic|-q}} parameter makes gpg2 quiet which prevents gpg2 output messing with Mutt interface.<br />
* The pipe {{ic|<nowiki>|</nowiki>}} at the end of a string is the Mutt syntax to tell that you want the result of what is preceeding.<br />
<br />
Explanation: when Mutt starts, it will first source the result of the password decryption, that's why it will prompt for a passphrase. Then all passwords will be stored in memory in specific variables for the time Mutt runs. Then, when a folder-hook is called, it sets the imap_pass variable to the variable holding the appropriate password. When switching accounts, the imap_pass variable will be set to another variable holding another password, etc.<br />
<br />
If you use external tools like OfflineIMAP and msmtp, you need to set up an agent (e.g. gpg-agent, see [[GnuPG#gpg-agent]]) to keep the passphrase into cache and thus avoiding those tools always prompting for it.<br />
<br />
{{Note|The previous instruction produces a mutt configuration error in the 'source' line. A quick workaround is to encrypt a file only consisting of your password, then storing the decrypted version in a variable in your muttrc.}}<br />
{{bc|<br />
echo "password" > ~/.my-pwd<br />
gpg -e -r 'your-name' ~/.my-pwd<br />
shred -xu ~/.my-pwd<br />
}}<br />
<br />
Once you have setup ~/.my-pwd.gpg, continue to editing {{ic|.muttrc}}<br />
{{bc|1=<br />
set my_pw = `gpg -dq ~/.my-pwd.gpg`<br />
set imap_pass = $my_pw<br />
}}<br />
<br />
==Advanced features==<br />
Guides to get you started with using & customizing Mutt : <br />
* [http://mutt.blackfish.org.uk/ My first Mutt] (maintained by Bruno Postle) <br />
* [http://www.therandymon.com/woodnotes/mutt/using-mutt.html The Woodnotes Guide to the Mutt Email Client] (maintained by Randall Wood)<br />
* [http://stevelosh.com/blog/2012/10/the-homely-mutt The Homely Mutt] (by Steve Losh)<br />
<br />
If you have any Mutt specific questions, feel free to ask in [[ArchChannel|the irc channel]].<br />
<br />
===E-mail character encoding===<br />
You may be concerned with sending e-mail in a decent character set (charset for short) like UTF-8. Nowadays UTF-8 is highly recommended to almost everyone.<br />
<br />
When using Mutt there is two levels where the charset must be specified:<br />
* The text editor used to write the e-mail must save it in the desired encoding.<br />
* Mutt will then check the e-mail and determine which encoding is the more apropriate according to the priority you specified in the {{ic|send_charset}} variable. Default: "us-ascii:iso-8859-1:utf-8".<br />
<br />
So if you write an e-mail with characters allowed in ISO-8859-1 (like 'résumé'), but without characters specific to Unicode, then Mutt will set the encoding to ISO-8859-1.<br />
<br />
To avoid this behaviour, set the variable in your {{ic|muttrc}}:<br />
set send_charset="us-ascii:utf-8"<br />
or even<br />
set send_charset="utf-8"<br />
<br />
The first compatible charset starting from the left will be used.<br />
Since UTF-8 is a superset of US-ASCII it does not harm to leave it in front of UTF-8, it may ensure old MUA will not get confused when seeing the charset in the e-mail header.<br />
<br />
===Printing===<br />
You can install {{AUR|muttprint}} from the [[AUR]] for a fancier printing quality.<br />
In your muttrc file, insert:<br />
set print_command="/usr/bin/muttprint %s -p {PrinterName}"<br />
<br />
===Custom mail headers===<br />
One of the greatest thing in Mutt is that you can have full control over your mail header.<br />
<br />
First, make your headers editable when you write e-mails:<br />
set edit_headers=yes<br />
<br />
Mutt also features a special function {{ic|my_hdr}} for customizing your header. Yes, it is named just like a variable, but in fact it is a function.<br />
<br />
You can clear it completely, which you ''should'' do when switching accounts with different headers, otherwise they will overlap:<br />
unmy_hdr *<br />
<br />
Other variables have also an impact on the headers, so it is wise to clear them before using {{ic|my_hdr}}:<br />
unset use_from<br />
unset use_domain<br />
unset user_agent<br />
<br />
Now, you can add any field you want -- even non-standard one -- to your header using the following syntax:<br />
my_hdr <FIELD>: <VALUE><br />
Note that <VALUE> can be the result of a command.<br />
<br />
Example:<br />
{{bc|<br />
## Extra info.<br />
my_hdr X-Info: Keep It Simple, Stupid.<br />
<br />
## OS Info.<br />
my_hdr X-Operating-System: `uname -s`, kernel `uname -r`<br />
<br />
## This header only appears to MS Outlook users<br />
my_hdr X-Message-Flag: WARNING!! Outlook sucks<br />
<br />
## Custom Mail-User-Agent ID.<br />
my_hdr User-Agent: Every email client sucks, this one just sucks less.<br />
}}<br />
<br />
===Signature block===<br />
Create a .signature in your home directory. Your signature will be appended at the end of your email.<br />
Alternatively you can specify a file in your Mutt configuration:<br />
set signature="path/to/sig/file"<br />
====Random signature====<br />
You can use fortune to add a random signature to Mutt.<br />
{{bc|$ pacman -S fortune-mod}}<br />
<br />
Create a fortune file and then add the following line to your .muttrc:<br />
{{bc|1=set signature="fortune pathtofortunefile&#124;"}}<br />
Note the pipe at the end. It tells Mutt that the specified string is not a file, but a command.<br />
<br />
===Viewing URLs & opening your favorite web browser===<br />
Your should start by creating a .mutt directory in $HOME if not done yet. There, create a file named macros. Insert the following:<br />
macro pager \cb <pipe-entry>'urlview'<enter> 'Follow links with urlview'<br />
<br />
Then install {{AUR|urlview}} from the [[AUR]].<br />
<br />
Create a .urlview in $HOME and insert the following:<br />
REGEXP (((http|https|ftp|gopher)|mailto)[.:][^ >"\t]*|www\.[-a-z0-9.]+)[^ .,;\t>">\):]<br />
COMMAND <your-browser> %s <br />
<br />
When you read an email on the pager, hitting ctrl+b will list all the urls from the email. Navigate up or down with arrow keys and hit enter on the desired url. Your browser will start and go to the selected site.<br />
<br />
Some browser will require additional arguments to work properly. For example, [[Luakit]] will close on Mutt exit. You need to fork it to background, using the {{ic|-n}} parameter:<br />
COMMAND luakit -n %s 2>/dev/null<br />
The {{ic|2>/dev/null}} is to make it quiet, i.e. to prevent useless message printing where you do not want them to.<br />
<br />
{{Note|urlview has a few deficiencies (e.g. the inability to handle certain email encodings) and is fairly feature-bare (e.g. it does not provide context for links it finds). There are a couple alternatives that do better. One, which can handle all email encodings and provides link context, is [http://www.memoryhole.net/~kyle/extract_url/ extract_url.pl]. Another, which can also provide link context but cannot handle all email encodings, is [https://aur.archlinux.org/packages.php?ID&#61;44853 urlscan]. Both are drop-in replacements for urlview, though extract_url has features which benefit from additional configuration changes.}}<br />
<br />
===Viewing HTML===<br />
It is possible to pass the html body to an external HTML program and then dump it, keeping email viewing uniform and unobtrusive. Three programs are described here: lynx, w3m and elinks.<br />
<br />
Install lynx, w3m or elinks:<br />
pacman -S lynx<br />
or<br />
pacman -S w3m<br />
or<br />
pacman -S elinks<br />
<br />
If {{ic|~/.mutt/mailcap}} does not exist you will need to create it and save the following to it.<br />
text/html; lynx -display_charset=utf-8 -dump %s; nametemplate=%s.html; copiousoutput<br />
or, in case of w3m,<br />
text/html; w3m -I %{charset} -T text/html; copiousoutput;<br />
or, in case of elinks,<br />
text/html; elinks -dump ; copiousoutput;<br />
<br />
Edit muttrc and add the following,<br />
set mailcap_path = ~/.mutt/mailcap<br />
<br />
To automatically open HTML messages in lynx, add this additional line to the muttrc:<br />
auto_view text/html<br />
<br />
The beauty of this is, instead of seeing an html body as source or being opened<br />
by a separate program, in this case lynx, you see the formatted content directly,<br />
and any url links within the email can be displayed with {{ic|Ctrl+b}}.<br />
<br />
If you receive many emails with multiple or alternate encodings Mutt may default to treating every email as html. To avoid this, add the following variable to your ~/.muttrc to have Mutt default to text when available and use w3m/lynx only when no text version is availble in the email:<br />
alternative_order text/plain text/html<br />
<br />
Some HTML mails may not display correctly in a text-based web browser. As a fallback solution, you can bind a key to open a graphical browser in such cases.<br />
The following macro will open the HTML mail selected from the attachment view in the web browser defined in the environment. (Feel free to adapt the {{ic|~/.cache/mutt/}} folder).<br />
macro attach 'V' "<pipe-entry>cat >~/.cache/mutt/mail.html && $BROWSER ~/.cache/mutt/mail.html && rm ~/.cache/mutt/mail.html<enter>"<br />
<br />
===Mutt and Vim===<br />
*To limit the width of text to 72 characters, edit your .[[vim]]rc file and add:<br />
au BufRead /tmp/mutt-* set tw=72<br />
<br />
*Another choice is to use Vim's mail filetype plugin to enable other mail-centric options besides 72 character width. Edit {{ic|~/.vim/filetype.vim}}, creating it if unpresent, and add:<br />
{{bc| <br />
augroup filetypedetect<br />
" Mail<br />
autocmd BufRead,BufNewFile *mutt-* setfiletype mail<br />
augroup END<br />
}}<br />
<br />
*To set a different tmp directory, e.g. ~/.tmp, add a line to your muttrc as follows:<br />
set tmpdir="~/.tmp"<br />
<br />
*To reformat a modified text see the Vim context help<br />
:h 10.7<br />
<br />
===Mutt and GNU nano===<br />
[[nano]] is another nice console editor to use with Mutt. <br />
<br />
To limit the width of text to 72 characters, edit your .nanorc file and add:<br />
set fill 72<br />
<br />
Also, in muttrc file, you can specify the line to start editing so that you will skip the mail header:<br />
set editor="nano +7"<br />
<br />
===Mutt and Emacs===<br />
Emacs has a ''mail'' and a ''message'' major mode.<br />
To switch to mail-mode automatically when Emacs is called from Mutt, you can add the following to your {{ic|.emacs}}:<br />
{{hc|.emacs|<nowiki><br />
;; Mutt support.<br />
(setq auto-mode-alist (append '(("/tmp/mutt.*" . mail-mode)) auto-mode-alist))<br />
</nowiki>}}<br />
<br />
If you usually run Emacs daemon, you may want Mutt to connect to it. Add this to your {{ic|.muttrc}}:<br />
{{hc|.muttrc|<nowiki><br />
set editor="emacsclient -a \"\" -t"</nowiki><br />
}}<br />
<br />
===Colors===<br />
Append sample color definitions to your .muttrc file:<br />
$ cat /usr/share/doc/mutt/samples/colors.linux >> ~/.muttrc<br />
Then adjust to your liking.<br />
The actual color each of these settings will produce depends on the colors set in your [[Xresources|~/.Xresources]] file.<br />
<br />
Alternatively, you can source any file you want containing colors (and thus act as a theme file):<br />
{{bc|<br />
source ~/.mutt/colors.zenburn<br />
}}<br />
<br />
A nice theme example:<br />
{{bc|<nowiki><br />
## Theme kindly inspired from <br />
## http://nongeekshandbook.blogspot.ie/2009/03/mutt-color-configuration.html <br />
<br />
## Colours for items in the index <br />
color index brightcyan black ~N<br />
color index brightred black ~O<br />
color index brightyellow black ~F<br />
color index black green ~T<br />
color index brightred black ~D<br />
mono index bold ~N<br />
mono index bold ~F<br />
mono index bold ~T<br />
mono index bold ~D<br />
<br />
## Highlights inside the body of a message. <br />
<br />
## URLs <br />
color body brightgreen black "(http|ftp|news|telnet|finger)://[^ \"\t\r\n]*"<br />
color body brightgreen black "mailto:[-a-z_0-9.]+@[-a-z_0-9.]+"<br />
mono body bold "(http|ftp|news|telnet|finger)://[^ \"\t\r\n]*"<br />
mono body bold "mailto:[-a-z_0-9.]+@[-a-z_0-9.]+"<br />
<br />
## Email addresses. <br />
color body brightgreen black "[-a-z_0-9.%$]+@[-a-z_0-9.]+\\.[-a-z][-a-z]+"<br />
<br />
## Header <br />
color header green black "^from:"<br />
color header green black "^to:"<br />
color header green black "^cc:"<br />
color header green black "^date:"<br />
color header yellow black "^newsgroups:"<br />
color header yellow black "^reply-to:"<br />
color header brightcyan black "^subject:"<br />
color header red black "^x-spam-rule:"<br />
color header green black "^x-mailer:"<br />
color header yellow black "^message-id:"<br />
color header yellow black "^Organization:"<br />
color header yellow black "^Organisation:"<br />
color header yellow black "^User-Agent:"<br />
color header yellow black "^message-id: .*pine"<br />
color header yellow black "^X-Fnord:"<br />
color header yellow black "^X-WebTV-Stationery:"<br />
<br />
color header red black "^x-spam-rule:"<br />
color header green black "^x-mailer:"<br />
color header yellow black "^message-id:"<br />
color header yellow black "^Organization:"<br />
color header yellow black "^Organisation:"<br />
color header yellow black "^User-Agent:"<br />
color header yellow black "^message-id: .*pine"<br />
color header yellow black "^X-Fnord:"<br />
color header yellow black "^X-WebTV-Stationery:"<br />
color header yellow black "^X-Message-Flag:"<br />
color header yellow black "^X-Spam-Status:"<br />
color header yellow black "^X-SpamProbe:"<br />
color header red black "^X-SpamProbe: SPAM"<br />
<br />
## Coloring quoted text - coloring the first 7 levels: <br />
color quoted cyan black<br />
color quoted1 yellow black<br />
color quoted2 red black<br />
color quoted3 green black<br />
color quoted4 cyan black<br />
color quoted5 yellow black<br />
color quoted6 red black<br />
color quoted7 green black<br />
<br />
## Default color definitions <br />
#color hdrdefault white green <br />
color signature brightmagenta black<br />
color indicator black cyan<br />
color attachment black green<br />
color error red black<br />
color message white black<br />
color search brightwhite magenta<br />
color status brightyellow blue<br />
color tree brightblue black<br />
color normal white black<br />
color tilde green black<br />
color bold brightyellow black<br />
#color underline magenta black <br />
color markers brightcyan black<br />
<br />
## Colour definitions when on a mono screen <br />
mono bold bold<br />
mono underline underline<br />
mono indicator reverse</nowiki><br />
}}<br />
<br />
===Index Format===<br />
<br />
Here follows a quick example to put in your {{ic|.muttrc}} to customize the Index Format, i.e. the columns displayed in the folder view.<br />
{{bc|<nowiki><br />
set date_format="%y-%m-%d %T"<br />
set index_format="%2C | %Z [%d] %-30.30F (%-4.4c) %s"</nowiki><br />
}}<br />
See the [http://www.mutt.org/doc/manual/manual-6.html Mutt Reference], {{ic|man 3 strftime}} and {{ic|man 3 printf}} for more details.<br />
<br />
====Display recipient instead of sender in "Sent" folder view====<br />
<br />
By default Mutt will display the sender in the index view. It is fine for most folders, but rather useless for the one were you store a copy of your sent e-mails since it will always display your name.<br />
<br />
The "columns" of the index can be configured through the {{ic|index_format}} variable. Its syntax is documented in the {{ic|muttrc}} man page. The values of our concern are {{ic|%t}} (recipient) and {{ic|%F}} (sender).<br />
<br />
To change the columns according to the current folder, we need to use a hook:<br />
{{hc|muttrc|<nowiki><br />
folder-hook *[sS]ent* 'set index_format="%2C | %Z [%d] %-30.30t (%-4.4c) %s"'<br />
folder-hook ! *[sS]ent* 'set index_format="%2C | %Z [%d] %-30.30F (%-4.4c) %s"'<br />
</nowiki>}}<br />
<br />
The exclamation mark means ''everything that does not match the following regex''. Of course you can change the index_format following you taste, and the regular expression if the folder does not have ''Sent'' not ''sent'' in its name.<br />
<br />
====Variable column width====<br />
<br />
If you rezise the window, the subject might get truncated while there is still unused space left for some fields, like for the sender.<br />
You can get the maximum column of your terminal (i.e. the width) using a shell call to {{ic|tput cols}}. With this value you can set a percentage of the width to fields like Sender and Subject.<br />
<br />
Example using the above folder-hook and a sidebar width of 24:<br />
{{hc|muttrc|<nowiki><br />
## From field gets 30% of remaining space, Subject gets 70%.<br />
## Remaining space is the total width minus the other fields (35), minus the sidebar (24)<br />
set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`<br />
set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`<br />
<br />
folder-hook .*[sS]ent.* 'set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}t (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
folder-hook ! .*[sS]ent.* 'set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}F (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
</nowiki><br />
}}<br />
<br />
Unfortunately, the above example suffers from one caveat: the {{ic|my_col_*}} variables get computed one time only, on first start. So if you want it to refresh automatically, we need to set the variable in a hook. Sadly there is no hook for window resizing, but you can still use the {{ic|folder-hook}} so that a simple folder switch suffice to recompute the view.<br />
{{hc|muttrc|<nowiki><br />
folder-hook .*[sS]ent.* 'set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`; set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`; set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}t (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
folder-hook ! .*[sS]ent.* 'set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`; set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`; set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}F (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
</nowiki><br />
}}<br />
<br />
===Contact management===<br />
<br />
====Address aliases====<br />
''Aliases'' is the way Mutt manages contacts.<br />
An alias is '''nickname [longname] <address>'''.<br />
* The '''nickname''' is what you will type in Mutt to get your contact address. One word only, and should be easy to remember.<br />
* The '''longname''' is optional. It may be several words.<br />
* An '''<address>''' must be in a valid form (i.e. with an {{ic|@}}).<br />
<br />
It is quite simple indeed. Add this to {{ic|.muttrc}}:<br />
{{bc|1=<br />
set alias_file = "~/.mutt/aliases"<br />
set sort_alias = alias<br />
set reverse_alias = yes<br />
source $alias_file<br />
}}<br />
<br />
Explanation:<br />
* {{ic|alias_file}} is the file where the information is getting stored when you add an alias from within Mutt.<br />
* {{ic|sort_alias}} specifies which field to use to sort the alias list when displayed in Mutt. Possible values: alias, address.<br />
* {{ic|reverse_alias}} sorts in reverse order if set to yes.<br />
* {{ic|source $alias_file}} tells Mutt to read aliases on startup. Needed for auto-completion.<br />
<br />
Now all you have to do when prompted {{ic|To:}} is writing the alias instead of the full address. The beauty of it is that you can auto-complete the alias using {{ic|Tab}}.<br />
Autocompleting a wrong or an empty string will display the full list. You can select the alias as usual, or by typing its index number.<br />
<br />
There is two ways to create aliases:<br />
* From Mutt, press {{ic|a}} when an e-mail of the targetted person if selected.<br />
* Edit the alias_file manually. The syntax is really simple:<br />
{{bc|<br />
alias nickname Long Name <my-friend@domain.tld><br />
}}<br />
<br />
====Abook====<br />
<br />
{{pkg|abook}} is a stand-alone program dedicated to contact management. It uses a very simple text-based interface and contacts are stored in a plain text, human-readable database. Besides the desired contact properties are extensible (birthday, address, fax, and so on).<br />
<br />
Abook is specifically designed to be interfaced with Mutt, so that it can serve as a full, more featured replacement of Mutt internal aliases. If you want to use Abook instead of aliases, remove the aliases configuration in {{ic|.muttrc}} and add this:<br />
<br />
{{hc|muttrc|<nowiki><br />
## Abook<br />
set query_command= "abook --mutt-query '%s'"<br />
macro index,pager a "<pipe-message>abook --add-email-quiet<return>" "Add this sender to Abook"<br />
bind editor <Tab> complete-query<br />
</nowiki><br />
}}<br />
<br />
See the man pages {{ic|abook}} and {{ic|abookrc}} for more details and a full configuration sample.<br />
<br />
===Request IMAP mail retrieval manually===<br />
If you do not want to wait for the next automatic IMAP fetching (or if you did not enable it), you might want to fetch mails manually.<br />
There is a mutt command {{ic|imap-fetch-mail}} for that.<br />
Alternatively, you could bind it to a key:<br />
bind index "^" imap-fetch-mail<br />
<br />
===Avoiding slow index on large (IMAP) folders due to coloring===<br />
<br />
Index highlighting by regex is nice, but can lead to slow folder viewing if your regex checks the body of the message.<br />
<br />
Use folder-hook for only highlighting in for example the inbox (if you manage to empty your mailbox effiently):<br />
<br />
folder-hook . 'uncolor index "~b \"Hi Joe\" ~R !~T !~F !~p !~P"'<br />
folder-hook ""!"" 'color index brightyellow black "~b \"Hi Joe\" ~N !~T !~F !~p !~P"'<br />
<br />
===Speed up folders switch===<br />
Add this to your {{ic|.muttrc}}:<br />
{{bc|1=<br />
set sleep_time = 0<br />
}}<br />
<br />
===Use Mutt to send mail from command line===<br />
Man pages will show all available commands and how to use them, but here are a couple of examples. You could use Mutt to send alerts, logs or some other system information, triggered by login through .bash_profile, or as a regular cron job.<br />
<br />
Send a message:<br />
mutt -s "Subject" somejoeorjane@someserver.com < /var/log/somelog<br />
<br />
Send a message with attachment:<br />
mutt -s "Subject" somejoeorjane@someserver.com -a somefile < /tmp/sometext.txt<br />
<br />
===Composing HTML e-mails===<br />
<br />
Since Mutt has nothing of a WYSIWIG client, HTML is quite straightforward, and you can do much more than with all WYSIWIG mail clients around since you edit the source code directly.<br />
Simply write your mail using HTML syntax. For example:<br />
{{bc|<nowiki><br />
This is normal text<br><br />
<b>This is bold text</b></nowiki><br />
}}<br />
Now before sending the mail, use the {{ic|edit-type}} command (default shortcut {{ic|Ctrl+t}}), and replace {{ic|text/plain}} by {{ic|text/html}}.<br />
<br />
{{Note|HTML e-mails are regarded by many people as useless, cumbersome, and subject to reading issues. Mutt can read HTML mails with a text browser like w3m or lynx, but it has clearly no advantage over a plain-text e-mail. You should avoid writing HTML e-mails when possible.}}<br />
<br />
===How to display another email while composing===<br />
A common complaint with Mutt is that when composing a new mail (or reply), you cannot open another mail (i.e. for checking with another correspondent) without closing the current mail (postponing). The following describes a solution:<br />
<br />
First, fire up Mutt as usual. Then, launch another terminal window. Now start a new Mutt with <br />
mutt -R<br />
This starts Mutt in read-only mode, and you can browse other emails at your convenience. It is strongly recommended to always launch a second Mutt in read-only mode, as conflicts will easily arise otherwise.<br />
<br />
Now, this solution calls for a bit of typing, so we would like to automate this. The following works with [[Awesome]], in other WM's or DE's similar solutions are probably available: just google how to add a key binding, and make the desired key execute <br />
$TERM -e mutt -R <br />
where $TERM is your terminal.<br />
<br />
As for Awesome: edit your rc.lua, and add the following on one of the first lines, after terminal = "yourTerminal" etc.<br />
mailview = terminal .. " -e mutt -R"<br />
This automatically uses your preferred terminal, ".." is concatenation in Lua. Note the space before -e.<br />
<br />
Then add the following inside --{{{ Key bindings<br />
awful.key({ modkey, }, "m", function() awful.util.spawn(mailview) end),<br />
<br />
Omit the final comma if this is the last line. You can, of course use another key than "m". Now, save&quit, and check your syntax with <br />
awesome -k<br />
If this is good, restart awesome and give it a try!<br />
<br />
Now, a usage example: Launch Mutt as usual. Start a new mail, and then press "Mod4"+"m". This opens your mailbox in a new terminal, and you can browse around and read other emails. Now, a neat bonus: exit this read-only-Mutt with "q", and the terminal window it created disappears!<br />
<br />
===Archive treated e-mails===<br />
When you read an e-mail, you have four choices: Answer it, Flag it, Archive it or Delete it. If you have this in mind, you can keep your inbox slim and fit with this macro (set up for Gmail):<br />
<br />
macro index \' "<tag-pattern>~R !~D !~F<enter>\<br />
<tag-prefix><save-message>+[Gmail]/All <enter>" \<br />
"Archive"<br />
<br />
===Mutt-Sidebar===<br />
<br />
The vanilla Mutt does not feature a sidebar unlike most MUAs. If you miss it, you can install {{Aur|mutt-sidebar}} from the AUR which features a patch for a list of folders on the left side of the Mutt window.<br />
<br />
For a while there has been several different patches for the sidebar. Since the late 2000's, it seems like the main patch is maintained at [http://www.lunar-linux.org/mutt-sidebar/ Lunar Linux]. See the documentation there. Note that the patch also updates the {{ic|muttrc}} man page, so have a look at the {{ic|sidebar_*}} sections.<br />
<br />
You can choose to display the sidebar on startup, or to prompt it manually with a key:<br />
{{bc|<nowiki><br />
set sidebar_visible = yes<br />
macro index b '<enter-command>toggle sidebar_visible<enter><refresh>'<br />
macro pager b '<enter-command>toggle sidebar_visible<enter><redraw-screen>'<br />
</nowiki>}}<br />
<br />
You also probabaly need some shortcuts to navigate in the bar:<br />
{{bc|<nowiki><br />
# Ctrl-n, Ctrl-p to select next, previous folder.<br />
# Ctrl-o to open selected folder.<br />
bind index,pager \CP sidebar-prev<br />
bind index,pager \CN sidebar-next<br />
bind index,pager \CO sidebar-open<br />
</nowiki>}}<br />
<br />
{{Note|You ''must'' set the {{ic|mailboxes}} variables or the {{ic|imap_check_subscribed}} to tell the sidebar which folder should be displayed. See the [[#mailboxes|mailboxes]] section.}}<br />
<br />
If you use the {{ic|imap_check_subscribed}} option to list all your folders, they will appear in an uncontrollable order in the sidebar. Fix it with<br />
set sidebar_sort = yes<br />
Note that with the {{ic|mailboxes}} option, folders appear in the order they were set to {{ic|mailboxes}} if you do not use the {{ic|sidebar_sort}} option.<br />
<br />
If you have trouble with truncated names, set the option<br />
set sidebar_shortpath = yes<br />
<br />
Finally, you may want to add a separator between different mailboxes. The sidebar patch does not currently provide any kind of separator option. A simple (and dirty) workaround is to add a fake folder to the list of folders:<br />
mailboxes "+-- My mailbox -----------"<br />
The dashes are not required, they are here just for fancy output.<br />
It will also work if you used the {{ic|imap_check_subscribed}} option.<br />
If you chose to sort the folders, the separator will not appear in the correct place, so an even more dirty workaround is to add an 'A' in front of the name. Note that punctuation is ignored during sorting.<br />
mailboxes "+A-- My mailbox -----------"<br />
<br />
===Migrating mails from one computer to another===<br />
In case you are transfering your mails to a new machine (copy&paste), you probably need to delete the header cache (a file or folder like {{ic|~/.cache/mutt}} if you followed the above configuration) to make Mutt able to read your migrated E-Mails. Otherwise Mutt may freeze.<br />
<br />
Note that if you had a folder created for you header cache, all mailboxes will have their own cache file, so you can delete caches individually without having to remove everything.<br />
<br />
=== Filtering the message view ===<br />
<br />
You can restrict the view to e-mails matching a pattern and specific properties with the {{ic|limit}} command (default shortcut: {{ic|l}}).<br />
<br />
To view all e-mails containing "foo" in the header, simply write "foo" and you are done. To remove the filter, use the "all" keyword.<br />
<br />
To view all flagged messages, use<br />
~F<br />
To view all unread messages, use<br />
~U<br />
<br />
All possible patterns are listed in the [http://www.mutt.org/doc/manual/manual-4.html#ss4.2 official manual].<br />
<br />
=== Display the index above the pager view ===<br />
<br />
Set the following variable in your {{ic|muttrc}}:<br />
set pager_index_lines=10<br />
<br />
==Troubleshooting==<br />
<br />
===Backspace does not work in Mutt===<br />
This is a common problem with some xterm-like terminals.<br />
Two solutions:<br />
* Either rebind the key in {{ic|.muttrc}}<br />
bind index,pager ^? previous-page<br />
Note that {{ic|^?}} is one single character representing backspace in [[wikipedia:Caret_notation|caret notation]]. To type in Emacs, use {{ic|Ctrl+q Backspace}}, in Vim {{ic|Ctrl+v Backspace}}.<br />
<br />
* Or fix your terminal:<br />
$ infocmp > termbs.src<br />
Edit {{ic|termbs.src}} and change {{ic|1= kbs=^H}} to {{ic|1= kbs=\177}}, then:<br />
$ tic -x termbs.src<br />
<br />
===Android's default MUA receives empty e-mail with attachment "Unknown.txt"===<br />
<br />
This is because Mutt adds 'Content-Disposition' line to every e-mail header. This line is actually correct, the issue comes from Android 2 MUA misinterpreting it. This bug seems to be fixed in the Android 4 MUA.<br />
There is a patched version for Android available in the AUR. Installing {{AUR|mutt-android-patch}} will fix the issue.<br />
<br />
===The ''change-folder'' function always prompt for the same mailbox ===<br />
<br />
This is not a bug, this is actually an intended behaviour. See the [[#Multiple accounts|multiple accounts section]] for a workaround.<br />
<br />
===I cannot change folder when using Mutt read-only (Mutt -R)===<br />
<br />
This is certainly because you are use are using macros like this one:<br />
macro index,pager <f2> '<sync-mailbox><enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
This macro tells Mutt to sync (which is a write operation) before switching.<br />
Either use the [[#Mutt-Sidebar|sidebar]] or set another macro:<br />
macro index,pager <f3> '<enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
<br />
== Documentation ==<br />
<br />
Newcomers may find it quite hard to find help for Mutt. Actually most of the topics are covered in the official documentation. We urge you to read it.<br />
<br />
* [http://www.mutt.org/doc/manual/ The official manual]. The stock {{pkg|mutt}} package for Arch Linux also installs the HTML and plain text manual at {{ic|/usr/share/doc/mutt/}}.<br />
* The {{ic|mutt}} and {{ic|muttrc}} man pages.<br />
<br />
== See also ==<br />
* [http://www.mutt.org/ The official Mutt website]<br />
* [http://wiki.mutt.org/ The Mutt wiki]<br />
* [http://pbrisbin.com/posts/two_accounts_in_mutt/ Brisbin's great guide on how to setup different IMAP accounts with Mutt, offlineimap, msmtp]<br />
* [http://home.roadrunner.com/~computertaijutsu/mutt.html A Quick Guide to Mutt]<br />
* [http://pyropus.ca/software/getmail/configuration.html#running Documentation on Configuring Getmail with rcfiles]<br />
* [http://stevelosh.com/blog/2012/10/the-homely-mutt/ Steve Losh on Mutt, offlineimap, msmtp, notmuch (gmail focussed)]<br />
* [http://www.muttrcbuilder.org/ muttrc builder]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mutt&diff=292675Mutt2014-01-13T08:34:42Z<p>Kevr: /* Passwords management */</p>
<hr />
<div>[[Category:Email Client]]<br />
[[es:Mutt]]<br />
[[it:Mutt]]<br />
[[zh-CN:Mutt]]<br />
[[zh-TW:Mutt]]<br />
{{Related articles start}}<br />
{{Related|fdm}}<br />
{{Related|msmtp}}<br />
{{Related|offlineimap}}<br />
{{Related articles end}}<br />
'''Mutt''' is a text-based mail client renowned for its powerful features. Though over a decade old, Mutt remains the mail client of choice for a great number of power-users. Unfortunately, a default Mutt install is plagued by complex keybindings along with a daunting amount of documentation. This guide will help the average user get Mutt up and running, and begin customizing it to their particular needs.<br />
<br />
==Overview==<br />
Mutt focuses primarily on being a Mail User Agent (MUA), and was originally written to view mail. Later implementations (added for retrieval, sending, and filtering mail) are simplistic compared to other mail applications and, as such, users may wish to use external applications to extend Mutt's capabilities. <br />
<br />
Nevertheless, the Arch Linux {{Pkg|mutt}} package is compiled with IMAP, POP3 and SMTP support, removing the necessity for external applications.<br />
<br />
This article covers using both native IMAP sending and retrieval, and a setup depending on [[OfflineIMAP]] or [[getmail]] (POP3) to retrieve mail, [[procmail]] to filter it in the case of POP3, and [[msmtp]] to send it.<br />
<br />
==Installing==<br />
[[pacman|Install]] {{Pkg|mutt}}, available in the [[Official Repositories]]. <br />
<br />
Optionally install external helper applications for an IMAP setup, such as {{Pkg|offlineimap}} and {{Pkg|msmtp}}.<br />
<br />
Or (if using POP3) {{Pkg|getmail}} or {{Pkg|fdm}} and {{Pkg|procmail}}.<br />
<br />
{{Note|<br />
*If you just need the authentication methods LOGIN and PLAIN, these are satisfied with the dependency {{Pkg|libsasl}}<br />
*If you want to (or have to) use CRAM-MD5, GSSAPI or DIGEST-MD5, install the package {{Pkg|cyrus-sasl-gssapi}}<br />
*If you are using Gmail as your SMTP server, you may need to install the package {{Pkg|cyrus-sasl}}<br />
}}<br />
<br />
==Configuring==<br />
This section covers IMAP, [[#POP3]], [[#Maildir]] and [[#SMTP]] configuration.<br />
<br />
Note that Mutt will recognize two locations for its configuration file; {{ic|~/.muttrc}} and {{ic|~/.mutt/muttrc}}. Either location will work.<br />
You should also know some prerequisite for Mutt configuration. Its syntax is very close to the Bourne Shell. For example, you can get the content of another config file:<br />
source /path/to/other/config/file<br />
You can use variables and assign the result of shell commands to them.<br />
set editor=`echo \$EDITOR`<br />
Here the {{ic|$}} gets escaped so that it does not get substituted by Mutt before being passed to the shell.<br />
Also note the use of the backquotes, as bash syntax {{ic|$(...)}} does not work.<br />
Mutt has a lot of predefined variables, but you can also set your own. User variable '''must begin with "my"!'''<br />
set my_name = "John Doe"<br />
<br />
===IMAP===<br />
''Native and external setups''<br />
<br />
====Using native IMAP support====<br />
The pacman version of Mutt is compiled with IMAP support. At the very least you need to have 4 lines in your muttrc file to be able to access your mail.<br />
<br />
=====imap_user=====<br />
set imap_user=USERNAME<br />
<br />
Continuing with the previous example, remember that Gmail requires your full email address (this is not standard):<br />
set imap_user=your.username@gmail.com<br />
<br />
=====imap_pass=====<br />
If unset, the password will be prompted for.<br />
set imap_pass=SECRET<br />
<br />
=====folder=====<br />
Instead of a local directory which contains all your mail (and directories), use your server (and the highest folder in the hierarchy, if needed).<br />
set folder=imap[s]://imap.server.domain[:port]/[folder/]<br />
<br />
You do not have to use a folder, but it might be convenient if you have all your other folders inside your INBOX, for example. Whatever you set here as your folder can be accessed later in Mutt with just an equal sign (=) or a plus sign (+). Example:<br />
set folder=imaps://imap.gmail.com/<br />
<br />
It should be noted that for several accounts, it is best practice to use different folders -- e.g. for ''account-hook''. If you have several Gmail account, use<br />
set folder=imaps://username@imap.gmail.com/<br />
instead, where your account is ''username@gmail.com''. This way it will be possible to distinguish the different folders. Otherwise it would lead to authentication errors.<br />
<br />
=====spoolfile=====<br />
The spoolfile is the folder where your (unfiltered) e-mail arrives. Most e-mail services conventionally names it ''INBOX''. You can now use '=' or '+' as a substitution for the full {{ic|folder}} path that was configured above. For example:<br />
set spoolfile=+INBOX<br />
<br />
=====mailboxes=====<br />
Any imap folders that should be checked regularly for new mail should be listed here:<br />
mailboxes =INBOX =family<br />
mailboxes imaps://imap.gmail.com/INBOX imaps://imap.gmail.com/family<br />
<br />
Alternatively, check for all subscribed IMAP folders (as if all were added with a {{Ic|mailboxes}} line):<br />
set imap_check_subscribed<br />
<br />
These two versions are equivalent if you want to subscribe to all folders. So the second method is much more convenient, but the first one gives you more flexibility. Also, newer Mutt versions are configured by default to include a macro bound to the 'y' key which will allow you to change to any of the folders listed under mailboxes.<br />
<br />
If you do not set this variable, the ''spoolfile'' will be used by default.<br />
This variable is also important for the [[#Mutt-Sidebar|sidebar]].<br />
<br />
=====Summary=====<br />
Using these options, you will be able to start Mutt, enter your IMAP password, and start reading your mail. Here is a muttrc snippet (for Gmail) with some other lines you might consider adding for better IMAP support.<br />
{{bc|1=<br />
set folder = imaps://imap.gmail.com/<br />
set imap_user = your.username@gmail.com<br />
set imap_pass = your-imap-password<br />
set spoolfile = +INBOX<br />
mailboxes = +INBOX<br />
<br />
# Store message headers locally to speed things up.<br />
# If hcache is a folder, Mutt will create sub cache folders for each account which may speeds things even more up.<br />
set header_cache = ~/.cache/mutt<br />
<br />
# Store messages locally to speed things up, like searching message bodies.<br />
# Can be the same folder as header_cache.<br />
# This will cost important disk usage according to your e-mail amount.<br />
set message_cachedir = "~/.cache/mutt"<br />
<br />
# Specify where to save and/or look for postponed messages.<br />
set postponed = +[Gmail]/Drafts<br />
<br />
# Allow Mutt to open new imap connection automatically.<br />
unset imap_passive<br />
<br />
# Keep IMAP connection alive by polling intermittently (time in seconds).<br />
set imap_keepalive = 300<br />
<br />
# How often to check for new mail (time in seconds).<br />
set mail_check = 120<br />
}}<br />
<br />
====External IMAP support====<br />
While IMAP-functionality is built into Mutt, it does not download mail for offline-use. The [[OfflineIMAP]] article describes how to download your emails to a local folder which can then be processed by Mutt.<br />
<br />
Consider using applications such as {{pkg|spamassassin}} or {{AUR|imapfilter}} to sort mail.<br />
<br />
===POP3===<br />
''Retrieving and sorting mail with external applications''<br />
<br />
====Retrieving mail====<br />
Create the directory {{ic|~/.getmail/}}. Open the file {{ic|~/.getmail/getmailrc}} in your favorite text editor.<br />
<br />
Here is an example {{ic|getmailrc}} used with a gmail account.<br />
{{bc|1=<br />
[retriever]<br />
type = SimplePOP3SSLRetriever<br />
server = pop.gmail.com<br />
username = username@gmail.com<br />
port = 995<br />
password = password<br />
<br />
[destination]<br />
type = Maildir<br />
path = ~/mail/<br />
}}<br />
<br />
You can tweak this to your POP3 service's specification.<br />
<br />
Most people will like to add the following section to their {{ic|getmailrc}} to prevent all the mail on the server being downloaded every time getmail is ran.<br />
{{bc|1=<br />
[options]<br />
read_all = False<br />
}}<br />
<br />
As you can see {{ic|~/.getmail/getmailrc}} contains sensitive information (namely, email account passwords in plain text). You will want to change access permissions to the directory so only the owner can see it:<br />
<br />
$ chmod 700 ~/.getmail<br />
<br />
For this guide we will be storing our mail in the {{ic|maildir}} format. The two main mailbox formats are {{ic|mbox}} and {{ic|maildir}}. The main difference between the two is that {{ic|mbox}} is one file, with all of your mails and their headers stored in it, whereas a {{ic|maildir}} is a directory tree. Each mail is its own file, which will often speed things up.<br />
<br />
A {{ic|maildir}} is just a folder with the folders {{ic|cur}}, {{ic|new}} and {{ic|tmp}} in it.<br />
mkdir -p ~/mail/{cur,new,tmp}<br />
<br />
Now, run getmail. If it works fine, you can create a cronjob for getmail to run every n hours/minutes. Type {{ic|crontab -e}} to edit cronjobs, and enter the following:<br />
*/10 * * * * /usr/bin/getmail<br />
That will run {{ic|getmail}} every 10 minutes.<br />
<br />
Also, to quiet getmail down, we can reduce its verbosity to zero by adding the following to {{ic|getmailrc}}.<br />
{{bc|1=<br />
[options]<br />
verbose = 0<br />
}}<br />
<br />
=====More than one Email account with getmail=====<br />
By default, when you run {{ic|getmail}} the program searches for the file getmailrc created as seen above. If you have more than one mail account you would like to get mail from, then you can create such a file for each email address, and then tell getmail to run using both of them. Obviously if you have two accounts and two files you cannot have both of them called getmailrc. What you do is give them two different names, using myself as an example: I call one personal, and one university. These two files contain content relevant to my personal mail, and my university work mail respectively. Then to get getmail to work on these two files, instead of searching for getmailrc(default), I use the --rcfile switch like so: {{ic|getmail --rcfile university --rcfile personal}} This can work with more files if you have more email accounts, just make sure each file is in the .getmail directory and make sure to alter the cronjob to run the command with the --rcfile switches. E.g.<br />
'''*/30 * * * * /usr/bin/getmail --rcfile university --rcfile personal'''<br />
<br />
Obviously you can call your files whatever you want, providing you include them in the cronjob or shell command, and they are in the .getmail/ directory, getmail will fetch mail from those two accounts.<br />
<br />
====Sorting mail====<br />
[http://www.procmail.org/ Procmail] is an extremely powerful sorting tool. For the purposes of this wiki, we will do some primitive sorting to get started.<br />
<br />
You must edit your getmailrc to pass retrieved mail to procmail:<br />
{{bc|1=<br />
[destination]<br />
type = MDA_external<br />
path = /usr/bin/procmail<br />
}}<br />
<br />
Now, open up {{ic|.procmailrc}} in your favorite editor. The following will sort all mail from the happy-kangaroos mailing list, and all mail from your lovey-dovey friend in their own maildirs.<br />
{{bc|1=<br />
MAILDIR=$HOME/mail<br />
DEFAULT=$MAILDIR/inbox/<br />
LOGFILE=$MAILDIR/log<br />
<br />
:0:<br />
* ^To: happy-kangaroos@nicehost.com<br />
happy-kangaroos/<br />
<br />
:0:<br />
* ^From: loveydovey@iheartyou.net<br />
lovey-dovey/<br />
}}<br />
After you have saved your {{ic|.procmailrc}}, run getmail and see if procmail succeeds in sorting your mail into the appropriate directories.<br />
<br />
{{Note|One easy to make mistake with .procmailrc is the permission. procmail require it to have permission 644 and will not give meaningless error message if you do not.}}<br />
<br />
===Maildir===<br />
Maildir is a generic and standardized format. Almost every MUA is able to handle Maildirs and Mutt's support is excellent. There are just a few simple things that you need to do to get Mutt to use them. Open your muttrc and add the following lines:<br />
{{bc|1=<br />
set mbox_type=Maildir<br />
set folder=$HOME/mail<br />
set spoolfile=+/<br />
set header_cache=~/.cache/mutt<br />
}}<br />
<br />
This is a minimal Configuration that enables you to access your Maildir and checks for new local Mails in INBOX. This configuration also caches the headers of the eMails to speed up directory-listings. It might not be enabled in your build (but it sure is in the Arch-Package). Note that this does not affect OfflineIMAP in any way. It always syncs the all directories on a Server. {{ic|spoolfile}} tells Mutt which local directories to poll for new Mail. You might want to add more Spoolfiles (for example the Directories of Mailing-Lists) and maybe other things. But this is subject to the Mutt manual and beyond the scope of this document.<br />
<br />
===SMTP===<br />
Whether you use POP or IMAP to receive mail you will probably still send mail using SMTP.<br />
<br />
==== Folders ====<br />
<br />
There is basically only one important folder here: the one where all your sent e-mails will be saved.<br />
record = +Sent<br />
<br />
Gmail saves automatically sent e-mail to {{ic|+[Gmail]/Sent}}, so we do not want<br />
duplicates.<br />
unset record<br />
<br />
====Using native SMTP support====<br />
The pacman version of Mutt is also compiled with SMTP support. Just check the online manual [http://manual.cream.org/index.cgi/muttrc.5 muttrc], or {{ic|man muttrc}} for more information.<br />
<br />
For example:<br />
{{bc|1=<br />
set my_pass='mysecretpass'<br />
set my_user=myname<br />
<br />
set realname = 'Your Real Name'<br />
set from = your-email-address<br />
set use_from = yes<br />
<br />
set smtp_url=smtps://$my_user:$my_pass@smtp.domain.tld<br />
set ssl_force_tls = yes<br />
}}<br />
<br />
Note that if your SMTP credentials are the same as your IMAP credentials, then you can use those variables:<br />
<br />
{{bc|1=<br />
set smtp_url=smtps://$imap_user:$imap_pass@smtp.domain.tld<br />
}}<br />
<br />
You may need to tweak the security parameters. If you get an error like<br />
{{ic|SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol}},<br />
then your server most probably uses the SMTP instead of SMTPS.<br />
<br />
{{bc|1=<br />
set smtp_url=smtp://$imap_user:$imap_pass@smtp.domain.tld<br />
}}<br />
<br />
There is other variable that you may need to set. For example for use of STARTTLS:<br />
{{bc|1=<br />
set ssl_starttls = yes<br />
}}<br />
<br />
====External SMTP support====<br />
An external SMTP agent such as [[msmtp]], [[SSMTP]] or {{Pkg|opensmtpd}} can also be used. This section exclusively covers configuring Mutt for msmtp.<br />
<br />
Edit Mutt's configuration file or create it if unpresent:<br />
{{hc|muttrc|2=<br />
set realname='Disgruntled Kangaroo'<br />
<br />
set sendmail="/usr/bin/msmtp"<br />
<br />
set edit_headers=yes<br />
set folder=~/mail<br />
set mbox=+mbox<br />
set spoolfile=+inbox<br />
set record=+sent<br />
set postponed=+drafts<br />
set mbox_type=Maildir<br />
<br />
mailboxes +inbox +lovey-dovey +happy-kangaroos<br />
}}<br />
<br />
====Sending mails from Mutt====<br />
Now, startup {{Ic|mutt}}:<br />
<br />
You should see all the mail in {{ic|~/mail/inbox}}. Press {{ic|m}} to compose mail; it will use the editor defined by your {{Ic|EDITOR}} environment variable. If this variable is not set, you can fix it before starting Mutt:<br />
$ export EDITOR=your-favorite-editor<br />
$ mutt<br />
<br />
You should store the EDITOR value into your shell resource configuration file (such as [[bashrc]]).<br />
You can also set the editor from Mutt's configuration file:<br />
{{hc|.muttrc|2=<br />
set editor=your-favorite-editor<br />
}}<br />
<br />
For testing purposes, address the letter to yourself. After you have written the letter, save and exit the editor. You will return to Mutt, which will now show information about your e-mail. Press {{ic|y}} to send it.<br />
<br />
===Multiple accounts===<br />
<br />
Now you should have a working configuration for one account at least. You might wonder how to use several accounts, since we put everything into a single file.<br />
<br />
Well all you need is to write account-specific parameters to their respective files and source them. All the IMAP/POP3/SMTP config for each account should go to its respective folder.<br />
{{Warning|When one account is setting a variable that is not specified for other accounts, you '''must unset''' it for them, otherwise configuration will overlap and you will most certainly experience unexpected behaviour.}}<br />
<br />
Mutt can handle this thanks to one of its most powerful feature: hooks.<br />
Basically a hook is a command that gets executed before a specific action.<br />
There are several hook availables. For multiple accounts, you must use account-hooks ''and'' folder-hooks.<br />
* Folder-hooks will run a command before switching folders. This is mostly useful to set the appropriate SMTP parameters when you are in a specific folder. For instance when you are in your work mailbox and you send a e-mail, it will automatically use your work account as sender.<br />
* Account-hooks will run a command everytime Mutt calls a function related to an account, like IMAP syncing. It does not require you to switch to any folder.<br />
<br />
Hooks take two parameters:<br />
account-hook [!]regex command<br />
folder-hook [!]regex command<br />
The regex is the folder to be matched (or not if preceded by the !).<br />
The command tells what to do.<br />
<br />
Let us give a full example:<br />
<br />
{{hc|.muttrc|<nowiki><br />
## General options<br />
set header_cache = "~/.cache/mutt"<br />
set imap_check_subscribed<br />
set imap_keepalive = 300<br />
unset imap_passive<br />
set mail_check = 60<br />
set mbox_type=Maildir<br />
<br />
## ACCOUNT1<br />
source "~/.mutt/work"<br />
# Here we use the $folder variable that has just been set in the sourced file.<br />
# We must set it right now otherwise the 'folder' variable will change in the next sourced file.<br />
folder-hook $folder 'source ~/.mutt/work'<br />
<br />
## ACCOUNT2<br />
source "~/.mutt/personal"<br />
folder-hook *user@gmail.com/ 'source ~/.mutt/personal'<br />
folder-hook *user@gmail.com/Family 'set realname="Bob"'<br />
</nowiki>}}<br />
<br />
{{hc|.mutt/work|<nowiki><br />
## Receive options.<br />
set imap_user=user@gmail.com<br />
set imap_pass=****<br />
set folder = imaps://user@imap.gmail.com/<br />
set spoolfile = +INBOX<br />
set postponed = +Drafts<br />
set record = +Sent<br />
<br />
## Send options.<br />
set smtp_url=smtps://user:****@smtp.gmail.com<br />
set realname='User X'<br />
set from=user@gmail.com<br />
set hostname="gmail.com"<br />
set signature="John Doe"<br />
# Connection options<br />
set ssl_force_tls = yes<br />
unset ssl_starttls<br />
<br />
## Hook -- IMPORTANT!<br />
account-hook $folder "set imap_user=user@gmail.com imap_pass=****"<br />
</nowiki>}}<br />
<br />
Finally {{ic|.mutt/personal}} should be similar to {{ic|.mutt/work}}.<br />
<br />
Now all your accounts are set, start Mutt. To switch from one account to another, just change the folder ({{ic|c}} key). Alternatively you can use the [[#Mutt-Sidebar|sidebar]].<br />
<br />
To change folder for different mailboxes you have to type the complete address -- for IMAP/POP3 folders, this may be quite inconvenient -- let us bind some key to it.<br />
<br />
{{bc|<br />
## Shortcuts<br />
macro index,pager <f2> '<sync-mailbox><enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
macro index,pager <f3> '<sync-mailbox><enter-command>source ~/.mutt/work<enter><change-folder>!<enter>'<br />
}}<br />
<br />
With the above shortcuts (or with the sidebar) you will find that changing folders (with {{ic|c}} by default) is not contextual, ''i.e.'' it will not list the folders of the current mailbox, but of the one used the last time you changed folders. To make the behaviour more contextual, the trick is to press ''='' or ''+'' for current mailbox. You can automate this with the following macro:<br />
macro index 'c' '<change-folder>?<change-dir><home>^K=<enter>'<br />
<br />
===Passwords management===<br />
Keep in mind that writing your password in {{ic|.muttrc}} is a security risk, and it might be of your concern.<br />
The trivial way to keep your passwords safe is not writing them in the config file. Mutt will then prompt for it when needed.<br />
However, this is quiet combersome in the long run, especiallly if you have several accounts.<br />
<br />
Here follows a smart and convenient solution: all your passwords are encrypted into one file and Mutt will prompt for a passphrase on startup only. You can opt for a keyring tool (e.g. GPG, {{pkg|pwsafe}}) or an encryption tool like {{pkg|ccrypt}}, which may be more simple and straightforward to use.<br />
Since GPG is a Mutt dependency, we will use it here.<br />
<br />
First create a pair of public/private keys:<br />
gpg --gen-key<br />
If you do not understand this process have a look at [[Wikipedia:Asymmetric cryptography]].<br />
<br />
Create a file '''in a secure environment''' since it will contain your passwords for a couple of seconds:<br />
{{hc|~/.my-pwds|<nowiki><br />
set my_pw_personal = ****<br />
set my_pw_work = ****</nowiki><br />
}}<br />
{{Note|Remember that user defined variables '''must''' start with {{ic|my_}}}}<br />
<br />
Now encrypt the file:<br />
gpg -e -r 'your-name' ~/.my-pwds<br />
Note that 'your-name' must match the one you provided at the {{ic|gpg --gen-key}} step.<br />
Now you can wipe your file containing your passwords in clear:<br />
shred -xu ~/.my-pwds<br />
Back to your account dedicated files, e.g. {{ic|.mutt/muttrc}}:<br />
{{bc|1=<br />
set imap_pass=$my_pw_personal<br />
# Every time the password is needed, use $my_pw_personal variable.<br />
}}<br />
<br />
And in your {{ic|.muttrc}}, '''before''' you source any account dedicated file:<br />
{{bc|<br />
source "gpg2 -dq $HOME/.my-pwds.gpg {{ic|<nowiki>|</nowiki>}}"<br />
}}<br />
{{Note|At the end of the line above, there is no space between the pipe and the double quote.}}<br />
* The {{ic|-q}} parameter makes gpg2 quiet which prevents gpg2 output messing with Mutt interface.<br />
* The pipe {{ic|<nowiki>|</nowiki>}} at the end of a string is the Mutt syntax to tell that you want the result of what is preceeding.<br />
<br />
Explanation: when Mutt starts, it will first source the result of the password decryption, that's why it will prompt for a passphrase. Then all passwords will be stored in memory in specific variables for the time Mutt runs. Then, when a folder-hook is called, it sets the imap_pass variable to the variable holding the appropriate password. When switching accounts, the imap_pass variable will be set to another variable holding another password, etc.<br />
<br />
If you use external tools like OfflineIMAP and msmtp, you need to set up an agent (e.g. gpg-agent, see [[GnuPG#gpg-agent]]) to keep the passphrase into cache and thus avoiding those tools always prompting for it.<br />
<br />
{{Note|The previous instruction produces a mutt configuration error in the 'source' line. A quick workaround is to encrypt a file only consisting of your password, then storing the decrypted version in a variable in your muttrc.}}<br />
{{bc|<br />
echo "password" > ~/.my-pwd<br />
gpg -e -r 'your-name' ~/.my-pwd<br />
shred -xu ~/.my-pwd<br />
}}<br />
<br />
Once you have setup ~/.my-pwd.gpg, continue to editing {{ic|.muttrc}}<br />
{{bc|1=<br />
set my_pw = `gpg -dq ~/.my-pwd.gpg`<br />
set imap_pass = $my_pass<br />
}}<br />
<br />
==Advanced features==<br />
Guides to get you started with using & customizing Mutt : <br />
* [http://mutt.blackfish.org.uk/ My first Mutt] (maintained by Bruno Postle) <br />
* [http://www.therandymon.com/woodnotes/mutt/using-mutt.html The Woodnotes Guide to the Mutt Email Client] (maintained by Randall Wood)<br />
* [http://stevelosh.com/blog/2012/10/the-homely-mutt The Homely Mutt] (by Steve Losh)<br />
<br />
If you have any Mutt specific questions, feel free to ask in [[ArchChannel|the irc channel]].<br />
<br />
===E-mail character encoding===<br />
You may be concerned with sending e-mail in a decent character set (charset for short) like UTF-8. Nowadays UTF-8 is highly recommended to almost everyone.<br />
<br />
When using Mutt there is two levels where the charset must be specified:<br />
* The text editor used to write the e-mail must save it in the desired encoding.<br />
* Mutt will then check the e-mail and determine which encoding is the more apropriate according to the priority you specified in the {{ic|send_charset}} variable. Default: "us-ascii:iso-8859-1:utf-8".<br />
<br />
So if you write an e-mail with characters allowed in ISO-8859-1 (like 'résumé'), but without characters specific to Unicode, then Mutt will set the encoding to ISO-8859-1.<br />
<br />
To avoid this behaviour, set the variable in your {{ic|muttrc}}:<br />
set send_charset="us-ascii:utf-8"<br />
or even<br />
set send_charset="utf-8"<br />
<br />
The first compatible charset starting from the left will be used.<br />
Since UTF-8 is a superset of US-ASCII it does not harm to leave it in front of UTF-8, it may ensure old MUA will not get confused when seeing the charset in the e-mail header.<br />
<br />
===Printing===<br />
You can install {{AUR|muttprint}} from the [[AUR]] for a fancier printing quality.<br />
In your muttrc file, insert:<br />
set print_command="/usr/bin/muttprint %s -p {PrinterName}"<br />
<br />
===Custom mail headers===<br />
One of the greatest thing in Mutt is that you can have full control over your mail header.<br />
<br />
First, make your headers editable when you write e-mails:<br />
set edit_headers=yes<br />
<br />
Mutt also features a special function {{ic|my_hdr}} for customizing your header. Yes, it is named just like a variable, but in fact it is a function.<br />
<br />
You can clear it completely, which you ''should'' do when switching accounts with different headers, otherwise they will overlap:<br />
unmy_hdr *<br />
<br />
Other variables have also an impact on the headers, so it is wise to clear them before using {{ic|my_hdr}}:<br />
unset use_from<br />
unset use_domain<br />
unset user_agent<br />
<br />
Now, you can add any field you want -- even non-standard one -- to your header using the following syntax:<br />
my_hdr <FIELD>: <VALUE><br />
Note that <VALUE> can be the result of a command.<br />
<br />
Example:<br />
{{bc|<br />
## Extra info.<br />
my_hdr X-Info: Keep It Simple, Stupid.<br />
<br />
## OS Info.<br />
my_hdr X-Operating-System: `uname -s`, kernel `uname -r`<br />
<br />
## This header only appears to MS Outlook users<br />
my_hdr X-Message-Flag: WARNING!! Outlook sucks<br />
<br />
## Custom Mail-User-Agent ID.<br />
my_hdr User-Agent: Every email client sucks, this one just sucks less.<br />
}}<br />
<br />
===Signature block===<br />
Create a .signature in your home directory. Your signature will be appended at the end of your email.<br />
Alternatively you can specify a file in your Mutt configuration:<br />
set signature="path/to/sig/file"<br />
====Random signature====<br />
You can use fortune to add a random signature to Mutt.<br />
{{bc|$ pacman -S fortune-mod}}<br />
<br />
Create a fortune file and then add the following line to your .muttrc:<br />
{{bc|1=set signature="fortune pathtofortunefile&#124;"}}<br />
Note the pipe at the end. It tells Mutt that the specified string is not a file, but a command.<br />
<br />
===Viewing URLs & opening your favorite web browser===<br />
Your should start by creating a .mutt directory in $HOME if not done yet. There, create a file named macros. Insert the following:<br />
macro pager \cb <pipe-entry>'urlview'<enter> 'Follow links with urlview'<br />
<br />
Then install {{AUR|urlview}} from the [[AUR]].<br />
<br />
Create a .urlview in $HOME and insert the following:<br />
REGEXP (((http|https|ftp|gopher)|mailto)[.:][^ >"\t]*|www\.[-a-z0-9.]+)[^ .,;\t>">\):]<br />
COMMAND <your-browser> %s <br />
<br />
When you read an email on the pager, hitting ctrl+b will list all the urls from the email. Navigate up or down with arrow keys and hit enter on the desired url. Your browser will start and go to the selected site.<br />
<br />
Some browser will require additional arguments to work properly. For example, [[Luakit]] will close on Mutt exit. You need to fork it to background, using the {{ic|-n}} parameter:<br />
COMMAND luakit -n %s 2>/dev/null<br />
The {{ic|2>/dev/null}} is to make it quiet, i.e. to prevent useless message printing where you do not want them to.<br />
<br />
{{Note|urlview has a few deficiencies (e.g. the inability to handle certain email encodings) and is fairly feature-bare (e.g. it does not provide context for links it finds). There are a couple alternatives that do better. One, which can handle all email encodings and provides link context, is [http://www.memoryhole.net/~kyle/extract_url/ extract_url.pl]. Another, which can also provide link context but cannot handle all email encodings, is [https://aur.archlinux.org/packages.php?ID&#61;44853 urlscan]. Both are drop-in replacements for urlview, though extract_url has features which benefit from additional configuration changes.}}<br />
<br />
===Viewing HTML===<br />
It is possible to pass the html body to an external HTML program and then dump it, keeping email viewing uniform and unobtrusive. Three programs are described here: lynx, w3m and elinks.<br />
<br />
Install lynx, w3m or elinks:<br />
pacman -S lynx<br />
or<br />
pacman -S w3m<br />
or<br />
pacman -S elinks<br />
<br />
If {{ic|~/.mutt/mailcap}} does not exist you will need to create it and save the following to it.<br />
text/html; lynx -display_charset=utf-8 -dump %s; nametemplate=%s.html; copiousoutput<br />
or, in case of w3m,<br />
text/html; w3m -I %{charset} -T text/html; copiousoutput;<br />
or, in case of elinks,<br />
text/html; elinks -dump ; copiousoutput;<br />
<br />
Edit muttrc and add the following,<br />
set mailcap_path = ~/.mutt/mailcap<br />
<br />
To automatically open HTML messages in lynx, add this additional line to the muttrc:<br />
auto_view text/html<br />
<br />
The beauty of this is, instead of seeing an html body as source or being opened<br />
by a separate program, in this case lynx, you see the formatted content directly,<br />
and any url links within the email can be displayed with {{ic|Ctrl+b}}.<br />
<br />
If you receive many emails with multiple or alternate encodings Mutt may default to treating every email as html. To avoid this, add the following variable to your ~/.muttrc to have Mutt default to text when available and use w3m/lynx only when no text version is availble in the email:<br />
alternative_order text/plain text/html<br />
<br />
Some HTML mails may not display correctly in a text-based web browser. As a fallback solution, you can bind a key to open a graphical browser in such cases.<br />
The following macro will open the HTML mail selected from the attachment view in the web browser defined in the environment. (Feel free to adapt the {{ic|~/.cache/mutt/}} folder).<br />
macro attach 'V' "<pipe-entry>cat >~/.cache/mutt/mail.html && $BROWSER ~/.cache/mutt/mail.html && rm ~/.cache/mutt/mail.html<enter>"<br />
<br />
===Mutt and Vim===<br />
*To limit the width of text to 72 characters, edit your .[[vim]]rc file and add:<br />
au BufRead /tmp/mutt-* set tw=72<br />
<br />
*Another choice is to use Vim's mail filetype plugin to enable other mail-centric options besides 72 character width. Edit {{ic|~/.vim/filetype.vim}}, creating it if unpresent, and add:<br />
{{bc| <br />
augroup filetypedetect<br />
" Mail<br />
autocmd BufRead,BufNewFile *mutt-* setfiletype mail<br />
augroup END<br />
}}<br />
<br />
*To set a different tmp directory, e.g. ~/.tmp, add a line to your muttrc as follows:<br />
set tmpdir="~/.tmp"<br />
<br />
*To reformat a modified text see the Vim context help<br />
:h 10.7<br />
<br />
===Mutt and GNU nano===<br />
[[nano]] is another nice console editor to use with Mutt. <br />
<br />
To limit the width of text to 72 characters, edit your .nanorc file and add:<br />
set fill 72<br />
<br />
Also, in muttrc file, you can specify the line to start editing so that you will skip the mail header:<br />
set editor="nano +7"<br />
<br />
===Mutt and Emacs===<br />
Emacs has a ''mail'' and a ''message'' major mode.<br />
To switch to mail-mode automatically when Emacs is called from Mutt, you can add the following to your {{ic|.emacs}}:<br />
{{hc|.emacs|<nowiki><br />
;; Mutt support.<br />
(setq auto-mode-alist (append '(("/tmp/mutt.*" . mail-mode)) auto-mode-alist))<br />
</nowiki>}}<br />
<br />
If you usually run Emacs daemon, you may want Mutt to connect to it. Add this to your {{ic|.muttrc}}:<br />
{{hc|.muttrc|<nowiki><br />
set editor="emacsclient -a \"\" -t"</nowiki><br />
}}<br />
<br />
===Colors===<br />
Append sample color definitions to your .muttrc file:<br />
$ cat /usr/share/doc/mutt/samples/colors.linux >> ~/.muttrc<br />
Then adjust to your liking.<br />
The actual color each of these settings will produce depends on the colors set in your [[Xresources|~/.Xresources]] file.<br />
<br />
Alternatively, you can source any file you want containing colors (and thus act as a theme file):<br />
{{bc|<br />
source ~/.mutt/colors.zenburn<br />
}}<br />
<br />
A nice theme example:<br />
{{bc|<nowiki><br />
## Theme kindly inspired from <br />
## http://nongeekshandbook.blogspot.ie/2009/03/mutt-color-configuration.html <br />
<br />
## Colours for items in the index <br />
color index brightcyan black ~N<br />
color index brightred black ~O<br />
color index brightyellow black ~F<br />
color index black green ~T<br />
color index brightred black ~D<br />
mono index bold ~N<br />
mono index bold ~F<br />
mono index bold ~T<br />
mono index bold ~D<br />
<br />
## Highlights inside the body of a message. <br />
<br />
## URLs <br />
color body brightgreen black "(http|ftp|news|telnet|finger)://[^ \"\t\r\n]*"<br />
color body brightgreen black "mailto:[-a-z_0-9.]+@[-a-z_0-9.]+"<br />
mono body bold "(http|ftp|news|telnet|finger)://[^ \"\t\r\n]*"<br />
mono body bold "mailto:[-a-z_0-9.]+@[-a-z_0-9.]+"<br />
<br />
## Email addresses. <br />
color body brightgreen black "[-a-z_0-9.%$]+@[-a-z_0-9.]+\\.[-a-z][-a-z]+"<br />
<br />
## Header <br />
color header green black "^from:"<br />
color header green black "^to:"<br />
color header green black "^cc:"<br />
color header green black "^date:"<br />
color header yellow black "^newsgroups:"<br />
color header yellow black "^reply-to:"<br />
color header brightcyan black "^subject:"<br />
color header red black "^x-spam-rule:"<br />
color header green black "^x-mailer:"<br />
color header yellow black "^message-id:"<br />
color header yellow black "^Organization:"<br />
color header yellow black "^Organisation:"<br />
color header yellow black "^User-Agent:"<br />
color header yellow black "^message-id: .*pine"<br />
color header yellow black "^X-Fnord:"<br />
color header yellow black "^X-WebTV-Stationery:"<br />
<br />
color header red black "^x-spam-rule:"<br />
color header green black "^x-mailer:"<br />
color header yellow black "^message-id:"<br />
color header yellow black "^Organization:"<br />
color header yellow black "^Organisation:"<br />
color header yellow black "^User-Agent:"<br />
color header yellow black "^message-id: .*pine"<br />
color header yellow black "^X-Fnord:"<br />
color header yellow black "^X-WebTV-Stationery:"<br />
color header yellow black "^X-Message-Flag:"<br />
color header yellow black "^X-Spam-Status:"<br />
color header yellow black "^X-SpamProbe:"<br />
color header red black "^X-SpamProbe: SPAM"<br />
<br />
## Coloring quoted text - coloring the first 7 levels: <br />
color quoted cyan black<br />
color quoted1 yellow black<br />
color quoted2 red black<br />
color quoted3 green black<br />
color quoted4 cyan black<br />
color quoted5 yellow black<br />
color quoted6 red black<br />
color quoted7 green black<br />
<br />
## Default color definitions <br />
#color hdrdefault white green <br />
color signature brightmagenta black<br />
color indicator black cyan<br />
color attachment black green<br />
color error red black<br />
color message white black<br />
color search brightwhite magenta<br />
color status brightyellow blue<br />
color tree brightblue black<br />
color normal white black<br />
color tilde green black<br />
color bold brightyellow black<br />
#color underline magenta black <br />
color markers brightcyan black<br />
<br />
## Colour definitions when on a mono screen <br />
mono bold bold<br />
mono underline underline<br />
mono indicator reverse</nowiki><br />
}}<br />
<br />
===Index Format===<br />
<br />
Here follows a quick example to put in your {{ic|.muttrc}} to customize the Index Format, i.e. the columns displayed in the folder view.<br />
{{bc|<nowiki><br />
set date_format="%y-%m-%d %T"<br />
set index_format="%2C | %Z [%d] %-30.30F (%-4.4c) %s"</nowiki><br />
}}<br />
See the [http://www.mutt.org/doc/manual/manual-6.html Mutt Reference], {{ic|man 3 strftime}} and {{ic|man 3 printf}} for more details.<br />
<br />
====Display recipient instead of sender in "Sent" folder view====<br />
<br />
By default Mutt will display the sender in the index view. It is fine for most folders, but rather useless for the one were you store a copy of your sent e-mails since it will always display your name.<br />
<br />
The "columns" of the index can be configured through the {{ic|index_format}} variable. Its syntax is documented in the {{ic|muttrc}} man page. The values of our concern are {{ic|%t}} (recipient) and {{ic|%F}} (sender).<br />
<br />
To change the columns according to the current folder, we need to use a hook:<br />
{{hc|muttrc|<nowiki><br />
folder-hook *[sS]ent* 'set index_format="%2C | %Z [%d] %-30.30t (%-4.4c) %s"'<br />
folder-hook ! *[sS]ent* 'set index_format="%2C | %Z [%d] %-30.30F (%-4.4c) %s"'<br />
</nowiki>}}<br />
<br />
The exclamation mark means ''everything that does not match the following regex''. Of course you can change the index_format following you taste, and the regular expression if the folder does not have ''Sent'' not ''sent'' in its name.<br />
<br />
====Variable column width====<br />
<br />
If you rezise the window, the subject might get truncated while there is still unused space left for some fields, like for the sender.<br />
You can get the maximum column of your terminal (i.e. the width) using a shell call to {{ic|tput cols}}. With this value you can set a percentage of the width to fields like Sender and Subject.<br />
<br />
Example using the above folder-hook and a sidebar width of 24:<br />
{{hc|muttrc|<nowiki><br />
## From field gets 30% of remaining space, Subject gets 70%.<br />
## Remaining space is the total width minus the other fields (35), minus the sidebar (24)<br />
set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`<br />
set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`<br />
<br />
folder-hook .*[sS]ent.* 'set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}t (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
folder-hook ! .*[sS]ent.* 'set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}F (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
</nowiki><br />
}}<br />
<br />
Unfortunately, the above example suffers from one caveat: the {{ic|my_col_*}} variables get computed one time only, on first start. So if you want it to refresh automatically, we need to set the variable in a hook. Sadly there is no hook for window resizing, but you can still use the {{ic|folder-hook}} so that a simple folder switch suffice to recompute the view.<br />
{{hc|muttrc|<nowiki><br />
folder-hook .*[sS]ent.* 'set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`; set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`; set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}t (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
folder-hook ! .*[sS]ent.* 'set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`; set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`; set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}F (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
</nowiki><br />
}}<br />
<br />
===Contact management===<br />
<br />
====Address aliases====<br />
''Aliases'' is the way Mutt manages contacts.<br />
An alias is '''nickname [longname] <address>'''.<br />
* The '''nickname''' is what you will type in Mutt to get your contact address. One word only, and should be easy to remember.<br />
* The '''longname''' is optional. It may be several words.<br />
* An '''<address>''' must be in a valid form (i.e. with an {{ic|@}}).<br />
<br />
It is quite simple indeed. Add this to {{ic|.muttrc}}:<br />
{{bc|1=<br />
set alias_file = "~/.mutt/aliases"<br />
set sort_alias = alias<br />
set reverse_alias = yes<br />
source $alias_file<br />
}}<br />
<br />
Explanation:<br />
* {{ic|alias_file}} is the file where the information is getting stored when you add an alias from within Mutt.<br />
* {{ic|sort_alias}} specifies which field to use to sort the alias list when displayed in Mutt. Possible values: alias, address.<br />
* {{ic|reverse_alias}} sorts in reverse order if set to yes.<br />
* {{ic|source $alias_file}} tells Mutt to read aliases on startup. Needed for auto-completion.<br />
<br />
Now all you have to do when prompted {{ic|To:}} is writing the alias instead of the full address. The beauty of it is that you can auto-complete the alias using {{ic|Tab}}.<br />
Autocompleting a wrong or an empty string will display the full list. You can select the alias as usual, or by typing its index number.<br />
<br />
There is two ways to create aliases:<br />
* From Mutt, press {{ic|a}} when an e-mail of the targetted person if selected.<br />
* Edit the alias_file manually. The syntax is really simple:<br />
{{bc|<br />
alias nickname Long Name <my-friend@domain.tld><br />
}}<br />
<br />
====Abook====<br />
<br />
{{pkg|abook}} is a stand-alone program dedicated to contact management. It uses a very simple text-based interface and contacts are stored in a plain text, human-readable database. Besides the desired contact properties are extensible (birthday, address, fax, and so on).<br />
<br />
Abook is specifically designed to be interfaced with Mutt, so that it can serve as a full, more featured replacement of Mutt internal aliases. If you want to use Abook instead of aliases, remove the aliases configuration in {{ic|.muttrc}} and add this:<br />
<br />
{{hc|muttrc|<nowiki><br />
## Abook<br />
set query_command= "abook --mutt-query '%s'"<br />
macro index,pager a "<pipe-message>abook --add-email-quiet<return>" "Add this sender to Abook"<br />
bind editor <Tab> complete-query<br />
</nowiki><br />
}}<br />
<br />
See the man pages {{ic|abook}} and {{ic|abookrc}} for more details and a full configuration sample.<br />
<br />
===Request IMAP mail retrieval manually===<br />
If you do not want to wait for the next automatic IMAP fetching (or if you did not enable it), you might want to fetch mails manually.<br />
There is a mutt command {{ic|imap-fetch-mail}} for that.<br />
Alternatively, you could bind it to a key:<br />
bind index "^" imap-fetch-mail<br />
<br />
===Avoiding slow index on large (IMAP) folders due to coloring===<br />
<br />
Index highlighting by regex is nice, but can lead to slow folder viewing if your regex checks the body of the message.<br />
<br />
Use folder-hook for only highlighting in for example the inbox (if you manage to empty your mailbox effiently):<br />
<br />
folder-hook . 'uncolor index "~b \"Hi Joe\" ~R !~T !~F !~p !~P"'<br />
folder-hook ""!"" 'color index brightyellow black "~b \"Hi Joe\" ~N !~T !~F !~p !~P"'<br />
<br />
===Speed up folders switch===<br />
Add this to your {{ic|.muttrc}}:<br />
{{bc|1=<br />
set sleep_time = 0<br />
}}<br />
<br />
===Use Mutt to send mail from command line===<br />
Man pages will show all available commands and how to use them, but here are a couple of examples. You could use Mutt to send alerts, logs or some other system information, triggered by login through .bash_profile, or as a regular cron job.<br />
<br />
Send a message:<br />
mutt -s "Subject" somejoeorjane@someserver.com < /var/log/somelog<br />
<br />
Send a message with attachment:<br />
mutt -s "Subject" somejoeorjane@someserver.com -a somefile < /tmp/sometext.txt<br />
<br />
===Composing HTML e-mails===<br />
<br />
Since Mutt has nothing of a WYSIWIG client, HTML is quite straightforward, and you can do much more than with all WYSIWIG mail clients around since you edit the source code directly.<br />
Simply write your mail using HTML syntax. For example:<br />
{{bc|<nowiki><br />
This is normal text<br><br />
<b>This is bold text</b></nowiki><br />
}}<br />
Now before sending the mail, use the {{ic|edit-type}} command (default shortcut {{ic|Ctrl+t}}), and replace {{ic|text/plain}} by {{ic|text/html}}.<br />
<br />
{{Note|HTML e-mails are regarded by many people as useless, cumbersome, and subject to reading issues. Mutt can read HTML mails with a text browser like w3m or lynx, but it has clearly no advantage over a plain-text e-mail. You should avoid writing HTML e-mails when possible.}}<br />
<br />
===How to display another email while composing===<br />
A common complaint with Mutt is that when composing a new mail (or reply), you cannot open another mail (i.e. for checking with another correspondent) without closing the current mail (postponing). The following describes a solution:<br />
<br />
First, fire up Mutt as usual. Then, launch another terminal window. Now start a new Mutt with <br />
mutt -R<br />
This starts Mutt in read-only mode, and you can browse other emails at your convenience. It is strongly recommended to always launch a second Mutt in read-only mode, as conflicts will easily arise otherwise.<br />
<br />
Now, this solution calls for a bit of typing, so we would like to automate this. The following works with [[Awesome]], in other WM's or DE's similar solutions are probably available: just google how to add a key binding, and make the desired key execute <br />
$TERM -e mutt -R <br />
where $TERM is your terminal.<br />
<br />
As for Awesome: edit your rc.lua, and add the following on one of the first lines, after terminal = "yourTerminal" etc.<br />
mailview = terminal .. " -e mutt -R"<br />
This automatically uses your preferred terminal, ".." is concatenation in Lua. Note the space before -e.<br />
<br />
Then add the following inside --{{{ Key bindings<br />
awful.key({ modkey, }, "m", function() awful.util.spawn(mailview) end),<br />
<br />
Omit the final comma if this is the last line. You can, of course use another key than "m". Now, save&quit, and check your syntax with <br />
awesome -k<br />
If this is good, restart awesome and give it a try!<br />
<br />
Now, a usage example: Launch Mutt as usual. Start a new mail, and then press "Mod4"+"m". This opens your mailbox in a new terminal, and you can browse around and read other emails. Now, a neat bonus: exit this read-only-Mutt with "q", and the terminal window it created disappears!<br />
<br />
===Archive treated e-mails===<br />
When you read an e-mail, you have four choices: Answer it, Flag it, Archive it or Delete it. If you have this in mind, you can keep your inbox slim and fit with this macro (set up for Gmail):<br />
<br />
macro index \' "<tag-pattern>~R !~D !~F<enter>\<br />
<tag-prefix><save-message>+[Gmail]/All <enter>" \<br />
"Archive"<br />
<br />
===Mutt-Sidebar===<br />
<br />
The vanilla Mutt does not feature a sidebar unlike most MUAs. If you miss it, you can install {{Aur|mutt-sidebar}} from the AUR which features a patch for a list of folders on the left side of the Mutt window.<br />
<br />
For a while there has been several different patches for the sidebar. Since the late 2000's, it seems like the main patch is maintained at [http://www.lunar-linux.org/mutt-sidebar/ Lunar Linux]. See the documentation there. Note that the patch also updates the {{ic|muttrc}} man page, so have a look at the {{ic|sidebar_*}} sections.<br />
<br />
You can choose to display the sidebar on startup, or to prompt it manually with a key:<br />
{{bc|<nowiki><br />
set sidebar_visible = yes<br />
macro index b '<enter-command>toggle sidebar_visible<enter><refresh>'<br />
macro pager b '<enter-command>toggle sidebar_visible<enter><redraw-screen>'<br />
</nowiki>}}<br />
<br />
You also probabaly need some shortcuts to navigate in the bar:<br />
{{bc|<nowiki><br />
# Ctrl-n, Ctrl-p to select next, previous folder.<br />
# Ctrl-o to open selected folder.<br />
bind index,pager \CP sidebar-prev<br />
bind index,pager \CN sidebar-next<br />
bind index,pager \CO sidebar-open<br />
</nowiki>}}<br />
<br />
{{Note|You ''must'' set the {{ic|mailboxes}} variables or the {{ic|imap_check_subscribed}} to tell the sidebar which folder should be displayed. See the [[#mailboxes|mailboxes]] section.}}<br />
<br />
If you use the {{ic|imap_check_subscribed}} option to list all your folders, they will appear in an uncontrollable order in the sidebar. Fix it with<br />
set sidebar_sort = yes<br />
Note that with the {{ic|mailboxes}} option, folders appear in the order they were set to {{ic|mailboxes}} if you do not use the {{ic|sidebar_sort}} option.<br />
<br />
If you have trouble with truncated names, set the option<br />
set sidebar_shortpath = yes<br />
<br />
Finally, you may want to add a separator between different mailboxes. The sidebar patch does not currently provide any kind of separator option. A simple (and dirty) workaround is to add a fake folder to the list of folders:<br />
mailboxes "+-- My mailbox -----------"<br />
The dashes are not required, they are here just for fancy output.<br />
It will also work if you used the {{ic|imap_check_subscribed}} option.<br />
If you chose to sort the folders, the separator will not appear in the correct place, so an even more dirty workaround is to add an 'A' in front of the name. Note that punctuation is ignored during sorting.<br />
mailboxes "+A-- My mailbox -----------"<br />
<br />
===Migrating mails from one computer to another===<br />
In case you are transfering your mails to a new machine (copy&paste), you probably need to delete the header cache (a file or folder like {{ic|~/.cache/mutt}} if you followed the above configuration) to make Mutt able to read your migrated E-Mails. Otherwise Mutt may freeze.<br />
<br />
Note that if you had a folder created for you header cache, all mailboxes will have their own cache file, so you can delete caches individually without having to remove everything.<br />
<br />
=== Filtering the message view ===<br />
<br />
You can restrict the view to e-mails matching a pattern and specific properties with the {{ic|limit}} command (default shortcut: {{ic|l}}).<br />
<br />
To view all e-mails containing "foo" in the header, simply write "foo" and you are done. To remove the filter, use the "all" keyword.<br />
<br />
To view all flagged messages, use<br />
~F<br />
To view all unread messages, use<br />
~U<br />
<br />
All possible patterns are listed in the [http://www.mutt.org/doc/manual/manual-4.html#ss4.2 official manual].<br />
<br />
=== Display the index above the pager view ===<br />
<br />
Set the following variable in your {{ic|muttrc}}:<br />
set pager_index_lines=10<br />
<br />
==Troubleshooting==<br />
<br />
===Backspace does not work in Mutt===<br />
This is a common problem with some xterm-like terminals.<br />
Two solutions:<br />
* Either rebind the key in {{ic|.muttrc}}<br />
bind index,pager ^? previous-page<br />
Note that {{ic|^?}} is one single character representing backspace in [[wikipedia:Caret_notation|caret notation]]. To type in Emacs, use {{ic|Ctrl+q Backspace}}, in Vim {{ic|Ctrl+v Backspace}}.<br />
<br />
* Or fix your terminal:<br />
$ infocmp > termbs.src<br />
Edit {{ic|termbs.src}} and change {{ic|1= kbs=^H}} to {{ic|1= kbs=\177}}, then:<br />
$ tic -x termbs.src<br />
<br />
===Android's default MUA receives empty e-mail with attachment "Unknown.txt"===<br />
<br />
This is because Mutt adds 'Content-Disposition' line to every e-mail header. This line is actually correct, the issue comes from Android 2 MUA misinterpreting it. This bug seems to be fixed in the Android 4 MUA.<br />
There is a patched version for Android available in the AUR. Installing {{AUR|mutt-android-patch}} will fix the issue.<br />
<br />
===The ''change-folder'' function always prompt for the same mailbox ===<br />
<br />
This is not a bug, this is actually an intended behaviour. See the [[#Multiple accounts|multiple accounts section]] for a workaround.<br />
<br />
===I cannot change folder when using Mutt read-only (Mutt -R)===<br />
<br />
This is certainly because you are use are using macros like this one:<br />
macro index,pager <f2> '<sync-mailbox><enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
This macro tells Mutt to sync (which is a write operation) before switching.<br />
Either use the [[#Mutt-Sidebar|sidebar]] or set another macro:<br />
macro index,pager <f3> '<enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
<br />
== Documentation ==<br />
<br />
Newcomers may find it quite hard to find help for Mutt. Actually most of the topics are covered in the official documentation. We urge you to read it.<br />
<br />
* [http://www.mutt.org/doc/manual/ The official manual]. The stock {{pkg|mutt}} package for Arch Linux also installs the HTML and plain text manual at {{ic|/usr/share/doc/mutt/}}.<br />
* The {{ic|mutt}} and {{ic|muttrc}} man pages.<br />
<br />
== See also ==<br />
* [http://www.mutt.org/ The official Mutt website]<br />
* [http://wiki.mutt.org/ The Mutt wiki]<br />
* [http://pbrisbin.com/posts/two_accounts_in_mutt/ Brisbin's great guide on how to setup different IMAP accounts with Mutt, offlineimap, msmtp]<br />
* [http://home.roadrunner.com/~computertaijutsu/mutt.html A Quick Guide to Mutt]<br />
* [http://pyropus.ca/software/getmail/configuration.html#running Documentation on Configuring Getmail with rcfiles]<br />
* [http://stevelosh.com/blog/2012/10/the-homely-mutt/ Steve Losh on Mutt, offlineimap, msmtp, notmuch (gmail focussed)]<br />
* [http://www.muttrcbuilder.org/ muttrc builder]</div>Kevrhttps://wiki.archlinux.org/index.php?title=Mutt&diff=292674Mutt2014-01-13T08:33:52Z<p>Kevr: /* Passwords management */</p>
<hr />
<div>[[Category:Email Client]]<br />
[[es:Mutt]]<br />
[[it:Mutt]]<br />
[[zh-CN:Mutt]]<br />
[[zh-TW:Mutt]]<br />
{{Related articles start}}<br />
{{Related|fdm}}<br />
{{Related|msmtp}}<br />
{{Related|offlineimap}}<br />
{{Related articles end}}<br />
'''Mutt''' is a text-based mail client renowned for its powerful features. Though over a decade old, Mutt remains the mail client of choice for a great number of power-users. Unfortunately, a default Mutt install is plagued by complex keybindings along with a daunting amount of documentation. This guide will help the average user get Mutt up and running, and begin customizing it to their particular needs.<br />
<br />
==Overview==<br />
Mutt focuses primarily on being a Mail User Agent (MUA), and was originally written to view mail. Later implementations (added for retrieval, sending, and filtering mail) are simplistic compared to other mail applications and, as such, users may wish to use external applications to extend Mutt's capabilities. <br />
<br />
Nevertheless, the Arch Linux {{Pkg|mutt}} package is compiled with IMAP, POP3 and SMTP support, removing the necessity for external applications.<br />
<br />
This article covers using both native IMAP sending and retrieval, and a setup depending on [[OfflineIMAP]] or [[getmail]] (POP3) to retrieve mail, [[procmail]] to filter it in the case of POP3, and [[msmtp]] to send it.<br />
<br />
==Installing==<br />
[[pacman|Install]] {{Pkg|mutt}}, available in the [[Official Repositories]]. <br />
<br />
Optionally install external helper applications for an IMAP setup, such as {{Pkg|offlineimap}} and {{Pkg|msmtp}}.<br />
<br />
Or (if using POP3) {{Pkg|getmail}} or {{Pkg|fdm}} and {{Pkg|procmail}}.<br />
<br />
{{Note|<br />
*If you just need the authentication methods LOGIN and PLAIN, these are satisfied with the dependency {{Pkg|libsasl}}<br />
*If you want to (or have to) use CRAM-MD5, GSSAPI or DIGEST-MD5, install the package {{Pkg|cyrus-sasl-gssapi}}<br />
*If you are using Gmail as your SMTP server, you may need to install the package {{Pkg|cyrus-sasl}}<br />
}}<br />
<br />
==Configuring==<br />
This section covers IMAP, [[#POP3]], [[#Maildir]] and [[#SMTP]] configuration.<br />
<br />
Note that Mutt will recognize two locations for its configuration file; {{ic|~/.muttrc}} and {{ic|~/.mutt/muttrc}}. Either location will work.<br />
You should also know some prerequisite for Mutt configuration. Its syntax is very close to the Bourne Shell. For example, you can get the content of another config file:<br />
source /path/to/other/config/file<br />
You can use variables and assign the result of shell commands to them.<br />
set editor=`echo \$EDITOR`<br />
Here the {{ic|$}} gets escaped so that it does not get substituted by Mutt before being passed to the shell.<br />
Also note the use of the backquotes, as bash syntax {{ic|$(...)}} does not work.<br />
Mutt has a lot of predefined variables, but you can also set your own. User variable '''must begin with "my"!'''<br />
set my_name = "John Doe"<br />
<br />
===IMAP===<br />
''Native and external setups''<br />
<br />
====Using native IMAP support====<br />
The pacman version of Mutt is compiled with IMAP support. At the very least you need to have 4 lines in your muttrc file to be able to access your mail.<br />
<br />
=====imap_user=====<br />
set imap_user=USERNAME<br />
<br />
Continuing with the previous example, remember that Gmail requires your full email address (this is not standard):<br />
set imap_user=your.username@gmail.com<br />
<br />
=====imap_pass=====<br />
If unset, the password will be prompted for.<br />
set imap_pass=SECRET<br />
<br />
=====folder=====<br />
Instead of a local directory which contains all your mail (and directories), use your server (and the highest folder in the hierarchy, if needed).<br />
set folder=imap[s]://imap.server.domain[:port]/[folder/]<br />
<br />
You do not have to use a folder, but it might be convenient if you have all your other folders inside your INBOX, for example. Whatever you set here as your folder can be accessed later in Mutt with just an equal sign (=) or a plus sign (+). Example:<br />
set folder=imaps://imap.gmail.com/<br />
<br />
It should be noted that for several accounts, it is best practice to use different folders -- e.g. for ''account-hook''. If you have several Gmail account, use<br />
set folder=imaps://username@imap.gmail.com/<br />
instead, where your account is ''username@gmail.com''. This way it will be possible to distinguish the different folders. Otherwise it would lead to authentication errors.<br />
<br />
=====spoolfile=====<br />
The spoolfile is the folder where your (unfiltered) e-mail arrives. Most e-mail services conventionally names it ''INBOX''. You can now use '=' or '+' as a substitution for the full {{ic|folder}} path that was configured above. For example:<br />
set spoolfile=+INBOX<br />
<br />
=====mailboxes=====<br />
Any imap folders that should be checked regularly for new mail should be listed here:<br />
mailboxes =INBOX =family<br />
mailboxes imaps://imap.gmail.com/INBOX imaps://imap.gmail.com/family<br />
<br />
Alternatively, check for all subscribed IMAP folders (as if all were added with a {{Ic|mailboxes}} line):<br />
set imap_check_subscribed<br />
<br />
These two versions are equivalent if you want to subscribe to all folders. So the second method is much more convenient, but the first one gives you more flexibility. Also, newer Mutt versions are configured by default to include a macro bound to the 'y' key which will allow you to change to any of the folders listed under mailboxes.<br />
<br />
If you do not set this variable, the ''spoolfile'' will be used by default.<br />
This variable is also important for the [[#Mutt-Sidebar|sidebar]].<br />
<br />
=====Summary=====<br />
Using these options, you will be able to start Mutt, enter your IMAP password, and start reading your mail. Here is a muttrc snippet (for Gmail) with some other lines you might consider adding for better IMAP support.<br />
{{bc|1=<br />
set folder = imaps://imap.gmail.com/<br />
set imap_user = your.username@gmail.com<br />
set imap_pass = your-imap-password<br />
set spoolfile = +INBOX<br />
mailboxes = +INBOX<br />
<br />
# Store message headers locally to speed things up.<br />
# If hcache is a folder, Mutt will create sub cache folders for each account which may speeds things even more up.<br />
set header_cache = ~/.cache/mutt<br />
<br />
# Store messages locally to speed things up, like searching message bodies.<br />
# Can be the same folder as header_cache.<br />
# This will cost important disk usage according to your e-mail amount.<br />
set message_cachedir = "~/.cache/mutt"<br />
<br />
# Specify where to save and/or look for postponed messages.<br />
set postponed = +[Gmail]/Drafts<br />
<br />
# Allow Mutt to open new imap connection automatically.<br />
unset imap_passive<br />
<br />
# Keep IMAP connection alive by polling intermittently (time in seconds).<br />
set imap_keepalive = 300<br />
<br />
# How often to check for new mail (time in seconds).<br />
set mail_check = 120<br />
}}<br />
<br />
====External IMAP support====<br />
While IMAP-functionality is built into Mutt, it does not download mail for offline-use. The [[OfflineIMAP]] article describes how to download your emails to a local folder which can then be processed by Mutt.<br />
<br />
Consider using applications such as {{pkg|spamassassin}} or {{AUR|imapfilter}} to sort mail.<br />
<br />
===POP3===<br />
''Retrieving and sorting mail with external applications''<br />
<br />
====Retrieving mail====<br />
Create the directory {{ic|~/.getmail/}}. Open the file {{ic|~/.getmail/getmailrc}} in your favorite text editor.<br />
<br />
Here is an example {{ic|getmailrc}} used with a gmail account.<br />
{{bc|1=<br />
[retriever]<br />
type = SimplePOP3SSLRetriever<br />
server = pop.gmail.com<br />
username = username@gmail.com<br />
port = 995<br />
password = password<br />
<br />
[destination]<br />
type = Maildir<br />
path = ~/mail/<br />
}}<br />
<br />
You can tweak this to your POP3 service's specification.<br />
<br />
Most people will like to add the following section to their {{ic|getmailrc}} to prevent all the mail on the server being downloaded every time getmail is ran.<br />
{{bc|1=<br />
[options]<br />
read_all = False<br />
}}<br />
<br />
As you can see {{ic|~/.getmail/getmailrc}} contains sensitive information (namely, email account passwords in plain text). You will want to change access permissions to the directory so only the owner can see it:<br />
<br />
$ chmod 700 ~/.getmail<br />
<br />
For this guide we will be storing our mail in the {{ic|maildir}} format. The two main mailbox formats are {{ic|mbox}} and {{ic|maildir}}. The main difference between the two is that {{ic|mbox}} is one file, with all of your mails and their headers stored in it, whereas a {{ic|maildir}} is a directory tree. Each mail is its own file, which will often speed things up.<br />
<br />
A {{ic|maildir}} is just a folder with the folders {{ic|cur}}, {{ic|new}} and {{ic|tmp}} in it.<br />
mkdir -p ~/mail/{cur,new,tmp}<br />
<br />
Now, run getmail. If it works fine, you can create a cronjob for getmail to run every n hours/minutes. Type {{ic|crontab -e}} to edit cronjobs, and enter the following:<br />
*/10 * * * * /usr/bin/getmail<br />
That will run {{ic|getmail}} every 10 minutes.<br />
<br />
Also, to quiet getmail down, we can reduce its verbosity to zero by adding the following to {{ic|getmailrc}}.<br />
{{bc|1=<br />
[options]<br />
verbose = 0<br />
}}<br />
<br />
=====More than one Email account with getmail=====<br />
By default, when you run {{ic|getmail}} the program searches for the file getmailrc created as seen above. If you have more than one mail account you would like to get mail from, then you can create such a file for each email address, and then tell getmail to run using both of them. Obviously if you have two accounts and two files you cannot have both of them called getmailrc. What you do is give them two different names, using myself as an example: I call one personal, and one university. These two files contain content relevant to my personal mail, and my university work mail respectively. Then to get getmail to work on these two files, instead of searching for getmailrc(default), I use the --rcfile switch like so: {{ic|getmail --rcfile university --rcfile personal}} This can work with more files if you have more email accounts, just make sure each file is in the .getmail directory and make sure to alter the cronjob to run the command with the --rcfile switches. E.g.<br />
'''*/30 * * * * /usr/bin/getmail --rcfile university --rcfile personal'''<br />
<br />
Obviously you can call your files whatever you want, providing you include them in the cronjob or shell command, and they are in the .getmail/ directory, getmail will fetch mail from those two accounts.<br />
<br />
====Sorting mail====<br />
[http://www.procmail.org/ Procmail] is an extremely powerful sorting tool. For the purposes of this wiki, we will do some primitive sorting to get started.<br />
<br />
You must edit your getmailrc to pass retrieved mail to procmail:<br />
{{bc|1=<br />
[destination]<br />
type = MDA_external<br />
path = /usr/bin/procmail<br />
}}<br />
<br />
Now, open up {{ic|.procmailrc}} in your favorite editor. The following will sort all mail from the happy-kangaroos mailing list, and all mail from your lovey-dovey friend in their own maildirs.<br />
{{bc|1=<br />
MAILDIR=$HOME/mail<br />
DEFAULT=$MAILDIR/inbox/<br />
LOGFILE=$MAILDIR/log<br />
<br />
:0:<br />
* ^To: happy-kangaroos@nicehost.com<br />
happy-kangaroos/<br />
<br />
:0:<br />
* ^From: loveydovey@iheartyou.net<br />
lovey-dovey/<br />
}}<br />
After you have saved your {{ic|.procmailrc}}, run getmail and see if procmail succeeds in sorting your mail into the appropriate directories.<br />
<br />
{{Note|One easy to make mistake with .procmailrc is the permission. procmail require it to have permission 644 and will not give meaningless error message if you do not.}}<br />
<br />
===Maildir===<br />
Maildir is a generic and standardized format. Almost every MUA is able to handle Maildirs and Mutt's support is excellent. There are just a few simple things that you need to do to get Mutt to use them. Open your muttrc and add the following lines:<br />
{{bc|1=<br />
set mbox_type=Maildir<br />
set folder=$HOME/mail<br />
set spoolfile=+/<br />
set header_cache=~/.cache/mutt<br />
}}<br />
<br />
This is a minimal Configuration that enables you to access your Maildir and checks for new local Mails in INBOX. This configuration also caches the headers of the eMails to speed up directory-listings. It might not be enabled in your build (but it sure is in the Arch-Package). Note that this does not affect OfflineIMAP in any way. It always syncs the all directories on a Server. {{ic|spoolfile}} tells Mutt which local directories to poll for new Mail. You might want to add more Spoolfiles (for example the Directories of Mailing-Lists) and maybe other things. But this is subject to the Mutt manual and beyond the scope of this document.<br />
<br />
===SMTP===<br />
Whether you use POP or IMAP to receive mail you will probably still send mail using SMTP.<br />
<br />
==== Folders ====<br />
<br />
There is basically only one important folder here: the one where all your sent e-mails will be saved.<br />
record = +Sent<br />
<br />
Gmail saves automatically sent e-mail to {{ic|+[Gmail]/Sent}}, so we do not want<br />
duplicates.<br />
unset record<br />
<br />
====Using native SMTP support====<br />
The pacman version of Mutt is also compiled with SMTP support. Just check the online manual [http://manual.cream.org/index.cgi/muttrc.5 muttrc], or {{ic|man muttrc}} for more information.<br />
<br />
For example:<br />
{{bc|1=<br />
set my_pass='mysecretpass'<br />
set my_user=myname<br />
<br />
set realname = 'Your Real Name'<br />
set from = your-email-address<br />
set use_from = yes<br />
<br />
set smtp_url=smtps://$my_user:$my_pass@smtp.domain.tld<br />
set ssl_force_tls = yes<br />
}}<br />
<br />
Note that if your SMTP credentials are the same as your IMAP credentials, then you can use those variables:<br />
<br />
{{bc|1=<br />
set smtp_url=smtps://$imap_user:$imap_pass@smtp.domain.tld<br />
}}<br />
<br />
You may need to tweak the security parameters. If you get an error like<br />
{{ic|SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol}},<br />
then your server most probably uses the SMTP instead of SMTPS.<br />
<br />
{{bc|1=<br />
set smtp_url=smtp://$imap_user:$imap_pass@smtp.domain.tld<br />
}}<br />
<br />
There is other variable that you may need to set. For example for use of STARTTLS:<br />
{{bc|1=<br />
set ssl_starttls = yes<br />
}}<br />
<br />
====External SMTP support====<br />
An external SMTP agent such as [[msmtp]], [[SSMTP]] or {{Pkg|opensmtpd}} can also be used. This section exclusively covers configuring Mutt for msmtp.<br />
<br />
Edit Mutt's configuration file or create it if unpresent:<br />
{{hc|muttrc|2=<br />
set realname='Disgruntled Kangaroo'<br />
<br />
set sendmail="/usr/bin/msmtp"<br />
<br />
set edit_headers=yes<br />
set folder=~/mail<br />
set mbox=+mbox<br />
set spoolfile=+inbox<br />
set record=+sent<br />
set postponed=+drafts<br />
set mbox_type=Maildir<br />
<br />
mailboxes +inbox +lovey-dovey +happy-kangaroos<br />
}}<br />
<br />
====Sending mails from Mutt====<br />
Now, startup {{Ic|mutt}}:<br />
<br />
You should see all the mail in {{ic|~/mail/inbox}}. Press {{ic|m}} to compose mail; it will use the editor defined by your {{Ic|EDITOR}} environment variable. If this variable is not set, you can fix it before starting Mutt:<br />
$ export EDITOR=your-favorite-editor<br />
$ mutt<br />
<br />
You should store the EDITOR value into your shell resource configuration file (such as [[bashrc]]).<br />
You can also set the editor from Mutt's configuration file:<br />
{{hc|.muttrc|2=<br />
set editor=your-favorite-editor<br />
}}<br />
<br />
For testing purposes, address the letter to yourself. After you have written the letter, save and exit the editor. You will return to Mutt, which will now show information about your e-mail. Press {{ic|y}} to send it.<br />
<br />
===Multiple accounts===<br />
<br />
Now you should have a working configuration for one account at least. You might wonder how to use several accounts, since we put everything into a single file.<br />
<br />
Well all you need is to write account-specific parameters to their respective files and source them. All the IMAP/POP3/SMTP config for each account should go to its respective folder.<br />
{{Warning|When one account is setting a variable that is not specified for other accounts, you '''must unset''' it for them, otherwise configuration will overlap and you will most certainly experience unexpected behaviour.}}<br />
<br />
Mutt can handle this thanks to one of its most powerful feature: hooks.<br />
Basically a hook is a command that gets executed before a specific action.<br />
There are several hook availables. For multiple accounts, you must use account-hooks ''and'' folder-hooks.<br />
* Folder-hooks will run a command before switching folders. This is mostly useful to set the appropriate SMTP parameters when you are in a specific folder. For instance when you are in your work mailbox and you send a e-mail, it will automatically use your work account as sender.<br />
* Account-hooks will run a command everytime Mutt calls a function related to an account, like IMAP syncing. It does not require you to switch to any folder.<br />
<br />
Hooks take two parameters:<br />
account-hook [!]regex command<br />
folder-hook [!]regex command<br />
The regex is the folder to be matched (or not if preceded by the !).<br />
The command tells what to do.<br />
<br />
Let us give a full example:<br />
<br />
{{hc|.muttrc|<nowiki><br />
## General options<br />
set header_cache = "~/.cache/mutt"<br />
set imap_check_subscribed<br />
set imap_keepalive = 300<br />
unset imap_passive<br />
set mail_check = 60<br />
set mbox_type=Maildir<br />
<br />
## ACCOUNT1<br />
source "~/.mutt/work"<br />
# Here we use the $folder variable that has just been set in the sourced file.<br />
# We must set it right now otherwise the 'folder' variable will change in the next sourced file.<br />
folder-hook $folder 'source ~/.mutt/work'<br />
<br />
## ACCOUNT2<br />
source "~/.mutt/personal"<br />
folder-hook *user@gmail.com/ 'source ~/.mutt/personal'<br />
folder-hook *user@gmail.com/Family 'set realname="Bob"'<br />
</nowiki>}}<br />
<br />
{{hc|.mutt/work|<nowiki><br />
## Receive options.<br />
set imap_user=user@gmail.com<br />
set imap_pass=****<br />
set folder = imaps://user@imap.gmail.com/<br />
set spoolfile = +INBOX<br />
set postponed = +Drafts<br />
set record = +Sent<br />
<br />
## Send options.<br />
set smtp_url=smtps://user:****@smtp.gmail.com<br />
set realname='User X'<br />
set from=user@gmail.com<br />
set hostname="gmail.com"<br />
set signature="John Doe"<br />
# Connection options<br />
set ssl_force_tls = yes<br />
unset ssl_starttls<br />
<br />
## Hook -- IMPORTANT!<br />
account-hook $folder "set imap_user=user@gmail.com imap_pass=****"<br />
</nowiki>}}<br />
<br />
Finally {{ic|.mutt/personal}} should be similar to {{ic|.mutt/work}}.<br />
<br />
Now all your accounts are set, start Mutt. To switch from one account to another, just change the folder ({{ic|c}} key). Alternatively you can use the [[#Mutt-Sidebar|sidebar]].<br />
<br />
To change folder for different mailboxes you have to type the complete address -- for IMAP/POP3 folders, this may be quite inconvenient -- let us bind some key to it.<br />
<br />
{{bc|<br />
## Shortcuts<br />
macro index,pager <f2> '<sync-mailbox><enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
macro index,pager <f3> '<sync-mailbox><enter-command>source ~/.mutt/work<enter><change-folder>!<enter>'<br />
}}<br />
<br />
With the above shortcuts (or with the sidebar) you will find that changing folders (with {{ic|c}} by default) is not contextual, ''i.e.'' it will not list the folders of the current mailbox, but of the one used the last time you changed folders. To make the behaviour more contextual, the trick is to press ''='' or ''+'' for current mailbox. You can automate this with the following macro:<br />
macro index 'c' '<change-folder>?<change-dir><home>^K=<enter>'<br />
<br />
===Passwords management===<br />
Keep in mind that writing your password in {{ic|.muttrc}} is a security risk, and it might be of your concern.<br />
The trivial way to keep your passwords safe is not writing them in the config file. Mutt will then prompt for it when needed.<br />
However, this is quiet combersome in the long run, especiallly if you have several accounts.<br />
<br />
Here follows a smart and convenient solution: all your passwords are encrypted into one file and Mutt will prompt for a passphrase on startup only. You can opt for a keyring tool (e.g. GPG, {{pkg|pwsafe}}) or an encryption tool like {{pkg|ccrypt}}, which may be more simple and straightforward to use.<br />
Since GPG is a Mutt dependency, we will use it here.<br />
<br />
First create a pair of public/private keys:<br />
gpg --gen-key<br />
If you do not understand this process have a look at [[Wikipedia:Asymmetric cryptography]].<br />
<br />
Create a file '''in a secure environment''' since it will contain your passwords for a couple of seconds:<br />
{{hc|~/.my-pwds|<nowiki><br />
set my_pw_personal = ****<br />
set my_pw_work = ****</nowiki><br />
}}<br />
{{Note|Remember that user defined variables '''must''' start with {{ic|my_}}}}<br />
<br />
Now encrypt the file:<br />
gpg -e -r 'your-name' ~/.my-pwds<br />
Note that 'your-name' must match the one you provided at the {{ic|gpg --gen-key}} step.<br />
Now you can wipe your file containing your passwords in clear:<br />
shred -xu ~/.my-pwds<br />
Back to your account dedicated files, e.g. {{ic|.mutt/muttrc}}:<br />
{{bc|1=<br />
set imap_pass=$my_pw_personal<br />
# Every time the password is needed, use $my_pw_personal variable.<br />
}}<br />
<br />
And in your {{ic|.muttrc}}, '''before''' you source any account dedicated file:<br />
{{bc|<br />
source "gpg2 -dq $HOME/.my-pwds.gpg {{ic|<nowiki>|</nowiki>}}"<br />
}}<br />
{{Note|At the end of the line above, there is no space between the pipe and the double quote.}}<br />
* The {{ic|-q}} parameter makes gpg2 quiet which prevents gpg2 output messing with Mutt interface.<br />
* The pipe {{ic|<nowiki>|</nowiki>}} at the end of a string is the Mutt syntax to tell that you want the result of what is preceeding.<br />
<br />
Explanation: when Mutt starts, it will first source the result of the password decryption, that's why it will prompt for a passphrase. Then all passwords will be stored in memory in specific variables for the time Mutt runs. Then, when a folder-hook is called, it sets the imap_pass variable to the variable holding the appropriate password. When switching accounts, the imap_pass variable will be set to another variable holding another password, etc.<br />
<br />
If you use external tools like OfflineIMAP and msmtp, you need to set up an agent (e.g. gpg-agent, see [[GnuPG#gpg-agent]]) to keep the passphrase into cache and thus avoiding those tools always prompting for it.<br />
<br />
{{Note|The previous instruction produces a mutt configuration error in the 'source' line. A quick workaround is to encrypt a file only consisting of your password, then storing the decrypted version in a variable in your muttrc.}}<br />
{{bc|<br />
echo "password" > ~/.my-pwd<br />
gpg -e -r 'your-name' ~/.my-pwd<br />
shred -xu ~/.my-pwd<br />
}}<br />
<br />
Once you have setup ~/.my-pwd.gpg, continue to editing {{ic|.muttrc}}<br />
{{bc|1=<br />
set my_pw = `gpg -dq ~/.my-pwd.gpg`<br />
set imap_pw = $my_pass<br />
}}<br />
<br />
==Advanced features==<br />
Guides to get you started with using & customizing Mutt : <br />
* [http://mutt.blackfish.org.uk/ My first Mutt] (maintained by Bruno Postle) <br />
* [http://www.therandymon.com/woodnotes/mutt/using-mutt.html The Woodnotes Guide to the Mutt Email Client] (maintained by Randall Wood)<br />
* [http://stevelosh.com/blog/2012/10/the-homely-mutt The Homely Mutt] (by Steve Losh)<br />
<br />
If you have any Mutt specific questions, feel free to ask in [[ArchChannel|the irc channel]].<br />
<br />
===E-mail character encoding===<br />
You may be concerned with sending e-mail in a decent character set (charset for short) like UTF-8. Nowadays UTF-8 is highly recommended to almost everyone.<br />
<br />
When using Mutt there is two levels where the charset must be specified:<br />
* The text editor used to write the e-mail must save it in the desired encoding.<br />
* Mutt will then check the e-mail and determine which encoding is the more apropriate according to the priority you specified in the {{ic|send_charset}} variable. Default: "us-ascii:iso-8859-1:utf-8".<br />
<br />
So if you write an e-mail with characters allowed in ISO-8859-1 (like 'résumé'), but without characters specific to Unicode, then Mutt will set the encoding to ISO-8859-1.<br />
<br />
To avoid this behaviour, set the variable in your {{ic|muttrc}}:<br />
set send_charset="us-ascii:utf-8"<br />
or even<br />
set send_charset="utf-8"<br />
<br />
The first compatible charset starting from the left will be used.<br />
Since UTF-8 is a superset of US-ASCII it does not harm to leave it in front of UTF-8, it may ensure old MUA will not get confused when seeing the charset in the e-mail header.<br />
<br />
===Printing===<br />
You can install {{AUR|muttprint}} from the [[AUR]] for a fancier printing quality.<br />
In your muttrc file, insert:<br />
set print_command="/usr/bin/muttprint %s -p {PrinterName}"<br />
<br />
===Custom mail headers===<br />
One of the greatest thing in Mutt is that you can have full control over your mail header.<br />
<br />
First, make your headers editable when you write e-mails:<br />
set edit_headers=yes<br />
<br />
Mutt also features a special function {{ic|my_hdr}} for customizing your header. Yes, it is named just like a variable, but in fact it is a function.<br />
<br />
You can clear it completely, which you ''should'' do when switching accounts with different headers, otherwise they will overlap:<br />
unmy_hdr *<br />
<br />
Other variables have also an impact on the headers, so it is wise to clear them before using {{ic|my_hdr}}:<br />
unset use_from<br />
unset use_domain<br />
unset user_agent<br />
<br />
Now, you can add any field you want -- even non-standard one -- to your header using the following syntax:<br />
my_hdr <FIELD>: <VALUE><br />
Note that <VALUE> can be the result of a command.<br />
<br />
Example:<br />
{{bc|<br />
## Extra info.<br />
my_hdr X-Info: Keep It Simple, Stupid.<br />
<br />
## OS Info.<br />
my_hdr X-Operating-System: `uname -s`, kernel `uname -r`<br />
<br />
## This header only appears to MS Outlook users<br />
my_hdr X-Message-Flag: WARNING!! Outlook sucks<br />
<br />
## Custom Mail-User-Agent ID.<br />
my_hdr User-Agent: Every email client sucks, this one just sucks less.<br />
}}<br />
<br />
===Signature block===<br />
Create a .signature in your home directory. Your signature will be appended at the end of your email.<br />
Alternatively you can specify a file in your Mutt configuration:<br />
set signature="path/to/sig/file"<br />
====Random signature====<br />
You can use fortune to add a random signature to Mutt.<br />
{{bc|$ pacman -S fortune-mod}}<br />
<br />
Create a fortune file and then add the following line to your .muttrc:<br />
{{bc|1=set signature="fortune pathtofortunefile&#124;"}}<br />
Note the pipe at the end. It tells Mutt that the specified string is not a file, but a command.<br />
<br />
===Viewing URLs & opening your favorite web browser===<br />
Your should start by creating a .mutt directory in $HOME if not done yet. There, create a file named macros. Insert the following:<br />
macro pager \cb <pipe-entry>'urlview'<enter> 'Follow links with urlview'<br />
<br />
Then install {{AUR|urlview}} from the [[AUR]].<br />
<br />
Create a .urlview in $HOME and insert the following:<br />
REGEXP (((http|https|ftp|gopher)|mailto)[.:][^ >"\t]*|www\.[-a-z0-9.]+)[^ .,;\t>">\):]<br />
COMMAND <your-browser> %s <br />
<br />
When you read an email on the pager, hitting ctrl+b will list all the urls from the email. Navigate up or down with arrow keys and hit enter on the desired url. Your browser will start and go to the selected site.<br />
<br />
Some browser will require additional arguments to work properly. For example, [[Luakit]] will close on Mutt exit. You need to fork it to background, using the {{ic|-n}} parameter:<br />
COMMAND luakit -n %s 2>/dev/null<br />
The {{ic|2>/dev/null}} is to make it quiet, i.e. to prevent useless message printing where you do not want them to.<br />
<br />
{{Note|urlview has a few deficiencies (e.g. the inability to handle certain email encodings) and is fairly feature-bare (e.g. it does not provide context for links it finds). There are a couple alternatives that do better. One, which can handle all email encodings and provides link context, is [http://www.memoryhole.net/~kyle/extract_url/ extract_url.pl]. Another, which can also provide link context but cannot handle all email encodings, is [https://aur.archlinux.org/packages.php?ID&#61;44853 urlscan]. Both are drop-in replacements for urlview, though extract_url has features which benefit from additional configuration changes.}}<br />
<br />
===Viewing HTML===<br />
It is possible to pass the html body to an external HTML program and then dump it, keeping email viewing uniform and unobtrusive. Three programs are described here: lynx, w3m and elinks.<br />
<br />
Install lynx, w3m or elinks:<br />
pacman -S lynx<br />
or<br />
pacman -S w3m<br />
or<br />
pacman -S elinks<br />
<br />
If {{ic|~/.mutt/mailcap}} does not exist you will need to create it and save the following to it.<br />
text/html; lynx -display_charset=utf-8 -dump %s; nametemplate=%s.html; copiousoutput<br />
or, in case of w3m,<br />
text/html; w3m -I %{charset} -T text/html; copiousoutput;<br />
or, in case of elinks,<br />
text/html; elinks -dump ; copiousoutput;<br />
<br />
Edit muttrc and add the following,<br />
set mailcap_path = ~/.mutt/mailcap<br />
<br />
To automatically open HTML messages in lynx, add this additional line to the muttrc:<br />
auto_view text/html<br />
<br />
The beauty of this is, instead of seeing an html body as source or being opened<br />
by a separate program, in this case lynx, you see the formatted content directly,<br />
and any url links within the email can be displayed with {{ic|Ctrl+b}}.<br />
<br />
If you receive many emails with multiple or alternate encodings Mutt may default to treating every email as html. To avoid this, add the following variable to your ~/.muttrc to have Mutt default to text when available and use w3m/lynx only when no text version is availble in the email:<br />
alternative_order text/plain text/html<br />
<br />
Some HTML mails may not display correctly in a text-based web browser. As a fallback solution, you can bind a key to open a graphical browser in such cases.<br />
The following macro will open the HTML mail selected from the attachment view in the web browser defined in the environment. (Feel free to adapt the {{ic|~/.cache/mutt/}} folder).<br />
macro attach 'V' "<pipe-entry>cat >~/.cache/mutt/mail.html && $BROWSER ~/.cache/mutt/mail.html && rm ~/.cache/mutt/mail.html<enter>"<br />
<br />
===Mutt and Vim===<br />
*To limit the width of text to 72 characters, edit your .[[vim]]rc file and add:<br />
au BufRead /tmp/mutt-* set tw=72<br />
<br />
*Another choice is to use Vim's mail filetype plugin to enable other mail-centric options besides 72 character width. Edit {{ic|~/.vim/filetype.vim}}, creating it if unpresent, and add:<br />
{{bc| <br />
augroup filetypedetect<br />
" Mail<br />
autocmd BufRead,BufNewFile *mutt-* setfiletype mail<br />
augroup END<br />
}}<br />
<br />
*To set a different tmp directory, e.g. ~/.tmp, add a line to your muttrc as follows:<br />
set tmpdir="~/.tmp"<br />
<br />
*To reformat a modified text see the Vim context help<br />
:h 10.7<br />
<br />
===Mutt and GNU nano===<br />
[[nano]] is another nice console editor to use with Mutt. <br />
<br />
To limit the width of text to 72 characters, edit your .nanorc file and add:<br />
set fill 72<br />
<br />
Also, in muttrc file, you can specify the line to start editing so that you will skip the mail header:<br />
set editor="nano +7"<br />
<br />
===Mutt and Emacs===<br />
Emacs has a ''mail'' and a ''message'' major mode.<br />
To switch to mail-mode automatically when Emacs is called from Mutt, you can add the following to your {{ic|.emacs}}:<br />
{{hc|.emacs|<nowiki><br />
;; Mutt support.<br />
(setq auto-mode-alist (append '(("/tmp/mutt.*" . mail-mode)) auto-mode-alist))<br />
</nowiki>}}<br />
<br />
If you usually run Emacs daemon, you may want Mutt to connect to it. Add this to your {{ic|.muttrc}}:<br />
{{hc|.muttrc|<nowiki><br />
set editor="emacsclient -a \"\" -t"</nowiki><br />
}}<br />
<br />
===Colors===<br />
Append sample color definitions to your .muttrc file:<br />
$ cat /usr/share/doc/mutt/samples/colors.linux >> ~/.muttrc<br />
Then adjust to your liking.<br />
The actual color each of these settings will produce depends on the colors set in your [[Xresources|~/.Xresources]] file.<br />
<br />
Alternatively, you can source any file you want containing colors (and thus act as a theme file):<br />
{{bc|<br />
source ~/.mutt/colors.zenburn<br />
}}<br />
<br />
A nice theme example:<br />
{{bc|<nowiki><br />
## Theme kindly inspired from <br />
## http://nongeekshandbook.blogspot.ie/2009/03/mutt-color-configuration.html <br />
<br />
## Colours for items in the index <br />
color index brightcyan black ~N<br />
color index brightred black ~O<br />
color index brightyellow black ~F<br />
color index black green ~T<br />
color index brightred black ~D<br />
mono index bold ~N<br />
mono index bold ~F<br />
mono index bold ~T<br />
mono index bold ~D<br />
<br />
## Highlights inside the body of a message. <br />
<br />
## URLs <br />
color body brightgreen black "(http|ftp|news|telnet|finger)://[^ \"\t\r\n]*"<br />
color body brightgreen black "mailto:[-a-z_0-9.]+@[-a-z_0-9.]+"<br />
mono body bold "(http|ftp|news|telnet|finger)://[^ \"\t\r\n]*"<br />
mono body bold "mailto:[-a-z_0-9.]+@[-a-z_0-9.]+"<br />
<br />
## Email addresses. <br />
color body brightgreen black "[-a-z_0-9.%$]+@[-a-z_0-9.]+\\.[-a-z][-a-z]+"<br />
<br />
## Header <br />
color header green black "^from:"<br />
color header green black "^to:"<br />
color header green black "^cc:"<br />
color header green black "^date:"<br />
color header yellow black "^newsgroups:"<br />
color header yellow black "^reply-to:"<br />
color header brightcyan black "^subject:"<br />
color header red black "^x-spam-rule:"<br />
color header green black "^x-mailer:"<br />
color header yellow black "^message-id:"<br />
color header yellow black "^Organization:"<br />
color header yellow black "^Organisation:"<br />
color header yellow black "^User-Agent:"<br />
color header yellow black "^message-id: .*pine"<br />
color header yellow black "^X-Fnord:"<br />
color header yellow black "^X-WebTV-Stationery:"<br />
<br />
color header red black "^x-spam-rule:"<br />
color header green black "^x-mailer:"<br />
color header yellow black "^message-id:"<br />
color header yellow black "^Organization:"<br />
color header yellow black "^Organisation:"<br />
color header yellow black "^User-Agent:"<br />
color header yellow black "^message-id: .*pine"<br />
color header yellow black "^X-Fnord:"<br />
color header yellow black "^X-WebTV-Stationery:"<br />
color header yellow black "^X-Message-Flag:"<br />
color header yellow black "^X-Spam-Status:"<br />
color header yellow black "^X-SpamProbe:"<br />
color header red black "^X-SpamProbe: SPAM"<br />
<br />
## Coloring quoted text - coloring the first 7 levels: <br />
color quoted cyan black<br />
color quoted1 yellow black<br />
color quoted2 red black<br />
color quoted3 green black<br />
color quoted4 cyan black<br />
color quoted5 yellow black<br />
color quoted6 red black<br />
color quoted7 green black<br />
<br />
## Default color definitions <br />
#color hdrdefault white green <br />
color signature brightmagenta black<br />
color indicator black cyan<br />
color attachment black green<br />
color error red black<br />
color message white black<br />
color search brightwhite magenta<br />
color status brightyellow blue<br />
color tree brightblue black<br />
color normal white black<br />
color tilde green black<br />
color bold brightyellow black<br />
#color underline magenta black <br />
color markers brightcyan black<br />
<br />
## Colour definitions when on a mono screen <br />
mono bold bold<br />
mono underline underline<br />
mono indicator reverse</nowiki><br />
}}<br />
<br />
===Index Format===<br />
<br />
Here follows a quick example to put in your {{ic|.muttrc}} to customize the Index Format, i.e. the columns displayed in the folder view.<br />
{{bc|<nowiki><br />
set date_format="%y-%m-%d %T"<br />
set index_format="%2C | %Z [%d] %-30.30F (%-4.4c) %s"</nowiki><br />
}}<br />
See the [http://www.mutt.org/doc/manual/manual-6.html Mutt Reference], {{ic|man 3 strftime}} and {{ic|man 3 printf}} for more details.<br />
<br />
====Display recipient instead of sender in "Sent" folder view====<br />
<br />
By default Mutt will display the sender in the index view. It is fine for most folders, but rather useless for the one were you store a copy of your sent e-mails since it will always display your name.<br />
<br />
The "columns" of the index can be configured through the {{ic|index_format}} variable. Its syntax is documented in the {{ic|muttrc}} man page. The values of our concern are {{ic|%t}} (recipient) and {{ic|%F}} (sender).<br />
<br />
To change the columns according to the current folder, we need to use a hook:<br />
{{hc|muttrc|<nowiki><br />
folder-hook *[sS]ent* 'set index_format="%2C | %Z [%d] %-30.30t (%-4.4c) %s"'<br />
folder-hook ! *[sS]ent* 'set index_format="%2C | %Z [%d] %-30.30F (%-4.4c) %s"'<br />
</nowiki>}}<br />
<br />
The exclamation mark means ''everything that does not match the following regex''. Of course you can change the index_format following you taste, and the regular expression if the folder does not have ''Sent'' not ''sent'' in its name.<br />
<br />
====Variable column width====<br />
<br />
If you rezise the window, the subject might get truncated while there is still unused space left for some fields, like for the sender.<br />
You can get the maximum column of your terminal (i.e. the width) using a shell call to {{ic|tput cols}}. With this value you can set a percentage of the width to fields like Sender and Subject.<br />
<br />
Example using the above folder-hook and a sidebar width of 24:<br />
{{hc|muttrc|<nowiki><br />
## From field gets 30% of remaining space, Subject gets 70%.<br />
## Remaining space is the total width minus the other fields (35), minus the sidebar (24)<br />
set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`<br />
set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`<br />
<br />
folder-hook .*[sS]ent.* 'set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}t (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
folder-hook ! .*[sS]ent.* 'set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}F (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
</nowiki><br />
}}<br />
<br />
Unfortunately, the above example suffers from one caveat: the {{ic|my_col_*}} variables get computed one time only, on first start. So if you want it to refresh automatically, we need to set the variable in a hook. Sadly there is no hook for window resizing, but you can still use the {{ic|folder-hook}} so that a simple folder switch suffice to recompute the view.<br />
{{hc|muttrc|<nowiki><br />
folder-hook .*[sS]ent.* 'set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`; set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`; set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}t (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
folder-hook ! .*[sS]ent.* 'set my_col_from = `echo $((30 * ($(tput cols)-35-24) / 100))`; set my_col_subject = `echo $((70 * ($(tput cols)-35-24) / 100))`; set index_format="%2C | %Z [%d] %-$my_col_from.${my_col_from}F (%-4.4c) %-$my_col_subject.${my_col_subject}s"'<br />
</nowiki><br />
}}<br />
<br />
===Contact management===<br />
<br />
====Address aliases====<br />
''Aliases'' is the way Mutt manages contacts.<br />
An alias is '''nickname [longname] <address>'''.<br />
* The '''nickname''' is what you will type in Mutt to get your contact address. One word only, and should be easy to remember.<br />
* The '''longname''' is optional. It may be several words.<br />
* An '''<address>''' must be in a valid form (i.e. with an {{ic|@}}).<br />
<br />
It is quite simple indeed. Add this to {{ic|.muttrc}}:<br />
{{bc|1=<br />
set alias_file = "~/.mutt/aliases"<br />
set sort_alias = alias<br />
set reverse_alias = yes<br />
source $alias_file<br />
}}<br />
<br />
Explanation:<br />
* {{ic|alias_file}} is the file where the information is getting stored when you add an alias from within Mutt.<br />
* {{ic|sort_alias}} specifies which field to use to sort the alias list when displayed in Mutt. Possible values: alias, address.<br />
* {{ic|reverse_alias}} sorts in reverse order if set to yes.<br />
* {{ic|source $alias_file}} tells Mutt to read aliases on startup. Needed for auto-completion.<br />
<br />
Now all you have to do when prompted {{ic|To:}} is writing the alias instead of the full address. The beauty of it is that you can auto-complete the alias using {{ic|Tab}}.<br />
Autocompleting a wrong or an empty string will display the full list. You can select the alias as usual, or by typing its index number.<br />
<br />
There is two ways to create aliases:<br />
* From Mutt, press {{ic|a}} when an e-mail of the targetted person if selected.<br />
* Edit the alias_file manually. The syntax is really simple:<br />
{{bc|<br />
alias nickname Long Name <my-friend@domain.tld><br />
}}<br />
<br />
====Abook====<br />
<br />
{{pkg|abook}} is a stand-alone program dedicated to contact management. It uses a very simple text-based interface and contacts are stored in a plain text, human-readable database. Besides the desired contact properties are extensible (birthday, address, fax, and so on).<br />
<br />
Abook is specifically designed to be interfaced with Mutt, so that it can serve as a full, more featured replacement of Mutt internal aliases. If you want to use Abook instead of aliases, remove the aliases configuration in {{ic|.muttrc}} and add this:<br />
<br />
{{hc|muttrc|<nowiki><br />
## Abook<br />
set query_command= "abook --mutt-query '%s'"<br />
macro index,pager a "<pipe-message>abook --add-email-quiet<return>" "Add this sender to Abook"<br />
bind editor <Tab> complete-query<br />
</nowiki><br />
}}<br />
<br />
See the man pages {{ic|abook}} and {{ic|abookrc}} for more details and a full configuration sample.<br />
<br />
===Request IMAP mail retrieval manually===<br />
If you do not want to wait for the next automatic IMAP fetching (or if you did not enable it), you might want to fetch mails manually.<br />
There is a mutt command {{ic|imap-fetch-mail}} for that.<br />
Alternatively, you could bind it to a key:<br />
bind index "^" imap-fetch-mail<br />
<br />
===Avoiding slow index on large (IMAP) folders due to coloring===<br />
<br />
Index highlighting by regex is nice, but can lead to slow folder viewing if your regex checks the body of the message.<br />
<br />
Use folder-hook for only highlighting in for example the inbox (if you manage to empty your mailbox effiently):<br />
<br />
folder-hook . 'uncolor index "~b \"Hi Joe\" ~R !~T !~F !~p !~P"'<br />
folder-hook ""!"" 'color index brightyellow black "~b \"Hi Joe\" ~N !~T !~F !~p !~P"'<br />
<br />
===Speed up folders switch===<br />
Add this to your {{ic|.muttrc}}:<br />
{{bc|1=<br />
set sleep_time = 0<br />
}}<br />
<br />
===Use Mutt to send mail from command line===<br />
Man pages will show all available commands and how to use them, but here are a couple of examples. You could use Mutt to send alerts, logs or some other system information, triggered by login through .bash_profile, or as a regular cron job.<br />
<br />
Send a message:<br />
mutt -s "Subject" somejoeorjane@someserver.com < /var/log/somelog<br />
<br />
Send a message with attachment:<br />
mutt -s "Subject" somejoeorjane@someserver.com -a somefile < /tmp/sometext.txt<br />
<br />
===Composing HTML e-mails===<br />
<br />
Since Mutt has nothing of a WYSIWIG client, HTML is quite straightforward, and you can do much more than with all WYSIWIG mail clients around since you edit the source code directly.<br />
Simply write your mail using HTML syntax. For example:<br />
{{bc|<nowiki><br />
This is normal text<br><br />
<b>This is bold text</b></nowiki><br />
}}<br />
Now before sending the mail, use the {{ic|edit-type}} command (default shortcut {{ic|Ctrl+t}}), and replace {{ic|text/plain}} by {{ic|text/html}}.<br />
<br />
{{Note|HTML e-mails are regarded by many people as useless, cumbersome, and subject to reading issues. Mutt can read HTML mails with a text browser like w3m or lynx, but it has clearly no advantage over a plain-text e-mail. You should avoid writing HTML e-mails when possible.}}<br />
<br />
===How to display another email while composing===<br />
A common complaint with Mutt is that when composing a new mail (or reply), you cannot open another mail (i.e. for checking with another correspondent) without closing the current mail (postponing). The following describes a solution:<br />
<br />
First, fire up Mutt as usual. Then, launch another terminal window. Now start a new Mutt with <br />
mutt -R<br />
This starts Mutt in read-only mode, and you can browse other emails at your convenience. It is strongly recommended to always launch a second Mutt in read-only mode, as conflicts will easily arise otherwise.<br />
<br />
Now, this solution calls for a bit of typing, so we would like to automate this. The following works with [[Awesome]], in other WM's or DE's similar solutions are probably available: just google how to add a key binding, and make the desired key execute <br />
$TERM -e mutt -R <br />
where $TERM is your terminal.<br />
<br />
As for Awesome: edit your rc.lua, and add the following on one of the first lines, after terminal = "yourTerminal" etc.<br />
mailview = terminal .. " -e mutt -R"<br />
This automatically uses your preferred terminal, ".." is concatenation in Lua. Note the space before -e.<br />
<br />
Then add the following inside --{{{ Key bindings<br />
awful.key({ modkey, }, "m", function() awful.util.spawn(mailview) end),<br />
<br />
Omit the final comma if this is the last line. You can, of course use another key than "m". Now, save&quit, and check your syntax with <br />
awesome -k<br />
If this is good, restart awesome and give it a try!<br />
<br />
Now, a usage example: Launch Mutt as usual. Start a new mail, and then press "Mod4"+"m". This opens your mailbox in a new terminal, and you can browse around and read other emails. Now, a neat bonus: exit this read-only-Mutt with "q", and the terminal window it created disappears!<br />
<br />
===Archive treated e-mails===<br />
When you read an e-mail, you have four choices: Answer it, Flag it, Archive it or Delete it. If you have this in mind, you can keep your inbox slim and fit with this macro (set up for Gmail):<br />
<br />
macro index \' "<tag-pattern>~R !~D !~F<enter>\<br />
<tag-prefix><save-message>+[Gmail]/All <enter>" \<br />
"Archive"<br />
<br />
===Mutt-Sidebar===<br />
<br />
The vanilla Mutt does not feature a sidebar unlike most MUAs. If you miss it, you can install {{Aur|mutt-sidebar}} from the AUR which features a patch for a list of folders on the left side of the Mutt window.<br />
<br />
For a while there has been several different patches for the sidebar. Since the late 2000's, it seems like the main patch is maintained at [http://www.lunar-linux.org/mutt-sidebar/ Lunar Linux]. See the documentation there. Note that the patch also updates the {{ic|muttrc}} man page, so have a look at the {{ic|sidebar_*}} sections.<br />
<br />
You can choose to display the sidebar on startup, or to prompt it manually with a key:<br />
{{bc|<nowiki><br />
set sidebar_visible = yes<br />
macro index b '<enter-command>toggle sidebar_visible<enter><refresh>'<br />
macro pager b '<enter-command>toggle sidebar_visible<enter><redraw-screen>'<br />
</nowiki>}}<br />
<br />
You also probabaly need some shortcuts to navigate in the bar:<br />
{{bc|<nowiki><br />
# Ctrl-n, Ctrl-p to select next, previous folder.<br />
# Ctrl-o to open selected folder.<br />
bind index,pager \CP sidebar-prev<br />
bind index,pager \CN sidebar-next<br />
bind index,pager \CO sidebar-open<br />
</nowiki>}}<br />
<br />
{{Note|You ''must'' set the {{ic|mailboxes}} variables or the {{ic|imap_check_subscribed}} to tell the sidebar which folder should be displayed. See the [[#mailboxes|mailboxes]] section.}}<br />
<br />
If you use the {{ic|imap_check_subscribed}} option to list all your folders, they will appear in an uncontrollable order in the sidebar. Fix it with<br />
set sidebar_sort = yes<br />
Note that with the {{ic|mailboxes}} option, folders appear in the order they were set to {{ic|mailboxes}} if you do not use the {{ic|sidebar_sort}} option.<br />
<br />
If you have trouble with truncated names, set the option<br />
set sidebar_shortpath = yes<br />
<br />
Finally, you may want to add a separator between different mailboxes. The sidebar patch does not currently provide any kind of separator option. A simple (and dirty) workaround is to add a fake folder to the list of folders:<br />
mailboxes "+-- My mailbox -----------"<br />
The dashes are not required, they are here just for fancy output.<br />
It will also work if you used the {{ic|imap_check_subscribed}} option.<br />
If you chose to sort the folders, the separator will not appear in the correct place, so an even more dirty workaround is to add an 'A' in front of the name. Note that punctuation is ignored during sorting.<br />
mailboxes "+A-- My mailbox -----------"<br />
<br />
===Migrating mails from one computer to another===<br />
In case you are transfering your mails to a new machine (copy&paste), you probably need to delete the header cache (a file or folder like {{ic|~/.cache/mutt}} if you followed the above configuration) to make Mutt able to read your migrated E-Mails. Otherwise Mutt may freeze.<br />
<br />
Note that if you had a folder created for you header cache, all mailboxes will have their own cache file, so you can delete caches individually without having to remove everything.<br />
<br />
=== Filtering the message view ===<br />
<br />
You can restrict the view to e-mails matching a pattern and specific properties with the {{ic|limit}} command (default shortcut: {{ic|l}}).<br />
<br />
To view all e-mails containing "foo" in the header, simply write "foo" and you are done. To remove the filter, use the "all" keyword.<br />
<br />
To view all flagged messages, use<br />
~F<br />
To view all unread messages, use<br />
~U<br />
<br />
All possible patterns are listed in the [http://www.mutt.org/doc/manual/manual-4.html#ss4.2 official manual].<br />
<br />
=== Display the index above the pager view ===<br />
<br />
Set the following variable in your {{ic|muttrc}}:<br />
set pager_index_lines=10<br />
<br />
==Troubleshooting==<br />
<br />
===Backspace does not work in Mutt===<br />
This is a common problem with some xterm-like terminals.<br />
Two solutions:<br />
* Either rebind the key in {{ic|.muttrc}}<br />
bind index,pager ^? previous-page<br />
Note that {{ic|^?}} is one single character representing backspace in [[wikipedia:Caret_notation|caret notation]]. To type in Emacs, use {{ic|Ctrl+q Backspace}}, in Vim {{ic|Ctrl+v Backspace}}.<br />
<br />
* Or fix your terminal:<br />
$ infocmp > termbs.src<br />
Edit {{ic|termbs.src}} and change {{ic|1= kbs=^H}} to {{ic|1= kbs=\177}}, then:<br />
$ tic -x termbs.src<br />
<br />
===Android's default MUA receives empty e-mail with attachment "Unknown.txt"===<br />
<br />
This is because Mutt adds 'Content-Disposition' line to every e-mail header. This line is actually correct, the issue comes from Android 2 MUA misinterpreting it. This bug seems to be fixed in the Android 4 MUA.<br />
There is a patched version for Android available in the AUR. Installing {{AUR|mutt-android-patch}} will fix the issue.<br />
<br />
===The ''change-folder'' function always prompt for the same mailbox ===<br />
<br />
This is not a bug, this is actually an intended behaviour. See the [[#Multiple accounts|multiple accounts section]] for a workaround.<br />
<br />
===I cannot change folder when using Mutt read-only (Mutt -R)===<br />
<br />
This is certainly because you are use are using macros like this one:<br />
macro index,pager <f2> '<sync-mailbox><enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
This macro tells Mutt to sync (which is a write operation) before switching.<br />
Either use the [[#Mutt-Sidebar|sidebar]] or set another macro:<br />
macro index,pager <f3> '<enter-command>source ~/.mutt/personal<enter><change-folder>!<enter>'<br />
<br />
== Documentation ==<br />
<br />
Newcomers may find it quite hard to find help for Mutt. Actually most of the topics are covered in the official documentation. We urge you to read it.<br />
<br />
* [http://www.mutt.org/doc/manual/ The official manual]. The stock {{pkg|mutt}} package for Arch Linux also installs the HTML and plain text manual at {{ic|/usr/share/doc/mutt/}}.<br />
* The {{ic|mutt}} and {{ic|muttrc}} man pages.<br />
<br />
== See also ==<br />
* [http://www.mutt.org/ The official Mutt website]<br />
* [http://wiki.mutt.org/ The Mutt wiki]<br />
* [http://pbrisbin.com/posts/two_accounts_in_mutt/ Brisbin's great guide on how to setup different IMAP accounts with Mutt, offlineimap, msmtp]<br />
* [http://home.roadrunner.com/~computertaijutsu/mutt.html A Quick Guide to Mutt]<br />
* [http://pyropus.ca/software/getmail/configuration.html#running Documentation on Configuring Getmail with rcfiles]<br />
* [http://stevelosh.com/blog/2012/10/the-homely-mutt/ Steve Losh on Mutt, offlineimap, msmtp, notmuch (gmail focussed)]<br />
* [http://www.muttrcbuilder.org/ muttrc builder]</div>Kevr