Provided by: tircd_0.30-1_all bug

NAME

       tircd  - An ircd proxy to the twitter API

DESCRIPTION

       tircd presents twitter as an irc channel.  You can connect to tircd with any irc client,
       and twitter as if you were on irc

INSTALLATION

       tircd requires a recent version of perl, and the following modules:

       POE

       POE::Filter::IRCD

       Net::Twitter::Lite::WithAPIv1_1

       JSON::Any

       Time::Local

       File::Glob

       IO::File

       LWP::UserAgent

       Storable

       URI

       List::Util

       HTML::Entities

       Digest::SHA1

       If you're using a redhat or debian based system, attempt to use the distrobutions CPAN
       module packages, in yum or apt.

       To install all modules via CPAN:

       cpan -i POE POE::Filter::IRCD Net::Twitter::Lite JSON::Any Time::Local File::Glob IO::File
       LWP::UserAgent Storable URI List::Util HTML::Entities Digest::SHA1

USAGE

       Running tircd
           ./tircd.pl [/path/to/tircd.cfg]

           When started, tircd will look for a configuration file in the following places:

           tircd.cfg (in the current directory)

           ~/.tircd

           /etc/tircd.cfg

           You can specify an alternate path to the configuration file on the commandline if you
           want to keep the configuration in another location.  There is an example config
           provided as part of the distribution. The easiest way to get started is to just rename
           that file from tircd.cfg.example to tircd.cfg

   Connecting
       By default, tircd listens on localhost port 6667.

       The first time you connect with a new twitter account you must specify a tircd password
       for that nick. This password does not have to (and should not) be the same as your twitter
       password. This password will protect your tircd account from unauthorized usage.

       The above password is to protect your tircd account, and is not related to your twitter
       account. The tircd nick password will only be saved once you have logged into Twitter

       With many irc clients you can do this by issuing the command /SERVER localhost 6667 <tircd
       password> <twitter username>. Check your client's documentation for the appropirate
       syntax.

       Tircd will make an OAuth challenege to Twitter, and Twitter will return a link to a page
       where you can authorize the connection. This link will appear in your IRC connection
       status window.

       Make sure you are either logged into twitter as the account you plan to use, or not logged
       in. Click the authorize link and log-in, then click "Allow". Twitter will then present you
       with a PIN number. To complete your connection to tircd, type: /stats pin <PIN NUMBER>. On
       some clients you may have to type: /quote stats pin <PIN NUMBER>.

       If the PIN is accepted by Twitter, the connection will be established. You may now join
       #twitter to begin. If the PIN is not accepted, another authorization link will be
       generated.

       Account password protection
           If your tircd installation is running in a shared environment (either listening on the
           localhost address on a shared computer, or listening on a public IP) you might want to
           password protect your account, or anyone can access your twitter account knowing the
           server address and your twitter username.  Your tircd-password do NOT need to be (and
           should not be!) the same as your twitter password.

           Tircd supports password protection in the following way.

           •   The first time you connect to tircd with a new Username, no password checking is
               done.  You are presented with the OAuth URL, and need to log in to twitter on the
               web, and enter the PIN as described above.

           •   When the PIN is accepted, IF your client connected with a password set, this
               password is encrypted (hashed) and saved along with your twitter access-tokens.

           •   Next time you connect, tircd will first check to see if a password is saved in
               your Username.config, and comapre it with the one your client sends.

           •   If they match, your connecton is allowed, and tircd continue to verify the OAuth
               tokens with twitter.

           •   If they don't match, the client is disconnected with an error message.

           •   If you want to change your password, or did not set one on your first connection,
               you can do so after you have connected to tircd with a simple "/STATS password
               <password>"

           •   Be aware that if you do this, you will also have to make sure your client uses the
               same password next time you connect to tircd.

           •   If you want to remove the password, simply issue a "/STATS password" without any
               password set.

           There is currently no way of regaining access to your account if you forget it.  To
           reset your tircd password, you will have to remove your Username.config and authorize
           with twitter using OAuth and a PIN again.

   After connecting
       Once connected "/JOIN #twitter" to get started.  The channel #twitter is where you will
       perform most opertions

       Updating your status
           To update your status on twitter, simply send a message starting with "!t " to the
           #twitter channel.  The server will keep your most recent update in the topic at all
           times.

           If you want to have all message you send to #twitter posted as tweets, you can set the
           config option "auto_post" to 1. Either in tircd.conf or via the /stats command.
           Messages beginning with an exclamation point ("!") will still be processed as
           commands, not tweeted.

       Getting your friend's status
           When users you follow update their status, it will be sent to the channel as a message
           from them. Each status will be preceded by a 3 letter identifier such as [a7f]. This
           identifier is used for retweeting and replying to tweets.

           @replies are also sent to the channel as messages.

       Retweeting a status
           To retweet a status, use the offerbot command !retweet followed by the 3 letter tweet
           identifier.

           !retweet a7f

       Replying to a status
           To reply to a status update, use the offerbot command !retweet followed by the 3
           letter tweet identifier.

           !reply 6eb @tircdbot not today!

       Favoriting a tweet
           To favorite a tweet use the offerbot command !favorite followed by the 3 letter tweet
           identifier.

           !favorite a44

       Listing the users you follow
           Each user you follow will be in the #twitter channel.  If you follow a new user
           outside of tircd, that user will join the channel the first time they update their
           status.  People who follow you back are given voice (+v) to indicate that fact.

       Direct Messages
           Direct messages to you will show up as a private message from the user.

           To send a direct message, simply send a private message to the user you want to dm.

       Getting additional information on users
           You can /WHO or /WHOIS a user to view their Location / Bio / Website. Their last
           status update (and time sent) will also be returned.

           Issuing a /WHOIS on your own user name will also provide the number of API calls that
           have been used in the last hour.

       Following new users
           To begin following a new user, simply /INVITE them to #twitter.  The user will join
           the channel if the request to follow was successful.  If you attempt to invite a user
           who protects their updates, you will receive a notice that you have requested to
           follow them.  The user will join the channel if they accept your request and update
           their status.

           !invite is the analagous offerbot command.

       Unfollowing / removing users
           To stop following a user, /KICK them from #twitter.

           !kick is the analagous offerbot command.

       Blocking users
           To block a user /BAN them.  There is currently no way to get a list of users you've
           currently blocked via the API, so listing the bans in #twitter will only return users
           you've blocked in the current session.

       Unblocking users
           To unblock a user /UNBAN them.

       Multiple Channels / Groups
           If you want to create a channel with just a subset of the people you follow, you can
           "/JOIN <any channel>" and then /INVITE them to the channel.  tircd will send a user's
           updates to #twitter and any other channels you have invited a user to.

       Search
           If you want to have updated search results for a specific term delivered, you can
           "/JOIN <any channel>" then set the /topic for the channnel to your search query.
           Results that match that query will be sent to that channel. The /TOPIC can be almost
           anything supported by the twitter search (see
           http://support.twitter.com/articles/71577-how-to-use-advanced-twitter-search
           <http://support.twitter.com/articles/71577-how-to-use-advanced-twitter-search> for
           exmaples).  Using the 'near' option is not currently supported.

       User config
           Certain options are changeable at runtime and set per user. To see a list of options
           and their current values simply send an "/STATS m" command to the server.

           These options are saved in a file with the name Username.config (where Username is
           your twitter username) located in a directory set in the global config file (default:
           /tmp/tricd)

       Offerbot commands
           Tircd supports offerbot style control. All functions available through the offerbot
           are available as they're metaphorically appropriate IRC functions. Therefore,
           retweeting, replying to a specific tweet, and saving the user configuration are only
           available through the offerbot.

           ![update|up|refresh] - Updates the #twitter stream immediately.

           ![tweet|t] <text of tweet> - Posts the given text as an update to your feed.

           ![retweet|rt] <tweed-id> - Posts a retweet. tweet-id is the 3 digit code preceding the
           tweet.

           ![reply|re] <tweet-id <message text>> - Replies to a tweet. tweet-id is a the 3 digit
           code preceding the tweet.

           ![conversation|conv] <tweet-id> - Replay a conversation from begining. If tweet is not
           a reply, shows related tweets.

           ![add|invite|follow] <username> - Begin following the specified twitter username.

           ![remove|kick|unfollow] <username> - Remove the username from the list of people your
           account follows.

           !save - Saves twitter-username specific configuration immediately.

           !help - Shows this help message.

AUTHOR

       Tim Sogard <tircd@timsogard.com> [2010-2011]

       Ola Thoresen <olen@inni.no> [2010-2011]

       Chris Nelson <cnelson@crazybrain.org>  [2009]

LICENSE

       This module may be used, modified, and distributed under the same terms as Perl itself.
       Please see the license that came with your Perl distribution for details.

SEE ALSO

       POE

       POE::Filter::IRCD

       Net::Twitter::Lite

       JSON::Any

       Time::Local

       File::Glob

       IO::File

       LWP::UserAgent

       Storable

       URI

       List::Util

       HTML::Entities

       Digest::SHA1