1BIBOUMI(1) biboumi BIBOUMI(1)
2
6 biboumi - biboumi Documentation
7
9 biboumi [config_filename]
10
12 Usage
13 Biboumi acts as a server, it should be run as a daemon that lives in
14 the background for as long as it is needed. Note that biboumi does not
15 daemonize itself, this task should be done by your init system
16 (SysVinit, systemd, upstart).
17 When started, biboumi connects, without encryption (see Security), to
19 the local XMPP server on the port 5347 and authenticates with the pro‐
20 vided password. Biboumi then serves the configured hostname: this
21 means that all XMPP stanza with a to JID on that domain will be for‐
22 warded to biboumi by the XMPP server, and biboumi will only send mes‐
23 sages coming from that hostname.
24 To cleanly shutdown the component, send a SIGINT or SIGTERM signal to
26 it. It will send messages to all connected IRC and XMPP servers to in‐
27 dicate a reason why the users are being disconnected. Biboumi exits
28 when the end of communication is acknowledged by all IRC servers. If
29 one or more IRC servers do not respond, biboumi will only exit if it
30 receives the same signal again or if a 2 seconds delay has passed.
31 Configuration
33 Configuration happens in different places, with different purposes:
34 • The main and global configuration that specifies vital settings for
36 the daemon to run, like the hostname, password etc. This is an ad‐
37 min-only configuration, and this is described in the next section.
38 • A TLS configuration, also admin-only, that can be either global or
40 per-domain. See TLS configuration section.
41 • Using the Ad-hoc commands, each user can configure various settings
43 for themself
44 Daemon configuration
46 The configuration file is read by biboumi as it starts. The path is
47 specified as the only argument to the biboumi binary.
48 The configuration file uses a simple format of the form option=value
50 (note that there are no spaces before or after the equal sign).
51 The values from the configuration file can be overridden by environment
53 variables, with the name all in upper case and prefixed with BIBOUMI_.
54 For example, if the environment contains “BIBOUMI_PASSWORD=blah”, this
55 will override the value of the “password” option in the configuration
56 file.
57 Sending SIGUSR1, SIGUSR2 or SIGHUP (see kill(1)) to the process will
59 force it to re-read the configuration and make it close and re-open the
60 log files. You can use this to change any configuration option at run‐
61 time, or do a log rotation.
62 Options
64 A configuration file can look something like this:
65 hostname=biboumi.example.com
67 password=mypassword
68 xmpp_server_ip=127.0.0.1
69 port=5347
70 admin=myself@example.com
71 db_name=postgresql://biboumi:password@localhost/biboumi
72 realname_customization=true
73 realname_from_jid=false
74 log_file=
75 ca_file=
76 outgoing_bind=192.168.0.12
77 Here is a description of all available options
79 hostname
81 Mandatory. The hostname served by the XMPP gateway. This domain must
82 be configured in the XMPP server as an external component. See the
83 manual for your XMPP server for more information. For prosody, see
84 http://prosody.im/doc/components#adding_an_external_component
85 password
87 Mandatory. The password used to authenticate the XMPP component to your
88 XMPP server. This password must be configured in the XMPP server, as‐
89 sociated with the external component on hostname.
90 xmpp_server_ip
92 The IP address to connect to the XMPP server on. The connection to the
93 XMPP server is unencrypted, so the biboumi instance and the server
94 should normally be on the same host. The default value is 127.0.0.1.
95 port
97 The TCP port to use to connect to the local XMPP component. The default
98 value is 5347.
99 db_name
101 The name of the database to use. This option can only be used if bi‐
102 boumi has been compiled with a database support (Sqlite3 and/or Post‐
103 greSQL). If the value begins with the postgresql scheme, “post‐
104 gresql://” or “postgres://”, then biboumi will try to connect to the
105 PostgreSQL database specified by the URI. See the PostgreSQL doc for
106 all possible values. For example the value could be “post‐
107 gresql://user:secret@localhost”. If the value does not start with the
108 postgresql scheme, then it specifies a filename that will be opened
109 with Sqlite3. For example the value could be “/var/lib/biboumi/bi‐
110 boumi.sqlite”.
111 admin
113 The bare JID of the gateway administrator. This JID will have more
114 privileges than other standard users, for example some administration
115 ad-hoc commands will only be available to that JID.
116 If you need more than one administrator, separate them with a colon
118 (:).
119 fixed_irc_server
121 If this option contains the hostname of an IRC server (for example
122 irc.example.org), then biboumi will enforce the connexion to that IRC
123 server only. This means that a JID like #chan@biboumi.example.com must
124 be used instead of #chan%irc.example.org@biboumi.example.com. The %
125 character loses any meaning in the JIDs. It can appear in the JID but
126 will not be interpreted as a separator (thus the JID #channel%hello@bi‐
127 boumi.example.com points to the channel named #channel%hello on the
128 configured IRC server) This option can for example be used by an admin‐
129 istrator that just wants to let their users join their own IRC server
130 using an XMPP client, while forbidding access to any other IRC server.
131 persistent_by_default
133 If this option is set to true, all rooms will be persistent by default:
134 the value of the “persistent” option in the global configuration of
135 each user will be “true”, but the value of each individual room will
136 still default to false. This means that a user just needs to change the
137 global “persistent” configuration option to false in order to override
138 this.
139 If it is set to false (the default value), all rooms are not persistent
141 by default.
142 Each room can be configured individually by each user, to override this
144 default value. See Ad-hoc commands.
145 realname_customization
147 If this option is set to “false” (default is “true”), the users will
148 not be able to use the ad-hoc commands that lets them configure their
149 realname and username.
150 realname_from_jid
152 If this option is set to “true”, the realname and username of each bi‐
153 boumi user will be extracted from their JID. The realname is their
154 bare JID, and the username is the node-part of their JID. Note that if
155 realname_customization is “true”, each user will still be able to cus‐
156 tomize their realname and username, this option just decides the de‐
157 fault realname and username.
158 If this option is set to “false” (the default value), the realname and
160 username of each user will be set to the nick they used to connect to
161 the IRC server.
162 webirc_password
164 Configure a password to be communicated to the IRC server, as part of
165 the WEBIRC message (see https://kiwiirc.com/docs/webirc). If this op‐
166 tion is set, an additional DNS resolution of the hostname of each XMPP
167 server will be made when connecting to an IRC server.
168 log_file
170 A filename into which logs are written. If none is provided, the logs
171 are written on standard output.
172 log_level
174 Indicate what type of log messages to write in the logs. Value can be
175 from 0 to 3. 0 is debug, 1 is info, 2 is warning, 3 is error. The de‐
176 fault is 0, but a more practical value for production use is 1.
177 ca_file
179 Specifies which file should be used as the list of trusted CA when ne‐
180 gociating a TLS session. By default this value is unset and biboumi
181 tries a list of well-known paths.
182 outgoing_bind
184 An address (IPv4 or IPv6) to bind the outgoing sockets to. If no value
185 is specified, it will use the one assigned by the operating system.
186 You can for example use outgoing_bind=192.168.1.11 to force biboumi to
187 use the interface with this address. Note that this is only used for
188 connections to IRC servers.
189 identd_port
191 The TCP port on which to listen for identd queries. The default is the
192 standard value: 113. To be able to listen on this privileged port, bi‐
193 boumi needs to have certain capabilities: on linux, using systemd, this
194 can be achieved by adding AmbientCapabilities=CAP_NET_BIND_SERVICE to
195 the unit file. On other systems, other solutions exist, like the por‐
196 tacl module on FreeBSD.
197 If biboumi’s identd server is properly started, it will receive queries
199 from the IRC servers asking for the “identity” of each IRC connection
200 made to it. Biboumi will answer with a hash of the JID that made the
201 connection. This is useful for the IRC server to be able to distinguish
202 the different users, and be able to deal with the absuses without hav‐
203 ing to simply ban the IP. Without this identd server, moderation is a
204 lot harder, because all the different users of a single biboumi in‐
205 stance all share the same IP, and they can’t be distinguished by the
206 IRC servers.
207 To disable the built-in identd, you may set identd_port to 0.
209 policy_directory
211 A directory that should contain the policy files, used to customize
212 Botan’s behaviour when negociating the TLS connections with the IRC
213 servers. If not specified, the directory is the one where biboumi’s
214 configuration file is located: for example if biboumi reads its config‐
215 uration from /etc/biboumi/biboumi.cfg, the policy_directory value will
216 be /etc/biboumi.
217 TLS configuration
219 Various settings of the TLS connections can be customized using policy
220 files. The files should be located in the directory specified by the
221 configuration option policy_directory. When attempting to connect to
222 an IRC server using TLS, biboumi will use Botan’s default TLS policy,
223 and then will try to load some policy files to override the values
224 found in these files. For example, if policy_directory is /etc/bi‐
225 boumi, when trying to connect to irc.example.com, biboumi will try to
226 read /etc/biboumi/policy.txt, use the values found to override the de‐
227 fault values, then it will try to read /etc/biboumi/irc.exam‐
228 ple.com.policy.txt and re-override the policy with the values found in
229 this file.
230 The policy.txt file applies to all the connections, and irc.exam‐
232 ple.policy.txt will only apply (in addition to policy.txt) when con‐
233 necting to that specific server.
234 To see the list of possible options to configure, refer to Botan’s TLS
236 documentation. In addition to these Botan options, biboumi implements
237 a few custom options listed hereafter: - verify_certificate: if this
238 value is set to false, biboumi will not check the certificate validity
239 at all. The default value is true.
240 By default, biboumi provides a few policy files, to work around some
242 issues found with a few well-known IRC servers.
243 Security
245 The connection to the XMPP server can only be made on localhost. The
246 XMPP server is not supposed to accept non-local connections from compo‐
247 nents. Thus, encryption is not used to connect to the local XMPP server
248 because it is useless.
249 If compiled with the Botan library, biboumi can use TLS when communi‐
251 cating with the IRC servers. It will first try ports 6697 and 6670 and
252 use TLS if it succeeds, if connection fails on both these ports, the
253 connection is established on port 6667 without any encryption.
254 Biboumi does not check if the received JIDs are properly formatted us‐
256 ing nodeprep. This must be done by the XMPP server to which biboumi is
257 directly connected.
258 Biboumi does not provide a way to ban users from connecting to it, has
260 no protection against flood or any sort of abuse that your users may
261 cause on the IRC servers. Some XMPP server however offer the possibil‐
262 ity to restrict what JID can access a gateway. Use that feature if you
263 wish to grant access to your biboumi instance only to a list of trusted
264 users.
265
267 Florent Le Coz
268
270 2023, Florent Le Coz
2718.4 Jan 18, 2023 BIBOUMI(1)