-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy patherc.info
2608 lines (2066 loc) · 114 KB
/
erc.info
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is docbCydIO.info, produced by makeinfo version 6.8 from erc.texi.
This manual is for ERC 5.6.1 from GNU ELPA.
Copyright © 2005–2025 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover Texts
being “A GNU Manual,” and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
“GNU Free Documentation License”.
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”
All Emacs Lisp code contained in this document may be used,
distributed, and modified without restriction.
INFO-DIR-SECTION Emacs network features
START-INFO-DIR-ENTRY
* ERC: (erc). Powerful and extensible IRC client for Emacs.
END-INFO-DIR-ENTRY
File: docbCydIO.info, Node: Top, Next: Introduction, Up: (dir)
ERC
***
This manual is for ERC 5.6.1 from GNU ELPA.
Copyright © 2005–2025 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover Texts
being “A GNU Manual,” and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
“GNU Free Documentation License”.
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”
All Emacs Lisp code contained in this document may be used,
distributed, and modified without restriction.
* Menu:
* Introduction:: What is ERC?
* Getting Started:: Quick Start guide to using ERC.
* Keystroke Summary:: Keystrokes used in ERC buffers.
* Modules:: Available modules for ERC.
* Advanced Usage:: Cool ways of using ERC.
* Getting Help and Reporting Bugs::
* History:: The history of ERC.
* GNU Free Documentation License:: The license for this documentation.
* Concept Index:: Search for terms.
— The Detailed Node Listing —
Getting Started
* Sample Session:: Example of connecting to the ‘#emacs’ channel
* Special Features:: Differences from standalone IRC clients
Advanced Usage
* Connecting:: Ways of connecting to an IRC server.
* SASL:: Authenticating via SASL.
* Sample Configuration:: An example configuration file.
* Integrations:: Integrations available for ERC.
* Options:: Options that are available for ERC.
File: docbCydIO.info, Node: Introduction, Next: Getting Started, Prev: Top, Up: Top
1 Introduction
**************
ERC is a powerful, modular, and extensible IRC client for Emacs. It has
been included in Emacs since 2006 (*note History::) and is also
available on GNU ELPA.
IRC is short for Internet Relay Chat. When using IRC, you can
communicate with other users on the same IRC network. There are many
different networks—if you search for “IRC networks” in your favorite
search engine, you will find up-to-date lists of IRC networks catering
to various interests and topics.
To use IRC, you need an IRC client such as ERC. Using the client, you
connect to an IRC server. Once you’ve done that, you will have access
to all available channels on that server’s network. A channel is
basically a chat room, and what you type in a channel will be shown to
all other users in that channel. You can be in several channels at the
same time—ERC will show each channel in its own buffer.
IRC channel names always begin with a ‘#’ character. For example,
the Emacs channel on Libera.Chat is ‘#emacs’, and the ERC channel is
‘#erc’. Do not confuse them with the hashtags used on many social media
platforms.
You can also send private messages to other IRC users on the same
network, even if they are not in the same channels as you.
ERC comes with the following capabilities enabled by default.
• Flood control
• Timestamps
• Join channels automatically
• Buttonize URLs, nicknames, and other text
• Wrap long lines
• Highlight or remove IRC control characters
• Highlight pals, fools, and other keywords
• Detect netsplits
• Complete nicknames and commands in a programmable fashion
• Make displayed lines read-only
• Input history
• Track channel activity in the mode-line
File: docbCydIO.info, Node: Getting Started, Next: Keystroke Summary, Prev: Introduction, Up: Top
2 Getting Started
*****************
The command ‘M-x erc’ will start ERC and prompt for the server to
connect to. If you’re unsure of which server or network to connect to,
we suggest starting with “irc.libera.chat”. There you will find the
‘#emacs’ channels where you can chat with other Emacs users, and if
you’re having trouble with ERC, you can join the ‘#erc’ channel and ask
for help there.
At some point in your ERC journey, you’ll inevitably want to change
how the client looks and behaves. As with other Emacs applications, the
typical place to store your settings is your ‘init.el’. If you would
rather use the Customize interface, a good place to start is by running
‘M-x customize-group <RET> erc <RET>’. In particular, ERC comes with
lots of modules that may be enabled or disabled; to select which ones
you want, do ‘M-x customize-variable <RET> erc-modules <RET>’.
* Menu:
* Sample Session:: Example of connecting to the #emacs channel
* Special Features:: Differences from standalone IRC clients
File: docbCydIO.info, Node: Sample Session, Next: Special Features, Up: Getting Started
2.1 Sample Session
==================
This example ERC session describes how to connect to the ‘#emacs’
channel on Libera.Chat. Also worth checking out is Libera’s own
introductory guide to IRC, <https://libera.chat/guides/basics>, which
presents a more comprehensive overview without instructions specific to
ERC.
• Connect to Libera.Chat
Run ‘M-x erc <RET>’. Use ‘irc.libera.chat’ for the server and
‘6667’ for the port. Choose a nickname, and hit <y> when asked if
you’d prefer to connect over TLS.
• Get used to the interface
Switch to the ‘Libera.Chat’ buffer if you’re not already there.
ERC calls this a “server buffer”, and it must exist for the
duration of the session. You will likely see some messages about
“ident”, authentication, and the like, followed by information
describing the current server and the network.
• Join the #emacs channel
In the server buffer, type ‘/join #emacs <RET>’ at the prompt. ERC
will create a new buffer called ‘#emacs’. If you’ve already
configured ERC, you may need to switch to it manually. Once there,
you will see the channel’s “topic” in the buffer’s header line
(*note (elisp)Header Lines::) and a list of people currently in the
channel. If you can’t see the full topic, mouse over it or type
‘/topic <RET>’ at the prompt.
• Register your nickname with Libera.Chat
In order to access essential network features, like speaking in
certain channels and participating in private conversations, you’ll
likely have to “register” your nickname. To do so, switch to the
‘Libera.Chat’ buffer and type ‘/msg NickServ register ‘<password>’
‘<email>’ <RET>’, replacing ‘<password>’ and ‘<email>’ with your
desired account password and contact email (both sans quotes). The
server should tell you that the operation was successful. See the
official Libera.Chat docs if you encounter problems.
In addition to creating an account, this process also
“authenticates” you to the network’s “account services” system for
the duration of the session. In other words, you’re now logged in.
However, when you connect in the future, you’ll need to
authenticate again by providing the same credentials somehow. When
you’re finished with this walk through, see “Next Steps”, below, to
learn some ways to do that.
• Talk to people in the channel
Switch back to the ‘#emacs’ buffer and type a message at the
prompt, hitting ‘RET’ once satisfied. Everyone in the channel will
now see your message.
• Open a query buffer to talk to someone
If you want to talk with someone in private, type ‘/query ‘<nick>’
<RET>’, replacing ‘<nick>’ with the their nickname. As before,
with the server buffer, if this new “query buffer” doesn’t appear
in the current window, you may have to switch to it. Regardless,
its name should match ‘<nick>’. Once there, type something at the
prompt and hit ‘RET’, and the other party will see it.
Keep in mind that if either party isn’t authenticated, you may not
be able to converse at all. Also, depending on the network,
certain social conventions may apply to the practice of direct
messaging. As a general rule, queries should usually be reserved
for personal matters rather than technical help, which can often
benefit (and benefit _from_) a larger audience.
• Next steps
Try joining another channel, such as ‘#erc’, where ERC users and
developers hang out (*note Official IRC channels:: for more on the
history of ‘#emacs’). For ideas on various options to customize,
*note Sample Configuration::. To learn how ERC can authenticate
you to the network automatically whenever you connect, *note
SASL::. As always, if you encounter problems, *note Getting Help
and Reporting Bugs::.
File: docbCydIO.info, Node: Special Features, Prev: Sample Session, Up: Getting Started
2.2 Special Features
====================
ERC has some features that distinguish it from some IRC clients.
• multiple channels and multiple servers
Every channel is put in a separate buffer. Several IRC servers may
be connected to at the same time.
• private message separation
Private conversations are treated as channels, and are put into
separate buffers in Emacs. We call these “query buffers”.
• highlighting
Some occurrences of words can be highlighted, which makes it easier
to track different kinds of conversations.
• notification
ERC can notify you that certain users are online.
• channel tracking
Channels can be hidden and conversation continue in the background.
You are notified when something is said in such a channel that is
not currently visible. This makes it easy to get Real Work done
while still maintaining an IRC presence.
• nick completion
ERC can complete words upon hitting ‘TAB’, which eases the writing
of nicknames in messages.
• history
Past actions are kept in history rings for future use. To navigate
a history ring, hit ‘M-p’ to go backwards and ‘M-n’ to go forwards.
• multiple languages
Different channels and servers may have different language
encodings.
multiple languages. Please contact the Emacs developers if you are
interested in helping with the translation effort.
• user scripting
Users can load scripts (e.g., auto greeting scripts) when ERC
starts up.
It is also possible to make custom IRC commands, if you know a
little Emacs Lisp. Just make an Emacs Lisp function and call it
‘erc-cmd-NEWCOMMAND’, where ‘NEWCOMMAND’ is the name of the new
command in capital letters.
• auto reconnect
If the connection goes away at some point, ERC will try to
reconnect automatically. If it fails to reconnect, and you want to
try to manually reestablish the connection at some later point,
switch to an ERC buffer and run the ‘/RECONNECT’ command.
File: docbCydIO.info, Node: Keystroke Summary, Next: Modules, Prev: Getting Started, Up: Top
3 Keys Used in ERC
******************
This is a summary of keystrokes available in every ERC buffer.
‘C-a or <home> (erc-bol)’
Go to beginning of line or end of prompt.
‘<RET> (erc-send-current-line)’
Send the current line
‘<TAB> (completion-at-point or erc-button-next)’
If at prompt, complete the current word. Otherwise, move to the
next link or button.
‘M-<TAB> (ispell-complete-word)’
Complete the given word, using ispell.
‘C-c C-a (erc-bol)’
Go to beginning of line or end of prompt.
‘C-c C-b (erc-switch-to-buffer)’
Use ‘read-buffer’ to prompt for a ERC buffer to switch to.
‘C-c C-c (erc-toggle-interpret-controls)’
Toggle interpretation of control sequences in messages.
‘C-c C-d (erc-input-action)’
Interactively input a user action and send it to IRC.
‘C-c C-e (erc-toggle-ctcp-autoresponse)’
Toggle automatic CTCP replies (like VERSION and PING).
‘C-c C-f (erc-toggle-flood-control)’
Toggle use of flood control on sent messages.
‘C-c <TAB> (erc-invite-only-mode)’
Turn on the invite only mode (+i) for the current channel.
‘C-c C-j (erc-join-channel)’
Join channel. If point is at the beginning of a channel name, use
that as default.
‘C-c C-k (erc-go-to-log-matches-buffer)’
Interactively open an erc-log-matches buffer
‘C-c C-l (erc-save-buffer-in-logs)’
Append buffer contents to the log file, if logging is enabled.
‘C-c C-n (erc-channel-names)’
Run "/names #channel" in the current channel.
‘C-c C-o (erc-get-channel-mode-from-keypress)’
Read a key sequence and call the corresponding channel mode
function. After doing ‘C-c C-o’, type in a channel mode letter.
‘C-g’ means quit. ‘RET’ lets you type more than one mode at a
time. If ‘l’ is pressed, ‘erc-set-channel-limit’ gets called. If
‘k’ is pressed, ‘erc-set-channel-key’ gets called. Anything else
will be sent to ‘erc-toggle-channel-mode’.
‘C-c C-p (erc-part-from-channel)’
Part from the current channel and prompt for a reason.
‘C-c C-q (erc-quit-server)’
Disconnect from current server after prompting for reason.
‘C-c C-r (erc-remove-text-properties-region)’
Clears the region (start,end) in object from all colors, etc.
‘C-c C-t (erc-set-topic)’
Prompt for a topic for the current channel.
‘C-c C-u (erc-kill-input)’
Kill current input line using ‘erc-bol’ followed by ‘kill-line’.
File: docbCydIO.info, Node: Modules, Next: Advanced Usage, Prev: Keystroke Summary, Up: Top
4 Modules
*********
One way to add functionality to ERC is to customize which of its many
modules are loaded.
You can do this by typing ‘C-h v erc-modules <RET>’ and clicking
‘customize’ near the bottom of the resulting help buffer, where it says
“You can _customize_ this variable.” When removing a module outside of
Customize, you may wish to ensure it’s disabled by invoking its
associated minor-mode toggle with a nonpositive prefix argument, for
example, ‘C-u - M-x erc-spelling-mode <RET>’. Additionally, if you plan
on loading third-party modules that perform atypical setup on
activation, you may need to arrange for calling ‘erc-update-modules’ in
your init file. Examples of such setup might include registering an
‘erc-before-connect’ hook, advising ‘erc-open’, and modifying
‘erc-modules’ itself. On Emacs 29 and greater, you can also run
‘erc-update-modules’ indirectly, via ‘(setopt erc-modules erc-modules)’.
The following is a list of available modules.
‘autoaway’
Set away status automatically
‘autojoin’
Join channels automatically
‘bufbar’
List buffers belonging to a connection in a side window; part of
Custom group ‘erc-status-sidebar’
‘button’
Buttonize URLs, nicknames, and other text
‘capab-identify’
Mark unidentified users on freenode and other servers supporting
CAPAB.
‘command-indicator (local)’
Echo command lines for “slash commands”, like ‘/JOIN #erc’ and
‘/HELP join’
‘completion (aka pcomplete)’
Complete nicknames and commands (programmable)
‘fill’
Wrap long lines
‘identd’
Launch an identd server on port 8113
‘irccontrols’
Highlight or remove IRC control characters
‘keep-place’
Remember your position in buffers
‘log’
Save buffers in logs
‘match’
Highlight pals, fools, and other keywords
‘menu’
Display a menu in ERC buffers
‘netsplit’
Detect netsplits
‘nicks (local)’
Automatically colorize nicks
‘nickbar’
List participating nicks for the current target buffer in a side
window; part of Custom group ‘erc-speedbar’
‘noncommands’
Don’t display non-IRC commands after evaluation
‘notify’
Notify when the online status of certain users changes
‘notifications’
Send you a notification when you get a private message, or your
nickname is mentioned
‘page’
Process CTCP PAGE requests from IRC
‘readonly’
Make displayed lines read-only
‘replace’
Replace text in messages
‘ring’
Enable an input history
‘sasl (local)’
Enable SASL authentication
‘scrolltobottom’
Scroll to the bottom of the buffer
‘services’
Identify to Nickserv (IRC Services) automatically
‘smiley’
Convert smileys to pretty icons
‘sound’
Play sounds when you receive CTCP SOUND requests
‘spelling’
Check spelling of messages
‘stamp’
Add timestamps to messages
‘track’
Track channel activity in the mode-line
‘truncate’
Truncate buffers to a certain size
‘unmorse’
Translate morse code in messages
Auxiliary Modules
-----------------
For various reasons, the following modules aren’t currently listed in
the Custom interface for ‘erc-modules’, but feel free to add them
explicitly. They may be managed by another module or just deemed too
niche or experimental.
‘fill-wrap (local)’
Wrap long lines using ‘visual-line-mode’
‘keep-place-indicator (local)’
Remember your place in buffers with a visible reminder; activated
interactively or via something like ‘erc-join-hook’
‘querypoll (local)’
Update query participant data by continually polling the server
‘services-regain (local)’
Automatically ask NickServ to reclaim your nick when reconnecting;
experimental as of ERC 5.6
Required Modules
----------------
Note that some modules are essential to core IRC operations and thus not
listed above. You can nevertheless still remove these, but doing so
demands special precautions to avoid degrading the user experience. At
present, the only such module is ‘networks’, whose library ERC always
loads anyway.
Local Modules
-------------
All modules operate as minor modes under the hood, and newer ones are
mostly defined as buffer-local. These so-called “local modules” are a
work in progress, and their behavior and interface are subject to
change. As of ERC 5.6, the only practical differences are as follows:
1. “Mode variables”, a.k.a. “control variables”, like
‘erc-sasl-mode’, retain their values across IRC sessions.
2. Removing a local module from ‘erc-modules’ via Customize not only
disables its mode but also kills its mode variable in all ERC
buffers.
3. “Mode commands”, like ‘erc-sasl-mode’ and its one-way variants
‘erc-sasl-enable’ and ‘erc-sasl-disable’, behave differently than
their global counterparts.
To detect whether a module is local, examine its mode variable. For
example, if you run ‘C-h v erc-sasl-mode <RET>’, you’ll notice it says
“Automatically becomes buffer-local when set”. You can do the same in
Lisp code with ‘(local-variable-if-set-p 'erc-sasl-mode)’.
In an ERC buffer, a local module is either enabled or disabled if its
mode variable has a local binding. This “activation state” may
contradict a module’s presence in ‘erc-modules’, namely, in buffers
where it isn’t applicable or has otherwise been disabled. In fact, a
local module’s membership in ‘erc-modules’ does nothing more than
guarantee
1. its setup code runs in _new_ buffers
2. its mode variable has a local binding in all affected buffers
In keeping with this, all built-in local modules disable themselves
in nonapplicable buffers rather than remain no-ops. Some also take
strides to enable themselves elsewhere when needed or at least emit a
helpful error. For example, the ‘nicks’ module does both in server
buffers, where it shares resources among the target buffers it primarily
services. ERC expects third-party local modules to mimic this pattern
and to document what buffer types they operate in: server, query, or
channel. (In the case of ‘nicks’, it would be all three: it’s
“session-local”.)
In ERC, you can think of an IRC session as a group of buffers sharing
the same connection to a server. After a connection ends, this
association endures so that ERC can revive the session when
reconnecting. As it does with connection parameters, ERC therefore
persists a local module’s activation state through reconnections,
reenabling modules that were previously active while ensuring others are
disabled. A couple related things to note here are
1. each module must manage its own application data and restore or
reset its environment accordingly
2. session persistence is less predictable if a user changes the
makeup of ‘erc-modules’ between sessions
When it comes to a local module’s various activation commands, the
primary mode command, like ‘erc-sasl-mode’, for example, only affects
the current buffer, but its unidirectional cousins, like
‘erc-sasl-enable’ and ‘erc-sasl-disable’, operate on all buffers
belonging to their connection (when called interactively). And unlike
global toggles, none of these ever mutates ‘erc-modules’.
Loading
-------
ERC loads internal modules in alphabetical order and third-party modules
as they appear in ‘erc-modules’. When defining your own module, take
care to ensure ERC can find it. An easy way to do that is by mimicking
the example in the doc string for ‘define-erc-module’ (also shown
below). For historical reasons, ERC falls back to ‘require’ing
features. For example, if some module ‘my-module’ in ‘erc-modules’
lacks a corresponding ‘erc-my-module-mode’ command, ERC will attempt to
load the library ‘erc-my-module’ prior to connecting. If this fails,
ERC signals an error. Users defining personal modules in an init file
should ‘(provide 'erc-my-module)’ somewhere to placate ERC. Dynamically
generating modules on the fly is not supported.
Some older built-in modules have a second name along with a second
minor-mode toggle, which is just a function alias for its primary
counterpart. For practical reasons, ERC does not define a corresponding
variable alias because contending with indirect variables complicates
bookkeeping tasks, such as persisting module state across IRC sessions.
New modules should definitely avoid defining aliases without a good
reason.
Some packages have been known to autoload a module’s definition
instead of its minor-mode command, which severs the link between the
library and the module. This means that enabling the mode by invoking
its command toggle isn’t enough to load its defining library. As such,
packages should only supply module-related autoload cookies with an
actual ‘autoload’ form for their module’s minor-mode command, like so:
;;;###autoload(autoload 'erc-my-module-mode "erc-my-module" nil t)
(define-erc-module my-module nil
"My doc string."
((add-hook 'erc-insert-post-hook #'erc-my-module-on-insert-post))
((remove-hook 'erc-insert-post-hook #'erc-my-module-on-insert-post)))
As implied earlier, packages can usually omit such cookies entirely so
long as their module’s prefixed name matches that of its defining
library and the library’s provided feature.
Finally, packages have also been observed to run ‘erc-update-modules’
in top-level forms, forcing ERC to take special precautions to avoid
recursive invocations. Another unfortunate practice is mutating
‘erc-modules’ itself upon loading ‘erc’, possibly by way of an autoload.
Doing this tricks Customize into displaying the widget for ‘erc-modules’
incorrectly, with built-in modules moved from the predefined checklist
to the user-provided free-form area.
File: docbCydIO.info, Node: Advanced Usage, Next: Getting Help and Reporting Bugs, Prev: Modules, Up: Top
5 Advanced Usage
****************
* Menu:
* Connecting:: Ways of connecting to an IRC server.
* SASL:: Authenticating via SASL.
* Sample Configuration:: An example configuration file.
* Integrations:: Integrations available for ERC.
* Options:: Options that are available for ERC.
— Detailed Node Listing —
Integrations
* URL:: Opening IRC URLs in ERC.
* SOCKS:: Connecting to IRC with a SOCKS proxy.
* auth-source:: Retrieving auth-source entries with ERC.
* display-buffer:: Controlling how ERC displays buffers.
File: docbCydIO.info, Node: Connecting, Next: SASL, Up: Advanced Usage
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
• 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
(*note 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
*Note (auth)Help for users::, for more on the ‘.authinfo’/‘.netrc’
backend of ‘auth-source’. For other uses of auth-source throughout
ERC, *note ERC’s auth-source integration: auth-source.
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 (*note
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. (*Note SASL in ERC: SASL.)
-- 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. *Note ERC’s auth-source
integration: auth-source, 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.
File: docbCydIO.info, Node: SASL, Next: Sample Configuration, Prev: Connecting, Up: Advanced Usage
5.2 Authenticating via SASL
===========================
If you’ve used SASL elsewhere, you can probably skip to the examples
below. Otherwise, if you haven’t already registered with your network,
please do so now, referring to the network’s own instructions for
details. If you’re new to IRC and using a bouncer, know that you
probably won’t be needing this for the client-to-bouncer connection.
When you’re ready to get started, add ‘sasl’ to ‘erc-modules’, like
you would any other module. If unsure which “mechanism” to choose,
stick with the default of ‘PLAIN’. Then try ‘C-u M-x erc-tls <RET>’,
and give your account name for the ‘user’ parameter and your account
password for the ‘server password’.
-- User Option: erc-sasl-mechanism
The name of an SASL subprotocol type as a _lowercase_ symbol. The
value can be one of the following:
‘plain’ or ‘scram’ (“password-based”)
Here, “password” refers to your account password, which is
usually your ‘NickServ’ password. To make this work,
customize ‘erc-sasl-user’ and ‘erc-sasl-password’ or specify
the ‘:user’ and ‘:password’ keyword arguments when invoking
‘erc-tls’.
‘external’ (via client TLS certificate)
This works in conjunction with the ‘:client-certificate’
keyword offered by ‘erc-tls’. Just ensure you’ve registered
your fingerprint with the network beforehand. The fingerprint
is usually a SHA1 or SHA256 digest in either "normalized" or
"openssl" forms. The first is lowercase without delims
(‘deadbeef’) and the second uppercase with colon seps
(‘DE:AD:BE:EF’). These days, there’s usually a ‘CERT ADD’
command offered by NickServ that can register you
automatically if you issue it while connected with a client
cert. *Note client-certificate::.
Additional considerations:
1. Most IRCds will allow you to authenticate with a client
cert but without the hassle of SASL (meaning you may not
need this module).
2. Technically, EXTERNAL merely indicates that an
out-of-band mode of authentication is in effect (being
deferred to), so depending on the specific application or
service, there’s a remote chance your server has
something else in mind.
‘ecdsa-nist256p-challenge’
This mechanism is quite complicated and currently requires the
external ‘openssl’ executable, so please use something else if
at all possible. Ignoring that, specify your key file (e.g.,
‘~/pki/mykey.pem’) as the value of ‘erc-sasl-password’, and
then configure your network settings. On servers running
Atheme services, you can add your public key with ‘NickServ’
like so:
ERC> /msg NickServ set property \
pubkey AgGZmlYTUjJlea/BVz7yrjJ6gysiAPaQxzeUzTH4hd5j
(You may be able to omit the ‘property’ subcommand.)
-- User Option: erc-sasl-user
This should be your network account username, typically the same
one registered with nickname services. Specify this when your
NickServ login differs from the ‘:user’ you’re connecting with.
*Note username parameter::.
-- User Option: erc-sasl-password
As noted elsewhere, the entry-point ‘:password’ param was
originally intended for traditional “server passwords,” but these