Sometimes, necessity is the mother of invention. I couldn't find any one, definitive guide to setting up a multi-network psyBNC installation from scratch when I set up a shell recently - so after struggling through the process through trial and error (and eventually succeeding) I decided to write one for the benefit of everybody else. (The official psyBNC tutorial is out of date and hasn't been updated in at least 2 years, and it actually tells you to do some things incorrectly, as do many other tutorials on the web, most of which are just copied and pasted).
Why am I doing this? I recently configured a new shell account for my IRC usage, and I had to reacquaint myself with the whims of psyBNC. It's a fearsome beast when it comes to multi-network chatting (one of its best strengths) - but equally, it's a right pain to configure. I use mIRC to chat with, and it also needs to be set up in a particular way so it can authenticate with psyBNC... But let's start from the beginning...
. It's a free telnet/SSH client which will save you oodles of time in the long run, and considering that Windows doesn't ship with inbuilt support for establishing SSH connections, you need a client. The application runs standalone without needing installing, creating files and directories as it requires (so I recommend you put it into C:\putty or its own folder in My Documents / on the Desktop, wherever you prefer).
Fire up PuTTY, and you get the PuTTY Configuration dialog. Put in your shell address / IP in the Host Name box, and leave the Port as 22. Type a name into the box under Saved Sessions (for example 'my IRC shell', name it what you like) and hit Save. Then, either double click it from the list or hit Open. The first time you connect, you will see another dialog showing the connection key for the SSH session, with three options; PuTTY is asking you whether you want to save the session key forever, for this session only or reject it. For ease of use, click the accept always button.
You then see a login dialog... Enter your username and hit enter, then put in your password (it won't show on the screen so be careful typing it) and hit enter. If you were successful, you'll (possibly) see a few screens of information and then you'll get a login prompt. Mine looks like this:
If you see that, you can move onto the next step.
NB: Through this guide, I'm assuming your shell is on a FreeBSD/Linux system. Mine's FreeBSD (my last one was, too). If it's a Windows shell, then that's 1) quite unusual and 2) problematic (you'll have to get a different BNC program).
Enquire with your provider as to whether they offer these, or READ THE MESSAGES when you first log in to see if these commands are listed. I actually installed my own copy of psyBNC before realising that my shell provider provided psyBNC preconfigured - it would've saved me a lot of time and energy, but I enjoy doing things my own way anyway. :)
If your provider only gives you an empty shell account though, your next step is to get a copy of psyBNC... There's no need to get an SFTP client and upload the psyBNC tarball from your machine, one of the handy things about shells is that you can (usually) wget the file you need straight over - and if the box is on a fat pipe, it'll transfer much more quickly anyway. So, go to the official psyBNC site and get the link to the latest release. As I write this, the latest stable is
(dated 04/06/2005); it's old but it works fine.
- right-click and copy the link (or click and drag, then copy it to the clipboard). Moving back to the PuTTY window, type the following:
To do this quickly, just type wget (then hit space) then right-click next to what you've just typed - PuTTY will paste in the URL to the psybnc tarball on the clipboard. Hit enter, and you'll see something like this (not all at once, but you will see it all once the download's finished):
The progress bar will slowly fill up as the file's downloaded, and when it's finished, you can type
To extract the files from the archive, type the following command (NB: almost any platform aside from Windows is case-sensitive, so you must use upper and lowercase where indicated):
will show your current folder path, and if your shell is running bash (or similar) the folder path will be shown at the command prompt.
One of the nicer things about psyBNC is that it comes with a graphical installation tool - to run it, type
... And then the screen will show a blue menu with
at the top.
If this doesn't happen, or you get an error - then something's not configured correctly with your server or shell account - enquire with your provider, they'll be able to help more than I can (every set up is different, and I'm not a BSD or Linux expert). You can configure psyBNC by editing the psybnc.conf file locally and uploading it (or using pico / vi / emacs to edit it from the console), but if you get any of the syntax incorrect, psyBNC won't work properly. All sorts of weird and wonderful behaviour can result from incorrect config files, so I recommend you use the GUI.
Step 3: here's where you configure psyBNC for your initial connection. Follow the instructions carefully and be careful to press the right keys at the right times (for example, to get out of some menus you press Escape, but for some menus you have to choose Ok or Cancel, and press Enter... A bit confusing, but it works once you get used to it).
selected, press Enter. You'll see a screen of default compile options - I recommend you leave everything as-is unless you have specific requirements (for example, I want Encryption with Blowfish support so I make sure that's enabled, but it is by default). I also enabled oIdentd, although I didn't need to (my shell provider runs an oIdentd server which overrides any per-user oIdentd server), but oIdentd gives you the option to specify your ident name (the bit that shows up in IRC before the hostname when you /whois someone.). Make sure Non permanent IRC-Connections is DISABLED, otherwise your BNC will disconnect from IRC whenever you quit the BNC.
Update, January 2009: John LSI
reports that, "it seems that OIDENTD is REQUIRED for SSL functionality (at least on freeBSD). Not including OIDENTD support appears to cause ssl connections to fail." (Thanks John!)
The Version Reply is where you can specify a custom CTCP version reply - it doesn't always work, but you can have some fun with it (putting in CP/M VERS 2.2 COPYRIGHT (C) 1979, DIGITAL RESEARCH
can provoke some amusing reactions!)
When you're done with that, choose Exit
and hit Enter. Go to Bouncer-Config
and hit Enter. for Listening Ports, find the IP address of your server and choose a port number to listen on (by default psyBNC listens on all IPs and on the default port 31337, but I can guarantee you someone else is using that). To put in your IP and port number, choose the single entry, hit Enter, then hit backspace to delete what's written. Replace it with your info in the following format:
127.0.0.1 1234(Obviously 127.0.0.1 will be replaced with the real IP of your server, and pick a port number above 1000 for most success)
Ensure you put a space between the IP and the port to delimit it, don't use a colon or any other symbol. Hit Enter, and you're back at the previous screen - hit Escape to go back to the Option menu.
Leave the Links menu alone, you don't need it. You can give the Bouncer a name (if you like), but it's only really useful if you're creating multi-BNC internal networks or relays, so you can leave it as-is if you like. I just put in a name like "Home".
the Host Allows screen is where you can define whitelists of hosts that are allowed to connect to your shell - if you have a static IP, you can specify it in here, and ensure that you and only you can connect to your shell. If, like most people, you have a dynamic IP, just leave this as it is by default
which allows anyone to connect. Hit Escape to return to the Options menu.
window is where the magic happens: this is where you set up your username to connect to psyBNC. mIRC has an odd behaviour whereby it won't correctly pass the variables to the psyBNC server unless you set it up in a particular way, I'll cover this further down the page.
Here's a sample configuration (to alter any of the values, use the up/down arrow keys and hit Enter to edit the values, then hit Enter to return to the User screen after you're done):
Login: christof (this is your psyBNC username)
Nick: christof (your IRC nick, you can change it later)
Username: christof (this is what appears after your ident@hostname, you can change it later)
Password: (you must define a password. This will be hashed after you compile psyBNC)
VHost: (you can define this later)
Rights: User (I change mine to Admin by selecting it and hitting Enter)
Relaying over Link #: None (leave this)
Using Proxy: (leave this)
Proxy Port: None (leave this)
Network User of User #: None (leave this)
User marked as quitted: No (leave this)
Receive Systemmessages: No (leave this)
Network name of Network User: (leave this)
Reset LastLog (leave this alone!)
At the bottom, you can see theServers
option. You can leave that alone for now and configure your servers through your IRC connection once you're logged on, but if you want to define one server to connect to you can do so here. Go into the Servers page, and add a server - if you have a favourite server, you can put it in here. Like before, you enter the data in the formatservername portnumber
, delimited with a space. I choseirc.blackened.com 6667
from the top of my head, to make sure it could connect ok. Save in the usual manner (hit Ok to close the screen then at the Servers page, hit Escape to return to the User options. To go up again, chooseExit
and hit Enter - this returns you to the Bouncer-Config screen. ChooseExit
and hit Enter, and you're at the root menu. If you're happy with your settings, choose Exit and hit Enter.
The menu will quit and you'll see
"Now compile psyBNC using make, if not yet compiled, or if Options were changed.
What this means is that your options have been saved to the config file, but psyBNC needs to be recompiled for the changes to take effect. You can rehash your options once you're actually using psyBNC from inside your IRC client, but this initial compile needs to be done this way.
Simply type make
and you'll see LOTS of information scroll past you... If you enabled encryption, it will generate an SSL key. Here's what you'll see (with example data in bold)...
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name [DE]:UK
State/Province [Somewhere]: South East
Locality Name (eg, city) : London
Organization Name (eg, company) [tCl]: My Company (optional)
Organizational Unit Name (eg, section) [psyBNC]: My Department (optional)
Common Name (FUll domain of your server) : machine.myshellcompany.com (optional, leave blank if unsure)
After that, it will generate the RSA SSL key and you should see something similar to the following:
psyBNC2.3.2-7-Linux ready. Please read the README before you run psybnc.
make: Leaving directory `/home/christopher/psybnc'
-rwxrwxr-x 1 christopher ab0123456 246348 2008-04-06 16:35 psybnc
Congrats, psyBNC is now compiled! You may see text that looks like warnings or errors, don't worry - if psyBNC fails compilation, it will say so.
To run psyBNC, type./psybnc
- you will see
... And then you'll get a shell prompt again. Congrats, it's working (and listening for incoming connections).
The next step: connecting to psyBNC.
Connecting to psyBNC is a fiddly thing to do sometimes, mIRC can be picky about how it sends the ident and user information to psyBNC (and it's not helpful when it doesn't work). To make sure you can connect, go into the mIRC options and do the following:
- Go into the OptionsFrom the Connect category, choose Identd
- Change your User ID to match your psyBNC username
- From the Local Info option (above Identd) make sure that the IP address option is ticked and the Lookup method is Server. This will help with DCC transfers should you receive any through the BNC at a later date
Save these options (hit OK) and you're ready to rock and roll.
Type /server :
> in the Status bar - this will connect to the psyBNC server. If you know your server already has a domain set up and pointing to it, you can use that instead (for e.g. if you had mybnc.isbrilliant.com and psyBNC was listening on port 28569 and your psyBNC user password was 'awesome123', you'd type "/server mybnc.isbrilliant.com:28569 awesome123)".
If you don't specify a password, you will see this in the Status:
--psyBNC- Your IRC Client did not support a password. Please type /QUOTE PASS yourpassword to connect.
Type /quote pass awesome123
, and provided everything's ok, you'll be logged on.
If you specified an IRC server in menuconfig, psyBNC will now connect to that network - but if you didn't it will just sit there waiting for your next command. This is how I recommend you proceed, so you don't have unnecessary connections before you've actually done your proper configuration.
If your shell provider has a vhost configured for your account (for e.g., mybnc.isbrilliant.com) then once connected, type
psyBNC will reply with
VHOST changed to 'mybnc.isbrilliant.com'.
Provided the reverse DNS (rDNS) is configured correctly on your shell provider's end, your IP should resolve to that hostname, and then anybody else on IRC should see you asuser@hostname
if they whois you (or when you join a channel).
There's a good guide (with screenshots) for configuring mIRC correctly at //www.blueshells.biz/setpsy.html
(I don't expressly recommend them above any other provider, I merely provide the link as a useful resource).
Here's where we get really fancy... Multi-networks.
Whenever you connect, psyBNC will open a private message window to you - and that's where I suggest you type all your commands, because otherwise they may accidentally be directed at the actual IRC server (and can sometimes invoke the wrath of opers!). You can send commands to psyBNC from any window by using/quote
before any command, but it's easier to work within psyBNC's PM window because that's where it will reply to any command you give it.
Ok, example scenario: you primarily chat on EFNet, but you want to also connect to Link-Net, Quakenet and P2P-Net. This is simple enough to configure, as long as you follow some simple steps when adding servers.
psyBNC works on a system of a primary network, then extra networks - if you add a server (with /addserver
) it, by default, is assigned to your primary network.
So, to add another server to EFNet, in the psyBNC PM window type
addnetwork irc.he.net :6667
(Note the space before the colon - you can leave the space out, but I believe it's good practice to delimit the portnumber with a space as well as use a colon.)
You'll then see Server irc.he.net port 6667 (password: None) added.
After a few seconds, if you didn't already have a server listed, psyBNC will begin to connect. It's important to set your hostname with bvhost
BEFORE you connect, otherwise the server will see your shell's default rDNS (which could be something ugly). If you do forget though, set your hostname and then issue jump
- this will make psyBNC disconnect then reconnect using the new vhost.
You can repeat the addserver process several times if you want to add more servers; for EFNet I use
I decided to go with US servers as my shell account's on an American box (why connect to UK IRC servers from the US if there's a closer, more powerful node nearby?)
Tip: If you've added several servers and you want to switch to a specific one, type
Which will show you a list of your servers, numbered. To jump to a particular server, just usejump x
(where 'x' is the number next to the server number, e.g. jump 2
For multi-networks, psyBNC adds a prefix to its entries, any channels you're in and any users in those channels - this is a hardcoded feature, you can't disable it (and it's quite useful once you get used to it). However, this means you have to remember the prefixes - I recommend using two-letter prefixes (e.g. dn for Dalnet, qn for Quakenet, pn for P2P-Net... You get the idea).
You'll have to type this prefix any time you want to issue network-specific commands or changes, so best to keep it short and sweet.
In the following examples, I'll work with the fictional network "xy-net". To add the network, typeaddnetwork xy
(where 'xy' is the prefix ). You'll see New Network 'xy' added by username
(where 'username' is your user).
To add a server to this network, you MUST prefix the server name with the network prefix. If you don't, the server will be added to the serverlist for your primary network!
To add a server to the 'xy' serverlist, type the following:
addserver xy'irc.xy-network.xy :6667
Getting this syntax right is the key to configuring multi-network. NB the apostrophe ('
symbol) between the network prefix and the server name - older tutorials or FAQs show the the delimiter as a tilde (~
), which is outdated and incorrect.
If you add the server, psyBNC will report Server irc.xy-network.xy port 6667 (password: None) added.
Check that it's gone into the right network by issuing listservers xy'
(WITH the apostrophe after the prefix) - it will show a list of 1 servers. If you type listservers xy
without the apostrophe, it will show the primary network's servers - if your latest addition is showing in that list, you went wrong. Note its number, and type delserver z
(where z is its number) and psyBNC will report Server z deleted.
If you enabled SSL support when you compiled psyBNC, you can add an SSL server by issuing addserver S=ssl.xy-network.xy :6669
(if the server is for a secondary network, you add in the network prefix, so the command becomes addserver xy'S=ssl.xy-network.xy :6669
. Of course, you will need to find out the details for the network's SSL server (if it even has an SSL server). The port number will always be different though, so remember that when you're adding the server (unencrypted servers won't accept SSL connections).
Repeat the process for each extra network you want to add. As soon as you add a server to its serverlist, psyBNC will begin to connect. You have to set your bvhost for each network you connect to; to do so for our fictional network, you would type
and psyBNC will report back the usual 'VHOST changed' message. Most other commands work in the same way -setusername
is also network prefix-sensitive, as are commands like jump
would jump to the first server on the xy network, jump
on its own will jump on all servers on all networks).
A word on setusername
- this affects the bit which comes after your ident@hostname when someone /whois
es you... You can change this to anything you like. Mine says 'o hy thar', (hy2u meme fans!) but you can put your name, a message, anything you like. It's easier to do this from psyBNC once you're connected via IRC rather than mess about in menuconfig - I try and spend as little time as possible doing the initial configuration, because there's a much more comprehensive help guide available once you're connected (which you can bring up at any time by typing /quote bhelp
To join a channel on your main network, just type the usual /join #channel
. For other networks, you need to add the network prefix in - so to join #lobby on the xy network, you would type/join xy'#lobby
. The # must come after the network prefix. You can also only login to a channel once you're connected to the network.
Everything else works in the same way - so if you wanted to DCC a file to someone, you can always use the right-click menus, or use the format/dcc send xy'recipient C:\mirc\file.txt
(where 'recipient' is the other person's nick). Rule of thumb is that the network prefix is put before any command where a network-specific username or command is issued.
One last thing - once you're connected to multiple networks, even if you have different nicks on the different networks, you will only ever see the nick for your primary network at your end (although if you connected directly in a second window, you would see the correct nick once you had set it). To set your nick on the secondary xy network, type
/nick xy'differentnick (where 'differentnick' is the nick of your choosing)
mIRC's screen won't update, but other people will see it change. This can cause confusion, but it is just how psyBNC works.
Housekeeping / modifying the config
If for some reason you want to reconfigure an aspect of psyBNC using menuconfig from the console, you must first kill psyBNC by issuing the following command from the shell console:
killall -9 psybnc
This signals all processes matching the name 'psybnc' to exit, and if issued correctly psyBNC will disconnect and quit (and your connection will drop). You can then usemake menuconfig
and change your options accordingly. For every extra network you add, you will see another user in your User list - one very important thing to remember is that if you edit the config once it's changed, the passwords will be in their hashed form. If you want to be able to log on to psyBNC again after recompiling, you MUST re-enter the passwords. If you don't, all you will do when you compile psyBNC is make psyBNC rehash already-hashed passwords! The password is hashed if you see an equals sign (=
) before it, so just select it, hit Enter and retype it, then continue with your changes. A finalmake
once you're out of menuconfig, and issue./psybnc
to start psyBNC back up again. If you didn't stop mIRC from connecting while you were doing this, as soon as psyBNC is running again mIRC will re-establish the connection - and it will automatically send the password for you.
If you want to add your psyBNC connection as a favourite server, the BlueShells page
has screenshots on what to enter and where (you do it through the Add Server dialog, and you put the /quote pass
password into the Password box).
I hope that helps some other people - I had a pain of a time working out the correct syntax for everything because it had been months since I'd last set up a psyBNC shell! If anybody has any questions, you can email me through my company web site's contact form
(I don't give out my email address as it gets enough spam already, but if you fill out the form on that page I will
receive it as an email).
Apologies also for this being such a Windows-and-mIRC-centric guide; I've been a longtime mIRC and Windows user so that's where the bulk of my knowledge (and usage) lies. I'm sure that if you run Linux, you'll know most of this already (especially the console / commandline stuff). Mac users, well... I just irrationally dislike Macs. ;) Plus OS X is based on FreeBSD, so the hardcore users out there (who are more than likely to be using shells for IRC anyway) will have an alright commandline knowledge anyway.
If you're still struggling however, there are many active user forums where you can ask for help. If you Google your query you'll probably find an answer from a fellow user. I aimed this tutorial at being an updated-for-2008, definitive guide for setting up psyBNC, and to provide the web with a consistent list of the correct commands (and their usage) for multi-network chatting, because most of the other guides out there are either contradictory or completely incorrect. Hopefully, I've done alright. If you spot any errors or have more information to add, please let me know.