Introduction
This guide will help you installing irccd on your system and running it.
Installing irccd
Irccd is provided as prebuilt binaries for Windows, the installer is quite easy to use. If you have and old computer, you should take the 32bits version, otherwise, choose 64bit version.
Grab the irccd package that fits your system at http://projects.malikania.fr/irccd/download.php
Building from sources
On Unix systems, there is probably prebuilt binaries provided by your distribution. If not you will need to build from sources, don’t worry it’s not very hard.
Requirements
To build from sources, you need the following installed on your system:
-
cmake, http://www.cmake.org.
-
libxdg-basedir, https://github.com/devnev/libxdg-basedir. On Unix only (optional).
-
Lua 5.2, http://lua.org (optional).
-
LuaJIT, http://luajit.org (optional).
-
C++11 support.
Running the build
When you’re ready, extract the irccd-x.y-sources.tar.xz where x.y is replaced with the current version. Go to that directory, then type the following commands:
markand@localhost [irccd-1.1] $ mkdir _build_ markand@localhost [irccd-1.1] $ cd _build_ markand@localhost [irccd-1.1/_build_] $ cmake .. markand@localhost [irccd-1.1/_build_] $ make markand@localhost [irccd-1.1/_build_] $ sudo make install
This is the quick way of compiling and installing. It’s also possible to set some options to customize the build.
You can use LuaJIT instead of vanilla Lua 5.2
markand@localhost [irccd-1.1/_build_] $ cmake .. -DWITH_LUA52=Off -DWITH_LUAJIT=On
You can disable Lua support.
markand@localhost [irccd-1.1/_build_] $ cmake .. -DWITH_LUA52=Off -DWITH_LUAJIT=Off
When disabling Lua, the IRC bot can still be used as a message relayer, so you can still use irccdctl to manage irccd.
![]() |
If Lua is not found on your system, Lua support is automatically disabled, if you plan to use Lua, do the above command and switch Off to On. |
If you don’t want to install Lua API documentation, use the following command.
markand@localhost [irccd-1.1/_build_] $ cmake .. -DWITH_LDOC=Off
You can disable installation of user guides.
markand@localhost [irccd-1.1/_build_] $ cmake .. -DWITH_DOC=Off
On Windows, man pages are not really useful, you can also disable them
markand@localhost [irccd-1.1/_build_] $ cmake .. -DWITH_MAN=Off
Sometimes, you may need to install irccd over other place, for that, you can specify the prefix where to install files. On unix systems, it’s usually /usr/local/ and C:/Program Files/ on Windows.
To change this, use the following:
markand@localhost [irccd-1.1/_build_] $ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/some/directory
By default, irccd use ${PREFIX}/share/man for manual pages. Some systems use different one.
For example, on FreeBSD the typical use would be:
markand@localhost [irccd-1.1/_build_] $ cmake .. -DMANDIR=/usr/local/man
Configuring irccd
Now that you’ve successfully installed irccd, let’s add a configuration file so we can run it.
Paths
The irccd configuration file is usually named irccd.conf and it’s location may vary on operating systems. On every operating systems, irccd will try to open user defined config file at first, then if not found, it fallbacks to the default configurations paths.
On Unix, the files are loaded in the following order:
-
${XDG_CONFIG_HOME}/irccd/irccd.conf
-
/usr/local/etc/irccd.conf.
On Windows, the files are loaded in the following order:
-
C:\Users\YourUser\irccd\irccd.conf
-
Path\To\Irccd\Directory\etc\irccd.conf
![]() |
Specify at the command line On every operating systems, it’s possible to pass a specific configuration file
at the command line, this will only try to open that file and exit if irccd
failed to open it. Example: irccd -c myconfig.conf. |
![]() |
Changing prefix The default config paths are using the default prefixes, check the
Building from sources section. |
Syntax
The irccd.conf follow a very basic .ini syntax. Every options are stored in sections and some of these sections may be redefined one or more times.
Each option takes one line, it’s not possible to write more than one option on the same line.
The comment character is # and can live at the beginning or the end of a line.
# This is a comment [general] verbose = false [server] host = "localhost" # this is a comment too
verbose = true # no section! [server] host = "localhost" port = "8520" # not allowed!
The section general
This section contains global options that are used in the whole irccd application.
The options available:
-
foreground: (bool) Keep irccd to foreground, default: false.
-
plugins: (DEPRECATED) (string list) A list of plugins to load, default: empty.
-
plugin-path: (string) A path to local plugins, default: empty.
-
syslog: (bool) If enabled, use syslog instead of standard output, default: false.
-
verbose: (bool) Enable verbose message, default: false.
![]() |
The options foreground and syslog are only available on Unix systems. |
[general] verbose = true
The section plugins
This section is used to load plugins. Just add any key you like to load a plugin. If the value is not specified, the plugin is searched through the standard directories, otherwise, provide the full path (including the .lua extension).
[plugins] history = myplugin = /tmp/myplugin.lua
The section identity
This section is completely optional, if you don’t provide one, irccd will use a default identity with irccd as nickname and username.
This section is redefinable, you can create one or more.
The options available:
-
name: (string) Required. the identity unique id.
-
nickname: (string) The nickname, default: irccd.
-
realname: (string) The realname, default: IRC Client daemon.
-
username: (string) The username name, default: irccd.
-
ctcp-version: (string) What version to respond to CTCP VERSION, default: IRC Client Daemon.
-
ctcp-autoreply: (bool) Enable auto CTCP VERSION reply, default: true.
[identity] name = "default" nickname = "jean" [identity] name = "development" nickname = "unstable" username = "un"
The section server
The section server is used to connect to one or more server. Thus, this section is also redefinable.
You need at least one server in your configuration file.
The options available:
-
name: (string) Required. A unique id.
-
host: (string) Required. The server address.
-
port: (int) Required, The server port.
-
identity: (string) An identity to use.
-
password: (string) An optional password.
-
join-invite: (bool) Join channels upon invitation, default: false.
-
channels: (string list) List of channel to auto join, default: empty.
-
command-char: (string) The prefix for invoking special commands, default: !.
-
ssl: (bool) Enable or disable SSL, default: false.
-
ssl-verify: (bool) Verify the SSL certificates, default: true.
-
reconnect: (bool) Enable reconnection after failure, default: true.
-
reconnect-tries: (int) Number of tries before giving up. A value of 0 means indefinitely, default: 0.
-
reconnect-timeout: (int) Number of seconds to wait before retrying, default: 30.
[server] name = "local" host = "localhost" port = 6667
The section listener
This section defines listeners, you may use sockets to do a basic IPC system in irccd. This let you controlling irccd with sockets.
For instance, with listeners, you may ask irccd to send a message, a notice or even kicking someone from a channel. This is done with the irccdctl utility.
There are two type of listeners availables:
-
Internet sockets, IPv4 and IPv6
-
Unix sockets, based on files (not available on Windows)
The following options are available for both types.
-
type: (string) Required. type of listener "internet" or "unix"
-
protocol: (string) Protocol to use, "tcp" or "udp", default: "tcp".
Using internet sockets
The options available:
-
address: (string) Address to bind or "*" for any, default: *.
-
family: (string list) Internet family: ipv6, ipv4. Both are accepted, default: ipv4
-
port: (int) Required: port number.
[listener] type = "internet" address = "*" family = "ipv4 ipv6" port = 9999
This will let you controlling irccd on port 9999 with both IPv4 and IPv6 families.
Using unix sockets
The options available:
-
path: (string) Required. The file path to the socket.
[listener] type = "unix" path = "/tmp/irccd.sock"
This will let you controlling irccd on path /tmp/irccd.sock, the file is automatically deleted when irccd starts, but not when it stops.
![]() |
Consider using internet sockets with care, especially if you are running your bot on a server with multiple users. If your bot has operator rights and you bind on any address, almost every users can do a kick or a ban. If this is a concern switch to a Unix socket if possible. |
Full example
There is an example of file that can be used, be sure to define real servers as the one defined here does not exist for real.
# This line is ignored [general] verbose = true # Add a listener that bind only to IPv6 [listener] address = "*" family = "ipv6" port = "12000" # A listener that bind to both IPv4 and IPv6 [listener] address = "*" family = "ipv4 ipv6" port = "15000" # Identity reused by many servers [identity] name = "myIdentity" nickname = "superbot" realname = "SuperBot v1.0" username = "sp" # A server [server] host = "irc.foo.org" port = "6667" identity = "myIdentity" # An other server [server] host = "chat.wanadoo.fr" port = "6667" identity = "myIdentity" # Load some plugins [plugins] ask = # This search for plugin ask myplugin = /path/to/myplugin.lua # This use absolute path
Running irccd
Now that you have a configured file, you can start irccd by typing its name.
markand@localhost [~] $ irccd
The following options are available:
-
-f, do not run as a daemon, keep irccd to the foreground
-
-c config.conf, load a specific config file, exit if not found
-
-p pluginpath, add a directory to find plugins
-
-P plugin, load a plugin, can be specified more than one time
-
-v, be verbose
Using plugins
Lua plugins can be used to manage IRC events, to let you overriding distributed plugins, irccd will try to open plugin in your home directory before.
On Unix, the paths are searched in the following order:
-
Specified by -p on command line
-
${XDG_CONFIG_HOME}/irccd/plugins
-
${HOME}/.config/irccd/plugins
-
/usr/local/share/irccd/plugins
On Windows, the paths are searched in the following order:
-
Specified by -p on command line
-
C:\Users\YourUser\irccd\plugins
-
Path\To\Irccd\Directory\share\plugins
Note about plugins
All plugins have a home directory. This allow configuring or caching some data needed for them. The home directory cannot be changed and is relative to the irccd config path plus the plugin name. For example, the plugin ask.lua will have the following home:
On Unix: ~/.config/irccd/ask/
On Windows: C:/Users/YourUser/irccd/ask/
And the respective installation config path or Windows executable location :
On Unix: /usr/local/etc/irccd/ask
On Windows: Path\To\Irccd\Directory\etc\irccd\ask
The order is :
-
User config directory
-
System directory
Common patterns in plugins
Some plugins can be configured, and some of them can use patterns to substitute variables.
For instance, using the logger plugin, it’s possible to customize the pattern to use when someone joins a channel like that:
#U joined #c
The keywords #U will be substituted to the nickname and #c to the channel name.
Note, some keywords are obviously not available for all contexts. When plugins supports these patterns, they are marked as Keywords supported: #c, #m.
If supported, you can use environment variables like ${HOME}. Please not that braces are mandatory.
When you can use patterns, the date and time may be used just like strftime(3) so for the hours and minutes, you can use %H:%M.
To match your user directory, you can use the famous ~.
Here’s the list of keywords that a lot of plugins uses:
-
#c, the channel name
-
#m, a message (depending on context)
-
#s, the current server name
-
#t, the topic
-
#T, a target, i.e a person who gets kicked
-
#u, the full user, i.e markand!~mkd@localhost
-
#U, the nickname
Using the plugin logger, you can use a configuration like this:
[general] directory = "~/logs/#s/%y/%m/#c-%d.log" [formats] message = "%H:%M #u: #m"
With this example, ~ will be substituted to the user home directory. With a server named local, a channel #staff everything would be stored like this:
/home/markand/local/13/07/#staff-08.log
Also the message would be stored like this:
20:50 markand: I'm watching TV.
The irccdctl utility
The irccdctl utility let you controlling a running irccd instance. It uses sockets to perform any operation.
First, you need to define at least one listener before using irccdctl.
Second, you need to write a configuration file named irccdctl.conf. It takes places at exactly the same irccd paths.
The section general
This section defines the global irccdctl parameters.
The options available:
-
verbose: (bool) enable verbose message, default: false.
[general] verbose = true
The section socket
The section socket permit irccdctl to connect to a specific irccd listener, only one may be defined.
Just like listeners you can connect to Unix or internet sockets.
The following options are available for both types.
-
type: (string) Required. type of listener "internet" or "unix"
-
protocol: (string) Required. Protocol to use, "tcp" or "udp".
Using internet sockets
The options available:
-
host: (string) Required. Host to connect.
-
family: (string) Required. Internet family: ipv6 or ipv4.
-
port: (int) Required: port number.
[socket] type = "internet" host = "localhost" port = "9999" family = "ipv6"
Using unix sockets
The options available:
-
path: (string) Required. The file path to the socket.
[socket] type = "unix" path = "/tmp/irccd.sock"
Available options
The following options are available:
-
-c, a path to a config file.
-
-i identity, use a specific identity, only used by connect command.
-
-k key, use a password, only used by connect command.
-
-s, use SSL, only used by connect command.
-
-t domain, the domain to use, specify internet or unix.
-
-T type, the type to use, tcp or udp.
-
-v, be more verbose.
The following options are available for -t internet :
-
-4, use IPv4.
-
-6, use IPv4.
-
-h, the hostname to connect.
-
-p, the port to use.
The following options are available for -t unix :
-
-P path, the path to the unix socket.
Available commands
Almost of all these commands takes a server as parameter. It is one defined in the server section with the parameter name.
Only load, reload and unload do not need it.
The following commands are available for irccdctl:
![]() |
Shell parsing warning
Some shells may discard arguments if they begins with a hash. For instance, bash will not understand the following command: $ irccdctl join localhost #staff Instead, enclose the arguments with quotes $ irccdctl join localhost "#staff" |
Channel notice
Send a notice to a public channel. This is a notice that everyone will be notified by.
$ irccdctl cnotice server channel message
$ irccdctl cnotice freenode #staff "Don't flood"
Connect
Connect to a new IRC server.
$ irccdctl [-s] [-i identity] [-k password] connect name host port
$ irccdctl connect wanadoo chat.wanadoo.fr 6667 $ irccdctl connect -s wanadoo chat.wanadoo.fr 6697 $ irccdctl connect -k "secret" wanadoo chat.wanadoo.fr 6667
Disconnect
Disconnect from a connected server.
$ irccdctl disconnect name
$ irccdctl disconnect wanadoo
Invite
Invite someone to a channel, needed for channel with mode +i
$ irccdctl invite server nickname channel
$ irccdctl invite freenode xorg62 #staff
Join
Join a channel on a specific server registered in irccd. The server is referenced by the parameter server. Parameter channel is the channel to join. An optional password may be set as password parameter.
$ irccdctl join server channel [password]
$ irccdctl join freenode #staff
Kick
Kick someone from a channel. The parameter reason is optional and may be ommited but when specified it must be unclosed between quotes.
$ irccdctl kick server nick channel [reason]
$ irccdctl kick freenode jean #staff "Stop flooding"
Load
Load a plugin into the irccd instance.
$ irccdctl load plugin
$ irccdctl load ask
Me
Send a CTCP ACTION message. It is exactly the same syntax as message.
$ irccdctl me server target message
$ irccdctl me freenode #staff "going back soon"
Message
Send a message to someone or a channel. The target may be a channel or a real person If the message contains more than one word it must be enclosed between quotes.
$ irccdctl message server target message
$ irccdctl message freenode #staff "Hello from irccd"
Channel mode
Change the mode of the specified channel. The mode contains full parameters like "+b" or "+k secret".
$ irccdctl mode server channel mode
$ irccdctl mode freenode #staff +t
Private notice
Send a private notice to a target user.
$ irccdctl notice server target message
$ irccdctl notice freenode jean "Private notice"
Change nickname
Change your nickname. The parameter nickname is the new nickname
$ irccdctl nick server nickname
$ irccdctl nick freenode david
Part from a channel
Leave a channel. Parameter server is one registered in irccd config. Parameter channel is the channel to leave.
$ irccdctl part server channel
$ irccdctl part freenode #staff
![]() |
Currently, there is no option to provide a part message. |
Reload a plugin
Reload a plugin, parameter name is the plugin to reload. The plugin needs to be loaded.
$ irccdctl reload name
$ irccdctl reload logger
Restart a server
Sometimes it is needed to force a reload by hand. This even more true when a server died, irccd has no way to detect that. This command force a reconnection even if it is not enabled in the config.
![]() |
If the parameter name is not given, all servers are restarted. |
$ irccdctl restart [name]
$ irccdctl restart
Change topic
Set the new topic of a channel. Topic must be enclosed between quotes.
$ irccdctl topic server channel topic
$ irccdctl topic freenode #wmfs "This is the best channel"
Change your user mode
Change your own user mode.
$ irccdctl umode server mode
$ irccdctl umode +i
Unload a plugin
Unload a loaded plugin from the irccd instance.
$ irccdctl unload name
$ irccdctl unload logger