Chapter 3 Installation

Tinderbox now determines where to do all of its work relative to the location of the tc program, passed around to other functions by means of the ${pb} environmental variable (think: package build). Historically, this was the /space/ directory (tc was usually found in /space/scripts/tc).

Henceforth, the top-level directory will be referred to as ${pb}, which you should substitute for whatever root directory you're using.

  1. Create directories ${pb} and ${pb}/scripts/.

  2. Extract the Tinderbox distribution into ${pb}/scripts/.

  3. Run tc to setup configuration files and initialize the Tinderbox database:

    # cd ${pb}/scripts && ./tc Setup

    If you are going to be using the web front-end, edit webui/inc_ds.php.dist for your database setup. Then copy this file to inc_ds.php.

    Note: On a new installation of PHP, it is important to define your default timezone in /usr/local/etc/php.ini, otherwise you will encounter errors while using the frontend.

    If your Tinderbox host does not have administrative access to the database server, you must perform the next few steps by hand. Else, skip to step 6. Since any user may create a SQLite database, users of SQLite can skip to step 5.

    Note: If you are going to be using the web front-end with SQLite, you should be sure to keep the database in a directory to which the www user has write permissions.

  4. Create the database and database user on the host that you defined within ds.ph.

    Tip: The database can live on the same server as Tinderbox. Just set $DB_HOST to localhost in ds.ph. The tinderbox user must be granted the following permissions on the Tinderbox database (for security purposes no other permissions should be granted) [MySQL only]:

    • Select_priv

    • Insert_priv

    • Update_priv

    • Delete_priv

    For PostgreSQL users, make sure the Tinderbox user owns the Tinderbox database as well as all the tables within that database.

    SQLite users need not do anything for this step.

  5. Populate the database with the Tinderbox schema:

    MySQL:

    # cd sql
    # ./genschema mysql | mysql -u{DB_ADMIN} -p -h {DB_HOST} {DB_NAME}

    PostgreSQL:

    # cd sql
    # ./genschema pgsql | psql -U {DB_USER} -W -h {DB_HOST} -d {DB_NAME}

    SQLite:

    # cd sql
    # ./genschema sqlite | sqlite3 {DB_NAME}

    Where {DB_HOST} and {DB_NAME} are the values of $DB_HOST and $DB_NAME from ds.ph respectively, {DB_ADMIN} is the database administrator username, {DB_USER} is the Tinderbox user, and {DB_NAME} is the name of the desired SQLite database file, including the desired full or relative path.

    Caution: Do not do this if you are upgrading! If you do, you will overwrite all of your previous data. If schema changes are required for upgrading, a separate upgrade schema file will be included, and instructions will be available at http://tinderbox.marcuscom.com.

  6. Edit ${pb}/scripts/tinderbox.ph.dist for your environment (if you are using the web front-end, also edit webui/inc_tinderbox.php.dist). Once these files have been edited they must be copied to tinderbox.ph and inc_tinderbox.php respectively.

  7. Initialize the Tinderbox:

    # cd ${pb}/scripts && ./tc init
  8. Tinderbox can use either NFS or nullfs to mount the required file systems within the build chroots (called Builds in Tinderbox). If you wish to use nullfs, skip to step 11.

  9. Setup the Tinderbox server as an NFS server by adding the following to /etc/exports:

    ${pb} -alldirs -maproot=0:0 localhost

    Important: ${pb} CANNOT be a symlink. It should be a real, fully qualified path (hint: use realpath on your desired ${pb} to find out what this needs to be).

  10. Add the following to /etc/rc.conf to enable the NFS client and server:

    nfs_client_enable="YES"
    nfs_server_flags="-u -t -n 20"
    rpcbind_enable="YES"
    nfs_server_enable="YES"
    nfs_reserved_port_only="YES"
  11. Create the required Jails using the tc command. A Jail is nothing more than a version of FreeBSD. For example, to create a Jail for FreeBSD 9.2-RELEASE:

    # cd ${pb}/scripts && ./tc createJail -j 9.2 -d "FreeBSD 9.2-RELEASE" \
      -D base/release/9.2.0 \
      -u SVN -H svn.FreeBSD.org -P https

    or

    # cd ${pb}/scripts && ./tc createJail -j 9.2 -d "FreeBSD 9.2-RELEASE" \
      -t 9.2-RELEASE -u LFTP -H ftp.freebsd.org

    The first method will download source via svn and use make world to compile a complete FreeBSD installation.

    The second method will instead download binary release sets (used on CDs) and install them, making the process much shorter. As the command suggests, the second method requires lftp (ftp/lftp) to be installed. You need to specify what release (not the Subversion tag, as opposed to the first method) you want to download with the -t option. Also note that you need to provide an FTP server to download the sets from (with the -H option).

    Important: All Jail names MUST begin with their FreeBSD major version number. That is, the following is an illegal jail name: FreeBSD-9.2.

    Tip: It is recommended that the Jail begin with the FreeBSD major.minor version (i.e. 9.2-FreeBSD instead of just 9-FreeBSD) as this may prove useful when using things such as Hooks (Section 8.8).

  12. Create the required PortsTrees using the tc command. A PortsTree is a set of ports you wish to build. A PortsTree does not have to be a complete FreeBSD ports tree. However, all ports within a tree must have all of their dependencies within the same tree.

    For example, to create a portstree that tracks the full FreeBSD ports tree:

    # cd ${pb}/scripts && ./tc createPortsTree -p FreeBSD \
      -d "FreeBSD ports tree" \
      -u SVN -P https -H svn.FreeBSD.org -D ports/head
      -w http://svnweb.FreeBSD.org/ports/
  13. Create the required Builds using the tc command. A Build is a combination of a Jail and a PortsTree. The build is the object in which packages are created. To create a build that combines a 9.2 Jail with the FreeBSD ports tree:

    # cd ${pb}/scripts && ./tc createBuild -b 9.2-FreeBSD -j 9.2 \
      -p FreeBSD -d "9.2-RELEASE with FreeBSD ports tree"

    Note: the recommended way to name Builds is Jail-PortsTree. All builds must also begin with their FreeBSD major version number.

Tip: It is possible to suppress spurious setuid warnings from periodic if ${pb} is on a dedicated partition. Simply add the nosuid flag to the partition; for UFS in /etc/fstab:

/dev/ad5s1f  /usr/local/tinderbox  ufs  rw,nosuid  1  1

and for ZFS:

# zfs set setuid=off $(zfs list ${pb} | tail -n 1 | cut -d ' ' -f 1)