TIRCD(1) User Contributed Perl Documentation TIRCD(1)NAMEtircd - An ircd proxy to the twitter API
DESCRIPTIONtircd presents twitter as an irc channel. You can connect to tircd
with any irc client, and twitter as if you were on irc
INSTALLATIONtircd 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
/usr/local/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>
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
perl v5.20.3 2016-02-18 TIRCD(1)
