psinode

SYNOPSIS

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

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.localhost. This argument allows on-chain services to handle HTTP requests. It can be specified multiple times. Arguments passed on the command line override those in the config file. HTTP requests that do not match any host will be redirected to the first host.
-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.

psibase