Package: kaoru
kaoruA Telegram Bot as your personal IoT assistantkaorucan be defined as a Telegram Bot whose roles are much alike
to those related to IoT personal assistant.OK, I think I get the idea, but what is it good for?kaoru’s purpose in life is to make your life a little bit easier by
allowing you remote control of certain things on your host(s), the rationale
behind this is that there could be moments in which you would need to perform
administrative tasks on either your office or home laptop, things that you
maybe forgot to do, or things you could only do by getting in front of them.
An IoT-like approach would be ideal on this scenario, namely, talk to your
machines and tell them to do stuff for you while you’re walking streets,
or having a dinner with your friend, or when you’re just too sleepy/lazy
to get up from your couch/bed.For the moment,kaoruis capable of:Rebooting your host(s)Shutting down your host(s)Locking the screen on your host(s)Send screen shots from your host(s)Suspending your host(s) to either RAM or diskThings I feel tempted to implement:Send alerts/warnings on certain things happening in your host(s)Tell your host(s) to send you a file in their file system.Perform atailon a file and send messages as new content is appended to that file.Wait, what?, bots are sort-of public domain, you know?While that’s true, the fact is that having your host runningkaorumeans that you have control overher, including (but not limited) to
control which people she’s going to listen to, as explained inSecurity.OK, I get it, how do I use this?, I just wanna get hands-on this “thing” …Well, the most essential thing you will need is to tell@BotFatherto
make a new bot for you, as specified inTelegram Bots DocumentationOn the other hand, you gotta installkaoru, of course.# First of all, you need to installpip3installkaoruA Telegram Bot is a just a dummy client with no cell phone attached to it,
you need something to control this bot so it can become active, and that’s whenkaorucomes into play.Make sure you have properly set up your brand new Telegram Bot,@BotFathershould have given you anAPI access token(a bunch of characters and numbers),kaoruneeds this token in order for her to do her magic.Moreover, you can edit yourconfiguration filefrom this point$vi/path/to/your/kaoru.confNOTE: A configuration file isnot mandatoryforkaoruto run, she can do
it using her defaults, however, you will need at least to set the API token
through the environment variableTG_TOKENNow you are done setting up kaoru, now is time to run it!$kaoru--config/path/to/you/kaoru.confkaoru[version]-https://github.com/axltxl/kaoru----------------------------------------------------Readingconfigurationfileat:asd.conf(!)Strictmodehasbeenenforced!(!)Youwillneedtoregistermycommandswithmy@BotFather(!)Askhimto/setcommandsandafteryou(!)havementionedme,youcanpastethefollowing:---about-Informationfornerdsstart-Startmeuphello-SeeifI"live"help-Getlistofavailablecommandsscreenlock-SeeifI"live"screenshot-Getascreenshotfromyourhost(s)dryrun-Toggle"dry run"modecancel-Cancelanypendingoperation(s)reboot-Rebootyourhost(s)poweroff-Shutdownyourhost(s)suspend-Suspendyourhost(s)toRAMhibernate-Suspendyourhost(s)todisk------Waitingforupdates...NOTE: bear in mind thatyou have to register kaoru’s commands for your botwith the@BotFather,kaoruwill tell you how.So, I have everything set up. What commands are available on this bot?Good question indeed!, the following is the current set of commands
supported bykaoru, more are planned to come:/helloA simple ping just to see if your bot isalive/helpHow to usekaoru/screenlockLock screens on your host(s)/screenshotGet a screen shot from your host(s)/poweroffTell your host(s) to shut down/rebootTell your host(s) to reboot/cancelCancel any pending operations/dryrundon’t do a thing, but pretend/aboutinformation, mostly for nerds/suspendSuspend your host(s) to RAM/hibernateSuspend your host(s) to diskAre there any sort of requirements for kaoru in order to work properly?Yes indeed. For the moment,kaoruis only working under certain
conditions. Hosts runningkaorumust:Be Linux-based at least (though conceptually speaking,*nixshould be supported)Havesudo. Since commands likeshutdownneed to be run asroot.Have eitherscrotorimagemagickinstalled (if you want/screenshotcommand to work)Run kaoru on behalf on an user whosesudoprivileges cover at least the execution ofshutdownwith no password requirement.Havepm-utilsinstalled on your system. This is necessary for/suspendand/hibernateto work properly.Configuration filekaorulists all sorts of configuration directives inside a YAML
configuration file. These directives range from essentials like
a Telegram Bot API token to those related with blablabla. Please refer
to theexample configuration filefor more details on how to configurekaoru.---############################# Example configuration file############################# Telegram Bot API access tokentoken:1XXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXX# shutdown the host 2 minutes after a /poweroff command has been receivedpoweroff_delay:2# command to execute when a /screenlock command has been receivedscreenlock_cmd:xscreensaverNOTE: Configuration files can be read bykaoruusing the--configargument, by default,kaoruwill look up for a configuration file on~/.config/kaoru/kaoru.confSecurityBy default,kaoruruns openly, namely, it will listen toany incoming
updates from any userwanting to communicate with her, while this would allow you
to quickly see her working,it is inherently and by all means INSECURE!!!!Once you feel happy with your configuration, it is strongly advised
that youenforce strict modeon your configuration file, like so:---# .. other options are behind# enforce strict modestrict:true# The following are the users who can talk# to kaoru. Requests coming from users outside# this list are simply IGNORED.masters:-<your Telegram user name>-betty# your friend betty can also talk to kaoruOnce you’re done, you can proceed to re-executekaoru.
Withstrictdirective set totrue,kaoruwill only
listen and react to commands and messages coming from users set inmasters.Optionskaoru[options]--versionshow version number and exit-i|--interactiveenter CLI mode-cFILE |--configFILEconfiguration file to use-h|--helpshow a help message and exit-d|--dry-rundon’t actually do anythingL NUM |--log-levelNUMset logging output level-lFILE |--log-fileLOG_FILEset log fileContributingThere are many ways in which you can contribute to kaoru.
Code patches are just one thing amongst others that you can submit to help the project.
We also welcome feedback, bug reports, feature requests, documentation improvements,
advertisement and testing.Feedback contributionsThis is by far the easiest way to contribute something.
If you’re using kaoru for your own benefit, don’t hesitate sharing.
Feel free tosubmit issues and enhancement requests.Copyright and LicensingCopyright (c) Alejandro RicoveriPermission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
“Software”), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.