NSAdaServer

What NSAdaServer is

nsadaserver is Nacarsoft’s web explorer for Adabas files. It runs as a single Go binary that embeds the server, the web UI and a SQLite database for security; there is no separate frontend to deploy. It connects to the Adabas nucleus through the native client (CGO, -tags adalnk).

• Six views per file: table, form, JSON, DDM, ADAREP and API, plus an ER graph of relationships.
• Data and metadata: the DDM catalog is cached on disk; the file list and its definition can be browsed without a live connection, while the connection provides the physical name and record count.
• Create and operate: create physical files with ADAFDU from the browser, update and delete records by ISN, empty files and reconcile the catalog.
• REST API: the same endpoints the web UI uses, with an OpenAPI 3.0 specification, Swagger and API keys with scopes, expiry and usage auditing.
• Access control: users → groups → roles → per-file permissions (read, write, delete), JWT, bcrypt, brute-force protection and daily auditing.
• Multi-database: several Adabas databases in one instance, with a connection pool and idle auto-stop.
• Experience: 6 languages (ES, EN, FR, DE, IT, PT), light/dark theme and adjustable font size.

Database, file, field and data names in the examples are fictional.

Use cases

1. Quick record lookup without desktop tools

Find a specific record (e.g. fictional policy POL-2024-00123) from the browser, without installing the Adabas client on the desk.

./build/nsadaserver init /tmp/nsadaserver-demo
# → prints the random password for the admin user; keep it
./build/nsadaserver start /tmp/nsadaserver-demo
./build/nsadaserver status /tmp/nsadaserver-demo
# → nsadaserver is RUNNING (PID 12345)  Listening: http://0.0.0.0:11010

Web flow (http://localhost:11010): sign in as admin with the password printed by init; pick the DEV database in the side panel, open the file in the tree, search by field or by ISN and read the record in table, form or JSON view.

2. Explore the DDM/FDT/ADAREP structure before coding

Review a file’s fields, formats, descriptors and indexes (e.g. fictional FNR 100) before writing an integration or a Natural program.

./build/nsadaserver status /tmp/nsadaserver-demo   # confirm RUNNING

Web flow: select database and file in the tree; open the DDM view for the definition and its fields/indexes tabs; open ADAREP for the server’s real output; use the API view to get the equivalent REST call.

3. Give support read-only access to one database

Let the support team query the files in TEST without touching DEV or being able to modify records.

curl -s http://localhost:11010/api/health
# → {"service":"nsadaserver","status":"healthy"}

Web flow (as admin): Administration → Groups, Roles and Permissions; create a role with can_read on the TEST files (or * for all) and assign it to the user’s group. The user signs in and only sees the allowed files; any other operation returns 403.

4. Page through a large file under controlled limits

Walk a fictional history file with thousands of records without overloading the server or the Adabas connection.

./build/nsadaserver stop /tmp/nsadaserver-demo
# (tune pagination.page_size and pagination.read_limit in /tmp/nsadaserver-demo/config.yaml)
./build/nsadaserver start /tmp/nsadaserver-demo

Web flow: open the file in table view and page through it; the status bar shows the record count and ASO/DATA usage. On databases with a pool, the connection stops by itself after idle_timeout_minutes without access.

5. Create a new physical file with ADAFDU

Create a file for a new load without leaving the browser or using nucleus tools.

Web flow: click + in the database tree; enter the FNR and file name, description and default values; add fields with level, type, length, description and the NU, DE, UQ, PE, GR, MU flags; add superdescriptors if needed. NSAdaServer creates the file with ADAFDU, updates the local DDM and makes it visible with the role’s permissions.

6. Try the API from the panel itself

Consume and debug the API without leaving the application.

Web flow: open the API view; search for the endpoint (e.g. GET /api/db/150/files/100), fill in parameters and body, press Execute Request and check the Response, URL and cURL tabs. The OpenAPI 3.0 specification is at /api/openapi.json and the Swagger UI at /swagger/.

7. Integrate an ERP with an API key

Give an integration scoped access without sharing a user’s password.

Web flow: Administration → API Keys → create; enter a name, expiry in days (0 = never) and scopes. The full key is shown only once, at creation. The ERP sends it in X-API-Key or as Authorization: Bearer <key>; every use is recorded and the key can be revoked or reactivated.

8. Audit who queried or changed data

Review operations and configuration changes for a ticket or an internal audit.

Web flow: Administration → Users/Groups/Roles/Permissions and API Keys; the Configuration editor lets you review config.yaml and warns when a restart is required. Activity is written to audit/ with daily rotation, and failed logins go through the brute-force protection.

Interface

The six views of a file

Reference

Requirements

CLI commands

--config does not work as the first argument: nsadaserver --config x answers Unknown command. Use nsadaserver start <dir> or nsadaserver start --config <dir>.

The admin password is not fixed: init generates a random one and prints it only once. Copy it before closing the terminal and change it on first login.

Main configuration (config.yaml)

Notes:

• If adabas.databases is empty, the legacy adabas.dbid / config_file configuration is used.
• A missing pool keeps the traditional shared-connection mode. In pool mode, non-positive size_acc and size_upd fall back to 5 and 2; idle_timeout_minutes: 0 means it never stops.
• etid and etid_prefix are mutually exclusive. The random prefix must be exactly 3 alphanumeric characters.
• files limits the visible FNRs of that database; it is independent of the per-file RBAC permissions.

DDM catalog

Each database declares its catalog in config_file: a JSON file with the file structure. The format is:

{
  "library": "SYSTEM",
  "files": [
    {
      "metadata": {
        "source_file": "DEMO-CLI.NSD",
        "ddm_name": "DEMO-CLIENTES",
        "db": "000",
        "file_number": 100,
        "record_type": "ADABAS",
        "total_fields": 21,
        "total_length": 654,
        "description": "Demo customer data"
      },
      "fields": [
        {
          "level": 1,
          "name": "AA",
          "field_name": "COD-CLIENTE",
          "format": "A",
          "length": "8",
          "descriptor": "D",
          "description": "Customer code"
        }
      ]
    }
  ]
}

The catalog is cached on disk: the file list and its definition are shown even when the Adabas connection is down; the connection only provides the physical information. POST /api/db/{dbid}/reconcile re-synchronises the catalog with the nucleus.

Permissions and API keys

users → groups → roles → per-file permissions (can_read / can_write / can_delete)

REST API

The OpenAPI 3.0 specification is served at /api/openapi.json and the Swagger UI at /swagger/. The web API Explorer uses the same specification and adds the session token.

Authentication:

• JWT: Authorization: Bearer <token> after POST /api/auth/login.
• API key: X-API-Key: <key> or Authorization: Bearer <key>.
• The token is also accepted as ?token= in shareable explorer URLs.

# Authentication (use the password printed by init)
TOKEN=$(curl -s -X POST http://localhost:11010/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<password-from-init>"}' \
  | sed 's/.*"token":"\([^"]*\)".*/\1/')

# Records of a file (DBID 150, FNR 100)
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:11010/api/db/150/files/100?page=1&page_size=40"

# Search with an Adabas expression
curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -X POST http://localhost:11010/api/db/150/files/100/search \
  -d '{"query":"COD-CLIENTE=DEMO*","limit":20}'

Security and auditing

• User passwords with bcrypt and an HS256 JWT session.
• Email recovery with a link and a 6-digit code, with configurable expiry.
• Brute-force protection and a log of login attempts.
• Audit per operation (user, action and result) with daily rotation in audit/.
• config.yaml is saved with 0600 permissions when edited from the application.
• 30-day trial; machine-signed license at $NS_HOME/licenses/nsadaserver.key.

Commented examples

# 1. New environment and startup (the directory must not exist)
./build/nsadaserver init /tmp/nsadaserver-demo
./build/nsadaserver start /tmp/nsadaserver-demo
./build/nsadaserver status /tmp/nsadaserver-demo

# 2. Two environments with the same binary
./build/nsadaserver init /tmp/nsadaserver-prod && ./build/nsadaserver start /tmp/nsadaserver-prod
./build/nsadaserver init /tmp/nsadaserver-dev  && ./build/nsadaserver start /tmp/nsadaserver-dev
./build/nsadaserver status /tmp/nsadaserver-prod
./build/nsadaserver stop /tmp/nsadaserver-dev

# 3. Restart after changing config.yaml
./build/nsadaserver restart /tmp/nsadaserver-demo

# 4. Verification: health, SPA, version and license
curl -s http://localhost:11010/api/health
curl -s http://localhost:11010/ -o /dev/null -w '%{http_code}\n'
./build/nsadaserver version
./build/nsadaserver license /tmp/nsadaserver-demo

# 5. Deprecated alias (works with a warning)
./build/nsadaserver -server /tmp/nsadaserver-demo

# API with a key (no user session)
curl -H "X-API-Key: $NSADASERVER_API_KEY" \
  "http://localhost:11010/api/db/150/files/100?page=1&page_size=40"

# State of a specific database
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:11010/api/databases/DEV/ping"

FAQ

What is the initial admin password? There is no fixed password. init generates a random one and prints it only once; keep it and change it on first login. If it is lost, use email recovery (when SMTP is configured) or create a new environment: init does not overwrite existing directories.

Where does the license go? At $NS_HOME/licenses/nsadaserver.key; if NS_HOME is not set, at /opt/ns/licenses/nsadaserver.key. Without a license there is a 30-day trial and nsadaserver license shows the machine fingerprint.

It won’t connect to Adabas? Check adabas.databases in config.yaml (dbid, connect, config_file and files) and network access to the nucleus. GET /api/databases/{database}/ping helps isolate the problem. On the server, check ldd build/nsadaserver and LD_LIBRARY_PATH if the native library is missing.

Why can’t I see any files? The DDM catalog may not be loaded, or the role may lack permission on those files. Check the config_file, that the JSON has files with its ddm_name, and the role’s can_read permissions (or the * wildcard).

Can I query without an Adabas connection? The file list and its DDM are read from the local cache; viewing records, ADAREP or statistics requires a live connection.

How do I access the API? From the web API view, with /api/openapi.json or with /swagger/. For integrations, create an API key in Administration → API Keys and send it in X-API-Key.

Which port does it use? 11010 by default. Change it in server.port; if it is taken, check with lsof -i :11010.

Which languages and themes are available? ES, EN, FR, DE, IT and PT; light/dark theme and adjustable font size. The manuals on this site are in Spanish and English, with an English fallback for the other languages.

Are the example data real? No: databases, files, fields, records and credentials in the examples are fictional.