From 901e03f39fca82ba054e9554f61f3c646c0c4962 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nguy=E1=BB=85n=20Gia=20Phong?= Date: Tue, 8 Sep 2020 22:58:35 +0700 Subject: [PATCH] [docs] Move caching and security notes from README --- README.md | 65 ----------------------------------- docs/source/caching.rst | 37 ++++++++++++++++++++ docs/source/index.rst | 2 ++ docs/source/security.rst | 27 +++++++++++++++ docs/source/usage-awesome.rst | 2 +- 5 files changed, 67 insertions(+), 66 deletions(-) create mode 100644 docs/source/caching.rst create mode 100644 docs/source/security.rst diff --git a/README.md b/README.md index c1ea57c..587c916 100644 --- a/README.md +++ b/README.md @@ -466,71 +466,6 @@ vicious.register. Your function can accept `format` and `warg` arguments, just like workers. -## Power and Caching - -When a lot of widgets are in use they, and awesome, can generate a lot -of wake-ups and also be very expensive for system resources. This is -especially important when running on battery power. It was a big -problem with awesome v2 and widgets that used shell scripts to gather -data, and with widget libraries written in languages like Ruby. - -Lua is an extremely fast and efficient programming language, and -Vicious takes advantage of that. But suspending Vicious widgets is one -way to prevent them from draining your battery, despite that. - -Update intervals also play a big role, and you can save a lot of power -with a smart approach. Don't use intervals like: 5, 10, 30, 60, … to -avoid harmonics. If you take the 60-second mark as an example, all of -your widgets would be executed at that point. Instead think about -using only prime numbers, in that case you will have only a few -widgets executed at any given time interval. When choosing intervals -also consider what a widget actually does. Some widget types read -files that reside in memory, others call external utilities and some, -like the mbox widget, read big files. - -Vicious can also cache values returned by widget types. Caching -enables you to have multiple widgets using the same widget type. With -caching its worker function gets executed only once - which is also -great for saving power. - -* Some widget types keep internal data and if you call one multiple times - without caching, the widget that executes it first would modify stored - values. This can lead to problems and give you inconsistent data. Remember - it for widget types like CPU and Network usage, which compare the old set of - data with the new one to calculate current usage. - -* Widget types that require a widget argument to be passed should be handled - carefully. If you are requesting information for different devices then - caching should not be used, because you could get inconsistent data. - - -## Security - -At the moment only one widget type (Gmail) requires auth. information -in order to get to the data. In the future there could be more, and -you should give some thought to the issue of protecting your data. The -Gmail widget type by default stores login information in the ~/.netrc -file, and you are advised to make sure that file is only readable by -the owner. Other than that we can not force all users to conform to -one standard, one way of keeping it secure, like in some keyring. - -First let's clear why we simply don't encrypt the login information -and store it in ciphertext. By exposing the algorithm anyone can -reverse the encryption steps. Some claim even that's better than -plaintext but it's just security trough obscurity. - -Here are some ideas actually worth your time. Users that have KDE (or -parts of it) installed could store their login information into the -Kwallet service and request it via DBus from the widget type. It can -be done with tools like `dbus-send` and `qdbus`. The Gnome keyring -should support the same, so those with parts of Gnome installed could -use that keyring. - -Users of GnuPG (and its agent) could consider encrypting the netrc -file with their GPG key. Trough the GPG Passphrase Agent they could -then decrypt the file transparently while their session is active. - - ## Usage examples Start with a simple widget, like `date`. Then build your setup from diff --git a/docs/source/caching.rst b/docs/source/caching.rst new file mode 100644 index 0000000..5efec11 --- /dev/null +++ b/docs/source/caching.rst @@ -0,0 +1,37 @@ +.. _caching: + +Power and Caching +================= + +When a lot of widgets are in use they, and awesome, can generate a lot +of wake-ups and also be very expensive for system resources. This is +especially important when running on battery power. It was a big problem +with awesome v2 and widgets that used shell scripts to gather data, +and with widget libraries written in languages like Ruby. + +Lua is an extremely fast and efficient programming language, and Vicious +takes advantage of that. But suspending Vicious widgets is one way +to prevent them from draining your battery, despite that. + +Update intervals also play a big role, and you can save a lot of power +with a smart approach. Don't use intervals like: 5, 10, 30, 60, etc. +to avoid harmonics. If you take the 60-second mark as an example, +all of your widgets would be executed at that point. Instead think about +using only prime numbers, in that case you will have only a few widgets +executed at any given time interval. When choosing intervals also consider +what a widget actually does. Some widget types read files that reside +in memory, others call external utilities and some, like the mbox widget, +read big files. + +Vicious can also cache values returned by widget types. Caching enables you +to have multiple widgets using the same widget type. With caching its worker +function gets executed only once---which is also great for saving power. + +* Some widget types keep internal data and if you call one multiple times + without caching, the widget that executes it first would modify stored values. + This can lead to problems and give you inconsistent data. Remember it + for widget types like CPU and Network usage, which compare the old set + of data with the new one to calculate current usage. +* Widget types that require a widget argument to be passed should be + handled carefully. If you are requesting information for different devices + then caching should not be used, because you could get inconsistent data. diff --git a/docs/source/index.rst b/docs/source/index.rst index f7562f5..d7a69e3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,6 +20,8 @@ Table of Contents usage-lua usage-awesome + caching + security copying See Also diff --git a/docs/source/security.rst b/docs/source/security.rst new file mode 100644 index 0000000..ceb6935 --- /dev/null +++ b/docs/source/security.rst @@ -0,0 +1,27 @@ +Security Notes +============== + +At the moment only one widget type (Gmail) requires +authentication information in order to get to the data. +In the future there could be more, and you should give some thought +to the issue of protecting your data. The Gmail widget type by default +stores login information in the ``~/.netrc`` file, and you are advised +to make sure that file is only readable by the owner. Other than that +we can not force all users to conform to one standard, +one way of keeping it secure, like in some keyring. + +First let's clear why we simply don't encrypt the login information +and store it in ciphertext. By exposing the algorithm anyone can +reverse the encryption steps. Some claim even that's better than +plaintext but it's just security through obscurity. + +Here are some ideas actually worth your time. Users that have KDE +(or parts of it) installed could store their login information into +the Kwallet service and request it via DBus from the widget type. +It can be done with tools like ``dbus-send`` and ``qdbus``. +The Gnome keyring should support the same, so those with parts of Gnome +installed could use that keyring. + +Users of GnuPG (and its agent) could consider encrypting the netrc file +with their GPG key. Through the GPG Passphrase Agent they could then +decrypt the file transparently while their session is active. diff --git a/docs/source/usage-awesome.rst b/docs/source/usage-awesome.rst index aa45071..e97ec5c 100644 --- a/docs/source/usage-awesome.rst +++ b/docs/source/usage-awesome.rst @@ -46,7 +46,7 @@ Once you create a widget (a textbox, graph or a progressbar) call ``interval`` Number of seconds between updates of the widget (default: 2). - Read section [Power and Caching](#power) for more information. + Read section :ref:`caching` for more information. ``warg`` Arguments to be passed to widget types, e.g. the battery ID.