app/irc: rewrite README
This commit is contained in:
Henrik Lissner
parent
19987df00a
commit
e8465bb5ff
1 changed files with 112 additions and 85 deletions
|
|
@ -1,97 +1,39 @@
|
||||||
#+TITLE: :app irc
|
#+TITLE: app/irc
|
||||||
|
#+DATE: June 11, 2017
|
||||||
This module turns adds an IRC client to Emacs ([[https://github.com/jorgenschaefer/circe][~circe~)]] with native notifications ([[https://github.com/eqyiel/circe-notifications][circe-notifications]]).
|
#+SINCE: v2.0.3
|
||||||
|
#+STARTUP: inlineimages
|
||||||
|
|
||||||
* Table of Contents :TOC:
|
* Table of Contents :TOC:
|
||||||
|
- [[Description][Description]]
|
||||||
|
- [[Module Flags][Module Flags]]
|
||||||
|
- [[Plugins][Plugins]]
|
||||||
- [[Dependencies][Dependencies]]
|
- [[Dependencies][Dependencies]]
|
||||||
- [[Configure][Configure]]
|
- [[Prerequisites][Prerequisites]]
|
||||||
|
- [[Features][Features]]
|
||||||
|
- [[An IRC Client in Emacs][An IRC Client in Emacs]]
|
||||||
|
- [[Configuration][Configuration]]
|
||||||
- [[Pass: the unix password manager][Pass: the unix password manager]]
|
- [[Pass: the unix password manager][Pass: the unix password manager]]
|
||||||
- [[Emacs' auth-source API][Emacs' auth-source API]]
|
- [[Emacs' auth-source API][Emacs' auth-source API]]
|
||||||
- [[Appendix][Appendix]]
|
- [[Troubleshooting][Troubleshooting]]
|
||||||
- [[Commands][Commands]]
|
|
||||||
|
* Description
|
||||||
|
This module turns adds an IRC client to Emacs with OS notifications.
|
||||||
|
|
||||||
|
** Module Flags
|
||||||
|
This module provides no flags.
|
||||||
|
|
||||||
|
** Plugins
|
||||||
|
+ [[https://github.com/jorgenschaefer/circe][circe]]
|
||||||
|
+ [[https://github.com/eqyiel/circe-notifications][circe-notifications]]
|
||||||
|
|
||||||
* Dependencies
|
* Dependencies
|
||||||
This module has no dependencies, besides =gnutls-cli= or =openssl= for secure connections.
|
This module requires =gnutls-cli= or =openssl= for secure connections.
|
||||||
|
|
||||||
* Configure
|
* Prerequisites
|
||||||
Use the ~:irc~ setting to configure IRC servers. Its second argument (a plist) takes the same arguments as ~circe-network-options~.
|
This module has no direct prerequisites.
|
||||||
|
|
||||||
#+BEGIN_SRC emacs-lisp :tangle no
|
|
||||||
(set! :irc "chat.freenode.net"
|
|
||||||
`(:tls t
|
|
||||||
:nick "doom"
|
|
||||||
:sasl-username "myusername"
|
|
||||||
:sasl-password "mypassword"
|
|
||||||
:channels ("#emacs")))
|
|
||||||
#+END_SRC
|
|
||||||
|
|
||||||
*It is a obviously a bad idea to store auth-details in plaintext,* so here are some ways to avoid that:
|
|
||||||
|
|
||||||
** Pass: the unix password manager
|
|
||||||
[[https://www.passwordstore.org/][Pass]] is my tool of choice. I use it to manage my passwords. If you activate the [[/modules/tools/password-store/README.org][:tools password-store]] module you get an elisp API through which to access your password store.
|
|
||||||
|
|
||||||
~:irc~'s plist can use functions instead of strings. ~+pass-get-user~ and ~+pass-get-secret~ can help here:
|
|
||||||
|
|
||||||
#+BEGIN_SRC emacs-lisp :tangle no
|
|
||||||
(set! :irc "chat.freenode.net"
|
|
||||||
`(:tls t
|
|
||||||
:nick "doom"
|
|
||||||
:sasl-username ,(+pass-get-user "irc/freenode.net")
|
|
||||||
:sasl-password ,(+pass-get-secret "irc/freenode.net")
|
|
||||||
:channels ("#emacs")))
|
|
||||||
#+END_SRC
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
#+BEGIN_SRC emacs-lisp :tangle no
|
|
||||||
(set! :irc "chat.freenode.net"
|
|
||||||
`(:tls t
|
|
||||||
:nick "doom"
|
|
||||||
:sasl-username ,(+pass-get-user "irc/freenode.net")
|
|
||||||
:sasl-password (lambda (&rest _) (+pass-get-secret "irc/freenode.net"))
|
|
||||||
:channels ("#emacs")))
|
|
||||||
#+END_SRC
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
#+BEGIN_SRC txt :tangle no
|
|
||||||
mysecretpassword
|
|
||||||
username: myusername
|
|
||||||
#+END_SRC
|
|
||||||
|
|
||||||
** Emacs' auth-source API
|
|
||||||
~auth-source~ is built into Emacs. As suggested [[https://github.com/jorgenschaefer/circe/wiki/Configuration#safer-password-management][in the circe wiki]], you can store (and retrieve) encrypted passwords with it.
|
|
||||||
|
|
||||||
#+BEGIN_SRC emacs-lisp :tangle no
|
|
||||||
(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.freenode.net"))
|
|
||||||
|
|
||||||
(set! :irc "chat.freenode.net"
|
|
||||||
'(:tls t
|
|
||||||
:nick "doom"
|
|
||||||
:sasl-password my-nickserver-password
|
|
||||||
:channels ("#emacs")))
|
|
||||||
#+END_SRC
|
|
||||||
|
|
||||||
* Appendix
|
|
||||||
** Commands
|
|
||||||
|
|
||||||
|
* Features
|
||||||
|
** An IRC Client in Emacs
|
||||||
To connect to IRC you can invoke the ~=irc~ function using =M-x= or your own
|
To connect to IRC you can invoke the ~=irc~ function using =M-x= or your own
|
||||||
custom keybinding.
|
custom keybinding.
|
||||||
|
|
||||||
|
|
@ -110,3 +52,88 @@ When in a circe buffer these keybindings will be available.
|
||||||
| ~circe-command-PART~ | =SPC m p= | Part the current channel |
|
| ~circe-command-PART~ | =SPC m p= | Part the current channel |
|
||||||
| ~+irc/quit~ | =SPC m Q= | Kill the current circe session and workgroup |
|
| ~+irc/quit~ | =SPC m Q= | Kill the current circe session and workgroup |
|
||||||
| ~circe-reconnect~ | =SPC m R= | Reconnect the current server |
|
| ~circe-reconnect~ | =SPC m R= | Reconnect the current server |
|
||||||
|
|
||||||
|
* Configuration
|
||||||
|
Use ~set-irc-server!~ to configure IRC servers. Its second argument (a plist)
|
||||||
|
takes the same arguments as ~circe-network-options~.
|
||||||
|
|
||||||
|
#+BEGIN_SRC emacs-lisp :tangle no
|
||||||
|
(set-irc-server! "chat.freenode.net"
|
||||||
|
`(:tls t
|
||||||
|
:nick "doom"
|
||||||
|
:sasl-username "myusername"
|
||||||
|
:sasl-password "mypassword"
|
||||||
|
:channels ("#emacs")))
|
||||||
|
#+END_SRC
|
||||||
|
|
||||||
|
*It is a obviously a bad idea to store auth-details in plaintext,* so here are
|
||||||
|
some ways to avoid that:
|
||||||
|
|
||||||
|
** Pass: the unix password manager
|
||||||
|
[[https://www.passwordstore.org/][Pass]] is my tool of choice. I use it to manage my passwords. If you activate the
|
||||||
|
[[../../../modules/tools/password-store/README.org][:tools password-store]] 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:
|
||||||
|
|
||||||
|
#+BEGIN_SRC emacs-lisp :tangle no
|
||||||
|
(set-irc-server! "chat.freenode.net"
|
||||||
|
`(:tls t
|
||||||
|
:nick "doom"
|
||||||
|
:sasl-username ,(+pass-get-user "irc/freenode.net")
|
||||||
|
:sasl-password ,(+pass-get-secret "irc/freenode.net")
|
||||||
|
:channels ("#emacs")))
|
||||||
|
#+END_SRC
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
#+BEGIN_SRC emacs-lisp :tangle no
|
||||||
|
(set-irc-server! "chat.freenode.net"
|
||||||
|
`(:tls t
|
||||||
|
:nick "doom"
|
||||||
|
:sasl-username ,(+pass-get-user "irc/freenode.net")
|
||||||
|
:sasl-password (lambda (&rest _) (+pass-get-secret "irc/freenode.net"))
|
||||||
|
:channels ("#emacs")))
|
||||||
|
#+END_SRC
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
#+BEGIN_SRC txt :tangle no
|
||||||
|
mysecretpassword
|
||||||
|
username: myusername
|
||||||
|
#+END_SRC
|
||||||
|
|
||||||
|
** Emacs' auth-source API
|
||||||
|
~auth-source~ is built into Emacs. As suggested [[https://github.com/jorgenschaefer/circe/wiki/Configuration#safer-password-management][in the circe wiki]], you can store
|
||||||
|
(and retrieve) encrypted passwords with it.
|
||||||
|
|
||||||
|
#+BEGIN_SRC emacs-lisp :tangle no
|
||||||
|
(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.freenode.net"))
|
||||||
|
|
||||||
|
(set-irc-server! "chat.freenode.net"
|
||||||
|
'(:tls t
|
||||||
|
:nick "doom"
|
||||||
|
:sasl-password my-nickserver-password
|
||||||
|
:channels ("#emacs")))
|
||||||
|
#+END_SRC
|
||||||
|
|
||||||
|
* TODO Troubleshooting
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue