Svace is an automatic defect detection tool for programs written in C, C++, Java, Kotlin and Go, based on static analysis. This program is copyright Institute for System Programming of the Russian Academy of Sciences (ISP RAS).

Svace is currently optimized for analysis of typical applications with command line interface written for Linux, primarily in C or C-style C++. Source code for different environments can be analyzed as well, but if it relies on libraries unknown to the tool instead of the standard ones, or heavily uses unexpected idioms, the quality of analysis results may decrease. Some warning types are also specific to Linux applications.

Outline

This User Guide includes the following main sections:

• Introduction
• Installation
• Server initialization
• Starting the Svace server
• Server setup
• Project management
• User management
• Project directory tuning
• Remote analysis

Introduction

Svace analysis and history server allows users to run analysis remotely using resources of the server and/or share users’ history modifications. It can handle multiple users working simultaneously with different projects.

Installation

Only usual Svace installation is required to run the server. It also has the same prerequisites. It is advised to create a new user account specifically for running the server.

Configuring the Svace server

Svace history requires a special directory called server directory. This directory contains server settings and all data for all projects on this server (except for projects which were explicitly configured to store data externally). Svace server directory is initialized as follows:

svace server init [--server-dir </path/to/server/dir>]

If server-dir flag is not set, svace will work like it is set to the current directory. This directory must be an existing empty directory on a file system. After execution of this command you’ll get an empty initialized server directory at the given path, which can now be used to configure and start a server.

Starting the Svace server

Svace analysis and history server is started as follows:

svace server start [--server-dir </path/to/server/dir>]

If server-dir flag is not set, svace will work like it is set to the current directory. This directory must be an existing initialized server directory. If the configuration is read successfully from this directory, server will start listening for jobs on the port specified in the config file (55135 by default) and for web-requests on another port specified in config (8060 by default) and the following message will be printed to the output stream:

Remote analysis server started at port 55135
Web server started at port 8060

This means that the server is set up properly and ready to receive analysis jobs.

Server single start mode

Svace server has simple mode for running without preliminary set up. It allows to view analysis results immediately after analysis without any server setting up. Every svace directory may be used as directory for svace server.

For importing result of last analysis to local svace server it is sufficient to run follow command:

svace history import

For running svace server it is enough to run command:

svace server single-start

This command starts svace server in single mode. All results will be available via web interface at localhost:8060.

Command history import may be used many times.

Server setup

Currently, Svace loads server configuration from the file located at [conf/svace.conf] path in the server directory. Server must be stopped prior to configuration process and restarted afterwards.

The following is the list of options Svace server currently supports. They are read by the server in the form <OPTION> = <VALUE> from the configuration file.

SERVER_DB_CONNECTION = – this option currently should remain untouched.

SERVER_DB_DRIVER = – this option currently should remain untouched.

SERVER_PORT = 55135 – the port Svace server will listen to for Svace native connections. This is the port clients must set as server port in eclipse plugin/svace remote commands.

SERVER_CONNECTIONS_LIMIT = 0 – how many simultaneous connections the server will handle (zero means no limit).

WAITING_CONNECTIONS_LIMIT = 0 – how many connections could be queued before the server has to start interacting with them. If its value is zero then default value from the JDK (fifty) will be used.

Remote analysis setup

The following is the list of options specific to analysis process.

ALLOW_ANALYSIS = true – if remote analysis should be enabled on this server or not.

SIMULTANEOUS_ANALYSIS_LIMIT = 3 – how many concurrent analyze commands the server is able to start. All extra analyze requests will be queued and processed later. The zero value means no limit.

ALLOW_SIMULTANEOUS_ANALYSIS_PER_PATH = false – whether parallel analyses are allowed using the same project folder. If it is set to ‘false’ then only one simultaneous remote analysis per path is allowed. The ‘true’ value of this option is ignored for server single-start mode.

ALLOW_ANALYSIS_LOGS_TRANSFER = false – if svace remote analyze clients must receive full analysis logs or just small status updates.

Web access setup

The following is the list of options specific to web server.

WEB_SERVER_PORT = 8060 – port for analysis statistics and history server (enabled by ALLOW_WEB_MONITORING).

ALLOW_WEB_MONITORING = false – allows Svace server to show a small web page with current analysis statistics.

ALLOW_WEB_HISTORY_ACCESS = true – allows Svace server to provide access to project histories.

Logs setup

ALLOW_LOGGING = true – if logging should be performed at all.

LOGGING_FILE = – the file server should log to. If not set, logs will be sent to stdout.

ALLOW_WEB_LOGGING = true – if web-server logging should be performed at all.

WEB_LOGGING_FILE = – the file web-server should log to. If not set, logs will be sent to stdout.

Setting up project list for Svace server

One running Svace analysis server can perform analysis or manage history in multiple projects. These projects first must be initialized or registered in Svace server directory.

All projects on Svace server must exist in some project group. This is a simple script to create a project and a project group on a server:

svace server admin create --project-group project_group_name
svace server admin create --project project_name --group project_group

Previous script will create a new project directory for the project inside the server directory. If you want to attach an existing project to the server directory, use this command:

svace server admin create --project external_project_name --group project_group --path /path/to/already/existing/project/directory.

Server directory can contain any number of project groups. Each project group can contain any number of projects. Each project group’s name must be unique among all project groups. Each project’s name must be unique among all projects.

User management

Even if you have created projects in server directory, you won’t be able to access them through web interface or svace remote commands without valid credentials. A user must have enough permissions to access a given project.

There can be any number of registered users and any number of ‘roles’ on the server. Each user has a certain list of these ‘roles’. Multiple users can have the same role. Each role may have any number of permissions to access different projects. Each user’s permissions is a sum of permissions from all of their roles.

So, imagine you want to create a new user on the server and grant them read-only access to one project and read-and-write access to another. That’s how you should do it:

# To create a user, set up user password with this utility:
svace server admin create --user username

# To create a role with required permissions:
svace server admin create --role role1

# To assign created role to our user:
svace server admin user username --add-role role1

# We grant read permission on the first project to this role...
svace server admin grant-permission read --role role1 --project project_name

# ...and modify permission on the second project to this role.
svace server admin grant-permission modify \
    --role role1 \
    --project external_project_name

You may find short but extremely simple documentation on project and user management in the output of this command:

svace server admin --help

Or you can just use web interface to manage users, projects, permissions, etc. You just need a user with admin-level permissions on the whole server:

svace server admin create --user admin_user_name
svace server admin create --role admin_role
svace server admin user admin_user_name --add-role admin_role
svace server admin grant-permission admin --role admin_role

Then you may log in into svace history web interface and use management tools.

Please note, that adding and revoking permissions to roles and roles to users will not affect users that are already logged in. To gain access to their new permission sets they must log out and then log in again.

Setting up project directory’s warnings database

Project directory’s DB can be configured with config file [.svace-dir]/shared/db.conf in project directory. Its format is PROPERTY=VALUE too, and these are the important options:

By default, Svace will use bundled SQLite as database engine. It is good enough to store local analysis results but may have synchronization problems if history server is used by many clients simultaneously. In this scenario it is advised to set up another external database. This is done with the help of a “db.conf” file.

Following is a sample setup for the MySQL database connection. Other databases should be configured similarly.

DRIVER_CLASS = com.mysql.jdbc.Driver – Svace uses JDBC as database connection engine, so it needs a Java JDBC driver for the database. This is a required option that specifies the class from the driver that Svace should use as the main class. Please consult the driver’s documentation (keyword is “Class.forName”) to get its name. In the current example “com.mysql.jdbc.Driver” class is used for MySQL JDBC driver.

JDBC_STRING = – this string specifies how JDBC connection should be set up for the database. Usually JDBC strings for databases look like “jdbc:driver:options”. If you know what the JDBC string should look like for the database connection, you may enter it as JDBC_STRING option. Otherwise, Svace will try to construct it using other parameters.

JDBC_DRIVER_NAME = mysql – this option names the JDBC driver. It is used to construct a JDBC string if it is not set explicitly. The “driver” parameter in the JDBC string above is the value of the JDBC_DRIVER_NAME option. MySQL’s driver name is “mysql” so it is used in this example.

JDBC_HOST = localhost – address for the database connection if applicable.

JDBC_PORT = 3306 – port for the database connection if applicable.

JDBC_EXTRA_PARAMS = – this option allows to set up extra database connection parameters. Svace will use them to finish construction of the JDBC string. MySQL needs a server’s host and port as were set up above. SQLite, for example, requires path to database file as an extra database connection parameters option.

JDBC_USER = svace – login for the database or empty if not applicable.

JDBC_PASSWORD = svace – password for the database or empty if not applicable.

TABLE_PREFIX = svace. – most database servers (MySQL as well) can maintain multiple databases. This option specifies which one of them Svace should work with. When constructing SQL queries Svace will use this option as a table name prefix. So instead of “svace_main_table” it will access “svace.svace_main_table” (note a dot at the end of this option). MySQL detects such table names (with a dot) as <DB name>.<table name>, and this allows Svace to transparently work with the “svace” database. This option may also be used to separate multiple project directories databases stored in one database server.

Remote analysis

Purpose

Run analysis on another machine. Svace server should be run on server machine. On another machine with after project building with svace task for remove analysis may be send to server.

Quick start

Server

mkdir new-dir
cd new-dir

svace init
svace server single-start

Now svace server is ready to get commands for remote analysis. Command svace init create directory .svace-dir where all server’s data will be stored.

Client

Run regular build with Svace:

svace init
svace build make

Run remote analysis:

svace remote --host server analyze

Parameter host set up name of server on first step. It may be omitted. In this case svace will be use host localhost.

After running command remote analyze all needed data will be sended to server and server will start analysis. The command returns result after remote server finish analysis.

Results may be import as during regular analysis:

svace history import

Those results will be available at localhost:8060 after running command svace server single-start.

As well results may be imported to Svacer:

svacer import --svace path-to-svace/bin/svace .
svacer upload

How it is working

Remote analysis wait results on port 55135 (SERVER_PORT). By default Svace server run at most 3 analysis simultenious (Option SIMULTANEOUS_ANALYSIS_LIMIT). If client attemps to run more analysis than limit server will add analysis task to queue. Client will wait when other analysis will be finished. Analysis results are stored at directory .svace-dir/remote-<hash>/analyze-res on server.

Server never cleanup any data. We recommend to cleanup server folder by some schedule.

Client sends to server hash of files that must be analysed. Server requests those files from client only if it doesn’t have those data. That is why data sending during regular building same project with minor changes expected to be efficient. Sending all data is also fast enough and by our testing takes much less time than analysis. Additioanlly Svace send settings (settings.txt and warn-settings.txt).

After sending analysis task svace clean up local folder .svace-dir/analyze-res. Otherwise it may be confused with results of local analysis. When remote anlysis will be ended svace put to this folder hashes of analysis result and build and svres-file. All other results are not sended and available only on server’s folders.

Svace server allows to look at currently working analysis via web-interface at address: http://<server>:8060/status.