Where to find Tomcat's username and password settings

Tomcat stores usernames and passwords in a file called tomcat-users.xml, which lives in the conf folder inside your Tomcat installation directory. On Windows, this is usually C:\Program Files\Apache Software Foundation\Tomcat [version]\conf. On Mac or Linux, it's typically /opt/tomcat/conf or /usr/local/tomcat/conf, depending on how you installed it.

You cannot change Tomcat credentials through a web interface the way you would change a password on Gmail or Facebook. Instead, you edit the XML file directly, then restart Tomcat so it reads the new settings. This means you need access to the server's file system — you cannot do this remotely unless you have SSH or remote desktop access to the machine running Tomcat.

Key Takeaways

  • Tomcat usernames and passwords are stored in a plain-text XML file, not in a database or web form.
  • You must edit the tomcat-users.xml file directly and restart Tomcat for changes to take effect.
  • Passwords in tomcat-users.xml should be encrypted using Tomcat's digest tool rather than stored in plain text.
  • If you lose access to the admin account, you can reset it by editing the file and restarting the service.
  • Always back up tomcat-users.xml before making changes, in case you need to revert.

Step 1: Stop the Tomcat service

Before you edit the configuration file, stop Tomcat completely. If Tomcat is running while you change the file, it may not read your changes, or it may overwrite them when it shuts down.

On Windows, open Services (press Windows key + R, type services.msc, and press Enter). Find the Tomcat service in the list, right-click it, and select Stop. On Mac or Linux, open a terminal and run sudo /path/to/tomcat/bin/shutdown.sh, replacing the path with your actual Tomcat location. Wait 10 to 15 seconds for the process to fully stop.

Step 2: Back up the original file

Before you make any edits, copy tomcat-users.xml to a safe location. Right-click the file, select Copy, then paste it in the same folder and rename it to something like tomcat-users.xml.backup. This way, if something goes wrong, you can restore the original and try again.

A backup takes 30 seconds and can save you hours of troubleshooting if you accidentally introduce a syntax error or need to revert to your previous credentials.

Step 3: Open and edit tomcat-users.xml

Open the tomcat-users.xml file in a plain-text editor. On Windows, right-click the file, select Open with, and choose Notepad. On Mac, use TextEdit (set it to plain-text mode first under Format menu). On Linux, use nano or vi from the terminal: nano /path/to/tomcat/conf/tomcat-users.xml.

Look for a line that contains the username you want to change. It will look something like this:

<user username="admin" password="s3cret" roles="manager-gui,admin-gui" />

To change the username, replace the text inside the first set of quotes after username=. To change the password, replace the text inside the quotes after password=. Do not delete the quotes themselves or the equals signs.

Step 4: Encrypt the new password (recommended)

Storing passwords in plain text in tomcat-users.xml is a security risk. Tomcat includes a tool to encrypt passwords so they are not readable if someone gains access to the file. Navigate to your Tomcat bin folder in a terminal or command prompt and run this command:

./catalina.sh digest -a SHA -s 0 YourNewPassword

On Windows, use catalina.bat instead of catalina.sh. Replace YourNewPassword with the actual password you want to use. The tool will output an encrypted string that looks like random characters. Copy this entire encrypted string (not including the word "YourNewPassword" at the start of the output).

Go back to your tomcat-users.xml file and replace the plain-text password with the encrypted version. Keep the digest= attribute in the user tag so Tomcat knows to decrypt it. The line should now look like:

<user username="admin" password="encrypted_string_here" roles="manager-gui,admin-gui" digest="SHA" />

Step 5: Save the file and restart Tomcat

Save the tomcat-users.xml file. If you are using Notepad or TextEdit, press Ctrl+S (or Cmd+S on Mac). If you are using nano in the terminal, press Ctrl+X, then Y, then Enter.

Now restart Tomcat. On Windows, go back to Services, find the Tomcat service, right-click it, and select Start. On Mac or Linux, run sudo /path/to/tomcat/bin/startup.sh. Wait 20 to 30 seconds for Tomcat to fully start. You can check the logs in the logs folder to see if it started without errors.

Step 6: Test the new credentials

Once Tomcat is running, open a web browser and go to http://localhost:8080/manager/html (or replace localhost with your server's IP address if accessing remotely). You should see a login prompt. Enter your new username and password. If they work, you have successfully changed them.

If the login fails, stop Tomcat again, check that you did not introduce any typos or XML syntax errors in the file, and try again. If you get locked out completely, restore your backup file and start over.

Frequently Asked Questions

What if I forgot the old password and cannot log in?

You can still change it by editing the tomcat-users.xml file directly, since you have access to the server's file system. Stop Tomcat, edit the file with a new password (encrypted or plain text), save it, and restart. You do not need to know the old password to set a new one.

Can I have multiple user accounts in Tomcat?

Yes. The tomcat-users.xml file can contain multiple <user> tags, each with a different username, password, and set of roles. Add a new line for each account you want to create, following the same format as the existing users.

What do the roles mean?

Roles control what parts of Tomcat a user can access. manager-gui allows access to the web-based manager interface, and admin-gui allows access to the host manager. You can assign one role, both, or create custom roles depending on what you need the account to do.

Do I need to encrypt the password, or can I leave it in plain text?

You can leave it in plain text, and Tomcat will work fine. However, encryption is strongly recommended because anyone with access to the tomcat-users.xml file will be able to read the password. Encryption takes only a few extra seconds and adds a layer of security.

What if Tomcat will not start after I made changes?

Check the logs in the logs folder (usually catalina.out on Linux or catalina.log on Windows) for error messages. Common problems are XML syntax errors (missing quotes, mismatched tags) or an incorrectly formatted encrypted password. Restore your backup file, fix the issue, and try again.