How To Multiple boinc clients on the same computer

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
Table of Contents

#2 – Quick guide for Windows installations
#3 – Quick guide for Linux installations
#17 – Tony's cheat sheet
#25 – How to tell multiple instances apart in the "Computers on this account" table at project web sites
#35 – How to add multiple client instances in BoincTasks
#44 – User credentials of the client – Don't run it as root!
#45 – How to auto-start extra clients at computer reboot (on Linux)
Summary
A computer can run more than one instance of the boinc client, either one after another, or several at once. This has a few interesting use cases, such as more direct resource control, or famously: so-called bunkering (i.e., retaining amounts of tasks in progress for a controlled period of time).

This thread shall contain a few articles on basic and advanced topics of it, and any questions/ answers/ corrections/ ideas. I plan to update the opening post with an index to any how-to style posts further down in this thread.
 
Last edited:

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
Quick guide for Windows installations

What you need
  • an already working boinc installation, and basic experience in operating it
  • a separate data directory for the secondary client
  • if you want to run primary and secondary client simultaneously (you probably want this):
    • a different GUI RPC port number for the secondary client
    • the primary client being prepared for a simultaneous secondary client
  • optionally, a few little helpers for convenient control of the clients

How to do it
It's not hard at all, and reasonably quickly done.

There is already the excellent mmonnin's Guide at overclock.net; no need to replicate it here.

(mmonnin's Guide got me going with multiple clients on Windows myself. On Linux, I did things differently.)
 
  • Like
Reactions: TennesseeTony

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
Quick guide for Linux installations

What you need
  • an already working boinc installation, and basic experience in operating it
  • a separate data directory for the secondary client
  • if you want to run primary and secondary client simultaneously (you probably want this):
    • a different GUI RPC port number for the secondary client
    • the primary client being prepared for a simultaneous secondary client
  • optionally, a few little helpers for convenient control of the clients

Step 1, prepare the primary client

The following commands assume that the boinc data directory is located in /var/lib/boinc. Some Linux distributions have it in /var/lib/boinc-client; you'll figure it out.

1.1 – Open cc_config.xml in an editor, with elevated privilege:
sudo nano -w /var/lib/boinc/cc_config.xml
or​
gksudo gedit /var/lib/boinc/cc_config.xml

1.2 – Within the <options>...</options> section, add the line
<allow_multiple_clients>1</allow_multiple_clients>
or if this tag already exists, change its value from 0 to 1.​

1.3 – Save and exit.

1.4 – Restart the client in order to apply the change.
On most Linux distributions:​
sudo service boinc-client restart
On some Linuxes:​
sudo /etc/init.d/boinc restart


Note, if the editor came up empty after step 1.1, then cc_config.xml didn't exist yet or wasn't populated yet.
In this case, enter the following as minimum content:
XML:
<cc_config>
    <options>
        <allow_multiple_clients>1</allow_multiple_clients>
    </options>
</cc_config>
After you saved this minimum file, look up under which username and group the boinc client runs:​
ps -C boinc,boinc_client -o user,group,cmd
On most Linux distributions, user and group will be "boinc" and "boinc". Change ownership of the newly created file accordingly:​
sudo chown boinc:boinc /var/lib/boinc/cc_config.xml
Then restart the client as in step 1.4.​
PS, documentation of cc_config.xml can be found at boinc.berkeley.edu.​


Step 2, make a few decisions about the secondary client(s)

Don't get worried now. All of these decisions can be revised later, anytime.

2.1 – Which user shall run the secondary client?
Let's choose a user which can normally log in to the desktop of this computer. Or into a shell anyway.​
Note, this is not safe for user accounts which are also used for sensitive tasks on this same computer, such as paid work, or home-banking, and so on. Better create a different user account which is then used to run boinc. Or stick with this primary user for now, but move it to a different user as soon as you can.​
The secondary boinc client could also be run with the same user and group ID as the primary boinc client, i.e., "boinc" and "boinc" typically. This is not discussed in this post.​
Don't run the boinc client as root. That would be a risk to integrity of the entire computer.​

2.2 – Where to put the data directory?
Suggestion: For ease of setup, put it in a new subdirectory of the home directory of the user chosen in step 2.1.​
Actually, since you might want to add a 3rd, 4th, ... client instance later, let's use a directory named "BOINC", and put separate data directories for each of the secondary clients.​
And finally, let's give each of those subdirectories the same name as the port number.​

2.3 – Which number to set the GUI RPC port to?
The primary client listens on port 31416 by default. We need to pick a different number, one which isn't used by any other service on this computer.​
Let's go with port number 40000. And if more client instances are created, give them the numbers 40001, 40002, ..., which is easy to memorize.​

Piecing steps 2.2 and 2.3 together, let's name the new data directory ~/BOINC/40000 (and later, when more are needed, ~/BOINC/40001, ~/BOINC/40002, ...). The "~" is a shorthand for "$HOME".


Step 3, prepare the data directory of the secondary client

3.1 – Create the directory.
Simply use the graphical file manager.​
Or do it in the command line:​
mkdir ~/BOINC
mkdir ~/BOINC/40000

3.2 – Set up cc_config.xml.
Either use the file manager to create a text file in ~/BOINC/40000, rename it to cc_config.xml, then open it with an editor.​
Or do it in the command line:​
nano -w ~/BOINC/40000/cc_config.xml
Paste this into the file:
XML:
<cc_config>
    <options>
        <allow_multiple_clients>1</allow_multiple_clients>
    </options>
</cc_config>
Looks familiar? Save it.​

3.3 – Set up the password for control of the client.
Create another text file in ~/BOINC/40000, named gui_rpc_auth.cfg. Either leave it empty, thus allow control of the client without password protection, or write a password into it. If you already have a password for the primary client, you can use the same here of course.​
If you prefer the command line:​
: > ~/BOINC/40000/gui_rpc_auth.cfg to create an empty file.​
echo "abc123" > ~/BOINC/40000/gui_rpc_auth.cfg to set the password "abc123", which isn't exactly best practice.​
cp /var/lib/boinc/gui_rpc_auth.cfg ~/BOINC/40000/ to copy the password of the primary client.​

Optionally, there is more which could be put into the data directory initially for convenience, but I leave this to other posts.


Step 4, launch the secondary client, and start using it

4.1 – Optional but recommended: Finish or suspend all work in the primary client.
We don't want to overload the computer in the next step.​

4.2 – Start the secondary client.
/usr/bin/boinc --daemon --allow_multiple_clients --gui_rpc_port 40000 --dir ~/BOINC/40000
Actually the --allow_multiple_clients switch is redundant to what we did in step 3.2, but it's a safeguard against mistakes.​
Now, if you feel this syntax is way too awkward to memorize, i'll address this further down in this post.​

4.3 – Control the secondary client.
If you have boincmgr already running,​
  • go to "View" -> "Advanced View..." if you aren't there already,
  • go to "File" -> "Select computer",
  • enter localhost:40000 as host name, enter the password (if any) from step 3.3, and click OK.
Or if boincmgr is not yet running, you can launch it and attach it to the secondary client in one go:​
boincmgr -g 40000 & if you created an empty gui_rpc_auth.cfg,​
boincmgr -g 40000 -p abc123 & if you set the password "abc123".​
The manager will ask you to add a project to the client.​


Step 5, optionally, add some helpers for convenient control

These are just examples; there are more ways to do it.

5.1 – Add a start script for the secondary client.
: > ~/BOINC/40000/_start.sh
chmod +x ~/BOINC/40000/_start.sh
nano -w ~/BOINC/40000/_start.sh
Paste this:
Bash:
#!/bin/bash

DIR=$(realpath $(dirname $0))
PORT=$(basename $DIR)

ps -C boinc,boinc_client -o cmd |
	grep -e "--gui_rpc_port $PORT" -e "--dir $DIR" >/dev/null &&
	exit 1

/usr/bin/boinc --daemon --allow_multiple_clients --gui_rpc_port $PORT --dir "$DIR"
This script doesn't just launch the secondary client, like done manually in step 4.2. It first makes an attempt to check whether there is already a client running with the given port number or the given data directory. Only if it doesn't see any, it starts the secondary client. We definitely don't want two client instances messing around in the same data directory.​
Note,​
  • if you want to store this script outside of the data directory, you need to replace the DIR line with something like
    DIR=~/BOINC/40000
  • if you did not name the data directory like the port number, you need to replace the PORT line with something like
    PORT=40000
The way I wrote it above with the $(...) directives, you can put an identical copy into ~/BOINC/40001 etc. later, and it will just work with that directory and portname without change.​

5.2 – Add a stop script for the secondary client.
: > ~/BOINC/40000/_stop.sh
chmod +x ~/BOINC/40000/_stop.sh
nano -w ~/BOINC/40000/_stop.sh
Paste this:
Bash:
#!/bin/bash

DIR=$(realpath $(dirname $0))
PORT=$(basename $DIR)

boinccmd --host localhost:$PORT --passwd "$(< $DIR/gui_rpc_auth.cfg)" --quit

5.3 – Add a script which launches boincmgr and attaches it to the secondary client.
: > ~/BOINC/40000/_mgr.sh
chmod +x ~/BOINC/40000/_mgr.sh
nano -w ~/BOINC/40000/_mgr.sh
Paste this:
Bash:
#!/bin/bash

DIR=$(realpath $(dirname $0))
PORT=$(basename $DIR)

boincmgr -g $PORT -p "$(< $DIR/gui_rpc_auth.cfg)"

You can execute these scripts from the file manager,
or you can start them in the shell like this:
~/BOINC/40000/_start.sh
 
Last edited:

Orange Kid

Elite Member
Oct 9, 1999
4,321
2,110
146
Thanks. I should really do this one day, just to have separate instances for CPU and GPU. :)
 

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
Finally added some content to post #3.

Dunno if it really is a "quick" guide like the title claims... :-) But I tried to reduce the steps to the minimum required. More can be said about the setup, operation, and maintenance of multiple clients, but I leave this to later posts.
 
  • Like
Reactions: biodoc

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
I just edited post #3 to fix an important mistake of mine:

The client needs to be started with /usr/bin/boinc [...], not simply with boinc [...]. Otherwise, GPU detection fails. This happens at least with the client version which I tested just now, 7.6.31.
 
  • Like
Reactions: TennesseeTony

TennesseeTony

Elite Member
Aug 2, 2003
4,201
3,630
136
www.google.com
I have found a slower way to add more clients, without having multiple hard drives of course. I just keep installing Linux Mint over and over, 'alongside' the original install. :D Gets a little confusing during the boot screen, trying to remember which is doing what, so I broke out the notepad and pen. ;)
 
  • Haha
Reactions: Assimilator1

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
I have found a slower way to add more clients, without having multiple hard drives of course. I just keep installing Linux Mint over and over,
I need to continue this thread with a small article which I have long wanted to add: Creating new instances by copying from a template directory. It's trivial and going quickly. The slowest part of that is waiting for the initial benchmark run which happens when the first project was added to a new instance.

I need all client instances in the same OS installation for at least these reasons:
  • Ability to run two or more clients in parallel. This has several applications, including
    • to have separate instances for CPU and GPU, as mentioned by @Orange Kid in #4,
    • to fetch new work into instance X while crunching away in instance Y,
    • to divide a large computer into what functions like several small computers, in projects whose scheduler does not assign work as fast as a large host can complete,
    • to fetch work which lasts for a few days but get this done within a timeframe of a few hours and mostly unattended.
  • Ability to run two or more clients in succession. I have trivial scripts which switch from one client to another as soon as the former is done with its work buffer.
  • Ability to look what is happening/ what is stored on all the instances at any time at once, using boinctasks, boinccmd etc.. For example, I have a simple script which count tasks on a given set of client instances and shows me individual task count as well as the sum of tasks.
 

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
Ah, OK, I missed that. On all my DC boxes, this file is group-readable (I don't remember whether I made it so) and my primary user is member of the boinc group (this is my doing).

PS,
since you certainly know the password of the primary instance, you can simply just do something along the lines of
echo "yourSupersecretPassword" > ~/BOINC/40000/gui_rpc_auth.cfg

PPS,
I am thinking of reconfiguring my clients for access without password, just with a source address range.
 

TennesseeTony

Elite Member
Aug 2, 2003
4,201
3,630
136
www.google.com
Linux: How would I get a second BOINC Manager window opened, rather than switching back and forth by using localhost:40000 etc?

( I would prefer a separate manager for each instance)
 

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
Launch it from the shell, equivalent to step 5.3:
boincmgr -p "yourSupersecretPassword" -g 40000 &

Or towards remote hosts:
boincmgr -p "yourSupersecretPassword" -h devastator -g 40000 &

...or with IP address behind -h, if you didn't set up name resolution.
 

TennesseeTony

Elite Member
Aug 2, 2003
4,201
3,630
136
www.google.com
I had to restart the test system. The original client naturally runs on it's own at start up. How do I restart the 2nd client? I skipped all the way to
Code:
4.2 – Start the secondary client.
/usr/bin/boinc --daemon --allow_multiple_clients --gui_rpc_port 40000 --dir ~/BOINC/40000

Then I went to the manager and selected localhost:40000, and....nothing, just sits and tries to connect to the 40000 client without success.

All the previously created folders and files are still there, all looks to be in order.

edit: This magically fixed itself later.
 
Last edited:

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
This same start command should work after a reboot.
Does ps auxf show just the primary client, or also the secondary?

Note, if the secondary client runs Rosetta, it is generally unresponsive at its remote GUI port from startup until it is done starting all Rosetta tasks. The ps auxf will also show you all child processes beneath a boinc process; from there you can deduct whether it is still not done staring all tasks.
 

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
Confirmed. Boincmgr is broken if this is entered into the "Select computer..." dialogue. On the other hand, -n localhost works (for me) as part of the command line when starting boincmgr from the shell.
 

TennesseeTony

Elite Member
Aug 2, 2003
4,201
3,630
136
www.google.com
Condensed version designed for how Tony's little brain works:

Code:
<cc_config>
    <options>
        <allow_multiple_clients>1</allow_multiple_clients>
        <max_file_xfers>30</max_file_xfers>
        <max_file_xfers_per_project>10</max_file_xfers_per_project>
    </options>
</cc_config>

  1. Copy cc_config.xml from the usb stick to var/lib/boinc
  2. Reboot (again, this is for my little brain)
  3. Make a BOINC folder in the home directory
  4. Make some sub-folder(s) starting with 40000
  5. Populate sub-folder(s) with the same cc_config.xml files, and empty gui_rpc_auth.cfg file(s).
  6. Reboot again.
  7. Start the secondary client. (Terminal) /usr/bin/boinc --daemon --allow_multiple_clients --gui_rpc_port 40000 --dir ~/BOINC/40000
  8. Select computer in Boinc Manager: localhost:40000 (31416 is original client)
  9. NEVER EVER restart the computer, because this is as far as you have gotten in the past. :D
EDIT: Step 8, alternate version. From BOINC Manager, select File/new manager, and enter the info there (if your password file is empty). This will give you another window to manage your tasks.

Now I am going to go try this out. Wish me luck.
 
Last edited:

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
8. Select computer in Boinc Manager: localhost:40000
Did this actually work for you? Maybe it makes a difference whether or not the password file (gui_rpc_auth.cfg) is empty.

Per post #15, and reproducible here, boincmgr accepts 127.0.0.1:40000 but gets stuck with localhost:40000.

9. NEVER EVER restart the computer, because this is as far as you have gotten in the past. :D
After restart, just repeat step 7 and optionally 8 in your list.

Good job BTW with this abridged version; I never seem to be able to write in this way. :-)
 
  • Like
Reactions: TennesseeTony

TennesseeTony

Elite Member
Aug 2, 2003
4,201
3,630
136
www.google.com
Skipped to step 7 on the 2 machines I had trouble with, and boom, all those wingmen are going to be happy I didn't lose those Uni tasks.

Trying a fresh 2nd instance now, on a third machine. Uhm Holy Crap that was easy! 5 minutes maybe?

Thanks Stefan!

PS: I used empty password files.
 
Last edited:

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
Oh, I forgot: Step 6 can be omitted without replacement.
Step 2 could be replaced with
sudo service boinc-client restart
or perhaps even just with boincmgr -> Options -> Read config files, but I am not sure of the latter. (Granted, if reboot is not too inconvenient, it is the easiest to memorize way.)
 

TennesseeTony

Elite Member
Aug 2, 2003
4,201
3,630
136
www.google.com
Oh boy. Big problem. I am adding instances to each machine, one at a time. I am successful on many machines already, just moments ago. But now, there is this one trouble maker. Upon completion and the final restart, the BOINC Manager refuses to run. CPU usage is 100%, so the service has started, but the Manager resists assimilation.

But I have this friend, dear BOINC Manager, and I assure you, resistance is futile! I hope.

Futile[1].jpg
 
  • Like
Reactions: Endgame124

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
First, run
killall boincmgr
Repeat until it says
boincmgr: no process found
These steps are to ensure that there aren't any leftover boincmgr processes around, even though no windows of theirs are to be seen.

Then, on the machine which is running the boinc client instances, reassure yourself which clients are running in which directory and with which GUI RPC port:
ps auxf
If everything looks good here, proceed.
Otherwise, fix what's obvious to you, or report here what you can't fix on your own.

If the above was alright, start boincmgr and tell it to attach itself to the desired instance right away.
If boinc client and boincmgr are on the same machine:
boincmgr -p YourPasswordHere -g 31416
Replace 31416 with the correct GUI RPC port number.
If boinc client is on a different machine:
boincmgr -p YourPasswordHere -n 192.168.0.42 -g 31416
Replace 192.168.0.42 with the actual IP address of the machine with the client, and replace the GUI RPC port number of course.
Instead of an IP address, you can also enter a host name after -n if you have name resolution set up and if the host name starts with a letter, not with a digit.

If you have empty gui_rpc_auth.cfg files, omit the -p YourPasswordHere part.
 

TennesseeTony

Elite Member
Aug 2, 2003
4,201
3,630
136
www.google.com
Thanks, if it happens again I will certainly do all that.

As it stands, I made lunch, caught up on some of the threads, and then an idea came to mind.

So:
  • I just learned how to set up WINE on Linux
  • BOINCtasks, due to recently gained knowledge, is no longer just a bunch of gibberish.
  • That got me back to at least seeing my tasks and all. Then BOINCtasks/wine crashed. lol
  • After a restart, BOINCtasks now won't start, but the regular manager DID start
  • 2nd instance has now been started and loaded up with NumberFields. lol
Now I am back to step 9 of my condensed post above. :D :D :D
 
  • Like
Reactions: biodoc

StefanR5R

Elite Member
Dec 10, 2016
5,441
7,681
136
How to distinguish client instances in "Computers on this account" web pages

Method 1: Via "model name" a.k.a. "product name"

If you do not like that the various client instances on the same host cannot be told apart in the "Computers on this account" page in your account at the project web sites, here is what you can do about it:

The command
boinccmd --host HOSTNAME:PORTNUMBER --passwd PASSWORD --set_host_info MODELNAME
gives a "model" name to the client instance. After you triggered a project update (or the client issued a scheduler request for its own reason), a new column with the heading "Model" appears in the "Computers on this account" table, showing the MODELNAME string which you set for this client instance.

In the individual host details page, this string is shown in a row with the heading "Product name". This row is only shown for your own computers when you are logged in. It is not shown to other users, or when you are viewing the host details page while you are not logged in.

Two MODELNAME strings have special significance:
  • The string "0"...
    boinccmd --host HOSTNAME:PORTNUMBER --passwd PASSWORD --set_host_info 0
    ...removes the model name from the instance.
    As soon as none of your client instances have a model name anymore, the "Model" column vanishes from the "Computers on this account" table.

  • The empty string ""...
    boinccmd --host HOSTNAME:PORTNUMBER --passwd PASSWORD --set_host_info ""
    ...simply does nothing: The previously set MODELNAME remains.

Note, the MODELNAME is cleared when the client instance is shut down. That is, if you want to keep it even if you shut down and restart the instance, or the entire computer, then you need to add the boinccmd as shown above to the client startup procedure.

For example, use this extended version of the ~/BOINC/40000/_start.sh script of post #3 step 5.1:
Bash:
#!/bin/bash

DIR=$(realpath $(dirname $0))
PORT=$(basename $DIR)

ps -C boinc,boinc_client -o cmd |
        grep -e "--gui_rpc_port $PORT" -e "--dir $DIR" >/dev/null &&
        exit 1

/usr/bin/boinc --daemon --allow_multiple_clients --gui_rpc_port $PORT --dir "$DIR"

while sleep 0.1
do
        boinccmd --host localhost:$PORT --passwd "$(< $DIR/gui_rpc_auth.cfg)" \
                 --set_host_info $PORT 2>/dev/null &&
        break
done
This sets the model name same as the remote GUI RPC port number. The while loop is necessary because the client is not able to respond immediately to RPCs when it was just started.

The model name feature requires a recent enough client version. E.g. boinc 7.8.x and 7.9.x work, whereas boinc 7.6.x does not. I haven't looked up the minimum version which supports the feature.


Method 2: Via "device name" a.k.a. "domain name"

In client version 7.16.11, the following new option is supported in cc_config.xml:
<device_name>NAME</device_name>
use the given name to identify this computer on project web sites. Default: network domain name.​
I have not tried this feature myself yet, as my clients are still at an older version, but this sounds promising and convenient.
Benefits of method 2 over method 1:
  • Setting the name in cc_config.xml is arguably easier than having to run a shell script each time.
  • This method should work with all projects, I guess, whereas method 1 is not supported by some project web sites.
  • Maybe, just maybe, boincmgr is showing the reconfigured computer name too? That would be really great. Users of client version 7.16.11, please test and report your findings.
One downside of method 2 compared to method 1:
  • The way I use method 1, port number and model name directly depend on the data directory name. There is no redundancy in method 1, hence no opportunity to accidentally assign a wrong port number or wrong model name by mistake.


________________
Edited on October 25: added method 2
 
Last edited: