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.
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