irssi¶

irssi is a terminal IRC client scriptable in Perl. The current stable series is 1.4.x; development of 1.5 (Meson-only builds) is ongoing.

See also: IRC guide · Command reference · Running UnrealIRCd

Install¶

sudo dnf install irssi            # Fedora / RHEL (EPEL)
sudo apt install irssi            # Debian / Ubuntu
sudo pkg install irssi            # FreeBSD
irssi --version

Configuration lives in ~/.irssi/config. Edit it with irssi closed (irssi rewrites it on /save), or make changes with commands inside irssi and run /save. Because it can contain passwords:

chmod 700 ~/.irssi && chmod 600 ~/.irssi/config

Modern Syntax Changes (if your notes are old)¶

The old -ssl* spellings still work as aliases, but use the new ones in new configs.

A Clean, Minimal Config¶

The irssi default config ships with a dozen networks (including dead ones like SILC). Rather than carrying all of that around, keep only what you use. Here's the core of a trimmed ~/.irssi/config:

servers = (
  {
    address = "irc.libera.chat";
    chatnet = "liberachat";
    port = "6697";
    use_tls = "yes";
    tls_verify = "yes";
    autoconnect = "yes";
  },
  {
    address = "irc.oftc.net";
    chatnet = "OFTC";
    port = "6697";
    use_tls = "yes";
    tls_verify = "yes";
  },
  {
    address = "irc.andrewmercer.net";
    chatnet = "AndrewMercer";
    port = "6697";
    use_tls = "yes";
    tls_verify = "yes";
    autoconnect = "yes";
  }
);

chatnets = {
  liberachat = {
    type = "IRC";
    sasl_mechanism = "EXTERNAL";
  };
  OFTC = { type = "IRC"; };
  AndrewMercer = {
    type = "IRC";
    max_kicks = "1";
    max_msgs = "3";
    max_whois = "30";
  };
};

channels = (
  { name = "#andrewmercer"; chatnet = "AndrewMercer"; autojoin = "yes"; },
  { name = "#libera"; chatnet = "liberachat"; autojoin = "no"; }
);

settings = {
  core = {
    real_name = "Andrew Mercer";
    user_name = "amercer";
    nick = "amercer";
  };
  "fe-text" = { actlist_sort = "refnum"; };
  "fe-common/core" = {
    autolog = "yes";
    autolog_path = "~/.irssi/logs/$tag/$0.log";
  };
};

The default aliases and statusbar blocks can stay as-is; they're irssi's stock definitions and are recreated if missing. A few of the stock aliases worth knowing: /j join, /wc close window, /wl window list, /kb kickban, /kn timed kickban, /mub unban all, /sb scrollback, /calc (uses bc).

Adding Networks and Servers from Inside irssi¶

/network add -sasl_mechanism PLAIN -sasl_username amercer -sasl_password <password> liberachat
/server add -auto -net liberachat -tls -tls_verify irc.libera.chat 6697
/channel add -auto #rust liberachat
/save
/connect liberachat

Duplicate chatnet names confuse irssi. If /connect picks the wrong server, check for two servers entries with the same chatnet and remove one (/server remove <address> <port>).

SASL Authentication¶

SASL is built into irssi since 1.0 — delete cap_sasl.pl from ~/.irssi/scripts/autorun/ if you still have it, as it conflicts with the native support.

SASL PLAIN (password)¶

/network add -sasl_mechanism PLAIN -sasl_username <account> -sasl_password <password> liberachat
/save
/reconnect

The password is stored in plaintext in ~/.irssi/config. That's why the next option is better.

SASL EXTERNAL (CertFP)¶

Authenticate with a client TLS certificate instead of a password. Nothing secret lives in the config file except a path.

1. Generate a certificate (one file containing key + cert):

   bash mkdir -p ~/.irssi/certs && cd ~/.irssi/certs openssl req -x509 -new -newkey ed25519 -sha256 -days 1096 -nodes \ -subj "/CN=amercer" -out libera.pem -keyout libera.pem chmod 600 libera.pem openssl x509 -in libera.pem -noout -fingerprint -sha512 | tr -d ':' | tr 'A-F' 'a-f'

2. Connect once with the cert and log in with your password, then register the fingerprint:

   text /server add -net liberachat -tls -tls_verify -tls_cert ~/.irssi/certs/libera.pem irc.libera.chat 6697 /connect liberachat /msg NickServ IDENTIFY amercer <password> /msg NickServ CERT ADD

3. Switch the network to EXTERNAL and reconnect:

   text /network add -sasl_mechanism EXTERNAL -sasl_username "" -sasl_password "" liberachat /save /reconnect

You should see SASL authentication successful on connect. OFTC supports CertFP too (/msg NickServ CERT ADD), though it logs you in by fingerprint rather than SASL.

Connecting to a Self-Hosted Server with a Self-Signed Certificate¶

My old config used ssl_verify = "no" for irc.andrewmercer.net. That disables all protection against interception. Better options, in order:

1. Use a real certificate (Let's Encrypt) on the server — then plain tls_verify = "yes" works. See UnrealIRCd → TLS.

2. Trust your own CA if you run a private CA:

   perl { address = "irc.andrewmercer.net"; chatnet = "AndrewMercer"; port = "6697"; use_tls = "yes"; tls_verify = "yes"; tls_cafile = "~/.irssi/certs/homelab-ca.pem"; }

3. Pin the server certificate if it's self-signed:

   bash openssl s_client -connect irc.andrewmercer.net:6697 </dev/null 2>/dev/null \ | openssl x509 -noout -fingerprint -sha256

   text /server add -tls -tls_pinned_cert <SHA256 fingerprint> -net AndrewMercer irc.andrewmercer.net 6697

   Pinning breaks (by design) when the certificate changes, so update it on renewal.

Usage¶

Windows¶

Docs: https://irssi.org/documentation/help/window_changing/

Running persistently¶

Run irssi inside tmux on a server so it stays connected when you detach:

tmux new -s irc irssi       # start
tmux attach -t irc          # reattach later (Ctrl+b d to detach)

Scripts¶

Browse at https://scripts.irssi.org/. Scripts go in ~/.irssi/scripts/; symlink into autorun/ to load at startup.

mkdir -p ~/.irssi/scripts/autorun
cd ~/.irssi/scripts
curl -fsSLO https://scripts.irssi.org/scripts/<name>.pl
ln -sf ../<name>.pl autorun/

Inside irssi:

/script load <name>
/script list
/script unload <name>

Scripts are Perl running with your user's privileges. Skim them before loading.

Scripts I've used¶

Configuring awayproxy.pl (if kept) — edit the %config values near the top of the script:

$config{emailto}      = '[email protected]';
$config{emailfrom}    = '[email protected]';
$config{sendmail}     = '/usr/sbin/sendmail';
$config{emailsubject} = '[irssi-proxy]';
$config{awayreason}   = 'Auto-away because client has disconnected from proxy.';

Bouncer Instead of irssi-in-tmux¶

If you want history on multiple devices (laptop, phone, web), run a bouncer and point irssi at it:

{ address = "bnc.andrewmercer.net"; chatnet = "soju"; port = "6697";
  use_tls = "yes"; tls_verify = "yes";
  password = "amercer/liberachat:<password>"; autoconnect = "yes"; }

soju (username/network login syntax shown above) also serves IRCv3 chathistory to clients that understand it, such as Goguma on Android or gamja in a browser.

Troubleshooting¶