The TDV Package Export Utility

The pkg_export command-line utility let you export specified TDV Server directories and resources to a single CAR file, which provides these advantages:

• All metadata files and resources are aggregated.
• Multiple resource files are packaged in a compressed, portable archive.

The pkg_export utility is available in <TDV_install_dir>/bin. Different versions are provided for use in different computing environments.

Platform

Utility

Windows

pkg_export.bat

UNIX

pkg_export.sh

Note: For details about using Studio to export selected resources, see the TDV User Guide.

The System user of the Operating System where the TDV Server is running on, should have write access to TDV_INSTALL/conf/server directory

The pkg_export utility exports each of the listed resources (using a namespace path such as /users/composite/manager/sources). It does not include any domains, users, groups, or server settings.

Any user can execute this command. If you do not have Read privilege on any of the specified resources, the export fails. If you have the Read privilege for all resources and their children, all children are also included.

Note: Child resources for which the user does not have the Read privilege are omitted from the export package, without notice.

To use the package export utility

1. Open a command prompt window.
2. Navigate to <TDV_install_dir>/bin.
3. Run the pkg_export command: 
./pkg_export -pkgfile <filename>
-encryptionPassword <encryptionPassword>
-server <hostname> [ -port <port> ] [ -encrypt ]
[-user <username> ] [ -password <password> ] [ -domain <domain> ]
[-sso ] [ -sspi ] [ -spn <spn> ] [ -krb5Conf <krb5Conf> ] 
[-pkgname <name> ] [ -description <text> ]
[-optfile <filename> ] ...
[-optfilePassword <optpassword>]
[-newOptfilePassword <new optpassword>]
[-rebindable <path> <description> ] ...
[-includeaccess ] [ -includecaching ]
[-nosourceinfo ] [ -includejars ]
[-includeAllUsers] [ -includeUser <domain> <user> ] ...
[-includeGroup <domain> <group>] ... [ -includeDomain <domain> ]
[-includeRequiredUsers ] [ -includeDependencies ]
[-includeStatistics ]
[-genopt <filename> ] [-optfilePassword <optpassword>]
[-verbose ] [ -quiet ]
[-includeParentResources]

The table below describes the pkg_export parameters, in alphabetical order.

Package Export Parameter

Optional / Required

Comments

-pkgfile <file_name>

Required

The new CAR file name.

-encryptionPassword

Required

The password used to encrypt /decrypt sensitive data in your car file, for example, data source password, etc.

-server <host_name>

Required

TDV Server host to which the utility connect.

-port <port_number>

Optional

Specifies Web Services base port (HTTP) to use to communicate with the TDV Server. The default value is 9400.

-encrypt

Optional

Encrypts communication between the command line and TDV using SSL sent over the dedicated HTTPS port. The HTTPS port is the base port number plus 2.

-user <user_name>

Required

TDV system administrative user name. The user must have ownership of the specified resource or at least read privilege on all the specified resources with Access Tools and Read All Config rights.

-password <password>

Required

Password for user profile used to export package.

Note: When using an optfile, if the password contains a double quote character, it is necessary to escape the character with a double-quote.

-domain <domain>

Optional

User domain. The default value is composite. Specify a value if the exporting user’s domain is not composite.

-sso

Optional

Enables SSO authentication. Must be used with the -spn option.

You do not need to input a user name or password.

-sspi

Optional

For Windows environments configured with SSPI, you can use this parameter after -sso and -spn.

-spn <spn>

Optional

Use this parameter after specifying -sso, to indicate what the service principal name is. Use one of the following formats depending on the protocol you are using:

• sspi is <ServiceName/Full_ComputerName@Realm>
• JGSS is <ServiceName@Full_ComputerName>

-krb5Conf <krb5Conf>

Optional

For environments configured with multiple Kerberos authentication files, you can use this parameter after -sso and -spn to specify which authentication file to use.

<krb5Conf> must specify the full path and filename to use.

If this parameter is not specified, the default Kerberos system file is used.

-pkgname “<name>”

Optional

Package name can be set. Spaces are allowed, but punctuation is not.

-description "<text>"

Optional

Package description of the archive file. Notation appears when Studio is used to import the CAR.

-optfile <file_name>

Optional

Specifies an options file to pass options without using the command line. The options file is useful for hiding password information. For example:

pkg_export 
-server localhost 
-user test 
-password password 
-pkgfile sample.car

is the same as:

pkg_export 
-optfile sample.opt -optfilepassword password

 

where sample.opt contains:

-server localhost -user test 
-password password 
-pkgfile sample.car

Notes:

• When the command-line utility is executed, the opt file will be modified and the password strings in the file will be encrypted.
• An optfilePassword is required to access the optfile.
• TDV Server versions prior to 8.4 do not have this feature.

-optfilePassword

Required if optfile is used.

Password required to access the option file.

-newOptfilePassword

Optional

Use this option to change the optfile password and re-encrypt the password strings in the option file.

-rebindable <path> <description> ...

Optional

Marks a resource dependency for rebinding on import. When a rebindable resource is imported a reminder and the <Description> are displayed on the command line. The -rebind option must be specified on import for that action to take place on import. That message is also displayed in Studio to prompt designation of a new resource (path) as the resource dependency.

Rebinding must be done after the import unless this option specifies the new resource for rebinding during import.

-includeAccess

Optional

Includes the current user access controls (privilege specifications) on the resources in the export file. Default setting does NOT include access control, even when exported by an administrator.

An error can occur if this option is used and the exporting user is not a member of the admin group (which has the Read All Resources right).

-includeCaching

Optional

Includes the details of caching on views and procedures in the export file. This option must be specified to include cached data from materialized views, or configurations that include scheduling for cache refreshes.

-nosourceinfo

Optional

Data source connection details (such as user name, password, host name, and port) are included by default. Specify ‑nosourceinfo to exclude these. If passwords are included, they are encrypted.

-includeJars

Optional

Exports any included custom Java procedure data source's JAR.

-includeallusers

Optional

Exports all domains, groups, and users to the export file. Requires the Read All Users right.

-includeuser <domain_name> <user_name>

Optional

Includes the specified user in the export file. This option can be repeated to export multiple users. Repeat the option keyword -includeUser with arguments for the new domain and user as many times as necessary.

-includegroup <domain_name> <group_name>

Optional

Exports group information about the specified group in the export file.

-includedomain <domain_name>

Optional

Exports the specified domain metadata to the export file.

-includeRequiredUsers

Optional

Includes the information about the required users in the export file.

-includeDependencies

Optional

Gathers and includes all dependent resources for the resources you choose to export.

-includeStatistics

Optional

Includes any resource statistics known about the table or column boundaries.

-genopt

Optional

By giving this option and an opt file name, the parameters will be stored in the opt file with the password encrypted. While doing an export or import operation the password saved will not be shown as a clear text.

Note: An optfilePassword is required for the generated optfile. TDV versions prior to 8.4 do not have this optfile password feature.

-verbose

Optional

Reports problems encountered during the export. If neither verbose nor quiet is mentioned, verbose is the default behavior.

-quiet

Optional

Command information is not reported when this option is set.

-includeParentResources

Optional

By enabling this option, the parent resources are included while exporting the data source metadata.

Example

In this example, myParameterizedQuery is exported with dependencies that include the products table from the orders data source. The -rebindable option is specified to notify or remind the user during an import that the products resource will need to be rebound. 

pkg_export -pkgfile MyExport.car
	shared/procedures/myParameterizedQuery
	-server localhost 
	-user admin -password AdminPassword
	-includeDependencies
	-rebindable shared/sources/ds_orders/products This needs rebinding to the production data source.

Example 2

In this example, shared/sources is backed up to Sources_Backup.car. 

pkg_export -pkgfile Sources_Backup.car
	shared/sources
	-optfile C:/BackupScripts/Sources/weekly.opt -optfilepassword password
	-includeDependencies
	-nosourceinfo

The options file weekly.opt must contain any required arguments that were missing in the original command. For example, the following options with some value might be required:

-server localhost 
-user DBASecure1
-password Password
-domain EnterpriseLDAP

An options file can be dynamically generated to specify options and arguments, including the user name, password, and domain. This makes it possible to set up programmatic backups, while preventing the DBA login from being displayed in the application window or in the file prior to running the scheduled script.