Migrating from previous Tomcat packages
---------------------------------------

  * Refer to the upstream migration guides for application compatibility
    and configuration changes:
    - http://tomcat.apache.org/migration-7.html
    - http://tomcat.apache.org/migration-8.html
    - http://tomcat.apache.org/migration-85.html
    - http://tomcat.apache.org/migration-9.html

  * Before the version 9 the Debian packages for Tomcat each created their
    own tomcat<n> users. You may need to recursively update your application
    directories to be owned by the tomcat user. This user will no longer
    change for the future upgrades.


Getting started
---------------

  * After installing the tomcat9 package, the server should be accessible
    at http://localhost:8080/

  * The default port 8080 can be changed by modifying the port of the
    connector in /etc/tomcat9/server.xml. Privileged ports (such as 80 or 443)
    can be used with no extra configuration.

  * If you install tomcat9-admin, you have to define an admin account to
    access the manager interface. Edit /etc/tomcat9/tomcat-users.xml and
    follow the instructions in the comments. The Tomcat manager will be
    accessible at http://localhost:8080/manager/html

  * Tomcat is not running under a Java security manager by default. If you
    expose your Tomcat instance to the internet, please consider editing
    your /etc/default/tomcat9 file and set SECURITY_MANAGER="true", then
    adjust policy files in /etc/tomcat9/policy.d/ as explained in
    https://tomcat.apache.org/tomcat-9.0-doc/security-manager-howto.html

  * Tomcat is sandboxed by systemd and only has write access to the following
    directories:
    - /var/lib/tomcat9/conf/Catalina (actually /etc/tomcat9/Catalina)
    - /var/lib/tomcat9/logs          (actually /var/log/tomcat9)
    - /var/lib/tomcat9/webapps
    - /var/lib/tomcat9/work          (actually /var/cache/tomcat9)

    If write access to other directories is required the service settings
    have to be overridden. This is done by creating an override.conf file
    in /etc/systemd/system/tomcat9.service.d/ containing:

      [Service]
      ReadWritePaths=/path/to/the/directory/

    The service has to be restarted afterward with:

      systemctl daemon-reload
      systemctl restart tomcat9

    ⚠ This is supported only when Tomcat is started with the systemd unit.

    Using Tomcat with other init systems is supported, however that will
    negate the security hardening detailed above, make Tomcat not have
    its own temporary directory, not drop privileges/capabilities after
    start, and not be restarted on crashing. Use at your own risk.

  * To run more than one Tomcat instance on your server, install the package
    tomcat9-user and run the tomcat9-instance-create utility.
    You should remove the tomcat9 package if you don't want Tomcat to
    start as a daemon at boot time.
