0.2

docs/administrators-guide/authentication.md

@@ -1,2 +1,42 @@
-!!! warning "TODO"
-    This section is not complete
+!!! success "Key note"
+    To obtain configuration from node, cBackup must go through authentication process, therefore we use combination of **credentials** and **authentication templates**.
+
+# Credentials
+
+Credential management is available via menu `Inventory -> Credentials`. Credentials is a named set of authentication data (logins, passwords, protocols, port numbers, etc) that is used in authentication processes. Credentials set can be assigned to any number of subnets and will be used in numerous cBackup processes.
+
+### Tips and features
+
+* You can hide/unhide passwords by clicking on the checkbox. No excessive fields for _"please repeat password again'_, but check your passwords twice.
+* You can save credentials set and test it against certain IP-address. Fill the form on the right side and check if credentials are valid. 
+    *  This form automatically adjusts depending on the set of credentials you've defined. E.g. if you didn't save _Telnet_ credentials, no telnet test will be performed. On the other hand, if you save _Telnet_ credentials, then you will be prompted to enter not only IP address, but also _Telnet username and password prompts_.
+    * Later, if you are planning to use Telnet for communicating with your devices, you will have to define username and password prompts in [authentication sequences](authentication#authentication-templates)
+* Test for _SNMP write_ is safe, no real OIDs are involved. We're trying to write to read-only OID, catching error code. Check the [source of CredentialTest.php](https://github.com/cBackup/core/blob/master/models/CredentialTest.php) if you have any doubts.
+
+### SNMP
+
+SNMP protocol is used in discovery process - i.e. in finding new nodes and gathering such information as sys.name, sys.location, sys.contact, network interfaces and so on. At this moment only SNMP v1 and v2/v2c are supported, 3d version is coming in next major release. Also you can use SNMP protocol for saving configuration or for any other custom tasks, in this case most likely you'll need to store _snmp set community_, otherwise it's enough to store _readonly community_.
+
+### Telnet and SSH
+
+Telnet and SSH protocols are used in obtaining text configuration data from nodes. Also you can use these protocols for custom tasks, defining commands to send to the node.
+
+------------
+
+# Authentication templates
+
+![Auth template in a nutshell](../assets/auth5.png)
+
+Authentication templates are located under `Inventory -> Device auth templates` menu. Authentication template is a named sequence of prompts and responses representing authentication sequence for communication via Telnet. Every template can be assigned to any existing [device](devices). There're several macros available (i.e. `{{telnet_login}}`, `{{telnet_password}}`, `{{enable_password}}`) representing corresponding data from predefined **credentials** (see above).
+
+!!! note
+     For communication via SSH all macros will be ignored and initial SSH login and password are retrieved from credentials directly. Rest of the sequence is still used to send privileged mode password if it's required.
+
+In all auth sequences on green fields there're command line prompts, and on the white fields - commands cBackup is sending to the node, trying to go through authentication process. Here are some authentication sequences:
+
+Description | Template
+------------ | -------------
+Cisco CLI with privileged mode password prompt (enable password). If your node wants SSH authentication, the `{{telnet*}}` macros will be ignored and the first active entry from sequence is the prompt | ![Cisco authentication with ena password](../assets/auth1.png) 
+Switch authentication sequence (Zyxel, D-Link). These switches primarily work via Telnet | ![Switch auth](../assets/auth2.png)
+MikroTik authentication sequence. Node works only via SSH, no telnet is involved, no privileged mode, therefore we wait only for CLI prompt | ![Mirotik auth](../assets/auth3.png)
+ZTE GPON OLT auth. Node works only via SSH, no telnet is involved, no privileged mode. As well as for MikroTik, all authentication entities (SSH login and password) are taken from **credentials set** (see chapter above) | ![ZTE auth](../assets/auth4.png)

docs/administrators-guide/devices.md

@@ -1,2 +1,35 @@
-!!! warning "TODO"
-    This section is not complete
+# Concept
+
+Device management is available via menu `Inventory -> Devices`. There're two entites to be managed in terms of 'devices': _vendors_ and _device list_. When cBackup discovers new device that is not yet defined, it will be shown in the list of _unknown devices_. Check the top of the device list ![No new devices](../assets/unknown-devices-0.png) if there are any unkonwn models found ![New unknown devices](../assets/unknown-devices-1.png)
+
+!!! cite "Notification"
+    Every node involved in cBackup task processing hase to be attached to corresponding device defined in the list, whether you discover it or add manually. Homogeneous network is easier to manage than heterogeneal, but device definition has to be done in any case - all devices must be recognized and ascribed.
+
+# Vendor management
+
+Vendors are represented by flat single-entity list of predefined vendor names. It can be used in factory methods in Java daemon, or more likely, used only for grouping device models classificator.
+
+# Device management
+
+Generally, device is described with three fields: vendor name, model and authentication template. Also for all auto discovered nodes additional attribute(-s) of System OID must be defined. These attributes describe SNMP root OID as main device identifier depending on hardware revision. Only for manually added nodes (i.e. nodes which don't go through discovery process) System OID can be empty.
+
+!!! note
+    Please note, if you add device manually, devices with the same model will be found during [discovery](discovery) process as unknown device and you will be prompted to define System OID attribute. At the same time, manually added node with manually created device will be skipped during discovery process and its' information won't be refreshed. 
+
+## Add discovered device
+
+If cBackup has discovered an unknown device, you will be notified in the widget on the top right corner near your username dropdown: 
+![Notification widget](../assets/device-1.png) 
+
+Or you can check the list of devices for the button ![New unknown devices](../assets/unknown-devices-1.png). Anyway, proceeding to the message you'll see the corresponding entry. You can truncate it by pressing <i class="fa fa-trash-o"></i>, or proceed with _recognizing_ it to the list by clicking on <i class="fa fa-plus-square"></i> to assign new System OID to a device
+![](../assets/device-2.png)
+
+Here you can assign found System OID property to any existing device by choosing it from dropdown select:
+![](../assets/device-3.png)
+
+...or to create a new device by clicking on <i class="fa fa-plus-square"></i>
+![](../assets/device-4.png)
+
+After you've added new System OID property to new or existing device, submitted data can be viewed in the grid:
+ ![](../assets/device-5.png)
+

docs/administrators-guide/mail.md

@@ -1,2 +1,21 @@
-!!! warning "TODO"
-    This section is not complete
+!!! cite
+    Scheduled mail reports can be configured in `Processes -> Mailer` menu. 
+
+**To define a mail template, follow these simple 4 steps:**
+
+1. Create named event
+2. Define recipients under ![](../assets/mail1.png) button. Simply list e-mail addresses.
+3. Edit mail message template under ![](../assets/mail2.png) button. 
+   1. Please note, that in the wysiwyg editor under ![](../assets/mail3.png) button there's a list of numerous variables that you can use in the template. Including but not limited: hdd utilization, node data, node or system logs of certain level.
+   2. By pressing <i class="fa fa-eye"></i> icon, you'll see the mail preview where all template variables will be replaced with actual data.
+4.  Send mail by pressing ![](../assets/mail4.png)
+
+**To schedule this mail:**
+
+1. Go to `Processes -> Schedules` to `Mailer schedules` tab.
+2. Choose created event from dropdown list and define time
+
+**To look through sent mails:**
+
+1. Go to `Processes -> Mailer -> Messages`
+2. Here is the list of sent mails with corresponding statuses. You can read it or resend if necessary. Logs under <i class="fa fa-undo"></i> icon are also available for each mail. 

docs/administrators-guide/plugins.md

@@ -0,0 +1,14 @@
+# Introduction
+
+Plugins are addons for cBackup, providing additional functionality in web interface. Our team is certain that _tool with a word 'backup' in its name must do backups_, therefore services aside from the primary one should be moved to separate packages.
+
+We do encourage development of plugins and created [the guide for developers](../developers-guide/plugins) with detailed step-by-step explanation for plugin creation process. Also you can always request help on [official forums](http://cbackup.me/forum). However, on official downloads page only cBackup approved plugins will be stored ex tunc.
+
+!!! warning
+    Plugins have access to the whole application namespace and database. Installing unapproved plugin from a third-party you do it at your own peril.   
+
+# Management
+
+In the menu `System -> Plugin manager` you can see list of plugins if there're any already installed in the system. Each plugin can have its own settings (click on plugin's name to manage its settings), each plugin can be deleted or disabled. Also you can check full plugin information in it's description `Plugin metadata`
+
+To install new plugin, go to the corresponding tab in `Plugin manager`. You want to browse for ZIP archive with plugin. The update is performed in the same way - simply upload new ZIP archive and all necessary procedures will be performed automatically.

docs/administrators-guide/plugins/geolocation.md

@@ -0,0 +1,14 @@
+!!! note "Info"
+    Geolocation plugin displays node location on Google map, depending on SNMP OID `system.SysLocation` and [system setting](../system-configuration/#system-settings) `Prepend location`
+
+When plugin is installed, new tab `Geo mapping` is being added next to configuration backup tab. When data is obtained from Google Maps API, tab will contain map with actual node location, node model and IP-address.
+
+As the name implies 'prepend location' prefix will be added before `system.SysLocation` OID data. If the vast majority of your nodes is located in one specific vicinity, you can define 'prepend location' in system configuration and this string will be prepended to every node's location. For all other nodes that require it - define prepend location data manually in the node editing interface. 
+
+![Geo map](../../assets/geo1.png)
+
+Also a new entry will appear in main menu as `Plugins -> Geo mapping`. There you'll see list of processed nodes with detailed information about geo coordinates, creation and modification time. If you need information about data retrieving process, click `View geolocation logs` on the top right side of the grid. Second button `Collect geolocations` initializes forced refresh of all geolocation data for all nodes. Also you can refresh each node data individually by clicking <i class="fa fa-refresh"></i> next to desired node.
+
+!!! warning
+    Currently there's no native way to schedule task for recurrent obtaining data from Google maps. This feature will be added in the upcoming major release. At this moment, use system cron adding `./yii plugins/geomapping/run/get-geolocation` command to be executed after discovery.
+

docs/administrators-guide/subnets.md

@@ -1,10 +1,11 @@
-!!! warning "TODO"
-    This section is not complete
-
 # Network management
 
-...
+Subnet management is available via menu `Inventory -> Subnets`. You can proceed with basic CRUD operations for subnets. All subnets have to be defined in CIDR format (e.g. 192.168.5.0/24). Every subnet should have default credentials attached. Credentials can be defined preliminary or created while you are editing/creating subnet (by pressing <i class="fa fa-plus-square"></i> near corresponding dropdown).
 
 # Exclusions
 
-At this moment there's no way to exclude subnet from a bigger network. You can exclude particular nodes or to split bigger network to smaller segments. 
+!!! note
+    You can exclude only end-point IP-addresses. At this moment there's no way to exclude subnet from a bigger network. You can exclude particular nodes or to split bigger network to smaller segments.
+
+!!! success "Note"
+    When IP-address is excluded, corresponding node is removed from all tasks.

docs/administrators-guide/system-messages.md

@@ -1,4 +1,4 @@
-!!! warning "TODO"
-    This section is not complete
+Most often log entries you'll see here are about new device model found during discovery process. It's a notification you need to take certain actions to add support for new devices. Also you can see system messages in the top right corner of the screen left to username dropdown.
 
-Most often log entries you'll see here are about new device model found during discovery process. It's a notification you need to take certain actions to add support for new devices. Also you can see system messages in the top right corner of the screen left to username dropdown.
+!!! note
+    After you've processed the message source, don't forget to _acknowledge_ it by pressing <i class="fa fa-check"></i> in the messages list. This will hide message from top widget.

docs/assets/cbackup.css

@@ -8,4 +8,54 @@
 
 #teminology-table ~ table div.warning {
     margin-bottom: 0;
+}
+
+.rst-content .cite,
+.rst-content .success {
+    padding: 12px;
+    line-height: 24px;
+    margin-bottom: 24px;
+}
+
+.rst-content .cite p:last-child,
+.rst-content .success p:last-child {
+    margin-bottom: 0;
+}
+
+.rst-content .cite .admonition-title:before,
+.rst-content .success .admonition-title:before {
+    content: '';
+    margin: 0;
+}
+
+.rst-content .cite { background: #eeeeee; }
+.rst-content .cite .admonition-title { background: #888888; }
+
+.rst-content .success { background: #dbfaf4; }
+.rst-content .success .admonition-title { background: #1abc9c; }
+
+.rst-content .success .admonition-title:before {
+    content: "";
+    margin-right: 4px;
+}
+
+.rst-content table.docutils img {
+    max-width: none;
+    height: 100% !important;
+}
+
+.rst-content li p ~ table.docutils {
+    margin-top: -12px;
+}
+
+.rst-content .section ul code {
+    line-height: 17px;
+}
+
+.rst-content .section ul p ~ pre {
+    margin-top: -12px;
+}
+
+.rst-content .section li pre {
+    margin-top: 0px;
 }

docs/developers-guide/apiv1.md

@@ -0,0 +1,56 @@
+!!! note "Description"
+    API v1 is RESTful API for Java daemon. Extend it only if you are adding new functionality to the daemon or modifying/fixing existing processes. Check the [flow scheme](../assets/rest_flow_2017-02-06.jpg) if Java is strong in you.
+
+* **Response format:** JSON
+* **Sessions:** none
+
+# Authentication
+
+* HttpBasicAuth<br>
+  Basic HTTP authentication, login and password are transferred as a string `login:password`<br><br>
+* HttpBearerAuth<br>
+  Token based authentication. To use it, you should pass bearer token in the HTTP header:
+
+        header('Authorization: Bearer USER_TOKEN');
+
+* QueryParamAuth<br>
+  Works in the same manner as HttpBearerAuth (i.e. identifies user with its token), but in this case token is passed as GET parameter
+
+        http://SITE_NAME/index.php?r=v1/core/ACTION_NAME&token=USER_TOKEN
+
+# Class hierarchy
+
+v1 module controllers can extend `yii\rest\ActiveController` or `yii\rest\Controller` depending on what is necessary. `ActiveController` allows us to manage certain model without redefining get-set methods (we're using Yii2 magic). If you need custom controller, extend `yii\rest\Controller` and do some manual labor.
+
+# REST request methods
+
+_Method_ | _Description_
+------------ | -------------
+GET | get data
+PUT | edit data
+DELETE | delete data
+POST | create data
+
+# REST response codes
+
+_Code | _Description_
+------------ | -------------
+200 | Success + DATA (GET SUCCESS, PUT SUCCESS)
+201 | Created + DATA (POST SUCCESS)
+204 | Operation success, but no responce + NO DATA (DELETE SUCCESS)
+404 | Not Found + NO DATA (GET, PUT, DELETE - NOT FOUND)
+422 | Unprocessable Entity + NO DATA (GET, PUT, POST VALIDATION FAILED OR REQUIRED PARAMETER MISSING OR EMPTY). It's not related to missing GET parameter - system will return 400.
+500 | Internal Server Error + NO DATA (GET, PUT, POST, DELETE - DB ERROR)
+
+# Test v1 API via CLI
+
+```bash
+// simple test, where -i tells to retrieve headers with data
+$ curl -i -H "Accept:application/json" "http://localhost/index.php?r=v1/core/isalive"
+
+// Simple call without headers
+curl -H "Accept:application/json" "http://localhost/index.php?r=v1/core/isalive" 
+
+// With authentication
+curl -i -H "Accept:application/json" --user admin:admin "http://localhost/index.php?r=v1/core/isalive" 
+```

docs/developers-guide/apiv2.md

@@ -0,0 +1,83 @@
+!!! note "Description"
+    API v2 is RESTful API for exporting data to embed it to the external services.
+
+# Available methods
+
+* **List nodes**
+
+        /index.php?r=v2/node/search
+        /index.php?r=v2/node/search&limit=1
+        /index.php?r=v2/node/search&offset=1
+        /index.php?r=v2/node/search&limit=1&offset=1
+
+* **Retrieve one node**
+
+        /index.php?r=v2/node/get&id=1
+
+# Examples
+
+**1. Search nodes by 'IN' or 'LIKE' criteria joined via 'AND' operand**
+
+```php
+$ch = curl_init();
+      curl_setopt_array($ch, [
+          CURLOPT_URL        => 'http://SITE_NAME/index.php?r=v2/node/search',
+          CURLOPT_HEADER     => false,
+          CURLOPT_POST       => 1,
+          CURLOPT_HTTPHEADER => [
+              "Accept: application/json",
+              "Cache-Control: no-cache",
+              "Authorization: Bearer CHICKEN-CHICKEN-CHICKEN-CHICKEN-CHICKEN" 
+          ],
+          CURLOPT_POSTFIELDS => [
+              'mac' => json_encode(['001122334455', '001122334456']), // will be treated as 'IN'
+              'ip'  => json_encode('172.16.22'),                      // will be treated as 'LIKE %%'
+          ]
+      ]);
+      curl_exec($ch);
+      curl_close($ch);
+```
+
+* All post fields array keys (parameter names for `CURLOPT_POSTFIELDS`) must be valid `Node` model attributes.
+* All post fields array values must be after `json_encode()`
+* The code above will produce the following query:
+
+        SELECT * FROM node 
+          WHERE (
+            mac IN ('001122334455', '001122334456')
+          ) 
+          AND (ip LIKE '%172.16.22%')
+
+---------
+
+**2. Lookup nodes by 'LIKE %%' non-strict match joined via 'OR' operand**
+
+```php
+$ch = curl_init();
+      curl_setopt_array($ch, [
+          CURLOPT_URL        => 'http://backup.local/index.php?r=v2/node/lookup',
+          CURLOPT_HEADER     => false,
+          CURLOPT_POST       => 1,
+          CURLOPT_HTTPHEADER => [
+              "Accept: application/json",
+              "Cache-Control: no-cache",
+              "Authorization: Bearer CHICKEN-CHICKEN-CHICKEN-CHICKEN-CHICKEN" 
+          ],
+          CURLOPT_POSTFIELDS => [
+              'mac' => json_encode(['001122334455', '001122334456']),
+              'ip'  => json_encode('172.16.22'),
+          ]
+      ]);
+      curl_exec($ch);
+      curl_close($ch);
+```
+
+The code above will produce the following query:
+
+```sql
+SELECT * FROM `node` 
+  WHERE (
+    (`mac` LIKE '%001122334455%') OR (`mac` LIKE '%001122334456%')
+  ) 
+  OR (`ip` LIKE '%172.16.22%')
+```

docs/developers-guide/java.md

@@ -0,0 +1,2 @@
+![Java flow](../assets/rest_flow_2017-03-29.png)
+![](../assets/rest_flow_concept.jpg)