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
|
<?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 % BOOK_ENTITIES SYSTEM "Fedora_Cookbook.ent">
%BOOK_ENTITIES;
]>
<!-- Do not edit above this line -->
<!--
name: Pete Travis
fas_id: immanetize
email: immanetize@fedoraproject.org
-->
<section id="bip">
<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 href="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>
</para></step>
<step>
<para>
Use the <application>bipgenconfig</application> utility to generate a configuration file.
</para>
<para>
In this example, you will configure the <xref linkend="http://freenode.net/">freenode</xref> 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>
<substeps>
<step>
<para />
</step>
<step>
<para />
</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>
|
