diff --git a/doc/bitsquare-sn.cron.sh b/doc/bitsquare-sn.cron.sh new file mode 100755 index 0000000000..d9683cafa4 --- /dev/null +++ b/doc/bitsquare-sn.cron.sh @@ -0,0 +1,43 @@ +#!/bin/sh +# Restart Bitsquare seed node daemons whose resident memory (RSS) +# is over MAX_RSS_MiB. +# +# Scripts in the INITDIR must contain a ``SN_ADDRESS=`` +# assignment. +# +# Exit with status 2 if there were restarted daemons. +# +# Author: Ivan Vilata-i-Balaguer +MAX_RSS_MiB=350 + +PIDDIR=/var/run/bitsquare-sn +INITDIR=/etc/init.d + +# Restart de daemon with the given address. +restart() { + rcscript=$(grep -El "^SN_ADDRESS=['\"]?$1['\"]?" $INITDIR/*) + if [ "$rcscript" ]; then + "$rcscript" restart + fi +} + +restarted= +max_rss_kib=$((MAX_RSS_MiB*1024)) +for pidfile in $PIDDIR/*.pid; do + address=$(basename ${pidfile%.pid}) + pid=$(cat "$pidfile") + test "$pid" || continue + rss_kib=$(ps -o rss= "$pid") + test "$rss_kib" || continue + if [ "$rss_kib" -gt "$max_rss_kib" ]; then + echo "Bitsquare seed node $address ($((rss_kib/1024))M) surpassed memory limit of ${MAX_RSS_MiB}M, restarting." >&2 + restart $address + restarted=y + fi +done + +if [ "$restarted" ]; then + exit 2 +else + exit 0 +fi diff --git a/doc/bitsquare-sn.init.sh b/doc/bitsquare-sn.init.sh new file mode 100755 index 0000000000..789b9adbfd --- /dev/null +++ b/doc/bitsquare-sn.init.sh @@ -0,0 +1,48 @@ +#!/bin/sh +# kFreeBSD do not accept scripts as interpreters, using #!/bin/sh and sourcing. +if [ true != "$INIT_D_SCRIPT_SOURCED" ] ; then + set "$0" "$@"; INIT_D_SCRIPT_SOURCED=true . /lib/init/init-d-script +fi +### BEGIN INIT INFO +# Provides: bitsquare-sn +# Required-Start: $local_fs $remote_fs $named $network $time +# Required-Stop: $local_fs $remote_fs $named $network $time +# Default-Start: 2 3 4 5 +# Default-Stop: 0 1 6 +# Short-Description: Bitsquare seed node +# Description: This script manages the execution of +# a Bitsquare seed node process using +# its own Tor node to provide a hidden service. +### END INIT INFO + +# Author: Ivan Vilata-i-Balaguer + + +## BEGIN CONFIGURATION +# HOST:PORT address of seed node. Change this for each instance. +SN_ADDRESS=1a2b3c4d5e6f7g8h.onion:8000 + +# Bitcoin network: 0=mainnet, 1=testnet, 2=regtest. +SN_NETWORK_ID=0 +# Maximum number of connecitions to allow. +SN_MAX_CONNECTIONS=50 + +# Location of the seed node jar file. Use to select a particular version. +SN_JAR=~bsqsn/SeedNode-0.4.2.jar +# User to run the seed node as. +SN_USER=bsqsn +## END CONFIGURATION + + +# Using a name different than the daemon's base name +# causes problems when stopping the process. +#NAME="bitsquare-sn" +DESC="Bitsquare seed node $SN_ADDRESS" +START_ARGS="--chuid $SN_USER --background --make-pidfile" +PIDFILE="/var/run/bitsquare-sn/$SN_ADDRESS.pid" +DAEMON=/usr/bin/java +DAEMON_ARGS="-jar $SN_JAR $SN_ADDRESS $SN_NETWORK_ID $SN_MAX_CONNECTIONS" + +do_start_prepare() { + mkdir -p "$(dirname "$PIDFILE")" +} diff --git a/doc/seed-node-daemon.md b/doc/seed-node-daemon.md new file mode 100644 index 0000000000..0059e51fce --- /dev/null +++ b/doc/seed-node-daemon.md @@ -0,0 +1,85 @@ +# Running a seed node as a daemon + +This document presents some steps to be able to run a Bitsquare seed node as +an unattended daemon in a GNU/Linux server with a traditional System V init. + +## Before you start + +We assume that you have already configured a Bitsquare seed node to run in a +computer. You will need to upload the seed node code and configuration to the +server: + + - The code is contained in the ``SeedNode.jar`` file which is usually left + under ``seednode/target`` after building Bitsquare. + - The seed node configuration is the ``Bitsquare_seed_node_HOST_PORT`` + directory under ``~/.local/share`` (Unix), ``%APPDATA%`` (Windows) or + ``~/Library/Application Support`` (Mac OS X). + +## Dedicated user + +In order to avoid security risks, it is highly recommended that you create a +dedicated user in the server to run the seed node daemon, and that you forbid +other users to access its files, for instance: + + # adduser bsqsn + # chmod go-rwx ~bsqsn + +Place the jar file where the ``bsqsn`` user can read it and tag it with +Bitsquare's version number (to allow running several instances of mutually +incompatible versions), e.g. ``~bsqsn/SeedNode-VERSION.jar``. Copy the +configuration directory to the ``~bsqsb/.local/share`` directory. + +## Testing the seed node + +You need to check that the seed node can actually run in your system. For +instance, if you are using version 0.4.2 and your seed node's Tor address is +``1a2b3c4d5e6f7g8h.onion:8000``, try to run this as the ``bsqsn`` user: + + $ java -jar ~bsqsn/SeedNode-0.4.2.jar 1a2b3c4d5e6f7g8h.onion:8000 0 50 + +Please check error messages if it fails to run. Do note that you will need +OpenJDK and OpenJFX in the server. In Debian-like systems you may install the +needed dependencies with: + + # apt-get --no-install-recommends install openjfx + +After the node runs successfully, interrupt it with Control-C. + +## Init script + +To allow the daemon to start automatically on system boot, use the attached +[init script](bitsquare-sn.init.sh). First edit it and change its +configuration variables to your needs, especially ``SN_ADDRESS``, ``SN_JAR`` +and ``SN_USER``. In the previous example, the values would be: + + SN_ADDRESS=1a2b3c4d5e6f7g8h.onion:8000 + SN_JAR=~bsqsn/SeedNode-0.4.2.jar + SN_USER=bsqsn + +Put the customized script under ``/etc/init.d`` using a name without +extensions (e.g. ``bitsquare-sn``), make it executable, add it to the boot +sequence and finally start it: + + # cp /path/to/bitsquare-sn.init.sh /etc/init.d/bitsquare-sn + # chmod a+rx /etc/init.d/bitsquare-sn + # update-rc.d bitsquare-sn defaults + # service bitsquare-sn start + +Executing ``service bitsquare-sn status`` should report that the process is +running. + +## Cron script + +The attached [Cron script](bitsquare-sn.cron.sh) can be used to check the seed +node daemon periodically and restart it if it is using too much memory (RSS at +the time, may change to VSS later). + +To enable this check, edit the script and change the ``MAX_RSS_MiB`` to +whatever limit (in MiB), copy it to ``/etc/cron.hourly`` and make it +executable: + + # cp /path/to/bitsquare-sn.cron.sh /etc/cron.hourly/bitsquare-sn + # chmod a+rx /etc/cron.hourly/bitsquare-sn + +The check will be run every hour. For more sophisticated checks, use a proper +monitor like [Monit](https://mmonit.com/monit/).