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
• user
• password
• full-name
• id

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.

Function: erc-tls

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

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

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 (for example, ~/.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.

Server

Function: erc-compute-server &optional server

Return an IRC server name.

This tries a progressively greater number of 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 progressively greater number of 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 progressively greater number of 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-show-speaker-membership-status

A boolean for including a channel member’s status prefix in their display name when they speak.

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.

User

Function: erc-compute-user &optional user

Determine a suitable value to send as the first argument of the opening ‘USER’ IRC command by consulting the following sources:

• user, the argument passed to this function
• The option erc-email-userid, assuming erc-anonymous-login is non-nil
• The result of calling the function user-login-name

User Option: erc-email-userid

A permanent username value to send for all connections. It should be a string abiding by the rules of the network.

Password

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.)

User Option: erc-prompt-for-password

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.

Full name

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

Return user’s full name.

This tries a progressively greater number of 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.

ID

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.