annotate man/irccd.conf.5 @ 996:2a6d753f79f6

man: add back
author David Demelier <markand@malikania.fr>
date Thu, 11 Feb 2021 22:13:01 +0100
parents d585adeee610
children c50f954d8c67
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 .\"
913
5e25439fe98d misc: update years
David Demelier <markand@malikania.fr>
parents: 911
diff changeset
2 .\" Copyright (c) 2013-2020 David Demelier <markand@malikania.fr>
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 .\"
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 .\" Permission to use, copy, modify, and/or distribute this software for any
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 .\" purpose with or without fee is hereby granted, provided that the above
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 .\" copyright notice and this permission notice appear in all copies.
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 .\"
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 .\"
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 .Dd @IRCCD_MAN_DATE@
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 .Dt IRCCD.CONF 5
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 .Os
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 .\" NAME
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 .Sh NAME
906
b831d9f48b0e doc: fix various errors
David Demelier <markand@malikania.fr>
parents: 884
diff changeset
21 .Nm irccd.conf
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 .Nd irccd configuration file
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 .\" DESCRIPTION
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 .Sh DESCRIPTION
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
25 The
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
26 .Nm
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
27 uses a custom configuration file to setup the IRC daemon.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
28 .\" SYNTAX
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
29 .Sh SYNTAX
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
30 The file consists of several directives that are evaluated in order of
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
31 appearance. It is advised to follow the same directive order as described in
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
32 this document.
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 .Pp
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
34 The below sections describe the supported syntax.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
35 .\" Comments
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
36 .Ss Comments
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
37 Comments start when a # is found and continue until the next line.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
38 .\" Strings
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
39 .Ss Strings
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
40 String are either written in pure ASCII strings or enclosed between double
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
41 quotes. Because some reserved tokens may collide with your values, it is
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
42 recommended to use double quoted strings in user values (such as identifiers,
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
43 channels names and such). Also, double quotes are required when string contain
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
44 spaces.
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 .Pp
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
46 Example:
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
47 .Bd -literal -offset indent
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
48 String
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
49 "This is a double quoted string"
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 .Ed
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
51 .\" Identifiers
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 .Ss Identifiers
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 Some sections require an identifier (specified as id) as parameter. They must be
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
54 unique, not empty and can only contain characters, numbers,
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
55 .Dq -
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
56 and
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
57 .Dq _ .
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 .Pp
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 Example: both
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 .Ar abc
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 and
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 .Ar server-tz2
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 are valid.
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
64 .\" Blocks
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
65 .Ss Blocks
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
66 For configuration sections that are more complex, block using braces are
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
67 required and each directive between the enclosing block require a trailing
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
68 semicolon.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
69 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
70 Example:
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
71 .Bd -literal -offset indent
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
72 block {
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
73 option;
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
74 key and value;
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
75 }
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
76 .Ed
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
77 .\" Lists
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
78 .Ss Lists
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
79 Lists are separated by a comma.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
80 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
81 Example:
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
82 .Bd -literal -offset indent
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
83 one, two, three
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
84 .Ed
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 .\" CONFIGURATION SECTIONS
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 .Sh CONFIGURATION SECTIONS
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
87 The following sections describe what is allowed in the configuration file.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
88 .\" logs
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 .Ss logs
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 This section can let you configure how irccd should log the messages.
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
91 .Bl -tag
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
92 .It Ar logs [verbose|quiet] to console
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
93 Use the standard output and error to log content. This the default.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
94 .It Ar logs [verbose|quiet] to syslog
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
95 Use the
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
96 .Xr syslog 3
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
97 daemon to log information.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
98 .It Ar logs [verbose|quiet] to file path
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
99 Use
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
100 .Pa path
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
101 to logs every entries.
856
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
102 .El
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
103 .Pp
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
104 The optional self explained
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
105 .Op verbose|quiet
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
106 argument controls either if verbose logging should be enabled or not. Only
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
107 informative messages are affected by this setting. Warnings and debugging
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
108 messages are stored independently from this setting.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
109 .\" transport
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
110 .Ss transport
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
111 Enable transport to interract with the
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
112 .Nm irccdctl
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
113 utility or any networking program that can communicate through a UNIX domain
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
114 socket.
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
115 .Pp
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
116 .Ar transport to path
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 .Pp
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
118 Enable transport on
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
119 .Pa path .
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
120 .\" server
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
121 .Ss server
856
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
122 This section is used to connect to one or more server. Create a new server
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
123 section block for each IRC server you want to connect to.
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
124 .Pp
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
125 .Ar server id { options }
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
126 .Pp
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
127 The following directives are allowed in the
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
128 .Em options
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
129 block:
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
130 .Bl -tag -width "hostname value"
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
131 .It Ar hostname value
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
132 Connect to the
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
133 .Ar value
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
134 hostname. This can be either a DNS name or a IP address.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
135 .It Ar port value
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
136 Use
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
137 .Ar value
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
138 number as IP port to connect to.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
139 .It Ar ident nick user realname
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
140 Specify the IRC identity to use by using the three arguments
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
141 .Ar nick , user
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
142 and
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
143 .Ar realname
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
144 as nickname, user name and your real name respectively.
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
145 .Pp
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
146 Note: this is not a list of strings but three arguments separated by a space. If
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
147 you want to use a real name with spaces, don't forget the double quotes.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
148 .It Ar ssl
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
149 Enable SSL. Only available if built with OpenSSL support.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
150 .It Ar channels list
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
151 List of channels to join automatically when the server is connected
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
152 successfully. This is a list of strings where each element is the channel name
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
153 to join prepended by a optional
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
154 .Ar password@
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
155 if required. You must use double quotes if the channel starts with a hash (#)
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
156 otherwise it would be detected as a comment.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
157 .It Ar options list
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
158 Use specific server features. This is a list of string which can be one of
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
159 following:
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
160 .Bl -tag -width "AUTO-RECONNECT"
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
161 .It Ar AUTO-RECONNECT
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
162 Reconnect automatically to a server upon disconnection.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
163 .It Ar AUTO-REJOIN
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
164 Automatically rejoin a channel if the bot was kicked from.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
165 .It Ar JOIN-INVITE
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
166 Automatically join a channel upon invitation.
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
167 .El
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
168 .It Ar prefix value
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
169 Use
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
170 .Ar value
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
171 as command prefix for plugins (Optional, default:
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
172 .Dq \&! ) .
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
173 .El
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
174 .\" rule
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
175 .Ss rule
856
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
176 The rule section is one of the most powerful within irccd configuration. It lets
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
177 you enable or disable plugins and IRC events for specific criteria. For
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
178 instance, you may want to disable a plugin only for a specific channel on a
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
179 specific server. And because rules are evaluated in the order they are defined,
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
180 you can override rules.
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
181 .Pp
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
182 When you don't specify any value into the corresponding criteria the rule is
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
183 considered as matched.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
184 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
185 .Ar rule accept|drop { criteria }
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
186 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
187 Create a rule that either
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
188 .Ar accept
856
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
189 or
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
190 .Ar drop
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
191 the current event.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
192 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
193 The following directives are allowed in the
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
194 .Em options
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
195 block:
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
196 .Bl -tag -width "channels list"
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
197 .It Ar servers list
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
198 List of servers to match by their ids.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
199 .It Ar channels list
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
200 List of channel to match. This can be used to match user nicknames as well.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
201 .It Ar origins list
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
202 List of originators to match.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
203 .It Ar events list
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
204 List of events to match (in the form onCommand, onMessage, etc). See the
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
205 .Xr irccd 1
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
206 manual page for the allowed names here.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
207 .It Ar plugins list
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
208 List of plugins to match by their ids.
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
209 .El
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
210 .Pp
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
211 Warning: don't make sensitive rules on origins option, irccd does not have any
856
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
212 kind of nickname authentication. Thus, it may be very easy for someone
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
213 to use a temporary nickname.
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
214 .\" hooks
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
215 .Ss hooks
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
216 This section loads hooks. The configuration does not test if the file is
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
217 actually executable nor present on the filesystem and will be tried as long as
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
218 the daemon is running.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
219 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
220 .Ar hook id to path
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
221 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
222 Load the hook with name
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
223 .Ar id
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
224 from the given
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
225 .Pa path .
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
226 .\" plugins
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
227 .Ss plugins
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
228 This section is used to load plugins.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
229 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
230 To load plugin with default values, you can just use the declaration without
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
231 block of options. Otherwise, use a block to add additional options,
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
232 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
233 .Ar plugin id { options }
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
234 .Pp
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
235 The following directives are allowed in the
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
236 .Em options
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
237 block:
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
238 .Bl -tag -width "hostname value"
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
239 .It Ar location path
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
240 Specify an absolute
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
241 .Pa path
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
242 to the plugin.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
243 .It Ar config { key value }
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
244 Specify a list of options to the plugin as key-value pair. Each entry consist of
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
245 two arguments, the option name and its value both as strings. See
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
246 .Xr EXAMPLES
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
247 for usage.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
248 .It Ar template { key value }
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
249 Same as
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
250 .Ar config
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
251 but for templates. See
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
252 .Xr irccd-templates 7
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
253 for more details about this section.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
254 .It Ar paths { key value }
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
255 Same as
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
256 .Ar config
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
257 but for additional paths. Individual plugins may accept special paths but the
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
258 following are reserved by irccd and always set when loading the plugin unless
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
259 explicitly overriden in this section:
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
260 .Bl -tag
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
261 .It Ar cache
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
262 Directory for temporary files.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
263 .It Ar data
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
264 Directory for additional data.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
265 .It Ar config
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
266 Directory to additional configuration files.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
267 .El
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
268 .El
856
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
269 .\" EXAMPLES
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
270 .Sh EXAMPLES
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
271 Full example of configuration file
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
272 .Bd -literal
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
273 # Logs to syslog instead of console (which is the default).
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
274 logs verbose to syslog
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
275
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
276 #
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
277 # Create a server "example" that connect to example.org using "fr" as nickname,
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
278 # "francis" as username and "Francis Meyer" as realname.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
279 #
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
280 # This channel will automatically join "#test" on connection and the password
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
281 # protected "#nightclub" channel with password "secret"
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
282 #
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
283 server example {
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
284 hostname example.org;
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
285 port 6667;
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
286 ident fr francis "Francis Meyer";
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
287 channels "#test", "secret@#nightclub";
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
288 }
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
289
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
290 # Load several plugins with their default values and locations.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
291 plugin ask
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
292 plugin plugin
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
293
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
294 # Configure the plugin hangman to change templates and the path to the words.
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
295 plugin hangman {
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
296 templates {
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
297 win "Success, the word was #{word}!";
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
298 }
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
299 config {
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
300 file "/var/irccd/hard-words.txt";
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
301 }
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
302 }
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
303
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
304 # This first rule disable the plugin reboot on all servers and channels.
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
305 rule drop {
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
306 plugins "reboot";
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
307 }
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
308
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
309 # This rule enable the reboot plugin again on the server localhost,
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
310 # channel #staff.
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
311 rule accept {
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
312 servers "localhost";
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
313 channels "#staff";
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
314 plugins "reboot";
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
315 }
895
f0d6bc79aa32 irccd: implement hooks, closes #2342 @2h
David Demelier <markand@malikania.fr>
parents: 884
diff changeset
316
f0d6bc79aa32 irccd: implement hooks, closes #2342 @2h
David Demelier <markand@malikania.fr>
parents: 884
diff changeset
317 # This create an hook named "mail" with the given path.
996
2a6d753f79f6 man: add back
David Demelier <markand@malikania.fr>
parents: 925
diff changeset
318 hook mail to "/path/to/mail.py"
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
319 .Ed
856
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
320 .\" SEE ALSO
845
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
321 .Sh SEE ALSO
00a4720c4874 doc: rewrite documentation in manual pages, closes #1674
David Demelier <markand@malikania.fr>
parents:
diff changeset
322 .Xr irccd 1
856
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
323 .\" AUTHORS
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
324 .Sh AUTHORS
906
b831d9f48b0e doc: fix various errors
David Demelier <markand@malikania.fr>
parents: 884
diff changeset
325 .Nm irccd
856
6c4fb8f42aca doc: improve wording and style
David Demelier <markand@malikania.fr>
parents: 847
diff changeset
326 was written by David Demelier <markand@malikania.fr>