Next: , Up: Advanced Usage   [Contents][Index]

5.1 Connecting to an IRC Server

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.

Function: erc

Select connection parameters and run ERC. Non-interactively, it takes the following keyword arguments.

  • server
  • port
  • nick
  • password
  • full-name

That is, if called with the following arguments, server and full-name will be set to those values, whereas erc-compute-port and erc-compute-nick will be invoked for the values of the other parameters.

(erc :server "irc.libera.chat" :full-name "J. Random Hacker")

To connect securely over an encrypted TLS connection, use M-x erc-tls.

Function: erc-tls

Select connection parameters and run ERC over TLS. Non-interactively, it takes the following keyword arguments.

  • server
  • port
  • nick
  • password
  • full-name
  • client-certificate

That is, if called with the following arguments, server and full-name will be set to those values, whereas erc-compute-port and erc-compute-nick will be invoked for the values of the other parameters, and client-certificate will be nil.

(erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker")

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.

Server

Function: erc-compute-server &optional server

Return an IRC server name.

This tries a number of increasingly more default methods until a non-nil value is found.

  • server (the argument passed to this function)
  • The erc-server option
  • The value of the IRCSERVER environment variable
  • The erc-default-server variable
User Option: erc-server

IRC server to use if one is not provided.

Port

Function: erc-compute-port &optional port

Return a port for an IRC server.

This tries a number of increasingly more default methods until a non-nil value is found.

  • port (the argument passed to this function)
  • The erc-port option
  • The erc-default-port variable
User Option: erc-port

IRC port to use if not specified.

This can be either a string or a number.

Nick

Function: erc-compute-nick &optional nick

Return user’s IRC nick.

This tries a number of increasingly more default methods until a non-nil value is found.

  • nick (the argument passed to this function)
  • The erc-nick option
  • The value of the IRCNICK environment variable
  • The result from the user-login-name function
User Option: 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.

User Option: erc-format-nick-function

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)
User Option: erc-nick-uniquifier

The string to append to the nick if it is already in use.

User Option: erc-try-new-nick-p

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.

Password

User Option: erc-prompt-for-password

If non-nil (the default), M-x erc prompts for a password.

If you prefer, you can set this option to nil and use the auth-source mechanism to store your password. For instance, if you use ~/.authinfo as your auth-source backend, then put something like the following in that file:

machine irc.example.net login "#fsf" password sEcReT

ERC also consults auth-source to find any channel keys required for the channels that you wish to autojoin, as specified by the variable erc-autojoin-channels-alist.

For more details, see auth-source in Emacs auth-source Library.

Full name

Function: erc-compute-full-name &optional full-name

Return user’s full name.

This tries a number of increasingly more default methods until a non-nil value is found.

  • full-name (the argument passed to this function)
  • The erc-user-full-name option
  • The value of the IRCNAME environment variable
  • The result from the user-full-name function
User Option: erc-user-full-name

User full name.

This can be either a string or a function to call.

Next: Sample Configuration, Up: Advanced Usage   [Contents][Index]