From 29ea2f46a81c516a08767eafdab9698d5cbd6150 Mon Sep 17 00:00:00 2001 From: Simeon Simeonov Date: Sat, 30 Jun 2018 12:22:35 +0200 Subject: Documentation cleanups. INSTALL -> INSTALL.md, README -> README.md --- Changelog | 4 +- INSTALL | 98 ------------------------------- INSTALL.md | 83 +++++++++++++++++++++++++++ README | 122 --------------------------------------- README.md | 124 ++++++++++++++++++++++++++++++++++++++++ beinc_config_sample.json | 12 ---- beinc_config_sample.json.readme | 34 ++--------- 7 files changed, 214 insertions(+), 263 deletions(-) delete mode 100644 INSTALL create mode 100644 INSTALL.md delete mode 100644 README create mode 100644 README.md diff --git a/Changelog b/Changelog index 136fba8..7da19a3 100644 --- a/Changelog +++ b/Changelog @@ -1,6 +1,8 @@ v3.0: - - remove TwistedWeb dependency and write the beinc_server.py in pure Python + - remove the TwistedWeb dependency and rewrite the beinc_server.py + in pure Python - implement Python >= 3.4.0 support + - remove pyosd support v2.0: - replace charrypy with TwistedWeb as beinc_server.py backend diff --git a/INSTALL b/INSTALL deleted file mode 100644 index f26a6f9..0000000 --- a/INSTALL +++ /dev/null @@ -1,98 +0,0 @@ -Installation Instructions -------------------------- - -Refer to README for a basic information about the different BEINC components -and their software requirements! - - -Installing the dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -Gentoo GNU/Linux 2014, 2015 -.......................... - -# emerge -va dev-python/pyopenssl dev-python/twisted-web dev-python/notify-python dev-python/pyosd - - -Ubuntu GNU/Linux -................ - -# apt-get install python-openssl python-twisted-web python-notify2 python-pyosd - - -FreeBSD 9, 10 -............. - -# cd /usr/ports/security/py-openssl -# make install clean - -# cd /usr/ports/www/py-twistedWeb -# make install clean - -# cd /usr/ports/devel/py-notify -# make install clean - -# cd /usr/ports/misc/py-osd -# make install clean - - -Intallation using virtualenv and pip -.................................... - -Very often you are not the administrator of the server hosting your BEINC server -This is where virtualenv may become handy (provided that it has been installed): -$ virtualenv beinc_installation -$ cd beinc_installation -$ source bin/activate -$ pip install Twisted -$ pip install pyopenssl -$ cd beinc- -$ ./beinc_server.py -h - - -Installing and setting up BEINC -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unpack the latest version of BEINC -$ tar zxvf beinc-.tar.gz - -$cd beinc- -Read the README file - -You should now have a basic understanding about the different BEINC components -and how they interact with each other. -beinc_server.py and beinc_weechat.py are using a .json configuration file. -Read beinc_config_sample.json.readme where every configuration option is explined. -Decide on a use-strategy and place the different components to their locations: - -beinc_server.py: -Create a configuration file based on beinc_config_sample.json, defining your instances -Start the BEINC server: -$ ./beinc_server.py -H 10.0.0.44 -p 9678 -The example loads the server listening on 10.0.0.44, port 9678 using the default -~/.beinc_server.json as a configuration file and usually gives you the Twisted -log console - -beinc_poller.py: -$ ./beinc_poller.py -h -The example lists all available command options -$ ./beinc_poller.py -n weechat -t 10 -f 7 --cert-file /home/sgs/weechat_cert.crt \ - -p /home/sgs/.weechat_beinc_passwd https://10.0.0.44:9678 -Starts polling from the instance (target) defined above, -defining an OSD timeout of 10 seconds, polling frequency of 7 seconds, -checking whether the server's SSL certificate was signed (issued) by /home/sgs/weechat_cert.crt, -extracting the target's password from /home/sgs/.weechat_beinc_passwd - -beinc_generic_client.py: -$ ./beinc_generic_client.py -h -The example lists all available command options - -beinc_weechat.py: -Create a configuration file based on beinc_config_sample.json, defining your targets -and copy it (or symlink it) to ~//beinc_weechat.json -(weechat-dir is usually ~/.weechat) -Copy (or symlink) beinc_weechat.py to ~//python/autoload/ -Load the script in Weechat by typing: /python load beinc_weechat.py -Make sure that all your targets look as they should: /beinc target list -Test if your targets are displaying / relaying your messages: /beinc broadcast Test diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..b0e8a0a --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,83 @@ +## Installation Instructions + +Refer to README for a basic information about the different BEINC components +and their software requirements! + + +### Installing the dependencies + +#### Gentoo GNU/Linux 2014, 2015 + +# emerge -va dev-python/pyopenssl dev-python/notify-python + + +#### Ubuntu GNU/Linux + +# apt-get install python-openssl python-notify2 + + +#### FreeBSD 10, 11 + +# cd /usr/ports/security/py-openssl +# make install clean + +# cd /usr/ports/devel/py-notify +# make install clean + + +#### Intallation using virtualenv and pip + +Very often you are not the administrator of the server hosting your BEINC server +This is where virtualenv may become handy (provided that it has been installed): +$ virtualenv beinc_installation +$ cd beinc_installation +$ source bin/activate +$ pip install pyopenssl +$ cd beinc- +$ ./beinc_server.py -h + + +### Installing and setting up BEINC + +Unpack the latest version of BEINC +$ tar zxvf beinc-.tar.gz + +$cd beinc- +Read the README file + +You should now have a basic understanding about the different BEINC components +and how they interact with each other. +beinc_server.py and beinc_weechat.py are using a .json configuration file. +Read beinc_config_sample.json.readme where every configuration option is explined. +Decide on a use-strategy and place the different components to their locations: + +beinc_server.py: +Create a configuration file based on beinc_config_sample.json, defining your instances +Start the BEINC server: +$ ./beinc_server.py -H 10.0.0.44 -p 9678 +The example loads the server listening on 10.0.0.44, port 9678 using the default +~/.beinc_server.json as a configuration file and usually gives you the Twisted +log console + +beinc_poller.py: +$ ./beinc_poller.py -h +The example lists all available command options +$ ./beinc_poller.py -n weechat -t 10 -f 7 --cert-file /home/sgs/weechat_cert.crt \ + -p /home/sgs/.weechat_beinc_passwd https://10.0.0.44:9678 +Starts polling from the instance (target) defined above, +defining an OSD timeout of 10 seconds, polling frequency of 7 seconds, +checking whether the server's SSL certificate was signed (issued) by /home/sgs/weechat_cert.crt, +extracting the target's password from /home/sgs/.weechat_beinc_passwd + +beinc_generic_client.py: +$ ./beinc_generic_client.py -h +The example lists all available command options + +beinc_weechat.py: +Create a configuration file based on beinc_config_sample.json, defining your targets +and copy it (or symlink it) to ~//beinc_weechat.json +(weechat-dir is usually ~/.weechat) +Copy (or symlink) beinc_weechat.py to ~//python/autoload/ +Load the script in Weechat by typing: /python load beinc_weechat.py +Make sure that all your targets look as they should: /beinc target list +Test if your targets are displaying / relaying your messages: /beinc broadcast Test diff --git a/README b/README deleted file mode 100644 index f2bf0d5..0000000 --- a/README +++ /dev/null @@ -1,122 +0,0 @@ -Copyright (C) 2014-2018 - Simeon Simeonov -See the end of the file for license conditions. - - -What is BEINC? --------------- - -Blackmore's Enchanced IRC Notification Collection (BEINC) is a free set of -components that aims to provide a complete system for different -on-screen-display notification scenarios. - -The current version of BEINC contains the following components: -beinc_server.py - server used for queueing or providing on-screen-display (OSD) -beinc_poller.py - client used to fetch enqueued messages from beinc_server.py - and provide OSD -beinc_weechat.py - a complete script / client for the Weechat IRC client >=0.4.0 - used to push notification messages to beinc_server.py -beinc_generic_client.py - a simple client used to push notification messages - to beinc_server.py - Its main purpose is to provide a convenient way to - test beinc_server.py (and beinc_poller.py) as well as - to serve as an example for how to develop BEINC-clients -+ documentation and a sample configuration file (beinc_config_sample.json) - - -Why should I use BEINC and what has it done for me lately? ----------------------------------------------------------- - -BEINC is a free-software, licensed under the GPL3. It gives you the freedoms -of using it, studying it and modifying it. - -BEINC is designed to assist you two common scenarios. -As an example we will consider the case of an IRC cliet, although BEINC can be -used by any client that conforms with BEINC's "messaging protocol". - -We have the common situation where a user is accessing an IRC client located on -a different computer (typically: weechat, irssi, etc. running on a remote server) -The IRC client receives a private message (or any event that requires the user's -attention) and the user has to be notified. -No matter which of the two scenarios applies to your needs, you should start by - - setting up a BEINC client similar to beinc_generic_client.py on the server - If you are running weechat >=0.4.0, this version of BEINC comes with - a complete weechat BEINC-client: beinc_weechat.py - Configure the client to send notifications to the beinc_server.py -N.B. Using encryption is important in these days and age. - -Scenario one: -The user's computer can be reached by the server running the IRC client. -If the server (running the IRC client) is able to connect to -a specified TCP port on the user's computer, this is sufficient for BEINC to -directly notify the user. Solution: - - set up the beinc_server.py on the desktop workstation (the computer where the - notification-message should be displayed). Define an unprivileged port for - beinc_server.py to listen on and enable its OSD capabilities - (through pynotify) - -Scenario two: -The user's computer can NOT be reached by the server running the IRC client. -This scenario is typical for users that are working on computers that can not -be reached from outside. -Solution: - - find a server that can be reached by the server running the IRC client. - - set up the beinc_server.py on it. No OSD capabilities are needed (no X11). - Define instance(s) for queueing. Define a queue size - (how many notifications to store) for each of them. - - set up beinc_poller.py on the desktop workstation (the computer where the - notification-message should be displayed). - beinc_poller.py should be able to access the server running beinc_server.py - Polling interval of 5 seconds should be enough for most users. - -Read beinc_config_sample.json.readme for details on how to setup -beinc_server.py and beinc_weechat.py! -Use "-h" command line parameter to display the available options for -beinc_poller.py and beinc_generic_client.py -Each configured beinc_server.py instance has an unique name. -There are 2 operations that can be done on an instance: - - push - a client is sending a notification to the BEINC server. - A push is available for all instances. - - pull - a poller (f.i. beinc_poller.py) is fetching data from the instance-queue. - A pull is available only for instances defined for queueing. - (read beinc_config_sample.json.readme for details!) -Example: -If you defined a beinc_server.py instance with SSL-support, -your URL will be: https://hostname:port - - -Supported systems & requirements --------------------------------- -Any system running the software required for the selected components. -All components tested on: Gentoo GNU/Linux 2014,2015, - Ubuntu GNU/Linux 14.4,14.10, - FreeBSD 10.x - - -Requirements: -All components: Python >= 2.7.9 or Python >= 3.4.* - -beinc_server.py: pynotify >= 0.1 (optional) -beinc_weechat.py: Weechat >= 0.4.0 -beinc_poller.py: pynotify >= 0.1 -beinc_generic_client.py: No additional software required - -Read INSTALL in this very same folder for more details about installing the requirements! - - -License -------- - -This file is part of BEINC. - -BEINC is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see diff --git a/README.md b/README.md new file mode 100644 index 0000000..c6722aa --- /dev/null +++ b/README.md @@ -0,0 +1,124 @@ +Copyright (C) 2014-2018 - Simeon Simeonov +See the end of the file for license conditions. + + +## What is BEINC? + +Blackmore's Enchanced IRC Notification Collection (BEINC) is a free set of +components that aims to provide a complete system for different +on-screen-display notification scenarios. + +The current version of BEINC contains the following components: +beinc_server.py - server used for queueing or providing on-screen-display (OSD) +beinc_poller.py - client used to fetch enqueued messages from beinc_server.py + and provide OSD +beinc_weechat.py - a complete script / client for the Weechat IRC client >=0.4.0 + used to push notification messages to beinc_server.py +beinc_generic_client.py - a simple client used to push notification messages + to beinc_server.py + Its main purpose is to provide a convenient way to + test beinc_server.py (and beinc_poller.py) as well as + to serve as an example for how to develop BEINC-clients ++ documentation and a sample configuration file (beinc_config_sample.json) + + +## Why should I use BEINC and what has it done for me lately? + +BEINC is a free-software, licensed under the GPL3. It gives you the freedoms +of using it, studying it and modifying it. + +BEINC is designed to assist you two common scenarios. +As an example we will consider the case of an IRC cliet, although BEINC can be +used by any client that conforms with BEINC's "messaging protocol". + +We have the common situation where a user is accessing an IRC client located on +a different computer (typically: weechat, irssi, etc. running on a remote server) +The IRC client receives a private message (or any event that requires the user's +attention) and the user has to be notified. +No matter which of the two scenarios applies to your needs, you should start by + - setting up a BEINC client similar to beinc_generic_client.py on the server + If you are running weechat >=0.4.0, this version of BEINC comes with + a complete weechat BEINC-client: beinc_weechat.py + Configure the client to send notifications to the beinc_server.py +N.B. Using encryption is important in these days and age. + + +### Scenario one + +The user's computer can be reached by the server running the IRC client. +If the server (running the IRC client) is able to connect to +a specified TCP port on the user's computer, this is sufficient for BEINC to +directly notify the user. Solution: + - set up the beinc_server.py on the desktop workstation (the computer where the + notification-message should be displayed). Define an unprivileged port for + beinc_server.py to listen on and enable its OSD capabilities + (through pynotify) + + +### Scenario two + +The user's computer can NOT be reached by the server running the IRC client. +This scenario is typical for users that are working on computers that can not +be reached from outside. + +Solution: + - find a server that can be reached by the server running the IRC client. + - set up the beinc_server.py on it. No OSD capabilities are needed (no X11). + Define instance(s) for queueing. Define a queue size + (how many notifications to store) for each of them. + - set up beinc_poller.py on the desktop workstation (the computer where the + notification-message should be displayed). + beinc_poller.py should be able to access the server running beinc_server.py + Polling interval of 5 seconds should be enough for most users. + +Read beinc_config_sample.json.readme for details on how to setup +beinc_server.py and beinc_weechat.py! +Use "-h" command line parameter to display the available options for +beinc_poller.py and beinc_generic_client.py +Each configured beinc_server.py instance has an unique name. +There are 2 operations that can be done on an instance: + - push - a client is sending a notification to the BEINC server. + A push is available for all instances. + - pull - a poller (f.i. beinc_poller.py) is fetching data from the instance-queue. + A pull is available only for instances defined for queueing. + (read beinc_config_sample.json.readme for details!) +Example: +If you defined a beinc_server.py instance with SSL-support, +your URL will be: https://hostname:port + + +## Supported systems & requirements + +Any system running the software required for the selected components. +All components tested on: Gentoo GNU/Linux 2014,2015, + Ubuntu GNU/Linux 14.4,14.10, + FreeBSD 10.x + + +### Requirements +All components: Python >= 2.7.9 or Python >= 3.4.* + +beinc_server.py: pynotify >= 0.1 (optional) +beinc_weechat.py: Weechat >= 0.4.0 +beinc_poller.py: pynotify >= 0.1 +beinc_generic_client.py: No additional software required + +Read INSTALL in this very same folder for more details about installing the requirements! + + +### License + +This file is part of BEINC. + +BEINC is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see diff --git a/beinc_config_sample.json b/beinc_config_sample.json index 4384555..3b04c0b 100644 --- a/beinc_config_sample.json +++ b/beinc_config_sample.json @@ -16,18 +16,6 @@ { "name": "instance2", "password": "changeme", - "osd_system": "pyosd", - "osd_timeout": 6, - "pyosd_font": "-adobe-courier-bold-o-normal--24-240-75-75-m-150-iso8859-1", - "pyosd_vertical_offset": 120, - "pyosd_horizontal_offset": 30, - "pyosd_align": "left", - "pyosd_position": "top", - "pyosd_color": "blue" - }, - { - "name": "instance3", - "password": "changeme", "osd_system": "none", "osd_timeout": 5, "queue_size": 4 diff --git a/beinc_config_sample.json.readme b/beinc_config_sample.json.readme index edf5845..1bc6b7f 100644 --- a/beinc_config_sample.json.readme +++ b/beinc_config_sample.json.readme @@ -30,8 +30,8 @@ documentation to better illustrate the comments. # Encryption method for the BEINC server # Possible values: - # "" or "auto" - Let Twisted decide (use the newest possible method) - # "SSLv3" - SSLv3 (weak) + # "" or "auto" - Let the server decide + # (use the newest possible method) # "TLSv1" - TLSv1.0 # "TLSv1_1" - TLSv1.1 # "TLSv1_2" - TLSv1.2 (most secure, but requires OpenSSL >= 1.0.1e) @@ -52,37 +52,12 @@ documentation to better illustrate the comments. # Possible values: # "none" - the instance will serve for queueing # "pynotify" - OSD implemented using pynotify (libnotify) - # "pyosd" - OSD implemented using pyosd (xosd) "osd_system": "pynotify", # OSD timeout in seconds # The amount of time the OSD message will remain in the screen "osd_timeout": 5, - # Specify a custom font for the pyosd - backend - # "xfontsel" can be used to obtain a list of available fonts - "pyosd_font": "", - - # Vertical offset (in pixels) for the pyosd - backend - "pyosd_vertical_offset": 120, - - # Horizontal offset (in pixels) for the pyosd - backend - "pyosd_horizontal_offset": 30, - - # Text horizontal alignment for the pyosd - backend - # Possible values: - # "left", "center", "right" - "pyosd_align": "left", - - # Text vertical position for the pyosd - backend - # Possible values: - # "top", "middle", "bottom" - "pyosd_position": "bottom", - - # Font color for the pyosd - backend - # See "rgb.txt" in the X11 distribution of a list of colors - "pyosd_color": "blue", - # How many entries to be kept in the queue # (when "osd_system": "none") "queue_size": 4 @@ -123,13 +98,12 @@ documentation to better illustrate the comments. "ssl_ciphers": "ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384", # Don't check whether the target's hostname matches the server's - # certificate. (Only for Python >= 2.7.9) + # certificate. # Default: 0 "disable-hostname-check": 0, # Force the client to use a specified SSL/TLS version - # Valid values: "auto", "SSLv3", "TLSv1", "TLSv1_1", "TLSv1_2" - # N.B. "TLSv1_1" and "TLSv1_2" only available in Python >= 2.7.9 + # Valid values: "auto", "TLSv1", "TLSv1_1", "TLSv1_2" # Default: "auto" (Let's OpenSSL select the best option) "ssl_version": "auto", -- cgit v1.3