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.
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.
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 "*!firstname.lastname@example.org email@example.com" 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.
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.
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:
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:
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.
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:
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.