doc/FAQ


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

Frequently Asked Questions about BitlBee
========================================

Well, maybe not exactly "Frequently", but definitely "Asked" ... mostly by
the developers :-)

Q: WTH were you guys on when you thought of that _weird_ name?
A: Though we live in The Netherlands and one of us even lives in Amsterdam,
   we're not on drugs ... most of the time.

Q: Okay, so the cops are so evil there, you can't even admit the truth, but
   WTH does BitlBee mean then?
A: There are a few explanations. But the most symbolical goes like: the two
   colors of the bee symbolize the two worlds betwee which the Bee flies. On
   the one hand there's the IM-networks, on the other is IRC.
   
   Truth be told, it's absolute nonsense. The biggest nutcase in the
   development team just played around with words for half an hour or so.
   BitlBee was the result. We liked it, we kept it. We lovingly shorten it
   to "the Bee" or even "het Bijtje" (Dutch for "the little Bee") sometimes.

Q: What is 'root' doing in my control channel? I didn't start the Bee as
   root.
A: 'root' is just the name for the most powerful user in BitlBee. Just like
   in the system, it is root who is the ... eh ... root of the
   functionality. Luckily, in BitlBee, root follows your orders (mostly), so
   no BOFHs there.
   
   We get some complaints from time to time that 'root' is a confusing name.
   Because of that name, some package maintainers have renamed root to, for
   example, BitlBee. We recognize that some people see that need. If the
   package maintainer hasn't renamed root, you can do this yourself with the
   'rename' command.
   
   The name root is not likely to change in the 'official' releases, though.
   We find the metaphor of root correct and feel that there is no important
   (security threatening) reason to change this non-creative piece of
   artistic creativity.

Q: When is $random_feature going to be implemented?
A: It depends on the feature. We keep a list of all wishlist "bugs" in our
   Bug Tracking system at http://bugs.bitlbee.org/

Q: The messages I send and/or receive look weird. I see weird characters and
   annoying HTML codes. Or, BitlBee does evil things when I send messages with
   non-ASCII characters!
A: You probably have to change some settings. To get rid of HTML in messages,
   see "help set strip_html". If you seem to have problems with your charset,
   see "help set charset".
   
   Although actually most of these problems should be gone by now. So if you
   can't get things to work well, you might have found a bug.

Q: Is BitlBee forked from Gaim?
A: BitlBee 0.7 was, sort-of. It contained a lot of code from Gaim 0.58
   (mainly the IM-code), although heavily modified, to make it work better
   with BitlBee. We were planning to keep BitlBee up-to-date with later Gaim
   versions, but this turned out to be very time-consuming because the API
   changed a lot, and we don't have the time to keep up with those changes
   all the time.
   
   These days, we replaced the Yahoo! code with libyahoo2 (which is a
   separate Yahoo! module. It's derived from Gaim, but separately
   maintained) and wrote our own MSN, Jabber and Twitter modules from
   scratch. Most of the API has also been changed, so by now the only traces
   of Gaim left are in the "nogaim" filename.
   
   There is good news for Gaim (or now Pidgin, of course) fans though:
   BitlBee can now be compiled to use libpurple for all IM interactions.
   This makes BitlBee a bit more resource-hungry, but adds support for many
   IM protocols/networks that couldn't be used from BitlBee so far.

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

# AUTHOR: blink <blinketje@gmail.com>; blink#ruby-lang@irc.freenode.net
# bugrep: Andreas Zehnder

require 'time'
require 'rack/request'
require 'rack/response'

module Rack

  module Session

    module Abstract

      # ID sets up a basic framework for implementing an id based sessioning
      # service. Cookies sent to the client for maintaining sessions will only
      # contain an id reference. Only #get_session and #set_session are
      # required to be overwritten.
      #
      # All parameters are optional.
      # * :key determines the name of the cookie, by default it is
      #   'rack.session'
      # * :path, :domain, :expire_after, :secure, and :httponly set the related
      #   cookie options as by Rack::Response#add_cookie
      # * :defer will not set a cookie in the response.
      # * :renew (implementation dependent) will prompt the generation of a new
      #   session id, and migration of data to be referenced at the new id. If
      #   :defer is set, it will be overridden and the cookie will be set.
      # * :sidbits sets the number of bits in length that a generated session
      #   id will be.
      #
      # These options can be set on a per request basis, at the location of
      # env['rack.session.options']. Additionally the id of the session can be
      # found within the options hash at the key :id. It is highly not
      # recommended to change its value.
      #
      # Is Rack::Utils::Context compatible.

      class ID
        DEFAULT_OPTIONS = {
          :path =>          '/',
          :domain =>        nil,
          :expire_after =>  nil,
          :secure =>        false,
          :httponly =>      true,
          :defer =>         false,
          :renew =>         false,
          :sidbits =>       128
        }

        attr_reader :key, :default_options
        def initialize(app, options={})
          @app = app
          @key = options[:key] || "rack.session"
          @default_options = self.class::DEFAULT_OPTIONS.merge(options)
        end

        def call(env)
          context(env)
        end

        def context(env, app=@app)
          load_session(env)
          status, headers, body = app.call(env)
          commit_session(env, status, headers, body)
        end

        private

        # Generate a new session id using Ruby #rand.  The size of the
        # session id is controlled by the :sidbits option.
        # Monkey patch this to use custom methods for session id generation.

        def generate_sid
          "%0#{@default_options[:sidbits] / 4}x" %
            rand(2**@default_options[:sidbits] - 1)
        end

        # Extracts the session id from provided cookies and passes it and the
        # environment to #get_session. It then sets the resulting session into
        # 'rack.session', and places options and session metadata into
        # 'rack.session.options'.

        def load_session(env)
          request = Rack::Request.new(env)
          session_id = request.cookies[@key]

          begin
            session_id, session = get_session(env, session_id)
            env['rack.session'] = session
          rescue
            env['rack.session'] = Hash.new
          end

          env['rack.session.options'] = @default_options.
            merge(:id => session_id)
        end

        # Acquires the session from the environment and the session id from
        # the session options and passes them to #set_session. If successful
        # and the :defer option is not true, a cookie will be added to the
        # response with the session's id.

        def commit_session(env, status, headers, body)
          session = env['rack.session']
          options = env['rack.session.options']
          session_id = options[:id]

          if not session_id = set_session(env, session_id, session, options)
            env["rack.errors"].puts("Warning! #{self.class.name} failed to save session. Content dropped.")
          elsif options[:defer] and not options[:renew]
            env["rack.errors"].puts("Defering cookie for #{session_id}") if $VERBOSE
          else
            cookie = Hash.new
            cookie[:value] = session_id
            cookie[:expires] = Time.now + options[:expire_after] unless options[:expire_after].nil?
            Utils.set_cookie_header!(headers, @key, cookie.merge(options))
          end

          [status, headers, body]
        end

        # All thread safety and session retrival proceedures should occur here.
        # Should return [session_id, session].
        # If nil is provided as the session id, generation of a new valid id
        # should occur within.

        def get_session(env, sid)
          raise '#get_session not implemented.'
        end

        # All thread safety and session storage proceedures should occur here.
        # Should return true or false dependant on whether or not the session
        # was saved or not.
        def set_session(env, sid, session, options)
          raise '#set_session not implemented.'
        end
      end
    end
  end
end