From FusionForge Wiki

Developers should also refer to the FusionForge Contribution Guide document, that is present in the sources (see a version here : http://fusionforge-ci.no-ip.org/job/fusionforge-Branch_5_0-full/ws/build/documentation/contribution_guide/contribution_guide.plain.html, built from "src/docs/docbook/docbook/contribution_guide/contribution_guide.xml")

Below is a few things to know about how the code works. Far from complete.

Contents 1 Internationalisation 2 Database access 3 URLs and links 4 Authentication 5 Permissions 5.1 Up to 5.0 5.2 Starting with 5.1 6 exit functions API 7 System security 7.1 Processes 7.1.1 Web server 7.1.2 Cronjobs 7.2 Directories 7.2.1 /opt/gforge 7.2.2 /etc/gforge 7.2.3 /var/lib/gforge 7.3 Potential problems 8 Configuration 9 Plugin development

Internationalisation

i18n in FusionForge is done via the standard Gettext library, with no particular quirks in FusionForge. This makes it a bit unwieldy to use custom/local translations or strings. Lolando has a local branch with code to generate a local translation package that can override the official ones. Need to finish it and commit it to trunk.

Database access

Database queries go through the db_query_params() method (db_query() is being deprecated to help get rid of a whole class of potential SQL injection bugs). This is a wrapper around the PostgreSQL database access methods, which passes the variable parts of a query as separate parameters, removing the need for careful escaping and unescaping. To get the full benefits of that, it is important that the query itself be immutable, and all variable parts need to go into separate parameters. For instance, a query counting the groups with a given word in their name or their description should read:

$res = db_query_params ('SELECT count(*) FROM groups WHERE group_name LIKE $1 OR description LIKE $2',
                        array ($word, $word)) ;

Thus, even if $word comes from a malicious user query, it can't do any harm in the database.

Note that this prevents usage of WHERE foo IN (...) constructs if the number of elements in the set is not constant. Fortunately, we can use an alternative way, with the WHERE foo = ANY($1), with the values built with the db_string_array_to_any_clause() or db_int_array_to_any_clause() methods:

$values = array (1, 2, 5, 8) ;
$res = db_query_params ('SELECT foo FROM bar WHERE col = ANY($1)',
                        array (db_int_array_to_any_clause($values))) ;

URLs and links

As described in FusionForge/Suggestions/URL relocation, URLs to pages in the forges should always be generated by the util_make_url() function. This allows to keep the URL scheme in a single point, so that individual pages don't have to know or care whether the forge runs in its own virtualhost, or on SSL, or in a subset of the URL space within a vhost, and so on.

util_make_link() can be used to generate links rather than just URLs, with extra parameters to add attributes to the <a ...> element in the generated HTML. A use case is to add a class for CSS styling.

Authentication

The authentication uses an MD5 password stored in the database by default, but a hook allows to override that with a plugin (see ldapextauth for an example).

Permissions

Up to 5.0

The permission model is RBAC, role-based access control. 'Users' are members of any number of 'groups'. Each membership of a user in a group has a 'role', possibly shared by several users in a group. Each role is specific to a group (no cross-group sharing currently), and it has a set of 'role settings' which are permission bits for the members of the role on the tools of the group.

There is a global admin "role" given to all users member of the admin project, there is no premission control on this user that can add/remove all permissions he wants

There is a specific admin role given to the project admin, each project creator is by default project admin, he can manage roles for other users, give or remove admin role, design new roles, add/remove users of the group he is admin.

Starting with 5.1

The RBAC model has been extended to make it more powerful and flexible. The model and the API are documented on the Planetforge wiki. The main differences are that a user can have several roles inside a project, there are global roles not attached to a project in particular, and a project can reference external roles (global or belonging to another project) and grant them permissions.

Plugins can define new permissions, and these permissions will be managed by the same page editing the permissions for the traditional tools. See the Mediawiki plugin for an example, in particular the places involving the PluginSpecificRoleSetting class.

exit functions API

The current exit API is described in www/include/exit.php main exit function is exit_error :

function exit_error($text="", $toptab=)

$text is the error message to be display, $toptab is where you want user to land with the error message. There are some wrappers above exit_error :

function exit_permission_denied($reason_descr=,$toptab=)

which call the login system if you're not logged or call exit_error

function exit_no_group()

no params needed

function exit_missing_param($url=,$missing_params=array(),$toptab=)

url should be HTTP_REFERER or any URL you like. missing_params is an array that will be append to the standard error message Missing required parameters

function exit_disabled($toptab=)

to be used when specific functionnality is disabled

function exit_form_double_submit($toptab=)

to be used when double click on submit button. Need to be rethink... I presume.

System security

This describes the concepts of FusionForge that shall ensure security of the underlying server. It describes

• what the different components of FusionForge should do or not do,
• what exceptions currently exist,
• and what technical measures are taken to ensure this.

Processes

Web server

• should not write to the filesystem directly
• if any write access is required, only write to /var/lib/gforge
• should only read and write the database
• Technical measures:
  • web server runs as user www-data
  • user www-data has usually no write access anywhere
  • only where required, write access can be granted (explicitly?) by the admin
• Exceptions: ftp upload, some plugins

Cronjobs

• should write only in /var/lib/gforge
• Technical measures:
  • cronjob runs as user root
  • most jobs restrict permissions to user gforge
  • user gforge can only write to /var/lib/gforge
• Exceptions:
  • pluginman:
    • creates links in /opt/gforge/www/plugins
    • creates links in /etc/gforge/plugins
  • configman:
    • modifies /etc/gforge/local.inc

Directories

/opt/gforge

• contains source code of FF
• server admin should not have to modify anything here (to simplify updates)
• modified only by FF developers
• Exceptions:
  • Links in /opt/gforge/www/plugins are set up by pluginman
  • Some plugins require modifications

/etc/gforge

• contains configuration files of FF
• modified by server admin
• FF code should not modify anything here (to simplify updates)
• Exceptions:
  • pluginman creates links here
  • configman modifies local.inc
  • setup autogenerates files here (e.g. httpd.conf)
• Technical measures: no write permissions for www-data or gforge

/var/lib/gforge

• contains files required by the current state of FF
• modifed by cronjobs
• Exceptions:
  • ftp upload
  • mediawiki upload
  • Other plugins?
• Technical measures:
  • write permissions for user gforge
  • no write permissions for user www-data

Potential problems

• Root cronjob is potentially dangerous
  • Possible solution: run cronjob as user gforge, use sudo when root access is required
  • More control over root jobs by admin
• Configman writes central config file that contains paths etc.!

Configuration

Configuration was previously accessed through a mess of global variables. This is being deprecated in favour of a (hopefully) clean API:

• forge_get_config(name [, section]): get value of variable "name" in section "section" (defaults to "core");
• forge_define_config_item(name, section, default): define a new configuration item with given name/section and default value;
• forge_set_config_item_bool(name, section): tag the variable as boolean, which allows human-readable values in the configuration files (such as yes, true, on and 1; anything else is mapped to false)
• forge_read_config_file(file): read a *.ini file and inject its contents into the configuration.
• forge_read_config_dir(path): read all configuration files in a directory.

See Configuration for more details on existing configuration variables.

For shell scripts, there's also a forge_get_config command that behaves like its counterpart in the PHP API: it loads the configuration and prints out the value of the requested variable.

Plugins are encouraged to store their configuration into a pluginname.ini config file, within a section called pluginname. See examples in the existing plugins.

Migration from the previous system can be performed with the migrate-to-ini-files.sh script.

Plugin development

See src/docs/README.Plugins.

---

See also Development environment.