Multi-Context Jamf Pro Environments

Apache Tomcat refers to web applications like Jamf Pro as contexts. If more than one instance of the Jamf Pro web application is installed using the same Tomcat instance, it is called a multi-context Jamf Pro environment.

In most situations, the Jamf Pro web application exists as a single context in the default Tomcat ROOT web application. However, multiple instances of the Jamf Pro web application can also be hosted on a single instance of Tomcat. Jamf Pro instances configured in this way do not communicate with each other—each Jamf Pro instance has its own database.

You might be interested in creating a multi-context Jamf Pro environment if one of the following use cases applies to you:
  • You are a managed service provider who wants to host separate Jamf Pro instances on a single Tomcat server.

  • Your organization needs to create a lab environment for training Jamf administrators.

  • You have a complex organization with many independent entities that require separate Jamf Pro instances.

  • Your organization wants to create a test environment by installing additional Jamf Pro instances on the Tomcat server that hosts your production server.
    Important:

    Jamf recommends that you use a separate Tomcat server for testing environments. Use extreme caution if you create a multi-context environment for testing purposes.

Additional contexts are accessible from https://jamfpro:8443/contextname.

Important Concepts for Multi-Context Jamf Pro Environments

Keep the following in mind before you configure a multi-context Jamf Pro environment:

  • URL syntax

    The context name is case-sensitive because file paths are case-sensitive. If capital letters are used in the context name, capital letters must be used in the browser URL to navigate to the site.

    The URL is an address to a specific computer. The context name appended to the end of the URL uses the same syntax as a file path. For example, the top level of a Mac has multiple names: slash (or /), Macintosh HD, which is a symlink for /, and root, because / is the root volume. It is understood that all of those names refer to the top of the path.

    If the URL (i.e., the hostname of the computer) has no context name appended, Tomcat's default behavior is to route traffic to a webapp called ROOT, which is a folder on the file system where Tomcat is installed. Using only the URL means: "go to the computer at address x running Tomcat and access the web application hosted there called ROOT".

  • DataBase.xmlEach context has a unique DataBase.xml file that connects it to its unique database. For more information on troubleshooting issues with these configuration files, see the Troubleshooting Database Connectivity from the Jamf Pro Server article.
  • Multi-context logging configuration
    To prevent the logs written by multi-context instances of Jamf Pro from overwriting each other because they have the same name, multi-context instances require a separate folder for each instance of the log files. For example:
    • /var/lib/tomcat/webapps/red/JAMFSoftwareServer.log

    • /var/lib/tomcat/webapps/blue/JAMFSoftwareServer.log

    These folders are created automatically when you expand the renamed ROOT.war files. In this example, they would be red.war and blue.war.

    While it is possible to change the log files in the log4j2.xml file, this method has more potential for future issues than creating separate log file folders.

  • Manual Installation of componentsThe Jamf Pro installers install Tomcat and then expand Jamf Pro into the ROOT web application as a single context. Therefore, a multi-context environment indicates that Tomcat and Jamf Pro must be manually installed in addition to Java and MySQL. For more information, see the Installing Java and MySQL for Jamf Pro 10.14.0 or Later article.

Multi-Context MySQL Databases

Keep the following in mind before you configure databases for multiple Jamf Pro contexts:
  • Each Jamf Pro context requires a unique MySQL database and user. You must grant access from each context to its associated MySQL database.

  • MySQL commands use ALL CAPS as a convention to separate the command syntax from the data provided by the user.

  • For enhanced security, Jamf strongly recommends unique passwords for each MySQL account. In addition, no additional MySQL passwords should match the MySQL root password. Executing the select user,host,authentication_string command is a good way to show the MySQL accounts that have been created and the hashed passwords. The hashes should all be unique.

  • If the MySQL service name was changed during installation, that name should be used in all commands calling it, including start and stop.

Configuring Multi-Context Jamf Pro Databases

These instructions describe how to create unique databases for separate Jamf Pro web applications. Grant access from the Jamf Pro web applications to the databases by creating unique MySQL accounts.

Note:

Data placeholders are used in these instructions to indicate where to place the actual strings needed for your environment. Replace variables such as username, password, hostname, context, and databasename with unique values when executing the commands.

  1. Create a MySQL database for the first context:
    1. From a command prompt, access the MySQL command line as the "root" MySQL user by typing:
      mysql -u root -p
    2. Create a database using a unique database name by executing the following command:
      CREATE DATABASE databaseone;
    3. Create a unique MySQL user for the first context by executing a command similar to the following:
      CREATE USER 'usernameone'@'localhost' IDENTIFIED WITH mysql_native_password BY 'passwordone';
  2. Grant access to the first database by executing a command similar to the following:
    GRANT ALL ON databaseone.* TO 'usernameone'@'localhost';
  3. Create a MySQL database for the second context:
    1. Open the MySQL CLI client and log in as the root user.
    2. Check the list of databases that already exist by executing the following command:
      SHOW DATABASES;
    3. Create a database using a unique database name by executing the following command:
      CREATE DATABASE databasetwo;
    4. Create a unique MySQL user for the first context by executing a command similar to the following:
      CREATE USER 'usernametwo'@'localhost' IDENTIFIED WITH mysql_native_password BY 'passwordtwo';
  4. Grant access to the second database by executing a command similar to the following:
    GRANT ALL ON databasetwo.* TO 'usernametwo'@'localhost';
  5. Continue adding databases and users until the number of databases and their corresponding users is equal to the number of Jamf Pro contexts on the Tomcat server.

Installing Multi-Context Jamf Pro Web Applications on a Linux Server

The following instructions describe how to install multiple Jamf Pro web applications on a Linux server. These instructions apply to both Red Hat Enterprise Linux and Ubuntu.
Note:
For reference, you may find the installation instructions for a single Jamf Pro context helpful. For more information, see the following section of this guide for your platform:
  1. On the Linux server, if needed, copy the ROOT.war file to the Linux server with a command like:
    scp ~/Desktop/ROOT.war serveradmin@192.168.56.101:/tmp/
  2. Manually install Tomcat. For instructions, see step 2 of the manual installation instructions for your platform:
  3. Use the desired name for the context to copy the ROOT.war file from /tmp/ into the Tomcat webapps directory:
    sudo cp /tmp/ROOT.war /opt/tomcat/webapps/contextone.war
  4. Open the DataBase.xml file with a text editor by executing the following command:
    sudo nano -Bc /opt/tomcat//webapps/contextone/WEB-INF/xml/DataBase.xml
  5. Edit the file to match the MySQL account you created earlier:
    <DataBaseName>databaseone</DataBaseName>
    <DataBaseUser>usernameone</DataBaseUser>
    <DataBasePassword>passwordone</DataBasePassword>
  6. Open the log4j2.xml file with a text editor by executing the following command:
    sudo nano -Bc /opt/tomcat/webapps/contextone/WEB-INF/classes/log4j2.xml
  7. Locate each of the (3) instances of the following path:
    /Library/JSS/Logs/
  8. Modify the target file path for each of the logs so they read as follows:
    Note:

    Change contextone in the paths below to match the context name from step 2.

    /opt/tomcat/logs/contextone/JAMFChangeManagement.log
    /opt/tomcat/logs/contextone/JAMFSoftwareServer.log
    0/opt/tomcat/logs/contextone/JSSAccess.log
  9. Restart Tomcat by executing the following command:
    sudo service tomcat restart
  10. Browse to http://192.168.56.101:9006/contextone to verify the installation.