@menu
* Connecting:: Ways of connecting to an IRC server.
-* SASL:: Authenticating via SASL
+* SASL:: Authenticating via SASL.
* Sample Configuration:: An example configuration file.
* Integrations:: Integrations available for ERC.
* Options:: Options that are available for ERC.
+
+@detailmenu
+--- Detailed Node Listing ---
+
+Integrations
+
+* URL:: Opening IRC URLs in ERC.
+* auth-source:: Retrieving auth-source entries with ERC.
+
+@end detailmenu
@end menu
@node Connecting
parameters, and some, like @code{client-certificate}, will just be
@code{nil}.
-@anchor{ERC client-certificate}
+@anchor{client-certificate}
To use a certificate with @code{erc-tls}, specify the optional
@var{client-certificate} keyword argument, whose value should be as
described in the documentation of @code{open-network-stream}: if
@xref{Help for users,,,auth, Emacs auth-source Library}, for more on the
@file{.authinfo}/@file{.netrc} backend of @code{auth-source}.
+For other uses of auth-source throughout ERC, @pxref{auth-source,
+ERC's auth-source integration}.
@end defun
@subheading Server
You can manually set another nickname with the /NICK command.
@end defopt
-@anchor{ERC username}
+@anchor{username parameter}
@subheading User
-@cindex user
+@cindex username parameter
@defun erc-compute-user &optional user
Determine a suitable value to send as the first argument of the
a string abiding by the rules of the network.
@end defopt
+@anchor{password parameter}
+@anchor{server password}
+@cindex password, server
@subheading Password
-@cindex password
+
+This parameter was traditionally meant to specify a @dfn{server
+password} to be sent along with the IRC @samp{PASS} command. However,
+such passwords aren't widely used. Instead, networks typically expect
+them, when present, to convey other authentication information. In
+the case of account-services (a.k.a., ``NickServ'') credentials, this
+typically involves a special syntax, such as @samp{myuser:mypass}.
+IRC bouncers often do something similar but include a pre-configured
+network-ID component, for example, @samp{bncuser/mynet:bncpass}.
+
+In general, if you have @emph{not} been asked by your network or
+bouncer to specify a repurposed server password, you should instead
+consider setting up @samp{services} or, preferably, @samp{sasl}, both
+ERC modules (@pxref{Modules}). In addition to performing
+network-account authentication, these obviate the need for this
+parameter completely, although both can optionally borrow it for their
+own purposes. (@xref{SASL, SASL in ERC}.)
@defopt erc-prompt-for-password
If non-@code{nil} (the default), @kbd{M-x erc} and @kbd{M-x erc-tls}
@noindent
If you prefer, you can set this option to @code{nil} and use the
-@code{auth-source} mechanism to store your password. For instance, if
-the option @code{auth-sources} contains @file{~/.authinfo}, put
-something like the following in that file:
-
-@example
-machine irc.example.net login mynick password sEcReT
-@end example
-
-@noindent
-For server passwords, that is, passwords sent for the IRC @samp{PASS}
-command, the @samp{host} field (@w{@code{machine irc.example.net}} in
-the above example)
-corresponds to the @var{server} parameter used by @code{erc} and
-@code{erc-tls}. Unfortunately, specifying a network, like
-@samp{Libera.Chat}, or a specific network server, like
-@samp{platinum.libera.chat}, won't normally work for looking up a server
-password because such information isn't available during opening
-introductions. (Actually, ERC @emph{can} find entries with arbitrary
-@samp{host} values for any context, including server passwords, but
-that requires customizing the more advanced options below.)
-
-If ERC can't find a suitable server password, it will just skip the IRC
-@samp{PASS} command altogether, something users may want when using
-CertFP or engaging NickServ via ERC's ``services'' module. If that is
-what you'd like to do, you can also customize the option
-@code{erc-auth-source-server-function} to @code{nil} to skip
-server-password lookup for all servers. Note that some networks and
-IRCds may accept account-services authentication via server password
-using the nonstandard @samp{mynick:sEcReT} convention.
-
-As just mentioned, you can also use @code{auth-source} to authenticate
-to account services the traditional way, through a bot called
-@samp{NickServ}. To tell ERC to do that, set
-@code{erc-use-auth-source-for-nickserv-password} to @code{t}. For
-these and most other queries, entries featuring custom identifiers and
-networks are matched first, followed by network-specific servers and
-dialed endpoints (typically, the @var{server} argument passed to
-@code{erc}). The following netrc-style entries appear in order of
-precedence:
-
-@example
-machine Libera/cellphone login MyNick password sEcReT
-machine Libera.Chat login MyNick password sEcReT
-machine zirconium.libera.chat login MyNick password sEcReT
-machine irc.libera.chat login MyNick password sEcReT
-@end example
-
-@noindent
-Remember that field labels vary per backend, so @samp{machine} (in
-netrc's case) maps to auth-source's generalized notion of a host,
-hence the @samp{:host} keyword property. Also, be sure to mind the
-syntax of your chosen backend medium. For example, always quote
-channel names in a netrc file.
-
-If this all seems overly nuanced or just plain doesn't appeal to you,
-see options @code{erc-auth-source-services-function} and friends, described
-below. These let you query auth-source your way. Most users can
-simply ignore the passed-in arguments and get by with something like
-the following:
-
-@lisp
-(defun my-fancy-auth-source-func (&rest _)
- (let* ((host (read-string "host: " nil nil "default"))
- (pass (auth-source-pick-first-password :host host)))
- (if (and pass (string-search "libera" host))
- (concat "MyNick:" pass)
- pass)))
-@end lisp
-
-Lastly, ERC also consults @code{auth-source} to find ``keys'' that may
-be required by certain channels you join. When modifying a
-traditional @code{auth-source} entry for this purpose, put the channel
-name in the @samp{user} field (for example, @samp{login "#fsf"}, in
-netrc's case). The actual key goes in the @samp{password} (or
-@samp{secret}) field.
-
-@noindent
-For details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
-
-@anchor{ERC auth-source functions}
-@defopt erc-auth-source-server-function
-@end defopt
-@defopt erc-auth-source-services-function
-@end defopt
-@defopt erc-auth-source-join-function
-
-ERC calls these functions with keyword arguments recognized by
-@code{auth-source-search}, namely, those deemed most relevant to the
-current context, if any. For example, with NickServ queries,
-@code{:user} is the ``desired'' nickname rather than the current one.
-Generalized names, like @code{:user} and @code{:host}, are always used
-over back-end specific ones, like @code{:login} or @code{:machine}.
-ERC expects a string to use as the secret or @code{nil}, if the search
-fails.
-
-@findex erc-auth-source-search
-The default value for all three options is the function
-@code{erc-auth-source-search}. It tries to merge relevant contextual
-parameters with those provided or discovered from the logical connection
-or the underlying transport. Some auth-source back ends may not be
-compatible; netrc, plstore, json, secrets, and pass are currently
-supported.
-@end defopt
+auth-source facility to retrieve a server password, although hitting
+@kbd{RET} at the prompt may achieve the same effect.
+@xref{auth-source, ERC's auth-source integration}, for more.
@subheading Full name
@end defopt
-@subheading ID
@anchor{Network Identifier}
+@subheading ID
ERC uses an abstract designation, called @dfn{network context
identifier}, for referring to a connection internally. While normally
uppercase with colon seps (@samp{DE:AD:BE:EF}). These days, there's
usually a @samp{CERT ADD} command offered by NickServ that can
register you automatically if you issue it while connected with a
-client cert. (@pxref{ERC client-certificate}).
+client cert. @xref{client-certificate}.
Additional considerations:
@enumerate
This should be your network account username, typically the same one
registered with nickname services. Specify this when your NickServ
login differs from the @code{:user} you're connecting with.
-(@pxref{ERC username})
+@xref{username parameter}.
@end defopt
@defopt erc-sasl-password
-As noted elsewhere, the @code{:password} parameter for @code{erc-tls}
-was originally intended for traditional ``server passwords,'' but these
-aren't really used any more. As such, this option defaults to
-borrowing that parameter for its own uses, thus allowing you to call
-@code{erc-tls} with @code{:password} set to your NickServ password.
+As noted elsewhere, the entry-point @code{:password} param was
+originally intended for traditional ``server passwords,'' but these
+aren't really used any more (@pxref{password parameter}). As such,
+this option defaults to borrowing that parameter for its own uses,
+thus allowing you to call @code{erc-tls} with @code{:password} set to
+your NickServ password.
You can also set this to a nonemtpy string, and ERC will send that
when needed, no questions asked. Or, if you'd rather use auth-source,
set @code{erc-sasl-auth-source-function} to a function, and ERC will
-perform an auth-source query instead. As last resort in all cases,
-ERC will prompt you for input.
+perform an auth-source query instead. In all cases, ERC will prompt
+you for input as a last resort.
Lastly, if your mechanism is @code{ecdsa-nist256p-challenge}, this
option should instead hold the file name of your key.
@end defopt
+@anchor{SASL auth-source function}
@defopt erc-sasl-auth-source-function
This is nearly identical to the other ERC @samp{auth-source} function
-options (@pxref{ERC auth-source functions}) except that the default
-value here is @code{nil}, meaning you have to set it to something like
+options (@pxref{auth-source functions}) except that the default value
+here is @code{nil}, meaning you have to set it to something like
@code{erc-auth-source-search} for queries to be performed. For
convenience, this module provides the following as a possible value:
@subheading Troubleshooting
-@strong{Warning:} ERC's SASL offering is currently limited by a lack
-of support for proper IRCv3 capability negotiation. In most cases,
-this shouldn't affect your ability to authenticate.
+First and foremost, please know that ERC's SASL offering is currently
+limited by a lack of support for proper IRCv3 capability negotiation.
+In most cases, this shouldn't affect your ability to authenticate.
If you're struggling, remember that your SASL password is almost
always your NickServ password. When in doubt, try restoring all SASL
@section Integrations
@cindex integrations
-@subheading URL
+@menu
+* auth-source:: Retrieving auth-source entries with ERC.
+@end menu
+
+@anchor{URL}
+@subsection URL
+@cindex URL
+
For anything to work, you'll want to set @code{url-irc-function} to
@code{url-irc-erc}. As a rule of thumb, libraries relying directly on
@code{url-retrieve} should be fine out the box from Emacs 29.1 onward.
On older versions of Emacs, you may need to @code{(require 'erc)}
-beforehand. @pxref{Retrieving URLs,,, url, URL}.
+beforehand. @xref{Retrieving URLs,,, url, URL}.
For other apps and libraries, such as those relying on the
higher-level @code{browse-url}, you'll oftentimes be asked to specify
@noindent
Users on Emacs 28 and below may need to use @code{browse-url} instead.
+@node auth-source
+@subsection auth-source
+@cindex auth-source
+
+You can configure ERC to use the built-in auth-source library for
+looking up passwords. @xref{Top,,auth-source, auth, Emacs auth-source
+Library}, for general info on setting up various backends, but keep in
+mind that some of these may not be compatible. Those currently
+supported are netrc, plstore, json, secrets, and pass. To get started
+with the default backend, netrc, put a line like the following in your
+@file{~/.authinfo.gpg} (or any file named in the option
+@code{auth-sources}):
+
+@example
+machine irc.example.net login mynick password sEcReT
+@end example
+
+@subsubheading Server Passwords
+When retrieving passwords to accompany the IRC @samp{PASS} command
+(@pxref{password parameter}), ERC asks auth-source to match the
+@var{server} parameter of @code{erc-tls} against each entry's
+@samp{host} field (@w{@code{machine irc.example.net}} in the above
+example). Unfortunately, specifying a network, like
+@samp{Libera.Chat}, or a specific network server, like
+@samp{platinum.libera.chat}, won't normally work for looking up a
+server password because that information isn't available during
+opening introductions. (Actually, ERC @emph{can} find entries with
+arbitrary @samp{host} values for any context, including server
+passwords, but that requires customizing the more advanced options
+below.)
+
+If ERC can't find a suitable server password, it will just skip the
+IRC @samp{PASS} command altogether, something users may want when
+using CertFP or engaging NickServ via ERC's @code{services} module.
+If that appeals to you, consider customizing the option
+@code{erc-auth-source-server-function} to @code{nil} to skip
+server-password lookup for all servers. Note that some networks and
+IRCds may accept account-services authentication via server password.
+Also, some ERC modules may commandeer the @code{erc-tls}
+@var{password} parameter for their own ends, which likely don't
+involve a server password.
+
+@subsubheading The @samp{services} module
+You can use auth-source to authenticate to account services the
+traditional way through a bot called @samp{NickServ}. To do so, add
+@code{services} to @code{erc-modules} and set the option
+@code{erc-use-auth-source-for-nickserv-password} to @code{t}. After
+that, expect the @samp{user} parameter in relevant auth-source queries
+to be your current nickname.
+
+Most of the time, a query's precise contextual details (such as
+whether a nick was granted or forcibly assigned) shouldn't affect how
+you define entries in your backend. However, if something isn't quite
+working, you may want to investigate the interplay between the option
+@code{erc-nickserv-identify-mode} and account services. In
+particular, if you find yourself facing nicks suffixed with an
+@code{erc-nick-uniquifier} (the infamous @samp{`}), check that the
+network's entry in @code{erc-nickserv-alist} is up to date, and do let
+us know if something's off (@pxref{Getting Help and Reporting Bugs}).
+Of course, if you've had your fill of fiddling with this module,
+consider switching to SASL for what's likely a more consistent
+auth-source experience. (@xref{SASL}.)
+
+@subsubheading Default query behavior
+When preparing entries for your backend, it may help to get a feel for
+how ERC and its modules conduct searches, especially when exploring a
+new context, such as channel keys. (Hint: in such situations, try
+temporarily setting the variable @code{auth-source-debug} to @code{t}
+and checking @samp{*Messages*} periodically for insights into how
+auth-source is operating.) Overall, though, ERC tries to be
+consistent in performing queries across various authentication
+contexts. Here's what to expect with respect to the @samp{host}
+field, which, by default, most heavily influences the fate of a query:
+
+@enumerate
+@item
+entries featuring custom identifiers and networks are matched first
+(@pxref{Network Identifier})
+@item
+followed by network-specific servers
+@item
+and, finally, dialed endpoints (typically the @var{server} argument
+passed to @code{erc-tls})
+@end enumerate
+
+@noindent
+The following netrc-style entries appear in order of precedence:
+
+@example
+machine Libera/cellphone login MyNick password sEcReT
+machine Libera.Chat login MyNick password sEcReT
+machine zirconium.libera.chat login MyNick password sEcReT
+machine irc.libera.chat login MyNick password sEcReT
+@end example
+
+@noindent
+Remember that field labels vary per backend, so @samp{machine} (in
+netrc's case) maps to auth-source's generalized notion of a host,
+hence the @samp{:host} keyword parameter to @code{auth-source-search}.
+Also, be sure to mind the syntax of your chosen backend medium. For
+example, always quote channel names in a netrc file.
+
+Lastly, if this all seems overly nuanced or just plain doesn't appeal
+to you, please see options @code{erc-auth-source-services-function}
+and friends, described just below.
+
+@subsubheading Custom query functions
+These let you query auth-source your way. Most users can
+simply ignore the passed-in arguments and get by with something like
+the following:
+
+@lisp
+(defun my-fancy-auth-source-func (&rest _)
+ (let* ((host (read-string "host: " nil nil "default"))
+ (pass (auth-source-pick-first-password :host host)))
+ (if (and pass (string-search "libera" host))
+ (concat "MyNick:" pass)
+ pass)))
+@end lisp
+
+@anchor{auth-source functions}
+@defopt erc-auth-source-server-function
+@end defopt
+@defopt erc-auth-source-services-function
+@end defopt
+@defopt erc-auth-source-join-function
+
+ERC calls these functions with keyword arguments recognized by
+@code{auth-source-search}, namely, those deemed most relevant to the
+current context, if any. For example, when identifying to services,
+@code{:user} contains your current nickname. Generalized parameter
+names, like @code{:user} and @code{:host}, are always preferred over
+backend specific ones, like @code{:login} or @code{:machine}. In
+return, ERC expects a string if the search succeeds or @code{nil} if
+it fails.
+
+@findex erc-auth-source-search
+The default value for all three options is the function
+@code{erc-auth-source-search}. It tries to merge relevant contextual
+parameters with those provided or discovered from the logical
+connection or the underlying transport.
+
+For using auth-source along with SASL, @pxref{SASL auth-source
+function}.
+@end defopt
+
+@subsubheading Channel keys
+ERC also consults @code{auth-source} to find ``keys'' that may be
+required by certain channels you join. When modifying a traditional
+@code{auth-source} entry for this purpose, put the channel name in the
+@samp{user} field (for example, @samp{login "#fsf"}, in netrc's case).
+The actual key goes in the @samp{password} (or @samp{secret}) field.
+
+
@node Options
@section Options
@cindex options
projects / emacs.git / commitdiff