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:

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.

Switching to LuaJIT

You can use LuaJIT instead of vanilla Lua 5.2

markand@localhost [irccd-1.1/_build_] $ cmake .. -DWITH_LUA52=Off -DWITH_LUAJIT=On
Disabling Lua

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.

Note 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.
Disable Lua documentation

If you don’t want to install Lua API documentation, use the following command.

markand@localhost [irccd-1.1/_build_] $ cmake .. -DWITH_LDOC=Off
Disable user guides

You can disable installation of user guides.

markand@localhost [irccd-1.1/_build_] $ cmake .. -DWITH_DOC=Off
Disable manual pages

On Windows, man pages are not really useful, you can also disable them

markand@localhost [irccd-1.1/_build_] $ cmake .. -DWITH_MAN=Off
Changing the default installation path

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
Changing the man paths

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:

  1. ${XDG_CONFIG_HOME}/irccd/irccd.conf

  2. /usr/local/etc/irccd.conf.

On Windows, the files are loaded in the following order:

  1. C:\Users\YourUser\irccd\irccd.conf

  2. Path\To\Irccd\Directory\etc\irccd.conf

Note
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.
Caution
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.

Correct config
# This is a comment
[general]
verbose = false

[server]
host = "localhost"              # this is a comment too
Bad config
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.

Note The options foreground and syslog are only available on Unix systems.
Example
[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).

Example
[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.

Example
[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.

Example
[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.

Example
[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.

Example
[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.

Warning 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.

Example of irccd.conf file
# 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:

  1. Specified by -p on command line

  2. ${XDG_CONFIG_HOME}/irccd/plugins

  3. ${HOME}/.config/irccd/plugins

  4. /usr/local/share/irccd/plugins

On Windows, the paths are searched in the following order:

  1. Specified by -p on command line

  2. C:\Users\YourUser\irccd\plugins

  3. 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 :

  1. User config directory

  2. 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.

Environment variables

If supported, you can use environment variables like ${HOME}. Please not that braces are mandatory.

Time

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.

Home

To match your user directory, you can use the famous ~.

List of keywords supported

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

Example with logger

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.

Example
[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.

Example
[socket]
type = "internet"
host = "localhost"
port = "9999"
family = "ipv6"

Using unix sockets

The options available:

  • path: (string) Required. The file path to the socket.

Example
[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:

Important
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.

Usage
$ irccdctl cnotice server channel message
Example
$ irccdctl cnotice freenode #staff "Don't flood"

Connect

Connect to a new IRC server.

Usage
$ irccdctl [-s] [-i identity] [-k password] connect name host port
Example
$ 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.

Usage
$ irccdctl disconnect name
Example
$ irccdctl disconnect wanadoo

Help

Get the help.

Usage
$ irccdctl help subject
Example
$ irccdctl help message

Invite

Invite someone to a channel, needed for channel with mode +i

Usage
$ irccdctl invite server nickname channel
Example
$ 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.

Usage
$ irccdctl join server channel [password]
Example
$ 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.

Usage
$ irccdctl kick server nick channel [reason]
Example
$ irccdctl kick freenode jean #staff "Stop flooding"

Load

Load a plugin into the irccd instance.

Usage
$ irccdctl load plugin
Example
$ irccdctl load ask

Me

Send a CTCP ACTION message. It is exactly the same syntax as message.

Usage
$ irccdctl me server target message
Example
$ 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.

Usage
$ irccdctl message server target message
Example
$ 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".

Usage
$ irccdctl mode server channel mode
Example
$ irccdctl mode freenode #staff +t

Private notice

Send a private notice to a target user.

Usage
$ irccdctl notice server target message
Example
$ irccdctl notice freenode jean "Private notice"

Change nickname

Change your nickname. The parameter nickname is the new nickname

Usage
$ irccdctl nick server nickname
Example
$ 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.

Usage
$ irccdctl part server channel
Example
$ irccdctl part freenode #staff
Note 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.

Usage
$ irccdctl reload name
Example
$ 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.

Note If the parameter name is not given, all servers are restarted.
Usage
$ irccdctl restart [name]
Example
$ irccdctl restart

Change topic

Set the new topic of a channel. Topic must be enclosed between quotes.

Usage
$ irccdctl topic server channel topic
Example
$ irccdctl topic freenode #wmfs "This is the best channel"

Change your user mode

Change your own user mode.

Usage
$ irccdctl umode server mode
Example
$ irccdctl umode +i

Unload a plugin

Unload a loaded plugin from the irccd instance.

Usage
$ irccdctl unload name
Example
$ irccdctl unload logger