Skip to content

MasterUrl

Jump to bottom
David Anderson edited this page Sep 19, 2024 · 5 revisions

The master URL

Each project is identified by a master URL. The document at this location (the master page) is, by default, generated by the script index.php, which is created by make_project. The master page is typically a web page describing the project, and offering instructions for volunteers.

In addition:

  • The master page must contain hidden elements specifying the project's scheduling servers. The BOINC client reads and parses the master page to find these.

  • The document at <MASTER_URL>/get_project_config.php must be an XML document describing the project, as generated by the script html/user/get_project_config.php.

Specifying scheduler addresses

The master page must contain elements of the form

<!--
<scheduler>http://host.domain.edu/cgi/scheduler</scheduler>
<scheduler>http://host2.domain.edu/cgi/scheduler</scheduler>
-->

specifying the URLs of the project's scheduling servers. The BOINC client reads and parses the master page to locate scheduling servers. If at any point it is unable to connect to any scheduling server for a project, it rereads the master page. This mechanism lets a project move or add scheduling servers.

Some ISPs remove HTML comments from downloaded pages. Therefore the master page should also specify the scheduler URLs using link elements:

<link rel="boinc_scheduler" href="http://host.domain.edu/cgi/scheduler">

The master page should include both; since older clients won't parse the <link> syntax.

The make_project script creates a master page in project/html/user/index.php. This file includes the file 'schedulers.txt', which contains the list of <scheduler> (and <link>) elements.

Choosing a project URL

It's recommended that projects choose master URLs that allow the server to change location. For example, even if you're still starting with a test project, don't use an IP address in the URL; use an actual hostname. Even having the university name as part of the hostname may be a bad idea. In December 2007, Docking@Home moved from the University of Texas at El Paso to the University of Delaware, and had to change their URL from docking.utep.edu to docking.cis.udel.edu. This required their volunteers to attach to the new project, and some volunteers were lost. Thus, the best way is having a hostname just for that project. Good URLs don't change.

Even having multiple projects in the same hostname, like http://boinc.example.org/project1/ and http://boinc.example.org/project2/ may be problematic if you eventually decide you want to move project2 to a different server. It's best to have project1.example.org and project2.example.org so they can (now or in the future) have different IP addresses.

How to change a project URL

All that said, here is how you change a project URL:

  1. Pick a good new URL according to the above recommendations, so that you will never need to change it again.
  2. If the project was ever public, post news to let users know the URL will change.
  3. If any BOINC stats website carries your project, let the site admins know about the URL change.
  4. If you have any tasks in progress or waiting to be sent, it's recommended you wait until they are all done before changing the URL. And/or abort the unsent tasks. You could edit the database to fix URLs for input files, to make the unsent workunits work once the URL is changed; but it's probably more trouble than it's worth, and won't help with workunits that people already have in their client queue.
  5. Stop the project. Take the website down too.
  6. Replace the URL everywhere in config.xml
  7. Replace the scheduler URL in html/users/schedulers.txt. Its prefix should match the URL in <cgi_url> in config.xml.
  8. If you have project-wide files, like logos for the simple GUI, replace download URLs in project_files.xml
  9. Delete everything in html/cache, since cached pages may have links to the old URL, and users would get broken links for an hour or so. Don't delete the cache folder itself.
rm -rf html/cache/*
  1. Either create new application versions, or update the app_version table to have the new URLs:
UPDATE app_version SET xml_doc = REPLACE(xml_doc, "http://old.example.com/", "http://new.example.org/");
  1. If you have forums enabled, you may want to do a similar replacement on forum contents, in case users posted links to their computers or similar.
  2. Start the project, send some test workunits, and make sure everything is working.

Home

Clone this wiki locally