webapps/docs/html-host-manager-howto.xml - tomcat - Git at Google

 <?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 may be persisted by using the <code>persist</code> command. 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:\tomcat9</code>, or
       <code>/usr/share/tomcat9</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>
       If you are using a different realm you will need to add the necessary role
       to the appropriate user(s) using the standard user management tools for
       that realm.
     </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>Persist configuration</strong> - Enables you to persist your
       current Virtual Hosts.</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="Persist Configuration">

   <p>The Persist Configuration section enables you to persist your current
   configuration into the <i>server.xml</i> file.</p>

   <p> This functionality is disabled by default. To enable this option, you must
   configure the <code>StoreConfigLifecycleListener</code> listener first.
   To do so, add the following listener to your <i>server.xml</i>:</p>
   <source><![CDATA[<Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener"/>]]></source>

   <p>After you configure the listener, click <strong>All</strong> to make your
   configuration 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>
	<?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 may be persisted by using the <code>persist</code> command. 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:\tomcat9</code>, or
	<code>/usr/share/tomcat9</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>
	If you are using a different realm you will need to add the necessary role
	to the appropriate user(s) using the standard user management tools for
	that realm.
	</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>Persist configuration</strong> - Enables you to persist your
	current Virtual Hosts.</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="Persist Configuration">

	<p>The Persist Configuration section enables you to persist your current
	configuration into the <i>server.xml</i> file.</p>

	<p> This functionality is disabled by default. To enable this option, you must
	configure the <code>StoreConfigLifecycleListener</code> listener first.
	To do so, add the following listener to your <i>server.xml</i>:</p>
	<source><![CDATA[<Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener"/>]]></source>

	<p>After you configure the listener, click <strong>All</strong> to make your
	configuration 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>