Install ZNC from Source on Debian

Updated by Elle Krout

Contribute on GitHub

View Project | View File | Edit File

ZNC is an IRC bouncer. It’s designed to run on a server that remains connected to an IRC network and buffer messages. With ZNC, a local IRC client can connect and disconnect without losing a chat session or missing any messages. In this guide, ZNC will be installed from source and then configured.

This guide is written for a non-root user. Commands that require elevated privileges are prefixed with sudo. If you’re not familiar with the sudo command, check our Users and Groups guide.

Before You Begin

  1. Make sure the system is up to date:

    1
    sudo apt-get update && sudo apt-get upgrade -y
    
  2. Install the build-essential and checkinstall packages:

    1
    sudo apt-get install build-essential checkinstall
    
  3. If you want to use SSL encryption to connect to the web interface (recommended), install libssl-dev:

    1
    sudo apt-get install libssl-dev
    

Install ZNC

  1. Download the latest version of ZNC (1.6.0 at the time of writing):

    1
    wget http://znc.in/releases/znc-1.6.0.tar.gz
    
  2. Expand the archive file:

    1
    tar -xvf znc-1.*.tar.gz
    
  3. Move into the ZNC directory:

    1
    cd znc-1.6.0
    
  4. Run the configure script to make sure the Linode has all the needed prerequisites:

    1
    ./configure
    

    If not, you will need to install any missing packages prior to continuing.

  5. Install ZNC:

    1
    2
    make
    sudo checkinstall --fstrans=0 make install
    

    The program checkinstall creates a .deb package which you can use to reinstall this version of ZNC in the future. It has its own set of options to review. If you prefer, you can instead run sudo make install to install ZNC as is.

Configure ZNC

  1. Begin the configuration process:

    1
    znc --makeconf
    
  2. This will launch an interactive script asking you for input on a variety of parameters. Below is an example output of the makeconf script with standard options selected. To match your needs, you can use or change the provided input at your discretion. If you’re not sure, use the default option. Many of these options can be adjusted later through the web interface.

    Make sure to change the username variable.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    [ .. ] Checking for list of available modules...
    [ >> ] ok
    [ ** ] Building new config
    [ ** ]
    [ ** ] First let's start with some global settings...
    [ ** ]
    [ ?? ] What port would you like ZNC to listen on? (1025 to 65535): 5678
    [ ?? ] Would you like ZNC to listen using SSL? (yes/no) [no]: yes
    [ ?? ] Would you like ZNC to listen using both IPv4 and IPv6? (yes/no) [yes]:
    [ .. ] Verifying the listener...
    [ >> ] ok
    [ ** ]
    [ ** ] -- Global Modules --
    [ ** ]
    [ ** ] +-----------+----------------------------------------------------------+
    [ ** ] | Name      | Description                                              |
    [ ** ] +-----------+----------------------------------------------------------+
    [ ** ] | partyline | Internal channels and queries for users connected to znc |
    [ ** ] | webadmin  | Web based administration module                          |
    [ ** ] +-----------+----------------------------------------------------------+
    [ ** ] And 9 other (uncommon) modules. You can enable those later.
    [ ** ]
    [ ?? ] Load global module <partyline>? (yes/no) [no]:
    [ ?? ] Load global module <webadmin>? (yes/no) [no]: yes
    [ ** ]
    [ ** ] Now we need to set up a user...
    [ ** ]
    [ ?? ] Username (AlphaNumeric): user
    [ ?? ] Enter Password:
    [ ?? ] Confirm Password:
    [ ?? ] Would you like this user to be an admin? (yes/no) [yes]:
    [ ?? ] Nick [user]: user
    [ ?? ] Alt Nick [user_]:
    [ ?? ] Ident [user]:
    [ ?? ] Real Name [Got ZNC?]:
    [ ?? ] Bind Host (optional):
    [ ** ] Enabled user modules [chansaver, controlpanel]
    [ ** ]
    [ ?? ] Set up a network? (yes/no) [yes]:
    [ ** ]
    [ ** ] -- Network settings --
    [ ** ]
    [ ?? ] Name [freenode]:
    [ ?? ] Server host [chat.freenode.net]:
    [ ?? ] Server uses SSL? (yes/no) [yes]:
    [ ?? ] Server port (1 to 65535) [6697]:
    [ ?? ] Server password (probably empty):
    [ ?? ] Initial channels:
    [ ** ] Enabled network modules [simple_away]
    [ ** ]
    [ .. ] Writing config [/home/elle/.znc/configs/znc.conf]...
    [ >> ] ok
    [ ** ]
    [ ** ] To connect to this ZNC you need to connect to it as your IRC server
    [ ** ] using the port that you supplied.  You have to supply your login info
    [ ** ] as the IRC server password like this: user/network:pass.
    [ ** ]
    [ ** ] Try something like this in your IRC client...
    [ ** ] /server <znc_server_ip> +5678 user:<pass>
    [ ** ]
    [ ** ] To manage settings, users and networks, point your web browser to
    [ ** ] https://<znc_server_ip>:5678/
    [ ** ]
    [ ?? ] Launch ZNC now? (yes/no) [yes]:
    [ .. ] Opening config [/home/elle/.znc/configs/znc.conf]...
    [ >> ] ok
    [ .. ] Loading global module [webadmin]...
    [ >> ] [/usr/local/lib/znc/webadmin.so]
    [ .. ] Binding to port [+5678]...
    [ >> ] ok
    [ ** ] Loading user [user]
    [ ** ] Loading network [freenode]
    [ .. ] Loading network module [simple_away]...
    [ >> ] [/usr/local/lib/znc/simple_away.so]
    [ .. ] Adding server [chat.freenode.net +6697 ]...
    [ >> ] ok
    [ .. ] Loading user module [chansaver]...
    [ >> ] ok
    [ .. ] Loading user module [controlpanel]...
    [ >> ] ok
    [ .. ] Forking into the background...
    [ >> ] [pid: 27369]
    [ ** ] ZNC - 1.6.0 - http://znc.in
    

    Once you’ve completed the configuration and launched ZNC, you can access the web interface by going to your Linode’s IP address in your web browser. Be sure to specify the port you defined during the configuration script and prefix it with https:// .

    If the Firewall portion of the Securing Your Server guide has been completed, add a line to /etc/iptables.firewall.rules allowing traffic to your IRC port.

    ZNC's Web Admin

Connect to The Client

You can use any preferred GUI or CLI client to connect to ZNC. For the example below, we’ll be using HexChat.

  1. Open HexChat, add your desired nicknames, and then create a new network. In this example, the network is called ZNCserver:

    ZNC

  2. With ZNCserver selected, click Edit....

  3. Add your server’s IP address and port to the list. If not using a signed certificate, select Accept invalid SSL certificated. Input your password:

    ZNC

    Close the window when done.

  4. Press Connect. You should be connected to your ZNC server and from there to any networks and channels you’ve configured to autojoin.

SSL Encryption with a Signed Certificate (Optional)

If you would like to use a signed certificate to encrypt your connection to ZNC, you can do so by adding your key and certificate to the znc.pem file:

1
cat domain.key domain.crt > znc.pem

This guide is published under a CC BY-ND 4.0 license.