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

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@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>
+
+