| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| |
| <document url="html-host-manager-howto.html"> |
| &project; |
| |
| <properties> |
| <title>Host Manager App -- HTML Interface</title> |
| </properties> |
| <body> |
| <section name="Table of Contents"> |
| <toc/> |
| </section> |
| <section name="Introduction"> |
| <p> |
| The <strong>Tomcat Host Manager</strong> application enables you to create, |
| delete, and otherwise manage virtual hosts within Tomcat. This how-to guide |
| is best accompanied by the following pieces of documentation: |
| </p> |
| <ul> |
| <li> |
| <a href="virtual-hosting-howto.html">Virtual Hosting How-To</a> for more |
| information about virtual hosting. |
| </li> |
| <li> |
| <a href="config/host.html">The Host Container</a> for more information |
| about the underlying xml configuration of virtual hosts and description |
| of attributes. |
| </li> |
| <li> |
| <a href="host-manager-howto.html">Host Manager App -- Text Interface</a> |
| for full description of the commands. |
| </li> |
| </ul> |
| |
| <p> |
| The <strong>Tomcat Host Manager</strong> application is a part of |
| Tomcat installation, by default available using the following |
| context: <code>/host-manager</code>. You can use the host manager in the |
| following ways: |
| </p> |
| |
| <ul> |
| <li> |
| Utilizing the graphical user interface, accessible at: |
| <code>{server}:{port}/host-manager/html</code>. |
| </li> |
| <li> |
| Utilizing a set of minimal HTTP requests suitable for scripting. |
| You can access this mode at: |
| <code>{server}:{port}/host-manager/text</code>. |
| </li> |
| </ul> |
| <p> |
| Both ways enable you to add, remove, start, and stop virtual hosts. |
| Changes are not persisted to the Tomcat configuraiton files. If you want |
| your settings to be persistent, you must write them into the |
| <i>server.xml</i> configuration file manually. For full documentation |
| about the configuration, see <a href="config/host.html">The Host |
| Container</a>. This document focuses on the HTML interface. For further |
| information about the graphical interface, see |
| <a href="host-manager-howto.html">Host Manager App -- Text Interface</a>. |
| </p> |
| </section> |
| |
| <section name="Configuring Manager Application Access"> |
| <p><em>The description below uses <code>$CATALINA_HOME</code> to refer the |
| base Tomcat directory. It is the directory in which you installed |
| Tomcat, for example <code>C:\tomcat8</code>, or |
| <code>/usr/share/tomcat8</code>.</em></p> |
| |
| <p> |
| The Host Manager application requires a user with one of the following |
| roles: |
| </p> |
| |
| <ul> |
| <li> |
| <code>admin-gui</code> - use this role for the graphical web interface. |
| </li> |
| <li> |
| <code>admin-script</code> - use this role for the scripting web interface. |
| </li> |
| </ul> |
| |
| <p> |
| To enable access to the HTML interface of the Host Manager application, |
| either grant your Tomcat user the appropriate role, or create a new one with |
| the correct role. For example, open |
| <code>${CATALINA_BASE}/conf/tomcat-users.xml</code> and enter the following: |
| </p> |
| <source><![CDATA[<user username="test" password="chang3m3N#w" roles="admin-gui"/>]]></source> |
| <p> |
| No further settings is needed. When you now access |
| <code>{server}:{port}/host-manager/html</code>,you are able to |
| log in with the created credentials. |
| </p> |
| <p> |
| Note that in case you retreive your users using the |
| <code>DataSourceRealm</code>, <code>JDBCRealm</code>, or |
| <code>JNDIRealm</code> mechanism, add the appropriate role in the database |
| or the directory server respectively. |
| </p> |
| </section> |
| |
| <section name="Interface Description"> |
| <p>The interface is divided into six sections:</p> |
| <ul> |
| <li><strong>Message</strong> - Displays success and failure messages.</li> |
| <li><strong>Host Manager</strong> - Provides basic Host Manager operations |
| , like list and help.</li> |
| <li><strong>Host name</strong> - Provides a list of virtual Host Names and |
| enables you to operate them. </li> |
| <li><strong>Add Virtual Host</strong> - Enables you to add a new Virtual |
| Host.</li> |
| <li><strong>Server Information</strong> - Information about the Tomcat |
| server.</li> |
| </ul> |
| </section> |
| |
| <section name="Message"> |
| |
| <p> |
| Displays information about the success or failure of the last Host Manager |
| command you performed: |
| </p> |
| <ul> |
| <li>Success: <strong>OK</strong> is displayed |
| and may be followed by a success message.</li> |
| <li>Failure: <strong>FAIL</strong> |
| is displayed followed by an error message.</li> |
| </ul> |
| <p> |
| Note that the console of your Tomcat server may reveal more information |
| about each command. |
| </p> |
| </section> |
| |
| <section name="Host Manager"> |
| |
| <p>The Host Manager section enables you to:</p> |
| <ul> |
| <li><strong>List Virtual Hosts</strong> - Refresh a list of |
| currently-configured virtual hosts.</li> |
| <li><strong>HTML Host Manager Help</strong> - A documentation link.</li> |
| <li><strong>Host Manager Help</strong> - A documentation link.</li> |
| <li><strong>Server Status</strong> - A link to the <strong>Manager</strong> |
| application. Note that you user must have sufficient permissions to access |
| the application.</li> |
| </ul> |
| </section> |
| |
| <section name="Host Name"> |
| |
| <p>The Host name section contains a list of currently-configured virtual host |
| names. It enables you to:</p> |
| <ul> |
| <li>View the host names</li> |
| <li>View the host name aliases</li> |
| <li>Perform basic commands, that is <strong>start</strong>, |
| <strong>stop</strong>, and <strong>remove</strong>.</li> |
| </ul> |
| </section> |
| |
| <section name="Add Virtual Host"> |
| |
| <p>The Add Virtual Host section enables you to add a virtual host using a |
| graphical interface. For a description of each property, see the |
| <a href="host-manager-howto.html">Host Manager App -- Text Interface</a> |
| documentation. Note that any configuration added via this interface is |
| non-persistent.</p> |
| </section> |
| |
| <section name="Server Information"> |
| <p> |
| Provides a basic information about the currently-running Tomcat instance, |
| the JVM, and the underlying operating system. |
| </p> |
| </section> |
| |
| </body> |
| </document> |