.\" -*- mode: nroff; -*-
.\"
.\" Copyright 2018-2023 Markus Uhlin. All rights reserved.
.\"
.Dd February 5, 2023
.Dt SWIRC.CONF 5
.Os
.Sh NAME
.Nm swirc.conf
.Nd swirc configuration file
.Sh DESCRIPTION
This manual page describes
.Nm
which is a configuration file for
.Xr swirc 1
(a curses based irc client).
\fBNOTE\fR
Certain settings take effect first after program restart while others
don't!
.Sh SETTING TYPES
.Bl -tag -width Ds
.It Sy bool
Bools are case insensitive and can have one of the following values:
.Bl -bullet -compact
.It
on, true or yes
.It
off, false or no
.El
.It Sy int
Integers.
.Sy swirc
implements a min/max value for each integer in order to keep its value
safe.
The error log will tell if the restrictions for an integer aren't
within limits and, if so, that a preprogrammed fallback value is being
used instead.
.It Sy string
An arbitrary sequence of characters
.El
.Sh SETTINGS
.Bl -tag -width Ds
.\" ----------------------------------------
.\" ACCOUNT NOTIFY
.\" ----------------------------------------
.It Sy account_notify Pq Em bool
Allows a client to be notified when another client’s accountname
changes
.\" ----------------------------------------
.\" ALT NICK
.\" ----------------------------------------
.It Sy alt_nick Pq Em string
Alternative nickname.
This nickname is used when processing a connection to a server and the
default nickname is busy.
.\" ----------------------------------------
.\" AUTO OP YOURSELF
.\" ----------------------------------------
.It Sy auto_op_yourself Pq Em bool
Automatically op yourself on channel join when you're identified as an
IRC operator
.\" ----------------------------------------
.\" AWAYMSGS IN PRIVCONV
.\" ----------------------------------------
.It Sy awaymsgs_in_privconv Pq Em bool
Output away messages in private conversations?
Away messages are often displayed each time you message the user who's
marked as being away which can be annoying if the user isn't really
away, i.e. he/she just forgot to unset the status.
This setting defaults to YES.
.\" ----------------------------------------
.\" AWAY NOTIFY
.\" ----------------------------------------
.It Sy away_notify Pq Em bool
Allows a client to specify that it would like to be notified when
users are marked/unmarked as away
.\" ----------------------------------------
.\" BEEPS
.\" ----------------------------------------
.It Sy beeps Pq Em bool
.Xr swirc 1
alerts the user by sending a beep in certain cases.
However, with the help of this setting, beeps can be turned on/off.
.\" ----------------------------------------
.\" CHANSERV HOST
.\" ----------------------------------------
.It Sy chanserv_host Pq Em string
ChanServ hostname
.\" ----------------------------------------
.\" CIPHER SUITE
.\" ----------------------------------------
.It Sy cipher_suite Pq Em string
Cipher suite.
Which can have one of the following values:
.Bl -bullet -compact
.It
secure
.It
compat
.It
legacy
.It
all
.El
.\" ----------------------------------------
.\" CMD HIST SIZE
.\" ----------------------------------------
.It Sy cmd_hist_size Pq Em int
Command history size.
No more than this number of commands will be stored in the memory.
.\" ----------------------------------------
.\" CMD TYPE PROT
.\" ----------------------------------------
.It Sy cmd_type_prot Pq Em bool
Command type protection.
Detects up to 5 leading spaces followed by a command character
preventing a command to be accidentally transmitted as a chat message.
.\" ----------------------------------------
.\" CONNECTION TIMEOUT
.\" ----------------------------------------
.It Sy connection_timeout Pq Em int
Connection timeout in seconds
.\" ----------------------------------------
.\" CTCP REPLY
.\" ----------------------------------------
.It Sy ctcp_reply Pq Em bool
Reply to CTCP requests?
(For example TIME and VERSION.)
.\" ----------------------------------------
.\" HOSTNAME CHECKING
.\" ----------------------------------------
.It Sy hostname_checking Pq Em bool
Enable or disable TLS/SSL hostname verification
.\" ----------------------------------------
.\" ICONV CONVERSION
.\" ----------------------------------------
.It Sy iconv_conversion Pq Em bool
Perform character conversion using GNU libiconv?
If having this option set to 'on' causes troubles or if you don't need
it, it can safely be switched off.
Switching it off boosts the performance of the printtext module
significantly.
.\" ----------------------------------------
.\" IDENTD
.\" ----------------------------------------
.It Sy identd Pq Em bool
Use the built-in ident protocol daemon/server?
It's automatically started and stopped during the connection process
if this option is enabled.
During the connection process to an IRC server the IRC server often
attempts to send an ident query to port 113 on your computer.
You might have seen something like:
.Bd -literal -offset indent
*** Processing connection to irc.server.com
*** Looking up your hostname...
*** Checking Ident
*** No Ident response <---
*** Found your hostname
.Ed
.Pp
This requires port 113 to be open, i.e. not behind a firewall.
.\" ----------------------------------------
.\" IDENTD FAKENAMES
.\" ----------------------------------------
.It Sy identd_fakenames Pq Em bool
Respond to ident queries with fake (randomized) names?
.\" ----------------------------------------
.\" IDENTD PORT
.\" ----------------------------------------
.It Sy identd_port Pq Em int
Which port shall the ident server listen on?
In general, on Unix only root can listen on ports below 1024.
Since you neither CAN or SHOULD run
.Xr swirc 1
as root you should specify a different port using this setting and
configure your firewall to redirect connections to port 113 to this
one.
.Pp
If you're using
.Ox
and
.Xr pf 4 ,
pose that you want use port 6500 and that the name of the target
interface is vio0.
You could then add the following lines to your
.Xr pf.conf 5 :
.Bd -literal -offset indent
pass in on vio0 inet  proto tcp from any to any port auth \e
    rdr-to 127.0.0.1 port 6500
pass in on vio0 inet6 proto tcp from any to any port auth \e
    rdr-to ::1 port 6500
.Ed
.\" ----------------------------------------
.\" INVITE NOTIFY
.\" ----------------------------------------
.It Sy invite_notify Pq Em bool
Allows a client to specify that it would like to be notified when
users are invited to channels
.\" ----------------------------------------
.\" IRCV3 SERVER TIME
.\" ----------------------------------------
.It Sy ircv3_server_time Pq Em bool
Enable or disable IRCv3 server time extension.
The server time extension is particularly useful if you're using an
IRC bouncer like
.Lk https://znc.in/ ZNC
.\" ----------------------------------------
.\" JOINS PARTS QUITS
.\" ----------------------------------------
.It Sy joins_parts_quits Pq Em bool
Show JOIN/PART/QUIT events?
.\" ----------------------------------------
.\" KICK CLOSE WINDOW
.\" ----------------------------------------
.It Sy kick_close_window Pq Em bool
If the active user gets kicked out from a channel,
should the channel window be terminated?
.\" ----------------------------------------
.\" MAX CHAT WINDOWS
.\" ----------------------------------------
.It Sy max_chat_windows Pq Em int
Max chat windows that can be open simultaneously
.\" ----------------------------------------
.\" MOUSE
.\" ----------------------------------------
.It Sy mouse Pq Em bool
Use the mouse?
.\" ----------------------------------------
.\" MOUSE EVENTS
.\" ----------------------------------------
.It Sy mouse_events Pq Em string
Which mouse events shall be reported?
.Bl -bullet -compact
.It
all
.It
wheel (default)
.El
.\" ----------------------------------------
.\" NICKNAME
.\" ----------------------------------------
.It Sy nickname Pq Em string
Online nickname
.\" ----------------------------------------
.\" NICKNAME ALIASES
.\" ----------------------------------------
.It Sy nickname_aliases Pq Em string
A space separated list of nickname aliases which are used, in addition
to the default nickname, to highlight a message if it matches any of
the aliases given by this setting.
.\" ----------------------------------------
.\" NICKSERV HOST
.\" ----------------------------------------
.It Sy nickserv_host Pq Em string
NickServ hostname
.\" ----------------------------------------
.\" PART MESSAGE
.\" ----------------------------------------
.It Sy part_message Pq Em string
Message when leaving a channel
.\" ----------------------------------------
.\" QBOT HOST
.\" ----------------------------------------
.It Sy qbot_host Pq Em string
Q bot hostname.
The Q bot is a
.Lk https://www.quakenet.org/ QuakeNet
service.
.\" ----------------------------------------
.\" QUIT MESSAGE
.\" ----------------------------------------
.It Sy quit_message Pq Em string
Message when disconnecting from a server
.\" ----------------------------------------
.\" REAL NAME
.\" ----------------------------------------
.It Sy real_name Pq Em string
Specifies the real name.
But can be set to anything.
.\" ----------------------------------------
.\" RECONNECT BACKOFF DELAY
.\" ----------------------------------------
.It Sy reconnect_backoff_delay Pq Em int
The number of seconds that should be added to each reconnect attempt
(0-99)
.\" ----------------------------------------
.\" RECONNECT DELAY
.\" ----------------------------------------
.It Sy reconnect_delay Pq Em int
Seconds to consume before the first reconnect attempt (0-999)
.\" ----------------------------------------
.\" RECONNECT DELAY MAX
.\" ----------------------------------------
.It Sy reconnect_delay_max Pq Em int
Maximum reconnect delay in seconds (0-999).
Regardless of the other related reconnect settings.
.\" ----------------------------------------
.\" RECONNECT RETRIES
.\" ----------------------------------------
.It Sy reconnect_retries Pq Em int
If the IRC connection is lost, how many attempts should be performed
to get the connection working again before giving up?
.\" ----------------------------------------
.\" SASL
.\" ----------------------------------------
.It Sy sasl Pq Em bool
Request SASL authentication on connection to a server?
.\" ----------------------------------------
.\" SASL MECHANISM
.\" ----------------------------------------
.It Sy sasl_mechanism Pq Em string
SASL mechanism.
Available mechanisms are:
.Bl -bullet -compact
.It
ECDSA-NIST256P-CHALLENGE
.It
EXTERNAL
.It
PLAIN
.It
SCRAM-SHA-256
.El
.Pp
Be sure to write them in all uppercase!
.\" ----------------------------------------
.\" SASL PASSWORD
.\" ----------------------------------------
.It Sy sasl_password Pq Em string
SASL password.
(For mechanism PLAIN and SCRAM-SHA-256.)
.Pp
It is recommended to set this setting using the interactive \fBsasl\fR
command.
However, if the initial character is a question mark
.Pq Sq \&?
it symbolizes that the password is in plain text/unencrypted; while a
hash mark
.Pq Sq #
symbolizes that the password is encrypted.
The initial character must be either of them and is not interpreted as
a part of the password.
.\" ----------------------------------------
.\" SASL USERNAME
.\" ----------------------------------------
.It Sy sasl_username Pq Em string
SASL username
.\" ----------------------------------------
.\" SASL X509
.\" ----------------------------------------
.It Sy sasl_x509 Pq Em string
Filename for your certificate chain file.
The file shall be located in Swirc's home dir and be in PEM format.
.Pp
The certificate chain file is used for automatic NickServ
authentication using the \fBexternal\fR SASL auth mechanism.
A file of this sort can be generated by running the following scripts:
.Bl -bullet -compact
.It
1-root-ca.sh (Create the root CA)
.It
4-client-cert.sh
(Create the client certificate and sign it with the root CA)
.El
.Pp
After running the scripts stated above in given order you can set this
setting to \fIclient.pem\fR.
.\" ----------------------------------------
.\" SERVER CIPHER SUITE
.\" ----------------------------------------
.It Sy server_cipher_suite Pq Em string
Server cipher suite.
Which can have one of the following values:
.Bl -bullet -compact
.It
secure
.It
compat
.It
legacy
.It
all
.El
.Pp
The server cipher suite is used when you start a TLS server in
.Xr swirc 1
used for remote GUI connections.
(Managed using the \fBrgui\fR command).
.\" ----------------------------------------
.\" SHOW PING PONG
.\" ----------------------------------------
.It Sy show_ping_pong Pq Em bool
Show ping pong events?
The default is NO.
.\" ----------------------------------------
.\" SKIP MOTD
.\" ----------------------------------------
.It Sy skip_motd Pq Em bool
Skip message of the day (MOTD) on connection to a server?
.\" ----------------------------------------
.\" SOCKS
.\" ----------------------------------------
.It Sy socks Pq Em bool
Use the SOCKS proxy client?
The SOCKS proxy client is particularly suited for use with Tor.
Examples of IRC networks that are accessible via Tor are Libera Chat
and OFTC.
In order to access Libera Chat or OFTC using the previously mentioned
technique you can add the following lines to your
.Xr torrc 5 :
.Bd -literal -offset indent
# Libera Chat
MapAddress palladium.libera.chat libera75jm6of4wxpxt4aynol3xjmbtxgfyjpu34ss4d7r7q2v5zrpyd.onion

# OFTC
MapAddress irc.oftc.net oftcnet6xg6roj6d7id4y4cu6dchysacqj2ldgea73qzdagufflqxrid.onion
.Ed
.Pp
After this has been done (and after restarting Tor) you should be able
to connect to one of the mapped addresses inside Swirc.
The socks host setting should point to the machine where the Tor
service is running.
.\" ----------------------------------------
.\" SOCKS ATYP
.\" ----------------------------------------
.It Sy socks_atyp Pq Em int
SOCKS address type.
Which can have one of the following values:
.Bl -bullet -compact
.It
(0) Fully qualified domain name.
The default.
.It
(1) IPv4 address
.It
(2) IPv6 address
.El
.\" ----------------------------------------
.\" SOCKS HOST
.\" ----------------------------------------
.It Sy socks_host Pq Em string
SOCKS hostname.
.\" ----------------------------------------
.\" SOCKS PORT
.\" ----------------------------------------
.It Sy socks_port Pq Em string
SOCKS port.
The default is 9050 which is used by
.Lk https://www.torproject.org/ Tor .
.\" ----------------------------------------
.\" SPELL
.\" ----------------------------------------
.It Sy spell Pq Em bool
Use spelling?
.\" ----------------------------------------
.\" SPELL LANG
.\" ----------------------------------------
.It Sy spell_lang Pq Em string
Spelling language.
The default is \fBen_US\fR.
.\" ----------------------------------------
.\" SPELL SYSWIDE
.\" ----------------------------------------
.It Sy spell_syswide Pq Em bool
Where shall Swirc look for spelling dictionaries?
(System wide or in the program settings dir.)
.\" ----------------------------------------
.\" SSL VERIFY PEER
.\" ----------------------------------------
.It Sy ssl_verify_peer Pq Em bool
Verify peer?
Setting it to NO decreases TLS/SSL security significantly,
but is a must on servers with trusted self signed certificates.
.\" ----------------------------------------
.\" STARTUP GREETING
.\" ----------------------------------------
.It Sy startup_greeting Pq Em bool
Enable or disable
.Sy swirc
startup greeting
.\" ----------------------------------------
.\" TEXTBUFFER SIZE ABSOLUTE
.\" ----------------------------------------
.It Sy textbuffer_size_absolute Pq Em int
Max number of elements in a text buffer before head gets removed from
scroll back history.
Each open window is assigned a buffer with this size,
so set a sane value!
.\" ----------------------------------------
.\" THEME
.\" ----------------------------------------
.It Sy theme Pq Em string
.Sy swirc
theme.
.\" ----------------------------------------
.\" USERNAME
.\" ----------------------------------------
.It Sy username Pq Em string
User identity.
Preferably to be set to the same as the nickname.
.El
.Sh FILES
.Bl -tag -width "                    " -compact
.It Pa ~/.swirc/swirc.conf
swirc configuration file
.El
.Sh SEE ALSO
.Xr swirc 1