Utility commands

The utility commands allow you to run and monitor Application Controller utilities through the eaccmd tool.

There are three kinds of Utility commands: Shell, Copy, and Archive.

Keep in mind the following general points about Application Controller utilities.

The List Directory Contents command lets you see the contents of directories on remote machines. Its behavior is similar to that of ls on UNIX, although some non-ls restrictions, noted below, apply.

Command

Description

ls --app app_id --host host_id --pattern file_pattern

Returns a list of files matching the pattern input in file_pattern. Note the following: A file_pattern must start with an absolute path, such as C:\ or /. A file_pattern can contain . or .. as directory names, and expands * and ? wildcards. A file_pattern cannot contain the wildcard expressions .*, .?, or ..* as directory or file names. Bracketed wildcards, such as file[123].txt, are not supported. Wildcards cannot be applied to drive names. You cannot use .. to create paths that do not exist. For example, the path /temp/../../a.txt refers to a path that is above the root directory. This is an invalid path that causes the operation to fail.

The List Directory Contents command expands the wildcards in a pattern. If the expansion results in a file, it returns a file. If the expansion results in a directory, it returns the directory non-recursively. Wildcard expansion can result in any combination of files and directories.

For example, assume that the following directories and files exist:

/home/endeca/reference/...
/home/endeca/install.log
/home/e.txt

The following command: 

eaccmd ls --app my_wine --host my_host --pattern /home/e\\*

would list all of these files and directories, because they match the file_pattern.

To prevent inappropriate expansion, any wildcard arguments you use with the List Directory Contents utility in eaccmd need to be delimited with double quotation marks. For example: On Windows, "C:\*.txt". On UNIX, "/home/endeca/test/*.txt".

The Shell utility allows you to run arbitrary commands in a host system shell.

Command

Description

start-util --type shell --app app_id [--token token] --host host_id [--wd working_dir] --cmd command [args...]

Starts a Shell utility with the specified command string. The token is a string. If you do not specify a token, one is generated and returned when you start the utility. The token is used to stop the utility or to get its status. --wd, which is optional, sets the working directory for the process that gets launched. If specified, it must be an absolute path. If wd is not specified, the setting defaults to %ENDECA_CONF%\working\ <appName>\shell on Windows or $ENDECA_CONF/working/ <appName>/shell on UNIX. The --cmd arguments are passed in a single string. If --cmd is omitted, the first unrecognized argument is taken as the start of your command.

stop-util --app app_id --token token

Stops a Shell utility. The token is a string, either user-created or generated and returned when you start the utility, that eaccmd prints to screen. The token can be used to stop the utility or to get its status.

status-util --app app_id --token token

Gets the status of a Shell utility. The token is a string, either user-created or generated and returned when you start the utility, that eaccmd prints to screen. The token can be used to stop the utility or to get its status.

The first example deletes the Dgidx output after it has been copied in a separate action over to the Dgraph:

eaccmd start-util --type shell --app my_wine --host mkt1010
--cmd rm <dgidx-output-dir>/*.*

The second example performs a recursive directory copy:

eaccmd start-util --type shell --app myapp --host hosttorunon
--cmd cp–r /mysourcedir /mydestdir

In many cases, particularly cross-platform scenarios, the Shell command must be wrapped in double quotation marks. The error message returned, which occurs at the console level, is usually something similar to the following: 

The system cannot find the path specified.

The Copy utility uses an internal Web services interface to copy files or directories, either locally or between machines.

Commands

Description

start-util --type copy --app app_id [--token token] [--recursive] --from host_id --to host_id --src file_pattern --dest dest_path

As part of the Copy utility, starts a copy. You identify the hostname, port, and path for both the source and destination directories. If the copy is local, you do not need to specify the host_id.

Keep in mind that you are not necessarily copying to the machine you are running eaccmd on. The hosts you are copying to and from are those you specified in your provisioning file.

--token is a string used to stop the utility or get its status. If you do not specify a token, one is generated and returned when you start the utility.

If --recursive is specified, it indicates that the Copy utility recursively copies any directories that match the wildcard.

If --recursive is not specified, the Copy utility does not copy directories, even if they match the wildcard. Instead, it creates intermediate directories required to place the copied files at the destination path.

--src is a string representing the file, wildcard, or directory to be copied. A --src must start with an absolute path, such as C:\ or /. A --src can contain . or .. as directory names, and expands * and ? wildcards.

Note the following:

--dest is the full path to the destination file or directory. --dest must be an absolute path, and no wildcards are allowed.

If --dest is a directory, that directory must exist, unless the following conditions are met:

stop-util --app app_id --token token

Stops a Copy utility. The token is a string, either user-created or generated and returned when you start the utility, that eaccmd prints to screen. The token can be used to stop the utility or to get its status.

status-util --app app_id --token token

Gets the status of a Copy utility. The token is a string, either user-created or generated and returned when you start the utility, that eaccmd prints to screen. The token can be used to stop the utility or to get its status.

This section illustrates several different Copy actions. For simplicity, the majority of the Copy actions are done on a single machine. The final example shows how to copy across machines.

First, assume the following directory structure exists on the source:

/
	endeca1/
		work/
			dgraphlogs/
				a.log
			forgelogs/
				b.log
	endeca2/
		work/
			dgraphlogs/
				c.log
			forgelogs/
				d.log
				e.log
	destination/

The following command copies one file to a new name:

eaccmd start-util --type copy --app myApp  
   --src "/endeca1/work/dgraphlogs/a.log" --dest "/destination/out.log"

The resulting directory change would look like this:

	destination/
		out.log

The following command copies one file into an existing directory:

eaccmd start-util --type copy --app myApp 
   --src "/endeca1/work/dgraphlogs/a.log" --dest "/destination"

The resulting directory change would look like this:

destination/
	a.log

The following command recursively copies a directory to a new name:

eaccmd start-util --type copy --app myApp 
   --src "/endeca1/work/dgraphlogs" --dest "/destination/outlogs" --recursive

The resulting directory change would look like this:

destination/
	outlogs/
		a.log

The following command recursively copies a directory into an existing directory:

eaccmd start-util --type copy --app myApp 
   --src "/endeca1/work/dgraphlogs" --dest "/destination"
   --recursive

The resulting directory change would look like this:

destination/
	dgraphlogs/
		a.log

The following command copies all files in a directory.

eaccmd start-util --type copy --app myApp 
   --src "/endeca2/work/forgelogs/*" --dest "/destination"

The resulting directory change would look like this:

destination/
		d.log
		e.log

The following copy command demonstrates the use of multiple wildcards:

eaccmd start-util --type copy --app myApp 
   --src "/e*/work/*logs/*.log" --dest "/destination"

The resulting directory change would look like this:

destination/
		a.log
		b.log
		c.log
		d.log
		e.log

The following copy demonstrates a recursive copy with wildcards:

eaccmd start-util --type copy --app myApp 
   --src "/e*/work" --dest "/destination" --recursive

The resulting directory change would look like this:

destination/
	work/
		dgraphlogs/
			a.log
			c.log
		forgelogs/
			b.log
			d.log
			e.log

When copying to another machine, the syntax is as follows:

eaccmd start-util --type copy --app myApp --from ITLHost --to MDEXHost 
   --src /full/path/to/file/src.txt --dest /full/path/to/file/dest.txt

Keep in mind that the hostnames are not IP addresses or DNS names, but rather are the hosts that are defined within the EAC. If you are using the Deployment Template, these are the hosts defined in the AppConfig.xml file with tags similar to this example:

<host id="ITLHost" hostName="itl.example.com" port="8888" />
<host id="MDEXHost" hostName="mdex.example.com" port="8888" />

Also make sure that you have a clear network path between hosts (if necessary, make the appropriate modifications in any firewall to allow traffic).

This topic provides details about how the Copy utility works.

The Copy utility supports wildcards (* and ?) and recursive copying. In some cases, the destination directory must already exist; in others, the utility automatically creates both the destination directory and any empty directories in the transfer.

Directories are copied first to a temporary directory on the destination machine before being copied one file at a time to the target location. You can configure the location of this temporary directory in the eac.properties file, using the optional setting com.endeca.eac.filetransfer.fileTransferTempDir as follows:

If the Copy utility tries to copy a file to a location where another file already exists, the utility overwrites the preexisting file.

Note

The Copy utility supports both SSL and non-SSL communication, with SSL being off by default. For details on enabling SSL, see the Oracle Commerce Guided Search Security Guide.

In most cases, the destination directory where the copied files are placed has to exist already. However, there are a few exceptions where the destination directory does not have to exist prior to the copy:

The following situations result in a failure of the Copy utility:

There is no recovery for copies. Therefore, if the transfer of a large file fails, the entire file must be transferred again. Likewise, if a multi-file transfer fails before completion, you must either re-run the entire transfer or request only those parts that did not transfer.

Keep in mind that when you are using the Copy utility, you are potentially working with three machines: the EAC Central Server, from which you issue eaccmd commands, the Agent machine you are copying data from, and the one you are copying data to. In such cases, the name localhost can be confusing. Unless you are using the Copy utility to move files on a single machine, you should use explicit machine names rather than simply localhost.

To prevent inappropriate expansion, any wildcard arguments you use with the Copy utility in eaccmd need to be delimited with double quotation marks. For example:

On Windows, "C:\*.txt".

On UNIX, "/home/endeca/test/*.txt".

If you are copying files or directories between machines on different platforms, you have to wrap any Window paths on a Linux or Solaris shell in double quotation marks (for example, "C:\*.txt").

The Archive utility allows you to archive and roll back directories.

Using the Archive utility, you can save off and back up a set of component outputs, which later can be rolled back on demand. With the backup operation, you create back up copies of directories distinguished by time stamps. With the rollback operation, you replace the current version of a directory with the most recently backed-up version. The current version is then renamed with an .unwanted suffix.

Note

Do not start a backup or rollback operation while another such operation is in progress on the same directory. Unexpected behavior may occur if you do so.

Backup operations create an archive directory from an existing directory.

Backup operations create an archive directory from an existing directory. The archive directory has the same name as the original directory, but with a timestamp appended to the end. The timestamp reflects the time when the backup operation was performed.

For example, if the original directory is called logs and was backed up on October 11, 2008 at 8:00 AM, the backup operation creates a directory called logs.2008_10_11.08_00_00.

Command

Description

start-util --type backup --app app_id [--token token] --host host-id --dir dir [--method] <copy|move> [--backups num_backups]

Starts the backup operation. The token is a string. If you do not specify a token, one is generated and returned when you start the utility. The token is used to stop the utility or to get its status. The host and dir settings specify the path to the directory that will be archived. The method is either copy or move (the default).

The optional backups setting specifies the maximum number of archives to store. This number does not include the original directory itself, so if backups is set to 3, you would have the original directory plus up to three archive directories, for a total of as many as four directories. The default num_backups is 5.

stop-util --app app_id --token token

Stops a backup operation. The token is a string, either user-created or system-generated when you start the utility. The token can be used to stop the utility or to get its status.

status-util --app app_id --token token

Gets the status of a backup operation. The token is a string, either user-created or system-generated when you start the utility. The token can be used to stop the utility or to get its status.

In the following example, an archive version of the logs directory is created.

eaccmd start-util --type backup --app my_wine --host mkt1010
--dir c:\my_wine\data\logs --backups 2

Rollback operations roll back the directory to the most recent backed up version.

For example, say you have a directory called logs, one called logs.2008_10_11.08_00_00, and other, older versions. When you roll back, the following things happen:

Note

There can only be a single .unwanted directory at a time. If you roll back twice, the .unwanted directory from the first rollback is deleted.

Command

Description

start-util --type rollback --app app_id [--token token] --host host_id --dir dir

Starts the rollback operation. The token is a string. If you do not specify a token, one is generated and returned when you start the utility. The token is used to stop the utility or to get its status. The host and dir settings specify the path to the directory that will be rolled back.

stop-util --app app_id --token token

Stops a rollback operation. The token is a string, either user-created or generated and returned when you start the utility, that eaccmd prints to screen. The token can be used to stop the utility or to get its status.

status-util --app app_id --token token

Gets the status of a rollback operation. The token is a string, either user-created or generated and returned when you start the utility, that eaccmd prints to screen. The token can be used to stop the utility or to get its status.

In the following example, the archived logs directory is rolled back.

eaccmd start-util --type rollback --app my_wine --host mkt1010
--dir c:\my_wine\data\logs

Copyright © Legal Notices