Linux Driver Verification

h1. LDV Tools in Docker

h2. Description

This file describes steps to deploy ldv-tools software verification system

from master branch of ldv-tools repository with help of docker. More details

about system usage are available in corresponding tutorials stored in the

ldv-tools repo.

This package should contain english and russian tutorials and two docker images:

* debianldv.tar - image with ldv installed ldv console tools and web interface;

* mysql.tar - image with a mysql-server, database for verification results and

              script for its initialization.

h2. Deployment

# Install Docker on your machine according to official tutorial. Provided below version may help if your docker version does not support these images. Images were built with Docker having following version:

<pre>

$ sudo docker version

Client version: 1.5.0

Client API version: 1.17

Go version (client): go1.4.1

Git commit (client): a8a31ef

OS/Arch (client): linux/amd64

Server version: 1.5.0

Server API version: 1.17

Go version (server): go1.4.1

Git commit (server): a8a31ef

</pre>

# Load your images to Docker on the host machine:

<pre>

$ sudo docker load -i debianldv.tar

$ sudo docker load -i mysql.tar

</pre>

After loading you will have two available images on your host:

<pre>

$ sudo docker images

ldv_tools/debianldv           latest              ff073a36d5be        23 hours ago        2.716 GB

ldv_tools/mysql               latest              4607ef975bea        3 days ago          260.8 MB

</pre>

h2. Run containers

Warning! Before running containers make sure that nobody uses ports listed

below:

* 3306 - usually it is claimed by mysql-server;

* 8999 - largely nobody uses it.

h3. Run container with mysql-server.

# Run ldv_tools/mysql container in a daemon mode on your host machine:

<pre>

$ sudo docker run -p 3306:3306 -d ldv_tools/mysql

</pre>

# Now you can connect from your host to the mysql-server in a container. Verification results will be stored in the database "ldvbase" which can be managed by user "ldvuser" with no password:

<pre>

$ mysql -u ldvuser --protocol=TCP

</pre>

# Next it is required to access database from other container, so it is necessary to obtain mysql container''s IP address first. Perform on host:

<pre>

$ sudo docker ps

</pre>

Remember the ID of mysql container and run command to get its IP address:

<pre>

$ docker inspect --format=''{{.NetworkSettings.IPAddress}}'' <MYSQL cont. ID>

</pre>

# There is no any other required actions to perform with the container, just keep it alive. The other instructions are concerned with the main ldv image and its container.

h3. Run container with ldv-tools

# Prepare host directory with Linux sources to share with the container in a read and write mode (you can choose your own path instead of /host/work):

<pre>

$ mkdir /host/work

$ cp linux-3.17-rc1.tar.xz /host/work

$ cd /host/work

</pre>

# Run container with ldv-tools (option "--privileged=true is required for control croups mounting, since docker restricts it inside a container by default):

<pre>

$ sudo docker run -i -t -v "/host/work:/work:rw" --privileged=true -p 8999:8999 ldv_tools/debianldv /bin/bash

</pre>

# Run inside a container command:

<pre>

# recursive_cg_mounter

</pre>

# You may need to start apache2 inside a container explicitly:

<pre>

# service apache2 start

</pre>

h2. Run verification

# Now you can perform verification inside ldv container in an interactive mode. Results will be stored in finished/ dir in a pax archive. The most frequent problem is that host systems have disabled swap accounting. You can use LDV without swap account at your own risk. More information is available in ldv-tools repository in the files INSTALL, TUTORIAL, README and others. Repository is not included in the containers to save disk space. Set LDV_WORK_WITHOUT_SWAP_ACCOUNT environment variable for that. There is an example:

<pre>

# RCV_MEMLIMIT=5Gb RCV_TIMELIMIT=100 ldv-manager envs=linux-3.17-rc1.tar.xz  kernel_driver=1 "drivers=drivers/net/usb/cdc-phonet.ko" "rule_models=32_7a"

</pre>

h2. Explore results

# Upload results from debianldv container to container with mysql (remember that this IP address we already obtained few steps above):

<pre>

# LDVDB=ldvbase LDVDBHOST=<MYSQL container IP> LDVUSER=ldvuser ldv-upload-2 finished/yours.pax

</pre>

# Now you can analyze your results in a browser from your host machine or even connecting from a remote host. Just type the address:

<pre>

http://localhost:8999/stats/index/profilename/default/name/ldvbase/user/ldvuser/host/<MYSQL container IP>/

</pre>

# To share your results use host name or host IP instead of localhost.

h2. Finish work

# To terminate containers use just "exit" in a container running interactive mode and commands "sudo docker ps" and "sudo docker kill <id>" for containers started in a daemon mode.

# Do not forget to dump your mysql base from corresponding container if you are planning its further usage, since information in destroyed containers is flushed.