Curl

The unix command curl can execute ad-hoc REST API queries from the command-line (or any script), to access Simscope's data.

Note: this requires an API token.

Security Notice

Careful: In general, when using curl do not use passwords or API tokens as direct command-line arguments to curl. Otherwise it is possible for other users on the same machine to view API tokens from inspecting curl shell commands on the machine.

Instead, use @file.txt arguments (where curl reads arguments from file.txt)

The curl examples here all use @$HOME/.simscope.apitoken headers, which are safely read from curl, rather than exposed via shell.

Simscope Curl syntax

The basic syntax for curl commands is:

> curl --location --data-urlencode "apitoken@$HOME/.simscope.apitoken" -G \
"http://server:8080/api/API"

→ Replace:

server:8080 with your Simscope server
API with the Simscope API
- for example: r/myregr/123 accesses a regression named myregr/123
Optional: replace -G with -XPOST if you want to perform a POST query, rather than a GET query.
Optional: append -v to get verbose output from curl (for debugging errors).

Example Curl query

Here is an example whoami query from Simscope, which prints the user information for the current API token, in JSON format.

# Replace server:8080 with your Simscope URL
> curl --location --data-urlencode "apitoken@$HOME/.simscope.apitoken" -G \
"http://server:8080/api/config/whoami"

Here is the JSON result:

{
    "uid": "pdq",
    "login": "pdq",
    "name": "Payton Quackenbush",
    "email": "payton@verops.com",
    "group": "",
    "admin": true,
    "manager": false,
    "subdaily": true,
    "subimport": false,
    "disabled": false,
    "foreground": 16777215,
    "background": 2317899,
    "initials": "PQ",
    "short_name": "Payton Q.",
    "apitoken": true,
    "createdns": 1435634894738375828,
    "updatedns": 1616281496576175081
}

Note: if curl fails, you can run with the -v (verbose) option, to get more information.

Publish coverage TSV to Simscope

Save this to simscope-coverage-publish.sh

#!/bin/bash

# Publish coverage to Simscope

HOST="http://localhost:8080"
REGR=$1
COVFILE=$2

set -e

if [ $# -ne 2 ]; then
    echo "Usage:   $0 REGR/NUM COVFILE.tsv"
    echo ""
    echo "Example: $0 dev/12345 mycov.tsv"
    exit 1
fi

echo "Simscope coverage publish"
echo "Host:    $HOST"
echo "Regr:    $REGR"
echo "CovFile: $COVFILE"
echo "----------------------------------------"

curl --data-urlencode "apitoken@$HOME/.simscope.apitoken" -XPOST --location --show-error -H "Content-Type: application/json" "$HOST/api/coverage/$REGR" --data-binary @$COVFILE
echo ""

Example Publish Session

Here is an example coverage publish session, publishing cov2.tsv to Regression dev/12021:

# Set the Simscope API token
> echo "7940bfb2090c7" > ~/.simscope.apitoken
> chmod 600 ~/.simscope.apitoken

# Publish coverage
> ./simscope-publish-coverage.sh dev/12021 cov2.tsv

Simscope coverage publish
Host:    http://localhost:8080
Regr:    dev/12021
CovFile: cov2.tsv
----------------------------------------
"dev/12021"

Publish Regression

Save this to simscope-publish-regr-json.sh

#!/bin/bash

# Publish a regression JSON to Simscope
# NOTE: the preferred method is via the Tunnel, but this is fine for debug purposes

HOST="http://localhost:8080"
REGR=$1
REGR_JSON=$2

if [ $# -ne 2 ]; then
    echo "Usage:   $0 REGR FILE.json"
    echo ""
    echo "Example: $0 myrun/12 debug.json"
    exit 1
fi

echo "Simscope regression JSON"
echo "Host:    $HOST"
echo "Regr:    $REGR"
echo "JSON:    $REGR_JSON"
echo "----------------------------------------"

curl --location --data-urlencode "apitoken@$HOME/.simscope.apitoken" --noproxy '*' -XPOST --location --show-error -H "Content-Type: application/json" -H @- "$HOST/api/r/$REGR" --data @$REGR_JSON
echo ""

Example JSON

{
    "component": "alpha_cpu_core",
    "project": "RocketChip",
    "model_branch": "dev",
    "model_version": "46fa3f7483ef06801a94c6b24c108fa2",
    "model_timestamp": "2020-02-03T12:00:54Z",
    "starttime": "2020-02-05T22:00:53.842443Z",
    "queue": "queue3",
    "pending": true,
    "userid": "admin",
    "host": "c-2",
    "command": "flow --regr --seed 6801a9 MODEL=1a4",
    "dir": "/mnt/proj/regr/integrate/105",
    "custom_metadata": [
        [
            "Area.combo",
            "102.7"
        ],
        [
            "Area.noncombo",
            "38.4"
        ]
    ]
}

Add a User via Curl

You can add a User account to simscope via curl, if you have Simscope Administrator privileges.

The user will be created with a blank (empty) password.
- Note that blank passwords are only allowed if Simscope has LDAP and OIDC disabled (ie local accounts).

Write this to user.json:

{
    "uid": "sally",
    "name": "Sally Johnson",
    "email": "sally.johnson@company.com"
}

Execute:

> curl --location --data-urlencode "apitoken@$HOME/.simscope.apitoken" --noproxy '*' -XPOST --location --show-error -H "Content-Type: application/json" -H @- "$HOST/api/u/" --data @user.json

If successful, you should get a 200 response like this:

{
    "uid": "sally",
    "login": "sally",
    "name": "Sally Johnson",
    "email": "sally@company.com",
    "group": "",
    "admin": false,
    "manager": false,
    "subdaily": false,
    "subimport": false,
    "disabled": false,
    "foreground": 16777215,
    "background": 9839123,
    "initials": "SJ",
    "short_name": "Sally J.",
    "apitoken": false
}

(Not recommended) Testing API with clear authentication (without API tokens)

Security note: do not use this command via curl for production, as you are exposing your session token. Use API Tokens with the @ syntax instead!

Encode the username into the simscope-session cookie:

# NOTE: this should only be used for testing purposes
> curl "$HOST/api/config/whoami" -H "simscope-session=sally:"

If successful, you should get a 200 JSON response like this:

{
    "uid": "sally",
    "login": "sally",
    "name": "Sally Johnson",
    "email": "sally@company.com",
    "group": "",
    "admin": false,
    "manager": false,
    "subdaily": false,
    "subimport": false,
    "disabled": false,
    "foreground": 16777215,
    "background": 9839123,
    "initials": "SJ",
    "short_name": "Sally J.",
    "apitoken": false
}

Alternative (to send an HTTP cookie back to a client browser): respond with:

> Set-Cookie: simscope-session=fred@verops.com:; Path=/; Max-Age=31536000

Simscope Administration Guide