[[PageOutline]] = Setting up a BOINC server = #ServerIntro == Using a virtual machine == #VM The easiest (and recommended) way to set up a BOINC server is in a [VirtualMachines virtual machine] that we've created for that purpose, with all the necessary software already installed. You can run this virtual machine using the [http://www.vmware.com/download/player/ VMWare player] and any Intel-based computer (Windows, Linux, or Mac OS X). If you take this approach, skip the rest of this page. Otherwise, you can use any Unix system as a BOINC server; we recommend using a recent Linux release. General instructions are given below, followed by a [#cookbook-debian40 a cookbook for setting up a BOINC server on a Debian 4.0 system]. == General instructions == #general === Groups and permissions === #permissions BOINC server programs run as two different users: * The scheduler and file upload handler are CGI programs, so they run as the same user as the web server (on Fedora this is user '`apache`'; on Debian it's '`www-data`'). * BOINC daemons runs as whoever created the project (let's say user '`boincadm`', group '`boinc`'). '''Do not run BOINC daemons (or anything else) as root'''. By default, the directories created by user apache are not world-writeable. This causes problems: for example, when the file upload handler creates a directory in the [DirHierarchy upload hierarchy], it's owned by (apache, apache), and the [FileDeleter file deleter] (which runs as `boincadm`) won't be able to delete the files there. To solve this problem, edit `/etc/group` so that `apache` belongs to group `boinc`, i.e. the line: {{{ boinc:x:566: }}} becomes: {{{ boinc:x:566:apache }}} (Apache will need to be stopped/restarted for this to take effect.) Both `boincadm` and `apache` should have umasks that allow group read and write. {{{ #!comment That umask thing needs to be clarified; I had to go see an old version of GroupPermissions to see how umasks were set. Umasks are "inverted", that makes them hard to understand (they mark permissions to UNset). }}} When you create a BOINC project using [MakeProject make_project], the critical directories are owned by `boincadm` and have the set-GID bit set; this means that any directories or files created by apache in those directories will have group `boinc` (not group `apache`). The BOINC software makes all directories group read/write. Thus, both `apache` and `boinc` will have read/write access to all directories and files, but other users will have no access. To fix permissions on an existing project, do: {{{ chmod 02770 upload chmod 02770 html/cache chmod 02770 html/inc chmod 02770 html/languages chmod 02770 html/languages/compiled chmod 02770 html/user_profiles }}} You may also need to change the ownership of these directories and all their subdirectories to `boincadm/boinc`. If you're running several projects on the same server and want to isolate them from each other, you can create a different user and group for each project, and add `apache` to all of the groups. When serving your project files from Apache, note that all directories up to and including the html directory must have execute permissions. For example, if you use make_project to create the project template in your home directory, your home directory must have 711 permissions as opposed to the default of 700. If this is not corrected, you will receive a '''403 Forbidden''' error when attempted to browse to your project page. See [http://httpd.apache.org/docs/1.3/misc/FAQ.html#forbidden more information] on dealing with Apache permissions problems]. === Installing BOINC software === #installing * Download and install the needed [SoftwarePrereqsUnix software prerequisites]. * [SourceCode Download] the BOINC software. * [BuildSystem Configure and build] the BOINC software. === Operating system configuration === #OS-config Some parts of the BOINC server (the feeder and scheduling server) use shared memory. Hosts where these run must have shared memory enabled, with a maximum segment size of at least 32 MB. How to do this depends on the operating system; some information is [http://developer.postgresql.org/docs/postgres/kernel-resources.html here]. === MySQL notes === #MySQL-notes * After installing and running the server, grant permissions for your own account and for the account under which Apache runs ('nobody' in the following; may be different on your machine). All MySQL accounts should be password protected, especially `root`. {{{ mysql -u root grant all on *.* to yourname@localhost identified by 'password'; grant all on *.* to yourname identified by 'password'; grant all on *.* to nobody@localhost identified by 'password'; grant all on *.* to nobody identified by 'password'; }}} * Set your `PATH` environment variable to include MySQL programs (typically `/usr/local/mysql` and `/usr/local/mysql/bin`). * You'll need to back up your database. Generally this requires stopping the project, making a copy or snapshot, and restarting. An example is [/mysql_backup.txt here]. * BOINC gets MySQL compiler and linker flags from a program called `mysql_config` which comes with your MySQL distribution. This sometimes references libraries that are not part of your base system installation, such as `-lnsl` or `-lnss_files`. You may need to install additional packages (often you can use something called 'mysql-dev' or 'mysql-devel') or fiddle with Makefiles. * MySQL can be the bottleneck in a BOINC server. To optimize its performance, read about [MysqlConfig configuring MySQL for BOINC]. * [/mysql_cluster.txt Notes on running MySQL on a cluster]. === MySQLclient notes === #MySQLclient-notes * Configure mysql with the `--enable-thread-safe-client` switch. * Set your `LD_LIBRARY_PATH` to refer to the correct library. === Apache notes === #apache-notes In `httpd.conf`, set the default MIME type as follows (otherwise you'll get file upload signature verification errors): {{{ DefaultType application/octet-stream }}} To limit denial-of-service attacks, we recommend turning off directory indexing by adding `-Indexes` to the [http://httpd.apache.org/docs/2.0/mod/core.html#options Options] directive. Make sure that the filename extensions used by your application or data files aren't handled in undesired way by Apache. For example, if some of your files have a '.map' extension, remove the line {{{ AddHandler imap-file map }}} from httpd.conf === PHP notes === #PHP-notes * Make sure 'magic_quotes' are enabled (this is the default). The file `/etc/php.ini` should contain {{{ magic_quotes_gpc = On }}} * By default, BOINC uses PHP's `mail` function to send email to participants. This uses sendmail. If this doesn't work, you can use [http://phpmailer.sourceforge.net/ PHPMailer] instead, which is a very flexible mail-sending mechanism. To do this: * Download PHPMailer and put it under PROJECT/html/inc/phpmailer. * Set the following variables in your PROJECT/html/project/project.inc file (substitute your own values): {{{ $USE_PHPMAILER = true; $PHPMAILER_HOST = "xxx.xxx.xxx"; $PHPMAILER_MAILER = "smtp"; }}} === Common problems === #common-problems After adding a new user you have to check if the home-folder was created. Sometimes it won’t, so you have to manually create it. {{{ $ mkdir /home/{username} $ chown {username}:{username} /home/{username} }}} The link /usr/bin/gcc that points to the currently used compiler could be missing. This could lead to errors when running the make command. So you have to create the symbolic links, depending on your gcc and g++ version, first. {{{ $ ln -s /usr/bin/gcc-4.11 /usr/bin/gcc $ ln -s /usr/bin/g++-4.11 /usr/bin/g++ }}} At newer linux distributions you can’t login as user root. Instead there is a user notroot with whom you can login, but you won’t have root privileges. If an application or script needs root privileges, you are forced to enter the password you entered during the installation. In the console window you can get root privileges with the su (Debian) or sudo (Ubuntu, Fedora) command also. Note the inverted commas around the command when using su -c ! {{{ $ su -c {'command'} $ sudo {command} }}} If you have problems executing the sudo command, you have to add the user to the /etc/sudoers file. To edit this file just use this command: {{{ $ sudo visudo }}} In this file you have to add another line after the line for notroot. You can use this: {username} ALL=(ALL) ALL The Ubuntu and FedoraCore6 libcurl3-dev package is not recent enough for BOINC. So you have to install the latest version manually. The best way is to get the latest debian packages from the website and install with the dpkg command after downloading to your homefolder. {{{ $ sudo dpkg -i libcurl3_7.15.5-1_i386.deb $ sudo dpkg -i libcurl3-openssl-dev_7.15.5-1_i386.deb }}} == Cookbook for Debian 4.0 == #cookbook-debian40 === Install software prerequisites === #cookbook-prereq Common packages for building BOINC (based on [SoftwarePrereqsUnix Software prerequisites (Unix/Linux)]): {{{ m4 make autoconf automake1.9 gcc-4.1 gcc g++-4.1 pkg-config libtool subversion vim }}} packages needed for BOINC server: {{{ apache2-mpm-prefork libapache2-mod-php5 mysql-client-5.0 mysql-server-5.0 php5-mysql php5-cli php5-gd phpmyadmin python-mysqldb libmysql++-dev libssl-dev }}} packages needed for BOINC client: {{{ libssl-dev libglut3-dev glutg3-dev libglui-dev libglitz-glx1-dev libsdl1.2-dev libcurl3-dev freeglut3 freeglut3-dev libsm-dev libice-dev libxmu-dev libxi-dev libx11-dev libjpeg62-dev libgtk2.0-0 libgtk2.0-0-dev }}} optional packages for a graphical desktop manager {{{ kdebase kde-guidance synaptic iceweasel xserver-org }}} This list contains all necessary packages for the BOINC server and the client components. At first startup, these packages should be installed with aptitude. The graphical desktop manager is optional, but makes the configuration of the server a bit easier. The list contains no security packages to secure your server! Please ask your system administrator or read a good Linux book on how to secure your server against attacks. Hint: You can search packages within aptitude by pressing the '/' key. === Create a new BOINC user account === #cookbook-useraccount Login as user ‘notroot’ with the password: ‘thoughtpolice’ (downloaded image only) Go to ‘K-Menu’ -> ‘Settings’ -> ‘System Administration’ -> ‘User Management’, claim administrative privileges with password: ‘thoughtpolice’ (downloaded image only) Create a new user, for example: boincadm After that go to the ‘Groups’ tab and add the user ‘www-data’ to the group ‘boincadm’. Logout and login again as user boincadm if this is done. === Configuration of the MySQL server === #cookbook-mysql Open a new console window (’K-menu’ -> ‘Debian’ -> ‘XShells’ -> ‘Konsole’). Define a new MySQL root password. {{{ $ mysqladmin -h localhost -u root password mysqlrootpw {or own} }}} Create a new MySQL database user account. {{{ $ mysql -h localhost -u root -p > GRANT ALL ON *.* TO 'boincadm'@'localhost'; > SET PASSWORD FOR 'boincadm'@'localhost'=''; }}} The permissions can be limited to project database only, later; Defining an empty password simplifies the installation, can be changed later. === Install the wxWidgets library === #cookbook-wxwidgets {{{ #!comment Why is this needed? Later on the cookbook it clearly says "Normally you won't need a self-compiled client", and wxWidgets is only useful to compile the client, not needed for the server. }}} Download the latest wxGTK version [http://www.wxwidgets.org/downloads/ here]. Extract the contents of the file into ~/wxGTK-2.8.3 After this enter the following commands into the console window in this order: {{{ $ cd ~/wxGTK-2.8.3 $ mkdir gtkbuild $ cd gtkbuild $ ../configure --with-gtk --disable-shared $ make $ su root # make install # ldconfig # exit }}} The commands configure and make could take a while, so you can fetch some coffee. ;) === Download the BOINC source code === #cookbook-download-code The latest development version can be obtained with: {{{ $ cd ~ $ svn co http://boinc.berkeley.edu/svn/trunk/boinc boinc_trunk }}} To update the source code just go into the main directory and enter: {{{ $ cd ~/boinc_trunk $ svn update }}} A stable '''client''' version can be obtained with the following commands: {{{ $ cd ~ $ svn co http://boinc.berkeley.edu/svn/tags/boinc_core_release_5_9_5/boinc boinc_595 }}} Hint: Normally you won't need a self-compiled client, you can always get the latest one from [/download_all.php BOINC website]. NOTE: Tags are only for client software, always checkout the latest revision for the server! === Compiling BOINC source code === #cookbook-compiling Enter the following commands into the console window: {{{ $ cd ~/boinc_trunk $ ./_autosetup $ ./configure $ make }}}