README.md
1ZNC Push
2========
3
4[FAQ][] | [Example Configuration][examples] | [![Build Status](https://travis-ci.org/jreese/znc-push.svg?branch=master)](https://travis-ci.org/jreese/znc-push)
5
6
7Overview
8--------
9
10ZNC Push is a module for [ZNC][] that will send notifications to multiple push notification
11services, or SMS for any private message or channel highlight that matches a configurable set of
12conditions. ZNC Push current supports the following services:
13
14* [Boxcar][]
15* [Boxcar 2][]
16* [Pushover][]
17* [Pushsafer][]
18* [Prowl][]
19* [Supertoasty][]
20* [PushBullet][]
21* [Faast][]
22* [Nexmo][]
23* [Pushalot][]
24* [Pushjet][]
25* [Telegram][]
26* [Slack][]
27* [Discord][]
28* Custom URL GET requests
29
30This project is still a Work In Progress, but should be functional enough and stable enough
31for everyday usage. Users are more than welcome to submit feature requests or patches for
32discussion or inclusion. Bug reports and feature requests can be submitted to
33[the repository issues list][issues], or sent via email.
34
35For full functionality, this module requires ZNC version 0.090 or newer, but should compile
36and run with a reduced feature set on versions as old as 0.078, the current version used by
37Ubuntu. However, development and testing is done exclusively against the latest source
38distribution, so feedback on older releases of ZNC is needed to continue supporting them.
39If you want to use ZNC versions before 1.0 (0.206 or older), you will need to check out the
40"legacy" branch in order to compile it correctly.
41
42ZNC Push was created by [John Reese](http://johnmreese.com) and designed to fill a
43personal need. It may not fit your use cases, but any and all feedback would be greatly
44appreciated.
45
46
47Dependencies
48------------
49
50If you have installed ZNC from a Linux distribution's repository, you will most likely
51need to install the development package before building this module. On Ubuntu, this can
52be installed with:
53
54 $ sudo aptitude install znc-dev
55
56In order for this plugin to properly work, you will need to ensure you have the `ca-certificates`
57package on Ubuntu based systems. This is required for push to properly verify the certificate
58of the service it's sending your message to.
59
60 $ sudo aptitude install ca-certificates
61
62Optionally, if you want to use libcurl for http requests, you also need to install cURL
63development header files.
64
65On Ubuntu, development headers can be installed by installing `libcurl3-dev` or
66`libcurl4-openssl-dev` package:
67
68 $ sudo aptitude install libcurl4-openssl-dev
69
70
71Compiling
72---------
73
74If you have `make` installed, you can compile the module with:
75
76 $ make
77
78Otherwise, run the full command:
79
80 $ znc-buildmod push.cpp
81
82
83### Advanced
84
85If you would like to compile ZNC Push using libcurl for http requests, you must use:
86
87 $ make curl=yes
88
89If libcurl is not in the default system library paths, you will need to populate `$CXXFLAGS`
90with the appropriate GCC flags so that it can find and link ZNC Push with libcurl.
91
92Note: You are strongly encouraged to use libcurl transport. The reason for that is, that
93the default CSocket transport doesn't verify server's SSL certificate which leaves you
94vulnerable to MITM attacks. However, use of libcurl will *block* the main ZNC thread at every
95push notification; for installations with many users, libcurl is *not* yet ideal, even with
96the above security concerns in mind.
97
98
99Installation
100------------
101
102Copy the compiled module into your ZNC profile:
103
104 $ make install
105
106Now, load the module in ZNC:
107
108 /msg *status loadmod --type=user push
109
110Note: the below command will only enable ZNC Push for a single network in ZNC. Make sure you do not load it for both.
111
112 /msg *status loadmod push
113
114If you prefer to use ZNC's "controlpanel" module, you may do so like this:
115
116 /msg *status loadmod controlpanel
117 /msg *controlpanel loadmod push
118
119Then select the push service you want to use, and set your username and secret as needed.
120The secret is not your password, and can be obtained by logging into the service's website
121and looking in your profile or settings:
122
123 /msg *push set service pushover
124 /msg *push set username foo
125 /msg *push set secret ...
126
127If you're using Boxcar, you need to use the following command to send a subscription request
128to your account, before ZNC Push can start working:
129
130 /msg *push subscribe
131
132At this point, it should start sending notifications every time you get a private message
133or someone says your name in a channel. If this is everything you wanted, congratulations,
134you're done!
135
136For further, detailed instructions specific to each push notification service, the following
137documentation is available:
138
139* [Pushover](doc/pushover.md)
140* [Telegram](doc/telegram.md)
141
142
143Commands
144--------
145
146* `help`
147
148 Links you to this fine document.
149
150* `version`
151
152 Tells you the tagged build version currently running.
153
154* `set <option> <value>`
155
156 Allows you to modify configuration values.
157
158* `append <option> <value>`
159
160 Allows you to add a string to end of a configuration value. Automatically adds a
161 space to separate the appended value from the existing value.
162
163* `prepend <option> <value>`
164
165 Allows you to add a string to beginning of a configuration value. Automatically adds
166 a space to separate the prepended value from the existing value.
167
168* `get [<option>]`
169
170 Allows you to see current configuration values.
171
172* `unset <option>`
173
174 Allows you to reset a configuration option back to the default value.
175
176* `save <filename>`
177
178 Writes your options to a file with the given path and name.
179
180* `load <filename>`
181
182 Loads your options from a file with the given path and name. Caution should be taken,
183 as this will lose any options that aren't already saved to the given file.
184
185* `status [<context>]`
186
187 Check the status of current conditions. Specifying the "context" of either a channel
188 or nick name will provide status values specific to that context.
189
190* `subscribe`
191
192 Send a subscription request for the selected service to your configured account. This
193 is required by certain services, such as Boxcar, before ZNC Push can send any messages
194 to your account.
195
196* `send <message>`
197
198 Manually trigger a notification with the given message. Useful for testing to validate
199 credentials, etc.
200
201* `eval <expression>`
202
203 Evaluate the given expression in an empty context. Useful for testing to validate that
204 a given expression is properly formatted and does not contain invalid tokens.
205
206
207Configuration
208-------------
209
210### Keyword Expansion
211
212Some configuration options allow for optional keyword expansion, which happens
213while preparing to send the push notification. Expansion is performed each time
214a notification is sent. Expansion is only performed on options that explicitly
215 state that keyword expansion can be performed.
216
217
218The following keywords will be replaced with the appropriate value:
219
220* `{context}`: the channel or query window context
221* `{nick}`: the nick that sent the message
222* `{network}`: the network the message is coming from
223* `{datetime}`: [ISO 8601][] date string, in server-local time
224* `{unixtime}`: unix-style integer timestamp
225* `{title}`: the default title for the notification
226* `{message}`: the shortened message contents
227* `{username}`: the configured username string
228* `{secret}`: the configured secret string
229
230As an example, a value of "http://domain/{context}/{datetime}" would be expanded
231to something similar to "http://domain/#channel/2011-03-09 14:25:09", or
232"http://domain/{nick}/{unixtime}" to "http://domain/somenick/1299685136".
233
234
235### Push Services
236
237* `service` Default: ` `
238
239 Short name for the push notification service that you want to use. Must be set before
240 ZNC Push can send any notifications.
241
242 Possible values include:
243
244 * `boxcar`
245 * `pushover`
246 * `pushsafer`
247 * `prowl`
248 * `supertoasty`
249 * `pushbullet`
250 * `nexmo`
251 * `pushjet`
252 * `telegram`
253 * `slack`
254 * `discord`
255 * `url`
256
257* `username` Default: ` `
258
259 User account that should receive push notifications.
260
261 This option must be set when using Boxcar or Pushover. For Nexmo, this is the service/api key.
262
263 When using the custom URL service, if this option is set it will enable HTTP basic
264 authentication and be used as username.
265
266* `secret` Default: ` `
267
268 Authentication token for push notifications.
269
270 This option must be set when using Notify My Android, Pushover, Pushsafer, Prowl, Supertoasty, PushBullet, Nexmo, Pushjet, or Telegram.
271
272 When using the custom URL service, if this option is set it will enable HTTP basic
273 authentication and be used as password.
274
275* `target` Default: ` `
276
277 Device or target name for push notifications.
278
279 When using Pushover or PushBullet, this option allows you to specify a
280 single device to send notifications to; if blank or unset, notifications
281 will be sent to all devices. For Pushover, this is the device name; for
282 PushBullet, this is the device_iden.
283
284 When using Nexmo, this option allows you to specify the SMS destination
285 number. The number must be in international format.
286
287 When using Telegram, this is the id of the chat that receives the message.
288
289 When using Pushsafer, this is the id or group id of your devices.
290
291
292### Notifications
293
294* `message_content` Default: `{message}`
295
296 Message content that will be sent for the push notification. Keyword expansion is
297 performed on this value.
298
299* `message_length` Default: `100`
300
301 Maximum length of the notification message to be sent. The message will be nicely
302 truncated and ellipsized at or before this length is reached. A value of 0 (zero) will
303 disable this option.
304
305* `message_title` Default: `{title}`
306
307 Title that will be provided for the push notification. Keyword expansion is performed
308 on this value.
309
310 When using Nexmo, this value is where the SMS is "from". In most cases, you must use a valid number in international format.
311
312* `message_escape` Default: ` `
313
314 If set, keyword values will be escaped in this format before they are expanded in
315 `message_content`. Possible values are all that ZNC supports, most useful here will be
316 `HTML` or `URL`.
317
318 Note that the resulting string in `message_content` after keyword expansion will not be
319 escaped. If you need to escape characters for a service, you have to set the escaped
320 string to `message_content`.
321
322* `message_uri` Default: ` `
323
324 URI that will be sent with the push notification. This could be a web address or a
325 local scheme to access a mobile application. Keyword expansion is performed on this
326 value.
327
328 When using the custom URL service, this options allows you to specify the URL to send
329 a GET request to, and has keyword expansion performed on portions of it, including the
330 path and any query parameter values.
331
332* `message_uri_post` Default: `no`
333
334 When using the custom URL service, this option allows you to specify whether to use the
335 POST method instead of GET.
336
337* `message_uri_title` Default: ` `
338
339 If you're using Pushover.net or Pushsafer.com, you can specify a title for the `message_uri` option.
340
341* `message_priority` Default: ` `
342
343 Priority level that will be used for the push notification.
344 Currently supported only by Pushover.net, Notify My Android and Pushjet.
345
346* `message_sound` Default: ` `
347
348 Notification sound to play with the push notification.
349 Supported under Pushover, Pushsafer, Faast, and Boxcar 2. Must be chosen from the list of [Pushover sounds](https://pushover.net/api#sounds), [Pushsafer sounds](https://www.pushsafer.com/en/pushapi), [Faast sounds](http://developer.faast.io/) or [Boxcar 2 sounds](https://boxcar.uservoice.com/knowledgebase/articles/306788-how-to-send-your-boxcar-account-a-notification).
350
351
352### Conditions
353
354* `away_only` Default: `no`
355
356 If set to `yes`, notifications will only be sent if the user has set their `/away` status.
357
358 This condition requires version 0.090 of ZNC to operate, and will be disabled when
359 compiled against older versions.
360
361* `client_count_less_than` Default: `0`
362
363 Notifications will only be sent if the number of connected IRC clients is less than this
364 value. A value of 0 (zero) will disable this condition.
365
366* `highlight` Default: ` `
367
368 Space-separated list of highlight strings to match against channel messages using
369 case-insensitive, wildcard matching. Strings will be compared in order they appear in
370 the configuration value, and the first string to match will end the search, meaning
371 that earlier strings take priority over later values.
372
373 Individual strings may be prefixed with:
374
375 * `-` (hyphen) to negate the match, which makes the string act as a filter rather than
376 a search
377
378 * `_` (underscore) to trigger a "whole-word" match, where it must be surrounded by
379 whitespace to match the value
380
381 * `*` (asterisk) to match highlight strings that start with any of the above prefixes
382
383 As an example, a highlight value of `-pinto car` will trigger notification on the
384 message "I like cars", but will prevent notifications for "My favorite car is the Pinto"
385 *and* "I like pinto beans". Conversely, a highlight value of `car -pinto` will trigger
386 notifications for the first two messages, and only prevent notification of the last one.
387
388 As another example, a value of `_car` will trigger notification for the message "my car
389 is awesome", but will not match the message "I like cars".
390
391* `idle` Default: `0`
392
393 Time in seconds since the last activity by the user on any channel or query window,
394 including joins, parts, messages, and actions. Notifications will only be sent if the
395 elapsed time is greater than this value. A value of 0 (zero) will disable this condition.
396
397* `last_active` Default: `180`
398
399 Time in seconds since the last message sent by the user on that channel or query window.
400 Notifications will only be sent if the elapsed time is greater than this value. A value
401 of 0 (zero) will disable this condition.
402
403 Note that this condition keeps track of the last message sent to each channel and query
404 window separately, so a recent PM to Joe will not affect a notification sent from
405 channel #foo.
406
407* `last_notification` Default: `300`
408
409 Time in seconds since the last notification sent from that channel or query window.
410 Notifications will only be sent if the elapsed time is greater than this value. A value
411 of 0 (zero) will disable this condition.
412
413 Note that this condition keeps track of the last notification sent from each channel and
414 query window separately, so a recent PM from Joe will not affect a notification sent
415 from channel #foo.
416
417* `nick_blacklist` Default: ` `
418
419 Space-separated list of nicks. Applies to both channel mentions and query windows.
420 Notifications will only be sent for messages from nicks that are not present in this
421 list, using a case-insensitive comparison.
422
423 Note that wildcard patterns can be used to match multiple nicks with a single blacklist
424 entry. For example, `set nick_blacklist *bot` will not send notifications from nicks
425 like "channelbot", "FooBot", or "Robot". Care must be used to not accidentally
426 blacklist legitimate nicks with wildcards.
427
428* `network_blacklist` Default: ` `
429
430 Space-separated list of network names.
431 Notifications will only be sent for messages from networks that are not present in this
432 list, using a case-insensitive comparison.
433
434* `replied` Default: `yes`
435
436 If set to `yes`, notifications will only be sent if you have replied to the channel or
437 query window more recently than the last time a notification was sent for that context.
438
439* `context` Default: `*`
440
441 Similar to `highlight`, this is a space-separated list of strings to match against message
442 contexts using case-insensitive, wildcard matching. Strings will be compared in order
443 they appear in the configuration value, and the first string to match will end the search,
444 meaning that earlier strings take priority over later values.
445
446 Individual strings may be prefixed with a `-` (hyphen) to negate the match, which makes
447 the string act as a filter rather than a search.
448
449 The wildcard `*` (the default) may be used to match any context.
450
451 Examples:
452
453 * `#important` - Only messages from the #important channel that match all the other
454 conditions will be pushed
455 * `-#notimportant *` - Messages from #nonimportant will be ignored; everything else (`*`)
456 will be matched
457 * Set `channel_conditions` to `(highlight or context)` and `context` to `#iwantitall` -
458 Now you'll get notifications for every message in #iwantitall and messages that match your
459 highlight rules everywhere else.
460
461### Proxy
462
463* `proxy` Default: none
464
465 This option allows using a proxy service when libcurl support is enabled. The default
466 is no proxy. You must specify both the hostname/IP address and the port, as follows:
467
468 * myproxy.example.com:8080
469 * 203.0.113.5:8421
470 * [fc00:de4:ba::321a:4]:9000
471
472* `proxy_ssl_verify` Default: `yes`
473
474 This option allows you to disable SSL verification when using a proxy service. This
475 should only be done when you know the proxy service does not transparently pass SSL
476 connections through and you trust the proxy service. Set this to `no` to disable
477 SSL validation in libcurl.
478
479
480### Advanced
481
482* `channel_conditions` Default: `all`
483
484 This option allows customization of the boolean logic used to determine how conditional
485 values are used to filter notifications for channel messages. It evaluates as a full
486 boolean logic expression, including the use of sub-expressions. The default value of
487 `all` will bypass this evaluation and simply require all conditions to be true.
488
489 The expression consists of space-separated tokens in the following grammar:
490
491 * expression = `<expression> <operator> <expression>` | `( <expression> )` | `<value>`
492 * operator = `and` | `or`
493 * value = `true` | `false` | `<condition>`
494 * condition = `<any condition option>`
495
496 As a simple example, to replicate the default `all` value, would be the value of
497 `away_only and client_count_less_than and highlight and idle and last_active and
498 last_notification and nick_blacklist and replied`.
499
500 Alternately, setting a value of `true` would send a notification for *every* message,
501 while a value of `false` would *never* send a notification.
502
503 For a more complicated example, the value of `client_count_less_than and highlight and
504 (last_active or last_notification or replied) and nick_blacklist` would send a
505 notification if any of the three conditions in the sub-expression are met, while still
506 requiring all of the conditions outside of the parentheses to also be met.
507
508 Specifying `all` is equivalent to:
509
510 * `away_only and client_count_less_than and highlight and idle and last_active and last_notification and nick_blacklist and replied and context`
511
512* `query_conditions` Default: `all`
513
514 This option is more or less identical to `channel_conditions`, except that it is used
515 to filter notifications for private messages.
516
517 Specifying `all` is equivalent to:
518
519 * `away_only and client_count_less_than and idle and last_active and last_notification and nick_blacklist and replied`
520
521* `debug` Default: `off`
522
523 When set to `on`, this option enables debug output for various features, and is useful
524 in troubleshooting problems like failed push notifications. Debug output will show up
525 in your `*push` window.
526
527
528License
529-------
530
531This project is copyright John Reese, and licensed under the MIT license.
532I am providing code in this repository to you under an open source license.
533Because this is my personal repository, the license you receive to my code is
534from me and not from my employer. See the `LICENSE` file for details.
535
536
537
538[Boxcar]: http://boxcar.io
539[Boxcar 2]: http://boxcar.io
540[Pushover]: http://pushover.net
541[Pushsafer]: http://www.pushsafer.com
542[Prowl]: http://www.prowlapp.com
543[Supertoasty]: http://www.supertoasty.com
544[PushBullet]: https://www.pushbullet.com/
545[Faast]: http://faast.io/
546[Nexmo]: https://www.nexmo.com
547[Pushalot]: https://pushalot.com/
548[Pushjet]: http://pushjet.io
549[Telegram]: https://telegram.org/
550[Slack]: https://slack.com/
551[Discord]: https://discord.gg
552
553[faq]: https://github.com/jreese/znc-push/blob/master/doc/faq.md
554[examples]: https://github.com/jreese/znc-push/blob/master/doc/examples.md
555[issues]: https://github.com/jreese/znc-push/issues
556[ZNC]: http://en.znc.in "ZNC, an advanced IRC bouncer"
557[ISO 8601]: http://en.wikipedia.org/wiki/ISO_8601 "ISO 8601 Date Format"
558
559<!-- vim:set ft= expandtab tabstop=4 shiftwidth=4: -->
560