Client node

Run client -h to see all available command line switches. Some example ones are:

-t - use Testnet4 (instead of regular bitcoin network)

-t3 - use Testnet3

-ul=NN - set maximum upload speed to NN kilobytes per second

-dl=NN - set maximum download speed to NN kilobytes per second

-r - rebuild the UTXO database (fixes 'Unknown input TxID' errors)

-nowallet - do not enable the wallet functionality (uses less memory, processes blocks faster)

-sc - save the config file and exit (use it to create a default gocoin.conf)

-log <file> - save a copy of the console output to the given file

To run the client on a remote Linux server (via ssh connection), you probably want to get adventage of screen command.

TextUI

When the client is already running you have an interactive, text command based interface, on the console.
Type help to see the possible commands.

WebUI

There is also a web interface that you can operate with a web browser.

Make sure to have the www/ folder in the location where you execute the client from.
The folder contains files that are an essencial part of the WebUI application.

WebUI application is tested with Google Chrome, but should be compatible with any modern web browser.

By default (for security reasons) WebUI is available only from a local host, via http://127.0.0.1:8833/

Remote server

In order to use WebUI securely on a remote server, set up ssh tunneling to port 8833.
Alternatively, expose the WebUI over an encrypted connection - see WebUI over SSL below.

Local network

If you run the node on a local network and want to have access to its WebUI from different computers:

Open gocoin.conf file in a text editor (or edit it at the Home page of the WebUI).
Change Interface value in the config file to :8833 (Note: this binds the web service to all network interfaces).
Change AllowedIP value to allow access from all the addresses you need - e.g. 127.0.0.1,192.168.0.0/16 (Note: 0.0.0.0/0 allows to connect from anywhere).
Remember to save the new config and then restart your node.

Read more about the config file at the config file page.

WebUI over SSL

The node can also serve the WebUI over an encrypted HTTPS connection.
This mode uses two certificates:

a server certificate – which proves the node's identity to your browser,
a client certificate – which proves your identity to the node.

The client certificate is not optional. The node rejects any HTTPS connection that does not present a certificate signed by your own CA, so knowing the address of your node is not enough to get in.

Because the access is controlled by the certificate, the SSL server ignores the AllowedIP list and listens on all the network interfaces, no matter what Interface is set to. It runs in parallel with the regular HTTP server, which keeps its own settings.

Once connected, you get exactly the same WebUI as over HTTP, including the wallet and spending pages. It is therefore a convenient way of reaching your node from the outside world – without ssh tunneling and without exposing the unencrypted WebUI to the internet.

Which certificate comes from where

ssl_cert/ca.crt is used only to verify the client certificates, so it always has to be your own CA, generated by yourself. Never use a public CA for that file – it would let anyone holding a certificate from that CA into your node.

The server certificate is independent from it. You can either have it signed by your own CA (self-signed), or use one issued by a trusted party, e.g. Let's Encrypt. In the latter case your browser will trust the node's address out of the box.

Generating your own CA

openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key -out ca.crt

Copy ca.crt into the ssl_cert/ folder. Keep ca.key somewhere safe – you only need it to sign the certificates below.

Server certificate

If you have a certificate from a trusted CA, simply rename its private key to server.key and the certificate (or the full chain) to server.crt. Both files have to be in the PEM format.

To make a self-signed one instead, first create a v3.ext file:

authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = domain.com

Replace domain.com with the hostname (or IP) of your node, then:

openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt -sha256 -extfile v3.ext

When asked for the Common Name, give the same value as in DNS.1 above.

Place server.key and server.crt in the ssl_cert/ folder.
Using a self-signed certificate, also import ca.crt into your browser's Trusted Root CA list, to avoid security warnings.

Client certificate

This one is always signed by your own CA:

openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt
openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.p12

Import the resulting client.p12 into your browser's Personal certificates. The browser will ask you which certificate to use when you first open the node's page.

Note: the client.p12 file stays on your side only – it is never copied to the node. Repeat this step for each device you want to give access to.

Accessing the node

The SSL server starts automatically as soon as ca.crt, server.crt and server.key are all present in the ssl_cert/ folder – there is no config value enabling it. After restarting the node, look for Starting SSL server at :4433 ... in the console output.

Then point your browser at https://your.hostname.or.ip:4433/

The default port depends on the network: 4433 for main net, 14433 for Testnet3 and 44433 for Testnet4. Set SSLPort in the config file to use a different one.

To have the WebUI at the standard HTTPS port, redirect it on your nat, e.g.:

iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 4433

The server certificate is reloaded automatically whenever the server.crt file changes, so renewing it (e.g. by Let's Encrypt) does not require restarting the node.

Security precautions

Keep ca.key and all the client.* files secret. Whoever gets hold of any of them will be able to access your node's WebUI.

Your wallets are not exposed this way. The node's wallet is watch-only and it never holds any private keys, while the addresses themselves are kept in the LocalStorage of your own browser – not on the node. A stranger connecting from a different browser simply sees an empty Wallet page, until they add some wallets of their own.

What such a person does get is control over the node. With ServerMode disabled they can shut it down, change its configuration and add or remove network peers. And even with ServerMode enabled, they still see the memory pool and all the transactions loaded locally on your node.

See also the README in the client's ssl_cert/ folder.