Aaron Toponce

I have found, that since using Irssi, many people like to edit the config directly. This is a natural instinct that we have as hackers in general. Because configs are stored in plain text, such as our shell RC files, Apache configs and many more, we just intuitively reach for our editor, and start hacking away. Unfortunately, the Irssi config is anything but clean. It uses a noisy syntax that makes it easy to make mistakes, and as a result, lose settings in Irssi, or have a broken Irssi entirely.

When I used to teach system administrators for a living, I gave them the mantra that if you have a tool that can modify a config file, use the tool. The tool has most likely been tested for bugs, and will generate syntactically correct configs. Humans are error-prone, so editing a config by hand means setting yourself up for error and pain. For Irssi, the developers have put in rather extensive commands that can modify everything in the config directly, and there’s even an exhaustive documentation support structure behind those commands. So, there should be no reason to edit the Irssi config by hand.

To show this, in irssi, go to the status window, and type “/help”:

/help
05:29 Irssi commands:
05:29 accept     disconnect  lastlog  op        script     unquery
05:29 action     echo        layout   oper      scrollback unsilence
05:29 admin      eval        links    otr       server     upgrade
05:29 alias      exec        list     part      servlist   uping
05:29 away       flushbuffer load     ping      set        uptime
05:29 ban        foreach     log      query     sethost    userhost
05:29 beep       format      lusers   quit      silence    ver
05:29 bind       hash        map      quote     squery     version
05:29 cat        help        me       rawlog    squit      voice
05:29 cd         hilight     mircdcc  recode    stats      wait
05:29 channel    ignore      mode     reconnect statusbar  wall
05:29 clear      info        motd     redraw    time       wallops
05:29 completion invite      msg      rehash    toggle     who
05:29 connect    ircnet      names    reload    topic      whois
05:29 ctcp       ison        nctcp    resize    trace      whowas
05:29 cycle      join        netsplit restart   ts         window
05:29 dcc        kick        network  rmreconns unalias
05:29 dehilight  kickban     nick     rmrejoins unban
05:29 deop       kill        note     rping     unignore
05:29 devoice    knock       notice   save      unload
05:29 die        knockout    notify   sconnect  unnotify   

So, long story short, don’t edit the config. Use the commands, and learn the help system. With that out of the way, let’s begin.

I’ve encountered many who are using Irssi that don’t understand how a few key commands relate with each other and how to tie them in. So, I would like to cover those commands here, namely: /channel, /network, /server and /connect. Hopefully, by the end of this post, not only will you be comfortable enough with the commands I’ve taught you about, but you’ll be comfortable enough to use the built-in documentation should you be stuck.

/network
The first command to learn is /network, because all the rest of the commands take advantage of it. So, we’ll start there. /network is used for defining some client-specific settings you want to apply when connecting to a server. These settings can include username, real name, nickname, usermodes and other goodies. Running “/help network” can show you everything it supports:

05:32 NETWORK ADD [-nick <nick>] [-user <user>] [-realname <name>] [-host <host>] [-autosendcmd <cmd>] [-querychans <count>] [-whois <count>] [-msgs <count>] [-kicks <count>] [-modes <count>] [-cmdspeed <ms>] [-cmdmax <count>] <name>
05:32 NETWORK REMOVE <network>
05:32
05:32      -kicks: Maximum number of nicks in one /KICK command
05:32      -msgs: Maximum number of nicks in one /MSG command
05:32      -modes: Maximum number of mode changes in one /MODE command
05:32      -whois: Maximum number of nicks in one /WHOIS command
05:32      -cmdspeed: Same as /SET cmd_queue_speed, see section 3.1
05:32      -cmdmax: Same as /SET cmds_max_at_once, see section 3.1
05:32      -nick, -user, -realname: Specify what nick/user/name to use
05:32      -host: Specify what host name to use, if you have multiple
05:32      -usermode: Specify what usermode to use on this network
05:32      -autosendcmd: Command to send after connecting to a server
05:32
05:32 With -autosendcmd argument you can automatically run any commands after connecting to network. This is useful for automatically identifying yourself to NickServ, for example
05:32
05:32 Shows and changes the settings of defined IRC networks.
05:32
05:32 See also: CONNECT
05:32
05:32 Irssi commands:
05:32 network add network list network remove 

So, let’s go ahead an define some networks. I personally connect to several networks simultaneously, all of which have different usermodes, and some which I need to provide authentication to when connecting. So, let’s say I wish to define client-specific connections to Freenode, OFTC and bitlbee. Let’s look at what to add. Oh, by the way, every command and option provided by Irssi can be tab-completed. Worth knowing to save some typing.

/network add -user 88 -realname eightyeight -nick eightyeight -usermode +iw freenode
/network add -user 88 -realname eightyeight -nick eightyeight -usermode +w oftc
/network add -user aaron -realname "Aaron Toponce" -nick aaron -autosendcmd "say identify password" bitlbee

As you can see, each network line is different. I’m using the same username, real name and nick for “freenode” and “oftc”, but different ones for “bitlbee”. I’ve specified different user modes with “freenode” and “oftc” where I haven’t provided any with “bitlbee”. Further, with “bitlbee”, I’m sending an identify command to the server when I connect. As you can probably imagine, this gives me great flexibility on how I want my client to interact with different servers.

Running “/network list” should show you the three servers you just added:

/network list
05:48 Networks:
05:48 freenode: nick: eightyeight, username: 88, realname: eightyeight, usermode: +iw
05:48 bitlbee: nick: aaron, username: 88, realname: Aaron Toponce, autosendcmd: say identify password
05:48 oftc: nick: eightyeight, username: 88, realname: eightyeight, usermode: +w

If you’ve just installed Irssi, you will likely find many networks already defined, including OFTC. If this is the case, and you want to make some adjustments to the OFTC definition, go ahead and provide those in the “/network add” command, and those options will be appended, provided the network name is the same. If you wish to remove any of the networks, then as you learned in the help doc, “/network remove name” is the syntax for that.

It’s important to note that at this stage of the game, any of the commands you enter in Irssi are only used for the current running session. If you wish to keep the settings persistent, then you will need to save it to disk (your config). You can do this with the “/save” command. I would recommend saving often when manipulating Irssi. Further, if for some reason you make a mistake in the command you’re typing, and you wish to revert back to the previous “/save” command, then you can use “/reload” for this purpsoe. “/reload” will read the config, and load the settings it finds there, ignoring any previous settings you’ve defined without saving.

/channel
Now with our networks defined for our client settings, let’s define some channels to visit when we connect to these networks. So, in the status window, what does “/help channel” show?

05:56 CHANNEL LIST
05:56 CHANNEL ADD [-auto | -noauto] [-bots <masks>] [-botcmd <command>] <channel> <network> [<password>]
05:56 CHANNEL REMOVE <channel> <network>
05:56
05:56 Irssi can automatically join to specified channels in specified IRC networks. It can also automatically send the password when manually joining to channel without specifying the password.
05:56
05:56 /CHANNEL ADD [-auto | -noauto] [-bots <masks>] [-botcmd <command>]
05:56              <channel> <network> [<password>]
05:56
05:56 With -bots and -botcmd arguments you can automatically send commands to someone in channel. This is useful for automatically getting ops for channels, for example
05:56
05:56 /CHANNEL ADD -auto -bots "*!bot@bothost.org bot*!*@host2.org"
05:56              -botcmd "msg $0 op mypass" #channel ircnet
05:56
05:56 You can also use the -botcmd without -bots argument. The command is then sent whenever you join the channel.
05:56
05:56 If you want to remove some settings from existing channel record, for example bots, just give the -bots "" parameters to it. Password can be removed by setting it to - (or actually, "" works too).
05:56
05:56 You can remove the channels with /CHANNEL REMOVE <channel> <network>
05:56
05:56 /CHANNEL LIST displays list of channels with settings.
05:56
05:56 /CHANNEL without any arguments displays list of channels you have joined. You can also use /CHANNEL to join to channels just as with /JOIN, like /CHANNEL #a.
05:56
05:56 See also: TS, JOIN
05:56
05:56 Irssi commands:
05:56 channel add channel list channel remove 

As you can clearly see with “/channel”, we can define what channels to join, and if any, what bot commands to send to the channel when we join. Each channel we join will be based on the network that we’ve previously defined. So, I could join #ubuntu whenever I connect to the Freenode network and #debian whenever I connect to the OFTC network. As with “/network”, on a fresh install of Irssi, there may already be a couple channels defined. Feel free to keep them in play when using Irssi, or remove them with “/channel remove” as per the syntax in the help doc.

So, let’s define some channels:

/channel add -auto #ubuntu freenode
/channel add -auto #freenode freenode
/channel add -auto #debian oftc
/channel add -auto #bitlbee oftc

Pretty straight forward, right? I’ve added four channels, two on the “freenode” network and two on the “oftc” network. Because Bitlbee doesn’t handle “channels” necessarily the same way IRC servers do, I haven’t defined any channels to join when I connect to Bitlbee. Notice I’m passing the “-auto” switch, so when I join that network, I’ll automatically join those channels. This is entirely optional, and “-noauto” is default if “-auto” isn’t passed.

As with “/network”, you can append settings to each channel listing as needed, as long as the channel name and network name are the same. If you wish to remove some settings, then you’ll need to “/channel remove” and “/channel add” as appropriate. Running “/channel list” should show our progress thus far:

/channel list
06:05 Channel         Network    Password   Settings
06:05 #ubuntu         freenode              autojoin
06:05 #freenode       freenode              autojoin
06:05 #debian         oftc                  autojoin
06:05 #bitlbee        oftc                  autojoin

Again, you should run “/save” when you’ve defined your channels, so next time you start Irssi, your settings won’t be lost.

One last related note about your channels. For me, I get very used to the location, or layout, of my channels. When I lose my running Irssi connection, for whatever reason, nothing is more frustrating than the channels being in a different order than previous. Fortunately, I’m not the only one that this annoys, so the developers have provided “/layout save” as a way to keep my sanity. “/layout save” will save the location order of your channel windows, so should you join a channel again, it will go to the same location as it was in previously. However, as with every other command in Irssi, this will only save it to your currently running session in RAM. If you wish to keep it persistent, you must issue “/save” for the next time you start Irssi.

/server
At this point, we’re ready to connect. We have all the details out of the way, and we could easily just connect to Freenode or OFTC. However, we may want to pass some server-side options to the networks, such as connecting via SSL. So, before covering “/connect”, let’s get “/server” out of the way, as it’s the last command in this post that does any saving to disk, then we’ll play with “/connect”. As is verbatim in this post, let us pull up the help doc:

06:24 SERVER [-4 | -6] [-ssl] [-ssl_cert <cert>] [-ssl_pkey <pkey>] [-ssl_verify] [-ssl_cafile <cafile>] [-ssl_capath <capath>] [-noproxy] [-network <network>] [-host <hostname>] [-rawlog <file>] [+]<address>|<chatnet> [<port> [<password>
             [<nick>]]]
06:24 SERVER PURGE [<target>]
06:24 SERVER REMOVE <address> [<port>]
06:24 SERVER ADD [-4 | -6] [-ssl] [-ssl_cert <cert>] [-ssl_pkey <pkey>] [-ssl_verify] [-ssl_cafile <cafile>] [-ssl_capath <capath>] [-auto | -noauto] [-network <network>] [-host <hostname>] [-cmdspeed <ms>] [-cmdmax <count>] [-port
                 <port>] <address> [<port> [<password>]]
06:24 SERVER LIST
06:24
06:24      -4, -6: specify explicitly whether to use IPv4 or IPv6 address
06:24      -ssl: use SSL when connecting
06:24      -ssl_cert: The SSL client certificate file (implies -ssl)
06:24      -ssl_pkey: The SSL client private key (if not included in the certificate file)
06:24      -ssl_verify: Verify servers SSL certificate
06:24      -ssl_cafile: File with list of CA certificates (implies -ssl_verify)
06:24      -ssl_capath: Directory with CA certificates (implies -ssl_verify)
06:24      -noproxy: Ignore the global proxy configuration for this server
06:24      -auto: Automatically connect to server at startup
06:24      -noauto: Don't connect to server at startup (default)
06:24      -network: Specify what IRC network this server belongs to
06:24      -ircnet: Same as -network. Deprecated. Do not use
06:24      -host: Specify what host name to use, if you have multiple
06:24      -!: don't autojoin channels
06:24      -cmdspeed: Same as /SET cmd_queue_speed, see section 3.1
06:24      -cmdmax: Same as /SET cmds_max_at_once, see section 3.1
06:24      -port: Use this only to edit the port number of an existing server,
06:24             for new servers use the <port> argument
06:24
06:24 /SERVER disconnects the server in active window and connects to the new one. It will take the same arguments as /CONNECT. If you prefix the address with the + character, Irssi won't disconnect the active server, and it will create a
      new window where the server is connected (ie. /window new hide; /connect address)
06:24
06:24 /SERVER without any arguments displays the list of connected
06:24         servers.
06:24
06:24 /SERVER REMOVE <address> [<port>]
06:24
06:24 /SERVER LIST
06:24
06:24 /SERVER PURGE [<target>]
06:24
06:24 Clears the server send queue. Useful if, for example, you accidentally paste lots of text to a channel.
06:24
06:24 See also: CONNECT, DISCONNECT, RECONNECT, RMRECONNS
06:24
06:24 Irssi commands:
06:24 server add server connect server list server purge server remove 

As should be obvious, this help doc is rather verbose. There are a lot of options that you can send server-side, such as using IPV4 or IPV6, connecting via SSL, changing the connecting port, and a myriad of other options. Let’s pick on just a few, and I’ll let you examine the rest.

Just the other day, I posted on how to connect to Freenode using SSL, and yesterday I covered connecting to OFTC in a similar manner. Let’s take those “/server” strings, along with one for Bitlbee to define how I wish to connect to these servers. As with the previous commands, the syntax is “/server add”, as the help doc mentions:

/server add -auto -ssl -ssl_verify -ssl_capath /etc/ssl/certs -network freenode irc.freenode.net 7000
/server add -auto -ssl -ssl_cert ~/.irssi/certs/nick.pem -ssl_verify -ssl_cafile /etc/ssl/certs/spi-cacert-2008.pem -network oftc irc.oftc.net 6697
/server add -auto -network bitlbee localhost

As you can see, I’m using SSL for the Freenode and OFTC connections, but not for bitlbee. Further, I’m specifying “-ssl_cert” with OFTC to present my self-signed certificate to NickServ, which I’m not doing to the others and I’m using a specific CA certificate to verify the OFTC SSL cert, whereas with Freenode, I’m specifying a whole CA path, and letting it choose the appropriate CA certificate for verification. Lastly, with all three connections, I’m automatically connecting to the networks, so when I launch up Irssi, it begins connecting right away. Because there are channels with “-auto” added to them, when the server connection is successful, I’ll join those channels right away, and my session will be ready to go without any interaction from me.

If I wish to see the listing of servers I just added “/server list”, as per the documentation, will show me that list. Again, on a fresh install, there may be more servers than what we have added here, and you can keep them in play, or remove them as needed. If OFTC is already defined in the server list, then you can make changes to the listing as long as the port number, network name, and server url are the same. If there are settings you wish to remove, then you’ll need to “/server remove” and re-add as appropriate.

So, what does our listing show us:

/server list
06:50 Server               Port  Network    Settings
06:50 irc.freenode.net     7000  freenode   autoconnect, ssl, ssl_verify, ssl_capath: /etc/ssl/certs
06:50 irc.oftc.net         6697  oftc       autoconnect, ssl, ssl_cert: ~/.irssi/certs/nick.pem, ssl_verify, ssl_cafile: /etc/ssl/certs/spi-cacert-2008.pem
06:50 localhost            6667  bitlbee    autoconnect

As you can quickly see, where we specified ports for Freenode and OFTC, we didn’t for Bitlbee, so the default IRC port 6667 was added. Of course, don’t forget to “/save”, so you don’t lose your work up to this point.

A cautious word about “/server”. “/server” is used for defining server connections, not for connecting to servers themselves. However, it can connect you to a server should you say something of the effect to “/server irc.mozilla.org”. If you did this, it will disconnect you from your current connections, and ONLY connect to you irc.mozilla.org. This is an unfortunate side-effect that many first time Irssi users discover. The proper method for connecting to irc.mozilla.org is to use “/connect irc.mozilla.org”, as we’ll discuss below.

/connect
Our last command that I plan on covering in this post. With our networks defined and our servers and channels configured, we could easily at this point connect to Freenode, and all of our settings that we’ve set at this point would be applied, which means it will save us SERIOUS amounts of typing in the future, provided you don’t keep setting up Irssi over and over. Let’s first look at the help doc, as we did with the other commands, then we’ll see how simple our life is from here on out.

/help connect
06:58 CONNECT [-4 | -6] [-ssl] [-ssl_cert <cert>] [-ssl_pkey <pkey>] [-ssl_verify] [-ssl_cafile <cafile>] [-ssl_capath <capath>] [-noproxy] [-network <network>] [-host <hostname>] [-rawlog <file>] <address>|<chatnet> [<port> [<password>
              [<nick>]]]
06:58
06:58      -4, -6: specify explicitly whether to use IPv4 or IPv6 address
06:58      -ssl: use SSL when connecting
06:58      -ssl_cert: The SSL client certificate file (implies -ssl)
06:58      -ssl_pkey: The SSL client private key (if not included in the certificate file)
06:58      -ssl_verify: Verify servers SSL certificate
06:58      -ssl_cafile: File with list of CA certificates (implies -ssl_verify)
06:58      -ssl_capath: Directory with CA certificates (implies -ssl_verify)
06:58      -network: the network this connection belongs to
06:58      -ircnet: Same as -network. Deprecated. Do not use.
06:58      -host: the host
06:58      -!: don't autojoin channels
06:58      -rawlog: immediately open rawlog after connected
06:58
06:58 This command makes irssi to connect to specified server. Current connections are kept and a new one is created.
06:58
06:58 See also: SERVER, DISCONNECT, RMRECONNS, SCONNECT

Obviously, “/connect” is verbose, but not as verbose as “/server”. Further, the first thing to note about “/connect” is there is nothing to save. This command just takes the settings you’ve already defined for your networks, and applies them in to the connection string. However, should you not have a defined network or server to connect to, such as maybe connecting to irc.mozilla.org, you can use many of the settings in “/server” here, such as IPV4, IPV6, SSL and so on. So, say I’m wishing to test an IPV6 connection to irc.mozilla.org, I could issue something like the following:

/connect -6 irc.mozilla.org

That’s it! If it succeeds, then maybe I can add it to my server list with “/server add”, as discussed above and “/save” to the config. Maybe I want to test SSL over IPV6 on that network on a specific port. I could do this. Further, because I’ve already defined my networks, I can say something like:

/connect freenode

In this case, I’ll apply all the network settings AND server settings for the “freenode” connection. This keeps me from typing it over and over every time I wish to connect. Further, the network names themselves can be tab completed! Oh, how this makes life much more enjoyable!

At the end of the help document, you’ll notice a couple of additional commands. Namely “/disconnect” and “/rmreconns”. If you’re finished with a network, and wish to disconnect, then “/disconnect” would be what you want. For example, maybe you’re satisfied with your testing of IPV6 over SSL on irc.mozilla.org. Then, from your status window, you will need to tell Irssi that this is the connection you wish to disconnect. To do this, “^x” (control-x) will switch you servers until you reach the right one. Then, when you’ve switched to the right server you could issue:

/disconnect

Further, maybe a “/connect” isn’t working. Maybe you’re trying to reach a host that is currently down, it’s timing out, or the server on a different port than what you specified. As a result, Irssi won’t be able to connect to your preferred server, but it will keep trying. Eventually, maybe the host will become responsive, and a connection can be made. Maybe not. Regardless, Irssi will keep trying your “/connect” one way or the other. This might be undesirable, so running “/rmreconns” will remove any reconnections that Irssi is attempting to make. As with every other Irssi command, “/disconnect” and “/rmreconns” have a help doc.

Conclusion
So, that’s it. I hope this was helpful. If it was just noise, or much of it was confusing, I hope you walk away from this tutorial with at least two things:

1. /help
2. /save

If you can get those two commands deeply cemented in your brain, then you’ll be okay navigating Irssi and learning its ins and outs. Further, while there might be nothing technically wrong with editing the config by hand, Irssi provides powerful, powerful tools that can do it for you keeping the errors out, and the documentation for those tools, while not perfect, is vast and very complete. But, hopefully, you see now the relationship between “/network”, “/server”, “/connect” and “/channel”, and how you can tap into that power to make your Irssi experience more pleasurable.