ZNC · Whatbox

Wiki > ZNC

Official Install

ZNC is now provided by Whatbox, so it's no longer necessary to manually compile ZNC from source.

Configuration

A random port number between 10000 and 32767 is needed and will be used to access ZNC once setup is complete. The port number 19504 has automatically been generated and will be used throughout this article, but can be changed if needed.

Generate an initial configuration. znc --makeconf
At the least, you should worry about enabling the WebAdmin module when prompted. Make sure to select a valid port above 10000. Afterwards, you can access the web interface at http://server.whatbox.ca:19504(use https if you had the configuration use SSL).

Starting

After the initial configuration has been generated, ZNC will automatically start. If you need to restart it in the future, run znc.

An optional step is to add a @reboot line to your crontab, so that if the server is rebooted for any reason, ZNC will automatically restart. See the Cron wiki article for information on how to edit your crontab. The correct job syntax for restarting ZNC is @reboot znc

Modules

See the official ZNC wiki for a list of modules that can be enabled, as well as their respective uses.

Custom Modules

ZNC can be easily extended with custom modules.

Download the custom module to your slot. wget <url> if it's an archive, or git clone <repository url> if it's a git repo.
If archive, extract it, tar -xvf <archive filename> and remove it once extracted. rm <archive filename>
Make the newly acquired folder your working directory. cd <module source directory>
Compile the module. znc-buildmod *.cpp
Install the module. mkdir -p ~/.znc/modules/; cp *.so ~/.znc/modules/
Load the module. In IRC: /msg *status LOADMOD [--type=global|user|network] <module name>

Custom Modules Troubleshooting

Some modules require compile flags set that Whatbox has not set by default. If this affects you, the manual install instructions below may interest you.

This section will be expanded upon as more issues are encountered. Anyone can edit this wiki page, so if you have a problem and find a solution, please share it!

Custom Modules and Server Updates

Custom modules must be re-built any time a new version of ZNC is installed on the server, or when system updates upgrade shared libraries that ZNC depends on. When this happens, you'll receive an error similar to the following when attempting to start ZNC:

znc: error while loading shared libraries: libicuuc.so.55: cannot open shared object file: No such file or directory

Because of this, you may want to keep the source for the modules you use handy in the event you want to quickly get ZNC up and running again after a server update.

After initially compiling each module, copy its source to your modules folder. cp *.cpp ~/.znc/modules/
When a server update occurs and znc no longer loads because of your modules, navigate to your module directory and delete your .so files: cd ~/.znc/modules/ && rm *.so
Compile your modules. znc-buildmod *.cpp
Attempt to start znc again. znc

Manual Install

If you prefer, you can still manually compile ZNC from source.

Note: If you previously used these instructions and find that certain workflows below do not work for you now, you may find that ZNC was previously installed into ~/znc/bin/ instead of ~/bin/, and should adjust your commands accordingly.

Download and Install

Download the latest source tarball. wget http://znc.in/releases/znc-latest.tar.gz
Extract the downloaded archive. tar -xzvf znc*.*gz
Remove the downloaded archive once extracted. rm znc-latest.tar.gz
Make the newly extracted folder your working directory. cd znc-*
Configure the installation. ./configure --prefix=$HOME
Begin compilation of the application using the settings used in the previous step. make clean; make
Install the application. make install
Steps 6 and 7 can take some time, so just wait for it to complete.

Configuration

A random port number between 10000 and 65535 is needed and will be used to access ZNC once setup is complete. The port number 19504 has automatically been generated and will be used throughout this article, but can be changed if needed.

Generate an initial configuration. ~/bin/znc --makeconf
At the least, you should worry about enabling the WebAdmin module when prompted. Make sure to select a valid port above 10000. Afterwards, you can access the web interface at http://server.whatbox.ca:19504(use https if you had the configuration use SSL).

Starting

After the initial configuration has been generated, ZNC will automatically start. If you need to restart it in the future, run ~/bin/znc.

Modules

See the official ZNC wiki for a list of modules that can be enabled, as well as their respective uses.

Updates/Troubleshooting

Sometimes system updates performed on the server will upgrade the libraries that ZNC depends on, leading to error messages similar to the following:

/home/user/znc/bin/znc: error while loading shared libraries: libicuuc.so.55: cannot open shared object file: No such file or directory

In the event that this happens, you will need to recompile (and optionally upgrade) ZNC by following the Download and Install directions again and starting ZNC with ~/bin/znc. To only perform the recompile, start at step #3, otherwise start at step #1 to perform any available upgrades. Because ZNC is already configured, the Configuration section does not need to be performed again.

If you have any configurations that you cannot lose, you may first want to backup ~/znc and ~/.znc in case anything goes wrong with the installation.