improve documentation

gcontini

2020-03-22 d5c62b2bf602374febf5f4cc8c3d47a23f80ab27

improve documentation

 .travis.yml

@@ -210,7 +210,7 @@
             - doxygen
             - graphviz
     before_script: 
        - pip3 install setuptools sphinx sphinx_rtd_theme breathe sphinx-markdown-tables recommonmark sphinx-rtd-theme sphinx-sitemap
        - pip3 install setuptools sphinx sphinx_rtd_theme breathe sphinx-markdown-tables recommonmark sphinx-rtd-theme sphinx-sitemap sphinxemoji
        - cd build && cmake -DCMAKE_INSTALL_PREFIX=../../install ..
     script:
        - make documentation

 README.md

@@ -30,7 +30,8 @@
-   a license generator (github project [lcc-license-generator](https://github.com/open-license-manager/lcc-license-generator)) `lcc` for customizing the library and generate the licenses.
 
## How to build
Below an overview of the basic build procedure, you can find detailed instructions for [linux](https://github.com/open-license-manager/open-license-manager/wiki/Build-the-library) or [windows](https://github.com/open-license-manager/open-license-manager/wiki/Build-the-library-windows) in the wiki. 
Below an overview of the basic build procedure, you can find detailed instructions for [linux](http://open-license-manager.github.io/open-license-manager/development/Build-the-library.html) 
or [windows](http://open-license-manager.github.io/open-license-manager/development/Build-the-library-windows.html) in the project web site. 

### Prerequisites
-   Operating system: Linux(Ubuntu, CentOS), Windows
@@ -91,5 +92,8 @@

## How to contribute

The easiest way you can solve your problems or ask help is through the [forum](https://groups.google.com/forum/#!forum/licensecc), otherwise if you think there is a problem you can open an issue in the [issue system](https://github.com/open-license-manager/open-license-manager/issues). Have a look to the [contribution guidelines](CONTRIBUTING.md) before reporting.
We use [GitFlow](https://datasift.github.io/gitflow/IntroducingGitFlow.html) (or at least a subset of it). Remember to install the gitflow git plugin and use `develop` as default branch for your pull requests. 
The easiest way you can solve your problems or ask help is through the [forum](https://groups.google.com/forum/#!forum/licensecc) (hosted on Google), 
otherwise if you think there is a problem you can open an issue in the [issue system](https://github.com/open-license-manager/open-license-manager/issues). 
Have a look to the [contribution guidelines](CONTRIBUTING.md) before reporting.
We use [GitFlow](https://datasift.github.io/gitflow/IntroducingGitFlow.html) (or at least a subset of it). 
Remember to install the gitflow git plugin and use `develop` as default branch for your pull requests. 

 cmake/Findlccgen.cmake

 doc/analysis/features.md

File was deleted

 doc/analysis/features.rst

New file
@@ -0,0 +1,129 @@
###########
Features
###########

features and their status
****************************

======================================  ========================
 Feature                                 Implementation status    
======================================  ========================
Trial license with expiry date          |:heavy_check_mark:|  
Link software to "physical" hardware    |:heavy_check_mark:|  
Virtual machine detection               In progress           
Easy license retrieval                  |:heavy_check_mark:|   
Manage licenses                         Planned               
Easy Customizable limits                Planned               
Java/C# bindings                        Planned               
Floating/network licenses               Planned               
======================================  ========================

Issue a "demo" license with only expiry date.
==============================================
Software editors often want to release a trial license that is not linked to a specified machine, but just limit the usage in time or to some other feature (number of cpu, process memory).
See :ref:`execution limits <Execution limits>` section.

Licenses linked to "physical" hardware id
===========================================
Link the software to a physical hardware (a pc). In this scenario the software editor wants his software to be executed on a specific piece of hardware. We suppose the operating system is installed "bare to metal" and we're able to calculate an identifier of that hardware. This isn't always true for virtualized environments for which alternative strategies must be planned [eg. floating licenses (not yet implemented)]. See the section on [hardware identifiers](../usage/Hardware-identifiers) for a detailed discussion of the use cases.

Depending on the situation there are are different kinds of hardware id that can be used. See :ref:`execution limits <Execution limits>` section.

Virtual machine detection (in progress)
==========================================
Detect if the software is running in a virtualized environment and (optionally) forbid the execution. This is useful if software editors want to prevent the execution in virtual machines (lxc/dockers...) and be able to compute a meaningful hardware id. 
Another use case is the software is to be used only in a specific class of virtualized environments. For instance it was initially packaged as a docker image, the software editor don't want it to be "extracted" and placed elsewhere.

Licenses retrieval
=======================
Open License Manager, when integrated into a licensed software will find its license file based on many different strategies.
It can handle multiple licenses at the same time. See the wiki page about :ref:`license retrieval <usage/License-retrieval:License retrieval>` for details.
 
Licensed software features (partially implemented)
=========================================================
A licensed software may be composed by many features (functions) each one activable independently. Licensing system tells the licensed software which features are enabled, and which features are disabled.
 
License Management (planned)
==================================
It is necessary to keep track of the licenses that have been issued, of the clients, and their hardware identifier. 
A web application is planned that will provide integration with payment systems to allow licensed software customers to buy licenses.

Customizable execution limits (planned)
==========================================
It should be easy to add and implement your own "execution limit": that is require/forbid some feature in the application execution environment.

Java/C# bindings (planned)
============================
The application should support bindings to java language. The library has to be compiled as a .dll for use with JNI or C# integration layer. This is especially challenging on the api side.
Since the api is public, and the library is packaged as a separate .dll/.so everybody can compile a version of it always returning LICENSE_OK easily defeating the license schema. 

Floating licenses (planned)
===============================
Limit the execution of the licensed software to a certain number of instances per license. 
This can be done in multiple ways:
* without a central server, using broadcast or scanning the local network to find peers.
* with a central server installed in the client's network. 
* with a central server on internet.
Status of this implementation is tracked in `issue #4 <https://github.com/open-license-manager/open-license-manager/issues/4>`_

.. _Execution Limits:

Implemented/Planned Execution limits
*************************************

Open License Manager can limit execution of licensed software based on some criteria, called "execution limits".
Depending on the execution environment some criteria may not be applicable:

=============================== ==================== ====================  ============================== ==================== 
feature |:arrow_down:| system->  | Windows            | Linux               | Linux container              Virtual Machine
                                 | BareToMetal        | BareToMetal         | (lxc/docker)   
=============================== ==================== ====================  ============================== ==================== 
date                            |:heavy_check_mark:| |:heavy_check_mark:|  |:heavy_check_mark:|           |:heavy_check_mark:|
disk label                      |:heavy_check_mark:| |:heavy_check_mark:|  |:x:|\ :sup:`1`                |:heavy_check_mark:|
disk id                         |:heavy_check_mark:| |:heavy_check_mark:|  |:x:|\ :sup:`1`                |:heavy_check_mark:|
ip address                      |:heavy_check_mark:| |:heavy_check_mark:|  |:interrobang:|\ :sup:`2`      |:heavy_check_mark:|
mac address                     |:heavy_check_mark:| |:heavy_check_mark:|  |:interrobang:|\ :sup:`2`      |:heavy_check_mark:|
cpu number                      Planned              Planned               Planned                        Planned
process memory                  Planned              Planned               Planned                        Planned
machine memory                  Planned              Planned               Planned                        Planned
virtualization type             Planned              Planned               Planned                        Planned
concurrent execution            Planned              Planned               Planned                        Planned
licensed sw version             Planned              Planned               Planned                        Planned
=============================== ==================== ====================  ============================== ==================== 

Date
=========
This is the most common limit set on a license, allow the software to expire after the defined date.

Disk label/Disk id
==============================
It is possible to limit the execution to a computer that has a certain disk connected. 
This feature has been implemented in ``hardware identifier``. 

N.B.\ :sup:`1` This kind of limitation doesn't make sense in containerized environments. For an extensive discussion see the 
:ref:`hardware identifiers <usage/Hardware-identifiers:Hardware Identifiers>` section. 

Ip address/Mac address
=======================
It is possible to limit the execution to a computer that has a network card with a spefified MAC address 
(or even we can force to have a specific ip address). 
This feature has been implemented in ``hardware identifier``. 

N.B.\ :sup:`2` This kind of limitation,though it is supported, may not make sense in most of containerized environments. 
For an extensive discussion see the :ref:`hardware identifiers <usage/Hardware-identifiers:Hardware Identifiers>` section.

Cpu Number/Machine memory
===============================
Allow to restrict the execution only to a machine with the specified amount of cpu or memory or less. 
This is useful in virtualized environments, to create a licensed software demo version with limited performaces or with limited scalability.
Status of this implementation is tracked in `issue #3 <https://github.com/open-license-manager/open-license-manager/issues/3>`_

Virtualization type
==========================
Allow the execution of the licensed software only on some type of hardware or virtualized environment 
eg. only bare to metal, only in virtual machine, only in docker.
This feature is being implemented. 

Licensed software version
===========================
A licensed software may declare a version (eg 1.0.0). A license may span multiple releases of the software e.g. allow version 1.1.1 but not 2.0.0.

 doc/api/extend.rst

@@ -1,10 +1,10 @@
#######################################
Customizations
Extension points
#######################################

The version 2.0 of the library comes with clear API extension and customization points. 

Custom hardware signature generator
Tweak hardware signature generator
***************************************

You've found the provided hardware signatures don't behave well for your customers (we can test on a limited set of 

 doc/api/hardware_identifiers.rst

@@ -1,5 +1,5 @@
###############################################
Implement your own hardware signature generator 
Customize hardware signature generators 
###############################################

Customize how default strategy behaves

 doc/conf.py

@@ -33,7 +33,7 @@
# ones.
extensions = ['sphinx.ext.todo',
    'sphinx.ext.githubpages', 'breathe', 'recommonmark', 'sphinx_markdown_tables', 'sphinx_rtd_theme',
    'sphinx_sitemap','sphinx.ext.autosectionlabel' ]
    'sphinxemoji.sphinxemoji', 'sphinx_sitemap','sphinx.ext.autosectionlabel' ]

autosectionlabel_prefix_document = True

@@ -186,5 +186,7 @@
# Sitemap plugin
html_baseurl = 'http://open-license-manager.github.io/open-license-manager'

sphinxemoji_style = 'twemoji'

#html_logo = "_static/lock_32.png"
html_favicon="_static/lock_32.ico"

 doc/index.rst

@@ -24,7 +24,7 @@

Protect the software you develop from unauthorized copies, limit the usage in time, to a specific set of 
machines, or prevent the usage in  virtualized environments. It is an open source license management system that helps to keep your 
software closed :smirk: . Among the other features the most notable one is: if it runs on a "real hardware" 
software closed |:smirk:| . Among the other features the most notable one is: if it runs on a "real hardware" 
it can generate a signature of that hardware and report if the signature doesn't match, because for instance 
the software has been copied to another pc.

@@ -60,8 +60,11 @@
* tools            : Cmake(>3.6), git, make/ninja(linux)
* libraries        : If target is Linux Openssl is required. Windows depends only on system libraries. Boost is necessary to build license generator and to run the tests but it's NOT a dependency of the final `licensecc` library. 

For a complete list of dependencies and supported environments see the :ref:`development/Dependencies:Dependencies` section.
Clone the project. It has submodules, don't forget the `--recursive` option.
For a complete list of dependencies and supported environments see the :ref:`dependencies <development/Dependencies:Dependencies>` section.
Clone the project. 

.. NOTE::
  It has submodules, don't forget the `--recursive` option.

.. code-block:: console