src/README

How To Setup Apache Server
--------------------------
- mod_netconf compilation requires apache2-devel and libjson-devel packages.

- run following commands in this directory
$ make
# make install

- Apache module should be installed by now, the following line is added into
server's configuration:
LoadModule netconf_module                 /usr/lib64/apache2/mod_netconf.so

- Start Apache

- mod_netconf runs as the same user as Apache. It listens on the UNIX socket
(/var/run/mod_netconf.sock) for communication with frontend and on TCP socket 8080
for notifications over WebSocket.

If there is any problem with connection to the UNIX socket, please check file permissions.

Alternatively, there is a possibility to run binary 'webgui-backend'. It is a standalone
program independent on Apache. However, it still uses libapr1 etc.

List of dependencies
--------------------

* json-c
* libapr-1
* libapr-util-1
* libnetconf
* libxml-2.0
* httpd

(with development packages)

Optionally: libwebsockets


mod_netconf Message Format
--------------------------

UNIX socket (with default path /tmp/mod_netconf.sock) is used for communication
with mod_netconf daemon. Messages are formated using JSON and encoded using
Chunked Framing Mechanism described in RFC6242 (http://tools.ietf.org/html/rfc6242#section-4.2)
with the following content.
Client is free to send multiple requests when the communication socket
to the mod_netconf daemon is opened.

Replies
~~~~~~~
1) OK
key: type (int), value: 0

Optional (for request type 3 - create NETCONF connection):
key: session (string), value: 40 unique characters of session identifier

2) DATA
key: type (int), value: 1
key: data (string)

3) ERROR
key: type (int), value: 2
key: error-message (string)

Optional:
key: error-tag (string)
key: error-type (string)
key: error-severity (string)
key: error-app-tag (string)
key: error-path (string)
key: bad-attribute (string)
key: bad-element (string)
key: bad-namespace (string)
key: session-id (string)

4) INFO
key: type (int), value: 3
key: sid (string), value: session ID
key: version (string), value: NETCONF protocol version
key: host (string), value: hostname of the NETCONF server
key: port (string), value: port of the NETCONF server
key: user (string), value: username of the user holding the NETCONF session
key: capabilities (array of strings), value: list of supported capabilities

Requests
~~~~~~~~
1) Request to create NETCONF session (connect)
key: type (int), value: 4
key: user (string)
key: pass (string), value: plain text password

Optional:
key: host (string), "localhost" if not specified
key: port (string), "830" if not specified

2) Request to close NETCONF session (disconnect)
key: type (int), value: 5
key: session (string), value: unique session identifier

3) NETCONF <get>
key: type (int), value: 6
key: session (string), value: unique session identifier

Optional:
key: filter (string), value: xml subtree filter

4) NETCONF <get-config>
key: type (int), value: 7
key: session (string), value: unique session identifier
key: source (string), value: running|startup|candidate

Optional:
key: filter (string), value: xml subtree filter

5) NETCONF <edit-config>
key: type (int), value: 8
key: session (string), value: unique session identifier
key: target (string), value: running|startup|candidate
key: config (string), value: editing configuration data according to NETCONF RFC

Optional:
key: source (string), value: config|url, default value: config
key: default-operation (string), value: merge|replace|none
key: error-option (string), value: stop-on-error|continue-on-error|rollback-on-error 
key: uri-source (string), required when "source" is "url", value: uri
key: test-option (string), value: notset|testset|set|test, default value: testset

6) NETCONF <copy-config>
key: type (int), value: 9
key: session (string), value: unique session identifier
key: source (string), value: running|startup|candidate|url
key: target (string), value: running|startup|candidate|url
Optional, required when "url" is used:
key: uri-source (string), required when "source" is "url", value: uri
key: uri-target (string), required when "target" is "url", value: uri


Alternating:
key: source (string), value: running|startup|candidate
key: config (string), value: new complete configuration data, if source not specified

7) NETCONF <delete-config>
key: type (int), value: 10
key: session (string), value: unique session identifier
key: target (string), value: running|startup|candidate

8) NETCONF <lock>
key: type (int), value: 11
key: session (string), value: unique session identifier
key: target (string), value: running|startup|candidate

9) NETCONF <unlock>
key: type (int), value: 12
key: session (string), value: unique session identifier
key: target (string), value: running|startup|candidate

10) NETCONF <kill-session>
key: type (int), value: 13
key: session (string), value: unique session identifier
key: session-id (string), value: ID of the session to kill

11) Provide information about NETCONF session
key: type (int), value: 14
key: session (string), value: unique session identifier

12) Perform generic operation not included in base NETCONF
key: type (int), value: 15
key: session (string), value: unique session identifier
key: content (string), value: XML data as content of the NETCONF's <rpc> envelope

13) get-schema
key: type (int), value: 16
key: session (string), value: unique session identifier
key: identifier (string), value: identifier of schema

14) reloadhello Update hello message of NETCONF session
key: type (int), value: 17
key: session (string), value: unique session identifier

15) notif_history Provide list of notifications from past.
key: type (int), value: 18
key: session (string), value: unique session identifier
key: from (int64), value: start time in history
key: to (int64), value: end time

16) validate Validate datastore or url
key: type (int), value: 19
key: session (string), value: unique session identifier
key: target (string), value: running|startup|candidate|url
Required when target is "url":
key: url (string), value: URL of datastore to validate