The easiest way to connect to an IRC server is to call M-x erc. If you want to assign this function to a keystroke, the following will help you figure out its parameters.
Select connection parameters and run ERC. Non-interactively, it takes the following keyword arguments.
For example, calling the command like so
(erc :server "irc.libera.chat" :full-name "J. Random Hacker")
sets server and full-name directly while leaving the rest
up to functions like erc-compute-port. Note that some
arguments can’t be specified interactively. id, in particular,
is rarely needed (see Network Identifier).
To connect securely over an encrypted TLS connection, use M-x erc-tls.
Select connection parameters and run ERC over TLS. Non-interactively, it takes the following keyword arguments.
That is, if called in the following manner
(erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker")
the command will set server and full-name accordingly,
while helpers, like erc-compute-nick, will determine other
parameters, and some, like client-certificate, will just be
nil.
To use a certificate with erc-tls, specify the optional
client-certificate keyword argument, whose value should be as
described in the documentation of open-network-stream: if
non-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 t, which means that
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:
(erc-tls :server "irc.libera.chat" :port 6697
:client-certificate
'("/home/bandali/my-cert.key"
"/home/bandali/my-cert.crt"))
(erc-tls :server "irc.libera.chat" :port 6697
:client-certificate
`(,(expand-file-name "~/cert-libera.key")
,(expand-file-name "~/cert-libera.crt")))
(erc-tls :server "irc.libera.chat" :port 6697
:client-certificate t)
In the case of :client-certificate t, you will need to add a
line like the following to your authinfo file
(e.g. ~/.authinfo.gpg):
machine irc.libera.chat key /home/bandali/my-cert.key cert /home/bandali/my-cert.crt
See Help for users in Emacs auth-source Library, for more on the
.authinfo/.netrc backend of auth-source.
For other uses of auth-source throughout ERC, see ERC’s auth-source integration.
Return an IRC server name.
This tries a number of increasingly more default methods until a non-nil
value is found.
erc-server option
erc-default-server variable
IRC server to use if one is not provided.
Return a port for an IRC server.
This tries a number of increasingly more default methods until a non-nil
value is found.
erc-port option
erc-default-port variable
IRC port to use if not specified.
This can be either a string or a number.
Return user’s IRC nick.
This tries a number of increasingly more default methods until a
non-nil value is found.
erc-nick option
user-login-name function
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.
A function to format a nickname for message display
You can set this to erc-format-@nick to display user mode prefix
(setq erc-format-nick-function 'erc-format-@nick)
The string to append to the nick if it is already in use.
If the nickname you chose isn’t available, and this option is non-nil,
ERC should automatically attempt to connect with another nickname.
You can manually set another nickname with the /NICK command.
Determine a suitable value to send as the first argument of the opening ‘USER’ IRC command by consulting the following sources:
erc-email-userid, assuming erc-anonymous-login
is non-nil
user-login-name
A permanent username value to send for all connections. It should be a string abiding by the rules of the network.
This parameter was traditionally meant to specify a server password to be sent along with the IRC ‘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 ‘myuser:mypass’. IRC bouncers often do something similar but include a pre-configured network-ID component, for example, ‘bncuser/mynet:bncpass’.
In general, if you have not been asked by your network or bouncer to specify a repurposed server password, you should instead consider setting up ‘services’ or, preferably, ‘sasl’, both ERC modules (see 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. (See SASL in ERC.)
If non-nil (the default), M-x erc and M-x erc-tls
prompt for a server password. This only affects interactive
invocations of erc and erc-tls.
If you prefer, you can set this option to nil and use the
auth-source facility to retrieve a server password, although hitting
RET at the prompt may achieve the same effect.
See ERC’s auth-source integration, for more.
Return user’s full name.
This tries a number of increasingly more default methods until a
non-nil value is found.
erc-user-full-name option
user-full-name function
User full name.
This can be either a string or a function to call.
ERC uses an abstract designation, called 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 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) ‘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.