webapps/docs/host-manager-howto.xml - tomcat80 - 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="host-manager-howto.html">
   &project;

   <properties>
         <title>Host Manager App -- Text 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>
   </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 text interface. For further information about the graphical
     interface, see
     <a href="html-host-manager-howto.html">Host Manager App -- HTML 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 text 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-script"/>]]></source>
   <p>
     No further settings is needed. When you now access
     <code>{server}:{port}/host-manager/text/${COMMAND}</code>,you are able to
     log in with the created credentials. For example:
     <source>$ curl -u ${USERNAME}:${PASSWORD} http://localhost:8080/host-manager/text/list
 OK - Listed hosts
 localhost:</source>
   </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="List of Commands">
   <p>The following commands are supported:</p>
   <ul>
     <li>list</li>
     <li>add</li>
     <li>remove</li>
     <li>start</li>
     <li>stop</li>
   </ul>
   <p>
     In the following subsections, the username and password is assumed to be
     <b>test:test</b>. For your environment, use credentials created in the
     previous sections.
   </p>
   <subsection name="List command">
     <p>
       Use the <b>list</b> command to see the available virtual hosts on your
       Tomcat instance.
     </p>
     <p><i>Example command</i>:</p>
     <code>curl -u test:test http://localhost:8080/host-manager/text/list</code>
     <p><i>Example response</i>:</p>
     <source>OK - Listed hosts
 localhost:</source>
   </subsection>
   <subsection name="Add command">
     <p>
       Use the <b>add</b> command to add a new virtual host. Parameters used
       for the <b>add</b> command:
     </p>
     <ul>
       <li>String <b>name</b>: Name of the virtual host. <b>REQUIRED</b></li>
       <li>String <b>aliases</b>: Aliases for your virtual host.</li>
       <li>String <b>appBase</b>: Base path for the application that will be
       served by this virtual host. Provide relative or absolute path.</li>
       <li>Boolean <b>manager</b>: If true, the Manager app is added to the
       virtual host. You can access it with the <i>/manager</i> context.</li>
       <li>Boolean <b>autoDeploy</b>: If true, Tomcat automatically redeploys
       applications placed in the appBase directory.</li>
       <li>Boolean <b>deployOnStartup</b>: If true, Tomcat automatically deploys
       applications placed in the appBase directory on startup.</li>
       <li>Boolean <b>deployXML</b>: If true, the <i>/META-INF/context.xml</i>
       file is read and used by Tomcat.</li>
       <li>Boolean <b>copyXML</b>: If true, Tomcat copies <i>/META-INF/context.xml</i>
       file and uses the original copy regardless of updates to the application's
       <i>/META-INF/context.xml</i> file. Available only for
       <b>Tomcat 8 and newer</b>.</li>
     </ul>
     <p><i>Example command</i>:</p>
     <source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/add?name=www.awesomeserver.com&aliases=awesomeserver.com&appBase/mnt/appDir&deployOnStartup=true]]></source>
     <p><i>Example response</i>:</p>
     <source>add: Adding host [www.awesomeserver.com]</source>
   </subsection>
   <subsection name="Remove command">
     <p>
       Use the <b>remove</b> command to remove a virtual host. Parameters used
       for the <b>remove</b> command:
     </p>
     <ul>
       <li>String <b>name</b>: Name of the virtual host to be removed.
       <b>REQUIRED</b></li>
     </ul>
     <p><i>Example command</i>:</p>
     <source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/remove?name=www.awesomeserver.com]]></source>
     <p><i>Example response</i>:</p>
     <source>remove: Removing host [www.awesomeserver.com]</source>
   </subsection>
   <subsection name="Start command">
     <p>
       Use the <b>start</b> command to start a virtual host. Parameters used
       for the <b>start</b> command:
     </p>
     <ul>
       <li>String <b>name</b>: Name of the virtual host to be started.
       <b>REQUIRED</b></li>
     </ul>
     <p><i>Example command</i>:</p>
     <source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/start?name=www.awesomeserver.com]]></source>
     <p><i>Example response</i>:</p>
     <source>OK - Host www.awesomeserver.com started</source>
   </subsection>
   <subsection name="Stop command">
     <p>
       Use the <b>stop</b> command to stop a virtual host. Parameters used
       for the <b>stop</b> command:
     </p>
     <ul>
       <li>String <b>name</b>: Name of the virtual host to be stopped.
       <b>REQUIRED</b></li>
     </ul>
     <p><i>Example command</i>:</p>
     <source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/stop?name=www.awesomeserver.com]]></source>
     <p><i>Example response</i>:</p>
     <source>OK - Host www.awesomeserver.com stopped</source>
   </subsection>
 </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="host-manager-howto.html">
	&project;

	<properties>
	<title>Host Manager App -- Text 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>
	</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 text interface. For further information about the graphical
	interface, see
	<a href="html-host-manager-howto.html">Host Manager App -- HTML 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 text 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-script"/>]]></source>
	<p>
	No further settings is needed. When you now access
	<code>{server}:{port}/host-manager/text/${COMMAND}</code>,you are able to
	log in with the created credentials. For example:
	<source>$ curl -u ${USERNAME}:${PASSWORD} http://localhost:8080/host-manager/text/list
	OK - Listed hosts
	localhost:</source>
	</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="List of Commands">
	<p>The following commands are supported:</p>
	<ul>
	<li>list</li>
	<li>add</li>
	<li>remove</li>
	<li>start</li>
	<li>stop</li>
	</ul>
	<p>
	In the following subsections, the username and password is assumed to be
	<b>test:test</b>. For your environment, use credentials created in the
	previous sections.
	</p>
	<subsection name="List command">
	<p>
	Use the <b>list</b> command to see the available virtual hosts on your
	Tomcat instance.
	</p>
	<p><i>Example command</i>:</p>
	<code>curl -u test:test http://localhost:8080/host-manager/text/list</code>
	<p><i>Example response</i>:</p>
	<source>OK - Listed hosts
	localhost:</source>
	</subsection>
	<subsection name="Add command">
	<p>
	Use the <b>add</b> command to add a new virtual host. Parameters used
	for the <b>add</b> command:
	</p>
	<ul>
	<li>String <b>name</b>: Name of the virtual host. <b>REQUIRED</b></li>
	<li>String <b>aliases</b>: Aliases for your virtual host.</li>
	<li>String <b>appBase</b>: Base path for the application that will be
	served by this virtual host. Provide relative or absolute path.</li>
	<li>Boolean <b>manager</b>: If true, the Manager app is added to the
	virtual host. You can access it with the <i>/manager</i> context.</li>
	<li>Boolean <b>autoDeploy</b>: If true, Tomcat automatically redeploys
	applications placed in the appBase directory.</li>
	<li>Boolean <b>deployOnStartup</b>: If true, Tomcat automatically deploys
	applications placed in the appBase directory on startup.</li>
	<li>Boolean <b>deployXML</b>: If true, the <i>/META-INF/context.xml</i>
	file is read and used by Tomcat.</li>
	<li>Boolean <b>copyXML</b>: If true, Tomcat copies <i>/META-INF/context.xml</i>
	file and uses the original copy regardless of updates to the application's
	<i>/META-INF/context.xml</i> file. Available only for
	<b>Tomcat 8 and newer</b>.</li>
	</ul>
	<p><i>Example command</i>:</p>
	<source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/add?name=www.awesomeserver.com&aliases=awesomeserver.com&appBase/mnt/appDir&deployOnStartup=true]]></source>
	<p><i>Example response</i>:</p>
	<source>add: Adding host [www.awesomeserver.com]</source>
	</subsection>
	<subsection name="Remove command">
	<p>
	Use the <b>remove</b> command to remove a virtual host. Parameters used
	for the <b>remove</b> command:
	</p>
	<ul>
	<li>String <b>name</b>: Name of the virtual host to be removed.
	<b>REQUIRED</b></li>
	</ul>
	<p><i>Example command</i>:</p>
	<source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/remove?name=www.awesomeserver.com]]></source>
	<p><i>Example response</i>:</p>
	<source>remove: Removing host [www.awesomeserver.com]</source>
	</subsection>
	<subsection name="Start command">
	<p>
	Use the <b>start</b> command to start a virtual host. Parameters used
	for the <b>start</b> command:
	</p>
	<ul>
	<li>String <b>name</b>: Name of the virtual host to be started.
	<b>REQUIRED</b></li>
	</ul>
	<p><i>Example command</i>:</p>
	<source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/start?name=www.awesomeserver.com]]></source>
	<p><i>Example response</i>:</p>
	<source>OK - Host www.awesomeserver.com started</source>
	</subsection>
	<subsection name="Stop command">
	<p>
	Use the <b>stop</b> command to stop a virtual host. Parameters used
	for the <b>stop</b> command:
	</p>
	<ul>
	<li>String <b>name</b>: Name of the virtual host to be stopped.
	<b>REQUIRED</b></li>
	</ul>
	<p><i>Example command</i>:</p>
	<source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/stop?name=www.awesomeserver.com]]></source>
	<p><i>Example response</i>:</p>
	<source>OK - Host www.awesomeserver.com stopped</source>
	</subsection>
	</section>
	</body>
	</document>