installing_irc_at_home []

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Installing IRC at Home ======

Not because you need to, but because you can.

===== Summary =====

This how-to covers installing and IRC server and clients for a typical home LAN. The hardware and OS used is a Raspberry Pi 2 with FreeBSD 12.1, but any system with a recent BSD variant should work with little need or no modification.

At the time of writing, the SDF servers run InspIRCd for the server side and ircII for the default client. The same software is used in this document. In addition, this how-to covers Pidgin, a Windows/Mac GUI client that can be used for IRC as well as other instant messaging protocols. Mozilla Thunderbird has IRC capabilities and is covered as well.

===== Installing Server-Side Software =====

This section details how to install the InspIRCd server as well as ircII client using pkgtool.

Log in as root to run the following pkg commands:
  * pkg update
  * pkg install inspircd
  * pkg install ircii

===== Configuring InspIRCd =====

Configuring the server software is by far the majority of effort required. I am adding some diffs of the config at the end of this document so you can check your work.

You'll need to run everything in this section as the root user.

First, change directory to /usr/local/etc/inspircd. This is where all of the configuration files are.

==== inspircd.conf ====

Next, use your favorite text editor to open up inspircd.conf.

The file is quite large, but the majority is comments and instructions. The changes to be made will include section names. Section names are in centered and written in all caps inside the file, so they're easy to find.

=== SERVER DESCRIPTION ===

Start with the section entitled SERVER DESCRIPTION. Here you will find the server configuration spread out over several lines and interspersed with comments. For the examples in this document, I am naming the server "beastie" after the FreeBSD mascot. My server section (without the comments) looks like this:

<code>
<server name="beastie.home.lan"
  description="Beastie’s World"
  network="Home">
</code>

As noted in the configuration file's comments, this DNS name does not need to resolve to an IP address, so don't worry if your only DNS is provided by your ISP.

=== ADMIN INFORMATION ===

The next section to be edited is ADMIN INFORMATION. This is where the server administrator's contact information goes. Like the server description, it is purely informational and does not have to be a real email address or resolvable DNS name. Following my example so far, here's what I have:

<code>
<admin
  name="Beastie"
  nick="beastie"
  email="beastie@beastie.home.lan">
</code>

Again, this is all just a made-up tribute to the FreeBSD mascot. You can enter whatever you like for your set-up.

=== PORT CONFIGURATION ===

Most of the PORT CONFIGURATION section can be left as it is. However, the last two lines are used to open ports allowing other IRC servers to connect to ours. In a home LAN environment, with a single server, this will never happen.

So, find these lines:

<code>
<bind address="" port="7000,7001" type="servers">
<bind address="1.2.3.4" port="7005" type="servers" ssl="openssl">
</code>

Comment them by adding a hash as the first character so they look like this:

<code>
#<bind address="" port="7000,7001" type="servers">
#<bind address="1.2.3.4" port="7005" type="servers" ssl="openssl">
</code>
 
=== CONNECTIONS CONFIGURATION ===

After commenting out the last two lines of PORT CONFIGURATION, so we can move on to CONNECTIONS CONFIGURATION. The changes here involve changing resolvehostnames="yes" to resolvehostnames="no" and changing the IP address range in an example section.

The reason for changing resolvehostnames is entirely because of DNS as you might have guessed. Unless you are running a robust DNS infrastructure on your LAN, chances are good that your ISP's router (the typical home LAN DNS server) will not do reverse look-ups. Setting resolvehostnames="no" will instruct InspIRCd to not even try, sparing you countless warning messages.

If you have a more robust DNS server on your network, you can certainly leave this as-is. If you see errors like "Could not resolve your hostname: Malformed answer" when logging in, it means the reverse lookups are not working.

There are two resolvehostnames="yes" entries that must be changed. They should look like this when you're done:

<code>
resolvehostnames="no"
</code>

Do not give into the temptation to comment the lines out. This is not the same as setting it to no.

As for the IP address range that needs changing, this is in the example <connect:allow> class. There is a sample IP range of 203.0.113.* being allowed. This section should be deleted or at least have the IP range changed to your home LAN's range of addresses. Typical home setups use 192.168.0.* and that is what is shown here.

<code>
allow="192.168.0.*"
</code>

=== Enabling Server Operators ===

Slipped in between the headings of CIDR CONFIGURATION and MISCELLANEOUS CONFIGURATION is a little, unassuming line that looks like this:

<code>
#<include file="opers.conf">
</code>

It needs to be uncommented if you want to enable users to gain administrative privileges. If you don't remove the leading hash, any attempt to use the /OPER command will result in the message "Invalid oper credentials".

It should look like this when you're done:

<code>
<include file="opers.conf">
</code>

=== Sections left as default ===

These are the sections that do not need changes and can be skipped over:
  * MISCELLANEOUS CONFIGURATION
  * DNS SERVER
  * PID FILE
  * LIST MODE LIMITS
  * SERVER OPTIONS
  * PERFORMANCE CONFIGURATION
  * SECURITY CONFIGURATION
  * LIMITS CONFIGURATION
  * PATHS CONFIGURATION
  * WHOWAS OPTIONS
  * BAN OPTIONS
  * INSANE BAN OPTIONS

=== MODULES ===

The next section to need editing is MODULES. You will have scrolled by quite a few sections to get there.

There is only one change to be made in the MODULES section and that is to uncomment the line that reads: #<include file="modules.conf">, by removing the leading hash character.

It should look like this when you're done:

<code>
<include file="modules.conf">
</code>

This has the effect of instructing InspIRCd to process all the directives in modules.conf as well as the ones in the main configuration file. The reason for doing this is to enable the permanent channels feature. We'll get to that as soon as we save the changes to the inspircd.conf file.

There is no need to change anything in the SERVICES CONFIGURATION section or anything else in inspircd.conf.

==== modules.conf ====

After including modules.conf inside of inspircd.conf, the next step is to edit modules.conf. The main reason for using modules.conf in this how-to document is to use the permanent channel feature. This involves uncommenting a line and adding another to define the permanent channel.

But, while we're editing, there are two more handy modules to enable. Those are "sha256" and "password_hash" and are used for avoiding plain-text passwords. All of this gives us three uncomments and one new line for modules.conf.

  * <module name="sha256">
  * <module name="password_hash">
  * <module name="permchannels">
  * <permchannels channel="#home" topic="Is where the <3 is.">

Open modules.conf and search for them one at a time. Remove the hash symbol at the start to uncomment the module.

What started as this:
<code>
#<module name="sha256">
</code>

Should look like this:
<code>
<module name="sha256">
</code>

Make sure to uncomment all three modules.

A little less than 20 lines after uncommenting the permchannels module, you will see a permanent channel definition that's commented out. It looks like this: #<permchannels channel="#opers" modes="isP" topic="Opers only.">

It's just an example line showing how to configure a permanent channel. On the line after that, you can add your own to set up your permanent channel. Mine looks like this:

<code>
<permchannels channel="#home" topic="Is where the <3 is.">
</code>

Notice I removed the modes attribute. It is not required, and defaults suit me fine here.

There is no more configuration needed for the modules.conf file.

==== opers.conf ====

Opers, or server operators, are the administrators of the IRC server and can invoke special privileges using the /OPER command. You might be able to run IRC on a home LAN and never need any of the administrative privileges, so if you wish to skip this file, you can. It's simply included for the sake of being complete.

For InspIRCd, the opers.conf is where everything concerning this special ability is configured.

Open up opers.conf in a text editor.

What you see under the headings of CLASS CONFIGURATION and OPERATOR COMPOSITION can be left as default. It's the OPERATOR CONFIGURATION section we're interested in.

There are a couple examples given using the names Attila and Brain. Look them over to read the comments and then delete them. Yes, delete. Delete everything after the section heading.

When you're done, the opers.conf file should end here:

<code>
#-#-#-#-#-#-#-#-#-#-#-  OPERATOR CONFIGURATION   -#-#-#-#-#-#-#-#-#-#-#
#                                                                     #
#   Opers are defined here. This is a very important section.         #
#   Remember to only make operators out of trustworthy people.        #
#                                                                     #
</code>

We'll insert our operator after this. In keeping with the rest of the how-to, the operator will be named "beastie" and beastie will have full network admin privileges.

Here's what it will look like:

<code>
#-#-#-#-#-#-#-#-#-#-#-  OPERATOR CONFIGURATION   -#-#-#-#-#-#-#-#-#-#-#
#                                                                     #
#   Opers are defined here. This is a very important section.         #
#   Remember to only make operators out of trustworthy people.        #
#                                                                     #
<oper
    name="beastie"
    hash="sha256"
    password="1ec1c26b50d5d3c58d9583181af8076655fe00756bf7285940ba3670f99fcba0"
    host="*@*"
    type="NetAdmin">
</code>

The above should be pretty self-explanatory based on the key=value pairs you see. The two things that require a little clarification are probably password and host. Specifically, where did the password value come from and what does "*@*" mean?

The value for the password is a sha256 hash of the word s3cret. You may remember that was the plain-text password used for Attila in the opers.conf example that we deleted. You can create a new password hash using the sha256 command-line utility included with FreeBSD.

Here's the command to encode the s3cret password and the resulting hash.

<code>
# sha256 -s s3cret
SHA256 ("s3cret") = 1ec1c26b50d5d3c58d9583181af8076655fe00756bf7285940ba3670f99fcba0
</code>

The answer to the question of host="*@*" comes down to wildcards. * is treated as a wildcard matching any possible value. In this case, any user from any host is allowed to use /oper mode and become admin provided they know the password. This is not secure, but for purposes of a home LAN, where you trust your users, it's fine.

It would also be difficult to enforce in an environment were there are no reverse DNS lookups and IPs are handed out from a DHCP server. In other words, neither user@hostname nor user@192.168.x.x would work reliably. "user@*" could be used to give only one account the admin ability. On a home LAN, this is the best we can do. 

Other than changing the lame password, there's one more step for opers.conf, and that is to change the vhost under the OPERATOR COMPOSITION section. This is purely cosmetic, but it helps show that we pay attention to details.

Right around line 75 of opers.conf, you'll see:

<code>
vhost="netadmin.omega.example.org"
</code>

Following the naming used in the example, change this to:

<code>
vhost="netadmin.beastie.home.lan"
</code>

If you have customized the domain names to something else, by all means use that.

==== motd.txt ====

Finally, we get to the last InspIRCd file that needs to be edited. This is the motd.txt file that is displayed whenever users log onto the IRC server.

The reason for editing this is to simplify things. The included motd.txt file includes some fabulous ASCII art that causes any server messages to scroll right off the screen. I've changed mine to be a simple one-liner, like this:

<code>
Welcome to Beastie's World.
</code>

And that's it for configuration of the InspIRCd server. There are diffs at the end of this document if you want something to check against. Otherwise, it's time to start it up.

===== Starting InspIRCd =====

The following two commands will enable and start inspircd:
  * sysrc inspircd_enable="YES"
  * service inspircd start

To verify it's up and running, use:
  * service inspircd status
  * sockstat | grep 6667

If all is well, you should see something like this:

<code>
root@beastie:/usr/local/etc/inspircd # service inspircd status
inspircd is running as pid 7179.
root@beastie:/usr/local/etc/inspircd # sockstat -l | grep 6667
ircd     inspircd   7179  13 tcp46  *:6667                *:*
</code>

Port 6667/TCP is the de facto standard port for IRC. Sockstat -l shows that it's a listening port.

===== Local Client Connection =====

Seeing InspIRCd running is one thing. Connecting to it is another. We'll use the ircII client that was installed at the beginning of this how-to to verify.

For this part you will need to be a regular, non-root user.

The command is: irc <nickname> localhost

It should look something like this when successful:

<code>
$ irc beastie localhost
*** Connecting to port 6667 of server localhost
*** Welcome to the Home IRC Network beastie!user@127.0.0.1 (from
+beastie.home.lan)
*** Your host is beastie.home.lan, running version InspIRCd-3
*** This server was created 07:39:10 Jul 02 2020
*** umodes available iosw, channel modes available Pbiklmnopstv
*** AWAYLEN=200 CASEMAPPING=ascii CHANLIMIT=#:20 CHANMODES=b,k,l,Pimnpst
+CHANNELLEN=64 CHANTYPES=# ELIST=CMNTU HOSTLEN=64 KEYLEN=32 KICKLEN=255
+LINELEN=512 MAXLIST=b:100 are supported by this server
*** MAXTARGETS=20 MODES=20 NETWORK=Home NICKLEN=30 PREFIX=(ov)@+ SAFELIST
+STATUSMSG=@+ TOPICLEN=307 USERLEN=10 WHOX are supported by this server
*** There are 0 users and 0 invisible on 1 servers
*** 1 unknown connections
*** 0 channels have been formed
*** This server has 0 clients and 0 servers connected
*** Current local users: 0  Max: 1
*** Current global users: 0  Max: 1
*** beastie.home.lan message of the day
***  Welcome to Beastie's World.
</code>

If you've made it to this point without any errors, congratulations, InspIRCd is up and running.

The remainder of this how-to will focus on the IRC client.

===== Customizing ircII =====

In this section, there are a couple of time saving customizations that can be made. One is to specify a default server and the other is to specify a default channel. Neither are strictly necessary, but are included to save some keystrokes.

By the time you complete this short section, you can simply type irc on the command-line and go to channel #home on your server.

==== ircII.servers ====

The first file is created in the /usr/local/share/irc/ directory. It's called ircII.servers and contains a list of server names, each on its own line.

Here's what it looks like if you've been using the names in this how-to:

<code>
# cat /usr/local/share/irc/ircII.servers
beastie
</code>

You need to be root to create or modify the file and the effect is system-wide. Anyone using the ircII client will have the same server.

==== .ircrc ====

The next file is .ircrc and it resides in the root of each user's home directory. You should be logged in as a non-root user to create it.

To go straight to the #home channel when logging on, .ircrc should look like this:

<code>
$ cat .ircrc
channel #home
</code>

Of course, if you then decide to connect to the SDF IRC server using your shiny new installation of ircII at home, you will end up creating a channel called #home. Further customization of this file can be done, but is beyond the scope of this how-to.

===== InspIRCd Diffs =====

I promised you diffs of the customizations made to the InspIRCd configuration. Here they are:

==== inspircd.conf ====

<code>
89c89
<         name="penguin.omega.org"
---
>         name="beastie.home.lan"
92c92
<         description="Waddle World"
---
>         description="Beastie's World"
102c102
<         network="Omega">
---
>         network="Home">
113c113
<        name="Johnny English"
---
>        name="Beastie"
116c116
<        nick="MI5"
---
>        nick="beastie"
120c120
<        email="MI5@the.best.secret.agent">
---
>        email="beastie@beastie.home.lan">
225,226c225,226
< <bind address="" port="7000,7001" type="servers">
< <bind address="1.2.3.4" port="7005" type="servers" ssl="openssl">
---
> #<bind address="" port="7000,7001" type="servers">
> #<bind address="1.2.3.4" port="7005" type="servers" ssl="openssl">
278c278
<          allow="203.0.113.*"
---
>          allow="192.168.0.*"
313c313
<          resolvehostnames="yes"
---
>          resolvehostnames="no"
449c449
<          resolvehostnames="yes"
---
>          resolvehostnames="no"
497c497
< #<include file="opers.conf">
---
> <include file="opers.conf">
1044c1044
< #<include file="modules.conf">
---
> <include file="modules.conf">
</code>

==== modules.conf ====

<code>
49c49
< #<module name="sha256">
---
> <module name="sha256">
1640c1640
< #<module name="password_hash">
---
> <module name="password_hash">
1683c1683
< #<module name="permchannels">
---
> <module name="permchannels">
1700a1701
> <permchannels channel="#home" topic="Is where the <3 is.">
</code>

==== opers.conf ====

This is an abreviated diff of opers.conf since most of the changes involved deleting the bottom third of the file.

<code>
75c75
<     vhost="netadmin.omega.example.org"
---
>     vhost="netadmin.beastie2.home.lan"
94,95d93
<
< # Operator account with a plaintext password.
97,99c95,99
<       # name: Oper login that is used to oper up (/OPER <username> <password>).
<       # Remember: This is case sensitive.
<       name="Attila"
---
>     name="beastie"
>     hash="sha256"
>     password="1ec1c26b50d5d3c58d9583181af8076655fe00756bf7285940ba3670f99fcba0"
>     host="*@*"
>     type="NetAdmin">
101,181d100
[Not shown for brevity.]
</code>

==== motd.txt ====

motd.txt is not included since it is simply removing everything and replacing with a single line.

===== Pidgin for GUI clients =====

There are many IRC clients available for GUI clients like Windows or MacOS. Pidgin was chosen because it is available on a wide variety of platforms and also supports more than one messaging protocol. It's also very simplistic compared to IRC-specific software and that can be a plus for novice users.

Start by downloading from [[http://pidgin.im/]] and installing. 

Next, create an account.

  * Choose a protocol of IRC.
  * Fill in the login and server that you use on your LAN.
  * Password is not required for IRC, and be aware that it is saved in clear text in the %APPDATA% directory if you use it.
  * The remaining tabs may be left with default settings.

Once you can successfully connect to the server, you can add the default channel in Pidgin's Buddy List.

  * Open the Buddy List.
  * Choose the Buddies menu item and select Add Chat from the drop-down.
  * Make sure your IRC Account is shown at the top.
  * Fill in the channel name. (In the example, the permanent channel name was #home)
  * Check the box for Automatically join...

Finally, give the new connection a test and see if you end up in the #home channel on your local server.

See this WikiHow article for a guided step-by-step with pictures: [[ https://www.wikihow.com/Automatically-Join-an-IRC-Channel-in-Pidgin ]]

===== Thunderbird for GUI clients =====

In addition to email, Thunderbird also has IRC capabilities. To access, find Chat on the toolbar. It's after Get Messages and Write. Click Chat.

Unless you've set up Thunderbird as a chat client previously, you'll be looking at a message that say you haven't set up any chat accounts, and a button labeled Get Started. Click on Get Started.

Follow the set-up wizard.

  * Select IRC as the network.
  * Enter your nickname and IRC server hostname (beastie.home.lan if you're following the example.)
  * You can leave the password blank.
  * Change the port to 6667 in the Advanced Options.
  * Remove the check for Use SSL in the Advanced Options.

Leave the box checked for connect Connect to This Account Now to test.

====== Go Forth and Conquer ======

Now that you're running IRC at home, remember to get everyone else in your household using ircII or Pidgin so you can pester them with messages with just the stroke of a keyboard.