diff --git a/tutorial/content/_index.md b/tutorial/content/_index.md index 2c658e67..a8d6412f 100644 --- a/tutorial/content/_index.md +++ b/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. diff --git a/tutorial/content/build-system/_index.md b/tutorial/content/build-system/_index.md index 4704230a..cf2697d3 100644 --- a/tutorial/content/build-system/_index.md +++ b/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. diff --git a/tutorial/content/server/Access-control-servers/_index.md b/tutorial/content/server/Access-control-servers/_index.md new file mode 100644 index 00000000..96474cde --- /dev/null +++ b/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. diff --git a/tutorial/content/server/_index.md b/tutorial/content/server/_index.md index 502989c9..577d7acb 100644 --- a/tutorial/content/server/_index.md +++ b/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. diff --git a/tutorial/static/images/fav.png b/tutorial/static/images/fav.png new file mode 100644 index 00000000..25d01eca Binary files /dev/null and b/tutorial/static/images/fav.png differ diff --git a/tutorial/static/images/vissv2.png b/tutorial/static/images/vissv2.png index 8ec3aebe..e1d85759 100644 Binary files a/tutorial/static/images/vissv2.png and b/tutorial/static/images/vissv2.png differ