Reference Information › Command Line Shell Reference Guide › Shell Commands › Application Control › application migrate

application migrate

Migrate an application from or to a remote grid. Application configuration parameters may be specified for the new application.

Syntax

app migrate <remote_grid> <app> [.name=<new name>]
                                   [.local_ip=<local> .remote_ip=<remote>]
                                   [.encr_key=<encr_key>]
                                [<option>]* [<prop>=<val>]* 

Options

.name=<new name>

New name for the migrated application.

.local_ip=<local>

IP information to be used for the migrator application on the local grid. The value has the following format:

[_vlan.][<vlan id>.]<ip address> |
                _net.<network name>.<ip_address>

remote_ip=<remote>

IP information to be used for the migrator application on the remote grid. The value has the following format:

[_vlan.][<vlan id>.]<ip address> |
                        _net.<network name>.<ip_address>

.encr_key=<encr_key>

Specifies the name of a volume containing fixed encryption keys to be supplied to the migrator applications performing the volume migration.

--export

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

--import

Migrate the application from the remote grid

--nocompress

Do not compress volumes when migrating application

--novols

Do not migrate the application volumes (only descriptors)

--nocleanup

Skip cleanup upon failure or completion(troubleshooting)

--debug

Show debug information during migration(troubleshooting)

--preserve_acl

Preserve the application ACL if it is present.

--preserve_local_acl

Preserve local principals in the application ACL.

--preserve_global_acl

Preserve global principals in the application ACL.

Parameters

<prop>=<val>

Config parameter pairs as used for the 'app config' command.

Examples

app migrate myoldgrid.ca.net myapp

Migrate application from a remote grid to the local grid.

app migrate grid1.ca.net crm7 usr_ip=64.4.47.21 out_ip=64.4.47.22

Migrate application from a remote grid and configure IP settings.

app migrate myoldgrid.ca.net myapp .name=mynewapp

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

app migrate mynewgrid.ca.net myapp --export

Migrate application from the local grid to the remote grid.

app migrate mynewgrid.ca.net myapp .local_ip=1.2.3.4 .remote_ip=2.3.4.5

Migrate application between grids with different architectures

Notes

• .local_ip and .remote_ip must be present if an application migration is being done between grids with different architectures.
• Applications that contain singleton or catalog class volumes may not be migrated between grids with different architectures.
• If neither the --export or --import options are specified, the application is migrated from the remote grid.
• If the original application is running, it will be stopped prior to the migration. Upon completing the migration, the new application will be started.
• If the original application is not running, the new application will not be started.
• 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 applications that have very large volumes.
• -see 'help app config' for online help on properties and resources. The full and per-property reset are not supported (--reset and -d <prop>).
• By default application ACLs are not preserved during migration.

application modify_acl

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

Syntax

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

Parameters

<principal>=owner

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

<principal>=<val>

Add or replace the specified principal in the application 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 <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 application ACL if it is present.

Valid access levels are: read, control, configure and full.

template=<name>

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

--test_only

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

Examples

application modify_acl my-app local:user:admin=full

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

application modify_acl my-app admin=full

Replace that portion of the 'myapp' application 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.

application provision

Provision, configure, and start an application. Application configuration parameters may be specified for the new application and sizes for application user and singleton class volumes.

Syntax

app provision <template-app> <target-app> [<option>]* 
              [<prop>=<val>]* [<vol>.[parN.]size=<val>]*
              [.store=<store>] [<vol>.store=<store>]*

Parameters

<template-app>

Name of existing application to use as a template.

<target-app>

name of the application that is to be created - the application must not currently exist.

<prop>=<val>

Config parameter pairs as used for the 'app config' command.

<vol>.[parN.]size=<val>

Specify new size for application user or singleton class volumes. Units may be specified (for example, 128M[B], 2G[B]). If units are not provided, it is assumed that the size is in MB. 'parN' specifies the size for partition N. The value can be absolute (that is, 20G) or relative (that is, +10G). parN refers to a primary, extended or logical partition or an lvm logical volume. For primary partitions, this can be specified as parN.size, for logical partitions, the syntax is parN.parM.size (N is the number of the extended partition, M is the number of the logical partition on it starting from 1).For lvm logical volumes the syntax is parN.lv_name.size.

.store=<store>

Specifies the volume store where the provisioned application's 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

<vol>.store=<store>

Specifies the volume store where the specified volume is to be created. If this parameter is specified,it overrides that specified in the .store=<store> parameter.

--skipstart

Skip starting of new application

--fscpy

Force copying of volumes using filesystem-level copy. If not specified, volumes are copied using filesystem-level copy only if they are being resized.

--prefill

Allocate ALL blocks for copied volumes. This option is only valid if --fscpy is specified; otherwise it is ignored.

Examples

app provision crm crm2 user_ip=64.4.47.21 out_ip=64.4.47.22
app provision myapp myapp-new data.size=128M mysql.data.size=256M
app provision myapp myapp-new data.size=128M mysql.boot.par1.size=256M mysql.boot.par2.root.size=1G

Notes:

• This command will fail if the template application is running.
• This command will fail if the template application does not have the 'template' attribute set. See 'app config'.
• This operation is similar to 'app copy' with added volume resizing, configuration, and application start.
• A single command can specify size for more than one partition/logical volume, which can also be used with the current size option that changes the size of the volume. If a size is specified for a partition/logical volume and the size of its container (the entity that holds that partition/logical volume) is not specified, the container will be resized to reflect the changes (leaving no free space). If size of the container is specified, it will be honored, which may leave free space on the volume/partition or may cause the operation to fail if the container size is not big enough.
• If more than one partition is being resized, they need to be supported by the same Filer or the operation will fail.
• See 'help app config' for online help on properties and resources. The full and per-property reset are not supported (--reset and -d <prop>).

application put_acl

Replace the entire application ACL.

Syntax

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

Parameters

<name>

Name of the application.

<principal>=owner

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

<principal>=<val>

Add the specified principal to the application 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 qualified principal name 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.

Valid access levels are: read, control, configure, and full.

--test_only

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

--force

Skip prompting the user for verification.

Examples

application put_acl my-app local:user:admin=owner local:user:admin=full

Replace the 'my-app' application ACL such that the owner is the local user 'admin' and local user 'admin' has full access level permissions.

application put_acl my-app admin=owner admin=full

Replace the 'my-app' application 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.

application put_desc

Modify application package descriptor.

Syntax

application put_desc app 

Parameters

app

name of application for which package descriptor is to be modified

Example

application put_desc my-app

modify package descriptor for application my-app

Note: The new descriptor is obtained from standard input.

The user can type in or paste the new descriptor contents followed by typing CTRL-d to terminate the input.

The name of the application may not be changed within the new descriptor.

The specified new descriptor is not checked for validity.

If the operation is executed remotely, the command can be specified as follows: ssh root@controllerhost app put_desc myapp < newdesc where newdesc is a file containing the modified descriptor.

application rename

Rename an application.

Syntax

application rename name new-name 

Parameters

name

Name of application to rename

new-name

New name of application

Examples

application rename lamp lampnew

Rename application 'lamp' to 'lampnew'

Note: This command will fail if the application is currently running or if there is already an application installed as new-name.

application repair

Repair an application.

Syntax

application repair name 

Arguments

name

Name of application to repair

Examples

application repair lamp

Repair application 'lamp'

Note: This command will fail if the application is not in ‘failed’ state. If the application is supposed to be running and there are components that are not running, then those components are restarted. If the application is supposed to be stopped and there are components that are not stopped, then those components are stopped.

application restart

Restart an application.

Syntax

application restart <name> ( <prop>=<val> )* [ store=<store>]
                            [ --debug ] [ --clean ] [ --norestart ] [ no_overcommit ]
                            [ --skipbuild ] [ --cap_cpu  ] [ --force ]

Parameters

<name>

Name of application.

<prop>=<val>

Parameters for scheduling. The following parameters may be specified:

cpu - (optional) CPU allocation (val[%])

mem - (optional) Memory allocation (val[M[B]|G[B]]). If units are not specified, memory is in MB.

bw - (optional) Bandwidth allocation (val[M[b]|G[b]]). If units are not specified, bandwidth is in Mbps.

sched - String specifying scheduling target (see below)

servers - Number of servers on which application is to be started;

<store>

Specifies which volume store in which instance 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

--debug

Restart application in debug mode. The restart will fail if this option is specified and the application has field engineering code 16 set.

--clean

Clean application prior to restart.

--norestart

Do not restart application upon grid failure.

--skipbuild

Do not build application prior to restart.

--no_overcommit

Disable overcommitment when scheduling the application.

--force

Force releasing any volumes that are currently in use without asking for verification. This is useful when restart is executed over an application that is not currently running.

--cap_cpu

Enable the capping of CPU for all components of the application.

(see notes below)

Examples

application restart my-app

Restart application

application restart my-app --debug

Restart application in debug mode

application restart my-app cpu=2 mem=1024M

Restart application with modified cpu and memory allocation

application restart my-app sched=crunch

Restart application with minimum resources allocated

Notes:

• This command combines application stop and start commands.

  The --clean and --skipbuild options may not be specified at the same time.

  The following scheduling targets are supported:

  sched="percentile=(resource percentile)"

  sched=crunch - assign the minimum resources to all components, same as "percentile=0"

  sched=expand - assign the maximum resources to all components, same as "percentile=100"

  sched="mode=(scheduling mode)", valid values are one of the following:

  1. pack servers, schedule appliances on server with least amount of available resources
  2. round robin with random start, randomly schedule first appliance to a server and then assign remaining appliances to other servers using round robin
  3. round robin, schedule first appliance on the first server and then assign remaining appliances to other servers using round robin
• When using the pack server scheduling mode, the servers are chosen in priority order based on their assigned role and the least amount of available resources. CA AppLogic will always use servers with a role of none first, primary second and secondary last; without regards to the available resources on those servers (that is, the primary server won't be used until all of the none servers are used, the secondary servers won't be used until all none servers and primary server are used).
• When an application is restarted with the --cap_cpu option, each appliance of the application cannot use more than its assigned CPU; for example if an appliance is assigned 30% CPU, it cannot use more than 30% CPU even if the CPU has available cycles. In contrast, not capping the CPU allows the appliances to use as much CPU as is available on the server.
• When an application is restarted with --debug and the application fails to start, CA AppLogic does not cleanup the application (i.e., stop any appliances that may have started successfully) so that the user might be able to determine the reason for the start failure. If the user is able to resolve the problem, he may continue starting the application using the 'app continue' command.
• The application restart will fail if --debug is specified and the application has field engineering code 16 set.
• Restarting an application resets the component flapping counters that are maintained by CA AppLogic. A component's flapping counter is the number of times that component has failed within the last 24 hours (each component has its own flapping counter). Once a component fails 3 times in 24 hours, the component is not restarted by CA AppLogic. comp start/restart or app start may also be used to reset a component's flapping counter.

application start

Start an application.

Syntax

application start <name> ( <prop>=<val>)* [ store=<store> ]
                       [ --debug ] [ --norestart ] [ --no_overcommit]
                       [ --skipbuild ] [ --force ] [ --cap_cpu ]

Parameters

<name>

Name of application.

<prop>=<val>

Parameters for scheduling. The following parameters may be specified:

cpu - (optional) CPU allocation in whole CPUs or percent (val[%])

mem - (optional) Memory allocation (val[M[B]|G[B]]). If units are not specified, memory is specified in MB.

bw - (optional) Bandwidth allocation (val[M[b]|G[b]]). If units are not specified, bandwidth is specified in Mbps.

sched - String specifying scheduling target (see below)

servers - Number of servers on which application is to be started;

<store>

Specifies which volume store in which instance 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

--debug

Start application in debug mode. The start will fail if this option is specified and the application has field engineering code 16 set

--norestart

Do not restart application upon grid failure.

--no_overcommit

Disable overcommitment when scheduling the application.

--skipbuild

Do not build application prior to start.

--force

Force unmounting of any volumes that are mounted without asking for verification.

--cap_cpu

Enable the capping of CPU for all components of the application.

(see notes below)

Examples

application start my-app

Start application

application start my-app --debug

Start application in debug mode

application start my-app cpu=2 mem=1024M

Start application with modified cpu and memory allocation

application start my-app sched=crunch

Start application with minimum resources allocated

Notes:

• The following scheduling targets are supported:

  sched="percentile=(resource percentile)"

  sched=crunch - assign the minimum resources to all components, same as "percentile=0"

  sched=expand - assign the maximum resources to all components, same as "percentile=100"

  sched="mode=(scheduling mode)", valid values are one of the following:

  1. pack servers, schedule appliances on server with least amount of available resources
  2. round robin with random start, randomly schedule first appliance to a server and then assign remaining appliances to other servers using round robin
  3. round robin, schedule first appliance on the first server and then assign remaining appliances to other servers using round robin
• When using the pack server scheduling mode, the servers are chosen in priority order based on their assigned role and the least amount of available resources. CA AppLogic will always use servers with a role of none first, primary second and secondary last; without regards to the available resources on those servers (that is, the primary server won't be used until all of the none servers are used, the secondary servers won't be used until all none servers and primary server are used).
• When an application is started with the --cap_cpu option, each appliance of the application cannot use more than its assigned CPU; for example if an appliance is assigned 30% CPU, then it cannot use more than 30% CPU even if the CPU has available cycles. In contrast, not capping the CPU allows the appliances to use as much CPU as is available on the server.
• When an application is started with --debug and the application fails to start, CA AppLogic does not cleanup the application (i.e., stop any appliances that may have started successfully) so that the user might be able to determine the reason for the start failure. If the user is able to resolve the problem, he may continue starting the application using the 'app continue' command.
• The application start will fail if --debug is specified and the application has field engineering code 16 set.
• Starting an application resets the component flapping counters. A component's flapping counter is the number of times that component has failed within the last 24 hours. Each component has its own flapping counter. Once a component fails 3 times in 24 hours, the component is not restarted. You can also use comp start/restart or app restart to reset a component flapping counter.

application stop

Stop an application.

Syntax

application stop <name>| --all [ --user | --force ] 

Parameters

name

Name of application to stop.

--all

Stop all applications.

--user

Stop all user applications. This option is only valid if --all is specified.

--force

Skip user prompt to verify whether it is OK to stop system applications.

Examples

application stop lamp

Stop application 'lamp'

application stop --all

stop all applications

application stop --all --user

stop only user applications

application stop --all --force

stop all applications and do not prompt if system applications should be stopped.

application unlock

Unlock an application.

Syntax

application unlock app [ pwd=-] [--override] 

Arguments

app

name of application to be unlocked

pwd=-

Prompt the user for the password that was provided when the application was locked. 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).

--override

Override the lock and unlock the application. This option is only available to grid maintainers.

Examples

application unlock my-app

Unlock application my-app

application unlock my-app pwd=-

Unlock application and prompt for password

Notes:

• If the application was locked with a password, the passwords must match
• If the application was locked without a password, then only a maintainer may unlock the application.

For more information, see Application and Class Locking Reference.