hii

  1.Dd $Mdocdate: July 31 2018 $
  2.Dt HII 1
  3.Os
  4.Sh NAME
  5.Nm hii
  6.Nd a filesystem based IRC client
  7.Sh SYNOPSIS
  8.Nm hii
  9.Op Fl k Pa key
 10.Op Fl c Pa cert
 11.Op Fl r Pa certs
 12.Op Fl f Ar name
 13.Op Fl i Pa prefix
 14.Op Fl n Ar nick
 15.Op Fl p Ar port
 16.Op Fl t
 17.Op Fl d
 18.Op Fl s
 19.Ar server
 20.Op Ar target ...
 21.Sh DESCRIPTION
 22.Nm
 23is a file-based IRC client.
 24It is heavily inspired by
 25.Xr ii 1
 26but offers more features, e.g. built-in TLS support.
 27.Pp
 28Just as
 29.Xr ii 1
 30.Nm
 31creates a directory tree for the server (the master channel) containing
 32subdirectories for every conversation started on that server.
 33This includes public IRC channels and private conversations with other
 34users.
 35.Pp
 36On startup
 37.Nm
 38attempts to connect to the given
 39.Ar server .
 40If a connection was established successfully it automatically creates
 41directories for the given
 42.Ar targets
 43(if any).
 44Directories for users are only created automatically if the server
 45supports the IRCv3.2
 46.Em MONITOR
 47command and the user is currently online.
 48.Nm
 49makes no attempt to reestablish the connection, it simply terminates
 50when the connection to the IRC server is lost.
 51.Pp
 52The options are as follows:
 53.Bl -tag -width Ds
 54.It Fl k Pa key
 55Path to PEM encoded key used for client authorization using TLS, also
 56known as
 57.Em CertFP .
 58This requires
 59.Fl c
 60and
 61.Fl t
 62to be given as well.
 63.It Fl c Pa cert
 64Certificate
 65Path to PEM encoded certificate used for client authorization using TLS,
 66also known as
 67.Em CertFP .
 68This requires
 69.Fl k
 70and
 71.Fl t
 72to be given as well.
 73.It Fl r Pa certs
 74Path to file containing root certificates.
 75This requires
 76.Fl t
 77to be given as well.
 78Defaults to the host's root CA set.
 79.It Fl f Ar name
 80Real name associated with the user's nick.
 81Defaults to the user's login name.
 82.It Fl i Pa prefix
 83Path to the root directory used for creating channel and server
 84subdirectory.
 85Default to
 86.Pa ~/irc .
 87.It Fl n Ar nick
 88Nick name used on the IRC server.
 89Defaults to the user's login name.
 90.It Fl p Ar port
 91TCP port used to connect to the IRC server.
 92Defaults to 6667.
 93.It Fl t
 94Enables TLS, which is disabled by default.
 95.It Fl d
 96Write debug messages to standard output.
 97Contrary to text in the
 98.Pa out
 99file the debug output is not sanitized and might contain ANSI escape
100sequences or other non-printable characters.
101.It Fl s
102Attempt SASL authentication using the SASL EXTERNAL method with TLS
103client certificates.
104This requires
105.Fl k ,
106.Fl c ,
107and
108.Fl t
109to be given as well.
110.El
111.Sh FILES
112.Bl -tag -width "usr"
113.It Pa in
114A FIFO used to send messages to the IRC server.
115If the message is prefixed with a backlash it is send to the server as
116is.
117Otherwise it is interpreted as a
118.Em PRIVMSG
119and send to the target associated with the subdirectory.
120This file is removed on program termination.
121.It Pa out
122A regular file containing messages received for the target associated
123with the subdirectory.
124This file is not removed on program termination.
125.It Pa id
126A regular file containing a unique id for identifying the target
127associated with the subdirectory.
128This file does not exist in the master channel directory and is not
129removed on program termination.
130.It Pa usr
131A UNIX domain socket which reports the nicks of all users currently
132present in an IRC channel.
133Nicks are separated by a newline and are written descending by last
134activity to the socket.
135The socket only exists in subdirectories associated with IRC channels
136and is closed on program termination.
137.It Pa log
138A regular file containing received messages which either mention the
139user's nick or were received through private conversations.
140This file is not removed on program termination.
141.El
142.Sh EXIT STATUS
143.Nm
144always exits with a non-zero exit status.
145.Sh EXAMPLES
146Connect to hackint and join the
147.Nm
148irc channel:
149.Pp
150.Dl hii irc.hackint.org '#hii'
151.Pp
152Connect to Libera.Chat and monitor all server messages:
153.Bd -literal -offset indent
154hii irc.libera.chat &
155tail -f ~/irc/irc.libera.chat/out
156.Ed
157.Sh SEE ALSO
158.Xr ii 1 ,
159.Xr tail 1 ,
160.Xr hii 5
161.Sh STANDARDS
162.Rs
163.%A J. Oikarinen
164.%A D. Reed
165.%D May 1993
166.%R RFC 1459
167.%T Internet Relay Chat Protocol
168.Re
169.Pp
170.Rs
171.%A C. Kalt
172.%D April 2000
173.%R RFC 2812
174.%T Internet Relay Chat: Client Protocol
175.Re
176.Pp
177.Rs
178.%A L. Hardy
179.%A K. Aman
180.%A W. Pitcock
181.%U https://ircv3.net/specs/core/monitor-3.2.html
182.%T IRCv3.2 Monitor
183.Re
184.Pp
185.Rs
186.%A A. Molnar
187.%A W. Pitcock
188.%U https://ircv3.net/specs/extensions/sasl-3.2.html
189.%T IRCv3.2 SASL Authentication
190.Re
191.Sh AUTHORS
192.An Sören Tempel Aq Mt soeren@soeren-tempel.net
193.Sh BUGS
194.Nm
195has tight restrictions regarding directory names for both security and
196compatibility reasons.
197The problem with this being that directory names are not unique.
198For instance, joining a channel named
199.Em #foo|bar
200and a channel named
201.Em #foo/bar
202is not possible since they are assigned the same directory name.