Troubleshooting

List of relevant configuration files

/etc/httpd/conf.d/td-webportal.httpd.conf:

The configuration file that loads and enables the TeamDrive Web Portal Server-specific module for the Apache HTTP Server: mod_yvva.so.

mod_yvva.so is responsible for providing the web-based Host Server Administration Console as well as an API used for authentication.

The file also contains various Apache “rewrite” rules required by the Web Portal.

Note

The rewrite rules in this file are disable by default. This is because it is assumed that HTTPS is always used to access the Web Portal.

Enable the rewrite rules only if you are certain that HTTP access may be used.

/etc/logrotate.d/td-webportal:
This file configures how the log files belonging to the TeamDrive Web Portal are being rotated. See the logrotate(8) manual page for details.
/etc/td-webportal.conf:
This file defines how the td-webportal background service is started using the yvvad daemon.
/etc/td-webportal.my.cnf:
This configuration file defines the MySQL credentials used to access the webportal MySQL database. It is read by the Apache module mod_yvva and the yvvad daemon that runs the td-webportal background tasks and the yvva command line client.
/etc/yvva.conf:
This configuration file contains configuration settings specific to the Yvva Runtime Environment that effect the mod_yyva Apache module and the yvva command line shell.

List of relevant log files

In order to debug and analyse problems with the Web Portal configuration, there are several log files that you should consult:

/var/log/td-webportal.log:

The log file for the Yvva runtime which provides the web-based Administration Console, and the Web Portal authentication API. Errors that are incurred by the Web Portal background tasks are also written to this file.

Consult this log file when the Web Portal has issues in contacting the Registration Server, errors when handling API requests or problems with the Administration Console.

You can increase the amount of logging by changing the Yvva setting log-level from notice to trace or debug in the yvva.conf file:

log-level=trace

After changing yvva.conf you need to restart the Apache HTTP Server service using service httpd restart.

This log file is also used by the td-webportal background service. Check the log file to verify that background tasks are being processed without errors.

The log file location can be configured by changing the file name passed to the log-file option in the configuration file /etc/td-webportal.conf. The log level can be increased by changing the default value notice for the log-level option to trace or debug.

Changing these values requires a restart of the td-webportal background process using service td-webportal restart.

/var/log/httpd/:
The Apache HTTP Server’s log files (e.g. error_log) might also contain additional relevant error messages that should be checked.

Enable Logging with Syslog

As outlined in List of relevant log files, the TeamDrive Web Portal logs critical errors and other notable events in a log file by default.

It is now possible to redirect the log output of the Yvva runtime components to a local syslog instance instead.

Syslog support is an essential feature for auditing, security and/or compliance reasons, as it allows you to funnel all log messages into a centralized syslog server.

This makes it easier to monitor the logs for critical events or errors and prevents tampering with the log files in case of a security breach. It also helps to maintain control over the disk space utilization on the server, as growing log files can’t accidentally fill up the file system.

To enable syslog support, the log file name in the log-file setting has to be replaced with the keyword syslog. Optionally, a custom process identifier can be supplied, by appending it to the syslog keyword, using a colon as the separator, e.g. log-file=syslog:my_process_identifier. If not used, the default process identifier will be used, which is the name of the Yvva component.

To enable syslog support for the Yvva-based td-webportal background service, edit the log-file setting in file /etc/td-webportal.conf as follows:

log-file=syslog:webp-bkgr

You need to restart the td-webportal background service via service td-webportal restart in order to activate this change. If the log-level is set to debug you will now see log messages appearing in /var/log/messages:

Jun 23 11:57:33 localhost webp-bkgr: notice: yvvad startup
Jun 23 11:57:33 localhost webp-bkgr: notice: Using config file:
/etc/td-webportal.conf
Jun 23 11:57:33 localhost webp-bkgr: notice: No listen port
Jun 23 11:57:33 localhost webp-bkgr: notice: yvvad running in repeat 60
(seconds) mode

To enable syslog support for the Web Portal API and Administration Console, edit the /etc/yvva.conf file as follows:

log-file=syslog:webp-httd

You need to restart the Apache HTTP Server via service httpd restart in order to activate this change. If the log-level is set to debug you will now see log messages appearing in /var/log/messages:

Jun 23 12:06:04 localhost webp-httd: notice: mod_yvva 1.2.1 (May 21 2015
11:00:12) startup OK

Common errors

Web Installation: “500 Internal Server Error”

This error can be triggered by several error conditions. Check the log file /var/log/td-webportal.log for details.

Some common errors include:

[Error] -12036 (2002): Can't connect to local MySQL server through socket
'/var/lib/mysql/mysql.sock' (25)
[Error] "startup.yv" (80)

The local MySQL Server’s socket file can’t be opened. This could either be a permission problem, or the MySQL Server is simply not available. Check that MySQL is actually up and running (e.g. by running service mysqld status) and restart it, if necessary. If the error persists, check the MySQL error log file (usually /var/log/mysqld.log) for hints.

Similarly, an error like the following one indicates that a remote MySQL Server might not be answering (e.g. because of a firewall rule or because it’s not running):

[Error] -12036 (2003): Can't connect to MySQL server on
'webportal.yourdomain.com' (107)
[Error] "startup.yv" (80)

If you see Access denied errors like the following one:

[Error] -12036 (1045): Access denied for user 'teamdrive'@'localhost' (using
password: YES)
[Error] "startup.yv" (32)

Either the username or password used to connect to the MySQL Server are wrong. Double check that the MySQL username and password provided in /etc/td-webportal.my.cnf are correct, e.g. by trying to connect to the MySQL server using these credentials with the mysql command line client.

If you see the following error when connecting to a remote MySQL Server:

[Error] -12036 (1130): Host 'webportal.yourdomain.com' is not allowed to
connect to this MySQL server
[Error] "startup.yv" (80)

Check the TeamDrive MySQL user’s privileges on the remote MySQL server, e.g. by running SHOW GRANTS FOR `teamdrive`@`webportal.yourdomain.com`; and make sure that this user is allowed to connect to the MySQL server from the Registration Server’s host.

Errors When Accessing the Registration Server

If the Web Portal fails to contact the Registration Server, check the /var/log/td-webportal.log log file, as well as /var/log/td-regserver.log on the Registration Server for hints.

See the Troubleshooting chapter in the Registration Server Installation Manual for details.

Note

Note that Registration Server version 3.5 or later is required by the Web Portal.

Errors When Accessing Docker

If the Web Portal fails to contact the Docker daemon, first check If docker can be accessed using the command line interface, for example:

[root@webportal install]# export DOCKER_HOST=tcp://<docker-host>:2375
[root@webportal install]# docker images

This command will list the available images. The Docker daemon must be accessible using TCP. How to configure docker for TCP access is explained here: Installing Docker.

If the Web Interface does not work correctly it may be that the reference to the Docker host is not correct in the /etc/httpd/conf.d/ssl.conf file.

Open up this file and check that you have followed the instructions in section Configure mod_ssl.