1 # irgramd - IRC <-> Telegram Gateway
  2 
  3 irgramd is a gateway that allows connecting from an [IRC] client to
  4 [Telegram] as a regular user (not bot).
  5 
  6 irgramd is written in [python] (version 3), it acts as an IRC server
  7 where an IRC client can connect and on the other side it's a Telegram client
  8 using the [Telethon] library.
  9 
 10 **[irgramd primary repository] is in [darcs] version control system, github
 11 is used as [project management and secondary repository]**
 12 
 13 **irgramd was forked from [pbui/irtelegramd], was heavily modified and
 14 currently is a project on its own**
 15 
 16 **irgramd is under active development, though usable, several
 17 planned features are not implemented yet**
 18 
 19 ## How it works
 20 
 21 Configure your IRC client to connect to irgramd (running on the same host or
 22 on a remote host) then you will see in your IRC client the Telegram groups
 23 as IRC channels and Telegram users as IRC users, if you send a message to a
 24 user or channel in IRC it will go to the corresponding user or group in
 25 Telegram, and the same from Telegram to IRC.
 26 
 27 The users on Telegram using the official or other clients will see you with
 28 your regular Telegram user account and will be indistinguishable for them
 29 whether you are using irgramd or another Telegram client.
 30 
 31 Several IRC clients can connect to irgramd but they will see the same
 32 Telegram account, this allows connecting to the same Telegram account from
 33 different IRC clients on different locations or devices, so one irgramd
 34 instance only connects to one Telegram account, if you want to connect to
 35 several Telegram accounts you will need to run several irgramd instances. If
 36 all IRC clients are disconnected, irgramd will remain connected to Telegram.
 37 
 38 irgramd can also be seen as a kind of bouncer ([BNC]), with the difference
 39 that instead of talking IRC protocol on the client side, it talks Telegram
 40 protocol (MTProto), and can hide the IP and location of the IRC client (if
 41 executed in a different host).
 42 
 43 ## Features
 44 
 45 - Channels, groups and private chats
 46 - Users and channels mapped in IRC
 47 - Messages (receive, send)
 48 - Media in messages (receive, download, upload)
 49 - Replies (receive, send)
 50 - Forwards (receive, send)
 51 - Deletions (receive, do)
 52 - Editions (receive, do)
 53 - Reactions (receive, send, remove)
 54 - Polls (receive, show)
 55 - Actions [pin message, channel photo] (receive)
 56 - Dialogs management
 57 - History
 58 - Authentication and TLS for IRC
 59 - Multiple connections from IRC
 60 
 61 ## Requirements
 62 
 63 - [python] (>= v3.9)
 64 - [telethon] (tested with v1.28.5)
 65 - [tornado] (tested with v6.1.0)
 66 - [aioconsole] (tested with v0.6.1)
 67 - [pyPAM] (optional, tested with v0.4.2-13.4 from deb, [legacy web](https://web.archive.org/web/20110316070059/http://www.pangalactic.org/PyPAM/))
 68 
 69 ## Instalation
 70 
 71 ### From darcs
 72 
 73     darcs clone https://src.presi.org/repos/darcs/irgramd
 74     chmod +x irgramd/irgramd
 75 
 76 ### From git
 77 
 78     git clone https://github.com/prsai/irgramd.git
 79     chmod +x irgramd/irgramd
 80 
 81 ## Configuration
 82 
 83 From irgramd directory `./irgramd --help` will show all configuration
 84 options available, these options can be used directy in the command line or
 85 in a file.
 86 
 87 When used in command line the separator is `-` (dash) with two leading
 88 dashes, example: `--api-hash`.
 89 
 90 When used in a file the separator is `_` (underscore) without two leading
 91 dashes nor underscores, example: `api_hash`. The syntax of this file is just
 92 Python so strings are surrounded by quotes (`'`) and lists by brackets (`[]`).
 93 
 94 A sample of the configuration file is provided, copy it to the default
 95 configuration location:
 96 
 97     mkdir -p  ~/.config/irgramd
 98     cp irgramd/irgramdrc.sample ~/.config/irgramd/irgramdrc
 99 
100 And modified it with your API IDs and preferences.
101 
102 ## Usage
103 
104 From irgramd directory, in foreground:
105 
106     ./irgramd
107 
108 In background (with logs):
109 
110     ./irgramd --log-file=irgramd.log &
111 
112 ## Notes
113 
114 PAM authentication: it allows to authenticate IRC users from the system in
115 Unix/Linux. The user that executes irgramd must have permissions to use PAM
116 (e.g. in Linux be in the shadow group or equivalent). The dependency is
117 totally optional, if not used, the module pyPAM is not needed.
118 
119 ## Inspired by
120 
121 - [telegramircd]
122 - [ibotg]
123 - [bitlbee]
124 
125 ## License
126 
127 Copyright (c) 2019 Peter Bui <pbui@bx612.space>  
128 Copyright (c) 2020-2024 E. Bosch <presidev@AT@gmail.com>
129 
130 Use of this source code is governed by a MIT style license that
131 can be found in the LICENSE file included in this project.
132 
133 [IRC]: https://en.wikipedia.org/wiki/Internet_Relay_Chat
134 [Telegram]: https://telegram.org/
135 [python]: https://www.python.org/
136 [Telethon]: https://github.com/LonamiWebs/Telethon
137 [irgramd primary repository]: https://src.presi.org/darcs/irgramd
138 [darcs]: http://darcs.net
139 [project management and secondary repository]: https://github.com/prsai/irgramd
140 [pbui/irtelegramd]: https://github.com/pbui/irtelegramd
141 [python]: https://www.python.org
142 [tornado]: https://www.tornadoweb.org
143 [aioconsole]: https://github.com/vxgmichel/aioconsole
144 [pyPAM]: https://packages.debian.org/bullseye/python3-pam
145 [BNC]: https://en.wikipedia.org/wiki/BNC_(software)
146 [telegramircd]: https://github.com/prsai/telegramircd
147 [ibotg]: https://github.com/prsai/ibotg
148 [bitlbee]: https://www.bitlbee.org