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.xml—Each 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 components—The 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. Open the MySQL CLI client and log in as the root user.
    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 Windows Server

The following instructions describe how to install multiple Jamf Pro web applications (i.e., "contexts") on a Windows server.

Note:

For reference, you may find the installation instructions for a single Jamf Pro context helpful. For more information, see Manually Installing Jamf Pro on Windows.

  1. On the Windows server, prepare the ROOT.war file to be installed as a unique Tomcat context:
    1. If needed, copy the ROOT.war file to the Windows Desktop.
    2. Give the file a unique name formatted as follows:
      context.war
      Best Practice:

      Add Multiple .war Files Individually

      The best practice is to put .war files in the Tomcat webapps directory one at a time, waiting for each one to expand before adding the next. Putting multiple .war files in the Tomcat webapps directory at the same time can cause all of them to fail to expand. Although it is possible, you should not name a context ROOT on a multi-context Jamf Pro server.

  2. Manually install Tomcat. For instructions, see step 2 of the single-context manual installation instructions in this guide: Step 2: Installing Tomcat
  3. Install the web application by placing the renamed .war file in the Tomcat webapps directory: 
    C:\Program Files\Apache Software Foundation\Tomcat 8.5\webapps
  4. Locate the DataBase.xml file in the following location:
    C:\Program Files\Apache Software Foundation\Tomcat 8.5\webapps\context\WEB-INF\xml\DataBase.xml
    1. Make a backup copy of the DataBase.xml file.
    2. Open the DataBase.xml file with Notepad ++. (Avoid using NotePad or WordPad.)
    3. Edit the file to match the MySQL account created earlier:
      <DataBaseName>databasename</DataBaseName>
<DataBaseUser>username</DataBaseUser>
<DataBasePassword>password</DataBasePassword>
  5. Navigate to the log4j2.xml file inside of the web application directory:
    C:\Program Files\Apache Software Foundation\Tomcat 8.5\webapps\context\WEB-INF\classes\log4j2.xml
  6. Make a backup copy of the log4j2.xml file
  7. Open the log4j2.xml with Notepad++ and locate each of the (3) instances of the following path: 
    /Library/JSS/Logs/
  8. Use the Find... and Replace... features of Notepad++, or any other method, to modify the target file path for each of the log files. The modified paths should include a separate folder with the same name as the context name used in step 1 to prevent overwriting:
    \\Program Files\\Apache Software Foundation\\Tomcat 8.5\\logs\\context\\JAMFChangeManagement.log
\\Program Files\\Apache Software Foundation\\Tomcat 8.5\\logs\\context\\JAMFSoftwareServer.log
\\Program Files\\Apache Software Foundation\\Tomcat 8.5\\logs\\context\\JSSAccess.log
    Either the format above or the one below can be used for Windows file paths:
    /Program Files/Apache Software Foundation/Tomcat 8.5/logs/context/JAMFChangeManagement.log
/Program Files/Apache Software Foundation/Tomcat 8.5/logs/context/JAMFSoftwareServer.log
/Program Files/Apache Software Foundation/Tomcat 8.5/logs/context/JSSAccess.log
  9. Restart Tomcat using the Tomcat Properties application located on the Notification Center Task Bar at the bottom right of the screen or any preferred method.
  10. Browse to http://192.168.56.103:8080/context to verify the installation.