doomemacs/modules/app/irc/README.org

:app irc

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
  • macOS
  • Debian / Ubuntu
  • Arch Linux
  • NixOS
• Usage
• Configuration
  • Pass: the unix password manager
  • Emacs' auth-source API
• Troubleshooting
• Frequently asked questions
• Appendix

Description   unfold

This module turns Emacs into an IRC client, capable of OS notifications.

Maintainers

This module has no dedicated maintainers. Become a maintainer?

Module flags

This module has no flags.

Packages

• doom-package:circe
• doom-package:circe-notifications

Hacks

No hacks documented for this module.

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module requires:

• GnuTLS, for secure IRC connections to work.

This should be available through your OS package manager.

macOS

brew install gnutls

Debian / Ubuntu

apt install gnutls-bin

Arch Linux

pacman -S gnutls

NixOS

environment.systemPackages = [ pkgs.gnutls ];

TODO Usage

󱌣 This module's usage documentation is incomplete. Complete it?

To connect to IRC use M-x =irc.

When in a circe buffer these keybindings will be available:

command	key	description
+irc/tracking-next-buffer	<localleader> a	Switch to the next active buffer
circe-command-JOIN	<localleader> j	Join a channel
+irc/send-message	<localleader> m	Send a private message
circe-command-NAMES	<localleader> n	List the names of the current channel
circe-command-PART	<localleader> p	Part the current channel
+irc/quit	<localleader> Q	Kill the current circe session and workgroup
circe-reconnect	<localleader> R	Reconnect the current server

TODO Configuration

󱌣 This module's configuration documentation is incomplete. Complete it?

Use set-irc-server! SERVER PLIST to configure IRC servers. Its second argument (a plist) takes the same arguments as circe-network-options:

;; if you omit =:host=, ~SERVER~ will be used instead.
(after! circe
  (set-irc-server! "irc.libera.chat"
    `(:tls t
      :port 6697
      :nick "doom"
      :sasl-username "myusername"
      :sasl-password "mypassword"
      :channels ("#emacs"))))

However, it is a obviously a bad idea to store your password in plaintext, so here are ways to avoid that:

TODO Pass: the unix password manager

󱌣 This section is outdated and needs to be rewritten. Rewrite it?

Pass is my tool of choice. I use it to manage my passwords. If you activate the doom-module::tools pass module you get an elisp API through which to access your password store.

set-irc-server! accepts a plist can use functions instead of strings. +pass-get-user and +pass-get-secret can help here:

(set-irc-server! "irc.libera.chat"
  `(:tls t
    :port 6697
    :nick "doom"
    :sasl-username ,(+pass-get-user   "irc/libera.chat")
    :sasl-password ,(+pass-get-secret "irc/libera.chat")
    :channels ("#emacs")))

But wait, there's more! This stores your password in a public variable which could be accessed or appear in backtraces. Not good! So we go a step further:

(set-irc-server! "irc.libera.chat"
  `(:tls t
    :port 6697
    :nick "doom"
    :sasl-username ,(+pass-get-user "irc/libera.chat")
    :sasl-password (lambda (&rest _) (+pass-get-secret "irc/libera.chat"))
    :channels ("#emacs")))

And you're good to go!

Note that +pass-get-user tries to find your username by looking for the fields listed in +pass-user-fields (by default login, user=, username= and email)=). An example configuration looks like

mysecretpassword
username: myusername

Emacs' auth-source API

auth-source is built into Emacs. As suggested in the circe wiki, you can store (and retrieve) encrypted passwords with it.

(setq auth-sources '("~/.authinfo.gpg"))

(defun my-fetch-password (&rest params)
  (require 'auth-source)
  (let ((match (car (apply #'auth-source-search params))))
    (if match
        (let ((secret (plist-get match :secret)))
          (if (functionp secret)
              (funcall secret)
            secret))
      (error "Password not found for %S" params))))

(defun my-nickserv-password (server)
  (my-fetch-password :user "forcer" :host "irc.libera.chat"))

(set-irc-server! "irc.libera.chat"
  '(:tls t
    :port 6697
    :nick "doom"
    :sasl-password my-nickserver-password
    :channels ("#emacs")))

TODO Troubleshooting

There are no known problems with this module. Report one?

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

󱌣 This module has no appendix yet. Write one?