Administration

Much of the administration of an individual node can be done via the graphical user interface provided at x-admin.your_host.com, where your-host is the public address of your psibase infrastructure node (e.g. psibase.127.0.0.1.sslip.io for local nodes). To learn more about the administration app, see the documentation on x-admin. For more complex administration requirements, psinode exposes many services and configuration options over an http interface.

Booting a network

Booting a network is only a valid operation if psinode does not yet have any chain. It can be done either with the psibase CLI tool, or by using the GUI provided by the x-admin service. Alternatively, the POST /native/push_boot endpoint can be used manually in conjunction with POST /native/push_transaction to perform a custom boot sequence.

The body of the POST /native/push_boot request contains a list of transactions that will each be executed in order in the first block. The first transaction is a special transaction known as the genesis transaction. The genesis transaction uploads the core services to the blockchain and it is not permitted to do anything else.

A typical boot sequence contains more configuration than is able to fit in a single block. To understand how such a boot sequence is accomplished, see the description of SystemService::Transact::startBoot.

Peering with others

➕ TODO: document the /native/p2p endpoint.

Node administrator services

The administrator API under /native/admin provides tools for monitoring and controlling the server. All APIs use JSON (Content-Type should be application/json). Authorization to access this API is controlled by the server's admin-authz configuration option.

Server status

/native/admin/status returns an array of strings identifying conditions that affect the server.

POST to /native/admin/shutdown stops or restarts the server. The POST data should be JSON with any of the following options:

POST to /native/admin/login returns a bearer token that can be used to access the admin API. Requires bearer tokens to be enabled by the server configuration.

Peer management

/native/admin/peers lists the currently connected peers.

Each peer has the following fields:

/native/admin/connect creates a new p2p connection to another node. To set up a peer that will automatically connect whenever the server is running, use the peers config field.

/native/admin/disconnect closes an existing p2p connection. Note that if the server drops below its preferred number of connections, it will attempt to establish a new connection, possibly restoring the same connection that was just disconnected.

Key ring

GET on /native/admin/keys lists the public keys that the server can sign for.

POST to /native/admin/keys creates or uploads a new key pair. It returns the corresponding public key.

GET on /native/admin/keys/devices lists available cryptographic devices that can store keys.

POST to /native/admin/keys/unlock unlocks a cryptographic device.

POST to /native/admin/keys/lock locks a cryptographic device.

Server configuration

/native/admin/config provides GET and PUT access to the server's configuration. Changes made using this API are persistent across server restarts. New versions of psibase may add fields at any time. Clients that wish to set the configuration should GET the configuration first and return unknown fields to the server unchanged.

Example:

{
    "p2p": true,
    "peers": ["http://psibase.io/"],
    "producer": "prod",
    "pkcs11-modules": ["libsofthsm2.so"],
    "host": "127.0.0.1.sslip.io",
    "listen": [
        {
            "protocol": "http",
            "address": "0.0.0.0",
            "port": 8080
        }
    ],
    "tls": {
        "certificate": "psibase.cert",
        "key": "psibase.key",
        "trustfiles": []
    },
    "services": [
        {
            "host": "localhost",
            "root": "/usr/share/psibase/services/x-admin"
        }
    ],
    "admin": "builtin:*",
    "admin_authz": [{
        "mode": "rw",
        "kind": "bearer",
        "key": "swordfish"
    }],
    "loggers": {
        "console": {
            "type": "console",
            "filter": "Severity >= info",
            "format": "[{TimeStamp}] [{Severity}]: {Message}"
        },
        "file": {
            "type": "file",
            "filter": "Severity >= info",
            "format": "[{TimeStamp}]: {Message}",
            "filename": "psibase.log",
            "target": "psibase-%Y%m%d-%N.log",
            "rotationTime": "00:00:00Z",
            "rotationSize": 16777216,
            "maxSize": 1073741824
        },
        "syslog": {
            "type": "local",
            "filter": "Severity >= info",
            "format": "{Syslog:glibc}{Message}",
            "path": "/dev/log"
        }
    }
}

Performance monitoring

/native/admin/perf reports an assortment of performance related statistics.

The transactions field holds transaction statistics. It does not include transactions that were only seen in blocks.

The memory field holds a breakdown of resident memory usage.

The tasks array holds per-thread statistics.

Caveats: The precision of time measurements may be less than representation in microseconds might imply. Statistics that are unavailable may be reported as 0.

{
  "timestamp": "36999617055",
  "memory": {
    "database": "12914688",
    "code": "10002432",
    "wasmMemory": "7143424",
    "wasmCode": "7860224",
    "unclassified": "9269248"
  },
  "tasks": [
    {
      "id": 16367,
      "group": "chain",
      "user": "850000",
      "system": "190000",
      "pageFaults": "1",
      "read": "0",
      "written": "589824"
    },
    {
      "id": 16368,
      "group": "database",
      "user": "6370000",
      "system": "5750000",
      "pageFaults": "0",
      "read": "0",
      "written": "0"
    },
    {
      "id": 16369,
      "group": "http",
      "user": "120000",
      "system": "30000",
      "pageFaults": "0",
      "read": "0",
      "written": "0"
    }
  ],
  "transactions": {
    "unprocessed": "0",
    "total": "6",
    "failed": "2",
    "succeeded": "3",
    "skipped": "1"
  }
}

Logging

• Console Logger
• File Logger
• Local Socket Logger
• Pipe Logger
• Websocket Logger

The loggers field of /native/admin/config controls the server's logging configuration.

The log configuration is a JSON object which has a field for each logger. The name of the logger is only significant to identify the logger. When the log configuration is changed, if the new configuration has a logger with the same name and type as one in the old configuration, the old logger will be updated to the new configuration without dropping or duplicating any log records.

All loggers must have the following fields:

Additional fields are determined by the logger type.

Console logger

The console logger writes to the server's stderr. It does not use any additional configuration. There should not be more than one console logger.

File logger

The file logger writes to a named file and optionally provides log rotation and deletion. Multiple file loggers are supported as long as they do not write to the same files.

filename and target can contain patterns which will be used to generate multiple file names. The pattern should result in a unique name or old log files may be overwritten. The paths are relative to the server's root directory.

Both rotation and log deletion trigger when any condition is reached.

When log files are deleted, the oldest logs will be deleted first. All files that match the target pattern are assumed to be log files and are subject to deletion.

Example:

{
    "file-log": {
        "type": "file",
        "filter": "Severity >= info",
        "format": "[{TimeStamp}]: {Message}",
        "filename": "psibase.log",
        "target": "psibase-%Y%m%d-%N.log",
        "rotationTime": "00:00:00Z",
        "rotationSize": 16777216,
        "maxSize": 1073741824
    }
}

Local Socket Logger

The socket type local writes to a local datagram socket. Each log record is sent in a single message. With an appropriate format, it can be used to communicate with logging daemons on most unix systems.

Example:

{
    "syslog": {
        "type": "local",
        "filter": "Severity >= info",
        "format": "{Syslog:glibc}{Message}",
        "path": "/dev/log"
    }
}

Pipe logger

The pipe logger sends log messages to the stdin of a subprocess. The format MUST include any necessary framing.

The command SHOULD exit after receiving EOF. If it fails to do so, a configuration change that updates the command may terminate the previous command with a signal.

Examples:

{
    "syslog": {
        "type": "pipe",
        "filter": "Severity >= info",
        "format": "{FrameDec:{Syslog:rfc5424}{Message}}",
        "command": "nc --send-only --ssl-verify --ssl-cert logcert.pem --ssl-key logkey.pem logs.psibase.io 6154"
    },
    "alert": {
        "type": "pipe",
        "filter": "Severity >= error",
        "format": "notify-send -a {Process} -i /usr/share/psibase/icons/psibase.svg '{Process} {Channel}' \"{Escape:$`\\\":{Message}}\"\n",
        "command": "/bin/sh"
    }
}

Websocket logger

/native/admin/log is a websocket endpoint that provides access to server logs as they are generated. Each message from the server contains one log record. Messages sent to the server should be JSON objects representing the desired logger configuration for the connection.

The server begins sending log messages after it receives the first logger configuration from the client. The client can change the configuration at any time. The configuration change is asynchronous, so the server will continue to send messages using the old configuration for a short period after client sends the update but before the server processes it.