Instalación Basica e Intrucciones de Uso

Obteniendo Tinderbox

La ultima version de Tinderbox puedes descargarla desde http://tinderbox.marcuscom.com.

Tinderbox esta alojado en el Repositorio CVS de Marcus bajo el modulo de portstools.

Requerimientos

Una version reciente de FreeBSD (el desarrollo se realiza solo en -CURRENT, pero sabemos que Tinderbox tambien trabaja en RELENG_6 y RELENG_7), Perl 5.8 o superior (lang/perl5.8), el modulo de Perl DBD::Mysql (databases/p5-DBD-mysql41), y MySQL 4.1 o superior (databases/mysql41-server).

El front-end web requiere php4 (lang/php4), la extension php4-mysql (databases/php4-mysql), y PEAR::DB (databases/pear-DB).

El front-end web estandar (Se encuentra en el subdirectorio www ) y requiere que tengas la variable "register_globals=on" en tu php.ini. El front-end web experimental (Se encuentra en el subdirectorio www-exp) esto no requiere que la variable register_globals sea igual a on, pero requiere de la extension php4-session (www/php4-session).

Instalación

Por defecto, Tinderbox realiza todo su trabajo en la carpeta /space. Sin embargo, esto es completamente configurable. Sigamos adelante, la carpeta /space sera referenciado con ${pb} (pb = package build). Si tu estas usando un directorio root alterno para Tinderbox , puedes sustituir ${pb} con el nombre de ese directorio.

  1. Creamos los directorios ${pb} y ${pb}/scripts.
  2. Extraemos la distribución de Tinderbox dentro de ${pb}/scripts.
  3. Ejecutamos ${pb}/scripts/setup.sh para configurar los archivos de configuracion e inicializar la base de datos de Tinderbox.
    # cd ${pb}/scripts && ./setup.sh
    Si tu Tinderbox no tiene acceso administrativo al servidor de base de datos, debes realizar los siguientes pasos a mano. Caso contrario, podemos saltar al paso 7.
  4. Edita ${pb}/scripts/ds.ph para tu configuración (Si estas usando el front-end web estandar, tambien edita www/inc_ds.php).
  5. Crea la base de datos y el usuario, en la base de datos del host que se definio en el archivo ds.ph. Nota: la base de datos puedes estar en el mismo servidor que Tinderbox. Ahora define $DB_HOST a localhost en ds.ph. El usuario de Tinderbox debera tener los siguientes permisos en la base de datos (Por razones de seguridad no se deberia conceder otros permisos):
  6. Llenamos la base de datos con el esquema de Tinderbox:
    mysql -uroot -p -h {$DB_HOST} {$DB_NAME} &< tinderbox.schema
    Donde {$DB_HOST} y {$DB_NAME} son los valores de $DB_HOST y $DB_NAME en el archivo ds.ph respectivamente. Nota: no hacer esto si se esta actualizando! Si lo haces, podrias sobreescribir la data actual. Si hubiera algun cambio en el esquema esto necesitaria de una actualización, y un archivo de esquema seria incluido para actualizar, y las instrucciones de como hacerlo estaran disponibles en
    http://tinderbox.marcuscom.com.
  7. Edita ${pb}/scripts/tinderbox.ph para tus necesidades.
  8. Inicializa Tinderbox:
    # cd ${pb}/scripts && ./tc init
  9. Tinderbox puede utilizar NFS o nullfs para montar los sistemas de archivos esto requiere las estructuras chroot (llamadas Builds en Tinderbox). Si tu eliges usar nullfs, salta al paso 12.
  10. Para configurar Tinderbox como un NFS server agregamos lo siguiente en el archivo /etc/exports:
    ${pb} -alldirs -maproot=0:0 localhost
    Nota: ${pb} NO PUEDE SER un enlace simbolico. Tiene que ser un real fully-qualified path.
  11. Agregamos lo siguiente al archivo /etc/rc.conf para habilitar el cliente y servidor NFS:
    nfs_client_enable="YES"
    nfs_server_flags="-u -t -n 20"
    rpcbind_enable="YES"
    nfs_server_enable="YES"
    nfs_reserved_port_only="YES"
  12. Creamos los jails que necesitamos utilizando el comando ${pb}/scripts/create. Un jail no es nada mas que una version de FreeBSD. Por ejemplo, para crear un jail para FreeBSD 6.3-RELEASE:
    # cd ${pb}/scripts && ./create Jail -j 6.3 -d "FreeBSD 6.3-RELEASE" -t RELENG_6_3_0_RELEASE -u CVSUP
    Nota: todos los nombres de los jails TIENEN que empezar con el numero de version de FreeBSD. Lo siguiente es un nombre ilegal de un jail: FreeBSD-6.3.
  13. Creamos el PortsTrees que necesitamos utilizando el comando ${pb}/scripts/create. Un PortsTree es un grupo de ports que uno selecciona para construir las aplicaciones. El PortsTree no tiene por que ser el arbol completo de ports de FreeBSD. Sin embargo, todos los ports en el arbol deben tener sus respectivas dependencias en el mismo arbol.
    Por ejemplo , para crear un PortsTree de un arbol completo de ports de FreeBSD:
    # cd ${pb}/scripts && ./create PortsTree -p FreeBSD -d "FreeBSD ports tree" -w http://www.freebsd.org/cgi/cvsweb.cgi/ports/
  14. Creamos la estructura requerida usando el comando ${pb}/scripts/create. Una estructura es una combinación de Jails y PortsTree. La estructura es el lugar donde los paquetes son creados. Para crear y construir los paquetes se combina un 6.3-RELEASE Jail con el arbol de ports de FreeBSD:
    # cd ${pb}/scripts && ./create Build -b 6.3-FreeBSD -j 6.3 -p FreeBSD -d "6.3-RELEASE with FreeBSD ports tree"
    Nota: la manera recomendada para nombrar las Estructuras es Jail-PortsTree. Todas las estructuras tienen que empezar con el numero de versión de FreeBSD.

NOTA: El script de creación usa cvsup12 como el mirror cvsup por defecto. Si te gustaria usar otro server, habilita la compresión cvsup, o usa un programa alternativo de cvsup, utilizando los parametros en linea de comandos -H, -C, y -P con el script create. Por ejemplo, para usar cvsup2.freebsd.org, habilita la compresión cvsup, y usa csup en vez de cvsup para todo Las actualizaciones del jail, usan el siguiente comando:
# cd ${pb}/scripts && ./create Jail -j 6-STABLE -d "FreeBSD 6-STABLE" -t RELENG_6 -u CVSUP -C -H cvsup2.freebsd.org -P /usr/local/bin/csup

Actualizando

Tinderbox puede esperimentar una variedad de cambios entre versiones. Para estar seguro que Tinderbox quedara totalmente funcional despues de una actualización, tenemos que ejecutar el comando ${pb}/scripts/upgrade.sh:
# cd ${pb}/scripts && ./upgrade.sh

Nota: Este comando necesita privilegios administrativo a la base de datos. Si no tienes acceso disponible desde tu Tinderbox, tu tienes que cargar el archivo de actualización del esquema de la base de datos. El archivo script de actualización contendra intrucciones si las necesitaras.

Utilizando Tinderbox

Para ejecutar un Tinderbox build, y que guarde el progreso en la base de datos, tu tienes que agregar primero el port que tu quieres construir en la base de datos utilizando la aplicación ${pb}/scripts/tc :
# cd ${pb}/scripts && ./tc addPort -b {BUILD} -d {PORT DIRECTORY} -r

Donde {BUILD} es el nombre de la estructura del port que tu deseas construir, y {PORT DIRECTORY} es el directorio dentro del PortsTree donde el port puede ser encontrado. Por ejemplo, para construir el port GNOME 2 Desktop 6.3-FreeBSD:
# cd ${pb}/scripts && ./tc addPort -b 6.3-FreeBSD -d x11/gnome2 -r

Nota: un port no tiene que ser agregado a la base de datos para que Tinderbox construya esto. Si tu quieres hacer una construccióm de una manera rapida, olvida lo mencionado en el paso anterior.

Para empezar una construcción en Tinderbox, usa el comando ${pb}/scripts/tinderbuild:
# cd ${pb}/scripts && ./tinderbuild -b {BUILD} {PORT DIRECTORY}

Por ejemplo, para construir el GNOME 2 Desktop por la estructura 6.3-FreeBSD:
# cd ${pb}/scripts && ./tinderbuild -b 6.3-FreeBSD x11/gnome2

TIP: El ejemplo permite ejecutar una construcción en modo foreground con todos los mensajes y errores mostrandose en el terminal. Para capturar todo esto, se recomienda redireccionar la salida de tinderbuild hacia un archivo log. Por ejemplo:

El script tinderbuild tambien acepta algunos argumentos adicionales en linea de comandos:

-init Actualiza la Jaula y la Estructura
-nullfs Utiliza nullfs en vez de NFS para montar el Jail y el PortsTree file systems
-cleanpackages Remueve todos los paquetes construidos en una determinada Estructura
-updateports Actualiza el PortsTree de las Estructuras (NOTE: Peligroso si realizas ejecuciones paralelas con el mismo PortsTree)
-skipmake Salta la generación de Makefile (NOTA: usa solo esta opcion si existe un buen Makefile)
-noduds Salta el duds file generation stage (NOTA: los paquetes son prohibidos o ignorados para ser construidos)
-noclean No limpia la estructura jerarquica despues que un port ha finalizado de construirse.
-plistcheck Realiza la verificacion de problemas fatales en plist (e.g. Archivos faltantes)
-cleandistfiles Quita todos los archivos y directorios en el distfile cache antes de comenzar una construcción
-fetch-original Ignora el distfile cache, y vuelve a traer todos los distfiles desde sus respectivos sources
-nolog Desabilita el codigo de analisis de logs
-trybroken Construye los ports marcados como BROKEN (NO requiere -noduds)
-jobs Empieza n numeros de construcciones de ports paralelas (NOTA: por defecto es 1, y para mejores resultados no debe exceder el numero de CPUs fisicos que tiene nuestro Tinderbox)
-onceonly Realiza solo un paso en la construcción (i.e. tinderbuild Fase 1)

Mantenimiento

Para actualizar los Jails existentes , usa el comando ${pb}/scripts/mkjail. Por ejemplo:
# cd ${pb}/scripts && ./mkjail 6.3

La salida de la estructura del Jail ira hacia el stdout. La salida de el comando de actualización (e.g. cvsup) ira hacia ${pb}/jails/{JAIL}/update.log (donde {JAIL} es el nombre del Jail en cuestion).

Para actualizar un existente PortsTrees, usa la aplcaición tc (Tinderbox Controller) con el comando updatePortsTree. Por ejemplo:
# cd ${pb}/scripts && ./tc updatePortsTree -p FreeBSD

Cada cierto tiempo, los archivos de log y paquetes antiguos pueden estorbar en las Estructuras. Para limpiar los archivos antiguos, sin referencia, usa la aplicación ${pb}/scripts/tc con el comando tbcleanup:
# cd ${pb}/scripts && ./tc tbcleanup

Troubleshooting

Si encontraras problemas en Tinderbox, esto puede ayudarte a mirar que esta sucediendo dentro de una Estructura. Los logs operacionales de Tinderbox pueden ser encontrados en ${pb}/builds/{BUILD} (donde {BUILD} es el nombre de la Estructura). Aqui es donde las salidas de Tinderbox son redireccionadas (mira acerca de Utilizando Tinderbox). Los logs make.0 y make.1 contiene la configuración inicial de construcción por cada port. La razon de estos dos logs es que tinderbuild se ejecuta en dos fases. La segunda fase es identica a la primera , y esto se ejecuta para capturar problemas transitorios que pudieron ocurrir en la primera fase.

El archivo log completo de construcción por cada port son copiados hacia ${pb}/logs/{BUILD} (donde {BUILD} es el nombre de la Estructura). Si el port falla y no se construyo con exito, el log tambien sera copiado hacia ${pb}/errors/{BUILD} (donde {BUILD} es el nombre de la Estructura).

Algunas veces, el log no es suficiente para saber el porque la construcción de un port falla. En algunos casos, uno tiene que ver el directorio work del port. Para que Tinderbox grabe esto, crea un archivo vacio llamado .keep en el directorio del port, y el directorio work sera empaquetado, comprimido, y copiado hacia ${pb}/wrkdirs/{BUILD} (donde {BUILD} es el nombre de la Estructura).

Cuando empieza a ser dificil calcular el problema en el wrkdir puede ser necesario acceder a la construcción uno mismo. Para hacer esto, coloca un archivo llamado .sleepme en el directorio del port. Cuando el archivo .sleepme es detectado por el sistema de construcción, la construcción del port se suspendera antes de ejecutar make build. Tu puedes acceder a la estructura con el comando:
# cd ${pb}/scripts && ./enterbuild -b {BUILD} -d {PORT_DIRECTORY}

Cuando finalices, quita el archivo .sleepme, y la construcción del port continuara.

Advanced Topics

Montajes Alternativos

Si tu quieres montar /ports dentro de tu PortsTree o /src dentro de tu Jail via nullfs o NFS desde otra ubicación , usa -m para cambiar la creación.
Ejemplo para NFS:
./create PortsTree -p FreeBSD -m server:/directory
./create Jail -j 6-FreeBSD -m server:/directory

Ejemplo para nullfs:
./create PortsTree -p FreeBSD -m /directory
./create Jail -j 6-FreeBSD -m /directory

Tinderbuild se asegurara que el file system este correctamente montado para que no se necesite hacerlo uno mismo antes de llamar a tinderbuild.

Si tu quieres hacer cambios despues en la configuración, usa:
./tc setPortsMount -p <portstreename> -m <mount path>
./tc setSrcMount -j <jailname> -m <mount path>

Distfile Caching

Tener los archivos distfiles en un repositorio local puede traer grandes mejoras en el tiempo de construcción. Tanto como suficiente espacio en el disco, habilitar un local (o NFS) distfile cache es facil. Usa el siguiente comando:
./tc configDistfile -c <mount point>

Donde <mount point> puede ser un especificacion NFS, o un fully qualified path (en el cado de nullfs) en donde se descargaran y ubicaran los archivos distfiles. Por ejemplo:

NFS:
./tc configDistfile -c localhost:/space/distfiles

nullfs:
./tc configDistfile -c /d/distfiles

Utilizando Ccache

Otra excelente manera de acelerar las construcciones es utilizando el compiler cache, ccache. Para usar el soporte de ccache, deberas primero crear un archivo tar con ccache y varios enlaces simbolicos en un directorio llamado /opt. Tu tarball contendra lo siguiente:

opt
opt/ccache
opt/gcc -> ccache
opt/cc -> ccache
opt/g++ -> ccache
opt/c++ -> ccache

Este archivo tarball se llamara ccache.tar, y sera ubicado en el directorio del Jail por cada una de los Jails que utilicen ccache (e.g. ${pb}/jails/6.3).

Cuando el primer tarball es creado, ejecute (-e para habilitarlo, -d para desabilitarlo, -c especificara el directorio, y -s maximo tamaņo):
./tc configCcache -e -c /ccache -s 2G

Entonces ejecuta tus construcciones normalemnte. Para realizar un debug a ccache, agrega -l /ccache.log para cambiar el comando.

Encontes , en el root de cada directorio de construcci&ocute;n, deberias tener un archivo ccache.log, esto te hara saber si el cache esta trabajando.

Automating/Queuing Port Builds

Si tu quieres usar tinderbox para probar diferentes ports antes que otros tu probablemente buscas usar tinderd. tinderd se ejcuta como demonio esperando que algunas cosas sean agregadas a la cola de espera para la construcción de ports. Pueds agregar diferentes ports para diferentes construcciones para diferentes hosts con diferentes prioridades. tinderd automaticamente tomara el port con la prioridad mas alta para el host y empezara a construirlo. Esto se repetira hasta que la cola de espera este vacia. Despues que la cola de espera este vacia tinderd se detendra por lapso de tiempo previamente configurado (por defecto: 120 segundos) despues de este tiempo empezara a buscar por nuevos ports en la lista de espera nuevamente. Si necesitas que tinderd verifique la cola de espera antes que el tiempo para detenerse expire, envia el proceso de tinderd a SIGHUP:
# kill -HUP {PID of tinderd}

donde {PID of tinderd} es el ID del proceso del script de tinderd esto puede observarse en la salida de ps(1)

Para configurar esto primero tenemos que agregar un Tinderbox host en la base de datos:
# cd ${pb}/scripts && ./tc addHost

Bien ahora se puede iniciar tinderd (esto estara en foreground por defecto). Si tu quieres iniciar tinderd automaticamente cuando el sistema bootee, copia el script ${pb}/etc/rc.d/tinderd.sh hacia /usr/local/etc/rc.d. Asegurese de revisar el archivo rc.conf y las diferentes variables documentadas en este script antes de usarlo.
Ahora usa:
# cd ${pb}/scripts && ./tc addBuildPortsQueueEntry -b {BUILD} -d {PORT DIRECTORY}

para agregar un port en espera. tinderd automaticamente tomara esto, y ejecutara un tinderbuild en esto, y borrara la entrada despues que tinderbuild complete la construcción. (Donde {BUILD} es el nombre de la estructura, y {PORT DIRECTORY} es un directorio en el PortsTree de {BUILDS}'s (e.g. x11/gnome2).)

NOTA: Puedes utilizar el front-end web www-exp para tomar ventajas de lo siguiente:

Para usar tinderd via web, primero se tiene que crear un Usuario:
# cd ${pb}/scripts && ./tc addUser -u {USER} -e {EMAIL} -p {PASSWORD} -w

(Donde {USER} es un username, {EMAIL} es la direccion email del usuario, y {PASSWORD} es el password del usuario para acceder via web a Tinderbox.)

Si tu quieres habilitar el acceso web para un usuario creado anteriormente, tienes que actualizar la cuenta de usuario asignandole un password para el acceso via web:
# cd ${pb}/scripts && ./tc updateUser -u {USER} -e {EMAIL} -p {PASSWORD} -w

(Donde {USER} es un username, {EMAIL} es la direccion email del usuario, y {PASSWORD} es el password del usuario para acceder via web a Tinderbox.)

Tienes que definir un administrador web administrator quien tenga full derechos en todos los Hosts/Estructuras y sea el unico que pueda agregar otros usuarios:
# cd ${pb}/scripts && ./tc setWwwAdmin -u {USER}

(Donde {USER} es el username del administrador web.)

Despues de esto, podras acceder a la web de Tinderbox con tu web browser y autenticar con tu {USER} y {PASSWORD}. Tu puedes ahora crear y modificar otros usuarios facilmente utilizando los enlaces Add User o Modify User.

$MCom: tinderweb/README-es.html,v 1.3 2008/06/02 06:36:41 ade Exp $