Debian GRC Client

Jump to: navigation, search

Server Installation

Spin up a basic Debian 9 (Stretch) 64bit cloud instance at the provider of your choice; note that a BOINC client is CPU and RAM intensive, so be careful which provider you choose. This guide is written for a 1 CPU, 1G RAM, 25G disk cloud server with 1TB transfer/month which is billed at a flat monthly rate by the provider; tuning is provided to avoid noisy-neighbor behavior and keep resource usage within reasonable limits.

Be Careful of Costs - Cloud providers typically charge for time spent running (uptime) plus bandwidth charges. Research costs carefully and ensure the client is configured to meet your budget. The below tuning is only a guide and may need tweaked to specific circumstances.

The below instructions have been tested on various standard Debian 9 instances supplied by cloud providers. The actual CPU resource limits vary depending on type of provider/instance, however - be sure to pay attention to the CPU usage tuning details.

Server Hardening

1. The Debian 9 default vimrc (set mouse=a, /usr/share/vim/vim80/defaults.vim) messes up middle-mouse click paste when remote via SSH, override the setting to just disable the mouse:

echo 'set mouse=' >> /root/.vimrc

2. If desired, set up a non-root user and add to the sudo group, then add a password. Use this user for SSH access and become root once logged in with sudo; if you have used SSH keys to log in as root, copy to this new user's setup as well if needed:

export MYUSER="frankthetank"
useradd -m -d /home/${MYUSER} -s /bin/bash -g users -G sudo ${MYUSER}
passwd ${MYUSER}

mkdir /home/${MYUSER}/.ssh
cp /root/.ssh/authorized_keys /home/${MYUSER}/.ssh/
chmod 0700 /home/${MYUSER}/.ssh
chmod 0600 /home/${MYUSER}/.ssh/authorized_keys
chown -R ${MYUSER}:users /home/${MYUSER}/.ssh

3. Install a few basic packages to make life a little nicer; typically the cloud instances are stripped down and need a few things added, both for security and ease of use. Adjust as needed, at a minimum ensure the below are in place:

apt-get update
echo "iptables-persistent iptables-persistent/autosave_v4 boolean true" | debconf-set-selections
echo "iptables-persistent iptables-persistent/autosave_v6 boolean true" | debconf-set-selections
echo "unattended-upgrades unattended-upgrades/enable_auto_updates boolean true" | debconf-set-selections
apt-get install sysstat unattended-upgrades iptables-persistent fail2ban man less vim

4. Enable sysstat for ongoing statistics capture of your instance (use sar to view):

sed -i.bak -e 's|^ENABLED=".*"|ENABLED="true"|g' /etc/default/sysstat

5. Enable unattended-upgrades to ensure that all Security updates are applied:

cat << 'EOF' > /etc/apt/apt.conf.d/02periodic 
APT::Periodic::Enable "1";
APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Download-Upgradeable-Packages "1";
APT::Periodic::AutocleanInterval "5";
APT::Periodic::Unattended-Upgrade "1";

6. Enable the basic iptables rules to allow only port 22:

cat << 'EOF' > /etc/iptables/rules.v4
-A INPUT -p icmp -j ACCEPT 
-A INPUT -i lo -j ACCEPT 
-A INPUT -p tcp -m state --state NEW -m tcp --dport 22 -j ACCEPT 
-A INPUT -j REJECT --reject-with icmp-host-prohibited 
-A FORWARD -j REJECT --reject-with icmp-host-prohibited 

cat << 'EOF' > /etc/iptables/rules.v6
-A INPUT -p ipv6-icmp -j ACCEPT 
-A INPUT -i lo -j ACCEPT 
-A INPUT -p tcp -m state --state NEW -m tcp --dport 22 -j ACCEPT 
-A INPUT -j REJECT --reject-with icmp6-adm-prohibited
-A FORWARD -j REJECT --reject-with icmp6-adm-prohibited

7. Configure fail2ban to keep an eye on the SSH port for brute force attacks:

cat << 'EOF' > /etc/fail2ban/jail.local
ignoreip  =
bantime   = 600
maxretry  = 3
backend   = auto
destemail = root@localhost

enabled  = true
port     = ssh
filter   = sshd
logpath  = /var/log/auth.log
maxretry = 6

8. Add a bit of swap if desired - using swap is not bad in and of itself, the Linux kernel will attempt to cache it's small bits of data if available. Using swap in place of real RAM is bad, however - the tuning below will avoid actual application swapping.

# 512M file, probably overkill
dd if=/dev/zero of=/swap.file bs=4096 count=128000
chmod 0600 /swap.file
mkswap /swap.file
echo '/swap.file none swap defaults 0 0' >> /etc/fstab
swapon /swap.file

9. Finally, ensure all the services are enabled and apply all outstanding updates; reboot as needed for a new kernel. If you don't reboot here, you'll need to service foo restart each one individually:

systemctl disable
systemctl enable sysstat unattended-upgrades netfilter-persistent fail2ban

apt-get upgrade -y


BOINC Client Setup

This setup assumes you already have a Gridcoin (GRC) wallet created and uses your existing wallet ID. If needed, go set up a wallet first so that the researched GRC coins can be payed out.

1. Visit and create an account. Verify your account via email, then add your GRC wallet ID in the accounts page. The username (researcher name) and password used will be used to connect the client software.

2. Back on the cloud server, install the boinc-client and boinctui (optional) software; the client will automatically start and enable as part of the package installation process. As of this writing errors appeared in the logfile about missing directories which are being added:

apt-get install boinc-client boinctui

mkdir /var/lib/boinc-client/{slots,locale}
chown boinc:boinc /var/lib/boinc-client/{slots,locale}

systemctl restart boinc-client

3. Enable the client to always run, as this is a dedicated researching instance:

boinccmd --set_run_mode always
boinccmd --set_network_mode always

4. Tune the client settings to fit within the resources, and keep it from being a noisy-neighbor; as this is a dedicated instance, most RAM and disk will be allocated, but the CPU thresholds are reduced. As an example of two very different platforms, if you're using a Google Cloud f1-micro VM which has only 0.2 (20%) of a vCPU, a good throttle is 19%. But if you're using a full vCPU instance, 49% is an acceptable limit for most providers to avoid being a noisy neighbor. You will need to research the exact right throttle for your specific circumstances.

1 TB/month is roughly 400 KB/s sustained bandwidth

4.1 First, use systemd to control the CPU throttle, not the settings in the BOINC client. The BOINC client uses CPU idle detection and frequently pauses the process as it detects other things happening, which is undesirable in this specific setup. Instead, we will use systemd to create a cgroup (resources control group) to confine the BOINC process - and it's children, the work units - to a smaller percentage of the real CPU.

The CPUQuota option was added in systemd version 213 and requires CONFIG_CFS_BANDWIDTH=y to be configured in the active kernel. Debian 9 meets both of the requirements.

Use the built-in edit capability of systemctl to create the unit override setting(s), it will create /etc/systemd/system/boinc-client.service.d/override.conf and place you into edit mode:

EDITOR=vi systemctl edit boinc-client

# Add the below to the new file being edited and save

Inform systemd of the new content just created, then restart the BOINC client to activate:

systemctl daemon-reload
systemctl restart boinc-client

4.2 Next, set up the BOINC client to use 100% of what it thinks is the whole CPU and to only pause when it thinks other processes are using 100%, such that it basically never stops running at all while confined to it's custom cgroup. Remember that on the outside, it's only actually using 49% of the CPU in this throttled configuration.

Notice that we still set the real disk space and RAM thresholds, we are only telling it to use 100% of CPU as that's the only item we throttled from the outside. If you cannot use the above systemd throttle, you must set the CPU settings below to their actual lower values desired!

vi /var/lib/boinc-client/global_prefs_override.xml

boinccmd --read_global_prefs_override

5. Join the client to the "App Manager" ( using the username/password from your account; notice we are temporarily telling bash to not log commands which begin with a space, then running the command with a space in front of it. This is to avoid logging your password in root's bash history:

  boinccmd --join_acct_mgr (username) (password)

Gridcoin Pool Setup

Assuming the client has connected in the last step above, in the UI the server should now appear. This step adds project to have the client run; use the CPU only projects on the Gridcoin Whitelist. Which projects to join is not covered here, you will need to research and choose on your own.

1. Visit and the name of the cloud server should be listed; it will have a random ID - clicking on the servername takes you to an overview of the host and it's connected projects. The Project list is empty at this point.

2. Choose a Project (or two, but remember to balance your resources - the cloud instance only has 1 CPU) and Add it to the server. Be sure to select No Nvidia GPU, No ATI GPU, and No Intel GPU as no GPU exists in the cloud instance, you do not want tasks requiring those items sent to your client.

3. Save Settings; you will most likely receive a harmless warning that the client and are not synchronized, it can be ignored. The sync is happening next.

4. Back on the cloud instance, synchronize the settings just made on the setup; the command needs to be run twice in a row, as the process requires two steps (internally) to initialize; just in case, make sure HISTCONTROL is still set to ignore spaces and insert the spaces before the commands again:

  boinccmd --join_acct_mgr (username) (password)
  boinccmd --join_acct_mgr (username) (password)

At this point, the client running on the cloud server should be connected to as the "App Manager". Alternately, the above can be done via boinctui - F9 to bring up the menu, Projects then Synchronize with You will see the initialization happen, the first work unit download and start running - wait for this, then synchronize the second time.

Final Checks

Note that it may take a bit of time (not long) for tasks to be assigned to your new cloud client for processing; you should be able to get an immediate confirmation the client is connected and working with a general overview:

boinccmd --get_state

Once the Projects attach and start sending tasks, use top and you should see the active binaries crunching data using the CPU and RAM, and can be observed (see the man page for all options):

boinccmd --get_simple_gui_info
boinccmd --get_project_status
boinccmd --get_tasks

The boinctui is a very nice alternative, it presents a nice windowed interface which can fully control the client options with menus, and presents all the information cleanly. Pretty much anything boinccmd can do, boinctui can do as well.


The first time you start it, it will ask for a URL to connect to - accept the defaults and hit Enter to connect to the localhost instance. By default there is no password, and it can only be connected to from a localhost client. A netstat -plnt will show a listening socket on (all interfaces), however it does not need to be opened in iptables. If you decide to open this port in iptables, be sure and set a password in /etc/boinc-client/gui_rpc_auth.cfg first!