Administration Guide > TDV Command-Line Utilities > The TDV Package Import Utility > Using the Package Import Utility
 
Using the Package Import Utility
The package import (pkg_import) utility imports directories and resources from a zipped CAR file. The pkg_import utility is available for execution from the bin directory of the TDV installation.
Use of pkg_import requires the following rights to restore TDV-defined resources:
• Access Tools
• Read and Modify All Config
• Read and Modify All Resources
• Read and Modify All Users
Import generally requires multiple administrative rights because it overwrites many types of resource objects, directories, user privileges, and other resource definitions.
Note: When you import using the pkg_import utility, a data source will be re-introspected if the "set" option is used to change its connection properties.
The package being imported, and the options specified, dictate what rights are actually required to perform the import. Most import procedures require Modify All Resources and Modify All Users.
The pkg_import utility imports the resources in the archive file into the server following the import rules (Rules for the Package Import Utility). If you use pkg_import ‑pkgfile on an archive created using backup_export, only the resource information is used.
Different combinations of ‑overwrite, ‑includeusers, and ‑mergeusers options have different outcomes for the user definitions, resource ownership, and usage privileges defined on the TDV target after import is complete.
This table shows the eight combinations possible with these three import options. In each row, check marks on the left show the import options used, and check marks on the right show what users are defined on the TDV target after the import with the given options is performed.
Package Import Options
Users Imported into Target
-overwrite
-includeusers
-mergeusers
From CAR File
TDV Target
User A
User B (CAR)
User B (TDV)
User C
X
 
 
 
 
X
X
X
X
 
X
X
 
 
X
X
X
X
X
 
X
X
 
X
X
X
 
X
 
X
 
X
X
 
X
 
X
X
X
 
X
X
 
 
X
X
 
X
X
Note: The combination of ‑overwrite and ‑includeusers (without ‑mergeusers) removes all existing user definitions and replaces them with any users present in the CAR file being imported. The user performing the import must have Read and Modify All Users rights to be able to use this combination.
To use the package import utility
1. Open a command prompt window.
2. Navigate to <TDV_install_dir>/bin.
3. Run the pkg_import command:
./pkg_import -pkgfile <D:/directory/Path/and/File_Name.car>...
-server <host_name> [-port <port_number>] [-encrypt]
-user <user_name> -password <password> [-domain <domain>]
[ -sso ] [ -sspi ] [ -spn <spn> ] [ -krb5Conf <krb5Conf> ]
[ -optfile <path_and_filename> ] ...
[-relocate <old_path> <new_path>] ...
[-rebind <old_path> <new_path>] ...
[-set <path> <data_type> <attribute> <value>] ...
[ -encryptionPassword <encryptionPassword> ] ...
[-printinfo] [-printroots] [-printusers][ -includeusers ] [ -mergeusers ]
[-printcontents] [-printreferences]
[-includeaccess] [-nocaching] [-nopolicy] [-createcachetables]
[-updateCacheTables][-excludejars] [-nosourceinfo]
[-overwrite] [-overrideLocks] [-messagesonly]
[ -genopt <filename> ]
[-verbose] [-quiet]
[-ignoreEncryption]
 
The table below describes the pkg_import parameters.
Package Import Parameters
Optional/
Required
Comments
-pkgfile <file_name>
Required
Specifies one or more import CAR files. The file names should be specified as absolute paths from mapped directories.
-server <host_name>
Required
TDV Server host to which the utility is to connect.
-port <port_number>
Optional
Specifies port for the target TDV instance. Default is 9400.
-encrypt
Optional
Encrypts communication between the command line and TDV using SSL sent over the dedicated HTTPS port.
-user <user_name>
Required
User name of profile used to import. User rights specified by the target TDV instance grant permission to import, and can restrict Write privileges to designated directories.
-password <password>
Required
Password for user profile used to export package.
-domain <domain>
Optional
Domain of the user performing the import. If it is omitted, the assumed value is composite.
-sso
Optional
Enables SSO authentication. Must be used with the -spn option.
There is no need to input username 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.
-optfile <file_name>
Optional
Specifies a file to pass options without using the command line. The options file is useful for hiding password information. For example:
pkg_import
-server localhost
-user test
-password password
-pkgfile sample.car
 
is the same as:
pkg_import
-optfile sample.opt
where sample.opt contains:
-server localhost -user test
-password password
-pkgfile sample.car
-relocate <old_path> <new_path>
Optional
This option can be used one or more times to change the location for the import.
An error occurs if you try to relocate something that is not in the package or is not a top-level item.
Relocating a resource modifies (rebind) references made by other resources being imported, but does not modify references to resources that are not part of the import.
-rebind <old_path> <new_path>
Optional
Sets a new resource path for a dependency resource. The option can be repeated.
Resources can be rebound as a group during the import process. This option can be used when migrating from a development or test environment to a production server deployment.
All imported resources are rebound. If rebinds caused by the relocate and rebind flags conflict, the rebind ones are performed first.
-set
<path>
<type>
<attribute> <value>
Optional
Enables you to change resource attributes during import. You can repeat this option to set different attributes or multiple class paths. String values can be enclosed in double-quotes to allow for spaces.
• The <path> is the TDV resource name.
• The <type> is DATA_SOURCE when the <attribute> is classpath, host, port, database, user, or password.
• The <attribute> can be one or more of the following, where the <value> options are noted in the descriptions:
— user <login> or <user_name> or error depending on source type
— password <password> or error depending on source type
— user2 <app_user_name> or error if not Oracle EBS
— password2 <app_password> or error if not Oracle EBS
— host <url_IP> or <dsn> or <server> or <appServer> or <url> or <root> or error depending on the source type. Use this host attribute when importing WSDL packages.
— port <url_port> or <port> or error depending on source type
— database <url_database_name> or <enterprise> or <app_server> or error depending on the source type
— path <root> or <url> or error depending on source type. Do not use this when importing WSDL packages.
— annotation
For Windows systems, use semicolon as delimiter: C:\DevZone\ATeam\Jars\my.jar;D:\Current\Ref\classes
For UNIX systems, use colons as delimiter: /lib/ext/classes:/lib/src/jars
-encryptionPassword
Optional
The password used to encrypt /decrypt sensitive data in your car file, for example, data source password, etc.
You do not need to specify this parameter if you are importing a car file from a TDV version prior to 8.0.
-printinfo
Optional
Causes the archive file to be examined and information about it to be displayed. The archive file is not imported when this option is specified.
-printroots
Optional
Prints the new paths to the imported resources. The archive file is not imported when this option is specified.
-printusers
Optional
Prints the user names of the owners of the imported resources and their associated user groups. The archive file is not imported when this option is specified.
-includeusers
Optional
Imports all users present in the exported package CAR file unless mergeusers is specified. By default domain, groups, and user information are not included in export or import packages.
-mergeusers
Optional
Imports all users present in the CAR file who are not already present in the server target. This option takes precedence over the includeusers option, and can have different behavior when combined with the overwrite option.
-printcontents
Optional
Disables actual import, and prints properties of the CAR file to the command window.
-printreferences
Optional
Prints a list of resources referred to by the imported resources. The archive file is not imported when this option is specified.
-includeaccess
Optional
This option must be used if you want to preserve ownership and privilege information. This option is ignored if you are not logged in as a member of the admin group.
-nocaching
Optional
Caching configuration is imported by default. This option must be used if you want to ignore cache configurations.
-nopolicy
Optional
CBS, RBS and Security policies are imported by default. Set this option if you want to ignore the configuration.
-createcachetables
Optional
If used, the cache status, tracking and target tables required by cached resources are created, if not already present in the database for your data source as it is described in the metadata of the CAR file you are importing.
The import process does not create the TDV resources for cache_status, cache_tracking, and target tables if they are not described in the CAR file metadata.
-updateCacheTables
Optional
Yes or no. Use this optional value to indicate whether you want to have the cache tables dropped and recreated with any potential changes that are included in the CAR file.
-excludejars
Optional
Does not import custom Java procedure data source’s JAR files within the CAR file.
-nosourceinfo
Optional
(An overwrite safeguard.) Suppresses import of the following pre-existing connection attributes when an otherwise identical resource is already present in the target: driver, connectionURL, port, database name, login, password, and pass-through login.
Supports re-import without need for explicit set options and without altering original data source attributes.
-overwrite
Optional
Ensures that TDV exactly matches the directories present in the CAR file. Clears targeted folder directories before copying the CAR file contents to those directories.
The pkg_import utility clears only those directories that have representative resources in the CAR file, whether or not the -overwrite option is specified.
-overrideLocks
Optional
If the import user is not the locked resource owner, and if this option to override is specified, then it is overwritten, else an exception is reported.
-messagesonly
Optional
Displays the messages generated in a package import without actually performing the import.
-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.
-verbose
Optional
Reports problems encountered during the import. If neither verbose nor quiet is mentioned, verbose is the default behavior.
-quiet
Optional
Command information is not reported if this option is mentioned.
-ignoreEncryption
Optional
If this option is used, then all backup data will be imported regardless of whether a valid encryption key was provided. This means that the import will not fail. This option can be used to allow partially importing any backed up data. However, the import process will only import data that is not encrypted or can be decrypted using the provided encryption key. All encrypted portions of the backup data that cannot be decrypted will be imported as empty values and the import will otherwise succeed.
This affects all encrypted values in the backup data, which includes, but is not limited to data source and LDAP domain connection passwords.
Example 1
This example changes the password property of a data source:
pkg_import mycar.car -set /shared/myDataSource DATA_SOURCE password myNewPassword
pkg_import.sh -pkgfile C:/Store/EnterpriseArchive/mycar.car 
-server localhost -user ProdAdmin -password AdminPassW0rd 
-set /shared/myDataSource DATA_SOURCE password MyNewPassword
Example 2
In this example, only shared/procedures/myParameterizedQuery is imported (with its associated dependencies) from the specified CAR file. The relocate option moves the query to a new directory:
pkg_import -pkgfile Z:/Archive/QA_Image99999.car
shared/procedures/myParameterizedQuery -server localhost
-user admin -password AdminPassword -includeDependencies
-relocate shared/procedures/myParameterizedQuery shared/RestrictedUse_Procedures/myParameterizedQuery
Example 3
./pkg_import.sh -pkgfile MyCustJavaDB.car
-optfile C:\X.opt
-set /shared/datasources/DBCustom_Java DATA_SOURCE
classpath “C:\Program Files\JavaDev;D:\My Documents\JavaJim”
Example 4
This example imports a WSDL file, where the host attribute is used:
pkg_import.bat -pkgfile ..\TEST.car -server localhost -port 9420 -user admin -password sam -domain composite
-set /shared/test/DataSources/testWebService DATA_SOURCE
host http://localhost:9430/services/TEST/testWebService?wsdl
-set /shared/test/DataSources/testWebService DATA_SOURCE user admin
-set /shared/test/DataSources/testWebService DATA_SOURCE password admin