“Netrc” files are a de facto standard. They look like this:
machine mymachine login myloginname password mypassword port myport
The machine is the server (either a DNS name or an IP address).
It’s known as :host in auth-source-search queries.
The port is the connection port or protocol. It’s known as
:port in auth-source-search queries.
The user is the user name. It’s known as :user in
auth-source-search queries. You can also use login and
account.
Matching entries are usually used in the order they appear, so placing the most specific entries first in the file is a good idea. For instance:
machine example.com login foobar password geheimnis port smtp machine example.com login foobar password hemmelig
Here we’re using one password for the smtp service, and a
different one for all the other services.
You can also use this file to specify client certificates to use when setting up TLS connections. The format is:
machine mymachine port myport key key cert cert
key and cert are filenames containing the key and
certificate to use respectively. In order to make network connections
use them automatically, either pass :client-certificate t to
open-network-stream, or customize
network-stream-use-client-certificates to t.
You can use spaces inside a password or other token by surrounding the token with either single or double quotes.
You can use apostrophes inside a password or other token by
surrounding it with double quotes, e.g., "he'llo". Similarly you
can use double quotes inside a password or other token by surrounding
it with apostrophes, e.g., 'he"llo'. You can’t mix both (so a
password or other token can’t have both apostrophes and double quotes).
All this is optional. You could just say (but we don’t recommend it, we’re just showing that it’s possible)
password mypassword
to use the same password everywhere. Again, DO NOT DO THIS or you will be pwned as the kids say.
“Netrc” files are usually called .authinfo or .netrc; nowadays .authinfo seems to be more popular and the auth-source library encourages this confusion by accepting both, as you’ll see later.
If you have problems with the search, set auth-source-debug to
'trivia and see what host, port, and user the library is
checking in the *Messages* buffer. Ditto for any other
problems, your first step is always to see what’s being checked. The
second step, of course, is to write a blog entry about it and wait for
the answer in the comments.
You can customize the variable auth-sources. The following may
be needed if you are using an older version of Emacs or if the
auth-source library is not loaded for some other reason.
(require 'auth-source) ;; probably not necessary (customize-variable 'auth-sources) ;; optional, do it once
The auth-sources variable tells the auth-source library where
your netrc files, Secret Service API collection items, or your
password store live for a particular host and protocol. While you can
get fancy, the default and simplest configuration is:
;;; old default: required :host and :port, not needed anymore
(setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t)))
;;; mostly equivalent (see below about fallbacks) but shorter:
(setq auth-sources '((:source "~/.authinfo.gpg")))
;;; even shorter and the default:
(setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc"))
;;; use the Secrets API Login collection
;;; (see Secret Service API)
(setq auth-sources '("secrets:Login"))
;;; use pass (~/.password-store)
;;; (see The Unix password store)
(auth-source-pass-enable)
;;; JSON data in format [{ "machine": "SERVER",
;;; "login": "USER", "password": "PASSWORD" }...]
(setq auth-sources '("~/.authinfo.json.gpg"))
By adding multiple entries to auth-sources with a particular
host or protocol, you can have specific netrc files for that host or
protocol. Usually this is unnecessary but may make sense if you have
shared netrc files or some other unusual setup (90% of Emacs users
have unusual setups and the remaining 10% are really unusual).
Here’s a mixed example using two sources:
(setq auth-sources '((:source (:secrets default)
:host "myserver" :user "joe")
"~/.authinfo.gpg"))
If you don’t customize auth-sources, you’ll have to live with
the defaults: the unencrypted netrc file ~/.authinfo will be
used for any host and any port.
If that fails, any host and any port are looked up in the netrc file ~/.authinfo.gpg, which is a GnuPG encrypted file (see GnuPG and EasyPG Assistant Configuration).
Finally, the unencrypted netrc file ~/.netrc will be used for any host and any port.
The typical netrc line example is without a port.
machine YOURMACHINE login YOU password YOURPASSWORD
This will match any authentication port. Simple, right? But what if there’s a SMTP server on port 433 of that machine that needs a different password from the IMAP server?
machine YOURMACHINE login YOU password SMTPPASSWORD port 433 machine YOURMACHINE login YOU password GENERALPASSWORD
If you wish to specify a particular SMTP authentication method to use
with a machine, you can use the smtp-auth keyword.
See Authentication in Emacs SMTP Library,
for available methods.
For url-auth authentication (HTTP/HTTPS), you need to put this in your netrc file:
machine yourmachine.com:80 port http login testuser password testpass
This will match any realm and authentication method (basic or digest) over HTTP. HTTPS is set up similarly. If you want finer controls, explore the url-auth source code and variables.
For Tramp authentication, use:
machine yourmachine.com port scp login testuser password testpass
Note that the port denotes the Tramp connection method. When you don’t use a port entry, you match any Tramp method, as explained earlier. Since Tramp has about 88 connection methods, this may be necessary if you have an unusual (see earlier comment on those) setup.
The netrc format is directly translated into JSON, if you are into that sort of thing. Just point to a JSON file with entries like this:
[
{ "machine": "yourmachine.com", "port": "http",
"login": "testuser", "password": "testpass" }
]