Troubleshooting

List of relevant log files

In order to debug and analyse problems with the Registration Server configuration, there are several log files that you can consult:

  • /var/log/pbt_mod.trace: The log file of the mod_pbt Apache module. The amount of logging information can be defined by changing the value debug_trace in configuration file /etc/httpd/conf.d/pbt.conf. The following debug levels can be set: 0: OFF, 1: Errors Only, 2: PBT output, 3: everything. Changing this value requires a restart of the Apache httpd server. The file needs to be owned by the Apache user. Logging only occurs if this file exists and is writable by the Apache user.
  • /var/log/pbac_mailer.log: The default log file written by the pbac_mailer process (managed by pbctl). The log file location can be configured by changing the file name after the -l option in /usr/local/primebase/pbstab. Changing this value requires a restart of the pbac_mailer process using service teamdrive restart.
  • /var/log/pbvm.log: The log file for the PrimeBase Application Environment. This log file can be useful to investigate issues related to establishing a MySQL connection or sending out email. The amount of logging can be configured by changing the configuration variable 342 (Protocol Log Level) in /usr/local/primebase/setup/pbvm.env, which needs to be modified by using the pbee command line tool. Note that the log level should be set to at least 2 in order to obtain meaningful debugging messages. After changing this value, you need to restart PBAC-based services using service teamdrive restart.
  • /var/log/httpd/: The Apache httpd Server’s log files (e.g. error_log) might also contain additional relevant error messages that should be checked.
  • /var/log/td-adminconsole-api.log: A log file to track API accesses from the Admin Console. The location of this log file can be configured with the Registration Server setting RegServer/ApiLogFile via the Admin Console. The file needs to be owned by the Apache user. Logging only occurs if this file exists and is writable by the Apache user.
  • /var/log/td-adminconsole-failedlogins.log: A log file to keep track of failed login attempts to the Admin Console. The location of this log file can be configured with the Registration Server setting LoginSecurity/FailedLoginLog via the Admin Console.

Common errors

Invitation emails are not being sent

If users don’t receive invitation emails, there are several aspects that should be checked:

  • On the Admin Console, check the “Manage Auto Tasks” page: did the task “Send Emails” succeed and was it run recently (check the value of “laststarttime”?). On the “Manage Email Queue”, do you see emails with status “Failed”?
  • Is the pbac_mailer up and running? Check with pbctl status and use pbctl start to start the process. Also ensure that the PBAC process is configured to be started at system bootup time. See chapter Starting and stopping the TeamDrive Registration Server components for details.
  • Does sending of email work in general? Try using $sendmail as described in chapter Sending Email via PBAC and check /var/log/pbvm.log and your MTA logs for delivery status notifications.
  • Check the /var/log/pbac_mailer.log log file for errors.

PBAC: Errors sending email with $sendmail

If you get an error message like:

Error (501) sending mail: 501 Syntactically invalid HELO argument(s)

Try putting your hostname in the file /etc/hosts.

In case you get an error like:

01/17/2014 06:07:39
1: ERROR: -16045 (-12996) : "$sendmail("from_address@exam ..."@client line 1:
Error (-12996) sending mail: Bad mail ID.

Check the log file /var/log/pbvm.log for details.

Admin console: Error connecting to the MySQL server

If you get an error like:

Error connecting to the MySQL server: MDB2 Error: connect failed

Verify that the MySQL connection parameters like username and password are set up correctly. See chapter Administration Console MySQL Configuration for details.

Admin console: API error code: -30000, message: Access denied

If some operations on the web-based Administration Console (e.g. changing a configuration option) result in an error message API error code: -30000, message: Access denied, the IP address of the admin console host is likely not on the white list of IPs that are allowed to perform API calls. Check the content of the Registration Server setting API_IP_ACCESS (“Edit Provider Settings” -> “API” -> “API_IP_ACCESS”) and make sure that the external IP address of the server running the Administraton Console is included in the list. If necessary, add the missing address in a new line and click Save.

Invalid/insufficient connection options (TCP/IP communications error)

If some operations on the web-based admin console (e.g. changing provider settings or any other changes that perform API calls to the Registration Server) result in an error as the following one:

The following error occured in '"OPEN TD2REG_WRITE DBMS USER ..."@network
line 1: Invalid/insufficient connection options (TCP/IP communications
error) : Opening and initializing PBI connection, Alias "td2as"' while
processing your request: -12986 (-12948).

The Apache error log on the Registration Server /var/log/httpd/error_log shows a similar error:

[notice] Mod_pbt Error: pid: 8181, where: "OPEN TD2REG_WRITE DBMS USER
..."@network line 1: Invalid/insufficient connection options (TCP/IP
communications error) : Opening and initializing PBI connection, Alias
"td2as", perr: -12986, serr: -12948

Check that the MySQL connection definitions in file /usr/local/primebase/setup/connect.def are set up correctly and that the ownerships and permissions of this file allow the Apache http Server to open this file for reading (as the mod_pbt Apache module needs to obtain the MySQL connection information from there).

Email messages sent by the registration server show encoding issues

Invitation emails and other notifications sent out by the Registration Server are encoded as UTF-8. Before they are sent out, they are first inserted into the MySQL database before the pbac_mailer task delivers them to the configured MTA. If you notice encoding issues (special chars or umlauts not displayed properly), check the following:

  • Double check that your templates are UTF-8 encoded. The default templates shipped with the TeamDrive Registration Server use the correct encoding, but if you’re updating from previous versions, the encoding might be off.

  • Check the MySQL connection definition file /usr/local/primebase/setup/connect.def for the existence of Charset=utf8 in the xoHost= section, e.g.:

    TD2REG_WRITE:mem:\xoHost=regdb.local;Charset=utf8;Reconnect=\tCustom...