about summary refs log tree commit diff
path: root/README.7
blob: aba0d2a82a4658b91bdbd136a4f8e69f6146e45b (plain) (blame)
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
.Dd July 16, 2022
.Dt README 7
.Os "Causal Agency"
.
.Sh NAME
.Nm pounce
.Nd IRC pouncer :3
.
.Sh DESCRIPTION
.Xr pounce 1
is a multi-client, TLS-only IRC bouncer.
It maintains a persistent connection
to an IRC server,
acting as a proxy and buffer
for a number of clients.
When a client connects,
any messages received
since it last disconnected
will be relayed to it.
Unlike some other bouncers,
.Nm
uses a single buffer
for all IRC messages,
which acts as a queue
from which each client
reads messages independently.
.
.Pp
.Nm
speaks regular modern IRC
to both servers and clients,
using the
.Sy server-time
extension to indicate
when messages originally occurred.
Clients identify themselves to
.Nm
by their IRC usernames.
See
.Xr QUIRKS 7
for notes on connecting
.Nm
with particular networks and clients.
.
.Sh RATIONALE
As a former
.Xr znc 1
user,
I was dissatisfied with the multi-client experience it offered.
I wanted to connect from both my laptop and my phone
and have full chat history on both.
With
.Xr znc 1 ,
my options were either having both clients
spammed with redundant history every time they connect,
or having one client consume the buffer
and the other get no history at all.
.
.Pp
With a multiple-consumer ring buffer,
each client has its own place in the history
and can be brought up to date independently.
Additionally,
by expecting clients to implement the
.Sy server-time
extension,
all events can be accurately replayed,
rather than being limited to messages.
.
.Sh INSTALLING
.Nm
requires
.Sy libtls ,
provided by either
.Lk https://git.causal.agency/libretls/about LibreTLS
(for OpenSSL)
or by LibreSSL.
.Nm
and
.Sy libtls
may be packaged for your system.
Check the Repology pages for
.Lk https://repology.org/project/pounce/versions pounce
and
.Lk https://repology.org/project/libretls/versions libretls .
.
.Pp
.Nm
primarily targets
.Ox ,
where it is sandboxed with
.Xr pledge 2
and
.Xr unveil 2 .
.Fx ,
Linux and macOS
are also supported.
.Bd -literal -offset indent
\&./configure
make all
sudo make install
.Ed
.
.Pp
If installing
.Sy libtls
manually to
.Pa /usr/local ,
for example,
make sure
.Pa /usr/local/lib
appears in
.Pa /etc/ld.so.conf
or
.Pa /etc/ld.so.conf.d/*
and be sure to run
.Xr ldconfig 8
once the library is installed.
Set
.Ev PKG_CONFIG_PATH
for
.Nm ./configure
to find it.
.Bd -literal -offset indent
PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./configure
.Ed
.
.Pp
On
.Fx
and
.Ox
the recommended way to run
.Nm
is with the process supervisor
.Lk https://git.causal.agency/catsit catsit .
.
.Ss Additional Components
Additional functionality can be provided
by special-purpose clients connected to
.Nm .
.Bl -inset
.It Lk https://git.causal.agency/litterbox litterbox
provides logging and search.
.It Xr pounce-notify 1
provides notifications
by running an external command.
Configure with
.Fl \-enable-notify
to build.
.It Xr pounce-palaver 1
provides push notifications
for the Palaver IRC app.
Configure with
.Fl \-enable-palaver
to build.
Requires
.Sy libcurl
and
.Sy libsqlite3 .
.It Xr pounce-edit 1
provides configuration editing
over IRC.
Configure with
.Fl \-enable-edit
to build.
.El
.
.Sh FILES
.Bl -tag -width "dispatch.c" -compact
.It Pa bounce.h
declarations and common functions
.It Pa bounce.c
configuration and event loop
.It Pa local.c
local server binding
.It Pa server.c
remote server connection
.It Pa client.c
remote client connections
.It Pa state.c
state shared between clients
.It Pa ring.c
buffer between server and clients
.It Pa config.c
.Xr getopt_long 3 Ns -integrated
configuration parsing
.It Pa xdg.c
XDG base directories
.It Pa dispatch.c
SNI socket dispatch
.El
.
.Sh CONTRIBUTING
The upstream URL of this project is
.Aq Lk https://git.causal.agency/pounce .
Contributions in any form can be sent to
.Aq Mt list+pounce@causal.agency .
For sending patches by email, see
.Aq Lk https://git-send-email.io .
Mailing list archives are available at
.Aq Lk https://causal.agency/list/pounce.html .
.
.Pp
Monetary contributions can be
.Lk https://liberapay.com/june/donate "donated via Liberapay" .
.
.Sh SEE ALSO
.Xr calico 1 ,
.Xr pounce 1
.
.Pp
Central logging with full-text search:
.Lk https://git.causal.agency/litterbox "litterbox"
.
.Rs
.%A June McEnroe
.%T IRC Suite
.%U https://text.causal.agency/010-irc-suite.txt
.%D June 19, 2020
.Re