.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "TIRCD 1" .TH TIRCD 1 "2021-01-08" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" tircd \- An ircd proxy to the twitter API .SH "DESCRIPTION" .IX Header "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 .SH "INSTALLATION" .IX Header "INSTALLATION" tircd requires a recent version of perl, and the following modules: .PP \&\s-1POE\s0 .PP POE::Filter::IRCD .PP Net::Twitter::Lite::WithAPIv1_1 .PP JSON::Any .PP Time::Local .PP File::Glob .PP IO::File .PP LWP::UserAgent .PP Storable .PP \&\s-1URI\s0 .PP List::Util .PP HTML::Entities .PP Digest::SHA1 .PP If you're using a redhat or debian based system, attempt to use the distrobutions \s-1CPAN\s0 module packages, in yum or apt. .PP To install all modules via \s-1CPAN:\s0 .PP \&\fBcpan \-i \s-1POE\s0 POE::Filter::IRCD Net::Twitter::Lite JSON::Any Time::Local File::Glob IO::File LWP::UserAgent Storable \s-1URI\s0 List::Util HTML::Entities Digest::SHA1\fR .SH "USAGE" .IX Header "USAGE" .IP "Running tircd" 4 .IX Item "Running tircd" \&\fB./tircd.pl [/path/to/tircd.cfg]\fR .Sp When started, tircd will look for a configuration file in the following places: .Sp \&\fItircd.cfg\fR (in the current directory) .Sp \&\fI~/.tircd\fR .Sp \&\fI/etc/tircd.cfg\fR .Sp 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 \fItircd.cfg.example\fR to \fItircd.cfg\fR .SS "Connecting" .IX Subsection "Connecting" By default, tircd listens on localhost port 6667. .PP The first time you connect with a new twitter account you must specify a \fBtircd\fR 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. .PP \&\fBThe 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\fR .PP With many irc clients you can do this by issuing the command /SERVER localhost 6667 <\fBtircd\fR password> <\fBtwitter\fR username>. Check your client's documentation for the appropirate syntax. .PP 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 \s-1IRC\s0 connection status window. .PP 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 \*(L"Allow\*(R". Twitter will then present you with a \s-1PIN\s0 number. \fBTo complete your connection to tircd\fR, type: \fB/stats pin <\s-1PIN NUMBER\s0\fR>. On some clients you may have to type: \fB/quote stats pin <\s-1PIN NUMBER\s0\fR>. .PP If the \s-1PIN\s0 is accepted by Twitter, the connection will be established. You may now join #twitter to begin. If the \s-1PIN\s0 is not accepted, another authorization link will be generated. .IP "Account password protection" 4 .IX Item "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 \s-1IP\s0) you might want to password protect your account, or anyone can access your twitter account knowing the server address and your twitter username. \&\fBYour tircd-password do \s-1NOT\s0 need to be (and should not be!) the same as your twitter password.\fR .Sp Tircd supports password protection in the following way. .RS 4 .IP "\(bu" 4 The first time you connect to tircd with a new Username, no password checking is done. You are presented with the OAuth \s-1URL,\s0 and need to log in to twitter on the web, and enter the \s-1PIN\s0 as described above. .IP "\(bu" 4 When the \s-1PIN\s0 is accepted, \s-1IF\s0 your client connected with a password set, this password is encrypted (hashed) and saved along with your twitter access-tokens. .IP "\(bu" 4 Next time you connect, tircd will first check to see if a password is saved in your \fIUsername.config\fR, and comapre it with the one your client sends. .IP "\(bu" 4 If they match, your connecton is allowed, and tircd continue to verify the OAuth tokens with twitter. .IP "\(bu" 4 If they don't match, the client is disconnected with an error message. .IP "\(bu" 4 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 \f(CW\*(C`/STATS password \*(C'\fR .IP "\(bu" 4 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. .IP "\(bu" 4 If you want to remove the password, simply issue a \f(CW\*(C`/STATS password\*(C'\fR without any password set. .RE .RS 4 .Sp 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 \s-1PIN\s0 again. .RE .SS "After connecting" .IX Subsection "After connecting" Once connected \f(CW\*(C`/JOIN #twitter\*(C'\fR to get started. The channel #twitter is where you will perform most opertions .IP "Updating your status" 4 .IX Item "Updating your status" To update your status on twitter, simply send a message starting with \*(L"!t \*(R" to the #twitter channel. The server will keep your most recent update in the topic at all times. .Sp If you want to have all message you send to #twitter posted as tweets, you can set the config option \*(L"auto_post\*(R" to 1. Either in tircd.conf or via the /stats command. Messages beginning with an exclamation point (\*(L"!\*(R") will still be processed as commands, not tweeted. .IP "Getting your friend's status" 4 .IX Item "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. .Sp \&\f(CW@replies\fR are also sent to the channel as messages. .IP "Retweeting a status" 4 .IX Item "Retweeting a status" To retweet a status, use the offerbot command !retweet followed by the 3 letter tweet identifier. .Sp \&\fB!retweet a7f\fR .IP "Replying to a status" 4 .IX Item "Replying to a status" To reply to a status update, use the offerbot command !retweet followed by the 3 letter tweet identifier. .Sp \&\fB!reply 6eb \f(CB@tircdbot\fB not today! \fR .IP "Favoriting a tweet" 4 .IX Item "Favoriting a tweet" To favorite a tweet use the offerbot command !favorite followed by the 3 letter tweet identifier. .Sp \&\fB!favorite a44\fR .IP "Listing the users you follow" 4 .IX Item "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. .IP "Direct Messages" 4 .IX Item "Direct Messages" Direct messages to you will show up as a private message from the user. .Sp To send a direct message, simply send a private message to the user you want to dm. .IP "Getting additional information on users" 4 .IX Item "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. .Sp Issuing a /WHOIS on your own user name will also provide the number of \s-1API\s0 calls that have been used in the last hour. .IP "Following new users" 4 .IX Item "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. .Sp \&\fB!invite\fR is the analogous offerbot command. .IP "Unfollowing / removing users" 4 .IX Item "Unfollowing / removing users" To stop following a user, /KICK them from #twitter. .Sp \&\fB!kick\fR is the analogous offerbot command. .IP "Blocking users" 4 .IX Item "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 \s-1API,\s0 so listing the bans in #twitter will only return users you've blocked in the current session. .IP "Unblocking users" 4 .IX Item "Unblocking users" To unblock a user /UNBAN them. .IP "Multiple Channels / Groups" 4 .IX Item "Multiple Channels / Groups" If you want to create a channel with just a subset of the people you follow, you can \f(CW\*(C`/JOIN \*(C'\fR 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. .IP "Search" 4 .IX Item "Search" If you want to have updated search results for a specific term delivered, you can \f(CW\*(C`/JOIN \*(C'\fR then set the /topic for the channel 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 for exmaples). Using the 'near' option is not currently supported. .IP "User config" 4 .IX Item "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 \f(CW\*(C`/STATS m\*(C'\fR command to the server. .Sp These options are saved in a file with the name \fIUsername.config\fR (where Username is your twitter username) located in a directory set in the global config file (default: \fI/tmp/tricd\fR) .IP "Offerbot commands" 4 .IX Item "Offerbot commands" Tircd supports offerbot style control. All functions available through the offerbot are available as they're metaphorically appropriate \s-1IRC\s0 functions. Therefore, retweeting, replying to a specific tweet, and saving the user configuration are \fBonly\fR available through the offerbot. .Sp \&\fB![update|up|refresh]\fR \- Updates the #twitter stream immediately. .Sp \&\fB![tweet|t] \- Posts the given text as an update to your feed. .Sp \&\fB![retweet|rt] \- Posts a retweet. tweet-id is the 3 digit code preceding the tweet. .Sp \&\fB![reply|re] > \- Replies to a tweet. tweet-id is a the 3 digit code preceding the tweet. .Sp \&\fB![conversation|conv] \- Replay a conversation from beginning. If tweet is not a reply, shows related tweets. .Sp \&\fB![add|invite|follow] \- Begin following the specified twitter username. .Sp \&\fB![remove|kick|unfollow] \- Remove the username from the list of people your account follows. .Sp \&\fB!save\fR \- Saves twitter-username specific configuration immediately. .Sp \&\fB!help\fR \- Shows this help message. .SH "AUTHOR" .IX Header "AUTHOR" Tim Sogard [2010\-2011] .PP Ola Thoresen [2010\-2011] .PP Chris Nelson [2009] .SH "LICENSE" .IX Header "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. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1POE\s0 .PP POE::Filter::IRCD .PP Net::Twitter::Lite .PP JSON::Any .PP Time::Local .PP File::Glob .PP IO::File .PP LWP::UserAgent .PP Storable .PP \&\s-1URI\s0 .PP List::Util .PP HTML::Entities .PP Digest::SHA1