Merge pull request #64 from UlfBj/master

Tutorial update

tutorial/content/_index.md

@@ -1,25 +1,18 @@
 ---
-title: "W3C Vehicle Information Signal Specification ver 2, VISSv2 Tutorial"
+title: "W3C Vehicle Information Service Specification ver 2 Reference Implementation Tutorial"
 ---
-# W3C Vehicle Information Signal Specification ver 2
+## W3C Vehicle Information Service Specification ver 2 Reference Implementation Tutorial
 
-This W3C specification, soon to become a W3C standard, is developed at the [W3C/automotive github](https://github.com/w3c/automotive),
-and this Github contains a reference implementation in the form of a server that exposes an interface according to the specification.
+The W3C VISSv2 specification, soon to become a W3C standard, is developed at the [W3C/automotive github](https://github.com/w3c/automotive).
+A reference implementation in the form of a server that exposes an interface according to the specification is developed on this repo.
 
-Also found on this Github are implementations of other components that are needed to realize a communication tech stack, from clients to the underlying vehicle system.
-These components can be categorized as follows:
+Also found on this repo are implementations of other components that are needed to realize a communication tech stack that reaches from clients through the server and to the underlying vehicle system interface.
+
+These software components (SwCs) can be categorized as follows:
 * server
 * client
 * data storage
 * feeder
 
-## Server
-
-
-## Client
-
-
-## Data storage
-
-
-## Feeder
+The tutorial describes each SwC in a separate chapter.
+It also contains a few Proof of concept (POC) examples, and information about installing, building and running Golang based SwCs.

tutorial/content/build-system/_index.md

@@ -2,10 +2,30 @@
 title: "VISSv2 Build System"
 ---
 
+## Installing Golang
+
 Most of the code at this repository is written in Golang, so in order to use this repo Golang must be installed on the computer.
 
-## Installing Golang on Ubuntu
+Searching for "install golang" gives many hits, of which this is one:
+
+[How to install Go (golang) on Ubuntu Linux](https://www.cyberciti.biz/faq/how-to-install-gol-ang-on-ubuntu-linux/).
+
+For other operating systems [this](https://go.dev/doc/install) may be helpful.
+
+## Building and running
+
+As several of the Golang based Sw components on this repo can be started with command line input to configure its behavior,
+it is suitable to first build it (in the directory of the source code)
+
+$ go build
+
+and then run it
 
+$ ./'name-of-executable' 'any-command-line-config-input'
 
-## Installing Golang on Mac
+If the SwC supports command line configuration input it is possible to add "-h" (no quotes) on the command line, which will then show a help text.
+Checking the first lines of the main() function in the source code is another possibility to find out.
+If there is any calls to the "github.com/akamensky/argparse" lib then it is used.
 
+As the configurations have a default it is always possible to run it without adding any comand line configuration input.
+The configuration possibilities of the different SwCs are described in the respective chapters of this tutorial.

tutorial/content/server/Access-control-servers/_index.md

@@ -0,0 +1,46 @@
+---
+title: "VISSv2 Access Control Servers"
+---
+
+The [VISSv2 access control model](https://raw.githack.com/w3c/automotive/gh-pages/spec/VISSv2_Core.html#access-control-model) specifies two authorization servers:
+* Access Grant server
+* Access Token server
+
+### Access Grant server
+This server is in a typical scenario running in the cloud. It is built as a separate executable in the WAII/server/agt_server directory
+
+$ go build
+
+and run by
+
+$ ./agt_server
+
+It exposes an HTTP API according to the VISSv2 specification. However it is currently not TLS protected (which is a must in non-development scenario).
+What is also missing in the AGS implementation is authentication of the client, which according to the specification should be an AGT task.
+
+### Access Token server
+
+This server runs as a thread within the vissv2 server, so it is built by the vissv2 build command.
+For it to be built, it is necessary to make sure that the "atServer" line in the serverComponents array in the vissv2server.go code is uncommented:
+```
+var serverComponents []string = []string{
+	"serviceMgr",
+	"httpMgr",
+	"wsMgr",
+	"mqttMgr",
+	"grpcMgr",
+	"atServer",
+}
+```
+If it is part of the vissv2server build, and if a VSS node is access control tagged,
+the server will then forward the access token received in the client request to the ATS for validation.
+
+The ATS will as part of the validation also use the VISSv2 specified policy documents if they are found in the working directory.
+
+
+### VISS web client submodule
+
+This submodule implements a [VISSv2 web client](https://github.com/nicslabdev/viss-web-client/)
+that exposes a UI that is considerably more sophisticated than what other clients on the WAII repo exposes,
+and it is particularly helpful when it comes to the client interactions with access control involved.
+Check out the README on both repos for more information.

tutorial/content/server/_index.md

@@ -4,3 +4,53 @@ title: "VISSv2 Server"
 
 The VISSv2 server is the Sw component that implements the interface that is exposed to the clients, and that must conform to the W3C VISSv2 specification.
 
+### Build the server
+Please check the chapter [VISSv2 Build System](/automotive-viss2/build-system) for general Golang information.
+
+To build the server, open a erminal and go to the WAII/server/vissv2 directory and issue the command:
+
+$ go build
+
+### Configure the server
+
+#### VSS tree configuration
+The server has a copy of the VSS tree that it uses to verify that client requsts are valid -
+that there is a node in the tree that corresponds to the path in a request, if a node requires an access control token, etc.
+The tree parser that is used expects the tre to have the 'binary format' that one of the VSS-Tools genertes from the vspec files.
+To generate this the [VSS repo](https://github.com/COVESA/vehicle_signal_specification) must be cloned including the VSS-Tools submodule,
+and a file containing the binary representation must be created, which is done with the following command issued in the root directory.
+
+$ make binary
+
+This generates a file with a name like 'vss_rel_4.1-dev.binary',
+which then needs to be renamed to 'vss_vissv2.binary' and stored in the WAII/server/vissv2server directory.
+
+If you want to configure the tree to include access control, access control tags as described in the
+[VISSv2 - Access Control Selection chapter](https://raw.githack.com/w3c/automotive/gh-pages/spec/VISSv2_Core.html#access-control-selection) needs to be added to appropriate tree nodes.
+This can either be done by editing vspec files directly, or using the [VSS-Tools](https://github.com/covesa/vss-tools) overlay mechanism.
+
+#### Command line configuration
+The server has the following command line configurations:
+* Data storage implementation. Select either to use an SQLite implementation (-s sqlite) or a Redis implementation (-s redis). Default is SQLite.
+* Data storage file name (--dbfile 'file-name'). Only relevant for SQLite configuration. Default is "serviceMgr/statestorage.db".
+* Request the server to generate a pathlist file, then terminate (--dryrun). Default is not to terminate after generating it.
+* Pathlist file name (--vssjson 'file-name'. Default is "../vsspathlist.json".
+* UDS path for history control (--uds 'file-name'). Name of the Unix domain socket file. Default is "/var/tmp/vissv2/histctrlserver.sock".
+* Level of logging (--loglevel levelx). Levelx is one of [trace, debug, info, warn, error, fatal, panic]. Default is "info".
+* Whether logging should end up in standard output (false) or in a log file (true) (--logfile false/true). The default is 'false'.
+
+#### Data storage configuration
+To be written...
+
+#### Protocol support configuration
+
+The server supports the following protocols:
+* HTTP
+* Websockets
+* MQTT (with the VISSv2 specific application protocol on top)
+* gRPC
+
+The message payload is identical for all protocols at the client application level (after protocol specific modifications are restored).
+
+The code is structured to make it reasonably easy to remove any of the protocols if that is desired for reducing the code footprint.
+Similarly it should be reasonably straight forward to add new protocols, given that the payload format transformation is not too complicated.