\input texinfo @c %**start of header @setfilename ../../info/erc.info @settitle ERC Manual @set ERCVER 5.6.1 @set ERCDIST as distributed with Emacs @value{EMACSVER} @include docstyle.texi @syncodeindex fn cp @include emacsver.texi @c %**end of header @copying This manual is for ERC @value{ERCVER} @value{ERCDIST}. Copyright @copyright{} 2005--2024 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License''. (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.'' All Emacs Lisp code contained in this document may be used, distributed, and modified without restriction. @end quotation @end copying @dircategory Emacs network features @direntry * ERC: (erc). Powerful and extensible IRC client for Emacs. @end direntry @titlepage @title ERC manual @subtitle a full-featured IRC client @subtitle for Emacs @c The following two commands @c start the copyright page. @page @vskip 0pt plus 1filll @insertcopying @end titlepage @contents @ifnottex @node Top @top ERC @insertcopying @end ifnottex @menu * Introduction:: What is ERC? * Getting Started:: Quick Start guide to using ERC. * Keystroke Summary:: Keystrokes used in ERC buffers. * Modules:: Available modules for ERC. * Advanced Usage:: Cool ways of using ERC. * Getting Help and Reporting Bugs:: * History:: The history of ERC. * GNU Free Documentation License:: The license for this documentation. * Concept Index:: Search for terms. @detailmenu --- The Detailed Node Listing --- Getting Started * Sample Session:: Example of connecting to the @samp{#emacs} channel * Special Features:: Differences from standalone IRC clients Advanced Usage * Connecting:: Ways of connecting to an IRC server. * SASL:: Authenticating via SASL. * Sample Configuration:: An example configuration file. * Integrations:: Integrations available for ERC. * Options:: Options that are available for ERC. @end detailmenu @end menu @node Introduction @chapter Introduction ERC is a powerful, modular, and extensible IRC client for Emacs. It has been included in Emacs since 2006 (@pxref{History}) and is also available on GNU ELPA. IRC is short for Internet Relay Chat. When using IRC, you can communicate with other users on the same IRC network. There are many different networks---if you search for ``IRC networks'' in your favorite search engine, you will find up-to-date lists of IRC networks catering to various interests and topics. To use IRC, you need an IRC client such as ERC. Using the client, you connect to an IRC server. Once you've done that, you will have access to all available channels on that server's network. A channel is basically a chat room, and what you type in a channel will be shown to all other users in that channel. You can be in several channels at the same time---ERC will show each channel in its own buffer. IRC channel names always begin with a @samp{#} character. For example, the Emacs channel on Libera.Chat is @samp{#emacs}, and the ERC channel is @samp{#erc}. Do not confuse them with the hashtags used on many social media platforms. You can also send private messages to other IRC users on the same network, even if they are not in the same channels as you. ERC comes with the following capabilities enabled by default. @itemize @bullet @item Flood control @item Timestamps @item Join channels automatically @item Buttonize URLs, nicknames, and other text @item Wrap long lines @item Highlight or remove IRC control characters @item Highlight pals, fools, and other keywords @item Detect netsplits @item Complete nicknames and commands in a programmable fashion @item Make displayed lines read-only @item Input history @item Track channel activity in the mode-line @end itemize @node Getting Started @chapter Getting Started @cindex settings The command @kbd{M-x erc} will start ERC and prompt for the server to connect to. If you're unsure of which server or network to connect to, we suggest starting with ``irc.libera.chat''. There you will find the @samp{#emacs} channels where you can chat with other Emacs users, and if you're having trouble with ERC, you can join the @samp{#erc} channel and ask for help there. At some point in your ERC journey, you'll inevitably want to change how the client looks and behaves. As with other Emacs applications, the typical place to store your settings is your @file{init.el}. If you would rather use the Customize interface, a good place to start is by running @kbd{M-x customize-group @key{RET} erc @key{RET}}. In particular, ERC comes with lots of modules that may be enabled or disabled; to select which ones you want, do @kbd{M-x customize-variable @key{RET} erc-modules @key{RET}}. @menu * Sample Session:: Example of connecting to the #emacs channel * Special Features:: Differences from standalone IRC clients @end menu @node Sample Session @section Sample Session This example ERC session describes how to connect to the @samp{#emacs} channel on Libera.Chat. Also worth checking out is Libera's own introductory guide to IRC, @uref{https://libera.chat/guides/basics}, which presents a more comprehensive overview without instructions specific to ERC. @itemize @bullet @item Connect to Libera.Chat Run @kbd{M-x erc @key{RET}}. Use @samp{irc.libera.chat} for the server and @samp{6667} for the port. Choose a nickname, and hit @key{y} when asked if you'd prefer to connect over @acronym{TLS}. @item Get used to the interface Switch to the @file{Libera.Chat} buffer if you're not already there. ERC calls this a @dfn{server buffer}, and it must exist for the duration of the session. You will likely see some messages about ``ident'', authentication, and the like, followed by information describing the current server and the network. @item Join the #emacs channel In the server buffer, type @kbd{/join #emacs @key{RET}} at the prompt. ERC will create a new buffer called @file{#emacs}. If you've already configured ERC, you may need to switch to it manually. Once there, you will see the channel's ``topic'' in the buffer's header line (@pxref{Header Lines,,,elisp,}) and a list of people currently in the channel. If you can't see the full topic, mouse over it or type @kbd{/topic @key{RET}} at the prompt. @item Register your nickname with Libera.Chat In order to access essential network features, like speaking in certain channels and participating in private conversations, you'll likely have to ``register'' your nickname. To do so, switch to the @file{Libera.Chat} buffer and type @kbd{/msg NickServ register @samp{} @samp{} @key{RET}}, replacing @samp{} and @samp{} with your desired account password and contact email (both sans quotes). The server should tell you that the operation was successful. See the official Libera.Chat docs if you encounter problems. In addition to creating an account, this process also ``authenticates'' you to the network's ``account services'' system for the duration of the session. In other words, you're now logged in. However, when you connect in the future, you'll need to authenticate again by providing the same credentials somehow. When you're finished with this walk through, see ``Next Steps'', below, to learn some ways to do that. @item Talk to people in the channel Switch back to the @file{#emacs} buffer and type a message at the prompt, hitting @kbd{RET} once satisfied. Everyone in the channel will now see your message. @item Open a query buffer to talk to someone If you want to talk with someone in private, type @kbd{/query @samp{} @key{RET}}, replacing @samp{} with the their nickname. As before, with the server buffer, if this new @dfn{query buffer} doesn't appear in the current window, you may have to switch to it. Regardless, its name should match @samp{}. Once there, type something at the prompt and hit @kbd{RET}, and the other party will see it. Keep in mind that if either party isn't authenticated, you may not be able to converse at all. Also, depending on the network, certain social conventions may apply to the practice of direct messaging. As a general rule, queries should usually be reserved for personal matters rather than technical help, which can often benefit (and benefit @emph{from}) a larger audience. @item Next steps Try joining another channel, such as @samp{#erc}, where ERC users and developers hang out (@pxref{Official IRC channels} for more on the history of @samp{#emacs}). For ideas on various options to customize, @pxref{Sample Configuration}. To learn how ERC can authenticate you to the network automatically whenever you connect, @pxref{SASL}. As always, if you encounter problems, @pxref{Getting Help and Reporting Bugs}. @end itemize @node Special Features @section Special Features ERC has some features that distinguish it from some IRC clients. @itemize @bullet @item multiple channels and multiple servers Every channel is put in a separate buffer. Several IRC servers may be connected to at the same time. @cindex query buffers @item private message separation Private conversations are treated as channels, and are put into separate buffers in Emacs. We call these ``query buffers''. @item highlighting Some occurrences of words can be highlighted, which makes it easier to track different kinds of conversations. @item notification ERC can notify you that certain users are online. @item channel tracking Channels can be hidden and conversation continue in the background. You are notified when something is said in such a channel that is not currently visible. This makes it easy to get Real Work done while still maintaining an IRC presence. @item nick completion ERC can complete words upon hitting @kbd{TAB}, which eases the writing of nicknames in messages. @cindex history ring @item history Past actions are kept in history rings for future use. To navigate a history ring, hit @kbd{M-p} to go backwards and @kbd{M-n} to go forwards. @item multiple languages Different channels and servers may have different language encodings. multiple languages. Please contact the Emacs developers if you are interested in helping with the translation effort. @item user scripting Users can load scripts (e.g., auto greeting scripts) when ERC starts up. It is also possible to make custom IRC commands, if you know a little Emacs Lisp. Just make an Emacs Lisp function and call it @code{erc-cmd-NEWCOMMAND}, where @code{NEWCOMMAND} is the name of the new command in capital letters. @item auto reconnect If the connection goes away at some point, ERC will try to reconnect automatically. If it fails to reconnect, and you want to try to manually reestablish the connection at some later point, switch to an ERC buffer and run the @code{/RECONNECT} command. @end itemize @node Keystroke Summary @chapter Keys Used in ERC @cindex keystrokes This is a summary of keystrokes available in every ERC buffer. @table @kbd @item C-a or (@code{erc-bol}) Go to beginning of line or end of prompt. @item @key{RET} (@code{erc-send-current-line}) Send the current line @item @key{TAB} (@code{completion-at-point} or @code{erc-button-next}) If at prompt, complete the current word. Otherwise, move to the next link or button. @item M-@key{TAB} (@code{ispell-complete-word}) Complete the given word, using ispell. @item C-c C-a (@code{erc-bol}) Go to beginning of line or end of prompt. @item C-c C-b (@code{erc-switch-to-buffer}) Use @code{read-buffer} to prompt for a ERC buffer to switch to. @item C-c C-c (@code{erc-toggle-interpret-controls}) Toggle interpretation of control sequences in messages. @item C-c C-d (@code{erc-input-action}) Interactively input a user action and send it to IRC. @item C-c C-e (@code{erc-toggle-ctcp-autoresponse}) Toggle automatic CTCP replies (like VERSION and PING). @item C-c C-f (@code{erc-toggle-flood-control}) Toggle use of flood control on sent messages. @item C-c @key{TAB} (@code{erc-invite-only-mode}) Turn on the invite only mode (+i) for the current channel. @item C-c C-j (@code{erc-join-channel}) Join channel. If point is at the beginning of a channel name, use that as default. @item C-c C-k (@code{erc-go-to-log-matches-buffer}) Interactively open an erc-log-matches buffer @item C-c C-l (@code{erc-save-buffer-in-logs}) Append buffer contents to the log file, if logging is enabled. @item C-c C-n (@code{erc-channel-names}) Run "/names #channel" in the current channel. @item C-c C-o (@code{erc-get-channel-mode-from-keypress}) Read a key sequence and call the corresponding channel mode function. After doing @kbd{C-c C-o}, type in a channel mode letter. @kbd{C-g} means quit. @kbd{RET} lets you type more than one mode at a time. If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called. If @kbd{k} is pressed, @code{erc-set-channel-key} gets called. Anything else will be sent to @code{erc-toggle-channel-mode}. @item C-c C-p (@code{erc-part-from-channel}) Part from the current channel and prompt for a reason. @item C-c C-q (@code{erc-quit-server}) Disconnect from current server after prompting for reason. @item C-c C-r (@code{erc-remove-text-properties-region}) Clears the region (start,end) in object from all colors, etc. @item C-c C-t (@code{erc-set-topic}) Prompt for a topic for the current channel. @item C-c C-u (@code{erc-kill-input}) Kill current input line using @code{erc-bol} followed by @code{kill-line}. @end table @node Modules @chapter Modules @cindex modules One way to add functionality to ERC is to customize which of its many modules are loaded. You can do this by typing @kbd{C-h v erc-modules @key{RET}} and clicking @samp{customize} near the bottom of the resulting help buffer, where it says ``You can @emph{customize} this variable.'' When removing a module outside of Customize, you may wish to ensure it's disabled by invoking its associated minor-mode toggle with a nonpositive prefix argument, for example, @kbd{C-u - M-x erc-spelling-mode @key{RET}}. Additionally, if you plan on loading third-party modules that perform atypical setup on activation, you may need to arrange for calling @code{erc-update-modules} in your init file. Examples of such setup might include registering an @code{erc-before-connect} hook, advising @code{erc-open}, and modifying @code{erc-modules} itself. On Emacs 29 and greater, you can also run @code{erc-update-modules} indirectly, via @code{(setopt erc-modules erc-modules)}. The following is a list of available modules. @table @code @cindex modules, autoaway @item autoaway Set away status automatically @cindex modules, autojoin @item autojoin Join channels automatically @cindex modules, bufbar @item bufbar List buffers belonging to a connection in a side window; part of Custom group @code{erc-status-sidebar} @cindex modules, button @item button Buttonize URLs, nicknames, and other text @cindex modules, capab-identify @item capab-identify Mark unidentified users on freenode and other servers supporting CAPAB. @cindex modules, command-indicator @item command-indicator Echo command lines for ``slash commands'', like @kbd{/JOIN #erc} and @kbd{/HELP join} @cindex modules, completion @cindex modules, pcomplete @item completion (aka pcomplete) Complete nicknames and commands (programmable) @cindex modules, fill @item fill Wrap long lines @cindex modules, identd @item identd Launch an identd server on port 8113 @cindex modules, irccontrols @item irccontrols Highlight or remove IRC control characters @cindex modules, keep-place @item keep-place Remember your position in buffers @cindex modules, log @item log Save buffers in logs @cindex modules, match @item match Highlight pals, fools, and other keywords @cindex modules, menu @item menu Display a menu in ERC buffers @cindex modules, netsplit @item netsplit Detect netsplits @cindex modules, nicks @item nicks Automatically colorize nicks @cindex modules, nickbar @item nickbar List participating nicks for the current target buffer in a side window; part of Custom group @code{erc-speedbar} @cindex modules, noncommands @item noncommands Don't display non-IRC commands after evaluation @cindex modules, notify @item notify Notify when the online status of certain users changes @cindex modules, notifications @item notifications Send you a notification when you get a private message, or your nickname is mentioned @cindex modules, page @item page Process CTCP PAGE requests from IRC @cindex modules, querypoll @item querypoll Update query participant data by continually polling the server @cindex modules, readonly @item readonly Make displayed lines read-only @cindex modules, replace @item replace Replace text in messages @cindex modules, ring @item ring Enable an input history @cindex modules, sasl @item sasl Enable SASL authentication @cindex modules, scrolltobottom @item scrolltobottom Scroll to the bottom of the buffer @cindex modules, services @item services Identify to Nickserv (IRC Services) automatically @cindex modules, smiley @item smiley Convert smileys to pretty icons @cindex modules, sound @item sound Play sounds when you receive CTCP SOUND requests @cindex modules, spelling @item spelling Check spelling of messages @cindex modules, stamp @item stamp Add timestamps to messages @cindex modules, track @item track Track channel activity in the mode-line @cindex modules, truncate @item truncate Truncate buffers to a certain size @cindex modules, unmorse @item unmorse Translate morse code in messages @end table @anchor{Auxiliary Modules} @subheading Auxiliary Modules @cindex auxiliary modules For various reasons, the following modules aren't currently listed in the Custom interface for @code{erc-modules}, but feel free to add them explicitly. They may be managed by another module or considered more useful when toggled interactively or just deemed experimental. @table @code @cindex modules, fill-wrap @item fill-wrap Wrap long lines using @code{visual-line-mode} @cindex modules, keep-place-indicator @item keep-place-indicator Remember your place in buffers with a visible reminder; activated interactively or via something like @code{erc-join-hook} @cindex modules, services-regain @item services-regain Automatically ask NickServ to reclaim your nick when reconnecting; experimental as of ERC 5.6 @end table @anchor{Required Modules} @subheading Required Modules @cindex required modules Note that some modules are essential to core IRC operations and thus not listed above. You can nevertheless still remove these, but doing so demands special precautions to avoid degrading the user experience. At present, the only such module is @code{networks}, whose library ERC always loads anyway. @anchor{Local Modules} @subheading Local Modules @cindex local modules All modules operate as minor modes under the hood, and some newer ones may be defined as buffer-local. These so-called ``local modules'' are a work in progress and their behavior and interface are subject to change. As of ERC 5.5, the only practical differences are as follows: @enumerate @item ``Control variables,'' like @code{erc-sasl-mode}, retain their values across IRC sessions and override @code{erc-module} membership when influencing module activation. @item Removing a local module from @code{erc-modules} via Customize not only disables its mode but also kills its control variable in all ERC buffers. @item ``Mode toggles,'' like @code{erc-sasl-mode} and the complementary @code{erc-sasl-enable}/@code{erc-sasl-disable} pairing, behave differently than their global counterparts. @end enumerate In target buffers, a local module's activation state survives ``reassociation'' by default, but modules themselves always have the final say. For example, a module may reset all instances of itself in its network context upon reconnecting. Moreover, the value of a mode variable may be meaningless in buffers that its module has no interest in. For example, the value of @code{erc-sasl-mode} doesn't matter in target buffers and may even remain non-@code{nil} after SASL has been disabled for the current connection (and vice versa). When it comes to server buffers, a module's activation state only persists for sessions revived via the automatic reconnection mechanism or a manual @samp{/reconnect} issued at the prompt. In other words, this doesn't apply to sessions revived by an entry-point command, such as @code{erc-tls}, because such commands always ensure a clean slate by looking only to @code{erc-modules}. Although a session revived in this manner may indeed harvest other information from a previous server buffer, it simply doesn't care which modules might have been active during that connection. Lastly, a local mode's toggle command, like @code{erc-sasl-mode}, only affects the current buffer, but its ``non-mode'' cousins, like @code{erc-sasl-enable} and @code{erc-sasl-disable}, operate on all buffers belonging to their connection (when called interactively). And unlike global toggles, none of these ever mutates @code{erc-modules}. @c FIXME add section to Advanced chapter for creating modules, and @c move this there. @anchor{Module Loading} @subheading Loading @cindex module loading ERC loads internal modules in alphabetical order and third-party modules as they appear in @code{erc-modules}. When defining your own module, take care to ensure ERC can find it. An easy way to do that is by mimicking the example in the doc string for @code{define-erc-module} (also shown below). For historical reasons, ERC falls back to @code{require}ing features. For example, if some module @code{my-module} in @code{erc-modules} lacks a corresponding @code{erc-my-module-mode} command, ERC will attempt to load the library @code{erc-my-module} prior to connecting. If this fails, ERC signals an error. Users defining personal modules in an init file should @code{(provide 'erc-my-module)} somewhere to placate ERC. Dynamically generating modules on the fly is not supported. Some older built-in modules have a second name along with a second minor-mode toggle, which is just a function alias for its primary counterpart. For practical reasons, ERC does not define a corresponding variable alias because contending with indirect variables complicates bookkeeping tasks, such as persisting module state across IRC sessions. New modules should definitely avoid defining aliases without a good reason. Some packages have been known to autoload a module's definition instead of its minor-mode command, which severs the link between the library and the module. This means that enabling the mode by invoking its command toggle isn't enough to load its defining library. As such, packages should only supply module-related autoload cookies with an actual @code{autoload} form for their module's minor-mode command, like so: @lisp ;;;###autoload(autoload 'erc-my-module-mode "erc-my-module" nil t) (define-erc-module my-module nil "My doc string." ((add-hook 'erc-insert-post-hook #'erc-my-module-on-insert-post)) ((remove-hook 'erc-insert-post-hook #'erc-my-module-on-insert-post))) @end lisp @noindent As implied earlier, packages can usually omit such cookies entirely so long as their module's prefixed name matches that of its defining library and the library's provided feature. Finally, packages have also been observed to run @code{erc-update-modules} in top-level forms, forcing ERC to take special precautions to avoid recursive invocations. Another unfortunate practice is mutating @code{erc-modules} itself upon loading @code{erc}, possibly by way of an autoload. Doing this tricks Customize into displaying the widget for @code{erc-modules} incorrectly, with built-in modules moved from the predefined checklist to the user-provided free-form area. @c PRE5_4: Document every option of every module in its own subnode @node Advanced Usage @chapter Advanced Usage @cindex advanced topics @menu * Connecting:: Ways of connecting to an IRC server. * 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. * SOCKS:: Connecting to IRC with a SOCKS proxy. * auth-source:: Retrieving auth-source entries with ERC. * display-buffer:: Controlling how ERC displays buffers. @end detailmenu @end menu @node Connecting @section Connecting to an IRC Server @cindex connecting The easiest way to connect to an IRC server is to call @kbd{M-x erc}. If you want to assign this function to a keystroke, the following will help you figure out its parameters. @defun erc Select connection parameters and run ERC@. Non-interactively, it takes the following keyword arguments. @itemize @bullet @item @var{server} @item @var{port} @item @var{nick} @item @var{user} @item @var{password} @item @var{full-name} @item @var{id} @end itemize For example, calling the command like so @example lisp (erc :server "irc.libera.chat" :full-name "J. Random Hacker") @end example @noindent sets @var{server} and @var{full-name} directly while leaving the rest up to functions like @code{erc-compute-port}. Note that some arguments can't be specified interactively. @var{id}, in particular, is rarely needed (@pxref{Network Identifier}). @end defun @noindent To connect securely over an encrypted TLS connection, use @kbd{M-x erc-tls}. @defun erc-tls Select connection parameters and run ERC over TLS@. Non-interactively, it takes the following keyword arguments. @itemize @bullet @item @var{server} @item @var{port} @item @var{nick} @item @var{user} @item @var{password} @item @var{full-name} @item @var{id} @item @var{client-certificate} @end itemize That is, if called in the following manner @example lisp (erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker") @end example @noindent the command will set @var{server} and @var{full-name} accordingly, while helpers, like @code{erc-compute-nick}, will determine other parameters, and some, like @code{client-certificate}, will just be @code{nil}. @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 non-@code{nil}, it should either be a list where the first element is the file name of the private key corresponding to a client certificate and the second element is the file name of the client certificate itself to use when connecting over TLS, or @code{t}, which means that @code{auth-source} will be queried for the private key and the certificate. Authenticating using a TLS client certificate is also referred to as ``CertFP'' (Certificate Fingerprint) authentication by various IRC networks. Examples of use: @example (erc-tls :server "irc.libera.chat" :port 6697 :client-certificate '("/home/bandali/my-cert.key" "/home/bandali/my-cert.crt")) @end example @example (erc-tls :server "irc.libera.chat" :port 6697 :client-certificate `(,(expand-file-name "~/cert-libera.key") ,(expand-file-name "~/cert-libera.crt"))) @end example @example (erc-tls :server "irc.libera.chat" :port 6697 :client-certificate t) @end example In the case of @code{:client-certificate t}, you will need to add a line like the following to your authinfo file (e.g. @file{~/.authinfo.gpg}): @example machine irc.libera.chat key /home/bandali/my-cert.key cert /home/bandali/my-cert.crt @end example @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 @defun erc-compute-server &optional server Return an IRC server name. This tries a progressively greater number of default methods until a non-@code{nil} value is found. @itemize @bullet @item @var{server} (the argument passed to this function) @item The @code{erc-server} option @item The value of the IRCSERVER environment variable @item The @code{erc-default-server} variable @end itemize @end defun @defopt erc-server IRC server to use if one is not provided. @end defopt @subheading Port @defun erc-compute-port &optional port Return a port for an IRC server. This tries a progressively greater number of default methods until a non-@code{nil} value is found. @itemize @bullet @item @var{port} (the argument passed to this function) @item The @code{erc-port} option @item The @code{erc-default-port} variable @end itemize @end defun @defopt erc-port IRC port to use if not specified. This can be either a string or a number. @end defopt @subheading Nick @defun erc-compute-nick &optional nick Return user's IRC nick. This tries a progressively greater number of default methods until a non-@code{nil} value is found. @itemize @item @var{nick} (the argument passed to this function) @item The @code{erc-nick} option @item The value of the IRCNICK environment variable @item The result from the @code{user-login-name} function @end itemize @end defun @defopt erc-nick Nickname to use if one is not provided. This can be either a string, or a list of strings. In the latter case, if the first nick in the list is already in use, other nicks are tried in the list order. @end defopt @defopt erc-show-speaker-membership-status A boolean for including a channel member's @dfn{status prefix} in their display name when they speak. @end defopt @defopt erc-nick-uniquifier The string to append to the nick if it is already in use. @end defopt @defopt erc-try-new-nick-p If the nickname you chose isn't available, and this option is non-@code{nil}, ERC should automatically attempt to connect with another nickname. You can manually set another nickname with the /NICK command. @end defopt @anchor{username parameter} @subheading User @cindex username parameter @defun erc-compute-user &optional user Determine a suitable value to send as the first argument of the opening @samp{USER} IRC command by consulting the following sources: @itemize @item @var{user}, the argument passed to this function @item The option @code{erc-email-userid}, assuming @code{erc-anonymous-login} is non-@code{nil} @item The result of calling the function @code{user-login-name} @end itemize @end defun @defopt erc-email-userid A permanent username value to send for all connections. It should be a string abiding by the rules of the network. @end defopt @anchor{password parameter} @anchor{server password} @cindex password, server @subheading 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} prompt for a server password. This only affects interactive invocations of @code{erc} and @code{erc-tls}. @end defopt @noindent If you prefer, you can set this option to @code{nil} and use the 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 @defun erc-compute-full-name &optional full-name Return user's full name. This tries a progressively greater number of default methods until a non-@code{nil} value is found. @itemize @bullet @item @var{full-name} (the argument passed to this function) @item The @code{erc-user-full-name} option @item The value of the IRCNAME environment variable @item The result from the @code{user-full-name} function @end itemize @end defun @defopt erc-user-full-name User full name. This can be either a string or a function to call. @end defopt @anchor{Network Identifier} @subheading ID ERC uses an abstract designation, called @dfn{network context identifier}, for referring to a connection internally. While normally derived from a combination of logical and physical connection parameters, an ID can also be explicitly provided via an entry-point command (like @code{erc-tls}). Use this in rare situations where ERC would otherwise have trouble discerning between connections. One such situation might arise when using multiple connections to the same network with the same nick but different (nonstandard) @samp{device} identifiers, which some bouncers may support. Another might be when mimicking the experience offered by popular standalone clients, which normally offer ``named'' persistent configurations with server buffers reflecting those names. Yet another use case might involve third-party code needing to identify a connection unequivocally, but in a human-friendly way suitable for UI components. When providing an ID as an entry-point argument, strings and symbols make the most sense, but any reasonably printable object is acceptable. @node SASL @section Authenticating via SASL @cindex SASL If you've used @acronym{SASL} elsewhere, you can probably skip to the examples below. Otherwise, if you haven't already registered with your network, please do so now, referring to the network's own instructions for details. If you're new to IRC and using a bouncer, know that you probably won't be needing this for the client-to-bouncer connection. When you're ready to get started, add @code{sasl} to @code{erc-modules}, like you would any other module. If unsure which @dfn{mechanism} to choose, stick with the default of @samp{PLAIN}. Then try @kbd{C-u M-x erc-tls @key{RET}}, and give your account name for the @samp{user} parameter and your account password for the @samp{server password}. @defopt erc-sasl-mechanism The name of an SASL subprotocol type as a @emph{lowercase} symbol. The value can be one of the following: @table @asis @item @code{plain} or @code{scram} (``password-based'') Here, ``password'' refers to your account password, which is usually your @samp{NickServ} password. To make this work, customize @code{erc-sasl-user} and @code{erc-sasl-password} or specify the @code{:user} and @code{:password} keyword arguments when invoking @code{erc-tls}. @item @code{external} (via client @acronym{TLS} certificate) This works in conjunction with the @code{:client-certificate} keyword offered by @code{erc-tls}. Just ensure you've registered your fingerprint with the network beforehand. The fingerprint is usually a SHA1 or SHA256 digest in either "normalized" or "openssl" forms. The first is lowercase without delims (@samp{deadbeef}) and the second 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. @xref{client-certificate}. Additional considerations: @enumerate @item Most IRCds will allow you to authenticate with a client cert but without the hassle of SASL (meaning you may not need this module). @item Technically, @var{EXTERNAL} merely indicates that an out-of-band mode of authentication is in effect (being deferred to), so depending on the specific application or service, there's a remote chance your server has something else in mind. @end enumerate @item @code{ecdsa-nist256p-challenge} This mechanism is quite complicated and currently requires the external @samp{openssl} executable, so please use something else if at all possible. Ignoring that, specify your key file (e.g., @samp{~/pki/mykey.pem}) as the value of @code{erc-sasl-password}, and then configure your network settings. On servers running Atheme services, you can add your public key with @samp{NickServ} like so: @example ERC> /msg NickServ set property \ pubkey AgGZmlYTUjJlea/BVz7yrjJ6gysiAPaQxzeUzTH4hd5j @end example (You may be able to omit the @samp{property} subcommand.) @end table @end defopt @defopt erc-sasl-user 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. @xref{username parameter}. @end defopt @defopt erc-sasl-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. 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{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: @defun erc-sasl-auth-source-password-as-host &rest plist Setting @code{erc-sasl-auth-source-function} to this function tells ERC to use @code{erc-sasl-password} for the @code{:host} field when querying auth-source, even if its value is the default @code{:password}, in which case ERC knows to ``resolve'' it to @code{erc-session-password} and use that as long as it's non-@code{nil}. Otherwise, ERC just defers to @code{erc-auth-source-search} to determine the @code{:host}, along with everything else. @end defun As long as this option specifies a function, ERC will pass it the ``resolved'' value of @code{erc-sasl-user} for the auth-source @code{:user} param. @end defopt @defopt erc-sasl-authzid In the rarest of circumstances, a network may want you to specify a specific role or assume an alternate identity. In most cases, this happens because the server is buggy or misconfigured. If you suspect such a thing, please contact your network operator. Otherwise, just leave this set to @code{nil}. @end defopt @subheading Examples @itemize @bullet @item Defaults @lisp (erc-tls :server "irc.libera.chat" :port 6697 :nick "aph" :user "APHacker" :password "changeme") @end lisp Here, after adding @code{sasl} to @code{erc-modules} via the Customize interface, you authenticate to Libera.Chat using the @samp{PLAIN} mechanism and your NickServ credentials, @samp{APHacker} and @samp{changeme}. @item External @lisp (setopt erc-sasl-mechanism 'external) (erc-tls :server "irc.libera.chat" :port 6697 :nick "aph" :client-certificate '("/home/aph/my.key" "/home/aph/my.crt")) @end lisp You decide to switch things up and try out the @samp{EXTERNAL} mechanism. You follow your network's instructions for telling NickServ about your client-certificate's fingerprint, and you authenticate successfully. @item Multiple networks @example # ~/.authinfo.gpg machine irc.libera.chat key /home/aph/my.key cert /home/aph/my.crt machine Example.Net login alyssa password sEcReT machine Example.Net login aph-bot password sesame @end example @lisp ;; init.el (defun my-erc-up (network) (interactive "Snetwork: ") (require 'erc-sasl) (or (let ((erc-modules (cons 'sasl erc-modules))) (pcase network ('libera (let ((erc-sasl-mechanism 'external)) (erc-tls :server "irc.libera.chat" :client-certificate t))) ('example (let ((erc-sasl-auth-source-function #'erc-sasl-auth-source-password-as-host)) (erc-tls :server "irc.example.net" :user "alyssa" :password "Example.Net"))))) ;; Non-SASL (call-interactively #'erc-tls))) @end lisp You've started storing your credentials with auth-source and have decided to try SASL on another network as well. But there's a catch: this network doesn't support @samp{EXTERNAL}. You use @code{let}-binding to work around this and successfully authenticate to both networks. (Note that this example assumes you've removed @code{sasl} from @code{erc-modules} globally and have instead opted to add it locally when connecting to preconfigured networks.) @end itemize @subheading Troubleshooting 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 options to their defaults and calling @code{erc-tls} with @code{:user} set to your NickServ account name and @code{:password} to your NickServ password. If you're still having trouble, please contact us (@pxref{Getting Help and Reporting Bugs}). As you try out different settings, keep in mind that it's best to create a fresh session for every change, for example, by calling @code{erc-tls} from scratch. More experienced users may be able to get away with cycling @code{erc-sasl-mode} and issuing a @samp{/reconnect}, but that's generally not recommended. Whatever the case, you'll probably want to temporarily disable @code{erc-server-auto-reconnect} while experimenting. @node Sample Configuration @section Sample Configuration @cindex configuration, sample Here is an example configuration for ERC@. @strong{Don't panic} if you aren't familiar with @samp{use-package} or have no interest in learning it. For our purposes, it's just a means of presenting configuration details in a tidy, standardized format. If it helps, just pretend it's some make-believe, pseudo configuration language. And while the syntax below is easy enough to intuit and adapt to your setup, you may wish to keep the following in mind: @itemize @bullet @item Each @code{use-package} ``declaration'' focuses on a library ``feature'', which is just a symbol you'd normally @code{require} in your config. @item Emacs loads anything in a @code{:config} section @emph{after} loading whatever library @code{provide}s the declaration's feature. @item Everything in a @code{:custom} or @code{:custom-face} section is basically something you'd find in your @code{custom-file}. @item For more info, @pxref{Named Features,,, elisp,}, or @pxref{Top,,, use-package,}. @end itemize @noindent The following would typically go in your init file. Experienced users may opt to keep any non-settings, like commands and functions, in a dedicated @file{~/.emacs.d/.ercrc.el}. Whatever the case, please keep in mind that you can replace nearly all of the following with Custom settings (@pxref{Sample configuration via Customize}). @lisp ;;; My ERC configuration -*- lexical-binding: t -*- (use-package erc :config ;; Prefer SASL to NickServ, colorize nicknames, and show side panels ;; with joined channels and members (setopt erc-modules (seq-union '(sasl nicks bufbar nickbar scrolltobottom) erc-modules)) :custom ;; Protect me from accidentally sending excess lines. (erc-inhibit-multiline-input t) (erc-send-whitespace-lines t) (erc-ask-about-multiline-input t) ;; Scroll all windows to prompt when submitting input. (erc-scrolltobottom-all t) ;; Reconnect automatically using a fancy strategy. (erc-server-reconnect-function #'erc-server-delayed-check-reconnect) (erc-server-reconnect-timeout 30) ;; Show new buffers in the current window instead of a split. (erc-interactive-display 'buffer) ;; Insert a newline when I hit at the prompt, and prefer ;; something more deliberate for actually sending messages. :bind (:map erc-mode-map ("RET" . nil) ("C-c C-c" . #'erc-send-current-line)) ;; Emphasize buttonized text in notices. :custom-face (erc-notice-face ((t (:slant italic :weight unspecified))))) (use-package erc-sasl ;; Since my account name is the same as my nick, free me from having ;; to hit C-u before M-x erc to trigger a username prompt. :custom (erc-sasl-user :nick)) (use-package erc-join ;; Join #emacs and #erc whenever I connect to Libera.Chat. :custom (erc-autojoin-channels-alist '((Libera.Chat "#emacs" "#erc")))) (use-package erc-fill :custom ;; Prefer one message per line without continuation indicators. (erc-fill-function #'erc-fill-wrap) (erc-fill-static-center 18) :bind (:map erc-fill-wrap-mode-map ("C-c =" . #'erc-fill-wrap-nudge))) (use-package erc-match ;; Use the same face for my own nick wherever it appears. :custom-face (erc-current-nick-face ((t ( :weight unspecified :foreground unspecified :inherit erc-my-nick-face))))) (use-package erc-track ;; Prevent JOINs and PARTs from lighting up the mode-line. :config (setopt erc-track-faces-priority-list (remq 'erc-notice-face erc-track-faces-priority-list)) :custom (erc-track-priority-faces-only 'all)) (use-package erc-goodies ;; Turn on read indicators when joining channels. :hook (erc-join . my-erc-enable-keep-place-indicator-on-join)) (defvar my-erc-read-indicator-channels '("#emacs") "Channels in which to show a `keep-place-indicator'.") (defun my-erc-enable-keep-place-indicator-on-join () "Enable read indicators for certain queries or channels." (when (member (erc-default-target) my-erc-read-indicator-channels) (erc-keep-place-indicator-mode +1))) ;; Handy commands from the Emacs Wiki. (defun erc-cmd-TRACK (&optional target) "Start tracking TARGET or that of current buffer." (setq erc-track-exclude (delete (or target (erc-default-target) (current-buffer)) erc-track-exclude))) (defun erc-cmd-UNTRACK (&optional target) "Stop tracking TARGET or that of current buffer." (setq erc-track-exclude (cl-pushnew (or target (erc-default-target) (current-buffer)) erc-track-exclude :test #'equal))) @end lisp @noindent Those familiar with @code{use-package} may have noticed the lack of @code{:defer} keyword args. This was done to conserve space, but you can just pretend that this user has enabled @code{use-package-always-defer} elsewhere. @anchor{Sample configuration via Customize} @subheading Via Customize @cindex configuration, via customize As mentioned, Customize users can accomplish nearly all of the above via the Customize interface. Start by running @kbd{M-x customize-group @key{RET} erc @key{RET}}, and search for ``Modules'' with @kbd{C-s modules @key{RET}}. Toggle open the flyout menu to reveal the full @dfn{widget} panel, a web-form-like interface for ``Erc Modules''. Tick the boxes for @samp{bufbar}, @samp{nickbar}, @samp{nicks}, @samp{sasl}, and @samp{scrolltobottom}. Next, search for the phrases ``Erc Ask About Multiline Input'', ``Erc Inhibit Multiline Input'', and ``Erc Send Whitespace Lines''. These are the print names of three boolean options that control how ERC treats prompt input containing line breaks. When visiting each option's section, twirl open its triangle icon to reveal its widget UI, and click its @samp{[Toggle]} button to set its value to @code{t}. While going about this, you may find it helpful to glance at the descriptions just in case you want to disable them later. When finished, hit @kbd{C-x C-s} or click @samp{[Apply and Save]} atop the buffer. Now do the same for another couple options, this time having to do with automatic reconnection. But instead of searching for their print names, try running @kbd{M-x customize-option @key{RET} @samp{