The teamforge.py Script

Overview

Use the teamforge script wherever applicable as it subsumes the functions of the following legacy TeamForge scripts:

• bootstrap-data.sh
• bootstrap-data.py
• bootstrap-reporting-data.sh
• bootstrap-reporting-data.py
• create-runtime.py
• collabnet
• migrate.py
• post-install.py
• snapshot.py

Starting from TeamForge 17.8, /opt/collabnet/teamforge/bin/teamforge has been linked to /usr/bin. You can simply run the teamforge command from any path.

Run the teamforge script with the following syntax:

teamforge [command] [-s serviceName] [other parameters]

For example, the following command displays the status of all the services:

teamforge status

TeamForge components and services

Components

TeamForge comprises of a set of components such as ctfcore, subversion, james, and so on. Some components are always required to be installed, while some are optional. By delivering these components over multiple RPMs, we make sure that users do not have to install everything all the time. Though this is valuable, RPMs alone prove insufficient to manage the components and their inter-dependencies.

• Some components do not have a physical representation but are configuration-only.
• RPM dependencies are restricted to the local machine only; however, in a distributed installation, dependencies between components must be tracked across servers.

In addition to the physical componentization (using RPMs), there is also a need for a logical componentization of TeamForge.

Services

Services represent a logical component of TeamForge. Such a logical component may either be a feature, which the user explicitly opts to install (for example, Review Board) or a technical component (for example, Apache and Logrotate), which other services depend on. Services come with additional metadata, which makes it possible to track and manage dependencies to a more fine-grained level.

• Deployment dependencies specify which other services need to be deployed locally.
• Provided Endpoints specify which network endpoints the service offers.
• Required Endpoints specify which network endpoints the service depends on.

In general, services are more fine-grained than RPMs and it is common to have a single RPM containing multiple services.

Service Life Cycle

A service can be in one of the following states:

• Uninstalled: A service is uninstalled if the RPM that contains it is not installed. Uninstalled services do not exist as far as TeamForge is concerned.
• Undeployed: The RPM containing the service is installed, but the service has not been deployed yet. Deployment is also referred to as "creating the runtime", but is specific to one service.
• Dependencies unavailable: The service itself might be available, but at least one of its deployment dependencies is not in "Available" state.
• Available: Service is fully functional.

Services that manage data have the following additional states:

• Not bootstrapped: Data structures have not been initialized yet.
• Not migrated: Data structures are initialized, but data needs to be migrated.

Services that have a daemon have the following additional states:

• Dependencies unavailable: The service itself might be available, but at least one of its deployment dependencies is not in "Available" state.
• Ports Blocked: The service is impeded from starting up because at least one of the ports it needs is in use by a different process.
• Stopped: Service is an auto start-type service, yet is stopped.
• Inactive: Service is a demand start-type service and is stopped.
• Starting: Service is in the process of starting up.
• Available: Service is running and healthy according to its health check.
• Unhealthy: Service is running but unhealthy according to its health check.
• Dead: Service is supposed to be running, but the process disappeared.
• Doomed: Service is technically running, but it will never work properly because some part of it failed to initialize properly.
• Stopping: Service is in the process of stopping.

Parameters

teamforge.py script accepts the following command line parameters:

[-s | --service]

Use the -s parameter to selectively act on a specific service or component such as selectively start, stop, bootstrap, backup and restore a specific service. For example, the following command gets you the status of Jboss:

teamforge status -s jboss

[-f | --site_options_file]

Use the -f parameter to pass the site-options.conf file's path as a command line parameter (default is /opt/collabnet/teamforge/etc/site-options.conf).

[--skip-verification]

Pass this parameter if you want to skip environment verification.

[-y | --yes]

Pass this parameter if you want to skip confirmation prompts.

[-p | --path]

The path to the backup or restore directory. Used with the teamforge backup and teamforge restore commands.

Commands

The teamforge script can perform the following actions:

status

Show status of all services. Use the -s parameter to know the status of a specific service.

bootstrap

Bootstrap data (re-create data structures). Use the -s parameter to selectively bootstrap a specific component. Suppose, you did not have SVN on your TeamForge site and if you add SVN while upgrading to TeamForge 16.10 or later. You can now selectively bootstrap SVN alone.

deploy

Deploy service(s).

migrate

Migrate data to latest schema.

provision

Provision/reprovision the server. The provision command performs tasks such as creating the runtime, starting and stopping services, bootstrapping (fresh install) or migrating (upgrade) data, deploying services, setting file permissions, setting SELinux permissions, initializing services and so on.

undeploy

Undeploy service(s).

start

Start service(s).

stop

Stop service(s).

kill

Terminates service(s) forcefully.

verify

Verify environment.

show-endpoints

Show endpoints

show-dependencies

Show deployment dependencies

reinitialize

Reinitializes all the TeamForge services

apply-permissions

Applies the TeamForge file system permissions when you restore the TeamForge data in a new server while upgraing to a latest TeamForge version.

snapshot

Dumps relevant diagnostic information to the console (stdout) for each deployed service.

info

Displays a summary of TeamForge configuration.

check-data-integrity

Verifies the integrity of the data defined in the service manifest.

update-data-integrity

Updates the calculated checksums for the data defined in the manifest.

await-dependencies

Waits for dependencies to become available.

apply-selinux

Applies selinux policies.

unload-selinux

Unloads selinux policies.

logs

Tails log files.

backup

Back up TeamForge data. The -p parameter is mandatory. For more information, see Back up and Restore TeamForge Data Using the teamforge.py Script.

restore

Restore TeamForge data. The -p parameter is mandatory. For more information, see Back up and Restore TeamForge Data Using the teamforge.py Script.

teamforge reload

The teamforge reload command comes in handy when you want to quickly bring up the site after modifying some of the frequently-used site-options.conf tokens. Certain site-options.conf tokens, when modified, require stopping, deploying, restarting and initializing certain services. Instead of restarting the whole site, the teamforge reload command, depending on the tokens that are modified, restarts only the services that need a restart, while keeping the site up for other services.

The following table lists the tokens with which you can use the teamforge reload command and the services that are restarted when you change those tokens.

When you modify these tokens...	This is what teamforge reload does...
PGSQL_SHARED_BUFFERS= PGSQL_WORK_MEM= PGSQL_FSYNC= PGSQL_COMMIT_DELAY= PGSQL_COMMIT_SIBLINGS= PGSQL_EFFECTIVE_CACHE_SIZE= PGSQL_RANDOM_PAGE_COST= PGSQL_MAINTENANCE_WORK_MEM= PGSQL_LOG_MIN_DURATION=	1. Stop PostgreSQL. 2. Deploy PostgreSQL. 3. Start PostgreSQL.
JAMES_GATEWAY_HOST= JAMES_GATEWAY_PORT= PHOENIX_JAVA_OPTS=	1. Stop Phoenix. 2. Deploy Mail. 3. Start Phoenix. 4. Initialize Mail.
ETL_JOB_TRIGGER_TIME= ETL_JAVA_OPTS=	1. Stop ETL. 2. Deploy ETL. 3. Start ETL. 4. Initialize ETL.
ENABLE_SERVICE_MONITORING= SERVICE_MONITOR_RETRIES= MONIT_CHECK_INTERVAL=	1. Stop Monit (service-monitor). 2. Deploy Monit (service-monitor). 3. Start Monit (service-monitor).
SESSION_TIMEOUT= JBOSS_JAVA_OPTS= MAX_WWW_CLIENTS= USER_RESOURCE_CACHE_MAX_SIZE_LIMIT= ADHOC_QUERY_RESULTS_LIMT= ADHOC_QUERY_CONNECTION_TIMEOUT= PASSWORD_EXPIRY_PERIOD= PASSWORD_DISABLE_PERIOD= PASSWORD_WARNING_PERIOD= PASSWORD_DELETE_PERIOD= PASSWORD_CONTROL_EFFECTIVE_DATE=	1. Stop Jboss. 2. Deploy Jboss and ctfcore-app. 3. Start Jboss. 4. Initialize the ctfcore-app service.

Back up and Restore TeamForge Data Using the teamforge.py Script

Use the teamforge.py script's backup and restore commands to back up and restore TeamForge data.

Back up and Restore TeamForge

If you are upgrading to a latest TeamForge version, it is still recommended to follow the [usual backup and restore procedure][backupandrestore]. Use the teamforge.py script's backup and restore commands if you want to back up a particular service such as SVN and restore it on a new server (when you intend to move a specific service from one server to another, typically to move the service to a dedicated server of its own).

If you are backing up TeamForge as a whole, you must stop all the TeamForge services but PostgreSQL before running the teamforge backup and teamforge restore commands.

1. To back up TeamForge data:

   teamforge stop
   teamforge start -s postgres
   teamforge backup -p \<path to the directory where the data is backed up\>
2. Compress the backed up data and copy it to the target server where you want to restore the data.
3. To restore TeamForge data:

   teamforge stop
   teamforge start -s postgres
   teamforge restore -p \<path to the directory where you have the data to be restored\>

4. Provision services.

   teamforge provision

Back up and Restore a Specific Service

1. To back up a specific service (such as SVN):

   teamforge backup -s \<serviceName\> -p \<path to the directory where the data is backed up\>
   For example:

   teamforge backup -s svn -p /tmp/svnbackup
2. Compress the backed up data and copy it to the target server where you want to restore the data.
3. To restore a specific service's data:

   teamforge restore -s \<serviceName\> -p \<path to the directory where you have the data to be restored\>
   For example:

   teamforge restore -s svn -p /tmp/svnbackup

4. Provision services.

   teamforge provision

Did You Back up symlinked Directories?

Do this if and only if you had backed up and restored symlinked directories.

1. Move the svnroot, cvsroot and sf-svnroot directories from /opt/collabnet/teamforge/var/scm to the root directory.

   cd /opt/collabnet/teamforge/var/scm
   mv svnroot cvsroot sf-svnroot /

2. Create symlinks to the root directory.

   ln -s /sf-svnroot .
   ln -s /svnroot .
   ln -s /cvsroot .

3. Provision TeamForge.

   teamforge provision -y

4. Apply the TeamForge file system permissions.

   teamforge apply-permissions

Logging

The teamforge script writes entries to /opt/collabnet/teamforge/log/runtime/runtime.log file.