Troubleshooting Database Connectivity from the Jamf Pro Server
During startup, an error message appears indicating that Jamf Pro cannot establish a connection to the database.
This error occurs when the Jamf Pro server is unable to connect to the MySQL database when accessing the web interface. One or more of the following issues may explain the error:
The database connection details are not configured.
MySQL is not running on the database server.
The DataBase.xml file contains invalid MySQL server location details.
The database server is not accepting incoming connections.
The DataBase.xml file contains invalid user credentials.
The database user is not granted proper privileges to the database.
The database user password authentication plug-in is not properly configured.
If the database connection error persists after trying these options to resolve, contact Jamf Support.
The Database Connection Details are Not Configured
Jamf Pro needs certain information to connect to the MySQL database, such as the MySQL user credentials and port number. If these or any other required details are missing from the DataBase.xml file, a database connection error will appear. You can view and configure the database connection details using Jamf Pro Server Tools. For instructions, see the Editing the Database Connection Using Jamf Pro Server Tools article.
MySQL is Not Running on the Database Server
The MySQL service must be running on the database server for Jamf Pro to establish a connection during startup. If MySQL is not running when Jamf Pro attempts to connect to the database, a database connection error will appear. Follow these steps to verify and resolve this issue.
Linux
- Log in to the server hosting the MySQL database.
Verify that MySQL is running by executing one of the following commands:
Red Hat Enterprise Linux:service mysqld status
Ubuntu:service mysql status
If the command returns "Active: active (running)", this indicates that MySQL is currently running, and this is not the issue. Refer to the next possible issue to continue troubleshooting.
If the command returns "Active: inactive (dead)", this indicates that MySQL is not currently running. Continue following these steps to resolve.
Execute the following command:
Red Hat Enterprise Linux:service mysqld start
Ubuntu:service mysql start
After the service has started, reattempt connection to the database. If the database connection error persists, refer to the next possible issue in this article to continue troubleshooting.
Windows
Log in to the server hosting the MySQL database.
Open Services.
- Locate MySQL in the services list and verify that the service is running.
If Services reports that MySQL is Running, this is not the issue. Refer to the next possible issue in this article to continue troubleshooting.
If Services reports that MySQL is not running, continue following these steps to resolve.
Click Start the service to start MySQL.
Reattempt connection to the database. If the database connection error persists, refer to the next possible issue in this article to continue troubleshooting.
The DataBase.xml File Contains Invalid MySQL Server Location Details
Jamf Pro uses information in the DataBase.xml file to locate the MySQL database. If the DataBase.xml file's server location details are incorrect, a database connection error will occur. Follow these steps to verify and resolve this issue.
The Database Server is Not Accepting Incoming Connections
If MySQL is running on the same server as Tomcat, this is not the issue. Refer to the next possible issue in this article to continue troubleshooting.
- Work with your network administrator to verify that port 3306 is open both outbound on the Tomcat server and inbound on the database server.
- If port 3306 is open both outbound on the Tomcat server and inbound on the database server, this is not the issue. Refer to the next possible issue in this article to continue troubleshooting.
- If port 3306 is not open outbound on the Tomcat server, or if port 3306 is not open inbound on the database server, continue following these steps to resolve.
- Work with your network administrator to open port 3306 both outbound on the Tomcat server and inbound on the database server.
- Reattempt the connection to the database from the Jamf Pro server. If the database connection error persists, refer to the next possible issue in this article to continue troubleshooting.
The DataBase.xml File Contains Invalid MySQL User Credentials
Jamf Pro uses MySQL user information in the DataBase.xml file to login to MySQL. If the DataBase.xml file's MySQL user credentials are incorrect, a database connection error will occur. Follow these steps to verify and resolve this issue.
The Database User is Not Granted Proper Privileges to the Database
During startup, Jamf Pro logs in to MySQL as a specific database user. If the database user does not have proper permissions to access the Jamf Pro database, Jamf Pro will not be able to establish a connection and a database connection error will occur. Follow these steps to verify and resolve this issue.
The Database User Password Authentication Plug-In is Not Properly Configured
Starting with MySQL 8.0, the MySQL database requires an upgraded default user password authentication plug-in to allow access. If this is not configured during installation, the connection will fail. Follow these steps to resolve this issue:
Linux
- Log in to MySQL as the "root" user by executing:
$mysql -u root -h localhost -p
- Execute a command similar to the following:
alter user 'jamfsoftware'@'localhost' identified with mysql_native_password by 'jamfsw03';
Note:Replace
'jamfsoftware'@'localhost'
and'jamfsw03'
in the above command with the Jamf Pro database user credentials and location. These should match the credentials and location contained in the DataBase.xml file on the Jamf Pro server. Stop the MySQL server.
Open the my.cnf file.
- Add the following entry:
[mysqld] default-authentication-plugin=mysql_native_password
Restart the MySQL server.
Restart the Jamf Pro server.
On the Jamf Pro Server, reattempt the connection to the database.
Windows
- Log in to MySQL as the "root" user by executing:
mysql.exe -h localhost --user=root -p
- Execute a command similar to the following:
alter user 'jamfsoftware'@'localhost' identified with mysql_native_password by 'jamfsw03';
Note:Replace
'jamfsoftware'@'localhost'
and'jamfsw03'
in the above command with the Jamf Pro database user credentials and location. These should match the credentials and location contained in the DataBase.xml file on the Jamf Pro server. Stop the MySQL server.
Open the my.ini file in a text editor other than Notepad.
- Add the following entry:
[mysqld] default-authentication-plugin=mysql_native_password
Restart the MySQL server.
Restart the Jamf Pro server.
On the Jamf Pro server, reattempt the connection to the database.