A. The kandoMaintain Utility
   
A. The kandoMaintain Utility
The kandoMaintain utility provides the ability to perform occasional administrative operations under the guidance of an AccuRev Support Services representative. It is similar to the AccuRev maintain utility (see “The ‘maintain’ Utility” chapter of the AccuRev Administrator’s Guide).
Using kandoMaintain
The kandoMaintain utility is located in the bin directory where you installed GitCentric. To use kandoMaintain, the AccuRev database server must be running, but we recommend that you stop the GitCentric server, which you do by shutting down Tomcat, for example:
cd <ac_home>/WebUI/tomcat/bin
./shutdown.sh
All kandoMaintain commands except help require a database administrator user and password. You can enter the user name and password on the command line with the -u and -P options, respectively. If you do not supply these, kandoMaintain will prompt you for them. You can also provide either or both of these values in a text file and provide a path to the file (see the -Fc <path> option).
Note: Providing the database password in a script or in a configuration file can compromise system security. Make sure that such files are protected and not generally accessible.
The commands to make, remove, upgrade, back up, or restore a database (mkdb, rmdb, upgradedb, backupdbs, restoredbs) prompt you to confirm the operation before proceeding. This confirmation prompt can be overridden with the -y option.
Backup and Restore
The kandoMaintain commands to back up and restore the GitCentric database (backupdbs and restoredbs) are described in this appendix. For complete information about the backup and restore process, see Appendix: B Backup and Restore.
kandoMaintain Command Reference
Usage: kandoMaintain [COMMAND] [OPTIONS]
kandoMaintain [ mkdb | rmdb | upgradedb | backupdbs | restoredbs | mvrepos |
           testconn | lsconfig | addconfig | rmconfig | checksync | help ]

           [ -u <dbadmin> -P <dbpass> -c <url> | -Fc <path> ]
Commands
mkdb
kandoMaintain mkdb -u <db_admin> -P <dbpass>
Creates a GitCentric database with the latest schema.
Valid options (see below): -u, -P, -c, -Fc, -y
rmdb
kandoMaintain rmdb -u <db_admin> -P <dbpass>
Removes a GitCentric database
Valid options (see below): -u, -P, -c, -Fc, -y
upgradedb
kandoMaintain upgradedb -u <db_admin> -P <dbpass>
Upgrades a GitCentric database to the latest schema.
Valid options (see below): -u, -P, -c, -Fc, -y, -I
backupdbs
kandoMaintain backupdbs -u <db_admin> -P <dbpass>
Creates a backup of the GitCentric database and writes the backup file to the directory from which the backupdbs command was run; the backup file can be moved to any location after that. Each backup file is given a unique file name, such as kando_<timestamp>.backup, where the timestamp is in the format of yyy-mm-dd_hh:mm:ss:ms (2012-03-16_15:51:11.487, for example).
The backupdbs command uses PostgreSQL pg_dump, which is located in the PostgreSQL /bin directory. Before running backupdbs, make sure that the PostgreSQL /bin directory is specified in your system path.
Valid options (see below): -u, -P, -c, -Fc, -y
 
Note: Micro Focus recommends that you use full_backup.sh and full_restore.sh commands to back up and restore GitCentric. See Appendix: B Backup and Restore for more information.
restoredbs
kandoMaintain restoredbs -u <db_admin> -P <dbpass> -Fb <path>
Restores the backup of the GitCentric database created by the backupdbs command. Use the <path> argument to specify the location of the backup file. By default, the backup file is written to the same directory from which the backupdbs command was run, but it can be moved anywhere.
Valid options (see below): -u, -P, -c, -Fb, -Fc, -y
mvrepos
kandoMaintain mvrepos -u <db_admin> -P <dbpass> -r <destination_path>
Move any Kando 2012.1 repositories from their old storage area to the new GitCentric storage area at <destination_path> (typically <gc_home>/site/git ) after an upgrade installation. mvrepos identifies the old storage area by querying the database.
mvrepos checks that the target path exists and is writable. mvrepos only looks at acrepository records that are not hidden (deleted). If there is a null or empty path in any of the acrepository records, no moves will be attempted. Any of the above conditions will return error messages as well as a return status of 1. During the individual moves and database updates, if a single move fails, the others will still be attempted. There will be error messages for each move that fails and the overall return status will be 1. Therefore, you can rerun this command after fixing a failure condition, so that eventually all repos are moved. If all moves are successful, no message is displayed and a 0 is returned for status.
Valid options (see below): -u, -P, -c, -Fc, -y, -r
testconn
kandoMaintain testconn
Tests the Java Database Connectivity (JDBC) connection to the postgres instance (does not test for the existence of a GitCentric database.
Valid options (see below): -u, -P, -c, -Fc
lsconfig
kandoMaintain lsconfig
Lists the entries from the GitCentric database configuration table. Use -n to list a specific configuration parameter. If -n is not specified, all configuration parameters are displayed.
Valid options (see below): -u, -P, -c, -Fc, -n
addconfig
kandoMaintain addconfig -n <name> -v <value>
Adds a configuration parameter to the GitCentric database configuration table. Returns an error if you specify a name that already exists with -n <name>.
Valid options (see below): -u, -P, -c, -Fc, -n, -v, -m ( -n and -v are required)
rmconfig
kandoMaintain rmconfig -n <name>
Deletes a configuration parameter from the GitCentric database configuration table. (Note: no error is generated if the specific configuration name does not exist.)
Valid options (see below): -u, -P, -c, -Fc, -n ( -n is required)
checksync
kandoMaintain checksync
Verifies that the latest branch-stream synchronization for the specified branch is correct. For the latest shamap entry for the specified branch-stream mapping, checksync returns the sha, stream as string, transaction, timestamp, and operation fields, and identifies any discrepancies between:
• The current branch sha and that shamap entry
• The current stream high water mark (HWM, which is based on the transaction number of the last change made to the content of an AccuRev stream) and that sha map entry
Use the --diff option to compare the contents of each directory, file, and link on Git and AccuRev.
Valid options (see below): -Fc, -r, -b, --diff ( -r and -b are required)
help
kandoMaintain help
Displays usage information.
Valid options (see below): None.
Options
Connection Options
-u <dbadmin> -- The database administration user. This is the same user name as specified during installation (default is “postgres”). If this is required by the command you are using but you do not include it, kandoMaintain prompts you for it.
-P <dbpass> -- The database administration password. This is the same user password as specified during installation. If this is required by the command you are using but you do not include it, kandoMaintain prompts you for it. If you write scripts that incorporate this option, be sure to secure the file against unauthorized access.
-c <dbconnectstring> -- The database connection string:
jdbc:postgresql://<host>:<port>/<dbname>. If you do not specify -c for a command that requires it, kandoMaintain assumes the default value
"jdbc:postgresql://localhost:5075/kando". If you do specify -c, then
"jdbc:postgresql://" at a minimum is required. Partial connection strings will have default values automatically supplied. For example, if you specify "jdbc:postgresql://", kandoMaintain assumes a <host> of “localhost”, a <port> value of “5075” and a <dbname> of “kando”.
-Fc <path> -- The path to a text file (such as <gc_home>/dbsettings.conf) containing values for three of the parameters used by kandoMaintain. The contents of this file should include:
DB_USER=<dbadmin> (eliminates need for "-u" on the command line)
DB_PASS=<dbpassword> (eliminates need for "-P" on the command line)
DB_CONNECT=<dbconnectstring> (eliminates need for "-c" on the command line)
For example:
DB_USER=postgres
DB_PASS=postgres
DB_CONNECT =dbc:postgresql://localhost:5075/kando
Note: The settings and the values accepted by this configuration file can change without notice from release to release.
Other Options
-Fb <path> -- The path to the backup file of the GitCentric database created by the backupdbs command. Used by restoredbs.
-n <name> -- Configuration name (the param_name field in the GitCentric database configuration table). See GitCentric Bridge Configuration Settings below.
-v <value> -- Configuration value (the param_value field in the GitCentric database configuration table). See GitCentric Bridge Configuration Settings below.
-m '<comment>' -- Configuration comments (the comments field in the GitCentric database configuration table). (Double or single quotes are required if the comment includes spaces.)
-r <repository_path> -- The path to the GitCentric repository. For mvrepos, the path to the repository to which the command should move existing repositories after an upgrade installation. For checksync, the path to the repository whose synchronization status you are checking.
-b <branch> -- The name of the branch in the GitCentric repository whose synchronization status you are checking with the checksync command.
-y -- Suppress confirmation prompting for mkdb, rmdb, mvrepos, or upgradedb.
-I -- When executing an upgradedb command, initialize a new database if one does not exist.
--diff -- For checksync, compares each directory, file, and link between the Git branch and AccuRev stream whose synchronization status you are checking and reports any discrepancies.
GitCentric Bridge Configuration Settings
Here are the configuration values that can be set with
kandoMaintain addconfig -n <name> -v <value>
The bridge is the webapp <tomcat_home>/webapps/kandoBridge that keeps your Git repositories and AccuRev streams in sync.
Table 1. GitCentric Systemwide Configuration Settings
Name
Value
Comments
AC_GIT_BIN
Full path and name of Git executable.
Typically set by the GitCentric installer and should not need to be modified. If this value is not defined, GitCentric uses the PATH to find the Git executable.
ACCUREV_COMMAND_LOGFILE
Full path and name of a log file.
DEBUG ONLY. Use only when directed by AccuRev Support. This log shows each AccuRev command that gets executed by the bridge. Note: For Code Review and UI logging, see:
<gc_home>/site/etc/gerrit.config
PRESERVE_TEMP_FILES
[ Y | y ]
DEBUG ONLY. Use only when directed by AccuRev Support. "Y" specifies to not delete temporary files (from xmlpromote, fast-import, misc. messages, etc.) that are generated in $CATALINA_HOME/temp.
AC_BRIDGEAPI_SECURITY_POLICY
AllowAnyHost
DEBUG. By default GitCentric recognizes trigger events only from trusted servers. Use this setting to troubleshoot if a trusted server is having difficulty communicating with GitCentric. (Case sensitive.)
GIT_RENAME_THRESHOLD
[ 0 - 100 ]
Value for matching the Git rename detection threshold, so that a file delete/replace can be identified as a rename operation, allowing AccuRev to track the history of a renamed file. The default value is 50 which is the same as the default Git setting. Only adjust this value if renames are not identified accurately.
kando.bridgeURL
URL of the GitCentric bridge
Allows you to set the URL of the GitCentric bridge; used when the GitCentric server and AccuRev server are on different hosts. For example:
http://<host name>:8080/KandoBridge
where <host name> is the name or IP address of the GitCentric server host.
Examples
1. Test the JDBC connection to the PostgreSQL database instance for GitCentric, specifying the DB user account but having kandoMaintain prompt for the DB password:
kandoMaintain testconn -u postgres
kandoMaintain prompts you to enter the database admin password, and uses the default connection string "jdbc:postgresql://localhost:5075/kando" since you did not specify the
-c option.
2. List all the entries in the GitCentric database configuration table. Specify the database username, password, and connection string in an external file called db_vals.txt which exists in a secure directory named "securefiles".
kandoMaintain lsconfig -Fc ./securefiles/db_vals.txt
3. Remove the configuration value that points to the instance of Git used by GitCentric, specifying the DB user account and DB password:
kandoMaintain rmconfig -u postgres -P DBpass2901 -n AC_GIT_BIN
4. Add a new configuration value that points to the instance of Git used by GitCentric, specifying the DB user account but having kandoMaintain prompt for the DB password:
kandoMaintain addconfig -u postgres -n AC_GIT_BIN -v '/usr/local/bin/git’
5. After upgrading GitCentric, upgrade the GitCentric database with the latest schema. Suppress the confirmation prompt, and specify the database username, password, and connection string in an external file called db_vals.txt which exists in a secure directory named "securefiles".
kandoMaintain upgradedb -y -Fc ./securefiles/db_vals.txt