Reference Information › Command Line Shell Reference Guide › Shell Commands › Catalog Management

Catalog Management

This section contains the following topics:

catalog create

catalog destroy

catalog create

Create a new global catalog.

Syntax

cat create <name>

Parameters

name

Name of the catalog to create. It may be in the following format:

/catalog - Create a global catalog

Examples

cat create /system2

Create new global catalog named '/system2'

catalog destroy

Destroy an application or global catalog.

Syntax

catalog destroy catalog [ --force ]

Parameters

catalog

Name of the catalog to destroy. It may be in one of the following formats:

application/catalog: Destroy a local catalog of an application
/catalog: Destroy a global catalog

--force

skip asking verification to destroy the catalog

Examples

catalog destroy /system

Destroy global catalog

catalog destroy sugarcrm/local

Destroy local application catalog

catalog export

Export an entire catalog.

Syntax

cat export <catalog> <dir> [--force] [--nocompress] [ --preserve_acl | --preserve_local_acl | --preserve_global_acl ]

Options

<catalog>

Name of catalog to be exported. May specify one of the following:

a) <application>/<catalog>

b) /<catalog>

<dir>

Name of exchange directory relative to /vol/_impex where catalog is to be exported to

--force

Option to allow exporting of catalog class even if it is already present (i.e., each class is removed and then exported)

--nocompress

Option to disable compression of volume images.

--preserve_acl

Preserve the global catalog ACL if it is present.

--preserve_local_acl

Preserve local principals in the global catalog ACL.

--preserve_global_acl

Preserve global principals in the global catalog ACL.

Examples

cat export my-app/local catalog

Export all classes from local catalog of application 'my-app'.

cat export /system catalog

Export all classes from global catalog.

Notes

By default global catalog ACL's are not preserved during export.

catalog get_acl

Display the global catalog ACL, or display that portion of the global catalog ACL which relates to a particular principal.

Syntax

catalog get_acl <name> [ <principal> ] [ --batch ]

Parameters

<name>

Name of the global catalog.

<principal>

Name of a principal. <principal> is in the following form:

<name>: Local user or group.
/<name>: Global user or group.
<scope>:<type>:<name>: A fully qualified principal name where where <scope> is 'global' or 'local', <type> is 'group' or 'user', and <name> is the group or user name.

--batch

Display output in UDL format.

Examples

catalog get_acl /mycat

Display the catalog ACL.

catalog get_acl /mycat local:user:admin

Display the catalog ACL entry for local user 'admin'.

catalog get_acl /mycat admin

Display the catalog ACL entry for local user 'admin'.

Typical Output

The output of this command is as follows:

Non-batch output

--- Owner Information ---
ID                                    Scope    Type    Name
-------------------------------------------------------------------------
val                                   val      val     val
--- Entry Information ---
ID                                    Scope    Type    Name              Access
--------------------------------------------------------------------------------
val                                   val      val     val               val
...

The value of Scope is local or global. The value of Type is user or group. The value of Access is a comma separated list of access levels or permissions. If the principal is a local user or group which has been deleted, the value for Scope, Type and Name is *.

Batch output

acl
   {
   owner       : id="val"   # scope type name
   entries
      [
      id="val", access_level1, ... access_levelN, permission1, ... permissionN   # scope type name
      ...
      ]
   }

catalog get_desc

Display application or global catalog package descriptor.

Syntax

catalog get_desc catalog

Arguments

catalog

Name of the catalog for which to display package descriptor. It may be in one of the following formats:

application/catalog - Display application local catalog package descriptor

/catalog - Display global catalog package descriptor

Examples

catalog get_desc /system

Display global catalog package descriptor

catalog get_desc sugarcrm/local

Display local application catalog package descriptor

catalog import

Import an entire catalog.

Syntax

cat import <catalog> <dir> [ store=<store>][--force][ user=<user>[ pwd=- ] ]
[ --preserve_acl | --preserve_local_acl | --preserve_global_acl ]

Options

<catalog>

Name of catalog to be imported. May specify one of the following:

a) <application>/<catalog>

b) /<catalog>

<dir>

Name of exchange directory from which the catalog is to be imported. The directory may be one of the following:

Directory relative to /vol/_impex

URL with the following format 'http://<path>'

<store>

Specifies the volume store where volumes are created. May be set to one of the following values:

local - store volumes on local server storage

san - store volumes on a SAN

--force

Option to allow importing of catalog even if it is already present (that is, each class is removed and then imported)

user=<user>

Name of user to use for authentication purposes when importing the catalog from a URL

pwd=-

(Optional) Prompt for password to use for authentication purposes when importing the catalog from a URL. If the standard input is not a terminal device, it will not print a prompt and expect only one copy of the password on 'stdin' (this can be used for batch operations, to set the password from a file).

--preserve_acl

Preserve the global catalog ACL if it is present.

--preserve_local_acl

Preserve local principals in the global catalog ACL.

--preserve_global_acl

Preserve global principals in the global catalog ACL.

Examples

cat import my-app/local catalog

Import all classes to local catalog of application 'my-app'

cat import /system catalog

Import all classes to global catalog

Notes

By default global catalog ACL's are not preserved during import.

catalog info

Display information for a local application or global catalog.

Information displayed includes: name, description, number of classes, total disk space and list of protocols.

Syntax

catalog info package [ --batch ] [ --verbose ]

Parameters

package

Name of the package for which to display information.

application/catalog - Display information for a local catalog of an application

/catalog - Display information for a global catalog

--batch

Display output in UDL format

--verbose

Include list of protocols

Examples

catalog info /system

Display information for global catalog

catalog info sugarcrm/local

Display information for local application catalog

Note: A specification of the output of this command can be found here.

Typical Output

Name                : system
Description        :
Total Classes    : 26
Total Diskspace : 14.90 GB

catalog info Output

The output of this command is the following (protocols are displayed if -verbose option is provided.

Name                : val
Description         : val
Total classes       : val
Total diskspace     : val GB
Protocols           :
   (table containing the following columns: Name, Filter)

If --batch option is specified, the output is the following:

catalog <name>

   {          
   description      =  "val"    
   total_classes    =  val  
   total_diskspace  =  val  
   protocol <name>  : filter="<val>"
}

catalog list

List global catalogs.

Syntax

catalog list [ --batch ]

Parameters

--batch: Display output in UDL format

Examples

catalog list

List global catalogs

Note: A specification of the output of this command can be found here.

Typical Output

Global Catalogs

Name      Description
---------------------
proto
system
user
dynamic
filer

catalog list Output

This topic contains command output specification.

The output of this command when listing global catalogs if a table with the following columns:

name - name of catalog
description - catalog description

If --batch option is specified, the output is the following:

catalog <name> : description="<val>"
...

catalog migrate

Migrate a catalog from or to a remote grid.

Syntax

cat migrate <remote_grid> <cat> [.name=<new name>][.store=<store>] [<option>]*

Options

<cat>

Name of catalog to migrate. It may a global or application local catalog.

.name=<new name>

New name for the migrated catalog. It may be a global or application local catalog.

.store=<store>

Specifies the volume store where volumes are created. May be set to one of the following values:

local - store volumes on local server storage

san - store volumes on a SAN

--export

Migrate the catalog to the remote grid. This requires bi-directional trust between the two grids.

--import

Migrate the catalog from the remote grid.

--nocompress

Do not compress volumes when migrating the catalog.

--nocleanup

Skip cleanup upon failure or completion (troubleshooting).

--debug

Show debug information during migration (troubleshooting)

--preserve_acl

Preserve the global catalog ACL if it is present.

--preserve_local_acl

Preserve local principals in the global catalog ACL.

--preserve_global_acl

Preserve global principals in the global catalog ACL.

Examples

cat migrate myoldgrid.3tera.net /mycat

Migrate a global catalog from a remote grid to the local grid.

cat migrate myoldgrid.3tera.net /mycat .name=/mynewcat

Migrate a global catalog from a remote grid and rename it in the process.

cat migrate mynewgrid.3tera.net myapp/local .name=/newlocal

Migrate an application local catalog from a remote grid as a global catalog on the local grid.

Notes

The catalog MUST NOT exist on the destination grid.
If neither the --export or -import options are specified, the catalog is migrated FROM the remote grid.
SSH agent and agent forwarding must be enabled on the client machine for the remote grid access to work.
--nocompress option is useful when migrating catalogs that have very large volumes.
By default global catalog ACL's are not preserved during migration.

catalog modify_acl

Replace that portion of the global catalog ACL which relates to the owner or a principal.

Syntax

catalog modify_acl <name> [ <principal>=owner ] [ <principal1>=<val1> ... <principalN>=<valN> ] [ template=<name> ][ --test_only ]

Parameters

<principal>=owner

Set the owner attribute of the catalog ACL to the specified principal.

<principal>=<val>

Add or replace the specified principal in the catalog ACL with access level <val>. <principal> is in the following form:

<name>: Local user or group.
/<name>: Global user or group.
<scope>:<type>:<name>: A fully qualified principal name where where <scope> is 'global' or 'local', <type> is 'group' or 'user', and <name> is the group or user name. Valid access levels are: read, control, configure and full. If the access level is specified as 'none' the principal is removed from the catalog ACL if it is present.

template=<name>

Replace the principal entries of the catalog ACL with those of the specified template catalog.

--test_only

Do not replace any portion of the catalog ACL but rather test if the operation can succeed.

Examples

catalog modify_acl /mycat local:user:admin=full

Replace that portion of the global catalog 'mycat' ACL which relates to the local user 'admin', providing full access level permissions to this user.

catalog modify_acl /mycat admin=full

Replace that portion of the global catalog 'mycat' ACL which relates to the local user 'admin', providing full access level permissions to this user.

Notes

Specified local user and group principals must exist.
Specified global user principals must have logged in to the grid at some time in the past.
Specified global group principals must be associated to a global user who has logged in to the grid at some time in the past.

catalog put_acl

Replace the entire global catalog ACL.

Syntax

catalog put_acl <name> <principal>=owner [ <principal1>=<val> ... <principalN>=<val> ] [ --test_only | --force ]

Parameters

<name>

Name of the global catalog.

<principal>=owner

Set the owner attribute of the catalog ACL to the specified principal.

<principal>=<val>

Add the specified principal to the catalog ACL with access level <val>. <principal> is in the following form:

<name>: Local user or group.
/<name>: Global user or group.
<scope>:<type>:<name>: A fully qualified principal name where where <scope> is 'global' or 'local', <type> is 'group' or 'user', and <name> is the group or user name. Valid access levels are: read, control, configure and full.

--test_only

Do not replace the catalog ACL but rather test if the operation can succeed.

--force

Skip prompting the user for verification.

Examples

catalog put_acl /mycat local:user:admin=owner local:user:admin=full

Replace the 'mycat' global catalog ACL such that the owner is the local user 'admin' and local user 'admin' has full access level permissions.

catalog put_acl /mycat admin=owner admin=full

Replace the 'mycat' global catalog ACL such that the owner is the local user 'admin' and local user 'admin' has full access level permissions.

Notes

Specified local user and group principals must exist.
Specified global user principals must have logged in to the grid at some time in the past.
Specified global group principals must be associated to a global user who has logged in to the grid at some time in the past.

catalog put_desc

Replace catalog package descriptor with descriptor obtained from standard input.

Syntax

catalog put_desc catalog

Parameters

catalog

Name of the catalog for which to modify package descriptor. It may be in one of the following formats:

application/catalog - Modify application local catalog package descriptor

/catalog - Modify global catalog package descriptor

Examples

catalog put_desc /system

Modify global catalog package descriptor

catalog put_desc sugarcrm/local

Modify local application catalog package descriptor

Notes:

The descriptor is obtained from standard input. The user may type in or paste the contents of the new descriptor followed by CTRL-d to terminate the input.
The specified new descriptor is not checked for validity.
The name of the catalog may not be changed.
If executed remotely, the command can be specified as follows:
```
'ssh root@<controllerhost> catalog put_desc /system < <newdesc>'
```
where <newdesc> is a file containing the modified descriptor.

catalog rename

Rename a global catalog.

Syntax

catalog rename catalog new-catalog

Parameters

catalog

Name of the catalog to rename. It may be in one of the following formats:

/catalog - Rename a global catalog

new-catalog

New name for the catalog. It must be in the form of /catalog.

Examples

catalog rename /system /system-old

Rename system catalog to system-old

Notes:

The renaming of catalog does not update any references to the old catalog within existing applications.
This command will fail if any of the catalog volumes are in use.