Author: smumford Date: 2011-11-14 20:32:28 -0500 (Mon, 14 Nov 2011) New Revision: 8063 Added: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml epp/docs/branches/5.2/Admin_Guide/en-US/chapter-3-Command_Line_Interface.xml epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions.xml Log: Incorporating latest chenges from nscavelli Added: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml =================================================================== --- epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml (rev 0) +++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml 2011-11-15 01:32:28 UTC (rev 8063) @@ -0,0 +1,284 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="sid-8094332_GateInManagement-Introduction"> + + <title>Introduction</title> + <para>The management component of the portal allows portal resources to be managed over commons interfaces like REST, CLI, and Portlets/Gadgets. This guide will discuss these interfaces as well as general portal management concepts and terms. It will then discuss specific management extensions included in the portal.</para> + <section id="sid-8094332_GateInManagement-Terms"> + + <title>Terms</title> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>Term</para> + </entry> + <entry> + <para> + Description + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>Management Extension</para> + </entry> + <entry> + <para>An extension to the management system which defines a managed component.</para> + </entry> + </row> + <row> + <entry> + <para> + Managed Component + + </para> + </entry> + <entry> + <para>A managed component, which has been registered via an extension, serves as the root managed resource for a component.</para> + </entry> + </row> + <row> + <entry> + <para> + Managed Resource + + </para> + </entry> + <entry> + <para> + A managed resource is a uniquely identified self describing 'resource' which can have operations and sub-resources registered to it. + + </para> + </entry> + </row> + <row> + <entry> + <para> + Sub-resource + + </para> + </entry> + <entry> + <para> + A managed resource whose parent is also a managed resource. + + </para> + </entry> + </row> + <row> + <entry> + <para> + Address + + </para> + </entry> + <entry> + <para> + A management address is just the path of the managed resource with syntax similar to a file on a file system, ie: /foo/bar + + </para> + </entry> + </row> + <row> + <entry> + <para> + Operation + + </para> + </entry> + <entry> + <para> + An action that can be performed on a managed resource. + + </para> + </entry> + </row> + <row> + <entry> + <para> + Attributes + + </para> + </entry> + <entry> + <para> + Custom input parameters available to operations. + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + <section id="sid-8094332_GateInManagement-Goals"> + + <title>Goals</title> + <para>The management component provides a foundation for managing portal side components. By doing so it allows management extensions to register resources and operations over a set of API's, which in turn allows us to expose these over common interfaces like REST and CLI. In other words, management extensions don't have to worry about the interfaces in which they will be managed over. This allows us to add additional interfaces without needing to change anything. Also by providing a set of API's to obtain managed resources, interfaces are built in a consistent manner. So managing the same component in one interface should be very similar if you were to manage it in another.</para> + </section> + <section id="sid-8094332_GateInManagement-Operations"> + + <title>Operations</title> + <para> + The following operations are operations that have been identified by the management component to be common to most management extensions. The + <code>read-resource</code> + operation is really the only global operation supported in the core framework, all other operations need to be implemented by the extensions, since these would be specific to each extension. + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>Operation Name</para> + </entry> + <entry> + <para> + Description + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + read-resource + + </para> + </entry> + <entry> + <para> + The read-resource operation is responsible for reading the managed resource; describing itself and listing any operations and/or sub-resources it may contain. + + This is the primary operation to obtain information about a managed component and it's managed resources. + </para> + </entry> + </row> + <row> + <entry> + <para> + add-resource + + </para> + </entry> + <entry> + <para>The add-resource operation is responsible for adding/creating additional managed resources.</para> + </entry> + </row> + <row> + <entry> + <para> + remove-resource + + </para> + </entry> + <entry> + <para>The remove-resource operation is responsible for removing/deleting an existing managed resource.</para> + </entry> + </row> + <row> + <entry> + <para>update-resource</para> + </entry> + <entry> + <para>The update-resource operation is responsible for updating an existing managed resources state.</para> + </entry> + </row> + <row> + <entry> + <para> + read-config-as-xml + + </para> + </entry> + <entry> + <para>The read-config-as-xml operation is responsible for representing the current managed resource as xml configuration.</para> + </entry> + </row> + <row> + <entry> + <para> + export-resource + + </para> + </entry> + <entry> + <para> + The export-resource operation is responsible for exporting a managed resource in a format that is acceptable and used in an import. The export-resource is special in the + + sense that there's built-in functionality to recursively traverse managed resources until it finds one that supports an export-resource operation. In other words you can + + register an export-resource operation on a sub-resource and it will be executed even by calling export-resource on any of it's ancestors. + + </para> + </entry> + </row> + <row> + <entry> + <para> + import-resource + + </para> + </entry> + <entry> + <para> + The import-resource operation is responsible for importing managed resources previously exported through an export-resource operation. + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + <section id="sid-8094332_GateInManagement-ContentType"> + + <title>Content Type</title> + <para>Content type defines the format of management requests/responses. The three content types supported at the moment are json, xml, and zip. Since read-config-as-xml (xml), export-resource (zip), and import-resource (zip) are content type specific operations, the response must be in that format. Other then that it's up to the extension on which content type is supported for each operation.</para> + </section> + <section id="sid-8094332_GateInManagement-PathTemplates"> + + <title>Path Templates</title> + <para> + Path templates are something that management extensions use to define dynamic content when registering resources. These path template variables are used during an export-resource to filter these managed resources. By specifying the + <code>filter</code> + attribute of an export-resource operation, managed resources can be explicitly included or excluded during export. + </para> + <para>The filter attribute has the following value syntax:</para> + <example> + <title>Filter Syntax</title> + <programlisting>[path-var]:(!)?[name],...[name];...[path-var]:(!)?[name],...[name]</programlisting> + </example> + <para>where path-var is the path template variable name, name is the name of a managed-resource, and the '!' char, which is optional, is to exclude that resource rather then include it. Below are some examples that use the path template variable 'foo':</para> + <example> + <title>Only include managed resource 'bar'</title> + <programlisting>foo:bar</programlisting> + </example> + <example> + <title>Include managed resource 'bar' and 'foo-bar'</title> + <programlisting>foo:bar,foo-bar</programlisting> + </example> + <example> + <title>Exclude managed resource 'bar'</title> + <programlisting>foo:!bar</programlisting> + </example> + <example> + <title>Exclude managed resource 'bar' and 'foo-bar'</title> + <programlisting>foo:!bar,foo-bar</programlisting> + </example> + <example> + <title>Multiple path template variables (foo and baz) separated by the ';' char</title> + <programlisting>foo:bar,foo-bar;baz:blah</programlisting> + </example> + <note> + <title>Note</title> + <para>For more information on the usage of path templates specific to a management extension, see the management extensions section below.</para> + </note> + </section> + </chapter> Added: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml =================================================================== --- epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml (rev 0) +++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml 2011-11-15 01:32:28 UTC (rev 8063) @@ -0,0 +1,502 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="sid-8094332_GateInManagement-REST"> + + <title>REST</title> + <para>The management REST component is responsible for mapping restful requests to management requests. It does this by locating the managed resource by mapping the request URL to a management address and then invoking an operation on that managed resource. It defines an entry point for RESTful clients, and exposes the registered managed resources and operations over REST.</para> + <section id="sid-8094332_GateInManagement-EntryPoint"> + + <title>Entry Point</title> + <para>To gain access to management resources and operations over REST a RESTful client must know the entry point URL, which is defined as follows:</para> + <example> + <title>URL Syntax</title> + <programlisting>http(s)://&amp;lt;host&amp;gt;:&amp;lt;port&amp;gt;/&amp;lt;rest-context-name&amp;gt;/private/managed-components</programlisting> + </example> + <para>Where the rest-context-name is the portal container's rest context name. So for the default portal, the rest context name is 'rest', and for a portal running on localhost and port 8080 the URL would be</para> + <example> + <title>URL Example</title> + <programlisting>http://localhost:8080/rest/private/managed-components/</programlisting> + </example> + <note> + <title>Note</title> + <para>The REST URL is protected, and the authenticated user must belong to the 'administrators' group of the portal.</para> + </note> + </section> + <section id="sid-8094332_GateInManagement-ResourceURLs"> + + <title>Resource URLs</title> + <para>REST resource URLs are mapped to management addresses, and since every managed resource has a unique management address, every managed resource can be represented by a unique REST URL. The URL for identifying managed resources is as follows:</para> + <example> + <title>URL Syntax</title> + <programlisting>http://&amp;lt;host&amp;gt;:&amp;lt;port&amp;gt;/&amp;lt;rest-context-name&amp;gt;/private/managed-components/&amp;lt;component-name&amp;gt;/&amp;lt;managed-resource-name&amp;gt;/&amp;lt;sub-resource-name&amp;gt;/.../&amp;lt;sub-resource-name&amp;gt;</programlisting> + </example> + <para>The URL below uniquely identifies a managed resource named 'foo-bar', which is a sub-resource of 'bar', and 'bar' being a managed resource of the managed component 'foo'.</para> + <example> + <title>URL Example</title> + <programlisting>http://localhost:8080/rest/private/managed-components/foo/bar/foo-bar</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-Operationsx"> + + <title>Operations</title> + <para>To map a RESTful request to an operation the REST component must somehow map the HTTP request to an operation name. It can achieve this by looking at three things (in order of precedence):</para> + <itemizedlist> + <listitem> + <para>HTTP URL Parameters</para> + </listitem> + <listitem> + <para>URL Extension</para> + </listitem> + <listitem> + <para>The HTTP method of the request.</para> + </listitem> + </itemizedlist> + <section id="sid-8094332_GateInManagement-HTTPMethod"> + + <title>HTTP Method</title> + <para>The following table shows which HTTP methods map to operation names.</para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + HTTP Method + + </para> + </entry> + <entry> + <para> + Management Operation + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + GET + + </para> + </entry> + <entry> + <para> + read-resource + + </para> + </entry> + </row> + <row> + <entry> + <para> + PUT + + </para> + </entry> + <entry> + <para> + update-resource + + </para> + </entry> + </row> + <row> + <entry> + <para> + POST + + </para> + </entry> + <entry> + <para> + add-resource + + </para> + </entry> + </row> + <row> + <entry> + <para> + DELETE + + </para> + </entry> + <entry> + <para> + remove-resource + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>This means that the same URL can invoke four different operations just by changing the HTTP method of the REST request.</para> + </section> + <section id="sid-8094332_GateInManagement-RequestParameter"> + + <title>Request Parameter</title> + <para> + Since the management system supports more then just four operations, operations can also be explicitly defined by including HTTP parameters as part of the REST request. For example by adding the query parameter + <emphasis role="strong">op</emphasis> + to the request URL, clients can define what operation to invoke. + </para> + <example> + <title>Custom operation defined in request parameter</title> + <programlisting>http://localhost:8080/rest/private/managed-components/foo/bar?op=some-custom-operation</programlisting> + </example> + <para>It's best practice to use the HTTP method to dictate the operation name when it can. However nothing stops a client explicitly setting operation names as request parameters.</para> + <note> + <title>Note</title> + <para>The following URL's are equivalent for a GET request:</para> + <itemizedlist> + <listitem> + <para> + <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar"/> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar?op=read-resource"/> + </para> + </listitem> + </itemizedlist> + </note> + </section> + <section id="sid-8094332_GateInManagement-URLExtension"> + + <title>URL Extension</title> + <para>Sometimes it's nice to represent REST resources as files, so two URL extensions have been added to support two common operations: read-config-as-xml and export-resource. By adding the following URL extensions at the end of the URL, you can invoke these two operations.</para> + <informaltable> + <tgroup cols="3"> + <thead> + <row> + <entry> + <para> + URL Extension + + </para> + </entry> + <entry> + <para> + Management Operation + + </para> + </entry> + <entry> + <para> + Example URL + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + .xml + + </para> + </entry> + <entry> + <para> + read-config-as-xml + + </para> + </entry> + <entry> + <para> + <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar.xml"/> + </para> + </entry> + </row> + <row> + <entry> + <para> + .zip + + </para> + </entry> + <entry> + <para> + export-resource + + </para> + </entry> + <entry> + <para> + <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar.zip"/> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>This is just a convenient way to specify the operation name as a file extension instead of specifying it as a request parameter.</para> + <note> + <title>Note</title> + <para>The following URL's are equivalent:</para> + <itemizedlist> + <listitem> + <para> + <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar.xml"/> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar?op=read-config-as-xml"/> + </para> + </listitem> + </itemizedlist> + </note> + </section> + </section> + <section id="sid-8094332_GateInManagement-Attributes"> + + <title>Attributes</title> + <para>Management attributes (which are part of a management request) are mapped by including all request parameters of the HTTP request as attributes. So if an operation supports certain attributes, query parameters can be added to the request URL to be used as attributes of the management request.</para> + <example> + <title>Attributes first-name and last-name as request parameters</title> + <programlisting>http://localhost:8080/rest/private/managed-components/foo/bar?first-name=john&amp;amp;last-name=doe</programlisting> + </example> + <section id="sid-8094332_GateInManagement-MultivalueAttributes"> + + <title>Multi-value Attributes</title> + <para>Management attributes can be multi-valued (meaning more then one value associated with an attribute). This is easy as HTTP query parameters can be multi-valued as well.</para> + <example> + <title>Multi-valued attribute colors as request parameters</title> + <programlisting>http://localhost:8080/rest/private/managed-components/foo/bar?colors=red&amp;amp;colors=green&amp;amp;colors=blue</programlisting> + </example> + </section> + </section> + <section id="sid-8094332_GateInManagement-ContentNegotiation"> + + <title>Content Negotiation</title> + <para> + The management framework defines Content Type to indicate the format of management requests and responses. Clients can dictate the content type of the management request by specifying the + <code>Accept</code> + and + <code>Content-Type</code> + headers of the HTTP request. The + <code>Accept</code> + header indicates the format of the response and the + <code>Content-Type</code> + header specifies the format of the request. Below is a list of request headers that map to the Content Type of the management system. + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + Header + + </para> + </entry> + <entry> + <para> + Content Type + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + application/json + + </para> + </entry> + <entry> + <para> + JSON + + </para> + </entry> + </row> + <row> + <entry> + <para> + application/xml + + </para> + </entry> + <entry> + <para> + XML + + </para> + </entry> + </row> + <row> + <entry> + <para> + application/zip + + </para> + </entry> + <entry> + <para> + ZIP + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <note> + <title>Note</title> + <para>JSON is the default content type.</para> + </note> + <section id="sid-8094332_GateInManagement-BrowserContentNegotiation"> + + <title>Browser Content Negotiation</title> + <para> + To make it easy to control the content type of management requests through the browser, the rest component supports the + <code>format</code> + HTTP parameter to dictate the format of the response. This is because most browsers already send an 'Accept' header. + </para> + <example> + <title>Specifying the response should be returned as xml</title> + <programlisting>http://localhost:8080/rest/private/managed-components/foo/bar?format=xml</programlisting> + </example> + <para> + Below is the list of + <code>format</code> + HTTP parameters which map to Content Types. + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + Format parameter + + </para> + </entry> + <entry> + <para> + Content Type + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + format=json (default) + + </para> + </entry> + <entry> + <para> + JSON + + </para> + </entry> + </row> + <row> + <entry> + <para> + format=xml + + </para> + </entry> + <entry> + <para> + XML + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <important> + <title>Important</title> + <para>Content negotiation is ignored for content type specific operations such as 'read-config-as-xml' and 'export-resource' since these cannot return different formats.</para> + </important> + </section> + <section id="sid-8094332_GateInManagement-readresource"> + + <title>resource</title> + <para> + Since the + <code>read-resource</code> + operation is a built in operation provided by the management component, as opposed to extensions, below documents the format of the response. + </para> + <example> + <title>HTTP Request</title> + <programlisting>GET /managed-components + +or + +GET /managed-components?op=read-resource</programlisting> + </example> + <example> + <title>Response as JSON</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/json + +{ + "description": "Available operations and children (sub-resources).", + "children": [ + { + "name": "foo", + "description": "Some description", + "link": { + "rel": "child", + "href": "http://localhost:8080/rest/private/managed-components/foo" + } + } + ], + "operations": [ + { + "operation-name": "read-resource", + "operation-description": "Lists information about a managed resource, including available operations and children (sub-resources).", + "link": { + "rel": "self", + "href": "http://localhost:8080/rest/private/managed-components" + "type": "application/json" + "method": "get" + } + } + ] +}</programlisting> + </example> + <example> + <title>Response as XML</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/xml + +&amp;lt;?xml version="1.0" encoding="UTF-8" standalone="yes"?&amp;gt; +&amp;lt;resource&amp;gt; + &amp;lt;description&amp;gt;Available operations and children (sub-resources).&amp;lt;/description&amp;gt; + &amp;lt;children&amp;gt; + &amp;lt;child&amp;gt; + &amp;lt;name&amp;gt;foo&amp;lt;/name&amp;gt; + &amp;lt;description&amp;gt;Some description&amp;lt;/description&amp;gt; + &amp;lt;link href="http://localhost:8080/rest/private/managed-components/foo" rel="child"/&amp;gt; + &amp;lt;/child&amp;gt; + &amp;lt;/children&amp;gt; + &amp;lt;operations&amp;gt; + &amp;lt;operation&amp;gt; + &amp;lt;operation-name&amp;gt;read-resource&amp;lt;/operation-name&amp;gt; + &amp;lt;operation-description&amp;gt;Lists information about a managed resource, including available operations and children (sub-resources).&amp;lt;/operation-description&amp;gt; + &amp;lt;link href="http://localhost:8080/rest/private/managed-components" rel="self" type="application/xml" method="get"/&amp;gt; + &amp;lt;/operation&amp;gt; + &amp;lt;/operations&amp;gt; +&amp;lt;/resource&amp;gt;</programlisting> + </example> + </section> + </section> + </chapter> Added: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-3-Command_Line_Interface.xml =================================================================== --- epp/docs/branches/5.2/Admin_Guide/en-US/chapter-3-Command_Line_Interface.xml (rev 0) +++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-3-Command_Line_Interface.xml 2011-11-15 01:32:28 UTC (rev 8063) @@ -0,0 +1,352 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="sid-8094332_GateInManagement-CommandLineInterface"> + + <title>Command Line Interface</title> + <para>The command line interface (CLI) component provides an interactive shell using CRaSH to map commands to management requests. It connects over SSH, using the CRaSH SSH plugin.</para> + <note> + <title>Note</title> + <para> + For more information on CRaSH please visit + <ulink url="http://code.google.com/p/crsh/"/> + . + </para> + </note> + <section id="sid-8094332_GateInManagement-DeployingtheCLI"> + + <title>Deploying the CLI</title> + <para> + To deploy the CLI you must first build the gatein-management project. The source is available on + <ulink url="http://github.com/gatein/gatein-management">github</... + . Once built you can then deploy the web application to a GateIn instance like below: + </para> + <example> + <title>Copy CLI artifact as an exploded war to application server</title> + <programlisting>cp -r cli/target/gatein-management-cli $JBOSS_HOME/server/default/deploy/gatein-management-cli.war</programlisting> + </example> + <important> + <title>Important</title> + <para>The CLI web application must be deployed as an exploded war</para> + </important> + </section> + <section id="sid-8094332_GateInManagement-RunningtheCLI"> + + <title>Running the CLI</title> + <para>After deploying the CLI web application you can connect to the CLI over SSH as follows</para> + <example> + <title>SSH Syntax</title> + <programlisting>ssh -p &amp;lt;port&amp;gt; &amp;lt;user&amp;gt;@&amp;lt;host&amp;gt;</programlisting> + </example> + <example> + <title>SSH Example</title> + <programlisting>ssh -p 2000 root@localhost</programlisting> + </example> + <para> + You can change the default port that SSH listens on by changing the property crash.ssh.port in the + <code>WEB-INF/crash/crash.properties</code> + file. + </para> + <example> + <title>crash.properties</title> + <programlisting># VFS configuration +crash.vfs.refresh_period=1 + +# SSH configuration +crash.ssh.port=2000</programlisting> + </example> + <important> + <title>Important</title> + <para>Make sure the configured port is open and not blocked by firewall settings.</para> + </important> + </section> + <section id="sid-8094332_GateInManagement-Commands"> + + <title>Commands</title> + <para> + The CLI component comes with a number of management commands that will execute operations on managed resources in the portal. For a listing of all commands available type in + <emphasis role="strong">help</emphasis> + in the shell. You can also add the help option + <emphasis role="strong">-h</emphasis> + or + <emphasis role="strong">--help</emphasis> + for each command for further information. Also the + <emphasis role="strong">man</emphasis> + command can be executed for even more detailed information about the command. + </para> + <section id="sid-8094332_GateInManagement-mgmt"> + + <title>mgmt</title> + <para> + The mgmt command allows a user to connect and disconnect from the management system. It also provides an + <code>exec</code> + command which allows more custom control over executing operations with the management system. + </para> + <example> + <title>mgmt help</title> + <programlisting>% mgmt -h +usage: mgmt[-h | --help] COMMAND [ARGS] + +The most commonly used mgmt commands are: + exec Manually executes a management operation + connect login to gatein management + disconnect disconnect from management system + +% mgmt connect -h +usage: mgmt [-h | --help] connect [-u | --username] [-p | --password] [-c | --container] + + [-h | --help] command usage + [-u | --username] the user name + [-p | --password] the user passowrd + [-c | --container] portal container name (default is portal) + +%</programlisting> + </example> + <para> + The + <code>mgmt connect</code> + command allows the user to connect to the management system, optionally specifying a portal container (default is 'portal'). Since management commands are administrative operations, the user must authenticate again in order to validate authorization to the portal container. + </para> + <example> + <title>Connecting to default portal container</title> + <programlisting>% mgmt connect +Password: +Successfully connected to gatein management system: [user=root, container='portal', host='127.0.0.1'] + +[ /]%</programlisting> + </example> + <example> + <title>Connecting to portal container 'sample-portal' as user john</title> + <programlisting>% mgmt connect -u john -c sample-portal +Password: +Successfully connected to gatein management system: [user=john, container='sample-portal', host='127.0.0.1'] + +[ /]%</programlisting> + </example> + <para> + The + <code>mgmt exec</code> + command allows complete control over what to send to the management system. + </para> + <example> + <title>mgmt exec help</title> + <programlisting>[ /]% mgmt exec -h +usage: mgmt [-h | --help] exec [-c | --contentType] [-f | --file] [-a | --attribute] [-o | --operation] path + + [-h | --help] command usage + [-c | --contentType] content type of an operation + [-f | --file] File name + [-a | --attribute] Specifies an attribute. + [-o | --operation] Operation name + path + +[ /]%</programlisting> + </example> + <example> + <title>Executing operation read-config-as-xml on managed component foo</title> + <programlisting>[ /]% mgmt exec --operation read-config-as-xml --contentType xml /foo +&amp;lt;?xml version='1.0' encoding='UTF-8'?&amp;gt; +&amp;lt;data&amp;gt;...&amp;lt;/data&amp;gt; + +[ /]%</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-cat"> + + <title>cat</title> + <para> + The + <code>cat</code> + command executes the + <code>read-config-as-xml</code> + operation on a managed resource and outputs the xml data to the shell. Obviously the managed resource must support the + <code>read-config-as-xml</code> + operation. + </para> + <example> + <title>cat help</title> + <programlisting>[ /]% cat -h +usage: cat [-h | --help] path + +   [-h | --help] command usage +   path + +[ /]% cat /foo +&amp;lt;?xml version='1.0' encoding='UTF-8'?&amp;gt; +&amp;lt;data&amp;gt;...&amp;lt;/data&amp;gt; + +[ /]%</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-cd"> + + <title>cd</title> + <para>The cd command changes the current path of the CLI.</para> + <example> + <title>cd help</title> + <programlisting>[ /]% cd -h +usage: cd [-h | --help] path + +   [-h | --help] command usage +   path + +[ /]%</programlisting> + </example> + <example> + <title>Change path to /foo/bar</title> + <programlisting>[ /]% cd /foo/bar + +[bar]%</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-ls"> + + <title>ls</title> + <para> + The + <code>ls</code> + command executes the + <code>read-resource</code> + operation on the current (or specified by the path) managed resource. + </para> + <example> + <title>ls help</title> + <programlisting>[ /]% ls -h +usage: ls [-h | --help] path + + [-h | --help] command usage + path + +[ /]% ls +foo +bar + +[ /]% ls /foo +baz + +[ /]%</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-pwd"> + + <title>pwd</title> + <para> + The + <code>pwd</code> + command prints out the current resource path of the CLI. + </para> + <example> + <title>pwd help</title> + <programlisting>[ /]% pwd -h +usage: pwd [-h | --help] + + [-h | --help] command usage + +[ /]% pwd +/ +[ /]% cd foo/baz + +[baz]% pwd +/foo/baz + +[baz]%</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-export"> + + <title>export</title> + <para> + The + <code>export</code> + operation executes the + <code>export-resource</code> + operation on a managed resource and writes the exported content to the file. + </para> + <important> + <title>Important</title> + <para>Since the CLI is connected to the portal server over SSH, the export command will write to the servers file system, not the client.</para> + </important> + <example> + <title>export help</title> + <programlisting>[ /]% export -h +usage: export [-h | --help] [-f | --file] [-r | --filter] path + + [-h | --help] command usage + [-f | --file] File name + [-r | --filter] Specifies the value of the filter to use during an export for example. + path + +[ /]%</programlisting> + </example> + <example> + <title>Export resource foo to /tmp directory</title> + <programlisting>[ /]% export --file /tmp foo +Export complete ! File location: /tmp/foo_2011-10-21_18-29-36.zip + +[ /%]</programlisting> + </example> + <note> + <title>Note</title> + <para>If you only specify a directory the export command will write a file with the name of the managed resource and a timestamp.</para> + </note> + <example> + <title>Export resource /foo to /tmp/export-example.zip file</title> + <programlisting>[ /]% export --file /tmp/export-example.zip foo +Export complete ! File location: /tmp/export-example.zip + +[ /%]</programlisting> + </example> + <example> + <title>Export resource filtering on path template variable bar</title> + <programlisting>[ /]% export --file /tmp/export-filter-example.zip --filter bar:baz,foo-bar foo +Export complete ! File location: /tmp/export-filter-example.zip + +[ /%]</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-import"> + + <title>import</title> + <para> + The + <code>import</code> + command executes the + <code>import-resource</code> + operation on a managed resource. + </para> + <example> + <title>import help</title> + <programlisting>[ /]% import -h +usage: importfile [-h | --help] [-f | --file] [-m | --importMode] path + + [-h | --help] command usage + [-f | --file] File name + [-m | --importMode] The import mode for an import operation + path + +[ /]%</programlisting> + </example> + <important> + <title>Important</title> + <para>Since the CLI is connected to the portal server over SSH, the import command must specify a file that exists on the server.</para> + </important> + <example> + <title>Import file /tmp/foo.zip to resource foo</title> + <programlisting>[ /]% import --file /tmp/foo.zip /foo +Successfully imported file /tmp/foo.zip + +[ /]%</programlisting> + </example> + <example> + <title>Import file /tmp/foo.zip to resource foo using importMode overwrite</title> + <programlisting>[ /]% import --file /tmp/foo.zip --importMode overwrite /foo +Successfully imported file /tmp/foo.zip + +[ /]%</programlisting> + </example> + <note> + <title>Note</title> + <para>You can autocomplete the import modes by typing --importMode and hitting tab.</para> + </note> + </section> + </section> + </chapter> Added: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions.xml =================================================================== --- epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions.xml (rev 0) +++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions.xml 2011-11-15 01:32:28 UTC (rev 8063) @@ -0,0 +1,558 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="sid-8094332_GateInManagement-ManagementExtensions"> + + <title>Management Extensions</title> + <para>The following management extensions supported in the portal are:</para> + <itemizedlist> + <listitem> + <para>MOP Management Extension</para> + </listitem> + </itemizedlist> + <section id="sid-8094332_GateInManagement-MOPManagementExtension"> + + <title>MOP Management Extension</title> + <para>The MOP management extension registers the 'mop' managed component which is responsible for managing pages, navigation, and site layout. It primarily supports exporting and importing this data through the export-resource and import-resource operations. It also supports the read-config-as-xml operation to expose the portal meta data as xml.</para> + </section> + <section id="sid-8094332_GateInManagement-Operationsxx"> + + <title>Operations</title> + <section id="sid-8094332_GateInManagement-readconfigasxml"> + + <title>config-as-xml</title> + <para> + The + <code>read-config-as-xml</code> + operation can only be executed on the site layout, pages, and navigation managed resources. The xml format returned is that of which is defined in by the + <ulink url="http://www.gatein.org/xml/ns/">gatein-objects</ulink... + xsd. This means that these resources are exposed in the same format as what a portal extension would accept for importing data into the portal. + </para> + </section> + <section id="sid-8094332_GateInManagement-exportresource"> + + <title>export-resource</title> + <para> + The + <code>export-resource</code> + operation can be executed on any resource of the MOP extension (including the mop component itself). Since the management system recursively searches for all sub-resources that have export-resource defined (which they are defined at the site layout, page, and navigation level), exports can be very granular. + </para> + </section> + <section id="sid-8094332_GateInManagement-importresource"> + + <title>import-resource</title> + <para> + The + <code>import-resource</code> + operation can only be executed at the mop component (root managed resource of the mop extension). This is because the exported zip file contains the path information (like site type and site name). So executing an + <code>import-resource</code> + operation on a group site, when the zip contains data from a portal site, doesn't make sense. + </para> + <para> + The MOP + <code>import-resource</code> + operation defines the + <code>importMode</code> + attribute as follows during import. + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + Mode + + </para> + </entry> + <entry> + <para> + Description + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + conserve + + </para> + </entry> + <entry> + <para> + Import data only if no artifacts exist for that site. For example if one page exists for site 'classic', nothing will be imported. + + </para> + </entry> + </row> + <row> + <entry> + <para> + insert + + </para> + </entry> + <entry> + <para> + Import data when data does not exist, otherwise do nothing. + + </para> + </entry> + </row> + <row> + <entry> + <para> + merge + + </para> + </entry> + <entry> + <para> + Import when data does not exist, update data when it does exist. + + </para> + </entry> + </row> + <row> + <entry> + <para> + overwrite + + </para> + </entry> + <entry> + <para> + Delete all data for that artifact of the site, import new data. For example if the zip file only contains pages for site classic, then + + all pages for that site are deleted and imported. + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <note> + <title>Note</title> + <para>'merge' is the default importMode.</para> + </note> + </section> + </section> + <section id="sid-8094332_GateInManagement-PathTemplatesx"> + + <title>Path Templates</title> + <para>Below are the list of path template variables defined in the MOP management extension. These path template variables are used for filtering during export.</para> + <itemizedlist> + <listitem> + <para> + <code>site-type</code> + + These are the site types of the portal to include or exclude. Available values are: + <code>portal</code> + , + <code>group</code> + , and + <code>user</code> + . + </para> + </listitem> + <listitem> + <para> + <code>site-name</code> + + The sites to include or exclude. Examples could be + <code>classic</code> + and + <code>/platform/administrators</code> + . + </para> + </listitem> + <listitem> + <para> + <code>site-layout</code> + + The name of the site layout depending on the site type. Available values are: + <code>portal</code> + , + <code>group</code> + , + <code>user</code> + . + </para> + </listitem> + <listitem> + <para> + <code>page-name</code> + + The name of the page(s) to include or exclude. + </para> + </listitem> + <listitem> + <para> + <code>nav-uri</code> + + The URI of the navigation node to include or exclude. + </para> + </listitem> + </itemizedlist> + </section> + <section id="sid-8094332_GateInManagement-RESTAPI"> + + <title>REST API</title> + <note> + <title>Note</title> + <para>All URL's below are relative to the REST management entry point of the portal container.</para> + </note> + <note> + <title>Note</title> + <para> + For all read-config-as-xml refer + <ulink url="http://www.gatein.org/xml/ns/gatein_objects_1_2"/> + for the format of the XML. + </para> + </note> + <section id="sid-8094332_GateInManagement-MOPComponentResource"> + + <title>MOP Component Resource</title> + <para> + The mop managed component resource (root managed resource) is the only resource that accepts the + <code>import-resource</code> + operation. + </para> + <example> + <title>HTTP Request</title> + <programlisting>PUT /mop + +Headers: + Content-Type: application/zip</programlisting> + </example> + <example> + <title>HTTP Response</title> + <programlisting>HTTP/1.1 200 OK</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-SiteLayoutResource"> + + <title>Site Layout Resource</title> + <para> + The site layout resource represents the site layout of the portal. It's the data defined in the + <emphasis role="strong">portal.xml</emphasis> + , + <emphasis role="strong">group.xml</emphasis> + , and + <emphasis role="strong">user.xml</emphasis> + files (depending on site type) used in portal extensions to configure data. + </para> + <example> + <title>URL</title> + <programlisting>URL: /mop/{site-type}sites/{site-name}/{site-layout}</programlisting> + </example> + <section id="sid-8094332_GateInManagement-readconfigasxmlx"> + + <title>config-as-xml</title> + <para>Example of reading the site layout as xml for site classic.</para> + <example> + <title>HTTP Request</title> + <programlisting>GET /mop/portalsites/classic/portal.xml + +or + +GET /mop/portalsites/classic/portal?op=read-config-as-xml</programlisting> + </example> + <example> + <title>HTTP Response</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/xml + +&amp;lt;portal-config&amp;gt; + &amp;lt;portal-name&amp;gt;classic&amp;lt;/portal-name&amp;gt; + &amp;lt;label&amp;gt;Classic&amp;lt;/label&amp;gt; + &amp;lt;description&amp;gt;GateIn default portal&amp;lt;/description&amp;gt; + &amp;lt;locale&amp;gt;en&amp;lt;/locale&amp;gt; +... +&amp;lt;/portal-config&amp;gt;</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-exportresourcex"> + + <title>export-resource</title> + <para>Example of exporting the site layout for site classic.</para> + <example> + <title>HTTP Request</title> + <programlisting>GET /mop/portalsites/classic/portal.zip + +or + +GET /mop/portalsites/classic/portal?op=export-resource</programlisting> + </example> + <example> + <title>HTTP Response</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/zip + +[binary data]</programlisting> + </example> + </section> + </section> + <section id="sid-8094332_GateInManagement-PagesResource"> + + <title>Pages Resource</title> + <para>The pages resource represents the pages of the portal. It's the data defined in the pages.xml used in portal extensions to configure data.</para> + <example> + <title>URL</title> + <programlisting>URL: /mop/{site-type}sites/{site-name}/pages/{page-name}</programlisting> + </example> + <section id="sid-8094332_GateInManagement-readconfigasxmlxx"> + + <title>config-as-xml</title> + <para>Example of reading all pages as xml for site classic.</para> + <example> + <title>HTTP Request</title> + <programlisting>GET /mop/portalsites/classic/pages.xml + +or + +GET /mop/portalsites/classic/pages?op=read-config-as-xml</programlisting> + </example> + <example> + <title>HTTP Response</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/xml + +&amp;lt;page-set&amp;gt; + &amp;lt;page&amp;gt; + &amp;lt;name&amp;gt;homepage&amp;lt;/name&amp;gt; + &amp;lt;title&amp;gt;Home Page&amp;lt;/title&amp;gt; + &amp;lt;access-permissions&amp;gt;Everyone&amp;lt;/access-permissions&amp;gt; + &amp;lt;edit-permission&amp;gt;*:/platform/administrators&amp;lt;/edit-permission&amp;gt; + &amp;lt;show-max-window&amp;gt;false&amp;lt;/show-max-window&amp;gt; + &amp;lt;portlet-application&amp;gt; +... +&amp;lt;/page-set&amp;gt;</programlisting> + </example> + <para>Example of reading the homepage as xml for site classic.</para> + <example> + <title>HTTP Request</title> + <programlisting>GET /mop/portalsites/classic/pages/homepage.xml + +or + +GET /mop/portalsites/classic/pages/homepage?op=read-config-as-xml</programlisting> + </example> + <example> + <title>HTTP Response</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/xml + +&amp;lt;page-set&amp;gt; + &amp;lt;page&amp;gt; + &amp;lt;name&amp;gt;homepage&amp;lt;/name&amp;gt; + &amp;lt;title&amp;gt;Home Page&amp;lt;/title&amp;gt; + &amp;lt;access-permissions&amp;gt;Everyone&amp;lt;/access-permissions&amp;gt; + &amp;lt;edit-permission&amp;gt;*:/platform/administrators&amp;lt;/edit-permission&amp;gt; + &amp;lt;show-max-window&amp;gt;false&amp;lt;/show-max-window&amp;gt; + &amp;lt;portlet-application&amp;gt; +... +&amp;lt;/page-set&amp;gt;</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-exportresourcexx"> + + <title>export-resource</title> + <para>Example of exporting all pages of site classic.</para> + <example> + <title>HTTP Request</title> + <programlisting>GET /mop/portalsites/classic/pages.zip + +or + +GET /mop/portalsites/classic/pages?op=export-resource</programlisting> + </example> + <example> + <title>HTTP Response</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/zip + +[binary data]</programlisting> + </example> + </section> + </section> + <section id="sid-8094332_GateInManagement-NavigationResource"> + + <title>Navigation Resource</title> + <para>The navigation resource represents the navigation of the portal. It's the data defined in the navigation.xml used in portal extensions to configure data.</para> + <example> + <title>URL</title> + <programlisting>URL: /mop/{site-type}sites/{site-name}/navigation/{nav-uri}</programlisting> + </example> + <section id="sid-8094332_GateInManagement-readconfigasxmlxxx"> + + <title>config-as-xml</title> + <para>Example of reading all navigation as xml for site classic.</para> + <example> + <title>HTTP Request</title> + <programlisting>GET /mop/portalsites/classic/navigation.xml + +or + +GET /mop/portalsites/classic/navigation?op=read-config-as-xml</programlisting> + </example> + <example> + <title>HTTP Response</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/xml + +&amp;lt;node-navigation&amp;gt; + &amp;lt;priority&amp;gt;1&amp;lt;/priority&amp;gt; + &amp;lt;page-nodes&amp;gt; + &amp;lt;node&amp;gt; + &amp;lt;name&amp;gt;home&amp;lt;/name&amp;gt; + &amp;lt;label xml:lang="en"&amp;gt;Home&amp;lt;/label&amp;gt; + ... + &amp;lt;visibility&amp;gt;DISPLAYED&amp;lt;/visibility&amp;gt; + &amp;lt;page-reference&amp;gt;portal::classic::homepage&amp;lt;/page-reference&amp;gt; + &amp;lt;/node&amp;gt; + &amp;lt;node&amp;gt; + &amp;lt;name&amp;gt;sitemap&amp;lt;/name&amp;gt; +... +&amp;lt;/node-navigation&amp;gt;</programlisting> + </example> + <para>Example of reading the home node as xml for site classic.</para> + <example> + <title>HTTP Request</title> + <programlisting>GET /mop/portalsites/classic/navigation/home.xml + +or + +GET /mop/portalsites/classic/navigation/home?op=read-config-as-xml</programlisting> + </example> + <example> + <title>HTTP Response</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/xml + +&amp;lt;node-navigation&amp;gt; + &amp;lt;priority&amp;gt;1&amp;lt;/priority&amp;gt; + &amp;lt;page-nodes&amp;gt; + &amp;lt;parent-uri&amp;gt;&amp;lt;/parent-uri&amp;gt; + &amp;lt;node&amp;gt; + &amp;lt;name&amp;gt;home&amp;lt;/name&amp;gt; + &amp;lt;label xml:lang="en"&amp;gt;Home&amp;lt;/label&amp;gt; + ... + &amp;lt;visibility&amp;gt;DISPLAYED&amp;lt;/visibility&amp;gt; + &amp;lt;page-reference&amp;gt;portal::classic::homepage&amp;lt;/page-reference&amp;gt; + &amp;lt;/node&amp;gt; + &amp;lt;/page-nodes&amp;gt; +&amp;lt;/node-navigation&amp;gt;</programlisting> + </example> + </section> + <section id="sid-8094332_GateInManagement-exportresource_Example"> + + <title>export-resource Example</title> + <para>Example of exporting all navigation of site classic.</para> + <example> + <title>HTTP Request</title> + <programlisting>GET /mop/portalsites/classic/navigation.zip + +or + +GET /mop/portalsites/classic/navigation?op=export-resource</programlisting> + </example> + <example> + <title>HTTP Response</title> + <programlisting>HTTP/1.1 200 OK +Content-Type: application/zip + +[binary data]</programlisting> + </example> + </section> + </section> + <section id="sid-8094332_GateInManagement-ExportandFiltering-1"> + + <title>Export and Filtering</title> + <para> + Filtering is activated when the + <code>filter</code> + attribute is passed to an + <code>export-resource</code> + operation. The filter attribute is a multi-value attribute that is passed as request parameters of the HTTP request. + </para> + <note> + <title>Note</title> + <para>You can either include multiple filter parameters (?filter=foo:bar&amp;filter=baz:foo-bar) or separate via ';' character (?filter=foo:bar;baz:foo-bar)</para> + </note> + <example> + <title>Export only registry and pageManagement navigation nodes</title> + <programlisting>GET /mop/groupsites/platform/administrators/navigation.zip?filter=nav-uri:/administration/registry,/administration/pageManagement</programlisting> + </example> + <example> + <title>Export all site types but user and group</title> + <programlisting>GET /mop.zip?filter=site-type:!user,group</programlisting> + </example> + </section> + </section> + <section id="sid-8094332_GateInManagement-CommandLineInterfacex"> + + <title>Command Line Interface</title> + <para>The commands included in the management component provide us the tools to perform management operations on these MOP artifacts: site layout, pages, and navigation.</para> + <section id="sid-8094332_GateInManagement-ResourcePaths"> + + <title>Resource Paths</title> + <para>The paths of the MOP resources are exactly the same as the REST URL's (of course without the URL syntax). For example the path of the homepage for the classic site would be:</para> + <example> + <title>Example</title> + <programlisting>[ /]% cd /mop/portalsites/classic/pages/homepage + +[homepage]% pwd +/mop/portalsites/classic/pages/homepage</programlisting> + </example> + <note> + <title>Note</title> + <para>All resources/paths can be autocompleted by hitting the tab key.</para> + </note> + </section> + <section id="sid-8094332_GateInManagement-ExportandFiltering-2"> + + <title>Export and Filtering</title> + <para> + Filtering is activated when the + <code>filter</code> + attribute is passed to an + <code>export-resource</code> + operation. The filter attribute is a multi-value attribute that is passed to the CLI using the + <code>--filter</code> + attribute for the + <code>export</code> + command. + </para> + <example> + <title>Export all portal site types</title> + <programlisting>export --file /tmp/mop.zip --filter site-type:portal /mop</programlisting> + </example> + <example> + <title>Export all sites types but user</title> + <programlisting>export --file /tmp/mop.zip --filter site-type:!user /mop</programlisting> + </example> + <para>The option can be specified multiple times for multiple values.</para> + <example> + <title>Export only the /platform/administrators group site</title> + <programlisting>export --file /tmp/mop.zip --filter site-type:group --filter site-name:/platform/administrators /mop</programlisting> + </example> + <para> + Also as discussed in the Path Templates section in this document, the filter attribute can separate different path templates by the + <code>;</code> + character. + </para> + <example> + <title>Export only pages named homepage, navigation named home for site classic</title> + <programlisting>export --file /tmp/classic.zip --filter page-name:homepage;nav-uri:home /mop/portalsites/classic</programlisting> + </example> + <important> + <title>Important</title> + <para>All three artifacts (site layout, navigation, and pages) are included in export by default. In other words if you don't specify their path template in the filter, the data will be included.</para> + </important> + </section> + </section> + </chapter>