x-admin

The adminstrator service is hosted on localhost by default as a Builtin Service. It provides tools for monitoring and controlling the server.

Authentication

Access to x-admin is allowed only if

• The client and all proxies are either running over the loopback interface (localhost) or have IP addresses listed in the environmental variable PSIBASE_ADMIN_IP, which holds a comma separated list of IP addresses, or
• The user is logged in as an authorized on-chain account, or
• The proxy that is directly connected to psinode is authorized and the request includes the header configured in the environmental variable PSIBASE_USERNAME_FIELD

Configuration Options

All of these options can also be specified on the command line or in the server's config file. Changes applied through the web API will be saved to the config file and will be remembered across server restarts. Except where noted otherwise, a new configuration takes effect when saved.

Accept incoming P2P connections

If enabled, the node will accept p2p connections at the websocket endpoint /native/p2p.

Block Producer Name

The name that the server uses to produce blocks. It must be a valid account name. The node will only produce blocks when its producer name is one of the currently active producers specified by the chain. To disable block production, the producer name can be left blank.

Host

The root host name for services. If it is empty, only builtin services will be available.

Port

The TCP port on which the server listens. The server must be restarted for a change to the port to take effect.

Logger

See Logging for a list of the available logger types and their parameters.

Builtin Services

psinode will serve content directly from the filesystem when the request's host matches the host of a builtin service. A builtin service hides a chain service with the same name.

Builtin services have significant limitations. On-chain services should be preferred unless the service requires access to the admin API (the administrator service) or needs to be available before the chain is booted.

Builtin services can only serve the following files types:

• .html
• .svg
• .js
• .mjs
• .css
• .ttf
• .wasm

HTTP Endpoints

Service

LocalService::XAdmin

struct LocalService::XAdmin {
    const psibase::AccountNumber service; 

    isAdmin(...);      // Returns true if the account or the remote end of socket is a node admin
    checkAuth(...);    
    serveSys(...);     
    startSession(...); 
    options(...);      
};

Service for node administration.

LocalService::XAdmin::isAdmin

bool LocalService::XAdmin::isAdmin(
    std::optional<psibase::AccountNumber>          account,
    std::optional<std::int32_t>                    socket,
    std::vector<std::optional<psibase::IPAddress>> forwardedFor
);

Returns true if the account or the remote end of socket is a node admin.

LocalService::XAdmin::checkAuth

std::optional<psibase::HttpReply> LocalService::XAdmin::checkAuth(
    const psibase::HttpRequest & req,
    std::optional<std::int32_t>  socket
);

LocalService::XAdmin::serveSys

std::optional<psibase::HttpReply> LocalService::XAdmin::serveSys(
    psibase::HttpRequest        req,
    std::optional<std::int32_t> socket
);

LocalService::XAdmin::startSession

void LocalService::XAdmin::startSession();

LocalService::XAdmin::options

AdminOptionsRow LocalService::XAdmin::options();

Monitoring Dashboards

Psinode monitoring is powered by metrics collected and fed into Prometheus. Then, Grafana is used to manage dashboards and visualize all the collected data.

The easiest way to run these services is to use docker containers, since we prepared a docker-compose file with all the needed services.

All the following instructions are assuming you are working with the files under the Psibase repo, in the /packages/local/XAdmin/monitors directory.

Running with docker

Update the prometheus.yml file to have the correct target of your psinode instance. Eg: if it's running locally, outside of your docker network, you can leave as is and add a new built-in service in psinode config, then restart it:

service = host.docker.internal:

If the psinode is running in another docker, just make sure you have access to that network and update the target properly. You will not need the builtin service conf.

Then, simply run:

docker-compose up

Open http://localhost:8080 and you will be able to see the XAdmin panel with the embedded dashboards.

Proxying Grafana

If you are accessing the x-admin ui locally, eg. from http://localhost:8080 you can skip this part.

Most cases you will end up putting the access to the x-admin behind a reverse proxy with at least the minimum HTTP basic-auth or perhaps restricting IPs. In any case, this reverse proxy needs to add a rule for accessing the Grafana dashboards on /grafana location. Here's an example:

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

upstream docker-grafana {
    server grafana:3000;
}

server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html index.htm;

    location /grafana/ {
        rewrite  ^/grafana/(.*)  /$1 break;
        proxy_set_header Host $http_host;
        proxy_pass http://docker-grafana;
    }

    # Proxy Grafana Live WebSocket connections.
    location /grafana/api/live/ {
        rewrite  ^/grafana/(.*)  /$1 break;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_pass http://docker-grafana;
    }
}

Full instructions can be found here: https://grafana.com/tutorials/run-grafana-behind-a-proxy/

Running locally

You don't need to, but if you prefer or have to run these services in your dedicated server, you can execute the following steps.

Grok exporter listens to psibase logs and extracts the metrics.

wget https://github.com/fstab/grok_exporter/releases/download/v1.0.0.RC5/grok_exporter-1.0.0.RC5.linux-amd64.zip
unzip grok_exporter-*.zip
cd grok_exporter-*
./grok_exporter --config=./grok-exporter.yml

Node exporter collects metrics from the node (not being used in our dashboard for now).

wget https://github.com/prometheus/node_exporter/releases/download/v1.5.0/node_exporter-1.5.0.linux-amd64.tar.gz
tar -xzvf node_exporter-*.*.tar.gz

Prometheus is the timeseries DB that will consolidate all the above metrics.

wget https://github.com/prometheus/prometheus/releases/download/v2.41.0/prometheus-2.41.0.linux-amd64.tar.gz
tar xvfz prometheus-*.tar.gz
cd prometheus-*
./prometheus --config.file=../prometheus.yml