README.md

   1 # [![ZNC](https://wiki.znc.in/resources/assets/wiki.png)](https://znc.in) - An advanced IRC bouncer
   2
   3 [![Travis Build Status](https://img.shields.io/travis/znc/znc/master.svg?label=linux%2Fmacos)](https://travis-ci.org/znc/znc)
   4 [![Jenkins Build Status](https://img.shields.io/jenkins/s/https/jenkins.znc.in/job/znc/job/znc/job/master.svg?label=freebsd)](https://jenkins.znc.in/job/znc/job/znc/job/master/)
   5 [![AppVeyor Build status](https://img.shields.io/appveyor/ci/DarthGandalf/znc/master.svg?label=windows)](https://ci.appveyor.com/project/DarthGandalf/znc/branch/master)
   6 [![Bountysource](https://www.bountysource.com/badge/tracker?tracker_id=1759)](https://www.bountysource.com/trackers/1759-znc?utm_source=1759&utm_medium=shield&utm_campaign=TRACKER_BADGE)
   7 [![Coverage Status](https://img.shields.io/codecov/c/github/znc/znc.svg)](https://codecov.io/gh/znc/znc)
   8 [![Coverity Scan Build Status](https://img.shields.io/coverity/scan/6778.svg)](https://scan.coverity.com/projects/znc-coverity)
   9
  10 ## Table of contents
  11
  12 - [Minimal Requirements](#minimal-requirements)
  13 - [Optional Requirements](#optional-requirements)
  14 - [Installing ZNC](#installing-znc)
  15 - [Setting up znc.conf](#setting-up-zncconf)
  16 - [Special config options](#special-config-options)
  17 - [Using ZNC](#using-znc)
  18 - [File Locations](#file-locations)
  19 - [ZNC's config file](#zncs-config-file)
  20 - [Writing own modules](#writing-own-modules)
  21 - [Further information](#further-information)
  22
  23 ## Minimal Requirements
  24
  25 Core:
  26
  27 * GNU make
  28 * pkg-config
  29 * GCC 4.8 or clang 3.2
  30 * Either of:
  31     * autoconf and automake (but only if building from git, not from tarball)
  32     * CMake
  33
  34 ## Optional Requirements
  35
  36 SSL/TLS support:
  37 * openssl 0.9.7d or later
  38     * try installing openssl-dev, openssl-devel or libssl-dev
  39     * macOS: OpenSSL from Homebrew is preferred over system
  40
  41 modperl:
  42 * perl and its bundled libperl
  43 * SWIG if building from git
  44
  45 modpython:
  46 * python 3.3+ and its bundled libpython
  47 * perl is a build dependency
  48 * macOS: Python from Homebrew is preferred over system version
  49 * SWIG if building from git
  50
  51 cyrusauth:
  52 * This module needs cyrus-sasl2
  53
  54 Character Encodings:
  55 * To get proper character encoding and charsets install ICU (`libicu4-dev`)
  56
  57 I18N (UI translation)
  58 * CMake-based build only
  59 * Boost.Locale
  60 * gettext is a build dependency
  61
  62 ## Installing ZNC
  63
  64 Currently there are 2 build systems in place: CMake and `./configure`.
  65 `./configure` will eventually be removed.
  66 There is also `configure.sh` which should make migration to CMake easier:
  67 it accepts the same parameters as `./configure`,
  68 but calls CMake with CMake-style parameters.
  69
  70 ### Installing with CMake
  71
  72 Installation from source code is performed using the CMake toolchain.
  73
  74 ```shell
  75 mkdir build
  76 cd build
  77 cmake ..
  78 make
  79 make install
  80 ```
  81
  82 You can use `cmake-gui` or `ccmake` for more interactiveness.
  83
  84 Note for FreeBSD users:
  85 By default base OpenSSL is selected.
  86 If you want the one from ports, use `-DOPENSSL_ROOT_DIR=/usr/local`.
  87
  88 For troubleshooting, `cmake --system-information` will show you details.
  89
  90 ### Installing with `./configure`
  91
  92 Installation from source code is performed using the `automake` toolchain.
  93 If you are building from git, you will need to run `./autogen.sh` first to
  94 produce the `configure` script.
  95
  96 ```shell
  97 mkdir build
  98 cd build
  99 ../configure
 100 make
 101 make install
 102 ```
 103
 104 You can use `./configure --help` if you want to get a list of options, though
 105 the defaults should be suiting most needs.
 106
 107 ## Setting up znc.conf
 108
 109 For setting up a configuration file in `~/.znc` you can simply do
 110 `znc --makeconf` or `./znc --makeconf` for in-place execution.
 111
 112 If you are using SSL you should do `znc --makepem`
 113
 114 ## Special config options
 115
 116 When you create your ZNC configuration file via --makeconf, you are asked
 117 two questions which might not be easy to understand.
 118
 119 > Number of lines to buffer per channel
 120
 121 How many messages should be buffered for each channel. When you connect to
 122 ZNC you get a buffer replay for each channel which shows what was said
 123 last. This option selects the number of lines this replay should consist
 124 of. Increasing this can greatly increase ZNC's memory usage if you are
 125 hosting many users. The default value should be fine for most setups.
 126
 127 > Would you like to keep buffers after replay?
 128
 129 If this is disabled, you get the buffer playback only once and then it is
 130 deleted. If this is enabled, the buffer is not deleted. This may be useful
 131 if you regularly use more than one client to connect to ZNC.
 132
 133 ## Using ZNC
 134
 135 Once you have started ZNC you can connect with your favorite IRC-client to
 136 ZNC. You should use `username:password` as the server password (e.g.
 137 `/pass user:pass`).
 138
 139 Once you are connected you can do `/msg *status help` for some commands.
 140 Every module you have loaded (`/msg *status listmods`) should additionally
 141 provide `/msg *modulename help`
 142
 143 ## File Locations
 144
 145 In its data dir (`~/.znc` is default) ZNC saves most of its data. The only
 146 exception are modules and module data, which are saved in
 147 `<prefix>/lib/znc` and `<prefix>/share/znc`, and the znc binary itself.
 148 More modules (e.g. if you install some later) can be saved in
 149 `<data dir>/modules` (-> `~/.znc/modules`).
 150
 151 In the datadir is only one file:
 152
 153 - `znc.pem` - This is the server certificate ZNC uses for listening and is
 154 created with `znc --makepem`.
 155
 156 These directories are also in there:
 157
 158 - configs - Contains `znc.conf` (ZNC's config file) and backups of older
 159   configs.
 160 - modules - ZNC also looks in here for a module.
 161 - moddata - Global modules save their settings here.
 162   (e.g. webadmin saves the current skin name in here)
 163 - users   - This is per-user data and mainly contains just a moddata
 164   directory.
 165
 166 ## ZNC's config file
 167
 168 This file shouldn't be too hard too understand. An explanation of all the
 169 items can be found on the
 170 [Configuration](https://wiki.znc.in/Configuration) page.
 171 **Warning: it is better not to edit config while ZNC is running.** Use the
 172 [webadmin] and [controlpanel] modules instead.
 173
 174 [webadmin]:https://wiki.znc.in/Webadmin
 175 [controlpanel]:https://wiki.znc.in/Controlpanel
 176
 177 If you changed some settings while ZNC is running, a simple
 178 `pkill -SIGUSR1 znc` will make ZNC rewrite its config file. Alternatively
 179 you can use `/msg *status saveconfig`
 180
 181 ## Writing own modules
 182
 183 You can write your own modules in either C++, python or perl.
 184
 185 C++ modules are compiled by either saving them in the modules source dir
 186 and running make or with the `znc-buildmod` shell script.
 187
 188 For additional info look in the wiki:
 189
 190 - [Writing modules](https://wiki.znc.in/Writing_modules)
 191
 192 Perl modules are loaded through the global module
 193 [ModPerl](https://wiki.znc.in/Modperl).
 194
 195 Python modules are loaded through the global module
 196 [ModPython](https://wiki.znc.in/Modpython).
 197
 198 ## Further information
 199
 200 Please visit https://znc.in/ or #znc on freenode if you still have questions:
 201 - [freenode webchat](https://webchat.freenode.net/?nick=znc_....&channels=znc)
 202 - [ircs://irc.freenode.net:6697/znc](ircs://irc.freenode.net:6697/znc)
 203
 204 You can get the latest development version with git:
 205 `git clone https://github.com/znc/znc.git --recursive`