How to create a Tomcat Manager user

Tomcat Manager access fails closed until an account has one of the Manager roles. Adding the wrong role can leave the browser interface blocked, expose the text API to an interactive user, or give an automation credential more Manager access than it needs.

Default UserDatabaseRealm and MemoryUserDatabase configurations read Manager users from $CATALINA_BASE/conf/tomcat-users.xml. Package-managed systems may place the same user database under a versioned path such as /etc/tomcat10/tomcat-users.xml, so confirm the active file for the instance before editing.

The Manager application uses separate roles for separate surfaces. Use manager-gui for the browser interface, manager-script for the text API and automation, manager-jmx only for the JMX proxy, and manager-status for status pages without deployment controls. Keep browser and script roles on separate accounts so CSRF protection and automation credentials stay scoped to their intended use.

1. Identify the active tomcat-users.xml file for the Tomcat instance.

   Source-style installations commonly use /opt/tomcat/conf/tomcat-users.xml or $CATALINA_BASE/conf/tomcat-users.xml. Debian and Ubuntu Tomcat 10 packages commonly use /etc/tomcat10/tomcat-users.xml.

2. Back up the users file before editing it.

   $ sudo cp /opt/tomcat/conf/tomcat-users.xml /opt/tomcat/conf/tomcat-users.xml.bak

   Replace /opt/tomcat/conf/tomcat-users.xml with the active users file for the instance.

3. Open the users file in a text editor.

   $ sudoedit /opt/tomcat/conf/tomcat-users.xml

4. Add the Manager roles and separate accounts for browser and script access.

   <tomcat-users xmlns="http://tomcat.apache.org/xml"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
                 version="1.0">
     <role rolename="manager-gui"/>
     <role rolename="manager-script"/>
     <role rolename="manager-status"/>
   
     <user username="manager-ui"
           password="change-this-ui-password"
           roles="manager-gui"/>
   
     <user username="manager-api"
           password="change-this-api-password"
           roles="manager-script"/>
   </tomcat-users>

   Do not reuse the example passwords. Generate unique secrets and store them in the system's approved credential store.

   Do not grant manager-gui together with manager-script or manager-jmx on the same account. The Tomcat Manager HTML interface has CSRF protection, but the text and JMX interfaces are intended for tools and cannot use the same browser-side protection.

5. Test the Tomcat configuration before applying the change.

   $ sudo /opt/tomcat/bin/catalina.sh configtest
   INFO: CATALINA_BASE:         /opt/tomcat
   ##### snipped #####
   INFO: Server initialization in [335] milliseconds

   If the packaged service does not expose catalina.sh directly, restart during the maintenance window and check the Tomcat logs immediately afterward.

   Related: How to view Tomcat logs on Linux

6. Restart the Tomcat service so the users database is loaded by the running instance.

   $ sudo systemctl restart tomcat

   Use the actual unit name for the host, such as tomcat10 on many package-managed Ubuntu systems or a custom tomcat unit for source-style installs.

   Related: How to start and stop Tomcat with systemd

7. Verify the script account against the Manager text interface when manager-script was created.

   $ curl --user manager-api:change-this-api-password \
     http://127.0.0.1:8080/manager/text/list
   OK - Listed applications for virtual host [localhost]
   /manager:running:0:manager

   An HTTP 401 means the username or password was rejected. An HTTP 403 means the account authenticated but lacks the role required for that Manager interface.

   Related: How to list deployed applications in Tomcat Manager

8. Verify the browser account reaches the HTML Manager interface when manager-gui was created.

   $ curl -sS -o /dev/null -w "%{http_code}\n" \
     --user manager-ui:change-this-ui-password \
     http://127.0.0.1:8080/manager/html
   200

   Use the real Manager hostname and port when access is allowed from an admin network instead of localhost.

9. Confirm the browser account is blocked from the text API.

   $ curl -sS -o /dev/null -w "%{http_code}\n" \
     --user manager-ui:change-this-ui-password \
     http://127.0.0.1:8080/manager/text/list
   403

   A 403 here confirms the browser account was not accidentally granted manager-script.