BOINCOS-Minimal User Manual Beta v2.0.

Contents:
Installation 1
Getting Started 1
Hardware Setup And Requirements 1
Boot Options 1
Logging In 2
The BOINC OS Helper 2
Networking 2
Ethernet 2
Wireless 3
Accessing BOINC 3
SSH 3
Troubleshooting, Maintenance and Performance 3
Changing User Password 3
Setting machine hostname 3
Firewall Configuration 4
Updating the System 4
Reporting Issues 4
Email a Developer 4
Make a Github Issue 5
Installation:
BOINCOS is packaged into a raw disk image format and it must be noted that the
size of the uncompressed image is 4GB.

Requirements for installation:

● A 4GB USB or greater
● A computer with a functioning operating system
● Disk imaging software (such as ​Rufus​ or ​Etcher​)
● An archival program that can extract .zip archives
● Optional: Program that can perform file hashes

Steps:
1. Download the compressed image from the ​official website​ or ​repository
2. Decompress the image file ​(This file will decompress to 4GB)
3. Optional: Perform a checksum on the decompressed file and compare with the provided
hashes (bundled in the ​repository​ release)
4. Execute the chosen imaging software and write the decompressed image to the USB
medium

Getting Started:
Hardware Setup and Requirements:
The USB or hard drive flashed with BOINCOS should be connected to a computer which is
configured according to these specifications:
● Is in UEFI boot mode
● Secure boot is turned off
● Contains an Intel or AMD 64-bit CPU
● Has networking capabilities
Be sure to set your BIOS to boot via USB devices, else open the boot menu during the boot
process and select to boot from the USB device which may appear as “BOINCOS” in the boot
options.

Grub Boot Options:

When the OS is booted, the user will be presented with two boot options presented in a grub
screen:
1. BOINCOS
2. BOINCOS - KMS failure fallback

Option 1:
Default boot options.
Option 2:
Optional boot parameters in the event that the OS is booted to a black screen and fails to perform
Kernel Mode-Setting of the GPU drivers. (Includes the nomodeset kernel argument)

1
Logging In:
The OS will boot into a text-based console and prompt for a login. Type the username
“boincuser”, press enter and then type the password “boincos”.

The BOINC OS Helper:

This is a program packaged with BOINC OS and is used to aid the user in navigating, using and
configuring the system. The Helper is automatically set to run at login, this feature can be
disabled in the initial screen by setting the appropriate radio buttons to the right.

Keys:
● Spacebar : Make a selection or enter a menu
● q : Exit the current menu
● Arrow keys : Navigate the menus

For more information about using the helper, press spacebar on the help option in the main
screen.

If in some case you were using the helper and it crashes or receives an interrupt, the current
prompt may become unusable. If this happens at any point, press ​ctrl+c​ a few times to ensure
the prompt is clear, then type ​logout​ and then press enter. If the above fails to work, you can
change terminals by pressing ​ctrl+alt+f1...7​ (any function key 1 to 7).

Networking:
These steps can be performed within the BOINC OS Helper under the “Network configuration”
interface.
Ethernet:
Manual:
1. Run ​ip addr show​ and look for the name of your ethernet interface (should appear as
“en…” eg, enp3s0)
2. Type ​nano /etc/netctl/eth​ and look for a line that says “Interface=”
3. Use the editor to put the name of the ethernet interface from step 1 just after the equal
sign in “Interface=”
4. Press ctrl+o to write the file and ctrl+x to exit the editor
5. Type the following one after the other:
sudo netctl stop eth
sudo netctl disable eth
sudo netctl enable eth
sudo netctl start eth

2
Wireless:
Manual:
1. Type into the terminal: ​sudo wifi-menu
2. Follow all prompts to connect to a wireless interface
3. Once complete, ensure that the settings take effect on boot by typing
sudo netctl enable [name]​ where “​[name]​” is the name of the profile you specified
in step 2

Accessing BOINC:
Locally, the user is able to access boinc via the console interface by typing ​boinctui​. You can
also access this manager through the BOINC OS Helper.

Remotely, the default port for BOINC RPC is open and a user is able to connect via their
external BOINC manager by clicking ​file > select computer...​ and entering the IP address
of the BOINCOS machine and its BOINC client password. The IP address can be obtained by
running ​ip addr show​ in the terminal.

The password for the BOINC client is located at ​/var/lib/boinc/gui_rpc_auth.cfg​ and can
be edited by using ​nano /var/lib/boinc/gui_rpc_auth.cfg​. The password can be viewed
and changed through the BOINC OS Helper.

Changes to the password will take effect upon restarting the BOINC client (consult the BOINC
OS Helper or run ​sudo systemctl restart boinc​)

SSH:
Secure SHell (SSH) can be used to access the OS in the event that a video output is inaccessible.
It allows a remote terminal interface to be established with BOINC OS and requires the IP
address of the system running it (​[IP address]​), and the set password of the system (default
password is a single spacebar).
● Linux/Unix and Mac/OSX: Open terminal and type ​ssh boincuser@[IP address]
● Windows: Download Putty at ​http://www.putty.org

References:
● SSH Arch Linux wiki article: ​https://wiki.archlinux.org/index.php/Secure_Shell

Troubleshooting, Maintenance and Performance:

Changing User Password:
Within the system terminal, type ​passwd​ and follow all prompts.

Setting Machine Hostname:

By default, the hostname of the Minimal Spin is “BOINCOS-MIN”. To change, simply type
sudo hostnamectl set-hostname [New Hostname]
3
Firewall Configuration:
The OS packages ​ufw​ as it’s firewall program and the user has full privileges to modify the
firewall in any way. Under most circumstances, it is recommended to use the BOINC OS Helper
software to modify firewall settings else you can refer to the wiki page listed under references to
control it manually.

You can easily switch the firewall on or off through ​fwset [on/off/reset]

References:
● ufw Arch Linux wiki article:
https://wiki.archlinux.org/index.php/Uncomplicated_Firewall

Updating the System:

This step is unnecessary in the context of the system and may even break it, but under any
circumstance in which the user wishes to update the system, they can do so by typing ​sudo
pacman -Syu​ in the system terminal.

References:
● Pacman (PACkage MANager) wiki: ​https://wiki.archlinux.org/index.php/Pacman

Reporting Issues:
In both methods of reporting it is recommended to include as much information as possible to
describe the issue including:
● The full set of specifications of the computer BOINC OS is being run on.
● Steps that were taken before the issue occurred and a description of how it can be
reproduced. Else a specific area of the OS or code that needs fixing.
● Any logs that are associated with the issue (if accessible).

Email a Developer:
It is advised to contact a developer if you think that the issue is trivial, you do not have enough
information to back it up, require help in accessing the required information to create an issue in
the GitHub repository or if the issue is major (Ie, releasing the information to the public may
affect the security of the system or reveal critical flaws in the design which could be used to take
control or advantage of the system).

Developer emails:
● [email protected] ​- Founder and main developer

4
Make a Github Issue:
It is advised to make a ​GitHub issue​ on the official BOINCOS repository if the issue has
information backing it or is a request for functionality and support that is not planned within the
milestones of the project.

The official BOINCOS GitHub repository can be found ​here​.