Repository :
http://git.fedorahosted.org/cgit/docs/fedora-cookbook.git
On branch : master
---------------------------------------------------------------
commit db0bfbce1a2c9793aea2d99ea01ac53d24d9d6e9
Author: Pete Travis <immanetize(a)fedoraproject.org>
Date: Wed May 21 23:31:47 2014 -0600
add recipe for deploying bip.
TODO:
- follow up on
https://bugzilla.redhat.com/show_bug.cgi?id=1100133
- Complete client configuration instructions
- provide references or external resources
---------------------------------------------------------------
en-US/Communications/bip.xml | 271 ++++++++++++++++++++++++++++++++++++++++++
1 files changed, 271 insertions(+), 0 deletions(-)
diff --git a/en-US/Communications/bip.xml b/en-US/Communications/bip.xml
new file mode 100644
index 0000000..829412e
--- /dev/null
+++ b/en-US/Communications/bip.xml
@@ -0,0 +1,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(a)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#...
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>
+
+