.. _troubleshooting: 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 :ref:`startingstoppingcomponents` for details. - Does sending of email work in general? Try using ``$sendmail`` as described in chapter :ref:`sendingmail` 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 :ref:`adminconsoleconfig` 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...