]>
Commit | Line | Data |
---|---|---|
11ba3ff9 | 1 | # [![ZNC](logo.png)](https://znc.in) - An advanced IRC bouncer |
f63c3131 | 2 | |
525aac56 | 3 | [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/znc/znc/build.yml?branch=master&label=linux)](https://github.com/znc/znc/actions/workflows/build.yml) |
98a1a2dd | 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/) |
bc77cf79 | 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) |
f1c721ce | 6 | [![Coverage Status](https://img.shields.io/codecov/c/github/znc/znc.svg)](https://codecov.io/gh/znc/znc) |
9aa1df15 U |
7 | |
8 | ## Table of contents | |
e6bff0c3 | 9 | |
a75ad25a JA |
10 | - [Minimal Requirements](#minimal-requirements) |
11 | - [Optional Requirements](#optional-requirements) | |
12 | - [Installing ZNC](#installing-znc) | |
13 | - [Setting up znc.conf](#setting-up-zncconf) | |
14 | - [Special config options](#special-config-options) | |
15 | - [Using ZNC](#using-znc) | |
16 | - [File Locations](#file-locations) | |
17 | - [ZNC's config file](#zncs-config-file) | |
18 | - [Writing own modules](#writing-own-modules) | |
19 | - [Further information](#further-information) | |
7a157b26 | 20 | |
9aa1df15 | 21 | ## Minimal Requirements |
7a157b26 | 22 | |
23 | Core: | |
e6bff0c3 | 24 | |
a405aadd TK |
25 | * GNU make |
26 | * pkg-config | |
53f0751f | 27 | * GCC 8 or clang 5 |
3c62741b | 28 | * CMake 3.13 |
7a157b26 | 29 | |
9aa1df15 | 30 | ## Optional Requirements |
7a157b26 | 31 | |
a405aadd TK |
32 | SSL/TLS support: |
33 | * openssl 0.9.7d or later | |
34 | * try installing openssl-dev, openssl-devel or libssl-dev | |
c7c878ad | 35 | * macOS: OpenSSL from Homebrew is preferred over system |
54d8cd68 | 36 | |
7a157b26 | 37 | modperl: |
a405aadd TK |
38 | * perl and its bundled libperl |
39 | * SWIG if building from git | |
54d8cd68 US |
40 | |
41 | modpython: | |
9ea9d308 | 42 | * python 3.4+ and its bundled libpython |
9ba1ea46 | 43 | * perl is a build dependency |
c7c878ad | 44 | * macOS: Python from Homebrew is preferred over system version |
a405aadd | 45 | * SWIG if building from git |
54d8cd68 | 46 | |
71df50ec | 47 | cyrusauth: |
a405aadd | 48 | * This module needs cyrus-sasl2 |
54d8cd68 | 49 | |
a405aadd TK |
50 | Character Encodings: |
51 | * To get proper character encoding and charsets install ICU (`libicu4-dev`) | |
7a157b26 | 52 | |
8d34d9c8 | 53 | I18N (UI translation): |
2e31a8ee AS |
54 | * Boost.Locale |
55 | * gettext is a build dependency | |
56 | ||
8d34d9c8 AS |
57 | Argon2 password hash: |
58 | * libargon2 | |
59 | ||
9aa1df15 | 60 | ## Installing ZNC |
7a157b26 | 61 | |
561a1805 AS |
62 | Installation from source code is performed using the CMake toolchain. |
63 | ||
64 | ```shell | |
ece09d11 AS |
65 | mkdir build |
66 | cd build | |
67 | cmake .. | |
561a1805 AS |
68 | make |
69 | make install | |
70 | ``` | |
71 | ||
72 | You can use `cmake-gui` or `ccmake` for more interactiveness. | |
73 | ||
dd42fcd2 AS |
74 | There is also `configure.sh` which should make migration to CMake easier: |
75 | it accepts the same parameters as old `./configure`, | |
76 | but calls CMake with CMake-style parameters. | |
77 | ||
561a1805 AS |
78 | Note for FreeBSD users: |
79 | By default base OpenSSL is selected. | |
80 | If you want the one from ports, use `-DOPENSSL_ROOT_DIR=/usr/local`. | |
81 | ||
82 | For troubleshooting, `cmake --system-information` will show you details. | |
83 | ||
9aa1df15 | 84 | ## Setting up znc.conf |
7a157b26 | 85 | |
e6bff0c3 | 86 | For setting up a configuration file in `~/.znc` you can simply do |
79821695 | 87 | `znc --makeconf` or `./znc --makeconf` for in-place execution. |
7a157b26 | 88 | |
79821695 | 89 | If you are using SSL you should do `znc --makepem` |
7a157b26 | 90 | |
9aa1df15 | 91 | ## Special config options |
b475f5d6 | 92 | |
79821695 MS |
93 | When you create your ZNC configuration file via --makeconf, you are asked |
94 | two questions which might not be easy to understand. | |
b475f5d6 | 95 | |
96 | > Number of lines to buffer per channel | |
e6bff0c3 | 97 | |
79821695 MS |
98 | How many messages should be buffered for each channel. When you connect to |
99 | ZNC you get a buffer replay for each channel which shows what was said | |
100 | last. This option selects the number of lines this replay should consist | |
101 | of. Increasing this can greatly increase ZNC's memory usage if you are | |
102 | hosting many users. The default value should be fine for most setups. | |
b475f5d6 | 103 | |
104 | > Would you like to keep buffers after replay? | |
e6bff0c3 | 105 | |
b475f5d6 | 106 | If this is disabled, you get the buffer playback only once and then it is |
79821695 MS |
107 | deleted. If this is enabled, the buffer is not deleted. This may be useful |
108 | if you regularly use more than one client to connect to ZNC. | |
b475f5d6 | 109 | |
9aa1df15 | 110 | ## Using ZNC |
7a157b26 | 111 | |
79821695 MS |
112 | Once you have started ZNC you can connect with your favorite IRC-client to |
113 | ZNC. You should use `username:password` as the server password (e.g. | |
114 | `/pass user:pass`). | |
7a157b26 | 115 | |
e6bff0c3 | 116 | Once you are connected you can do `/msg *status help` for some commands. |
79821695 MS |
117 | Every module you have loaded (`/msg *status listmods`) should additionally |
118 | provide `/msg *modulename help` | |
7a157b26 | 119 | |
9aa1df15 | 120 | ## File Locations |
7a157b26 | 121 | |
e6bff0c3 | 122 | In its data dir (`~/.znc` is default) ZNC saves most of its data. The only |
79821695 MS |
123 | exception are modules and module data, which are saved in |
124 | `<prefix>/lib/znc` and `<prefix>/share/znc`, and the znc binary itself. | |
7cb4c3fc | 125 | More modules (e.g. if you install some later) can be saved in |
e6bff0c3 | 126 | `<data dir>/modules` (-> `~/.znc/modules`). |
7a157b26 | 127 | |
79821695 | 128 | In the datadir is only one file: |
e6bff0c3 | 129 | |
79821695 MS |
130 | - `znc.pem` - This is the server certificate ZNC uses for listening and is |
131 | created with `znc --makepem`. | |
7a157b26 | 132 | |
133 | These directories are also in there: | |
e6bff0c3 | 134 | |
79821695 MS |
135 | - configs - Contains `znc.conf` (ZNC's config file) and backups of older |
136 | configs. | |
e6bff0c3 KF |
137 | - modules - ZNC also looks in here for a module. |
138 | - moddata - Global modules save their settings here. | |
139 | (e.g. webadmin saves the current skin name in here) | |
79821695 | 140 | - users - This is per-user data and mainly contains just a moddata |
3c62741b | 141 | directory and a directory for each network configured. |
7a157b26 | 142 | |
9aa1df15 | 143 | ## ZNC's config file |
7a157b26 | 144 | |
145 | This file shouldn't be too hard too understand. An explanation of all the | |
79821695 | 146 | items can be found on the |
a75ad25a JA |
147 | [Configuration](https://wiki.znc.in/Configuration) page. |
148 | **Warning: it is better not to edit config while ZNC is running.** Use the | |
79821695 | 149 | [webadmin] and [controlpanel] modules instead. |
7a157b26 | 150 | |
10bfece3 AS |
151 | [webadmin]:https://wiki.znc.in/Webadmin |
152 | [controlpanel]:https://wiki.znc.in/Controlpanel | |
7a157b26 | 153 | |
d252a2b4 | 154 | If you changed some settings while ZNC is running, a simple |
79821695 MS |
155 | `pkill -SIGUSR1 znc` will make ZNC rewrite its config file. Alternatively |
156 | you can use `/msg *status saveconfig` | |
c2e87beb | 157 | |
9aa1df15 | 158 | ## Writing own modules |
7a157b26 | 159 | |
8ca1859a | 160 | You can write your own modules in either C++, python or perl. |
7a157b26 | 161 | |
79821695 MS |
162 | C++ modules are compiled by either saving them in the modules source dir |
163 | and running make or with the `znc-buildmod` shell script. | |
7a157b26 | 164 | |
4abf3fea | 165 | For additional info look in the wiki: |
9aa1df15 | 166 | |
10bfece3 | 167 | - [Writing modules](https://wiki.znc.in/Writing_modules) |
7a157b26 | 168 | |
79821695 | 169 | Perl modules are loaded through the global module |
10bfece3 | 170 | [ModPerl](https://wiki.znc.in/Modperl). |
6a2b5a23 | 171 | |
79821695 | 172 | Python modules are loaded through the global module |
10bfece3 | 173 | [ModPython](https://wiki.znc.in/Modpython). |
7a157b26 | 174 | |
a75ad25a | 175 | ## Further information |
7a157b26 | 176 | |
3c3a445a P |
177 | Please visit https://znc.in/ or #znc on Libera.Chat if you still have questions: |
178 | - [ircs://irc.libera.chat:6697/#znc](ircs://irc.libera.chat:6697/#znc) | |
7a157b26 | 179 | |
ed178040 | 180 | You can get the latest development version with git: |
79821695 | 181 | `git clone https://github.com/znc/znc.git --recursive` |