Svace is an automatic defect detection tool for programs written in C and C++, 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 of the 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

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 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_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 projects 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:

svace server admin create --user username # to create a user. Set up user password with this utility
svace server admin create --role role1 # to create a role with required permissions
svace server admin user username --add-role role1 # to assign created role to our user
svace server admin grant-permission read --role role1 --project project_name # we grant read permission on the first project to this role...
svace server admin grant-permission modify --role role1 --project external_project_name # ...and modify permission on the second project to this role

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 setup 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.