psinode

NAME

psinode - The psibase blockchain server

SYNOPSIS

psinode [-l port] [-p name] [-o host] [options]... database

DESCRIPTION

psinode runs a chain. It can optionally be a producer or a non-producer node on a chain. It also optionally hosts an http interface which provides RPC services, GraphQL services, and hosts web UIs. On-chain services define most of the http interface.

database is a directory which will contain the chain database. psinode creates it if it does not already exist.

OPTIONS

General options

  • -l interface, --listen interface

    Accept connections on interface. The argument can be any of the following:

    • A port number: Listens on 0.0.0.0 with the specified port
    • An IP address: Listen on port 80 on the given interface
    • An IP address and port separated by a colon: ipv4:port or [ipv6]:port
    • An http or https URL: The host component must be an IP address. All components other than the host and port must be empty. https requires --tls-cert and --tls-key to be provided.
    • A filesystem path: Listens on a local socket

    This option can be used more than once to listen on multiple ports. If it appears in both the command line and the config file, however, any instances in the config file will be ignored. The default config file template uses port 8080.

  • -p name, --producer name

    Produce blocks using the given producer name. It will not start production on an empty chain until you boot the chain. psinode will only produce blocks when it is this producer's turn according to consensus. Multiple distinct nodes must not use the same producer name. If the producer has an associated key, the server must have access to the corresponding private key, either by --key or though an unlocked PKCS #11 token.

  • -o hostname, --host hostname

    Enable the service http interface. Its argument is a domain name which supports virtual hosting. e.g. if it's running on your local machine, use psibase.127.0.0.1.sslip.io. This argument allows on-chain services to handle HTTP requests and also allows the node to accept transactions.

  • -k private-key, --key private-key

    Use this private key to sign blocks. Any number of keys may be provided, but only the one that matches the public key corresponding to the producer name will be used.

  • --pkcs11-module filename

    Loads a PKCS #11 module from filename. The server will be able to sign blocks using keys from the module. The tokens that the module provides must be unlocked using the HTTP API before they can be used. This option can appear any number of times.

P2P Network Options

  • --p2p

    allows external nodes to peer to psinode it over its http interface at /native/p2p.

  • --peer url

    tells psinode a peer to sync with. The argument should have the form host:port. This argument can appear any number of times.

  • --autoconnect number

    limits the number of out-going peer connections. If it is less than the number of --peer options, the later peers will be tried after a connection to an earlier peer fails.

HTTP Server

  • --service host:path

    tells psinode to host static content from path. This argument is included in the default config file template. It should typically not be necessary to change these default settings.

  • --admin static:* | * | service

    tells psinode to enable the admin API

  • --admin-authz mode:type:params

    Restricts client access to the admin API. mode can be r or rw. type should be one of the following:

    • any: Allows any client
    • loopback: Allows connections from localhost
    • ip:address: Allows connections from a specific IP address
    • bearer:key: Allows access with a bearer token, which must be sent in the HTTP Authorization header. The key is an arbitrary string which will be used to verify the tokens. Tokens can be generated by psibase create-token or by the /native/admin/login endpoint. This option may be specified more than once. A client can access the admin API if it satisfies any of the conditions.

  • --http-timeout seconds

    tells psinode how long to wait before closing an idle connection. The value is in seconds unless it has an explicit unit symbol. A value of inf means that connections will never time out.

TLS Options

  • --tls-cert file

    A file containing the certificate chain that the server will use. The key must be specified as well using --tls-key. This certificate will be used both as a server certificate for incoming https connections and as a client certificate for outing p2p connections using https. The certificate should be a wildcard certificate, valid for both host and *.host.

  • --tls-key file

    The private key corresponding to --tls-cert

  • --tls-trustfile file

    This file should contain trusted root certification authorities used to verify certificates. If it is not provided a system dependent default will be used.

Configuration File

Options can also be specified in a configuration file loaded from database/config. If an option is specified on both the command line and the config file, the command line takes precedence. When a new database is created, a default config file will be created.

The configuration file also controls logging.

Environmental variables, double quotes, and backslash escapes can be used in the value of most options. psinode adds some variables to its environment:

  • PSIBASE_DATADIR

    The directory containing data files used by psinode. Usually <install-prefix>/share/psibase.