summaryrefslogtreecommitdiff
path: root/xN/xN.adoc
blob: 1f5404fa616d4fd7481dc05f60f6b3c0bd48bb57 (plain)
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
xN(1)
=====
:doctype: manpage
:manmanual: xK Manual
:mansource: xK {release-version}

Name
----
xN - IRC notifier

Synopsis
--------
*xN* [_OPTION_]... IRC-URL...

Description
-----------
*xN* is a simple IRC notifier, sending the text it receives on its standard
input to all IRC targets specified by its command line arguments.

The input text is forced to validate as UTF-8, and it is _not_ split
automatically to comply with the maximum IRC message length.
Thus, make sure to make the lines short, or they will be trimmed by the servers.

*xN* does not attempt to appease flood detectors.

Options
-------
*-debug*::
	Print incoming IRC traffic, which may help in debugging any issues.

*-version*::
	Output version information and exit.

URL format
----------
*xN* accepts URLs describing IRC users and channels, roughly as specified by
the Internet Draft _draft-butcher-irc-url-04.txt_.  Note, however, that close
to no validation is done on these, and you should not pass URLs from untrusted
sources, so as to avoid command or parameter injection.

Any provided username will be propagated to the nickname, username,
and realname.  The default value for these is the name of your system user.

As an extension, you may use the following options:

*skipjoin*::
	Do not JOIN channels before sending messages to them.
	This requires channels to allow external messages
	(which are disabled by channel mode *+n*).
*usenotice*::
	Send a NOTICE rather than a PRIVMSG, which distinguishes automated messages,
	and is more appropriate for bots.

Examples
--------
 $ uptime | xN 'irc://uptime@localhost/%23watch?skipjoin&usenotice'

Send *uptime*(1) information as an external notice to channel *#watch*
on the local server, using the standard port *6667*.

 $ fortune -s | xN ircs://ohayou@irc.libera.chat/john,isuser

Greet user *john* with a fortune for this day.  In compliance with _RFC 7194_,
the default TLS port is assumed to be *6697*.

 $ xN 'ircs://agent:Password123@irc.cia.gov:1337/#hq?key=123456' <<EOF
 The red fox trots quietly at midnight.
 EOF

Connect over TLS to *irc.cia.gov* on port *1337*, use *Password123*
as the server password, register as user *agent*,
join channel *#hq* using the channel key *123456*,
and send a very secret message.

Reporting bugs
--------------
Use https://git.janouch.name/p/xK to report bugs, request features,
or submit pull requests.

See also
--------
_Uniform Resource Locator Schemes for Internet Relay Chat Entities_,
https://datatracker.ietf.org/doc/html/draft-butcher-irc-url-04[].

_Default Port for Internet Relay Chat (IRC) via TLS/SSL_,
https://datatracker.ietf.org/doc/html/rfc7194[].