1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY YEAR "2014">
<!ENTITY HOLDER "| You need to change the HOLDER entity in the en-US/Fedora_Cookbook.ent file |">
<!ENTITY PRODUCT "Fedora Documentation">
<!ENTITY BOOKID "cookbook">
<!ENTITY BZURL "<ulink url='https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&component=&BOOKID;'>http://bugzilla.redhat.com/</ulink>">
]>
<section id="bip" lang="en-US">
<!-- Do not edit above this line --><!--
name: Pete Travis
fas_id: immanetize
email: immanetize@fedoraproject.org
--> <title>Installing the <systemitem class="daemon">bip</systemitem> IRC Proxy</title>
<para>
Internet Relay Chat, or IRC, is a venerable and popular way to communicate over the internet. Fedora users can <ulink url="https://fedoraproject.org/wiki/Communicating_and_getting_help#IRC_for_interactive_community_support">get help</ulink> on IRC, and many other open source projects use it to collaborate. IRC is accessed using an <emphasis>IRC Client</emphasis>, and clients are available for almost every platform, including <systemitem class="osname">Windows</systemitem>, <systemitem class="osname">OS X</systemitem>, <systemitem class="osname">Android</systemitem>, <systemitem class="osname">iOS</systemitem>, and of course every Linux distribution.
</para>
<indexterm>
<primary>bouncer</primary>
</indexterm>
<para>
An IRC Proxy, or <firstterm>bouncer</firstterm>, connects to an IRC server just like any other client. Rather than presenting the connection in a chat window, the <application>bouncer</application> relays the connection to other clients. You can connect multiple clients to the same bouncer, allowing conversations to remain uninterrupted as you move between devices. The bouncer also keeps logs, and replays recent conversations when you connect, so you can catch up after being away.
</para>
<para>
The <systemitem class="daemon">bip</systemitem> is easy to install and configure in Fedora. Follow the instructions below, and you'll be up and running in just a few minutes.
</para>
<section id="bip-ingredients">
<title>Required Ingredients</title>
<!-- list packages, services, other recipes etc that are required --> <itemizedlist>
<listitem>
<para>
Seperate machines for the IRC proxy and client.
</para>
<para>
This ingredient is optional; you can use bip on the same system as the client to keep logs, or a persistent IRC session while switching users or logging out. <systemitem class="daemon">bip</systemitem> is most useful when run on a seperate server, and can work on even low power devices like a <hardware arch="ARMv6">Raspberry Pi</hardware> or other ARM device.
</para>
</listitem>
<listitem>
<para>
An active internet connection.
</para>
</listitem>
<listitem>
<para>
The <package>bip</package> package.
</para>
</listitem>
<listitem>
<para>
An IRC Client.
</para>
<para>
Fedora offers many IRC clients, and the right one is a matter of personal preference. If you are new to IRC, try starting with <application>hexchat</application>.
</para>
</listitem>
<listitem>
<para>
tcp port 7778 set to forward to your <systemitem class="daemon">bip</systemitem> server.
</para>
<para>
This is <emphasis>only</emphasis> needed if you want to use the server when outside your home network.
</para>
</listitem>
</itemizedlist>
</section>
<section id="bip-directions">
<title>Directions</title>
<procedure>
<title>Installing and Configuring <systemitem class="daemon">bip</systemitem></title>
<step>
<para>
Install required packages on the server:
</para>
<screen>
<command>yum install bip</command>
</screen>
</step>
<step>
<para>
Use the <application>bipgenconfig</application> utility to generate a configuration file.
</para>
<para>
In this example, you will configure the <ulink url="http://freenode.net/">freenode</ulink> IRC network. Fedora's IRC channels are on Freenode.
</para>
<substeps>
<step>
<para>
Start <application>bipgenconfig</application> from a terminal.
</para>
<screen>
<command>bipgenconfig</command>
<computeroutput> # This script will help you build a configuration file # # WARNING: non-advanced mode, some 'expert' options'll be hidden ! # 1. Set global options 2. Add a new network 3. Add a new user 4. View global options 5. View/Edit/Delete networks 6. View/Edit/Delete users 7. Generate a server certificate/key pair 8. Switch to advanced mode 10. Exit: store, write configuration and exit 11. Exit without saving 12. Store configuration for later use 20. Reset config options 21. Load stored config 22. Parse and load current config (todo) What do you want to do ? </computeroutput>
</screen>
</step>
<step>
<para>
Enter the system wide settings dialog by pressing <keycap>1</keycap> and <keycap>Enter</keycap>
</para>
<screen>
<computeroutput> * Do you want to enable channel logging ? [Y/n] y * Do you want to enable system logging ? [Y/n] y * In which directory do you want logs to be stored ? [/home/pete/.bip/logs] /var/log/bip/ </computeroutput>
</screen>
<para>
Logging is turned on here, and logs are sent to the system log directory.
</para>
</step>
<step>
<para>
Back at the main menu, press <keycap>2</keycap> and <keycap>Enter</keycap> to create a network definition.
</para>
<screen><computeroutput> * Network's name <replaceable>freenode</replaceable> * Enable SSL for this network ? [y/N] <replaceable>n</replaceable> Adding a new server : * IRC server's IP address/hostname <replaceable>irc.freenode.net</replaceable> * IRC server's port [6667] <replaceable>6667</replaceable> Do you want to add a new server ? [Y/n] <replaceable>n</replaceable> </computeroutput></screen>
</step>
<step>
<para>
The <function>Add a new user</function> section at option <keycap>3</keycap> is where you configure your user for bip, the connections bip will provide to that user, and the user's accounts on the previously configured networks.
</para>
<screen><computeroutput> * User's internal name ? fedorauser Set a password for his bip account: ? Password: * User's default IRC nickname fedorauser * User's default IRC username fedorauser * User's default IRC realname Fedora B User * Do you want to activate backlog {play back logs} system ? [Y/n] y </computeroutput></screen>
<para>
The options above are for your user account with bip. The password is hashed when stored, and does not appear on the screen when typed.
</para>
<screen><computeroutput> Adding a new connection : * Connection name (used by bip only) <replaceable>freenode</replaceable> * Network to connect to freenode * Use default identity ? [Y/n] y * IRC server's password ? <replaceable>fedorauser</replaceable>:<replaceable>freenode-nickserv-password</replaceable> </computeroutput></screen>
<para>
In this section, you have created a <function>connection</function> for the freenode network that was defined in an earlier step. Freenode accepts authentication to a registered nick by a server password like the one in the example. While the configuration file will only be readable by root on the server, this password is stored in plain text.
</para>
<screen><computeroutput> * Follow nicknames changes from clients to use upon reconnection (if false, bip'll use config nickname) [Y/n] n * Ignore nickname change sent by a client (first one only, upon client attach) [Y/n] y * Set nickname to this value when there's no more client attached: fedorauser * Set this away message when there's no more client attached: * Send this raw message upon connection to IRC server </computeroutput></screen>
<para>
These options are set to retain the configured user name as much as possible. It is generally considered good IRC ediquette to avoid adding noise by changing your nick often.
</para>
<screen><computeroutput> Adding a new channel : * Channel name #fedora * Channel key (optional) Do you want to add a new channel ? [Y/n] y Adding a new channel : * Channel name #fedora-docs * Channel key (optional) Do you want to add a new channel ? [Y/n] n Do you want to add a new connection ? [Y/n] n </computeroutput></screen>
<para>
Configure the channels you would like to automatically join, and enter the channel password if required. <systemitem class="daemon">bip</systemitem> will connect to these channels when it starts. If you join additional channels, bip can keep them open for you, but they will not be rejoined if the service is restarted.
</para>
</step>
<step>
<para>
Select option <keycap>10</keycap> after reviewing your configuration to save and exit.
</para>
<screen><computeroutput> Configuration stored in /home/pete/.bip/bipgenconfig.store Configuration saved in /home/pete/.bip/bip.conf.autogen 1 users defined, 1 networks defined Configuration has been generated in /home/pete/.bip/bip.conf.autogen You have to rename all generated files to use them </computeroutput></screen>
</step>
<step>
<para>
Copy the new configuration file to the appropriate path and set ownership.
</para>
<screen>
<command> sudo cp /home/fedorauser/.bip/bip.conf.autogen /etc/ </command>
<command> sudo chown root:bip /etc/bip.conf </command>
<command> sudo chmod 0640 /etc/bip.conf </command>
</screen>
</step>
</substeps>
</step>
<step>
<para>
Activate the bip service:
<screen>
<command>systemctl start bip</command>
<command>systemctl enable bip</command>
</screen>
</para>
</step>
<step>
<para>
Configure your IRC client to use the bip service.
</para>
<para>
This example is for <application>HexChat</application>. To configure other clients, refer to that client's documentation.
</para>
<substeps>
<step>
<para>
Launch <application>hexchat</application> and open the Network List by clicking <guimenuitem>Hexchat</guimenuitem> then <guimenuitem>Network List...</guimenuitem>.
</para>
</step>
<step>
<para>
Click the <guibutton>Add</guibutton> button in the Network List window.
</para>
<para>
A new network item is immediately added to the <guilabel>Networks</guilabel>. Type in a name for your network, such as <replaceable>Fedorauser's BIP server</replaceable>.
</para>
</step>
<step>
<para>
Click <guibutton>Edit...</guibutton> to enter more details for the connection.
</para>
<substeps>
<step>
<para>
Click <guibutton>Add</guibutton> to add an address for your server. A new entry will immediately be created for editing in the list.
</para>
<para>
Enter your server's IP address and the port number. It should look something like this:
</para>
<screen>
<systemitem class="ipaddress">192.168.1.72</systemitem>/7778
</screen>
</step>
<step>
<para>
Enter your bip user information in the <guilabel>Password:</guilabel>. The form is <emphasis>bip_username:bip_connection:bip_user_password</emphasis>. To use the freenode connection from the earlier steps, this would be:
</para>
<screen>
fedorauser:freenode:<replaceable>bip_user_password</replaceable>
</screen>
</step>
<step>
<para>
If you choose, checking the box for <guilabel>Connect to this network automatically</guilabel> will configure hexchat to connect to your bouncer every time hexchat is opened.
</para>
</step>
</substeps>
</step>
</substeps>
</step>
</procedure>
</section>
<section>
<title>References</title>
<itemizedlist>
<listitem>
<para>
<ulink url="http://example.com">Upstream Documentation</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://example.com/myblog/posts/todays_date" />
</para>
</listitem>
</itemizedlist>
</section>
</section>
|
